net/mlx4: fix RxQ errors stat
[dpdk.git] / drivers / event / opdl / opdl_ring.h
1 /* SPDX-License-Identifier: BSD-3-Clause
2  * Copyright(c) 2017 Intel Corporation
3  */
4
5 #ifndef _OPDL_H_
6 #define _OPDL_H_
7
8 /**
9  * @file
10  * The "opdl_ring" is a data structure that contains a fixed number of slots,
11  * with each slot having the same, but configurable, size. Entries are input
12  * into the opdl_ring by copying into available slots. Once in the opdl_ring,
13  * an entry is processed by a number of stages, with the ordering of stage
14  * processing controlled by making stages dependent on one or more other stages.
15  * An entry is not available for a stage to process until it has been processed
16  * by that stages dependencies. Entries are always made available for
17  * processing in the same order that they were input in to the opdl_ring.
18  * Inputting is considered as a stage that depends on all other stages,
19  * and is also a dependency of all stages.
20  *
21  * Inputting and processing in a stage can support multi-threading. Note that
22  * multi-thread processing can also be done by making stages co-operate e.g. two
23  * stages where one processes the even packets and the other processes odd
24  * packets.
25  *
26  * A opdl_ring can be used as the basis for pipeline based applications. Instead
27  * of each stage in a pipeline dequeuing from a ring, processing and enqueuing
28  * to another ring, it can process entries in-place on the ring. If stages do
29  * not depend on each other, they can run in parallel.
30  *
31  * The opdl_ring works with entries of configurable size, these could be
32  * pointers to mbufs, pointers to mbufs with application specific meta-data,
33  * tasks etc.
34  */
35
36 #include <stdbool.h>
37 #include <stdint.h>
38 #include <stdio.h>
39
40 #include <rte_eventdev.h>
41 #ifdef __cplusplus
42 extern "C" {
43 #endif
44
45 #ifndef OPDL_DISCLAIMS_PER_LCORE
46 /** Multi-threaded processing allows one thread to process multiple batches in a
47  * stage, while another thread is processing a single large batch. This number
48  * controls how many non-contiguous batches one stage can process before being
49  * blocked by the other stage.
50  */
51 #define OPDL_DISCLAIMS_PER_LCORE 8
52 #endif
53
54 /** Opaque handle to a opdl_ring instance */
55 struct opdl_ring;
56
57 /** Opaque handle to a single stage in a opdl_ring */
58 struct opdl_stage;
59
60 /**
61  * Create a new instance of a opdl_ring.
62  *
63  * @param name
64  *   String containing the name to give the new opdl_ring instance.
65  * @param num_slots
66  *   How many slots the opdl_ring contains. Must be a power a 2!
67  * @param slot_size
68  *   How many bytes in each slot.
69  * @param max_num_stages
70  *   Maximum number of stages.
71  * @param socket
72  *   The NUMA socket (or SOCKET_ID_ANY) to allocate the memory used for this
73  *   opdl_ring instance.
74  * @param threadsafe
75  *   Whether to support multiple threads inputting to the opdl_ring or not.
76  *   Enabling this may have a negative impact on performance if only one thread
77  *   will be inputting.
78  *
79  * @return
80  *   A pointer to a new opdl_ring instance, or NULL on error.
81  */
82 struct opdl_ring *
83 opdl_ring_create(const char *name, uint32_t num_slots, uint32_t slot_size,
84                 uint32_t max_num_stages, int socket);
85
86 /**
87  * Get pointer to individual slot in a opdl_ring.
88  *
89  * @param t
90  *   The opdl_ring.
91  * @param index
92  *   Index of slot. If greater than the number of slots it will be masked to be
93  *   within correct range.
94  *
95  * @return
96  *   A pointer to that slot.
97  */
98 void *
99 opdl_ring_get_slot(const struct opdl_ring *t, uint32_t index);
100
101 /**
102  * Get NUMA socket used by a opdl_ring.
103  *
104  * @param t
105  *   The opdl_ring.
106  *
107  * @return
108  *   NUMA socket.
109  */
110 int
111 opdl_ring_get_socket(const struct opdl_ring *t);
112
113 /**
114  * Get number of slots in a opdl_ring.
115  *
116  * @param t
117  *   The opdl_ring.
118  *
119  * @return
120  *   Number of slots.
121  */
122 uint32_t
123 opdl_ring_get_num_slots(const struct opdl_ring *t);
124
125 /**
126  * Get name of a opdl_ring.
127  *
128  * @param t
129  *   The opdl_ring.
130  *
131  * @return
132  *   Name string.
133  */
134 const char *
135 opdl_ring_get_name(const struct opdl_ring *t);
136
137 /**
138  * Adds a new processing stage to a specified opdl_ring instance. Adding a stage
139  * while there are entries in the opdl_ring being processed will cause undefined
140  * behaviour.
141  *
142  * @param t
143  *   The opdl_ring to add the stage to.
144  * @param deps
145  *   An array of pointers to other stages that this stage depends on. The other
146  *   stages must be part of the same opdl_ring! Note that input is an implied
147  *   dependency. This can be NULL if num_deps is 0.
148  * @param num_deps
149  *   The size of the deps array.
150  * @param threadsafe
151  *   Whether to support multiple threads processing this stage or  not.
152  *   Enabling this may have a negative impact on performance if only one thread
153  *   will be processing this stage.
154  * @param is_input
155  *   Indication to initialise the stage with all slots available or none
156  *
157  * @return
158  *   A pointer to the new stage, or NULL on error.
159  */
160 struct opdl_stage *
161 opdl_stage_add(struct opdl_ring *t, bool threadsafe, bool is_input);
162
163 /**
164  * Returns the input stage of a opdl_ring to be used by other API functions.
165  *
166  * @param t
167  *   The opdl_ring.
168  *
169  * @return
170  *   A pointer to the input stage.
171  */
172 struct opdl_stage *
173 opdl_ring_get_input_stage(const struct opdl_ring *t);
174
175 /**
176  * Sets the dependencies for a stage (clears all the previous deps!). Changing
177  * dependencies while there are entries in the opdl_ring being processed will
178  * cause undefined behaviour.
179  *
180  * @param s
181  *   The stage to set the dependencies for.
182  * @param deps
183  *   An array of pointers to other stages that this stage will depends on. The
184  *   other stages must be part of the same opdl_ring!
185  * @param num_deps
186  *   The size of the deps array. This must be > 0.
187  *
188  * @return
189  *   0 on success, a negative value on error.
190  */
191 int
192 opdl_stage_set_deps(struct opdl_stage *s, struct opdl_stage *deps[],
193                 uint32_t num_deps);
194
195 /**
196  * Returns the opdl_ring that a stage belongs to.
197  *
198  * @param s
199  *   The stage
200  *
201  * @return
202  *   A pointer to the opdl_ring that the stage belongs to.
203  */
204 struct opdl_ring *
205 opdl_stage_get_opdl_ring(const struct opdl_stage *s);
206
207 /**
208  * Inputs a new batch of entries into the opdl_ring. This function is only
209  * threadsafe (with the same opdl_ring parameter) if the threadsafe parameter of
210  * opdl_ring_create() was true. For performance reasons, this function does not
211  * check input parameters.
212  *
213  * @param t
214  *   The opdl_ring to input entries in to.
215  * @param entries
216  *   An array of entries that will be copied in to the opdl_ring.
217  * @param num_entries
218  *   The size of the entries array.
219  * @param block
220  *   If this is true, the function blocks until enough slots are available to
221  *   input all the requested entries. If false, then the function inputs as
222  *   many entries as currently possible.
223  *
224  * @return
225  *   The number of entries successfully input.
226  */
227 uint32_t
228 opdl_ring_input(struct opdl_ring *t, const void *entries, uint32_t num_entries,
229                 bool block);
230
231 /**
232  * Inputs a new batch of entries into a opdl stage. This function is only
233  * threadsafe (with the same opdl parameter) if the threadsafe parameter of
234  * opdl_create() was true. For performance reasons, this function does not
235  * check input parameters.
236  *
237  * @param t
238  *   The opdl ring to input entries in to.
239  * @param s
240  *   The stage to copy entries to.
241  * @param entries
242  *   An array of entries that will be copied in to the opdl ring.
243  * @param num_entries
244  *   The size of the entries array.
245  * @param block
246  *   If this is true, the function blocks until enough slots are available to
247  *   input all the requested entries. If false, then the function inputs as
248  *   many entries as currently possible.
249  *
250  * @return
251  *   The number of entries successfully input.
252  */
253 uint32_t
254 opdl_ring_copy_from_burst(struct opdl_ring *t, struct opdl_stage *s,
255                         const void *entries, uint32_t num_entries, bool block);
256
257 /**
258  * Copy a batch of entries from the opdl ring. This function is only
259  * threadsafe (with the same opdl parameter) if the threadsafe parameter of
260  * opdl_create() was true. For performance reasons, this function does not
261  * check input parameters.
262  *
263  * @param t
264  *   The opdl ring to copy entries from.
265  * @param s
266  *   The stage to copy entries from.
267  * @param entries
268  *   An array of entries that will be copied from the opdl ring.
269  * @param num_entries
270  *   The size of the entries array.
271  * @param block
272  *   If this is true, the function blocks until enough slots are available to
273  *   input all the requested entries. If false, then the function inputs as
274  *   many entries as currently possible.
275  *
276  * @return
277  *   The number of entries successfully input.
278  */
279 uint32_t
280 opdl_ring_copy_to_burst(struct opdl_ring *t, struct opdl_stage *s,
281                 void *entries, uint32_t num_entries, bool block);
282
283 /**
284  * Before processing a batch of entries, a stage must first claim them to get
285  * access. This function is threadsafe using same opdl_stage parameter if
286  * the stage was created with threadsafe set to true, otherwise it is only
287  * threadsafe with a different opdl_stage per thread. For performance
288  * reasons, this function does not check input parameters.
289  *
290  * @param s
291  *   The opdl_ring stage to read entries in.
292  * @param entries
293  *   An array of pointers to entries that will be filled in by this function.
294  * @param num_entries
295  *   The number of entries to attempt to claim for processing (and the size of
296  *   the entries array).
297  * @param seq
298  *   If not NULL, this is set to the value of the internal stage sequence number
299  *   associated with the first entry returned.
300  * @param block
301  *   If this is true, the function blocks until num_entries slots are available
302  *   to process. If false, then the function claims as many entries as
303  *   currently possible.
304  *
305  * @param atomic
306  *   if this is true, the function will return event according to event flow id
307  * @return
308  *   The number of pointers to entries filled in to the entries array.
309  */
310 uint32_t
311 opdl_stage_claim(struct opdl_stage *s, void *entries,
312                 uint32_t num_entries, uint32_t *seq, bool block, bool atomic);
313
314 uint32_t
315 opdl_stage_deps_add(struct opdl_ring *t, struct opdl_stage *s,
316                 uint32_t nb_instance, uint32_t instance_id,
317                 struct opdl_stage *deps[], uint32_t num_deps);
318
319 /**
320  * A function to check how many entries are ready to be claimed.
321  *
322  * @param entries
323  *   An array of pointers to entries.
324  * @param num_entries
325  *   Number of entries in an array.
326  * @param arg
327  *   An opaque pointer to data passed to the claim function.
328  * @param block
329  *   When set to true, the function should wait until num_entries are ready to
330  *   be processed. Otherwise it should return immediately.
331  *
332  * @return
333  *   Number of entries ready to be claimed.
334  */
335 typedef uint32_t (opdl_ring_check_entries_t)(void *entries[],
336                 uint32_t num_entries, void *arg, bool block);
337
338 /**
339  * Before processing a batch of entries, a stage must first claim them to get
340  * access. Each entry is checked by the passed check() function and depending
341  * on block value, it waits until num_entries are ready or returns immediately.
342  * This function is only threadsafe with a different opdl_stage per thread.
343  *
344  * @param s
345  *   The opdl_ring stage to read entries in.
346  * @param entries
347  *   An array of pointers to entries that will be filled in by this function.
348  * @param num_entries
349  *   The number of entries to attempt to claim for processing (and the size of
350  *   the entries array).
351  * @param seq
352  *   If not NULL, this is set to the value of the internal stage sequence number
353  *   associated with the first entry returned.
354  * @param block
355  *   If this is true, the function blocks until num_entries ready slots are
356  *   available to process. If false, then the function claims as many ready
357  *   entries as currently possible.
358  * @param check
359  *   Pointer to a function called to check entries.
360  * @param arg
361  *   Opaque data passed to check() function.
362  *
363  * @return
364  *   The number of pointers to ready entries filled in to the entries array.
365  */
366 uint32_t
367 opdl_stage_claim_check(struct opdl_stage *s, void **entries,
368                 uint32_t num_entries, uint32_t *seq, bool block,
369                 opdl_ring_check_entries_t *check, void *arg);
370
371 /**
372  * Before processing a batch of entries, a stage must first claim them to get
373  * access. This function is threadsafe using same opdl_stage parameter if
374  * the stage was created with threadsafe set to true, otherwise it is only
375  * threadsafe with a different opdl_stage per thread.
376  *
377  * The difference between this function and opdl_stage_claim() is that this
378  * function copies the entries from the opdl_ring. Note that any changes made to
379  * the copied entries will not be reflected back in to the entries in the
380  * opdl_ring, so this function probably only makes sense if the entries are
381  * pointers to other data. For performance reasons, this function does not check
382  * input parameters.
383  *
384  * @param s
385  *   The opdl_ring stage to read entries in.
386  * @param entries
387  *   An array of entries that will be filled in by this function.
388  * @param num_entries
389  *   The number of entries to attempt to claim for processing (and the size of
390  *   the entries array).
391  * @param seq
392  *   If not NULL, this is set to the value of the internal stage sequence number
393  *   associated with the first entry returned.
394  * @param block
395  *   If this is true, the function blocks until num_entries slots are available
396  *   to process. If false, then the function claims as many entries as
397  *   currently possible.
398  *
399  * @return
400  *   The number of entries copied in to the entries array.
401  */
402 uint32_t
403 opdl_stage_claim_copy(struct opdl_stage *s, void *entries,
404                 uint32_t num_entries, uint32_t *seq, bool block);
405
406 /**
407  * This function must be called when a stage has finished its processing of
408  * entries, to make them available to any dependent stages. All entries that are
409  * claimed by the calling thread in the stage will be disclaimed. It is possible
410  * to claim multiple batches before disclaiming. For performance reasons, this
411  * function does not check input parameters.
412  *
413  * @param s
414  *   The opdl_ring stage in which to disclaim all claimed entries.
415  *
416  * @param block
417  *   Entries are always made available to a stage in the same order that they
418  *   were input in the stage. If a stage is multithread safe, this may mean that
419  *   full disclaiming of a batch of entries can not be considered complete until
420  *   all earlier threads in the stage have disclaimed. If this parameter is true
421  *   then the function blocks until all entries are fully disclaimed, otherwise
422  *   it disclaims as many as currently possible, with non fully disclaimed
423  *   batches stored until the next call to a claim or disclaim function for this
424  *   stage on this thread.
425  *
426  *   If a thread is not going to process any more entries in this stage, it
427  *   *must* first call this function with this parameter set to true to ensure
428  *   it does not block the entire opdl_ring.
429  *
430  *   In a single threaded stage, this parameter has no effect.
431  */
432 int
433 opdl_stage_disclaim(struct opdl_stage *s, uint32_t num_entries,
434                 bool block);
435
436 /**
437  * This function can be called when a stage has finished its processing of
438  * entries, to make them available to any dependent stages. The difference
439  * between this function and opdl_stage_disclaim() is that here only a
440  * portion of entries are disclaimed, not all of them. For performance reasons,
441  * this function does not check input parameters.
442  *
443  * @param s
444  *   The opdl_ring stage in which to disclaim entries.
445  *
446  * @param num_entries
447  *   The number of entries to disclaim.
448  *
449  * @param block
450  *   Entries are always made available to a stage in the same order that they
451  *   were input in the stage. If a stage is multithread safe, this may mean that
452  *   full disclaiming of a batch of entries can not be considered complete until
453  *   all earlier threads in the stage have disclaimed. If this parameter is true
454  *   then the function blocks until the specified number of entries has been
455  *   disclaimed (or there are no more entries to disclaim). Otherwise it
456  *   disclaims as many claims as currently possible and an attempt to disclaim
457  *   them is made the next time a claim or disclaim function for this stage on
458  *   this thread is called.
459  *
460  *   In a single threaded stage, this parameter has no effect.
461  */
462 void
463 opdl_stage_disclaim_n(struct opdl_stage *s, uint32_t num_entries,
464                 bool block);
465
466 /**
467  * Check how many entries can be input.
468  *
469  * @param t
470  *   The opdl_ring instance to check.
471  *
472  * @return
473  *   The number of new entries currently allowed to be input.
474  */
475 uint32_t
476 opdl_ring_available(struct opdl_ring *t);
477
478 /**
479  * Check how many entries can be processed in a stage.
480  *
481  * @param s
482  *   The stage to check.
483  *
484  * @return
485  *   The number of entries currently available to be processed in this stage.
486  */
487 uint32_t
488 opdl_stage_available(struct opdl_stage *s);
489
490 /**
491  * Check how many entries are available to be processed.
492  *
493  * NOTE : DOES NOT CHANGE ANY STATE WITHIN THE STAGE
494  *
495  * @param s
496  *   The stage to check.
497  *
498  * @param num_entries
499  *   The number of entries to check for availability.
500  *
501  * @return
502  *   The number of entries currently available to be processed in this stage.
503  */
504 uint32_t
505 opdl_stage_find_num_available(struct opdl_stage *s, uint32_t num_entries);
506
507 /**
508  * Create empty stage instance and return the pointer.
509  *
510  * @param t
511  *   The pointer of  opdl_ring.
512  *
513  * @param threadsafe
514  *    enable multiple thread or not.
515  * @return
516  *   The pointer of one empty stage instance.
517  */
518 struct opdl_stage *
519 opdl_stage_create(struct opdl_ring *t,  bool threadsafe);
520
521
522 /**
523  * Set the internal queue id for each stage instance.
524  *
525  * @param s
526  *   The pointer of  stage instance.
527  *
528  * @param queue_id
529  *    The value of internal queue id.
530  */
531 void
532 opdl_stage_set_queue_id(struct opdl_stage *s,
533                 uint32_t queue_id);
534
535 /**
536  * Prints information on opdl_ring instance and all its stages
537  *
538  * @param t
539  *   The stage to print info on.
540  * @param f
541  *   Where to print the info.
542  */
543 void
544 opdl_ring_dump(const struct opdl_ring *t, FILE *f);
545
546 /**
547  * Blocks until all entries in a opdl_ring have been processed by all stages.
548  *
549  * @param t
550  *   The opdl_ring instance to flush.
551  */
552 void
553 opdl_ring_flush(struct opdl_ring *t);
554
555 /**
556  * Deallocates all resources used by a opdl_ring instance
557  *
558  * @param t
559  *   The opdl_ring instance to free.
560  */
561 void
562 opdl_ring_free(struct opdl_ring *t);
563
564 /**
565  * Search for a opdl_ring by its name
566  *
567  * @param name
568  *   The name of the opdl_ring.
569  * @return
570  *   The pointer to the opdl_ring matching the name, or NULL if not found.
571  *
572  */
573 struct opdl_ring *
574 opdl_ring_lookup(const char *name);
575
576 /**
577  * Set a opdl_stage to threadsafe variable.
578  *
579  * @param s
580  *   The opdl_stage.
581  * @param threadsafe
582  *   Threadsafe value.
583  */
584 void
585 opdl_ring_set_stage_threadsafe(struct opdl_stage *s, bool threadsafe);
586
587
588 /**
589  * Compare the event descriptor with original version in the ring.
590  * if key field event descriptor is changed by application, then
591  * update the slot in the ring otherwise do nothing with it.
592  * the key field is flow_id, priority, mbuf, impl_opaque
593  *
594  * @param s
595  *   The opdl_stage.
596  * @param ev
597  *   pointer of the event descriptor.
598  * @param index
599  *   index of the event descriptor.
600  * @param atomic
601  *   queue type associate with the stage.
602  * @return
603  *   if the event key field is changed compare with previous record.
604  */
605
606 bool
607 opdl_ring_cas_slot(struct opdl_stage *s, const struct rte_event *ev,
608                 uint32_t index, bool atomic);
609
610 #ifdef __cplusplus
611 }
612 #endif
613
614 #endif  /* _OPDL_H_ */