2 * SPDX-License-Identifier: BSD-3-Clause
3 * Copyright(c) 2010-2014 Intel Corporation
11 * The "opdl_ring" is a data structure that contains a fixed number of slots,
12 * with each slot having the same, but configurable, size. Entries are input
13 * into the opdl_ring by copying into available slots. Once in the opdl_ring,
14 * an entry is processed by a number of stages, with the ordering of stage
15 * processing controlled by making stages dependent on one or more other stages.
16 * An entry is not available for a stage to process until it has been processed
17 * by that stages dependencies. Entries are always made available for
18 * processing in the same order that they were input in to the opdl_ring.
19 * Inputting is considered as a stage that depends on all other stages,
20 * and is also a dependency of all stages.
22 * Inputting and processing in a stage can support multi-threading. Note that
23 * multi-thread processing can also be done by making stages co-operate e.g. two
24 * stages where one processes the even packets and the other processes odd
27 * A opdl_ring can be used as the basis for pipeline based applications. Instead
28 * of each stage in a pipeline dequeueing from a ring, processing and enqueueing
29 * to another ring, it can process entries in-place on the ring. If stages do
30 * not depend on each other, they can run in parallel.
32 * The opdl_ring works with entries of configurable size, these could be
33 * pointers to mbufs, pointers to mbufs with application specific meta-data,
41 #include <rte_eventdev.h>
46 #ifndef OPDL_DISCLAIMS_PER_LCORE
47 /** Multi-threaded processing allows one thread to process multiple batches in a
48 * stage, while another thread is processing a single large batch. This number
49 * controls how many non-contiguous batches one stage can process before being
50 * blocked by the other stage.
52 #define OPDL_DISCLAIMS_PER_LCORE 8
55 /** Opaque handle to a opdl_ring instance */
58 /** Opaque handle to a single stage in a opdl_ring */
62 * Create a new instance of a opdl_ring.
65 * String containing the name to give the new opdl_ring instance.
67 * How many slots the opdl_ring contains. Must be a power a 2!
69 * How many bytes in each slot.
70 * @param max_num_stages
71 * Maximum number of stages.
73 * The NUMA socket (or SOCKET_ID_ANY) to allocate the memory used for this
76 * Whether to support multiple threads inputting to the opdl_ring or not.
77 * Enabling this may have a negative impact on performance if only one thread
81 * A pointer to a new opdl_ring instance, or NULL on error.
84 opdl_ring_create(const char *name, uint32_t num_slots, uint32_t slot_size,
85 uint32_t max_num_stages, int socket);
88 * Get pointer to individual slot in a opdl_ring.
93 * Index of slot. If greater than the number of slots it will be masked to be
94 * within correct range.
97 * A pointer to that slot.
100 opdl_ring_get_slot(const struct opdl_ring *t, uint32_t index);
103 * Get NUMA socket used by a opdl_ring.
112 opdl_ring_get_socket(const struct opdl_ring *t);
115 * Get number of slots in a opdl_ring.
124 opdl_ring_get_num_slots(const struct opdl_ring *t);
127 * Get name of a opdl_ring.
136 opdl_ring_get_name(const struct opdl_ring *t);
139 * Adds a new processing stage to a specified opdl_ring instance. Adding a stage
140 * while there are entries in the opdl_ring being processed will cause undefined
144 * The opdl_ring to add the stage to.
146 * An array of pointers to other stages that this stage depends on. The other
147 * stages must be part of the same opdl_ring! Note that input is an implied
148 * dependency. This can be NULL if num_deps is 0.
150 * The size of the deps array.
152 * Whether to support multiple threads processing this stage or not.
153 * Enabling this may have a negative impact on performance if only one thread
154 * will be processing this stage.
156 * Indication to nitialise the stage with all slots available or none
159 * A pointer to the new stage, or NULL on error.
162 opdl_stage_add(struct opdl_ring *t, bool threadsafe, bool is_input);
165 * Returns the input stage of a opdl_ring to be used by other API functions.
171 * A pointer to the input stage.
174 opdl_ring_get_input_stage(const struct opdl_ring *t);
177 * Sets the dependencies for a stage (clears all the previous deps!). Changing
178 * dependencies while there are entries in the opdl_ring being processed will
179 * cause undefined behaviour.
182 * The stage to set the dependencies for.
184 * An array of pointers to other stages that this stage will depends on. The
185 * other stages must be part of the same opdl_ring!
187 * The size of the deps array. This must be > 0.
190 * 0 on success, a negative value on error.
193 opdl_stage_set_deps(struct opdl_stage *s, struct opdl_stage *deps[],
197 * Returns the opdl_ring that a stage belongs to.
203 * A pointer to the opdl_ring that the stage belongs to.
206 opdl_stage_get_opdl_ring(const struct opdl_stage *s);
209 * Inputs a new batch of entries into the opdl_ring. This function is only
210 * threadsafe (with the same opdl_ring parameter) if the threadsafe parameter of
211 * opdl_ring_create() was true. For performance reasons, this function does not
212 * check input parameters.
215 * The opdl_ring to input entries in to.
217 * An array of entries that will be copied in to the opdl_ring.
219 * The size of the entries array.
221 * If this is true, the function blocks until enough slots are available to
222 * input all the requested entries. If false, then the function inputs as
223 * many entries as currently possible.
226 * The number of entries successfully input.
229 opdl_ring_input(struct opdl_ring *t, const void *entries, uint32_t num_entries,
233 * Inputs a new batch of entries into a opdl stage. This function is only
234 * threadsafe (with the same opdl parameter) if the threadsafe parameter of
235 * opdl_create() was true. For performance reasons, this function does not
236 * check input parameters.
239 * The opdl ring to input entries in to.
241 * The stage to copy entries to.
243 * An array of entries that will be copied in to the opdl ring.
245 * The size of the entries array.
247 * If this is true, the function blocks until enough slots are available to
248 * input all the requested entries. If false, then the function inputs as
249 * many entries as currently possible.
252 * The number of entries successfully input.
255 opdl_ring_copy_from_burst(struct opdl_ring *t, struct opdl_stage *s,
256 const void *entries, uint32_t num_entries, bool block);
259 * Copy a batch of entries from the opdl ring. This function is only
260 * threadsafe (with the same opdl parameter) if the threadsafe parameter of
261 * opdl_create() was true. For performance reasons, this function does not
262 * check input parameters.
265 * The opdl ring to copy entries from.
267 * The stage to copy entries from.
269 * An array of entries that will be copied from the opdl ring.
271 * The size of the entries array.
273 * If this is true, the function blocks until enough slots are available to
274 * input all the requested entries. If false, then the function inputs as
275 * many entries as currently possible.
278 * The number of entries successfully input.
281 opdl_ring_copy_to_burst(struct opdl_ring *t, struct opdl_stage *s,
282 void *entries, uint32_t num_entries, bool block);
285 * Before processing a batch of entries, a stage must first claim them to get
286 * access. This function is threadsafe using same opdl_stage parameter if
287 * the stage was created with threadsafe set to true, otherwise it is only
288 * threadsafe with a different opdl_stage per thread. For performance
289 * reasons, this function does not check input parameters.
292 * The opdl_ring stage to read entries in.
294 * An array of pointers to entries that will be filled in by this function.
296 * The number of entries to attempt to claim for processing (and the size of
297 * the entries array).
299 * If not NULL, this is set to the value of the internal stage sequence number
300 * associated with the first entry returned.
302 * If this is true, the function blocks until num_entries slots are available
303 * to process. If false, then the function claims as many entries as
304 * currently possible.
307 * if this is true, the function will return event according to event flow id
309 * The number of pointers to entries filled in to the entries array.
312 opdl_stage_claim(struct opdl_stage *s, void *entries,
313 uint32_t num_entries, uint32_t *seq, bool block, bool atomic);
316 opdl_stage_deps_add(struct opdl_ring *t, struct opdl_stage *s,
317 uint32_t nb_instance, uint32_t instance_id,
318 struct opdl_stage *deps[], uint32_t num_deps);
321 * A function to check how many entries are ready to be claimed.
324 * An array of pointers to entries.
326 * Number of entries in an array.
328 * An opaque pointer to data passed to the claim function.
330 * When set to true, the function should wait until num_entries are ready to
331 * be processed. Otherwise it should return immediately.
334 * Number of entries ready to be claimed.
336 typedef uint32_t (opdl_ring_check_entries_t)(void *entries[],
337 uint32_t num_entries, void *arg, bool block);
340 * Before processing a batch of entries, a stage must first claim them to get
341 * access. Each entry is checked by the passed check() function and depending
342 * on block value, it waits until num_entries are ready or returns immediately.
343 * This function is only threadsafe with a different opdl_stage per thread.
346 * The opdl_ring stage to read entries in.
348 * An array of pointers to entries that will be filled in by this function.
350 * The number of entries to attempt to claim for processing (and the size of
351 * the entries array).
353 * If not NULL, this is set to the value of the internal stage sequence number
354 * associated with the first entry returned.
356 * If this is true, the function blocks until num_entries ready slots are
357 * available to process. If false, then the function claims as many ready
358 * entries as currently possible.
360 * Pointer to a function called to check entries.
362 * Opaque data passed to check() function.
365 * The number of pointers to ready entries filled in to the entries array.
368 opdl_stage_claim_check(struct opdl_stage *s, void **entries,
369 uint32_t num_entries, uint32_t *seq, bool block,
370 opdl_ring_check_entries_t *check, void *arg);
373 * Before processing a batch of entries, a stage must first claim them to get
374 * access. This function is threadsafe using same opdl_stage parameter if
375 * the stage was created with threadsafe set to true, otherwise it is only
376 * threadsafe with a different opdl_stage per thread.
378 * The difference between this function and opdl_stage_claim() is that this
379 * function copies the entries from the opdl_ring. Note that any changes made to
380 * the copied entries will not be reflected back in to the entries in the
381 * opdl_ring, so this function probably only makes sense if the entries are
382 * pointers to other data. For performance reasons, this function does not check
386 * The opdl_ring stage to read entries in.
388 * An array of entries that will be filled in by this function.
390 * The number of entries to attempt to claim for processing (and the size of
391 * the entries array).
393 * If not NULL, this is set to the value of the internal stage sequence number
394 * associated with the first entry returned.
396 * If this is true, the function blocks until num_entries slots are available
397 * to process. If false, then the function claims as many entries as
398 * currently possible.
401 * The number of entries copied in to the entries array.
404 opdl_stage_claim_copy(struct opdl_stage *s, void *entries,
405 uint32_t num_entries, uint32_t *seq, bool block);
408 * This function must be called when a stage has finished its processing of
409 * entries, to make them available to any dependent stages. All entries that are
410 * claimed by the calling thread in the stage will be disclaimed. It is possible
411 * to claim multiple batches before disclaiming. For performance reasons, this
412 * function does not check input parameters.
415 * The opdl_ring stage in which to disclaim all claimed entries.
418 * Entries are always made available to a stage in the same order that they
419 * were input in the stage. If a stage is multithread safe, this may mean that
420 * full disclaiming of a batch of entries can not be considered complete until
421 * all earlier threads in the stage have disclaimed. If this parameter is true
422 * then the function blocks until all entries are fully disclaimed, otherwise
423 * it disclaims as many as currently possible, with non fully disclaimed
424 * batches stored until the next call to a claim or disclaim function for this
425 * stage on this thread.
427 * If a thread is not going to process any more entries in this stage, it
428 * *must* first call this function with this parameter set to true to ensure
429 * it does not block the entire opdl_ring.
431 * In a single threaded stage, this parameter has no effect.
434 opdl_stage_disclaim(struct opdl_stage *s, uint32_t num_entries,
438 * This function can be called when a stage has finished its processing of
439 * entries, to make them available to any dependent stages. The difference
440 * between this function and opdl_stage_disclaim() is that here only a
441 * portion of entries are disclaimed, not all of them. For performance reasons,
442 * this function does not check input parameters.
445 * The opdl_ring stage in which to disclaim entries.
448 * The number of entries to disclaim.
451 * Entries are always made available to a stage in the same order that they
452 * were input in the stage. If a stage is multithread safe, this may mean that
453 * full disclaiming of a batch of entries can not be considered complete until
454 * all earlier threads in the stage have disclaimed. If this parameter is true
455 * then the function blocks until the specified number of entries has been
456 * disclaimed (or there are no more entries to disclaim). Otherwise it
457 * disclaims as many claims as currently possible and an attempt to disclaim
458 * them is made the next time a claim or disclaim function for this stage on
459 * this thread is called.
461 * In a single threaded stage, this parameter has no effect.
464 opdl_stage_disclaim_n(struct opdl_stage *s, uint32_t num_entries,
468 * Check how many entries can be input.
471 * The opdl_ring instance to check.
474 * The number of new entries currently allowed to be input.
477 opdl_ring_available(struct opdl_ring *t);
480 * Check how many entries can be processed in a stage.
483 * The stage to check.
486 * The number of entries currently available to be processed in this stage.
489 opdl_stage_available(struct opdl_stage *s);
492 * Check how many entries are available to be processed.
494 * NOTE : DOES NOT CHANGE ANY STATE WITHIN THE STAGE
497 * The stage to check.
500 * The number of entries to check for availability.
503 * The number of entries currently available to be processed in this stage.
506 opdl_stage_find_num_available(struct opdl_stage *s, uint32_t num_entries);
509 * Create empty stage instance and return the pointer.
512 * The pointer of opdl_ring.
515 * enable multiple thread or not.
517 * The pointer of one empty stage instance.
520 opdl_stage_create(struct opdl_ring *t, bool threadsafe);
523 * Prints information on opdl_ring instance and all its stages
526 * The stage to print info on.
528 * Where to print the info.
531 opdl_ring_dump(const struct opdl_ring *t, FILE *f);
534 * Blocks until all entries in a opdl_ring have been processed by all stages.
537 * The opdl_ring instance to flush.
540 opdl_ring_flush(struct opdl_ring *t);
543 * Deallocates all resources used by a opdl_ring instance
546 * The opdl_ring instance to free.
549 opdl_ring_free(struct opdl_ring *t);
552 * Search for a opdl_ring by its name
555 * The name of the opdl_ring.
557 * The pointer to the opdl_ring matching the name, or NULL if not found.
561 opdl_ring_lookup(const char *name);
564 * Set a opdl_stage to threadsafe variable.
572 opdl_ring_set_stage_threadsafe(struct opdl_stage *s, bool threadsafe);
576 * Compare the event descriptor with original version in the ring.
577 * if key field event descriptor is changed by application, then
578 * update the slot in the ring otherwise do nothing with it.
579 * the key field is flow_id, prioirty, mbuf, impl_opaque
584 * pointer of the event descriptor.
586 * index of the event descriptor.
588 * queue type associate with the stage.
590 * if the evevnt key field is changed compare with previous record.
594 opdl_ring_cas_slot(const struct opdl_stage *s, const struct rte_event *ev,
595 uint32_t index, bool atomic);
601 #endif /* _OPDL_H_ */