DOKK / manpages / debian 13 / dpdk-doc / RTE_GPU_ID_ANY.3.en
rte_gpudev.h(3) Library Functions Manual rte_gpudev.h(3)

rte_gpudev.h

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


struct rte_gpu_info
struct rte_gpu_comm_flag
struct rte_gpu_comm_pkt
struct rte_gpu_comm_list


#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)


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


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 }


__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)

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.

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

Definition at line 32 of file rte_gpudev.h.

Empty device ID.

Definition at line 35 of file rte_gpudev.h.

Catch-all device ID.

Definition at line 37 of file rte_gpudev.h.

Catch-all callback data.

Definition at line 40 of file rte_gpudev.h.

Access variable as volatile.

Definition at line 43 of file rte_gpudev.h.

Max number of packets per communication list.

Definition at line 46 of file rte_gpudev.h.

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.

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.

Value:.PP



    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 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.

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.

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

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.

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.

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

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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)

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

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

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

Generated automatically by Doxygen for DPDK from the source code.

Version 24.11.3 DPDK