1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright (c) 2021 NVIDIA Corporation & Affiliates
13 #include <rte_bitops.h>
14 #include <rte_compat.h>
18 * Generic library to interact with GPU computing device.
20 * The API is not thread-safe.
21 * Device management must be done by a single thread.
24 * @b EXPERIMENTAL: this API may change without prior notice.
31 /** Maximum number of devices if rte_gpu_init() is not called. */
32 #define RTE_GPU_DEFAULT_MAX 32
34 /** Empty device ID. */
35 #define RTE_GPU_ID_NONE -1
36 /** Catch-all device ID. */
37 #define RTE_GPU_ID_ANY INT16_MIN
39 /** Catch-all callback data. */
40 #define RTE_GPU_CALLBACK_ANY_DATA ((void *)-1)
42 /** Access variable as volatile. */
43 #define RTE_GPU_VOLATILE(x) (*(volatile typeof(x) *)&(x))
45 /** Max number of packets per communication list. */
46 #define RTE_GPU_COMM_LIST_PKTS_MAX 1024
48 /** Store device info. */
50 /** Unique identifier name. */
52 /** Opaque handler of the device context. */
56 /** ID of the parent device, RTE_GPU_ID_NONE if no parent */
58 /** Total processors available on device. */
59 uint32_t processor_count;
60 /** Total memory available on device. */
62 /* Local NUMA memory ID. -1 if unknown. */
66 /** Flags passed in notification callback. */
68 /** Device is just initialized. */
70 /** Device is going to be released. */
74 /** Prototype of event callback function. */
75 typedef void (rte_gpu_callback_t)(int16_t dev_id,
76 enum rte_gpu_event event, void *user_data);
78 /** Memory where communication flag is allocated. */
79 enum rte_gpu_comm_flag_type {
80 /** Allocate flag on CPU memory visible from device. */
81 RTE_GPU_COMM_FLAG_CPU = 0,
84 /** Communication flag to coordinate CPU with the device. */
85 struct rte_gpu_comm_flag {
86 /** Device that will use the device flag. */
88 /** Pointer to flag memory area. */
90 /** Type of memory used to allocate the flag. */
91 enum rte_gpu_comm_flag_type mtype;
94 /** List of packets shared among CPU and device. */
95 struct rte_gpu_comm_pkt {
96 /** Address of the packet in memory (e.g. mbuf->buf_addr). */
98 /** Size in byte of the packet. */
102 /** Possible status for the list of packets shared among CPU and device. */
103 enum rte_gpu_comm_list_status {
104 /** Packet list can be filled with new mbufs, no one is using it. */
105 RTE_GPU_COMM_LIST_FREE = 0,
106 /** Packet list has been filled with new mbufs and it's ready to be used .*/
107 RTE_GPU_COMM_LIST_READY,
108 /** Packet list has been processed, it's ready to be freed. */
109 RTE_GPU_COMM_LIST_DONE,
110 /** Some error occurred during packet list processing. */
111 RTE_GPU_COMM_LIST_ERROR,
115 * Communication list holding a number of lists of packets
116 * each having a status flag.
118 struct rte_gpu_comm_list {
119 /** Device that will use the communication list. */
121 /** List of mbufs populated by the CPU with a set of mbufs. */
122 struct rte_mbuf **mbufs;
123 /** List of packets populated by the CPU with a set of mbufs info. */
124 struct rte_gpu_comm_pkt *pkt_list;
125 /** Number of packets in the list. */
127 /** Status of the list. CPU pointer. */
128 enum rte_gpu_comm_list_status *status_h;
129 /** Status of the list. GPU pointer. */
130 enum rte_gpu_comm_list_status *status_d;
135 * @b EXPERIMENTAL: this API may change without prior notice.
137 * Initialize the device array before probing devices.
138 * If not called, the maximum of probed devices is RTE_GPU_DEFAULT_MAX.
141 * Maximum number of devices.
144 * 0 on success, -rte_errno otherwise:
145 * - ENOMEM if out of memory
147 * - EBUSY if already initialized
150 int rte_gpu_init(size_t dev_max);
154 * @b EXPERIMENTAL: this API may change without prior notice.
156 * Return the number of GPU detected and associated to DPDK.
159 * The number of available computing devices.
162 uint16_t rte_gpu_count_avail(void);
166 * @b EXPERIMENTAL: this API may change without prior notice.
168 * Check if the device is valid and initialized in DPDK.
171 * The input device ID.
174 * - True if dev_id is a valid and initialized computing device.
178 bool rte_gpu_is_valid(int16_t dev_id);
182 * @b EXPERIMENTAL: this API may change without prior notice.
184 * Create a virtual device representing a context in the parent device.
187 * Unique string to identify the device.
189 * Device ID of the parent.
190 * @param child_context
191 * Opaque context handler.
194 * Device ID of the new created child, -rte_errno otherwise:
195 * - EINVAL if empty name
196 * - ENAMETOOLONG if long name
197 * - EEXIST if existing device name
198 * - ENODEV if invalid parent
199 * - EPERM if secondary process
200 * - ENOENT if too many devices
201 * - ENOMEM if out of space
204 int16_t rte_gpu_add_child(const char *name,
205 int16_t parent, uint64_t child_context);
209 * @b EXPERIMENTAL: this API may change without prior notice.
211 * Get the ID of the next valid GPU initialized in DPDK.
214 * The initial device ID to start the research.
216 * The device ID of the parent.
217 * RTE_GPU_ID_NONE means no parent.
218 * RTE_GPU_ID_ANY means no or any parent.
221 * Next device ID corresponding to a valid and initialized computing device,
222 * RTE_GPU_ID_NONE if there is none.
225 int16_t rte_gpu_find_next(int16_t dev_id, int16_t parent);
229 * @b EXPERIMENTAL: this API may change without prior notice.
231 * Macro to iterate over all valid GPU devices.
234 * The ID of the next possible valid device, usually 0 to iterate all.
236 #define RTE_GPU_FOREACH(dev_id) \
237 RTE_GPU_FOREACH_CHILD(dev_id, RTE_GPU_ID_ANY)
241 * @b EXPERIMENTAL: this API may change without prior notice.
243 * Macro to iterate over all valid computing devices having no parent.
246 * The ID of the next possible valid device, usually 0 to iterate all.
248 #define RTE_GPU_FOREACH_PARENT(dev_id) \
249 RTE_GPU_FOREACH_CHILD(dev_id, RTE_GPU_ID_NONE)
253 * @b EXPERIMENTAL: this API may change without prior notice.
255 * Macro to iterate over all valid children of a computing device parent.
258 * The ID of the next possible valid device, usually 0 to iterate all.
260 * The device ID of the parent.
262 #define RTE_GPU_FOREACH_CHILD(dev_id, parent) \
263 for (dev_id = rte_gpu_find_next(0, parent); \
265 dev_id = rte_gpu_find_next(dev_id + 1, parent))
269 * @b EXPERIMENTAL: this API may change without prior notice.
271 * Close device or child context.
272 * All resources are released.
275 * Device ID to close.
278 * 0 on success, -rte_errno otherwise:
279 * - ENODEV if invalid dev_id
280 * - EPERM if driver error
283 int rte_gpu_close(int16_t dev_id);
287 * @b EXPERIMENTAL: this API may change without prior notice.
289 * Register a function as event callback.
290 * A function may be registered multiple times for different events.
293 * Device ID to get notified about.
294 * RTE_GPU_ID_ANY means all devices.
296 * Device event to be registered for.
298 * Callback function to be called on event.
300 * Optional parameter passed in the callback.
303 * 0 on success, -rte_errno otherwise:
304 * - ENODEV if invalid dev_id
305 * - EINVAL if NULL function
306 * - ENOMEM if out of memory
309 int rte_gpu_callback_register(int16_t dev_id, enum rte_gpu_event event,
310 rte_gpu_callback_t *function, void *user_data);
314 * @b EXPERIMENTAL: this API may change without prior notice.
316 * Unregister for an event.
319 * Device ID to be silenced.
320 * RTE_GPU_ID_ANY means all devices.
324 * Registered function.
326 * Optional parameter as registered.
327 * RTE_GPU_CALLBACK_ANY_DATA is a catch-all.
330 * 0 on success, -rte_errno otherwise:
331 * - ENODEV if invalid dev_id
332 * - EINVAL if NULL function
335 int rte_gpu_callback_unregister(int16_t dev_id, enum rte_gpu_event event,
336 rte_gpu_callback_t *function, void *user_data);
340 * @b EXPERIMENTAL: this API may change without prior notice.
342 * Return device specific info.
345 * Device ID to get info.
347 * Memory structure to fill with the info.
350 * 0 on success, -rte_errno otherwise:
351 * - ENODEV if invalid dev_id
352 * - EINVAL if NULL info
353 * - EPERM if driver error
356 int rte_gpu_info_get(int16_t dev_id, struct rte_gpu_info *info);
360 * @b EXPERIMENTAL: this API may change without prior notice.
362 * Allocate a chunk of memory in the device.
365 * Device ID requiring allocated memory.
367 * Number of bytes to allocate.
368 * Requesting 0 will do nothing.
370 * If 0, the return is a pointer that is suitably aligned
371 * for any kind of variable (in the same manner as malloc()).
372 * Otherwise, the return is a pointer that is a multiple of *align*.
373 * In this case, it must obviously be a power of two.
376 * A pointer to the allocated memory, otherwise NULL and rte_errno is set:
377 * - ENODEV if invalid dev_id
378 * - EINVAL if align is not a power of two
379 * - ENOTSUP if operation not supported by the driver
380 * - E2BIG if size is higher than limit
381 * - ENOMEM if out of space
382 * - EPERM if driver error
385 void *rte_gpu_mem_alloc(int16_t dev_id, size_t size, unsigned int align)
390 * @b EXPERIMENTAL: this API may change without prior notice.
392 * Deallocate a chunk of memory allocated with rte_gpu_mem_alloc().
395 * Reference device ID.
397 * Pointer to the memory area to be deallocated.
398 * NULL is a no-op accepted value.
401 * 0 on success, -rte_errno otherwise:
402 * - ENODEV if invalid dev_id
403 * - ENOTSUP if operation not supported by the driver
404 * - EPERM if driver error
407 int rte_gpu_mem_free(int16_t dev_id, void *ptr);
411 * @b EXPERIMENTAL: this API may change without prior notice.
413 * Register a chunk of memory on the CPU usable by the device.
416 * Device ID requiring allocated memory.
418 * Number of bytes to allocate.
419 * Requesting 0 will do nothing.
421 * Pointer to the memory area to be registered.
422 * NULL is a no-op accepted value.
425 * A pointer to the allocated memory, otherwise NULL and rte_errno is set:
426 * - ENODEV if invalid dev_id
427 * - EINVAL if reserved flags
428 * - ENOTSUP if operation not supported by the driver
429 * - E2BIG if size is higher than limit
430 * - ENOMEM if out of space
431 * - EPERM if driver error
434 int rte_gpu_mem_register(int16_t dev_id, size_t size, void *ptr);
438 * @b EXPERIMENTAL: this API may change without prior notice.
440 * Deregister a chunk of memory previously registered with rte_gpu_mem_register()
443 * Reference device ID.
445 * Pointer to the memory area to be unregistered.
446 * NULL is a no-op accepted value.
449 * 0 on success, -rte_errno otherwise:
450 * - ENODEV if invalid dev_id
451 * - ENOTSUP if operation not supported by the driver
452 * - EPERM if driver error
455 int rte_gpu_mem_unregister(int16_t dev_id, void *ptr);
459 * @b EXPERIMENTAL: this API may change without prior notice.
461 * Map a chunk of GPU memory to make it accessible from the CPU
462 * using the memory pointer returned by the function.
463 * GPU memory has to be allocated via rte_gpu_mem_alloc().
466 * Device ID requiring mapped memory.
468 * Number of bytes to map.
469 * Requesting 0 will do nothing.
471 * Pointer to the GPU memory area to be mapped.
472 * NULL is a no-op accepted value.
475 * A pointer to the mapped GPU memory usable by the CPU, otherwise NULL and rte_errno is set:
476 * - ENODEV if invalid dev_id
477 * - ENOTSUP if operation not supported by the driver
478 * - E2BIG if size is higher than limit
479 * - ENOMEM if out of space
480 * - EPERM if driver error
483 void *rte_gpu_mem_cpu_map(int16_t dev_id, size_t size, void *ptr);
487 * @b EXPERIMENTAL: this API may change without prior notice.
489 * Unmap a chunk of GPU memory previously mapped with rte_gpu_mem_cpu_map()
492 * Reference device ID.
494 * Pointer to the GPU memory area to be unmapped.
495 * NULL is a no-op accepted value.
498 * 0 on success, -rte_errno otherwise:
499 * - ENODEV if invalid dev_id
500 * - ENOTSUP if operation not supported by the driver
501 * - EPERM if driver error
504 int rte_gpu_mem_cpu_unmap(int16_t dev_id, void *ptr);
508 * @b EXPERIMENTAL: this API may change without prior notice.
510 * Enforce a GPU write memory barrier.
513 * Reference device ID.
516 * 0 on success, -rte_errno otherwise:
517 * - ENODEV if invalid dev_id
518 * - ENOTSUP if operation not supported by the driver
519 * - EPERM if driver error
522 int rte_gpu_wmb(int16_t dev_id);
526 * @b EXPERIMENTAL: this API may change without prior notice.
528 * Create a communication flag that can be shared
529 * between CPU threads and device workload to exchange some status info
530 * (e.g. work is done, processing can start, etc..).
533 * Reference device ID.
535 * Pointer to the memory area of the devflag structure.
537 * Type of memory to allocate the communication flag.
540 * 0 on success, -rte_errno otherwise:
541 * - ENODEV if invalid dev_id
542 * - EINVAL if invalid inputs
543 * - ENOTSUP if operation not supported by the driver
544 * - ENOMEM if out of space
545 * - EPERM if driver error
548 int rte_gpu_comm_create_flag(uint16_t dev_id,
549 struct rte_gpu_comm_flag *devflag,
550 enum rte_gpu_comm_flag_type mtype);
554 * @b EXPERIMENTAL: this API may change without prior notice.
556 * Deallocate a communication flag.
559 * Pointer to the memory area of the devflag structure.
562 * 0 on success, -rte_errno otherwise:
563 * - ENODEV if invalid dev_id
564 * - EINVAL if NULL devflag
565 * - ENOTSUP if operation not supported by the driver
566 * - EPERM if driver error
569 int rte_gpu_comm_destroy_flag(struct rte_gpu_comm_flag *devflag);
573 * @b EXPERIMENTAL: this API may change without prior notice.
575 * Set the value of a communication flag as the input value.
576 * Flag memory area is treated as volatile.
577 * The flag must have been allocated with RTE_GPU_COMM_FLAG_CPU.
580 * Pointer to the memory area of the devflag structure.
582 * Value to set in the flag.
585 * 0 on success, -rte_errno otherwise:
586 * - EINVAL if invalid input params
589 int rte_gpu_comm_set_flag(struct rte_gpu_comm_flag *devflag,
594 * @b EXPERIMENTAL: this API may change without prior notice.
596 * Get the value of the communication flag.
597 * Flag memory area is treated as volatile.
598 * The flag must have been allocated with RTE_GPU_COMM_FLAG_CPU.
601 * Pointer to the memory area of the devflag structure.
606 * 0 on success, -rte_errno otherwise:
607 * - EINVAL if invalid input params
610 int rte_gpu_comm_get_flag_value(struct rte_gpu_comm_flag *devflag,
615 * @b EXPERIMENTAL: this API may change without prior notice.
617 * Create a communication list that can be used to share packets
618 * between CPU and device.
619 * Each element of the list contains:
620 * - a packet list of RTE_GPU_COMM_LIST_PKTS_MAX elements
621 * - number of packets in the list
622 * - a status flag to communicate if the packet list is FREE,
623 * READY to be processed, DONE with processing.
625 * The list is allocated in CPU-visible memory.
626 * At creation time, every list is in FREE state.
629 * Reference device ID.
630 * @param num_comm_items
631 * Number of items in the communication list.
634 * A pointer to the allocated list, otherwise NULL and rte_errno is set:
635 * - EINVAL if invalid input params
638 struct rte_gpu_comm_list *rte_gpu_comm_create_list(uint16_t dev_id,
639 uint32_t num_comm_items);
643 * @b EXPERIMENTAL: this API may change without prior notice.
645 * Destroy a communication list.
648 * Communication list to be destroyed.
649 * @param num_comm_items
650 * Number of items in the communication list.
653 * 0 on success, -rte_errno otherwise:
654 * - EINVAL if invalid input params
657 int rte_gpu_comm_destroy_list(struct rte_gpu_comm_list *comm_list,
658 uint32_t num_comm_items);
662 * @b EXPERIMENTAL: this API may change without prior notice.
664 * Populate the packets list of the communication item
665 * with info from a list of mbufs.
666 * Status flag of that packet list is set to READY.
668 * @param comm_list_item
669 * Communication list item to fill.
676 * 0 on success, -rte_errno otherwise:
677 * - EINVAL if invalid input params
678 * - ENOTSUP if mbufs are chained (multiple segments)
681 int rte_gpu_comm_populate_list_pkts(struct rte_gpu_comm_list *comm_list_item,
682 struct rte_mbuf **mbufs, uint32_t num_mbufs);
686 * @b EXPERIMENTAL: this API may change without prior notice.
688 * Set status flag value of a communication list item.
690 * @param comm_list_item
691 * Communication list item to query.
693 * Status value to set.
696 * 0 on success, -rte_errno otherwise:
697 * - EINVAL if invalid input params
700 int rte_gpu_comm_set_status(struct rte_gpu_comm_list *comm_list_item,
701 enum rte_gpu_comm_list_status status);
705 * @b EXPERIMENTAL: this API may change without prior notice.
707 * Get status flag value of a communication list item.
709 * @param comm_list_item
710 * Communication list item to query.
713 * Communication list item status flag value.
717 * 0 on success, -rte_errno otherwise:
718 * - EINVAL if invalid input params
721 int rte_gpu_comm_get_status(struct rte_gpu_comm_list *comm_list_item,
722 enum rte_gpu_comm_list_status *status);
726 * @b EXPERIMENTAL: this API may change without prior notice.
728 * Reset a communication list item to the original state.
729 * The status flag set to FREE and mbufs are returned to the pool.
731 * @param comm_list_item
732 * Communication list item to reset.
735 * 0 on success, -rte_errno otherwise:
736 * - EINVAL if invalid input params
739 int rte_gpu_comm_cleanup_list(struct rte_gpu_comm_list *comm_list_item);
745 #endif /* RTE_GPUDEV_H */