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
  35 /** Store device info. */
  36 struct rte_gpu_info {
  37         /** Unique identifier name. */
  38         const char *name;
  39         /** Device ID. */
  40         int16_t dev_id;
  41         /** Total processors available on device. */
  42         uint32_t processor_count;
  43         /** Total memory available on device. */
  44         size_t total_memory;
  45         /* Local NUMA memory ID. -1 if unknown. */
  46         int16_t numa_node;
  47 };
  48
  49 /**
  50  * @warning
  51  * @b EXPERIMENTAL: this API may change without prior notice.
  52  *
  53  * Initialize the device array before probing devices.
  54  * If not called, the maximum of probed devices is RTE_GPU_DEFAULT_MAX.
  55  *
  56  * @param dev_max
  57  *   Maximum number of devices.
  58  *
  59  * @return
  60  *   0 on success, -rte_errno otherwise:
  61  *   - ENOMEM if out of memory
  62  *   - EINVAL if 0 size
  63  *   - EBUSY if already initialized
  64  */
  65 __rte_experimental
  66 int rte_gpu_init(size_t dev_max);
  67
  68 /**
  69  * @warning
  70  * @b EXPERIMENTAL: this API may change without prior notice.
  71  *
  72  * Return the number of GPU detected and associated to DPDK.
  73  *
  74  * @return
  75  *   The number of available computing devices.
  76  */
  77 __rte_experimental
  78 uint16_t rte_gpu_count_avail(void);
  79
  80 /**
  81  * @warning
  82  * @b EXPERIMENTAL: this API may change without prior notice.
  83  *
  84  * Check if the device is valid and initialized in DPDK.
  85  *
  86  * @param dev_id
  87  *   The input device ID.
  88  *
  89  * @return
  90  *   - True if dev_id is a valid and initialized computing device.
  91  *   - False otherwise.
  92  */
  93 __rte_experimental
  94 bool rte_gpu_is_valid(int16_t dev_id);
  95
  96 /**
  97  * @warning
  98  * @b EXPERIMENTAL: this API may change without prior notice.
  99  *
 100  * Get the ID of the next valid GPU initialized in DPDK.
 101  *
 102  * @param dev_id
 103  *   The initial device ID to start the research.
 104  *
 105  * @return
 106  *   Next device ID corresponding to a valid and initialized computing device,
 107  *   RTE_GPU_ID_NONE if there is none.
 108  */
 109 __rte_experimental
 110 int16_t rte_gpu_find_next(int16_t dev_id);
 111
 112 /**
 113  * @warning
 114  * @b EXPERIMENTAL: this API may change without prior notice.
 115  *
 116  * Macro to iterate over all valid GPU devices.
 117  *
 118  * @param dev_id
 119  *   The ID of the next possible valid device, usually 0 to iterate all.
 120  */
 121 #define RTE_GPU_FOREACH(dev_id) \
 122         for (dev_id = rte_gpu_find_next(0); \
 123              dev_id > 0; \
 124              dev_id = rte_gpu_find_next(dev_id + 1))
 125
 126 /**
 127  * @warning
 128  * @b EXPERIMENTAL: this API may change without prior notice.
 129  *
 130  * Close device.
 131  * All resources are released.
 132  *
 133  * @param dev_id
 134  *   Device ID to close.
 135  *
 136  * @return
 137  *   0 on success, -rte_errno otherwise:
 138  *   - ENODEV if invalid dev_id
 139  *   - EPERM if driver error
 140  */
 141 __rte_experimental
 142 int rte_gpu_close(int16_t dev_id);
 143
 144 /**
 145  * @warning
 146  * @b EXPERIMENTAL: this API may change without prior notice.
 147  *
 148  * Return device specific info.
 149  *
 150  * @param dev_id
 151  *   Device ID to get info.
 152  * @param info
 153  *   Memory structure to fill with the info.
 154  *
 155  * @return
 156  *   0 on success, -rte_errno otherwise:
 157  *   - ENODEV if invalid dev_id
 158  *   - EINVAL if NULL info
 159  *   - EPERM if driver error
 160  */
 161 __rte_experimental
 162 int rte_gpu_info_get(int16_t dev_id, struct rte_gpu_info *info);
 163
 164 #ifdef __cplusplus
 165 }
 166 #endif
 167
 168 #endif /* RTE_GPUDEV_H */