2. EL 8
  3. dpdk-devel
  4. rte_gpu_is_valid(3)

Scroll to navigation

rte_gpudev.h(3) DPDK rte_gpudev.h(3)

NAME

rte_gpudev.h

SYNOPSIS

#include <stddef.h>
#include <stdint.h>
#include <stdbool.h>
#include <rte_mbuf.h>
#include <rte_bitops.h>
#include <rte_compat.h>

Data Structures


struct rte_gpu_info
struct rte_gpu_comm_flag
struct rte_gpu_comm_pkt
struct rte_gpu_comm_list

Macros


#define RTE_GPU_DEFAULT_MAX 32
#define RTE_GPU_ID_NONE -1
#define RTE_GPU_ID_ANY INT16_MIN
#define RTE_GPU_CALLBACK_ANY_DATA ((void *)-1)
#define RTE_GPU_VOLATILE(x) (*(volatile typeof(x) *)&(x))
#define RTE_GPU_COMM_LIST_PKTS_MAX 1024
#define RTE_GPU_FOREACH(dev_id) RTE_GPU_FOREACH_CHILD(dev_id, RTE_GPU_ID_ANY)
#define RTE_GPU_FOREACH_PARENT(dev_id) RTE_GPU_FOREACH_CHILD(dev_id, RTE_GPU_ID_NONE)
#define RTE_GPU_FOREACH_CHILD(dev_id, parent)

Typedefs


typedef void() rte_gpu_callback_t(int16_t dev_id, enum rte_gpu_event event, void *user_data)

Enumerations


enum rte_gpu_event { RTE_GPU_EVENT_NEW, RTE_GPU_EVENT_DEL }
enum rte_gpu_comm_flag_type { RTE_GPU_COMM_FLAG_CPU = 0 }
enum rte_gpu_comm_list_status { RTE_GPU_COMM_LIST_FREE = 0, RTE_GPU_COMM_LIST_READY, RTE_GPU_COMM_LIST_DONE, RTE_GPU_COMM_LIST_ERROR }

Functions


__rte_experimental int rte_gpu_init (size_t dev_max)
__rte_experimental uint16_t rte_gpu_count_avail (void)
__rte_experimental bool rte_gpu_is_valid (int16_t dev_id)
__rte_experimental int16_t rte_gpu_add_child (const char *name, int16_t parent, uint64_t child_context)
__rte_experimental int16_t rte_gpu_find_next (int16_t dev_id, int16_t parent)
__rte_experimental int rte_gpu_close (int16_t dev_id)
__rte_experimental int rte_gpu_callback_register (int16_t dev_id, enum rte_gpu_event event, rte_gpu_callback_t *function, void *user_data)
__rte_experimental int rte_gpu_callback_unregister (int16_t dev_id, enum rte_gpu_event event, rte_gpu_callback_t *function, void *user_data)
__rte_experimental int rte_gpu_info_get (int16_t dev_id, struct rte_gpu_info *info)
__rte_experimental void * rte_gpu_mem_alloc (int16_t dev_id, size_t size, unsigned int align) __rte_alloc_size(2)
__rte_experimental int rte_gpu_mem_free (int16_t dev_id, void *ptr)
__rte_experimental int rte_gpu_mem_register (int16_t dev_id, size_t size, void *ptr)
__rte_experimental int rte_gpu_mem_unregister (int16_t dev_id, void *ptr)
__rte_experimental void * rte_gpu_mem_cpu_map (int16_t dev_id, size_t size, void *ptr)
__rte_experimental int rte_gpu_mem_cpu_unmap (int16_t dev_id, void *ptr)
__rte_experimental int rte_gpu_wmb (int16_t dev_id)
__rte_experimental int rte_gpu_comm_create_flag (uint16_t dev_id, struct rte_gpu_comm_flag *devflag, enum rte_gpu_comm_flag_type mtype)
__rte_experimental int rte_gpu_comm_destroy_flag (struct rte_gpu_comm_flag *devflag)
__rte_experimental int rte_gpu_comm_set_flag (struct rte_gpu_comm_flag *devflag, uint32_t val)
__rte_experimental int rte_gpu_comm_get_flag_value (struct rte_gpu_comm_flag *devflag, uint32_t *val)
__rte_experimental struct rte_gpu_comm_list * rte_gpu_comm_create_list (uint16_t dev_id, uint32_t num_comm_items)
__rte_experimental int rte_gpu_comm_destroy_list (struct rte_gpu_comm_list *comm_list, uint32_t num_comm_items)
__rte_experimental int rte_gpu_comm_populate_list_pkts (struct rte_gpu_comm_list *comm_list_item, struct rte_mbuf **mbufs, uint32_t num_mbufs)
__rte_experimental int rte_gpu_comm_set_status (struct rte_gpu_comm_list *comm_list_item, enum rte_gpu_comm_list_status status)
__rte_experimental int rte_gpu_comm_get_status (struct rte_gpu_comm_list *comm_list_item, enum rte_gpu_comm_list_status *status)
__rte_experimental int rte_gpu_comm_cleanup_list (struct rte_gpu_comm_list *comm_list_item)

Detailed Description

Generic library to interact with GPU computing device.

The API is not thread-safe. Device management must be done by a single thread.

Warning:

EXPERIMENTAL: this API may change without prior notice.

Definition in file rte_gpudev.h.

Macro Definition Documentation

#define RTE_GPU_DEFAULT_MAX 32

Maximum number of devices if rte_gpu_init() is not called.

Definition at line 32 of file rte_gpudev.h.

#define RTE_GPU_ID_NONE -1

Empty device ID.

Definition at line 35 of file rte_gpudev.h.

#define RTE_GPU_ID_ANY INT16_MIN

Catch-all device ID.

Definition at line 37 of file rte_gpudev.h.

#define RTE_GPU_CALLBACK_ANY_DATA ((void *)-1)

Catch-all callback data.

Definition at line 40 of file rte_gpudev.h.

#define RTE_GPU_VOLATILE(x) (*(volatile typeof(x) *)&(x))

Access variable as volatile.

Definition at line 43 of file rte_gpudev.h.

#define RTE_GPU_COMM_LIST_PKTS_MAX 1024

Max number of packets per communication list.

Definition at line 46 of file rte_gpudev.h.

#define RTE_GPU_FOREACH(dev_id) RTE_GPU_FOREACH_CHILD(dev_id, RTE_GPU_ID_ANY)

Warning:

EXPERIMENTAL: this API may change without prior notice.

Macro to iterate over all valid GPU devices.

Parameters:

dev_id The ID of the next possible valid device, usually 0 to iterate all.

Definition at line 238 of file rte_gpudev.h.

#define RTE_GPU_FOREACH_PARENT(dev_id) RTE_GPU_FOREACH_CHILD(dev_id, RTE_GPU_ID_NONE)

Warning:

EXPERIMENTAL: this API may change without prior notice.

Macro to iterate over all valid computing devices having no parent.

Parameters:

dev_id The ID of the next possible valid device, usually 0 to iterate all.

Definition at line 250 of file rte_gpudev.h.

#define RTE_GPU_FOREACH_CHILD(dev_id, parent)

Value:

for (dev_id = rte_gpu_find_next(0, parent);          dev_id >= 0;          dev_id = rte_gpu_find_next(dev_id + 1, parent))

Warning:

EXPERIMENTAL: this API may change without prior notice.

Macro to iterate over all valid children of a computing device parent.

Parameters:

dev_id The ID of the next possible valid device, usually 0 to iterate all.
parent The device ID of the parent.

Definition at line 264 of file rte_gpudev.h.

Typedef Documentation

typedef void() rte_gpu_callback_t(int16_t dev_id, enum rte_gpu_event event, void *user_data)

Prototype of event callback function.

Definition at line 77 of file rte_gpudev.h.

Enumeration Type Documentation

enum rte_gpu_event

Flags passed in notification callback.

Enumerator

Device is just initialized.
Device is going to be released.

Definition at line 69 of file rte_gpudev.h.

enum rte_gpu_comm_flag_type

Memory where communication flag is allocated.

Enumerator

Allocate flag on CPU memory visible from device.

Definition at line 81 of file rte_gpudev.h.

enum rte_gpu_comm_list_status

Possible status for the list of packets shared among CPU and device.

Enumerator

Packet list can be filled with new mbufs, no one is using it.
Packet list has been filled with new mbufs and it's ready to be used .
Packet list has been processed, it's ready to be freed.
Some error occurred during packet list processing.

Definition at line 105 of file rte_gpudev.h.

Function Documentation

__rte_experimental int rte_gpu_init (size_t dev_max)

Warning:

EXPERIMENTAL: this API may change without prior notice.

Initialize the device array before probing devices. If not called, the maximum of probed devices is RTE_GPU_DEFAULT_MAX.

Parameters:

dev_max Maximum number of devices.

Returns:

0 on success, -rte_errno otherwise:
  • ENOMEM if out of memory
  • EINVAL if 0 size
  • EBUSY if already initialized

__rte_experimental uint16_t rte_gpu_count_avail (void)

Warning:

EXPERIMENTAL: this API may change without prior notice.

Return the number of GPU detected and associated to DPDK.

Returns:

The number of available computing devices.

__rte_experimental bool rte_gpu_is_valid (int16_t dev_id)

Warning:

EXPERIMENTAL: this API may change without prior notice.

Check if the device is valid and initialized in DPDK.

Parameters:

dev_id The input device ID.

Returns:

  • True if dev_id is a valid and initialized computing device.
  • False otherwise.

__rte_experimental int16_t rte_gpu_add_child (const char * name, int16_t parent, uint64_t child_context)

Warning:

EXPERIMENTAL: this API may change without prior notice.

Create a virtual device representing a context in the parent device.

Parameters:

name Unique string to identify the device.
parent Device ID of the parent.
child_context Opaque context handler.

Returns:

Device ID of the new created child, -rte_errno otherwise:
  • EINVAL if empty name
  • ENAMETOOLONG if long name
  • EEXIST if existing device name
  • ENODEV if invalid parent
  • EPERM if secondary process
  • ENOENT if too many devices
  • ENOMEM if out of space

__rte_experimental int16_t rte_gpu_find_next (int16_t dev_id, int16_t parent)

Warning:

EXPERIMENTAL: this API may change without prior notice.

Get the ID of the next valid GPU initialized in DPDK.

Parameters:

dev_id The initial device ID to start the research.
parent The device ID of the parent. RTE_GPU_ID_NONE means no parent. RTE_GPU_ID_ANY means no or any parent.

Returns:

Next device ID corresponding to a valid and initialized computing device, RTE_GPU_ID_NONE if there is none.

__rte_experimental int rte_gpu_close (int16_t dev_id)

Warning:

EXPERIMENTAL: this API may change without prior notice.

Close device or child context. All resources are released.

Parameters:

dev_id Device ID to close.

Returns:

0 on success, -rte_errno otherwise:
  • ENODEV if invalid dev_id
  • EPERM if driver error

__rte_experimental int rte_gpu_callback_register (int16_t dev_id, enum rte_gpu_event event, rte_gpu_callback_t * function, void * user_data)

Warning:

EXPERIMENTAL: this API may change without prior notice.

Register a function as event callback. A function may be registered multiple times for different events.

Parameters:

dev_id Device ID to get notified about. RTE_GPU_ID_ANY means all devices.
event Device event to be registered for.
function Callback function to be called on event.
user_data Optional parameter passed in the callback.

Returns:

0 on success, -rte_errno otherwise:
  • ENODEV if invalid dev_id
  • EINVAL if NULL function
  • ENOMEM if out of memory

__rte_experimental int rte_gpu_callback_unregister (int16_t dev_id, enum rte_gpu_event event, rte_gpu_callback_t * function, void * user_data)

Warning:

EXPERIMENTAL: this API may change without prior notice.

Unregister for an event.

Parameters:

dev_id Device ID to be silenced. RTE_GPU_ID_ANY means all devices.
event Registered event.
function Registered function.
user_data Optional parameter as registered. RTE_GPU_CALLBACK_ANY_DATA is a catch-all.

Returns:

0 on success, -rte_errno otherwise:
  • ENODEV if invalid dev_id
  • EINVAL if NULL function

__rte_experimental int rte_gpu_info_get (int16_t dev_id, struct rte_gpu_info * info)

Warning:

EXPERIMENTAL: this API may change without prior notice.

Return device specific info.

Parameters:

dev_id Device ID to get info.
info Memory structure to fill with the info.

Returns:

0 on success, -rte_errno otherwise:
  • ENODEV if invalid dev_id
  • EINVAL if NULL info
  • EPERM if driver error

__rte_experimental void* rte_gpu_mem_alloc (int16_t dev_id, size_t size, unsigned int align)

Warning:

EXPERIMENTAL: this API may change without prior notice.

Allocate a chunk of memory in the device.

Parameters:

dev_id Device ID requiring allocated memory.
size Number of bytes to allocate. Requesting 0 will do nothing.
align If 0, the return is a pointer that is suitably aligned for any kind of variable (in the same manner as malloc()). Otherwise, the return is a pointer that is a multiple of align. In this case, it must obviously be a power of two.

Returns:

A pointer to the allocated memory, otherwise NULL and rte_errno is set:
  • ENODEV if invalid dev_id
  • EINVAL if align is not a power of two
  • ENOTSUP if operation not supported by the driver
  • E2BIG if size is higher than limit
  • ENOMEM if out of space
  • EPERM if driver error

__rte_experimental int rte_gpu_mem_free (int16_t dev_id, void * ptr)

Warning:

EXPERIMENTAL: this API may change without prior notice.

Deallocate a chunk of memory allocated with rte_gpu_mem_alloc().

Parameters:

dev_id Reference device ID.
ptr Pointer to the memory area to be deallocated. NULL is a no-op accepted value.

Returns:

0 on success, -rte_errno otherwise:
  • ENODEV if invalid dev_id
  • ENOTSUP if operation not supported by the driver
  • EPERM if driver error

__rte_experimental int rte_gpu_mem_register (int16_t dev_id, size_t size, void * ptr)

Warning:

EXPERIMENTAL: this API may change without prior notice.

Register a chunk of memory on the CPU usable by the device.

Parameters:

dev_id Device ID requiring allocated memory.
size Number of bytes to allocate. Requesting 0 will do nothing.
ptr Pointer to the memory area to be registered. NULL is a no-op accepted value.

Returns:

A pointer to the allocated memory, otherwise NULL and rte_errno is set:
  • ENODEV if invalid dev_id
  • EINVAL if reserved flags
  • ENOTSUP if operation not supported by the driver
  • E2BIG if size is higher than limit
  • ENOMEM if out of space
  • EPERM if driver error

__rte_experimental int rte_gpu_mem_unregister (int16_t dev_id, void * ptr)

Warning:

EXPERIMENTAL: this API may change without prior notice.

Deregister a chunk of memory previously registered with rte_gpu_mem_register()

Parameters:

dev_id Reference device ID.
ptr Pointer to the memory area to be unregistered. NULL is a no-op accepted value.

Returns:

0 on success, -rte_errno otherwise:
  • ENODEV if invalid dev_id
  • ENOTSUP if operation not supported by the driver
  • EPERM if driver error

__rte_experimental void* rte_gpu_mem_cpu_map (int16_t dev_id, size_t size, void * ptr)

Warning:

EXPERIMENTAL: this API may change without prior notice.

Map a chunk of GPU memory to make it accessible from the CPU using the memory pointer returned by the function. GPU memory has to be allocated via rte_gpu_mem_alloc().

Parameters:

dev_id Device ID requiring mapped memory.
size Number of bytes to map. Requesting 0 will do nothing.
ptr Pointer to the GPU memory area to be mapped. NULL is a no-op accepted value.

Returns:

A pointer to the mapped GPU memory usable by the CPU, otherwise NULL and rte_errno is set:
  • ENODEV if invalid dev_id
  • ENOTSUP if operation not supported by the driver
  • E2BIG if size is higher than limit
  • ENOMEM if out of space
  • EPERM if driver error

__rte_experimental int rte_gpu_mem_cpu_unmap (int16_t dev_id, void * ptr)

Warning:

EXPERIMENTAL: this API may change without prior notice.

Unmap a chunk of GPU memory previously mapped with rte_gpu_mem_cpu_map()

Parameters:

dev_id Reference device ID.
ptr Pointer to the GPU memory area to be unmapped. NULL is a no-op accepted value.

Returns:

0 on success, -rte_errno otherwise:
  • ENODEV if invalid dev_id
  • ENOTSUP if operation not supported by the driver
  • EPERM if driver error

__rte_experimental int rte_gpu_wmb (int16_t dev_id)

Warning:

EXPERIMENTAL: this API may change without prior notice.

Enforce a GPU write memory barrier.

Parameters:

dev_id Reference device ID.

Returns:

0 on success, -rte_errno otherwise:
  • ENODEV if invalid dev_id
  • ENOTSUP if operation not supported by the driver
  • EPERM if driver error

__rte_experimental int rte_gpu_comm_create_flag (uint16_t dev_id, struct rte_gpu_comm_flag * devflag, enum rte_gpu_comm_flag_type mtype)

Warning:

EXPERIMENTAL: this API may change without prior notice.

Create a communication flag that can be shared between CPU threads and device workload to exchange some status info (e.g. work is done, processing can start, etc..).

Parameters:

dev_id Reference device ID.
devflag Pointer to the memory area of the devflag structure.
mtype Type of memory to allocate the communication flag.

Returns:

0 on success, -rte_errno otherwise:
  • ENODEV if invalid dev_id
  • EINVAL if invalid inputs
  • ENOTSUP if operation not supported by the driver
  • ENOMEM if out of space
  • EPERM if driver error

__rte_experimental int rte_gpu_comm_destroy_flag (struct rte_gpu_comm_flag * devflag)

Warning:

EXPERIMENTAL: this API may change without prior notice.

Deallocate a communication flag.

Parameters:

devflag Pointer to the memory area of the devflag structure.

Returns:

0 on success, -rte_errno otherwise:
  • ENODEV if invalid dev_id
  • EINVAL if NULL devflag
  • ENOTSUP if operation not supported by the driver
  • EPERM if driver error

__rte_experimental int rte_gpu_comm_set_flag (struct rte_gpu_comm_flag * devflag, uint32_t val)

Warning:

EXPERIMENTAL: this API may change without prior notice.

Set the value of a communication flag as the input value. Flag memory area is treated as volatile. The flag must have been allocated with RTE_GPU_COMM_FLAG_CPU.

Parameters:

devflag Pointer to the memory area of the devflag structure.
val Value to set in the flag.

Returns:

0 on success, -rte_errno otherwise:
•
EINVAL if invalid input params

__rte_experimental int rte_gpu_comm_get_flag_value (struct rte_gpu_comm_flag * devflag, uint32_t * val)

Warning:

EXPERIMENTAL: this API may change without prior notice.

Get the value of the communication flag. Flag memory area is treated as volatile. The flag must have been allocated with RTE_GPU_COMM_FLAG_CPU.

Parameters:

devflag Pointer to the memory area of the devflag structure.
val Flag output value.

Returns:

0 on success, -rte_errno otherwise:
•
EINVAL if invalid input params

__rte_experimental struct rte_gpu_comm_list* rte_gpu_comm_create_list (uint16_t dev_id, uint32_t num_comm_items)

Warning:

EXPERIMENTAL: this API may change without prior notice.

Create a communication list that can be used to share packets between CPU and device. Each element of the list contains:

  • a packet list of RTE_GPU_COMM_LIST_PKTS_MAX elements
  • number of packets in the list
  • a status flag to communicate if the packet list is FREE, READY to be processed, DONE with processing.

The list is allocated in CPU-visible memory. At creation time, every list is in FREE state.

Parameters:

dev_id Reference device ID.
num_comm_items Number of items in the communication list.

Returns:

A pointer to the allocated list, otherwise NULL and rte_errno is set:
•
EINVAL if invalid input params

__rte_experimental int rte_gpu_comm_destroy_list (struct rte_gpu_comm_list * comm_list, uint32_t num_comm_items)

Warning:

EXPERIMENTAL: this API may change without prior notice.

Destroy a communication list.

Parameters:

comm_list Communication list to be destroyed.
num_comm_items Number of items in the communication list.

Returns:

0 on success, -rte_errno otherwise:
•
EINVAL if invalid input params

__rte_experimental int rte_gpu_comm_populate_list_pkts (struct rte_gpu_comm_list * comm_list_item, struct rte_mbuf ** mbufs, uint32_t num_mbufs)

Warning:

EXPERIMENTAL: this API may change without prior notice.

Populate the packets list of the communication item with info from a list of mbufs. Status flag of that packet list is set to READY.

Parameters:

comm_list_item Communication list item to fill.
mbufs List of mbufs.
num_mbufs Number of mbufs.

Returns:

0 on success, -rte_errno otherwise:
  • EINVAL if invalid input params
  • ENOTSUP if mbufs are chained (multiple segments)

__rte_experimental int rte_gpu_comm_set_status (struct rte_gpu_comm_list * comm_list_item, enum rte_gpu_comm_list_status status)

Warning:

EXPERIMENTAL: this API may change without prior notice.

Set status flag value of a communication list item.

Parameters:

comm_list_item Communication list item to query.
status Status value to set.

Returns:

0 on success, -rte_errno otherwise:
•
EINVAL if invalid input params

__rte_experimental int rte_gpu_comm_get_status (struct rte_gpu_comm_list * comm_list_item, enum rte_gpu_comm_list_status * status)

Warning:

EXPERIMENTAL: this API may change without prior notice.

Get status flag value of a communication list item.

Parameters:

comm_list_item Communication list item to query. Input parameter.
status Communication list item status flag value. Output parameter.

Returns:

0 on success, -rte_errno otherwise:
•
EINVAL if invalid input params

__rte_experimental int rte_gpu_comm_cleanup_list (struct rte_gpu_comm_list * comm_list_item)

Warning:

EXPERIMENTAL: this API may change without prior notice.

Reset a communication list item to the original state. The status flag set to FREE and mbufs are returned to the pool.

Parameters:

comm_list_item Communication list item to reset.

Returns:

0 on success, -rte_errno otherwise:
•
EINVAL if invalid input params

Author

Generated automatically by Doxygen for DPDK from the source code.

Thu May 23 2024 Version 23.11.0