1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright (c) 2021 NVIDIA Corporation & Affiliates
12 #include <rte_compat.h>
16 * Generic library to interact with GPU computing device.
18 * The API is not thread-safe.
19 * Device management must be done by a single thread.
22 * @b EXPERIMENTAL: this API may change without prior notice.
29 /** Maximum number of devices if rte_gpu_init() is not called. */
30 #define RTE_GPU_DEFAULT_MAX 32
32 /** Empty device ID. */
33 #define RTE_GPU_ID_NONE -1
34 /** Catch-all device ID. */
35 #define RTE_GPU_ID_ANY INT16_MIN
37 /** Catch-all callback data. */
38 #define RTE_GPU_CALLBACK_ANY_DATA ((void *)-1)
40 /** Store device info. */
42 /** Unique identifier name. */
44 /** Opaque handler of the device context. */
48 /** ID of the parent device, RTE_GPU_ID_NONE if no parent */
50 /** Total processors available on device. */
51 uint32_t processor_count;
52 /** Total memory available on device. */
54 /* Local NUMA memory ID. -1 if unknown. */
58 /** Flags passed in notification callback. */
60 /** Device is just initialized. */
62 /** Device is going to be released. */
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);
72 * @b EXPERIMENTAL: this API may change without prior notice.
74 * Initialize the device array before probing devices.
75 * If not called, the maximum of probed devices is RTE_GPU_DEFAULT_MAX.
78 * Maximum number of devices.
81 * 0 on success, -rte_errno otherwise:
82 * - ENOMEM if out of memory
84 * - EBUSY if already initialized
87 int rte_gpu_init(size_t dev_max);
91 * @b EXPERIMENTAL: this API may change without prior notice.
93 * Return the number of GPU detected and associated to DPDK.
96 * The number of available computing devices.
99 uint16_t rte_gpu_count_avail(void);
103 * @b EXPERIMENTAL: this API may change without prior notice.
105 * Check if the device is valid and initialized in DPDK.
108 * The input device ID.
111 * - True if dev_id is a valid and initialized computing device.
115 bool rte_gpu_is_valid(int16_t dev_id);
119 * @b EXPERIMENTAL: this API may change without prior notice.
121 * Create a virtual device representing a context in the parent device.
124 * Unique string to identify the device.
126 * Device ID of the parent.
127 * @param child_context
128 * Opaque context handler.
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
141 int16_t rte_gpu_add_child(const char *name,
142 int16_t parent, uint64_t child_context);
146 * @b EXPERIMENTAL: this API may change without prior notice.
148 * Get the ID of the next valid GPU initialized in DPDK.
151 * The initial device ID to start the research.
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.
158 * Next device ID corresponding to a valid and initialized computing device,
159 * RTE_GPU_ID_NONE if there is none.
162 int16_t rte_gpu_find_next(int16_t dev_id, int16_t parent);
166 * @b EXPERIMENTAL: this API may change without prior notice.
168 * Macro to iterate over all valid GPU devices.
171 * The ID of the next possible valid device, usually 0 to iterate all.
173 #define RTE_GPU_FOREACH(dev_id) \
174 RTE_GPU_FOREACH_CHILD(dev_id, RTE_GPU_ID_ANY)
178 * @b EXPERIMENTAL: this API may change without prior notice.
180 * Macro to iterate over all valid computing devices having no parent.
183 * The ID of the next possible valid device, usually 0 to iterate all.
185 #define RTE_GPU_FOREACH_PARENT(dev_id) \
186 RTE_GPU_FOREACH_CHILD(dev_id, RTE_GPU_ID_NONE)
190 * @b EXPERIMENTAL: this API may change without prior notice.
192 * Macro to iterate over all valid children of a computing device parent.
195 * The ID of the next possible valid device, usually 0 to iterate all.
197 * The device ID of the parent.
199 #define RTE_GPU_FOREACH_CHILD(dev_id, parent) \
200 for (dev_id = rte_gpu_find_next(0, parent); \
202 dev_id = rte_gpu_find_next(dev_id + 1, parent))
206 * @b EXPERIMENTAL: this API may change without prior notice.
208 * Close device or child context.
209 * All resources are released.
212 * Device ID to close.
215 * 0 on success, -rte_errno otherwise:
216 * - ENODEV if invalid dev_id
217 * - EPERM if driver error
220 int rte_gpu_close(int16_t dev_id);
224 * @b EXPERIMENTAL: this API may change without prior notice.
226 * Register a function as event callback.
227 * A function may be registered multiple times for different events.
230 * Device ID to get notified about.
231 * RTE_GPU_ID_ANY means all devices.
233 * Device event to be registered for.
235 * Callback function to be called on event.
237 * Optional parameter passed in the callback.
240 * 0 on success, -rte_errno otherwise:
241 * - ENODEV if invalid dev_id
242 * - EINVAL if NULL function
243 * - ENOMEM if out of memory
246 int rte_gpu_callback_register(int16_t dev_id, enum rte_gpu_event event,
247 rte_gpu_callback_t *function, void *user_data);
251 * @b EXPERIMENTAL: this API may change without prior notice.
253 * Unregister for an event.
256 * Device ID to be silenced.
257 * RTE_GPU_ID_ANY means all devices.
261 * Registered function.
263 * Optional parameter as registered.
264 * RTE_GPU_CALLBACK_ANY_DATA is a catch-all.
267 * 0 on success, -rte_errno otherwise:
268 * - ENODEV if invalid dev_id
269 * - EINVAL if NULL function
272 int rte_gpu_callback_unregister(int16_t dev_id, enum rte_gpu_event event,
273 rte_gpu_callback_t *function, void *user_data);
277 * @b EXPERIMENTAL: this API may change without prior notice.
279 * Return device specific info.
282 * Device ID to get info.
284 * Memory structure to fill with the info.
287 * 0 on success, -rte_errno otherwise:
288 * - ENODEV if invalid dev_id
289 * - EINVAL if NULL info
290 * - EPERM if driver error
293 int rte_gpu_info_get(int16_t dev_id, struct rte_gpu_info *info);
299 #endif /* RTE_GPUDEV_H */