event/octeontx: add dump function for easier debugging
[dpdk.git] / lib / librte_eventdev / rte_eventdev_pmd.h
1 /*
2  *
3  *   Copyright(c) 2016 Cavium networks. 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 networks 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_dev.h>
50 #include <rte_pci.h>
51 #include <rte_malloc.h>
52 #include <rte_log.h>
53 #include <rte_common.h>
54
55 #include "rte_eventdev.h"
56
57 #ifdef RTE_LIBRTE_EVENTDEV_DEBUG
58 #define RTE_PMD_DEBUG_TRACE(...) \
59         rte_pmd_debug_trace(__func__, __VA_ARGS__)
60 #else
61 #define RTE_PMD_DEBUG_TRACE(...)
62 #endif
63
64 /* Logging Macros */
65 #define RTE_EDEV_LOG_ERR(fmt, args...) \
66         RTE_LOG(ERR, EVENTDEV, "%s() line %u: " fmt "\n",  \
67                         __func__, __LINE__, ## args)
68
69 #ifdef RTE_LIBRTE_EVENTDEV_DEBUG
70 #define RTE_EDEV_LOG_DEBUG(fmt, args...) \
71         RTE_LOG(DEBUG, EVENTDEV, "%s() line %u: " fmt "\n",  \
72                         __func__, __LINE__, ## args)
73 #else
74 #define RTE_EDEV_LOG_DEBUG(fmt, args...) (void)0
75 #endif
76
77 /* Macros to check for valid device */
78 #define RTE_EVENTDEV_VALID_DEVID_OR_ERR_RET(dev_id, retval) do { \
79         if (!rte_event_pmd_is_valid_dev((dev_id))) { \
80                 RTE_EDEV_LOG_ERR("Invalid dev_id=%d\n", dev_id); \
81                 return retval; \
82         } \
83 } while (0)
84
85 #define RTE_EVENTDEV_VALID_DEVID_OR_RET(dev_id) do { \
86         if (!rte_event_pmd_is_valid_dev((dev_id))) { \
87                 RTE_EDEV_LOG_ERR("Invalid dev_id=%d\n", dev_id); \
88                 return; \
89         } \
90 } while (0)
91
92 #define RTE_EVENTDEV_DETACHED  (0)
93 #define RTE_EVENTDEV_ATTACHED  (1)
94
95 /**
96  * Initialisation function of a event driver invoked for each matching
97  * event PCI device detected during the PCI probing phase.
98  *
99  * @param dev
100  *   The dev pointer is the address of the *rte_eventdev* structure associated
101  *   with the matching device and which has been [automatically] allocated in
102  *   the *rte_event_devices* array.
103  *
104  * @return
105  *   - 0: Success, the device is properly initialised by the driver.
106  *        In particular, the driver MUST have set up the *dev_ops* pointer
107  *        of the *dev* structure.
108  *   - <0: Error code of the device initialisation failure.
109  */
110 typedef int (*eventdev_init_t)(struct rte_eventdev *dev);
111
112 /**
113  * Finalisation function of a driver invoked for each matching
114  * PCI device detected during the PCI closing phase.
115  *
116  * @param dev
117  *   The dev pointer is the address of the *rte_eventdev* structure associated
118  *   with the matching device and which has been [automatically] allocated in
119  *   the *rte_event_devices* array.
120  *
121  * @return
122  *   - 0: Success, the device is properly finalised by the driver.
123  *        In particular, the driver MUST free the *dev_ops* pointer
124  *        of the *dev* structure.
125  *   - <0: Error code of the device initialisation failure.
126  */
127 typedef int (*eventdev_uninit_t)(struct rte_eventdev *dev);
128
129 /**
130  * The structure associated with a PMD driver.
131  *
132  * Each driver acts as a PCI driver and is represented by a generic
133  * *event_driver* structure that holds:
134  *
135  * - An *rte_pci_driver* structure (which must be the first field).
136  *
137  * - The *eventdev_init* function invoked for each matching PCI device.
138  *
139  * - The size of the private data to allocate for each matching device.
140  */
141 struct rte_eventdev_driver {
142         struct rte_pci_driver pci_drv;  /**< The PMD is also a PCI driver. */
143         unsigned int dev_private_size;  /**< Size of device private data. */
144
145         eventdev_init_t eventdev_init;  /**< Device init function. */
146         eventdev_uninit_t eventdev_uninit; /**< Device uninit function. */
147 };
148
149 /** Global structure used for maintaining state of allocated event devices */
150 struct rte_eventdev_global {
151         uint8_t nb_devs;        /**< Number of devices found */
152 };
153
154 extern struct rte_eventdev_global *rte_eventdev_globals;
155 /** Pointer to global event devices data structure. */
156 extern struct rte_eventdev *rte_eventdevs;
157 /** The pool of rte_eventdev structures. */
158
159 /**
160  * Get the rte_eventdev structure device pointer for the named device.
161  *
162  * @param name
163  *   device name to select the device structure.
164  *
165  * @return
166  *   - The rte_eventdev structure pointer for the given device ID.
167  */
168 static inline struct rte_eventdev *
169 rte_event_pmd_get_named_dev(const char *name)
170 {
171         struct rte_eventdev *dev;
172         unsigned int i;
173
174         if (name == NULL)
175                 return NULL;
176
177         for (i = 0; i < RTE_EVENT_MAX_DEVS; i++) {
178                 dev = &rte_eventdevs[i];
179                 if ((dev->attached == RTE_EVENTDEV_ATTACHED) &&
180                                 (strcmp(dev->data->name, name) == 0))
181                         return dev;
182         }
183
184         return NULL;
185 }
186
187 /**
188  * Validate if the event device index is valid attached event device.
189  *
190  * @param dev_id
191  *   Event device index.
192  *
193  * @return
194  *   - If the device index is valid (1) or not (0).
195  */
196 static inline unsigned
197 rte_event_pmd_is_valid_dev(uint8_t dev_id)
198 {
199         struct rte_eventdev *dev;
200
201         if (dev_id >= RTE_EVENT_MAX_DEVS)
202                 return 0;
203
204         dev = &rte_eventdevs[dev_id];
205         if (dev->attached != RTE_EVENTDEV_ATTACHED)
206                 return 0;
207         else
208                 return 1;
209 }
210
211 /**
212  * Definitions of all functions exported by a driver through the
213  * the generic structure of type *event_dev_ops* supplied in the
214  * *rte_eventdev* structure associated with a device.
215  */
216
217 /**
218  * Get device information of a device.
219  *
220  * @param dev
221  *   Event device pointer
222  * @param dev_info
223  *   Event device information structure
224  *
225  * @return
226  *   Returns 0 on success
227  */
228 typedef void (*eventdev_info_get_t)(struct rte_eventdev *dev,
229                 struct rte_event_dev_info *dev_info);
230
231 /**
232  * Configure a device.
233  *
234  * @param dev
235  *   Event device pointer
236  *
237  * @return
238  *   Returns 0 on success
239  */
240 typedef int (*eventdev_configure_t)(const struct rte_eventdev *dev);
241
242 /**
243  * Start a configured device.
244  *
245  * @param dev
246  *   Event device pointer
247  *
248  * @return
249  *   Returns 0 on success
250  */
251 typedef int (*eventdev_start_t)(struct rte_eventdev *dev);
252
253 /**
254  * Stop a configured device.
255  *
256  * @param dev
257  *   Event device pointer
258  */
259 typedef void (*eventdev_stop_t)(struct rte_eventdev *dev);
260
261 /**
262  * Close a configured device.
263  *
264  * @param dev
265  *   Event device pointer
266  *
267  * @return
268  * - 0 on success
269  * - (-EAGAIN) if can't close as device is busy
270  */
271 typedef int (*eventdev_close_t)(struct rte_eventdev *dev);
272
273 /**
274  * Retrieve the default event queue configuration.
275  *
276  * @param dev
277  *   Event device pointer
278  * @param queue_id
279  *   Event queue index
280  * @param[out] queue_conf
281  *   Event queue configuration structure
282  *
283  */
284 typedef void (*eventdev_queue_default_conf_get_t)(struct rte_eventdev *dev,
285                 uint8_t queue_id, struct rte_event_queue_conf *queue_conf);
286
287 /**
288  * Setup an event queue.
289  *
290  * @param dev
291  *   Event device pointer
292  * @param queue_id
293  *   Event queue index
294  * @param queue_conf
295  *   Event queue configuration structure
296  *
297  * @return
298  *   Returns 0 on success.
299  */
300 typedef int (*eventdev_queue_setup_t)(struct rte_eventdev *dev,
301                 uint8_t queue_id,
302                 const struct rte_event_queue_conf *queue_conf);
303
304 /**
305  * Release resources allocated by given event queue.
306  *
307  * @param dev
308  *   Event device pointer
309  * @param queue_id
310  *   Event queue index
311  *
312  */
313 typedef void (*eventdev_queue_release_t)(struct rte_eventdev *dev,
314                 uint8_t queue_id);
315
316 /**
317  * Retrieve the default event port configuration.
318  *
319  * @param dev
320  *   Event device pointer
321  * @param port_id
322  *   Event port index
323  * @param[out] port_conf
324  *   Event port configuration structure
325  *
326  */
327 typedef void (*eventdev_port_default_conf_get_t)(struct rte_eventdev *dev,
328                 uint8_t port_id, struct rte_event_port_conf *port_conf);
329
330 /**
331  * Setup an event port.
332  *
333  * @param dev
334  *   Event device pointer
335  * @param port_id
336  *   Event port index
337  * @param port_conf
338  *   Event port configuration structure
339  *
340  * @return
341  *   Returns 0 on success.
342  */
343 typedef int (*eventdev_port_setup_t)(struct rte_eventdev *dev,
344                 uint8_t port_id,
345                 const struct rte_event_port_conf *port_conf);
346
347 /**
348  * Release memory resources allocated by given event port.
349  *
350  * @param port
351  *   Event port pointer
352  *
353  */
354 typedef void (*eventdev_port_release_t)(void *port);
355
356 /**
357  * Link multiple source event queues to destination event port.
358  *
359  * @param dev
360  *   Event device pointer
361  * @param port
362  *   Event port pointer
363  * @param link
364  *   Points to an array of *nb_links* event queues to be linked
365  *   to the event port.
366  * @param priorities
367  *   Points to an array of *nb_links* service priorities associated with each
368  *   event queue link to event port.
369  * @param nb_links
370  *   The number of links to establish
371  *
372  * @return
373  *   Returns 0 on success.
374  *
375  */
376 typedef int (*eventdev_port_link_t)(struct rte_eventdev *dev, void *port,
377                 const uint8_t queues[], const uint8_t priorities[],
378                 uint16_t nb_links);
379
380 /**
381  * Unlink multiple source event queues from destination event port.
382  *
383  * @param dev
384  *   Event device pointer
385  * @param port
386  *   Event port pointer
387  * @param queues
388  *   An array of *nb_unlinks* event queues to be unlinked from the event port.
389  * @param nb_unlinks
390  *   The number of unlinks to establish
391  *
392  * @return
393  *   Returns 0 on success.
394  *
395  */
396 typedef int (*eventdev_port_unlink_t)(struct rte_eventdev *dev, void *port,
397                 uint8_t queues[], uint16_t nb_unlinks);
398
399 /**
400  * Converts nanoseconds to *timeout_ticks* value for rte_event_dequeue()
401  *
402  * @param dev
403  *   Event device pointer
404  * @param ns
405  *   Wait time in nanosecond
406  * @param[out] timeout_ticks
407  *   Value for the *timeout_ticks* parameter in rte_event_dequeue() function
408  *
409  * @return
410  *   Returns 0 on success.
411  *
412  */
413 typedef int (*eventdev_dequeue_timeout_ticks_t)(struct rte_eventdev *dev,
414                 uint64_t ns, uint64_t *timeout_ticks);
415
416 /**
417  * Dump internal information
418  *
419  * @param dev
420  *   Event device pointer
421  * @param f
422  *   A pointer to a file for output
423  *
424  */
425 typedef void (*eventdev_dump_t)(struct rte_eventdev *dev, FILE *f);
426
427 /**
428  * Retrieve a set of statistics from device
429  *
430  * @param dev
431  *   Event device pointer
432  * @param ids
433  *   The stat ids to retrieve
434  * @param values
435  *   The returned stat values
436  * @param n
437  *   The number of id values and entries in the values array
438  * @return
439  *   The number of stat values successfully filled into the values array
440  */
441 typedef int (*eventdev_xstats_get_t)(const struct rte_eventdev *dev,
442                 enum rte_event_dev_xstats_mode mode, uint8_t queue_port_id,
443                 const unsigned int ids[], uint64_t values[], unsigned int n);
444
445 /**
446  * Resets the statistic values in xstats for the device, based on mode.
447  */
448 typedef int (*eventdev_xstats_reset_t)(struct rte_eventdev *dev,
449                 enum rte_event_dev_xstats_mode mode,
450                 int16_t queue_port_id,
451                 const uint32_t ids[],
452                 uint32_t nb_ids);
453
454 /**
455  * Get names of extended stats of an event device
456  *
457  * @param dev
458  *   Event device pointer
459  * @param xstats_names
460  *   Array of name values to be filled in
461  * @param size
462  *   Number of values in the xstats_names array
463  * @return
464  *   When size >= the number of stats, return the number of stat values filled
465  *   into the array.
466  *   When size < the number of available stats, return the number of stats
467  *   values, and do not fill in any data into xstats_names.
468  */
469 typedef int (*eventdev_xstats_get_names_t)(const struct rte_eventdev *dev,
470                 enum rte_event_dev_xstats_mode mode, uint8_t queue_port_id,
471                 struct rte_event_dev_xstats_name *xstats_names,
472                 unsigned int *ids, unsigned int size);
473
474 /**
475  * Get value of one stats and optionally return its id
476  *
477  * @param dev
478  *   Event device pointer
479  * @param name
480  *   The name of the stat to retrieve
481  * @param id
482  *   Pointer to an unsigned int where we store the stat-id for future reference.
483  *   This pointer may be null if the id is not required.
484  * @return
485  *   The value of the stat, or (uint64_t)-1 if the stat is not found.
486  *   If the stat is not found, the id value will be returned as (unsigned)-1,
487  *   if id pointer is non-NULL
488  */
489 typedef uint64_t (*eventdev_xstats_get_by_name)(const struct rte_eventdev *dev,
490                 const char *name, unsigned int *id);
491
492 /** Event device operations function pointer table */
493 struct rte_eventdev_ops {
494         eventdev_info_get_t dev_infos_get;      /**< Get device info. */
495         eventdev_configure_t dev_configure;     /**< Configure device. */
496         eventdev_start_t dev_start;             /**< Start device. */
497         eventdev_stop_t dev_stop;               /**< Stop device. */
498         eventdev_close_t dev_close;             /**< Close device. */
499
500         eventdev_queue_default_conf_get_t queue_def_conf;
501         /**< Get default queue configuration. */
502         eventdev_queue_setup_t queue_setup;
503         /**< Set up an event queue. */
504         eventdev_queue_release_t queue_release;
505         /**< Release an event queue. */
506
507         eventdev_port_default_conf_get_t port_def_conf;
508         /**< Get default port configuration. */
509         eventdev_port_setup_t port_setup;
510         /**< Set up an event port. */
511         eventdev_port_release_t port_release;
512         /**< Release an event port. */
513
514         eventdev_port_link_t port_link;
515         /**< Link event queues to an event port. */
516         eventdev_port_unlink_t port_unlink;
517         /**< Unlink event queues from an event port. */
518         eventdev_dequeue_timeout_ticks_t timeout_ticks;
519         /**< Converts ns to *timeout_ticks* value for rte_event_dequeue() */
520         eventdev_dump_t dump;
521         /* Dump internal information */
522
523         eventdev_xstats_get_t xstats_get;
524         /**< Get extended device statistics. */
525         eventdev_xstats_get_names_t xstats_get_names;
526         /**< Get names of extended stats. */
527         eventdev_xstats_get_by_name xstats_get_by_name;
528         /**< Get one value by name. */
529         eventdev_xstats_reset_t xstats_reset;
530         /**< Reset the statistics values in xstats. */
531 };
532
533 /**
534  * Allocates a new eventdev slot for an event device and returns the pointer
535  * to that slot for the driver to use.
536  *
537  * @param name
538  *   Unique identifier name for each device
539  * @param socket_id
540  *   Socket to allocate resources on.
541  * @return
542  *   - Slot in the rte_dev_devices array for a new device;
543  */
544 struct rte_eventdev *
545 rte_event_pmd_allocate(const char *name, int socket_id);
546
547 /**
548  * Release the specified eventdev device.
549  *
550  * @param eventdev
551  * The *eventdev* pointer is the address of the *rte_eventdev* structure.
552  * @return
553  *   - 0 on success, negative on error
554  */
555 int
556 rte_event_pmd_release(struct rte_eventdev *eventdev);
557
558 /**
559  * Creates a new virtual event device and returns the pointer to that device.
560  *
561  * @param name
562  *   PMD type name
563  * @param dev_private_size
564  *   Size of event PMDs private data
565  * @param socket_id
566  *   Socket to allocate resources on.
567  *
568  * @return
569  *   - Eventdev pointer if device is successfully created.
570  *   - NULL if device cannot be created.
571  */
572 struct rte_eventdev *
573 rte_event_pmd_vdev_init(const char *name, size_t dev_private_size,
574                 int socket_id);
575
576 /**
577  * Destroy the given virtual event device
578  *
579  * @param name
580  *   PMD type name
581  * @return
582  *   - 0 on success, negative on error
583  */
584 int
585 rte_event_pmd_vdev_uninit(const char *name);
586
587 /**
588  * Wrapper for use by pci drivers as a .probe function to attach to a event
589  * interface.
590  */
591 int rte_event_pmd_pci_probe(struct rte_pci_driver *pci_drv,
592                             struct rte_pci_device *pci_dev);
593
594 /**
595  * Wrapper for use by pci drivers as a .remove function to detach a event
596  * interface.
597  */
598 int rte_event_pmd_pci_remove(struct rte_pci_device *pci_dev);
599
600 #ifdef __cplusplus
601 }
602 #endif
603
604 #endif /* _RTE_EVENTDEV_PMD_H_ */