drivers/event/opdl/opdl_ring.h

   1 /*-
   2  * SPDX-License-Identifier: BSD-3-Clause
   3  * Copyright(c) 2010-2014 Intel Corporation
   4  */
   5
   6 #ifndef _OPDL_H_
   7 #define _OPDL_H_
   8
   9 /**
  10  * @file
  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.
  21  *
  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
  25  * packets.
  26  *
  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.
  31  *
  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,
  34  * tasks etc.
  35  */
  36
  37 #include <stdbool.h>
  38 #include <stdint.h>
  39 #include <stdio.h>
  40
  41 #include <rte_eventdev.h>
  42 #ifdef __cplusplus
  43 extern "C" {
  44 #endif
  45
  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.
  51  */
  52 #define OPDL_DISCLAIMS_PER_LCORE 8
  53 #endif
  54
  55 /** Opaque handle to a opdl_ring instance */
  56 struct opdl_ring;
  57
  58 /** Opaque handle to a single stage in a opdl_ring */
  59 struct opdl_stage;
  60
  61 /**
  62  * Create a new instance of a opdl_ring.
  63  *
  64  * @param name
  65  *   String containing the name to give the new opdl_ring instance.
  66  * @param num_slots
  67  *   How many slots the opdl_ring contains. Must be a power a 2!
  68  * @param slot_size
  69  *   How many bytes in each slot.
  70  * @param max_num_stages
  71  *   Maximum number of stages.
  72  * @param socket
  73  *   The NUMA socket (or SOCKET_ID_ANY) to allocate the memory used for this
  74  *   opdl_ring instance.
  75  * @param threadsafe
  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
  78  *   will be inputting.
  79  *
  80  * @return
  81  *   A pointer to a new opdl_ring instance, or NULL on error.
  82  */
  83 struct opdl_ring *
  84 opdl_ring_create(const char *name, uint32_t num_slots, uint32_t slot_size,
  85                 uint32_t max_num_stages, int socket);
  86
  87 /**
  88  * Get pointer to individual slot in a opdl_ring.
  89  *
  90  * @param t
  91  *   The opdl_ring.
  92  * @param index
  93  *   Index of slot. If greater than the number of slots it will be masked to be
  94  *   within correct range.
  95  *
  96  * @return
  97  *   A pointer to that slot.
  98  */
  99 void *
 100 opdl_ring_get_slot(const struct opdl_ring *t, uint32_t index);
 101
 102 /**
 103  * Get NUMA socket used by a opdl_ring.
 104  *
 105  * @param t
 106  *   The opdl_ring.
 107  *
 108  * @return
 109  *   NUMA socket.
 110  */
 111 int
 112 opdl_ring_get_socket(const struct opdl_ring *t);
 113
 114 /**
 115  * Get number of slots in a opdl_ring.
 116  *
 117  * @param t
 118  *   The opdl_ring.
 119  *
 120  * @return
 121  *   Number of slots.
 122  */
 123 uint32_t
 124 opdl_ring_get_num_slots(const struct opdl_ring *t);
 125
 126 /**
 127  * Get name of a opdl_ring.
 128  *
 129  * @param t
 130  *   The opdl_ring.
 131  *
 132  * @return
 133  *   Name string.
 134  */
 135 const char *
 136 opdl_ring_get_name(const struct opdl_ring *t);
 137
 138 /**
 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
 141  * behaviour.
 142  *
 143  * @param t
 144  *   The opdl_ring to add the stage to.
 145  * @param deps
 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.
 149  * @param num_deps
 150  *   The size of the deps array.
 151  * @param threadsafe
 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.
 155  * @param is_input
 156  *   Indication to nitialise the stage with all slots available or none
 157  *
 158  * @return
 159  *   A pointer to the new stage, or NULL on error.
 160  */
 161 struct opdl_stage *
 162 opdl_stage_add(struct opdl_ring *t, bool threadsafe, bool is_input);
 163
 164 /**
 165  * Returns the input stage of a opdl_ring to be used by other API functions.
 166  *
 167  * @param t
 168  *   The opdl_ring.
 169  *
 170  * @return
 171  *   A pointer to the input stage.
 172  */
 173 struct opdl_stage *
 174 opdl_ring_get_input_stage(const struct opdl_ring *t);
 175
 176 /**
 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.
 180  *
 181  * @param s
 182  *   The stage to set the dependencies for.
 183  * @param deps
 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!
 186  * @param num_deps
 187  *   The size of the deps array. This must be > 0.
 188  *
 189  * @return
 190  *   0 on success, a negative value on error.
 191  */
 192 int
 193 opdl_stage_set_deps(struct opdl_stage *s, struct opdl_stage *deps[],
 194                 uint32_t num_deps);
 195
 196 /**
 197  * Returns the opdl_ring that a stage belongs to.
 198  *
 199  * @param s
 200  *   The stage
 201  *
 202  * @return
 203  *   A pointer to the opdl_ring that the stage belongs to.
 204  */
 205 struct opdl_ring *
 206 opdl_stage_get_opdl_ring(const struct opdl_stage *s);
 207
 208 /**
 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.
 213  *
 214  * @param t
 215  *   The opdl_ring to input entries in to.
 216  * @param entries
 217  *   An array of entries that will be copied in to the opdl_ring.
 218  * @param num_entries
 219  *   The size of the entries array.
 220  * @param block
 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.
 224  *
 225  * @return
 226  *   The number of entries successfully input.
 227  */
 228 uint32_t
 229 opdl_ring_input(struct opdl_ring *t, const void *entries, uint32_t num_entries,
 230                 bool block);
 231
 232 /**
 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.
 237  *
 238  * @param t
 239  *   The opdl ring to input entries in to.
 240  * @param s
 241  *   The stage to copy entries to.
 242  * @param entries
 243  *   An array of entries that will be copied in to the opdl ring.
 244  * @param num_entries
 245  *   The size of the entries array.
 246  * @param block
 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.
 250  *
 251  * @return
 252  *   The number of entries successfully input.
 253  */
 254 uint32_t
 255 opdl_ring_copy_from_burst(struct opdl_ring *t, struct opdl_stage *s,
 256                         const void *entries, uint32_t num_entries, bool block);
 257
 258 /**
 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.
 263  *
 264  * @param t
 265  *   The opdl ring to copy entries from.
 266  * @param s
 267  *   The stage to copy entries from.
 268  * @param entries
 269  *   An array of entries that will be copied from the opdl ring.
 270  * @param num_entries
 271  *   The size of the entries array.
 272  * @param block
 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.
 276  *
 277  * @return
 278  *   The number of entries successfully input.
 279  */
 280 uint32_t
 281 opdl_ring_copy_to_burst(struct opdl_ring *t, struct opdl_stage *s,
 282                 void *entries, uint32_t num_entries, bool block);
 283
 284 /**
 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.
 290  *
 291  * @param s
 292  *   The opdl_ring stage to read entries in.
 293  * @param entries
 294  *   An array of pointers to entries that will be filled in by this function.
 295  * @param num_entries
 296  *   The number of entries to attempt to claim for processing (and the size of
 297  *   the entries array).
 298  * @param seq
 299  *   If not NULL, this is set to the value of the internal stage sequence number
 300  *   associated with the first entry returned.
 301  * @param block
 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.
 305  *
 306  * @param atomic
 307  *   if this is true, the function will return event according to event flow id
 308  * @return
 309  *   The number of pointers to entries filled in to the entries array.
 310  */
 311 uint32_t
 312 opdl_stage_claim(struct opdl_stage *s, void *entries,
 313                 uint32_t num_entries, uint32_t *seq, bool block, bool atomic);
 314
 315 uint32_t
 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);
 319
 320 /**
 321  * A function to check how many entries are ready to be claimed.
 322  *
 323  * @param entries
 324  *   An array of pointers to entries.
 325  * @param num_entries
 326  *   Number of entries in an array.
 327  * @param arg
 328  *   An opaque pointer to data passed to the claim function.
 329  * @param block
 330  *   When set to true, the function should wait until num_entries are ready to
 331  *   be processed. Otherwise it should return immediately.
 332  *
 333  * @return
 334  *   Number of entries ready to be claimed.
 335  */
 336 typedef uint32_t (opdl_ring_check_entries_t)(void *entries[],
 337                 uint32_t num_entries, void *arg, bool block);
 338
 339 /**
 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.
 344  *
 345  * @param s
 346  *   The opdl_ring stage to read entries in.
 347  * @param entries
 348  *   An array of pointers to entries that will be filled in by this function.
 349  * @param num_entries
 350  *   The number of entries to attempt to claim for processing (and the size of
 351  *   the entries array).
 352  * @param seq
 353  *   If not NULL, this is set to the value of the internal stage sequence number
 354  *   associated with the first entry returned.
 355  * @param block
 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.
 359  * @param check
 360  *   Pointer to a function called to check entries.
 361  * @param arg
 362  *   Opaque data passed to check() function.
 363  *
 364  * @return
 365  *   The number of pointers to ready entries filled in to the entries array.
 366  */
 367 uint32_t
 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);
 371
 372 /**
 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.
 377  *
 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
 383  * input parameters.
 384  *
 385  * @param s
 386  *   The opdl_ring stage to read entries in.
 387  * @param entries
 388  *   An array of entries that will be filled in by this function.
 389  * @param num_entries
 390  *   The number of entries to attempt to claim for processing (and the size of
 391  *   the entries array).
 392  * @param seq
 393  *   If not NULL, this is set to the value of the internal stage sequence number
 394  *   associated with the first entry returned.
 395  * @param block
 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.
 399  *
 400  * @return
 401  *   The number of entries copied in to the entries array.
 402  */
 403 uint32_t
 404 opdl_stage_claim_copy(struct opdl_stage *s, void *entries,
 405                 uint32_t num_entries, uint32_t *seq, bool block);
 406
 407 /**
 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.
 413  *
 414  * @param s
 415  *   The opdl_ring stage in which to disclaim all claimed entries.
 416  *
 417  * @param block
 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.
 426  *
 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.
 430  *
 431  *   In a single threaded stage, this parameter has no effect.
 432  */
 433 int
 434 opdl_stage_disclaim(struct opdl_stage *s, uint32_t num_entries,
 435                 bool block);
 436
 437 /**
 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.
 443  *
 444  * @param s
 445  *   The opdl_ring stage in which to disclaim entries.
 446  *
 447  * @param num_entries
 448  *   The number of entries to disclaim.
 449  *
 450  * @param block
 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.
 460  *
 461  *   In a single threaded stage, this parameter has no effect.
 462  */
 463 void
 464 opdl_stage_disclaim_n(struct opdl_stage *s, uint32_t num_entries,
 465                 bool block);
 466
 467 /**
 468  * Check how many entries can be input.
 469  *
 470  * @param t
 471  *   The opdl_ring instance to check.
 472  *
 473  * @return
 474  *   The number of new entries currently allowed to be input.
 475  */
 476 uint32_t
 477 opdl_ring_available(struct opdl_ring *t);
 478
 479 /**
 480  * Check how many entries can be processed in a stage.
 481  *
 482  * @param s
 483  *   The stage to check.
 484  *
 485  * @return
 486  *   The number of entries currently available to be processed in this stage.
 487  */
 488 uint32_t
 489 opdl_stage_available(struct opdl_stage *s);
 490
 491 /**
 492  * Check how many entries are available to be processed.
 493  *
 494  * NOTE : DOES NOT CHANGE ANY STATE WITHIN THE STAGE
 495  *
 496  * @param s
 497  *   The stage to check.
 498  *
 499  * @param num_entries
 500  *   The number of entries to check for availability.
 501  *
 502  * @return
 503  *   The number of entries currently available to be processed in this stage.
 504  */
 505 uint32_t
 506 opdl_stage_find_num_available(struct opdl_stage *s, uint32_t num_entries);
 507
 508 /**
 509  * Create empty stage instance and return the pointer.
 510  *
 511  * @param t
 512  *   The pointer of  opdl_ring.
 513  *
 514  * @param threadsafe
 515  *    enable multiple thread or not.
 516  * @return
 517  *   The pointer of one empty stage instance.
 518  */
 519 struct opdl_stage *
 520 opdl_stage_create(struct opdl_ring *t,  bool threadsafe);
 521
 522 /**
 523  * Prints information on opdl_ring instance and all its stages
 524  *
 525  * @param t
 526  *   The stage to print info on.
 527  * @param f
 528  *   Where to print the info.
 529  */
 530 void
 531 opdl_ring_dump(const struct opdl_ring *t, FILE *f);
 532
 533 /**
 534  * Blocks until all entries in a opdl_ring have been processed by all stages.
 535  *
 536  * @param t
 537  *   The opdl_ring instance to flush.
 538  */
 539 void
 540 opdl_ring_flush(struct opdl_ring *t);
 541
 542 /**
 543  * Deallocates all resources used by a opdl_ring instance
 544  *
 545  * @param t
 546  *   The opdl_ring instance to free.
 547  */
 548 void
 549 opdl_ring_free(struct opdl_ring *t);
 550
 551 /**
 552  * Search for a opdl_ring by its name
 553  *
 554  * @param name
 555  *   The name of the opdl_ring.
 556  * @return
 557  *   The pointer to the opdl_ring matching the name, or NULL if not found.
 558  *
 559  */
 560 struct opdl_ring *
 561 opdl_ring_lookup(const char *name);
 562
 563 /**
 564  * Set a opdl_stage to threadsafe variable.
 565  *
 566  * @param s
 567  *   The opdl_stage.
 568  * @param threadsafe
 569  *   Threadsafe value.
 570  */
 571 void
 572 opdl_ring_set_stage_threadsafe(struct opdl_stage *s, bool threadsafe);
 573
 574
 575 /**
 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
 580  *
 581  * @param s
 582  *   The opdl_stage.
 583  * @param ev
 584  *   pointer of the event descriptor.
 585  * @param index
 586  *   index of the event descriptor.
 587  * @param atomic
 588  *   queue type associate with the stage.
 589  * @return
 590  *   if the evevnt key field is changed compare with previous record.
 591  */
 592
 593 bool
 594 opdl_ring_cas_slot(const struct opdl_stage *s, const struct rte_event *ev,
 595                 uint32_t index, bool atomic);
 596
 597 #ifdef __cplusplus
 598 }
 599 #endif
 600
 601 #endif  /* _OPDL_H_ */