eventdev: add capabilities API
[dpdk.git] / lib / librte_eventdev / rte_eventdev_pmd.h
1 /*
2  *
3  *   Copyright(c) 2016 Cavium, Inc. All rights reserved.
4  *
5  *   Redistribution and use in source and binary forms, with or without
6  *   modification, are permitted provided that the following conditions
7  *   are met:
8  *
9  *     * Redistributions of source code must retain the above copyright
10  *       notice, this list of conditions and the following disclaimer.
11  *     * Redistributions in binary form must reproduce the above copyright
12  *       notice, this list of conditions and the following disclaimer in
13  *       the documentation and/or other materials provided with the
14  *       distribution.
15  *     * Neither the name of Cavium, Inc nor the names of its
16  *       contributors may be used to endorse or promote products derived
17  *       from this software without specific prior written permission.
18  *
19  *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20  *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21  *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
22  *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
23  *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24  *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
25  *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
26  *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
27  *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
28  *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30  */
31
32 #ifndef _RTE_EVENTDEV_PMD_H_
33 #define _RTE_EVENTDEV_PMD_H_
34
35 /** @file
36  * RTE Event PMD APIs
37  *
38  * @note
39  * These API are from event PMD only and user applications should not call
40  * them directly.
41  */
42
43 #ifdef __cplusplus
44 extern "C" {
45 #endif
46
47 #include <string.h>
48
49 #include <rte_common.h>
50 #include <rte_dev.h>
51 #include <rte_log.h>
52 #include <rte_malloc.h>
53
54 #include "rte_eventdev.h"
55
56 /* Logging Macros */
57 #define RTE_EDEV_LOG_ERR(...) \
58         RTE_LOG(ERR, EVENTDEV, \
59                 RTE_FMT("%s() line %u: " RTE_FMT_HEAD(__VA_ARGS__,) "\n", \
60                         __func__, __LINE__, RTE_FMT_TAIL(__VA_ARGS__,)))
61
62 #ifdef RTE_LIBRTE_EVENTDEV_DEBUG
63 #define RTE_EDEV_LOG_DEBUG(...) \
64         RTE_LOG(DEBUG, EVENTDEV, \
65                 RTE_FMT("%s() line %u: " RTE_FMT_HEAD(__VA_ARGS__,) "\n", \
66                         __func__, __LINE__, RTE_FMT_TAIL(__VA_ARGS__,)))
67 #else
68 #define RTE_EDEV_LOG_DEBUG(...) (void)0
69 #endif
70
71 /* Macros to check for valid device */
72 #define RTE_EVENTDEV_VALID_DEVID_OR_ERR_RET(dev_id, retval) do { \
73         if (!rte_event_pmd_is_valid_dev((dev_id))) { \
74                 RTE_EDEV_LOG_ERR("Invalid dev_id=%d\n", dev_id); \
75                 return retval; \
76         } \
77 } while (0)
78
79 #define RTE_EVENTDEV_VALID_DEVID_OR_RET(dev_id) do { \
80         if (!rte_event_pmd_is_valid_dev((dev_id))) { \
81                 RTE_EDEV_LOG_ERR("Invalid dev_id=%d\n", dev_id); \
82                 return; \
83         } \
84 } while (0)
85
86 #define RTE_EVENTDEV_DETACHED  (0)
87 #define RTE_EVENTDEV_ATTACHED  (1)
88
89 struct rte_eth_dev;
90
91 /** Global structure used for maintaining state of allocated event devices */
92 struct rte_eventdev_global {
93         uint8_t nb_devs;        /**< Number of devices found */
94 };
95
96 extern struct rte_eventdev_global *rte_eventdev_globals;
97 /** Pointer to global event devices data structure. */
98 extern struct rte_eventdev *rte_eventdevs;
99 /** The pool of rte_eventdev structures. */
100
101 /**
102  * Get the rte_eventdev structure device pointer for the named device.
103  *
104  * @param name
105  *   device name to select the device structure.
106  *
107  * @return
108  *   - The rte_eventdev structure pointer for the given device ID.
109  */
110 static inline struct rte_eventdev *
111 rte_event_pmd_get_named_dev(const char *name)
112 {
113         struct rte_eventdev *dev;
114         unsigned int i;
115
116         if (name == NULL)
117                 return NULL;
118
119         for (i = 0; i < RTE_EVENT_MAX_DEVS; i++) {
120                 dev = &rte_eventdevs[i];
121                 if ((dev->attached == RTE_EVENTDEV_ATTACHED) &&
122                                 (strcmp(dev->data->name, name) == 0))
123                         return dev;
124         }
125
126         return NULL;
127 }
128
129 /**
130  * Validate if the event device index is valid attached event device.
131  *
132  * @param dev_id
133  *   Event device index.
134  *
135  * @return
136  *   - If the device index is valid (1) or not (0).
137  */
138 static inline unsigned
139 rte_event_pmd_is_valid_dev(uint8_t dev_id)
140 {
141         struct rte_eventdev *dev;
142
143         if (dev_id >= RTE_EVENT_MAX_DEVS)
144                 return 0;
145
146         dev = &rte_eventdevs[dev_id];
147         if (dev->attached != RTE_EVENTDEV_ATTACHED)
148                 return 0;
149         else
150                 return 1;
151 }
152
153 /**
154  * Definitions of all functions exported by a driver through the
155  * the generic structure of type *event_dev_ops* supplied in the
156  * *rte_eventdev* structure associated with a device.
157  */
158
159 /**
160  * Get device information of a device.
161  *
162  * @param dev
163  *   Event device pointer
164  * @param dev_info
165  *   Event device information structure
166  *
167  * @return
168  *   Returns 0 on success
169  */
170 typedef void (*eventdev_info_get_t)(struct rte_eventdev *dev,
171                 struct rte_event_dev_info *dev_info);
172
173 /**
174  * Configure a device.
175  *
176  * @param dev
177  *   Event device pointer
178  *
179  * @return
180  *   Returns 0 on success
181  */
182 typedef int (*eventdev_configure_t)(const struct rte_eventdev *dev);
183
184 /**
185  * Start a configured device.
186  *
187  * @param dev
188  *   Event device pointer
189  *
190  * @return
191  *   Returns 0 on success
192  */
193 typedef int (*eventdev_start_t)(struct rte_eventdev *dev);
194
195 /**
196  * Stop a configured device.
197  *
198  * @param dev
199  *   Event device pointer
200  */
201 typedef void (*eventdev_stop_t)(struct rte_eventdev *dev);
202
203 /**
204  * Close a configured device.
205  *
206  * @param dev
207  *   Event device pointer
208  *
209  * @return
210  * - 0 on success
211  * - (-EAGAIN) if can't close as device is busy
212  */
213 typedef int (*eventdev_close_t)(struct rte_eventdev *dev);
214
215 /**
216  * Retrieve the default event queue configuration.
217  *
218  * @param dev
219  *   Event device pointer
220  * @param queue_id
221  *   Event queue index
222  * @param[out] queue_conf
223  *   Event queue configuration structure
224  *
225  */
226 typedef void (*eventdev_queue_default_conf_get_t)(struct rte_eventdev *dev,
227                 uint8_t queue_id, struct rte_event_queue_conf *queue_conf);
228
229 /**
230  * Setup an event queue.
231  *
232  * @param dev
233  *   Event device pointer
234  * @param queue_id
235  *   Event queue index
236  * @param queue_conf
237  *   Event queue configuration structure
238  *
239  * @return
240  *   Returns 0 on success.
241  */
242 typedef int (*eventdev_queue_setup_t)(struct rte_eventdev *dev,
243                 uint8_t queue_id,
244                 const struct rte_event_queue_conf *queue_conf);
245
246 /**
247  * Release resources allocated by given event queue.
248  *
249  * @param dev
250  *   Event device pointer
251  * @param queue_id
252  *   Event queue index
253  *
254  */
255 typedef void (*eventdev_queue_release_t)(struct rte_eventdev *dev,
256                 uint8_t queue_id);
257
258 /**
259  * Retrieve the default event port configuration.
260  *
261  * @param dev
262  *   Event device pointer
263  * @param port_id
264  *   Event port index
265  * @param[out] port_conf
266  *   Event port configuration structure
267  *
268  */
269 typedef void (*eventdev_port_default_conf_get_t)(struct rte_eventdev *dev,
270                 uint8_t port_id, struct rte_event_port_conf *port_conf);
271
272 /**
273  * Setup an event port.
274  *
275  * @param dev
276  *   Event device pointer
277  * @param port_id
278  *   Event port index
279  * @param port_conf
280  *   Event port configuration structure
281  *
282  * @return
283  *   Returns 0 on success.
284  */
285 typedef int (*eventdev_port_setup_t)(struct rte_eventdev *dev,
286                 uint8_t port_id,
287                 const struct rte_event_port_conf *port_conf);
288
289 /**
290  * Release memory resources allocated by given event port.
291  *
292  * @param port
293  *   Event port pointer
294  *
295  */
296 typedef void (*eventdev_port_release_t)(void *port);
297
298 /**
299  * Link multiple source event queues to destination event port.
300  *
301  * @param dev
302  *   Event device pointer
303  * @param port
304  *   Event port pointer
305  * @param link
306  *   Points to an array of *nb_links* event queues to be linked
307  *   to the event port.
308  * @param priorities
309  *   Points to an array of *nb_links* service priorities associated with each
310  *   event queue link to event port.
311  * @param nb_links
312  *   The number of links to establish
313  *
314  * @return
315  *   Returns 0 on success.
316  *
317  */
318 typedef int (*eventdev_port_link_t)(struct rte_eventdev *dev, void *port,
319                 const uint8_t queues[], const uint8_t priorities[],
320                 uint16_t nb_links);
321
322 /**
323  * Unlink multiple source event queues from destination event port.
324  *
325  * @param dev
326  *   Event device pointer
327  * @param port
328  *   Event port pointer
329  * @param queues
330  *   An array of *nb_unlinks* event queues to be unlinked from the event port.
331  * @param nb_unlinks
332  *   The number of unlinks to establish
333  *
334  * @return
335  *   Returns 0 on success.
336  *
337  */
338 typedef int (*eventdev_port_unlink_t)(struct rte_eventdev *dev, void *port,
339                 uint8_t queues[], uint16_t nb_unlinks);
340
341 /**
342  * Converts nanoseconds to *timeout_ticks* value for rte_event_dequeue()
343  *
344  * @param dev
345  *   Event device pointer
346  * @param ns
347  *   Wait time in nanosecond
348  * @param[out] timeout_ticks
349  *   Value for the *timeout_ticks* parameter in rte_event_dequeue() function
350  *
351  * @return
352  *   Returns 0 on success.
353  *
354  */
355 typedef int (*eventdev_dequeue_timeout_ticks_t)(struct rte_eventdev *dev,
356                 uint64_t ns, uint64_t *timeout_ticks);
357
358 /**
359  * Dump internal information
360  *
361  * @param dev
362  *   Event device pointer
363  * @param f
364  *   A pointer to a file for output
365  *
366  */
367 typedef void (*eventdev_dump_t)(struct rte_eventdev *dev, FILE *f);
368
369 /**
370  * Retrieve a set of statistics from device
371  *
372  * @param dev
373  *   Event device pointer
374  * @param ids
375  *   The stat ids to retrieve
376  * @param values
377  *   The returned stat values
378  * @param n
379  *   The number of id values and entries in the values array
380  * @return
381  *   The number of stat values successfully filled into the values array
382  */
383 typedef int (*eventdev_xstats_get_t)(const struct rte_eventdev *dev,
384                 enum rte_event_dev_xstats_mode mode, uint8_t queue_port_id,
385                 const unsigned int ids[], uint64_t values[], unsigned int n);
386
387 /**
388  * Resets the statistic values in xstats for the device, based on mode.
389  */
390 typedef int (*eventdev_xstats_reset_t)(struct rte_eventdev *dev,
391                 enum rte_event_dev_xstats_mode mode,
392                 int16_t queue_port_id,
393                 const uint32_t ids[],
394                 uint32_t nb_ids);
395
396 /**
397  * Get names of extended stats of an event device
398  *
399  * @param dev
400  *   Event device pointer
401  * @param xstats_names
402  *   Array of name values to be filled in
403  * @param size
404  *   Number of values in the xstats_names array
405  * @return
406  *   When size >= the number of stats, return the number of stat values filled
407  *   into the array.
408  *   When size < the number of available stats, return the number of stats
409  *   values, and do not fill in any data into xstats_names.
410  */
411 typedef int (*eventdev_xstats_get_names_t)(const struct rte_eventdev *dev,
412                 enum rte_event_dev_xstats_mode mode, uint8_t queue_port_id,
413                 struct rte_event_dev_xstats_name *xstats_names,
414                 unsigned int *ids, unsigned int size);
415
416 /**
417  * Get value of one stats and optionally return its id
418  *
419  * @param dev
420  *   Event device pointer
421  * @param name
422  *   The name of the stat to retrieve
423  * @param id
424  *   Pointer to an unsigned int where we store the stat-id for future reference.
425  *   This pointer may be null if the id is not required.
426  * @return
427  *   The value of the stat, or (uint64_t)-1 if the stat is not found.
428  *   If the stat is not found, the id value will be returned as (unsigned)-1,
429  *   if id pointer is non-NULL
430  */
431 typedef uint64_t (*eventdev_xstats_get_by_name)(const struct rte_eventdev *dev,
432                 const char *name, unsigned int *id);
433
434
435 /**
436  * Retrieve the event device's ethdev Rx adapter capabilities for the
437  * specified ethernet port
438  *
439  * @param dev
440  *   Event device pointer
441  *
442  * @param eth_dev
443  *   Ethernet device pointer
444  *
445  * @param[out] caps
446  *   A pointer to memory filled with Rx event adapter capabilities.
447  *
448  * @return
449  *   - 0: Success, driver provides Rx event adapter capabilities for the
450  *      ethernet device.
451  *   - <0: Error code returned by the driver function.
452  *
453  */
454 typedef int (*eventdev_eth_rx_adapter_caps_get_t)
455                                         (const struct rte_eventdev *dev,
456                                         const struct rte_eth_dev *eth_dev,
457                                         uint32_t *caps);
458 /** Event device operations function pointer table */
459 struct rte_eventdev_ops {
460         eventdev_info_get_t dev_infos_get;      /**< Get device info. */
461         eventdev_configure_t dev_configure;     /**< Configure device. */
462         eventdev_start_t dev_start;             /**< Start device. */
463         eventdev_stop_t dev_stop;               /**< Stop device. */
464         eventdev_close_t dev_close;             /**< Close device. */
465
466         eventdev_queue_default_conf_get_t queue_def_conf;
467         /**< Get default queue configuration. */
468         eventdev_queue_setup_t queue_setup;
469         /**< Set up an event queue. */
470         eventdev_queue_release_t queue_release;
471         /**< Release an event queue. */
472
473         eventdev_port_default_conf_get_t port_def_conf;
474         /**< Get default port configuration. */
475         eventdev_port_setup_t port_setup;
476         /**< Set up an event port. */
477         eventdev_port_release_t port_release;
478         /**< Release an event port. */
479
480         eventdev_port_link_t port_link;
481         /**< Link event queues to an event port. */
482         eventdev_port_unlink_t port_unlink;
483         /**< Unlink event queues from an event port. */
484         eventdev_dequeue_timeout_ticks_t timeout_ticks;
485         /**< Converts ns to *timeout_ticks* value for rte_event_dequeue() */
486         eventdev_dump_t dump;
487         /* Dump internal information */
488
489         eventdev_xstats_get_t xstats_get;
490         /**< Get extended device statistics. */
491         eventdev_xstats_get_names_t xstats_get_names;
492         /**< Get names of extended stats. */
493         eventdev_xstats_get_by_name xstats_get_by_name;
494         /**< Get one value by name. */
495         eventdev_xstats_reset_t xstats_reset;
496         /**< Reset the statistics values in xstats. */
497
498         eventdev_eth_rx_adapter_caps_get_t eth_rx_adapter_caps_get;
499         /**< Get ethernet Rx adapter capabilities */
500 };
501
502 /**
503  * Allocates a new eventdev slot for an event device and returns the pointer
504  * to that slot for the driver to use.
505  *
506  * @param name
507  *   Unique identifier name for each device
508  * @param socket_id
509  *   Socket to allocate resources on.
510  * @return
511  *   - Slot in the rte_dev_devices array for a new device;
512  */
513 struct rte_eventdev *
514 rte_event_pmd_allocate(const char *name, int socket_id);
515
516 /**
517  * Release the specified eventdev device.
518  *
519  * @param eventdev
520  * The *eventdev* pointer is the address of the *rte_eventdev* structure.
521  * @return
522  *   - 0 on success, negative on error
523  */
524 int
525 rte_event_pmd_release(struct rte_eventdev *eventdev);
526
527 #ifdef __cplusplus
528 }
529 #endif
530
531 #endif /* _RTE_EVENTDEV_PMD_H_ */