DPDK  24.03.0
Data Structures | Macros | Typedefs | Enumerations | Functions
rte_gpudev.h File Reference
#include <stddef.h>
#include <stdint.h>
#include <stdbool.h>
#include <rte_mbuf.h>
#include <rte_bitops.h>
#include <rte_compat.h>

Go to the source code of this file.

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

◆ RTE_GPU_DEFAULT_MAX

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

◆ RTE_GPU_ID_NONE

#define RTE_GPU_ID_NONE   -1

Empty device ID.

Definition at line 35 of file rte_gpudev.h.

◆ RTE_GPU_ID_ANY

#define RTE_GPU_ID_ANY   INT16_MIN

Catch-all device ID.

Definition at line 37 of file rte_gpudev.h.

◆ RTE_GPU_CALLBACK_ANY_DATA

#define RTE_GPU_CALLBACK_ANY_DATA   ((void *)-1)

Catch-all callback data.

Definition at line 40 of file rte_gpudev.h.

◆ RTE_GPU_VOLATILE

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

Access variable as volatile.

Definition at line 43 of file rte_gpudev.h.

◆ RTE_GPU_COMM_LIST_PKTS_MAX

#define RTE_GPU_COMM_LIST_PKTS_MAX   1024

Max number of packets per communication list.

Definition at line 46 of file rte_gpudev.h.

◆ RTE_GPU_FOREACH

#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_idThe ID of the next possible valid device, usually 0 to iterate all.

Definition at line 238 of file rte_gpudev.h.

◆ RTE_GPU_FOREACH_PARENT

#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_idThe ID of the next possible valid device, usually 0 to iterate all.

Definition at line 250 of file rte_gpudev.h.

◆ RTE_GPU_FOREACH_CHILD

#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))
__rte_experimental int16_t rte_gpu_find_next(int16_t dev_id, int16_t parent)
Warning
EXPERIMENTAL: this API may change without prior notice.

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

Parameters
dev_idThe ID of the next possible valid device, usually 0 to iterate all.
parentThe device ID of the parent.

Definition at line 264 of file rte_gpudev.h.

Typedef Documentation

◆ rte_gpu_callback_t

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

◆ rte_gpu_event

Flags passed in notification callback.

Enumerator
RTE_GPU_EVENT_NEW 

Device is just initialized.

RTE_GPU_EVENT_DEL 

Device is going to be released.

Definition at line 69 of file rte_gpudev.h.

◆ rte_gpu_comm_flag_type

Memory where communication flag is allocated.

Enumerator
RTE_GPU_COMM_FLAG_CPU 

Allocate flag on CPU memory visible from device.

Definition at line 81 of file rte_gpudev.h.

◆ rte_gpu_comm_list_status

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

Enumerator
RTE_GPU_COMM_LIST_FREE 

Packet list can be filled with new mbufs, no one is using it.

RTE_GPU_COMM_LIST_READY 

Packet list has been filled with new mbufs and it's ready to be used .

RTE_GPU_COMM_LIST_DONE 

Packet list has been processed, it's ready to be freed.

RTE_GPU_COMM_LIST_ERROR 

Some error occurred during packet list processing.

Definition at line 105 of file rte_gpudev.h.

Function Documentation

◆ rte_gpu_init()

__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_maxMaximum number of devices.
Returns
0 on success, -rte_errno otherwise:
  • ENOMEM if out of memory
  • EINVAL if 0 size
  • EBUSY if already initialized

◆ rte_gpu_count_avail()

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

__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_idThe input device ID.
Returns
  • True if dev_id is a valid and initialized computing device.
  • False otherwise.

◆ rte_gpu_add_child()

__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
nameUnique string to identify the device.
parentDevice ID of the parent.
child_contextOpaque 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_gpu_find_next()

__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_idThe initial device ID to start the research.
parentThe 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_gpu_close()

__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_idDevice ID to close.
Returns
0 on success, -rte_errno otherwise:
  • ENODEV if invalid dev_id
  • EPERM if driver error

◆ rte_gpu_callback_register()

__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_idDevice ID to get notified about. RTE_GPU_ID_ANY means all devices.
eventDevice event to be registered for.
functionCallback function to be called on event.
user_dataOptional 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_gpu_callback_unregister()

__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_idDevice ID to be silenced. RTE_GPU_ID_ANY means all devices.
eventRegistered event.
functionRegistered function.
user_dataOptional 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_gpu_info_get()

__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_idDevice ID to get info.
infoMemory 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_gpu_mem_alloc()

__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_idDevice ID requiring allocated memory.
sizeNumber of bytes to allocate. Requesting 0 will do nothing.
alignIf 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_gpu_mem_free()

__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_idReference device ID.
ptrPointer 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_gpu_mem_register()

__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_idDevice ID requiring allocated memory.
sizeNumber of bytes to allocate. Requesting 0 will do nothing.
ptrPointer 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_gpu_mem_unregister()

__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_idReference device ID.
ptrPointer 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_gpu_mem_cpu_map()

__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_idDevice ID requiring mapped memory.
sizeNumber of bytes to map. Requesting 0 will do nothing.
ptrPointer 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_gpu_mem_cpu_unmap()

__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_idReference device ID.
ptrPointer 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_gpu_wmb()

__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_idReference 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_gpu_comm_create_flag()

__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_idReference device ID.
devflagPointer to the memory area of the devflag structure.
mtypeType 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_gpu_comm_destroy_flag()

__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
devflagPointer 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_gpu_comm_set_flag()

__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
devflagPointer to the memory area of the devflag structure.
valValue to set in the flag.
Returns
0 on success, -rte_errno otherwise:
  • EINVAL if invalid input params

◆ rte_gpu_comm_get_flag_value()

__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
devflagPointer to the memory area of the devflag structure.
valFlag output value.
Returns
0 on success, -rte_errno otherwise:
  • EINVAL if invalid input params

◆ rte_gpu_comm_create_list()

__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_idReference device ID.
num_comm_itemsNumber 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_gpu_comm_destroy_list()

__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_listCommunication list to be destroyed.
num_comm_itemsNumber of items in the communication list.
Returns
0 on success, -rte_errno otherwise:
  • EINVAL if invalid input params

◆ rte_gpu_comm_populate_list_pkts()

__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_itemCommunication list item to fill.
mbufsList of mbufs.
num_mbufsNumber of mbufs.
Returns
0 on success, -rte_errno otherwise:
  • EINVAL if invalid input params
  • ENOTSUP if mbufs are chained (multiple segments)

◆ rte_gpu_comm_set_status()

__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_itemCommunication list item to query.
statusStatus value to set.
Returns
0 on success, -rte_errno otherwise:
  • EINVAL if invalid input params

◆ rte_gpu_comm_get_status()

__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_itemCommunication list item to query. Input parameter.
statusCommunication list item status flag value. Output parameter.
Returns
0 on success, -rte_errno otherwise:
  • EINVAL if invalid input params

◆ rte_gpu_comm_cleanup_list()

__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_itemCommunication list item to reset.
Returns
0 on success, -rte_errno otherwise:
  • EINVAL if invalid input params