9802bff2a5322d7dc62c39e5701eae22fe8f4970
[dpdk.git] / lib / gpudev / rte_gpudev.h
1 /* SPDX-License-Identifier: BSD-3-Clause
2  * Copyright (c) 2021 NVIDIA Corporation & Affiliates
3  */
4
5 #ifndef RTE_GPUDEV_H
6 #define RTE_GPUDEV_H
7
8 #include <stddef.h>
9 #include <stdint.h>
10 #include <stdbool.h>
11
12 #include <rte_mbuf.h>
13 #include <rte_bitops.h>
14 #include <rte_compat.h>
15
16 /**
17  * @file
18  * Generic library to interact with GPU computing device.
19  *
20  * The API is not thread-safe.
21  * Device management must be done by a single thread.
22  *
23  * @warning
24  * @b EXPERIMENTAL: this API may change without prior notice.
25  */
26
27 #ifdef __cplusplus
28 extern "C" {
29 #endif
30
31 /** Maximum number of devices if rte_gpu_init() is not called. */
32 #define RTE_GPU_DEFAULT_MAX 32
33
34 /** Empty device ID. */
35 #define RTE_GPU_ID_NONE -1
36 /** Catch-all device ID. */
37 #define RTE_GPU_ID_ANY INT16_MIN
38
39 /** Catch-all callback data. */
40 #define RTE_GPU_CALLBACK_ANY_DATA ((void *)-1)
41
42 /** Access variable as volatile. */
43 #define RTE_GPU_VOLATILE(x) (*(volatile typeof(x) *)&(x))
44
45 /** Max number of packets per communication list. */
46 #define RTE_GPU_COMM_LIST_PKTS_MAX 1024
47
48 /** Store device info. */
49 struct rte_gpu_info {
50         /** Unique identifier name. */
51         const char *name;
52         /** Opaque handler of the device context. */
53         uint64_t context;
54         /** Device ID. */
55         int16_t dev_id;
56         /** ID of the parent device, RTE_GPU_ID_NONE if no parent */
57         int16_t parent;
58         /** Total processors available on device. */
59         uint32_t processor_count;
60         /** Total memory available on device. */
61         size_t total_memory;
62         /* Local NUMA memory ID. -1 if unknown. */
63         int16_t numa_node;
64 };
65
66 /** Flags passed in notification callback. */
67 enum rte_gpu_event {
68         /** Device is just initialized. */
69         RTE_GPU_EVENT_NEW,
70         /** Device is going to be released. */
71         RTE_GPU_EVENT_DEL,
72 };
73
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);
77
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,
82 };
83
84 /** Communication flag to coordinate CPU with the device. */
85 struct rte_gpu_comm_flag {
86         /** Device that will use the device flag. */
87         uint16_t dev_id;
88         /** Pointer to flag memory area. */
89         uint32_t *ptr;
90         /** Type of memory used to allocate the flag. */
91         enum rte_gpu_comm_flag_type mtype;
92 };
93
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). */
97         uintptr_t addr;
98         /** Size in byte of the packet. */
99         size_t size;
100 };
101
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,
112 };
113
114 /**
115  * Communication list holding a number of lists of packets
116  * each having a status flag.
117  */
118 struct rte_gpu_comm_list {
119         /** Device that will use the communication list. */
120         uint16_t dev_id;
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. */
126         uint32_t num_pkts;
127         /** Status of the list. */
128         enum rte_gpu_comm_list_status status;
129 };
130
131 /**
132  * @warning
133  * @b EXPERIMENTAL: this API may change without prior notice.
134  *
135  * Initialize the device array before probing devices.
136  * If not called, the maximum of probed devices is RTE_GPU_DEFAULT_MAX.
137  *
138  * @param dev_max
139  *   Maximum number of devices.
140  *
141  * @return
142  *   0 on success, -rte_errno otherwise:
143  *   - ENOMEM if out of memory
144  *   - EINVAL if 0 size
145  *   - EBUSY if already initialized
146  */
147 __rte_experimental
148 int rte_gpu_init(size_t dev_max);
149
150 /**
151  * @warning
152  * @b EXPERIMENTAL: this API may change without prior notice.
153  *
154  * Return the number of GPU detected and associated to DPDK.
155  *
156  * @return
157  *   The number of available computing devices.
158  */
159 __rte_experimental
160 uint16_t rte_gpu_count_avail(void);
161
162 /**
163  * @warning
164  * @b EXPERIMENTAL: this API may change without prior notice.
165  *
166  * Check if the device is valid and initialized in DPDK.
167  *
168  * @param dev_id
169  *   The input device ID.
170  *
171  * @return
172  *   - True if dev_id is a valid and initialized computing device.
173  *   - False otherwise.
174  */
175 __rte_experimental
176 bool rte_gpu_is_valid(int16_t dev_id);
177
178 /**
179  * @warning
180  * @b EXPERIMENTAL: this API may change without prior notice.
181  *
182  * Create a virtual device representing a context in the parent device.
183  *
184  * @param name
185  *   Unique string to identify the device.
186  * @param parent
187  *   Device ID of the parent.
188  * @param child_context
189  *   Opaque context handler.
190  *
191  * @return
192  *   Device ID of the new created child, -rte_errno otherwise:
193  *   - EINVAL if empty name
194  *   - ENAMETOOLONG if long name
195  *   - EEXIST if existing device name
196  *   - ENODEV if invalid parent
197  *   - EPERM if secondary process
198  *   - ENOENT if too many devices
199  *   - ENOMEM if out of space
200  */
201 __rte_experimental
202 int16_t rte_gpu_add_child(const char *name,
203                 int16_t parent, uint64_t child_context);
204
205 /**
206  * @warning
207  * @b EXPERIMENTAL: this API may change without prior notice.
208  *
209  * Get the ID of the next valid GPU initialized in DPDK.
210  *
211  * @param dev_id
212  *   The initial device ID to start the research.
213  * @param parent
214  *   The device ID of the parent.
215  *   RTE_GPU_ID_NONE means no parent.
216  *   RTE_GPU_ID_ANY means no or any parent.
217  *
218  * @return
219  *   Next device ID corresponding to a valid and initialized computing device,
220  *   RTE_GPU_ID_NONE if there is none.
221  */
222 __rte_experimental
223 int16_t rte_gpu_find_next(int16_t dev_id, int16_t parent);
224
225 /**
226  * @warning
227  * @b EXPERIMENTAL: this API may change without prior notice.
228  *
229  * Macro to iterate over all valid GPU devices.
230  *
231  * @param dev_id
232  *   The ID of the next possible valid device, usually 0 to iterate all.
233  */
234 #define RTE_GPU_FOREACH(dev_id) \
235         RTE_GPU_FOREACH_CHILD(dev_id, RTE_GPU_ID_ANY)
236
237 /**
238  * @warning
239  * @b EXPERIMENTAL: this API may change without prior notice.
240  *
241  * Macro to iterate over all valid computing devices having no parent.
242  *
243  * @param dev_id
244  *   The ID of the next possible valid device, usually 0 to iterate all.
245  */
246 #define RTE_GPU_FOREACH_PARENT(dev_id) \
247         RTE_GPU_FOREACH_CHILD(dev_id, RTE_GPU_ID_NONE)
248
249 /**
250  * @warning
251  * @b EXPERIMENTAL: this API may change without prior notice.
252  *
253  * Macro to iterate over all valid children of a computing device parent.
254  *
255  * @param dev_id
256  *   The ID of the next possible valid device, usually 0 to iterate all.
257  * @param parent
258  *   The device ID of the parent.
259  */
260 #define RTE_GPU_FOREACH_CHILD(dev_id, parent) \
261         for (dev_id = rte_gpu_find_next(0, parent); \
262              dev_id >= 0; \
263              dev_id = rte_gpu_find_next(dev_id + 1, parent))
264
265 /**
266  * @warning
267  * @b EXPERIMENTAL: this API may change without prior notice.
268  *
269  * Close device or child context.
270  * All resources are released.
271  *
272  * @param dev_id
273  *   Device ID to close.
274  *
275  * @return
276  *   0 on success, -rte_errno otherwise:
277  *   - ENODEV if invalid dev_id
278  *   - EPERM if driver error
279  */
280 __rte_experimental
281 int rte_gpu_close(int16_t dev_id);
282
283 /**
284  * @warning
285  * @b EXPERIMENTAL: this API may change without prior notice.
286  *
287  * Register a function as event callback.
288  * A function may be registered multiple times for different events.
289  *
290  * @param dev_id
291  *   Device ID to get notified about.
292  *   RTE_GPU_ID_ANY means all devices.
293  * @param event
294  *   Device event to be registered for.
295  * @param function
296  *   Callback function to be called on event.
297  * @param user_data
298  *   Optional parameter passed in the callback.
299  *
300  * @return
301  *   0 on success, -rte_errno otherwise:
302  *   - ENODEV if invalid dev_id
303  *   - EINVAL if NULL function
304  *   - ENOMEM if out of memory
305  */
306 __rte_experimental
307 int rte_gpu_callback_register(int16_t dev_id, enum rte_gpu_event event,
308                 rte_gpu_callback_t *function, void *user_data);
309
310 /**
311  * @warning
312  * @b EXPERIMENTAL: this API may change without prior notice.
313  *
314  * Unregister for an event.
315  *
316  * @param dev_id
317  *   Device ID to be silenced.
318  *   RTE_GPU_ID_ANY means all devices.
319  * @param event
320  *   Registered event.
321  * @param function
322  *   Registered function.
323  * @param user_data
324  *   Optional parameter as registered.
325  *   RTE_GPU_CALLBACK_ANY_DATA is a catch-all.
326  *
327  * @return
328  *   0 on success, -rte_errno otherwise:
329  *   - ENODEV if invalid dev_id
330  *   - EINVAL if NULL function
331  */
332 __rte_experimental
333 int rte_gpu_callback_unregister(int16_t dev_id, enum rte_gpu_event event,
334                 rte_gpu_callback_t *function, void *user_data);
335
336 /**
337  * @warning
338  * @b EXPERIMENTAL: this API may change without prior notice.
339  *
340  * Return device specific info.
341  *
342  * @param dev_id
343  *   Device ID to get info.
344  * @param info
345  *   Memory structure to fill with the info.
346  *
347  * @return
348  *   0 on success, -rte_errno otherwise:
349  *   - ENODEV if invalid dev_id
350  *   - EINVAL if NULL info
351  *   - EPERM if driver error
352  */
353 __rte_experimental
354 int rte_gpu_info_get(int16_t dev_id, struct rte_gpu_info *info);
355
356 /**
357  * @warning
358  * @b EXPERIMENTAL: this API may change without prior notice.
359  *
360  * Allocate a chunk of memory in the device.
361  *
362  * @param dev_id
363  *   Device ID requiring allocated memory.
364  * @param size
365  *   Number of bytes to allocate.
366  *   Requesting 0 will do nothing.
367  * @param align
368  *   If 0, the return is a pointer that is suitably aligned
369  *   for any kind of variable (in the same manner as malloc()).
370  *   Otherwise, the return is a pointer that is a multiple of *align*.
371  *   In this case, it must obviously be a power of two.
372  *
373  * @return
374  *   A pointer to the allocated memory, otherwise NULL and rte_errno is set:
375  *   - ENODEV if invalid dev_id
376  *   - EINVAL if align is not a power of two
377  *   - ENOTSUP if operation not supported by the driver
378  *   - E2BIG if size is higher than limit
379  *   - ENOMEM if out of space
380  *   - EPERM if driver error
381  */
382 __rte_experimental
383 void *rte_gpu_mem_alloc(int16_t dev_id, size_t size, unsigned int align)
384 __rte_alloc_size(2);
385
386 /**
387  * @warning
388  * @b EXPERIMENTAL: this API may change without prior notice.
389  *
390  * Deallocate a chunk of memory allocated with rte_gpu_mem_alloc().
391  *
392  * @param dev_id
393  *   Reference device ID.
394  * @param ptr
395  *   Pointer to the memory area to be deallocated.
396  *   NULL is a no-op accepted value.
397  *
398  * @return
399  *   0 on success, -rte_errno otherwise:
400  *   - ENODEV if invalid dev_id
401  *   - ENOTSUP if operation not supported by the driver
402  *   - EPERM if driver error
403  */
404 __rte_experimental
405 int rte_gpu_mem_free(int16_t dev_id, void *ptr);
406
407 /**
408  * @warning
409  * @b EXPERIMENTAL: this API may change without prior notice.
410  *
411  * Register a chunk of memory on the CPU usable by the device.
412  *
413  * @param dev_id
414  *   Device ID requiring allocated memory.
415  * @param size
416  *   Number of bytes to allocate.
417  *   Requesting 0 will do nothing.
418  * @param ptr
419  *   Pointer to the memory area to be registered.
420  *   NULL is a no-op accepted value.
421
422  * @return
423  *   A pointer to the allocated memory, otherwise NULL and rte_errno is set:
424  *   - ENODEV if invalid dev_id
425  *   - EINVAL if reserved flags
426  *   - ENOTSUP if operation not supported by the driver
427  *   - E2BIG if size is higher than limit
428  *   - ENOMEM if out of space
429  *   - EPERM if driver error
430  */
431 __rte_experimental
432 int rte_gpu_mem_register(int16_t dev_id, size_t size, void *ptr);
433
434 /**
435  * @warning
436  * @b EXPERIMENTAL: this API may change without prior notice.
437  *
438  * Deregister a chunk of memory previously registered with rte_gpu_mem_register()
439  *
440  * @param dev_id
441  *   Reference device ID.
442  * @param ptr
443  *   Pointer to the memory area to be unregistered.
444  *   NULL is a no-op accepted value.
445  *
446  * @return
447  *   0 on success, -rte_errno otherwise:
448  *   - ENODEV if invalid dev_id
449  *   - ENOTSUP if operation not supported by the driver
450  *   - EPERM if driver error
451  */
452 __rte_experimental
453 int rte_gpu_mem_unregister(int16_t dev_id, void *ptr);
454
455 /**
456  * @warning
457  * @b EXPERIMENTAL: this API may change without prior notice.
458  *
459  * Map a chunk of GPU memory to make it accessible from the CPU
460  * using the memory pointer returned by the function.
461  * GPU memory has to be allocated via rte_gpu_mem_alloc().
462  *
463  * @param dev_id
464  *   Device ID requiring mapped memory.
465  * @param size
466  *   Number of bytes to map.
467  *   Requesting 0 will do nothing.
468  * @param ptr
469  *   Pointer to the GPU memory area to be mapped.
470  *   NULL is a no-op accepted value.
471
472  * @return
473  *   A pointer to the mapped GPU memory usable by the CPU, otherwise NULL and rte_errno is set:
474  *   - ENODEV if invalid dev_id
475  *   - ENOTSUP if operation not supported by the driver
476  *   - E2BIG if size is higher than limit
477  *   - ENOMEM if out of space
478  *   - EPERM if driver error
479  */
480 __rte_experimental
481 void *rte_gpu_mem_cpu_map(int16_t dev_id, size_t size, void *ptr);
482
483 /**
484  * @warning
485  * @b EXPERIMENTAL: this API may change without prior notice.
486  *
487  * Unmap a chunk of GPU memory previously mapped with rte_gpu_mem_cpu_map()
488  *
489  * @param dev_id
490  *   Reference device ID.
491  * @param ptr
492  *   Pointer to the GPU memory area to be unmapped.
493  *   NULL is a no-op accepted value.
494  *
495  * @return
496  *   0 on success, -rte_errno otherwise:
497  *   - ENODEV if invalid dev_id
498  *   - ENOTSUP if operation not supported by the driver
499  *   - EPERM if driver error
500  */
501 __rte_experimental
502 int rte_gpu_mem_cpu_unmap(int16_t dev_id, void *ptr);
503
504 /**
505  * @warning
506  * @b EXPERIMENTAL: this API may change without prior notice.
507  *
508  * Enforce a GPU write memory barrier.
509  *
510  * @param dev_id
511  *   Reference device ID.
512  *
513  * @return
514  *   0 on success, -rte_errno otherwise:
515  *   - ENODEV if invalid dev_id
516  *   - ENOTSUP if operation not supported by the driver
517  *   - EPERM if driver error
518  */
519 __rte_experimental
520 int rte_gpu_wmb(int16_t dev_id);
521
522 /**
523  * @warning
524  * @b EXPERIMENTAL: this API may change without prior notice.
525  *
526  * Create a communication flag that can be shared
527  * between CPU threads and device workload to exchange some status info
528  * (e.g. work is done, processing can start, etc..).
529  *
530  * @param dev_id
531  *   Reference device ID.
532  * @param devflag
533  *   Pointer to the memory area of the devflag structure.
534  * @param mtype
535  *   Type of memory to allocate the communication flag.
536  *
537  * @return
538  *   0 on success, -rte_errno otherwise:
539  *   - ENODEV if invalid dev_id
540  *   - EINVAL if invalid inputs
541  *   - ENOTSUP if operation not supported by the driver
542  *   - ENOMEM if out of space
543  *   - EPERM if driver error
544  */
545 __rte_experimental
546 int rte_gpu_comm_create_flag(uint16_t dev_id,
547                 struct rte_gpu_comm_flag *devflag,
548                 enum rte_gpu_comm_flag_type mtype);
549
550 /**
551  * @warning
552  * @b EXPERIMENTAL: this API may change without prior notice.
553  *
554  * Deallocate a communication flag.
555  *
556  * @param devflag
557  *   Pointer to the memory area of the devflag structure.
558  *
559  * @return
560  *   0 on success, -rte_errno otherwise:
561  *   - ENODEV if invalid dev_id
562  *   - EINVAL if NULL devflag
563  *   - ENOTSUP if operation not supported by the driver
564  *   - EPERM if driver error
565  */
566 __rte_experimental
567 int rte_gpu_comm_destroy_flag(struct rte_gpu_comm_flag *devflag);
568
569 /**
570  * @warning
571  * @b EXPERIMENTAL: this API may change without prior notice.
572  *
573  * Set the value of a communication flag as the input value.
574  * Flag memory area is treated as volatile.
575  * The flag must have been allocated with RTE_GPU_COMM_FLAG_CPU.
576  *
577  * @param devflag
578  *   Pointer to the memory area of the devflag structure.
579  * @param val
580  *   Value to set in the flag.
581  *
582  * @return
583  *   0 on success, -rte_errno otherwise:
584  *   - EINVAL if invalid input params
585  */
586 __rte_experimental
587 int rte_gpu_comm_set_flag(struct rte_gpu_comm_flag *devflag,
588                 uint32_t val);
589
590 /**
591  * @warning
592  * @b EXPERIMENTAL: this API may change without prior notice.
593  *
594  * Get the value of the communication flag.
595  * Flag memory area is treated as volatile.
596  * The flag must have been allocated with RTE_GPU_COMM_FLAG_CPU.
597  *
598  * @param devflag
599  *   Pointer to the memory area of the devflag structure.
600  * @param val
601  *   Flag output value.
602  *
603  * @return
604  *   0 on success, -rte_errno otherwise:
605  *   - EINVAL if invalid input params
606  */
607 __rte_experimental
608 int rte_gpu_comm_get_flag_value(struct rte_gpu_comm_flag *devflag,
609                 uint32_t *val);
610
611 /**
612  * @warning
613  * @b EXPERIMENTAL: this API may change without prior notice.
614  *
615  * Create a communication list that can be used to share packets
616  * between CPU and device.
617  * Each element of the list contains:
618  *  - a packet list of RTE_GPU_COMM_LIST_PKTS_MAX elements
619  *  - number of packets in the list
620  *  - a status flag to communicate if the packet list is FREE,
621  *    READY to be processed, DONE with processing.
622  *
623  * The list is allocated in CPU-visible memory.
624  * At creation time, every list is in FREE state.
625  *
626  * @param dev_id
627  *   Reference device ID.
628  * @param num_comm_items
629  *   Number of items in the communication list.
630  *
631  * @return
632  *   A pointer to the allocated list, otherwise NULL and rte_errno is set:
633  *   - EINVAL if invalid input params
634  */
635 __rte_experimental
636 struct rte_gpu_comm_list *rte_gpu_comm_create_list(uint16_t dev_id,
637                 uint32_t num_comm_items);
638
639 /**
640  * @warning
641  * @b EXPERIMENTAL: this API may change without prior notice.
642  *
643  * Destroy a communication list.
644  *
645  * @param comm_list
646  *   Communication list to be destroyed.
647  * @param num_comm_items
648  *   Number of items in the communication list.
649  *
650  * @return
651  *   0 on success, -rte_errno otherwise:
652  *   - EINVAL if invalid input params
653  */
654 __rte_experimental
655 int rte_gpu_comm_destroy_list(struct rte_gpu_comm_list *comm_list,
656                 uint32_t num_comm_items);
657
658 /**
659  * @warning
660  * @b EXPERIMENTAL: this API may change without prior notice.
661  *
662  * Populate the packets list of the communication item
663  * with info from a list of mbufs.
664  * Status flag of that packet list is set to READY.
665  *
666  * @param comm_list_item
667  *   Communication list item to fill.
668  * @param mbufs
669  *   List of mbufs.
670  * @param num_mbufs
671  *   Number of mbufs.
672  *
673  * @return
674  *   0 on success, -rte_errno otherwise:
675  *   - EINVAL if invalid input params
676  *   - ENOTSUP if mbufs are chained (multiple segments)
677  */
678 __rte_experimental
679 int rte_gpu_comm_populate_list_pkts(struct rte_gpu_comm_list *comm_list_item,
680                 struct rte_mbuf **mbufs, uint32_t num_mbufs);
681
682 /**
683  * @warning
684  * @b EXPERIMENTAL: this API may change without prior notice.
685  *
686  * Reset a communication list item to the original state.
687  * The status flag set to FREE and mbufs are returned to the pool.
688  *
689  * @param comm_list_item
690  *   Communication list item to reset.
691  *
692  * @return
693  *   0 on success, -rte_errno otherwise:
694  *   - EINVAL if invalid input params
695  */
696 __rte_experimental
697 int rte_gpu_comm_cleanup_list(struct rte_gpu_comm_list *comm_list_item);
698
699 #ifdef __cplusplus
700 }
701 #endif
702
703 #endif /* RTE_GPUDEV_H */