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         /** Opaque handler of the device context. */
  45         uint64_t context;
  46         /** Device ID. */
  47         int16_t dev_id;
  48         /** ID of the parent device, RTE_GPU_ID_NONE if no parent */
  49         int16_t parent;
  50         /** Total processors available on device. */
  51         uint32_t processor_count;
  52         /** Total memory available on device. */
  53         size_t total_memory;
  54         /* Local NUMA memory ID. -1 if unknown. */
  55         int16_t numa_node;
  56 };
  57
  58 /** Flags passed in notification callback. */
  59 enum rte_gpu_event {
  60         /** Device is just initialized. */
  61         RTE_GPU_EVENT_NEW,
  62         /** Device is going to be released. */
  63         RTE_GPU_EVENT_DEL,
  64 };
  65
  66 /** Prototype of event callback function. */
  67 typedef void (rte_gpu_callback_t)(int16_t dev_id,
  68                 enum rte_gpu_event event, void *user_data);
  69
  70 /**
  71  * @warning
  72  * @b EXPERIMENTAL: this API may change without prior notice.
  73  *
  74  * Initialize the device array before probing devices.
  75  * If not called, the maximum of probed devices is RTE_GPU_DEFAULT_MAX.
  76  *
  77  * @param dev_max
  78  *   Maximum number of devices.
  79  *
  80  * @return
  81  *   0 on success, -rte_errno otherwise:
  82  *   - ENOMEM if out of memory
  83  *   - EINVAL if 0 size
  84  *   - EBUSY if already initialized
  85  */
  86 __rte_experimental
  87 int rte_gpu_init(size_t dev_max);
  88
  89 /**
  90  * @warning
  91  * @b EXPERIMENTAL: this API may change without prior notice.
  92  *
  93  * Return the number of GPU detected and associated to DPDK.
  94  *
  95  * @return
  96  *   The number of available computing devices.
  97  */
  98 __rte_experimental
  99 uint16_t rte_gpu_count_avail(void);
 100
 101 /**
 102  * @warning
 103  * @b EXPERIMENTAL: this API may change without prior notice.
 104  *
 105  * Check if the device is valid and initialized in DPDK.
 106  *
 107  * @param dev_id
 108  *   The input device ID.
 109  *
 110  * @return
 111  *   - True if dev_id is a valid and initialized computing device.
 112  *   - False otherwise.
 113  */
 114 __rte_experimental
 115 bool rte_gpu_is_valid(int16_t dev_id);
 116
 117 /**
 118  * @warning
 119  * @b EXPERIMENTAL: this API may change without prior notice.
 120  *
 121  * Create a virtual device representing a context in the parent device.
 122  *
 123  * @param name
 124  *   Unique string to identify the device.
 125  * @param parent
 126  *   Device ID of the parent.
 127  * @param child_context
 128  *   Opaque context handler.
 129  *
 130  * @return
 131  *   Device ID of the new created child, -rte_errno otherwise:
 132  *   - EINVAL if empty name
 133  *   - ENAMETOOLONG if long name
 134  *   - EEXIST if existing device name
 135  *   - ENODEV if invalid parent
 136  *   - EPERM if secondary process
 137  *   - ENOENT if too many devices
 138  *   - ENOMEM if out of space
 139  */
 140 __rte_experimental
 141 int16_t rte_gpu_add_child(const char *name,
 142                 int16_t parent, uint64_t child_context);
 143
 144 /**
 145  * @warning
 146  * @b EXPERIMENTAL: this API may change without prior notice.
 147  *
 148  * Get the ID of the next valid GPU initialized in DPDK.
 149  *
 150  * @param dev_id
 151  *   The initial device ID to start the research.
 152  * @param parent
 153  *   The device ID of the parent.
 154  *   RTE_GPU_ID_NONE means no parent.
 155  *   RTE_GPU_ID_ANY means no or any parent.
 156  *
 157  * @return
 158  *   Next device ID corresponding to a valid and initialized computing device,
 159  *   RTE_GPU_ID_NONE if there is none.
 160  */
 161 __rte_experimental
 162 int16_t rte_gpu_find_next(int16_t dev_id, int16_t parent);
 163
 164 /**
 165  * @warning
 166  * @b EXPERIMENTAL: this API may change without prior notice.
 167  *
 168  * Macro to iterate over all valid GPU devices.
 169  *
 170  * @param dev_id
 171  *   The ID of the next possible valid device, usually 0 to iterate all.
 172  */
 173 #define RTE_GPU_FOREACH(dev_id) \
 174         RTE_GPU_FOREACH_CHILD(dev_id, RTE_GPU_ID_ANY)
 175
 176 /**
 177  * @warning
 178  * @b EXPERIMENTAL: this API may change without prior notice.
 179  *
 180  * Macro to iterate over all valid computing devices having no parent.
 181  *
 182  * @param dev_id
 183  *   The ID of the next possible valid device, usually 0 to iterate all.
 184  */
 185 #define RTE_GPU_FOREACH_PARENT(dev_id) \
 186         RTE_GPU_FOREACH_CHILD(dev_id, RTE_GPU_ID_NONE)
 187
 188 /**
 189  * @warning
 190  * @b EXPERIMENTAL: this API may change without prior notice.
 191  *
 192  * Macro to iterate over all valid children of a computing device parent.
 193  *
 194  * @param dev_id
 195  *   The ID of the next possible valid device, usually 0 to iterate all.
 196  * @param parent
 197  *   The device ID of the parent.
 198  */
 199 #define RTE_GPU_FOREACH_CHILD(dev_id, parent) \
 200         for (dev_id = rte_gpu_find_next(0, parent); \
 201              dev_id >= 0; \
 202              dev_id = rte_gpu_find_next(dev_id + 1, parent))
 203
 204 /**
 205  * @warning
 206  * @b EXPERIMENTAL: this API may change without prior notice.
 207  *
 208  * Close device or child context.
 209  * All resources are released.
 210  *
 211  * @param dev_id
 212  *   Device ID to close.
 213  *
 214  * @return
 215  *   0 on success, -rte_errno otherwise:
 216  *   - ENODEV if invalid dev_id
 217  *   - EPERM if driver error
 218  */
 219 __rte_experimental
 220 int rte_gpu_close(int16_t dev_id);
 221
 222 /**
 223  * @warning
 224  * @b EXPERIMENTAL: this API may change without prior notice.
 225  *
 226  * Register a function as event callback.
 227  * A function may be registered multiple times for different events.
 228  *
 229  * @param dev_id
 230  *   Device ID to get notified about.
 231  *   RTE_GPU_ID_ANY means all devices.
 232  * @param event
 233  *   Device event to be registered for.
 234  * @param function
 235  *   Callback function to be called on event.
 236  * @param user_data
 237  *   Optional parameter passed in the callback.
 238  *
 239  * @return
 240  *   0 on success, -rte_errno otherwise:
 241  *   - ENODEV if invalid dev_id
 242  *   - EINVAL if NULL function
 243  *   - ENOMEM if out of memory
 244  */
 245 __rte_experimental
 246 int rte_gpu_callback_register(int16_t dev_id, enum rte_gpu_event event,
 247                 rte_gpu_callback_t *function, void *user_data);
 248
 249 /**
 250  * @warning
 251  * @b EXPERIMENTAL: this API may change without prior notice.
 252  *
 253  * Unregister for an event.
 254  *
 255  * @param dev_id
 256  *   Device ID to be silenced.
 257  *   RTE_GPU_ID_ANY means all devices.
 258  * @param event
 259  *   Registered event.
 260  * @param function
 261  *   Registered function.
 262  * @param user_data
 263  *   Optional parameter as registered.
 264  *   RTE_GPU_CALLBACK_ANY_DATA is a catch-all.
 265  *
 266  * @return
 267  *   0 on success, -rte_errno otherwise:
 268  *   - ENODEV if invalid dev_id
 269  *   - EINVAL if NULL function
 270  */
 271 __rte_experimental
 272 int rte_gpu_callback_unregister(int16_t dev_id, enum rte_gpu_event event,
 273                 rte_gpu_callback_t *function, void *user_data);
 274
 275 /**
 276  * @warning
 277  * @b EXPERIMENTAL: this API may change without prior notice.
 278  *
 279  * Return device specific info.
 280  *
 281  * @param dev_id
 282  *   Device ID to get info.
 283  * @param info
 284  *   Memory structure to fill with the info.
 285  *
 286  * @return
 287  *   0 on success, -rte_errno otherwise:
 288  *   - ENODEV if invalid dev_id
 289  *   - EINVAL if NULL info
 290  *   - EPERM if driver error
 291  */
 292 __rte_experimental
 293 int rte_gpu_info_get(int16_t dev_id, struct rte_gpu_info *info);
 294
 295 #ifdef __cplusplus
 296 }
 297 #endif
 298
 299 #endif /* RTE_GPUDEV_H */