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_compat.h>
  13
  14 /**
  15  * @file
  16  * Generic library to interact with GPU computing device.
  17  *
  18  * The API is not thread-safe.
  19  * Device management must be done by a single thread.
  20  *
  21  * @warning
  22  * @b EXPERIMENTAL: this API may change without prior notice.
  23  */
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28
  29 /** Maximum number of devices if rte_gpu_init() is not called. */
  30 #define RTE_GPU_DEFAULT_MAX 32
  31
  32 /** Empty device ID. */
  33 #define RTE_GPU_ID_NONE -1
  34 /** Catch-all device ID. */
  35 #define RTE_GPU_ID_ANY INT16_MIN
  36
  37 /** Catch-all callback data. */
  38 #define RTE_GPU_CALLBACK_ANY_DATA ((void *)-1)
  39
  40 /** Store device info. */
  41 struct rte_gpu_info {
  42         /** Unique identifier name. */
  43         const char *name;
  44         /** Device ID. */
  45         int16_t dev_id;
  46         /** Total processors available on device. */
  47         uint32_t processor_count;
  48         /** Total memory available on device. */
  49         size_t total_memory;
  50         /* Local NUMA memory ID. -1 if unknown. */
  51         int16_t numa_node;
  52 };
  53
  54 /** Flags passed in notification callback. */
  55 enum rte_gpu_event {
  56         /** Device is just initialized. */
  57         RTE_GPU_EVENT_NEW,
  58         /** Device is going to be released. */
  59         RTE_GPU_EVENT_DEL,
  60 };
  61
  62 /** Prototype of event callback function. */
  63 typedef void (rte_gpu_callback_t)(int16_t dev_id,
  64                 enum rte_gpu_event event, void *user_data);
  65
  66 /**
  67  * @warning
  68  * @b EXPERIMENTAL: this API may change without prior notice.
  69  *
  70  * Initialize the device array before probing devices.
  71  * If not called, the maximum of probed devices is RTE_GPU_DEFAULT_MAX.
  72  *
  73  * @param dev_max
  74  *   Maximum number of devices.
  75  *
  76  * @return
  77  *   0 on success, -rte_errno otherwise:
  78  *   - ENOMEM if out of memory
  79  *   - EINVAL if 0 size
  80  *   - EBUSY if already initialized
  81  */
  82 __rte_experimental
  83 int rte_gpu_init(size_t dev_max);
  84
  85 /**
  86  * @warning
  87  * @b EXPERIMENTAL: this API may change without prior notice.
  88  *
  89  * Return the number of GPU detected and associated to DPDK.
  90  *
  91  * @return
  92  *   The number of available computing devices.
  93  */
  94 __rte_experimental
  95 uint16_t rte_gpu_count_avail(void);
  96
  97 /**
  98  * @warning
  99  * @b EXPERIMENTAL: this API may change without prior notice.
 100  *
 101  * Check if the device is valid and initialized in DPDK.
 102  *
 103  * @param dev_id
 104  *   The input device ID.
 105  *
 106  * @return
 107  *   - True if dev_id is a valid and initialized computing device.
 108  *   - False otherwise.
 109  */
 110 __rte_experimental
 111 bool rte_gpu_is_valid(int16_t dev_id);
 112
 113 /**
 114  * @warning
 115  * @b EXPERIMENTAL: this API may change without prior notice.
 116  *
 117  * Get the ID of the next valid GPU initialized in DPDK.
 118  *
 119  * @param dev_id
 120  *   The initial device ID to start the research.
 121  *
 122  * @return
 123  *   Next device ID corresponding to a valid and initialized computing device,
 124  *   RTE_GPU_ID_NONE if there is none.
 125  */
 126 __rte_experimental
 127 int16_t rte_gpu_find_next(int16_t dev_id);
 128
 129 /**
 130  * @warning
 131  * @b EXPERIMENTAL: this API may change without prior notice.
 132  *
 133  * Macro to iterate over all valid GPU devices.
 134  *
 135  * @param dev_id
 136  *   The ID of the next possible valid device, usually 0 to iterate all.
 137  */
 138 #define RTE_GPU_FOREACH(dev_id) \
 139         for (dev_id = rte_gpu_find_next(0); \
 140              dev_id > 0; \
 141              dev_id = rte_gpu_find_next(dev_id + 1))
 142
 143 /**
 144  * @warning
 145  * @b EXPERIMENTAL: this API may change without prior notice.
 146  *
 147  * Close device.
 148  * All resources are released.
 149  *
 150  * @param dev_id
 151  *   Device ID to close.
 152  *
 153  * @return
 154  *   0 on success, -rte_errno otherwise:
 155  *   - ENODEV if invalid dev_id
 156  *   - EPERM if driver error
 157  */
 158 __rte_experimental
 159 int rte_gpu_close(int16_t dev_id);
 160
 161 /**
 162  * @warning
 163  * @b EXPERIMENTAL: this API may change without prior notice.
 164  *
 165  * Register a function as event callback.
 166  * A function may be registered multiple times for different events.
 167  *
 168  * @param dev_id
 169  *   Device ID to get notified about.
 170  *   RTE_GPU_ID_ANY means all devices.
 171  * @param event
 172  *   Device event to be registered for.
 173  * @param function
 174  *   Callback function to be called on event.
 175  * @param user_data
 176  *   Optional parameter passed in the callback.
 177  *
 178  * @return
 179  *   0 on success, -rte_errno otherwise:
 180  *   - ENODEV if invalid dev_id
 181  *   - EINVAL if NULL function
 182  *   - ENOMEM if out of memory
 183  */
 184 __rte_experimental
 185 int rte_gpu_callback_register(int16_t dev_id, enum rte_gpu_event event,
 186                 rte_gpu_callback_t *function, void *user_data);
 187
 188 /**
 189  * @warning
 190  * @b EXPERIMENTAL: this API may change without prior notice.
 191  *
 192  * Unregister for an event.
 193  *
 194  * @param dev_id
 195  *   Device ID to be silenced.
 196  *   RTE_GPU_ID_ANY means all devices.
 197  * @param event
 198  *   Registered event.
 199  * @param function
 200  *   Registered function.
 201  * @param user_data
 202  *   Optional parameter as registered.
 203  *   RTE_GPU_CALLBACK_ANY_DATA is a catch-all.
 204  *
 205  * @return
 206  *   0 on success, -rte_errno otherwise:
 207  *   - ENODEV if invalid dev_id
 208  *   - EINVAL if NULL function
 209  */
 210 __rte_experimental
 211 int rte_gpu_callback_unregister(int16_t dev_id, enum rte_gpu_event event,
 212                 rte_gpu_callback_t *function, void *user_data);
 213
 214 /**
 215  * @warning
 216  * @b EXPERIMENTAL: this API may change without prior notice.
 217  *
 218  * Return device specific info.
 219  *
 220  * @param dev_id
 221  *   Device ID to get info.
 222  * @param info
 223  *   Memory structure to fill with the info.
 224  *
 225  * @return
 226  *   0 on success, -rte_errno otherwise:
 227  *   - ENODEV if invalid dev_id
 228  *   - EINVAL if NULL info
 229  *   - EPERM if driver error
 230  */
 231 __rte_experimental
 232 int rte_gpu_info_get(int16_t dev_id, struct rte_gpu_info *info);
 233
 234 #ifdef __cplusplus
 235 }
 236 #endif
 237
 238 #endif /* RTE_GPUDEV_H */