lib/librte_eal/common/include/rte_fbarray.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2017-2018 Intel Corporation
   3  */
   4
   5 #ifndef RTE_FBARRAY_H
   6 #define RTE_FBARRAY_H
   7
   8 /**
   9  * @file
  10  *
  11  * File-backed shared indexed array for DPDK.
  12  *
  13  * Basic workflow is expected to be the following:
  14  *  1) Allocate array either using ``rte_fbarray_init()`` or
  15  *     ``rte_fbarray_attach()`` (depending on whether it's shared between
  16  *     multiple DPDK processes)
  17  *  2) find free spots using ``rte_fbarray_find_next_free()``
  18  *  3) get pointer to data in the free spot using ``rte_fbarray_get()``, and
  19  *     copy data into the pointer (element size is fixed)
  20  *  4) mark entry as used using ``rte_fbarray_set_used()``
  21  *
  22  * Calls to ``rte_fbarray_init()`` and ``rte_fbarray_destroy()`` will have
  23  * consequences for all processes, while calls to ``rte_fbarray_attach()`` and
  24  * ``rte_fbarray_detach()`` will only have consequences within a single process.
  25  * Therefore, it is safe to call ``rte_fbarray_attach()`` or
  26  * ``rte_fbarray_detach()`` while another process is using ``rte_fbarray``,
  27  * provided no other thread within the same process will try to use
  28  * ``rte_fbarray`` before attaching or after detaching. It is not safe to call
  29  * ``rte_fbarray_init()`` or ``rte_fbarray_destroy()`` while another thread or
  30  * another process is using ``rte_fbarray``.
  31  */
  32
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #endif
  36
  37 #include <stdio.h>
  38
  39 #include <rte_compat.h>
  40 #include <rte_rwlock.h>
  41
  42 #define RTE_FBARRAY_NAME_LEN 64
  43
  44 struct rte_fbarray {
  45         char name[RTE_FBARRAY_NAME_LEN]; /**< name associated with an array */
  46         unsigned int count;              /**< number of entries stored */
  47         unsigned int len;                /**< current length of the array */
  48         unsigned int elt_sz;             /**< size of each element */
  49         void *data;                      /**< data pointer */
  50         rte_rwlock_t rwlock;             /**< multiprocess lock */
  51 };
  52
  53 /**
  54  * Set up ``rte_fbarray`` structure and allocate underlying resources.
  55  *
  56  * Call this function to correctly set up ``rte_fbarray`` and allocate
  57  * underlying files that will be backing the data in the current process. Note
  58  * that in order to use and share ``rte_fbarray`` between multiple processes,
  59  * data pointed to by ``arr`` pointer must itself be allocated in shared memory.
  60  *
  61  * @param arr
  62  *   Valid pointer to allocated ``rte_fbarray`` structure.
  63  *
  64  * @param name
  65  *   Unique name to be assigned to this array.
  66  *
  67  * @param len
  68  *   Number of elements initially available in the array.
  69  *
  70  * @param elt_sz
  71  *   Size of each element.
  72  *
  73  * @return
  74  *  - 0 on success.
  75  *  - -1 on failure, with ``rte_errno`` indicating reason for failure.
  76  */
  77 __rte_experimental
  78 int
  79 rte_fbarray_init(struct rte_fbarray *arr, const char *name, unsigned int len,
  80                 unsigned int elt_sz);
  81
  82
  83 /**
  84  * Attach to a file backing an already allocated and correctly set up
  85  * ``rte_fbarray`` structure.
  86  *
  87  * Call this function to attach to file that will be backing the data in the
  88  * current process. The structure must have been previously correctly set up
  89  * with a call to ``rte_fbarray_init()``. Calls to ``rte_fbarray_attach()`` are
  90  * usually meant to be performed in a multiprocessing scenario, with data
  91  * pointed to by ``arr`` pointer allocated in shared memory.
  92  *
  93  * @param arr
  94  *   Valid pointer to allocated and correctly set up rte_fbarray structure.
  95  *
  96  * @return
  97  *  - 0 on success.
  98  *  - -1 on failure, with ``rte_errno`` indicating reason for failure.
  99  */
 100 __rte_experimental
 101 int
 102 rte_fbarray_attach(struct rte_fbarray *arr);
 103
 104
 105 /**
 106  * Deallocate resources for an already allocated and correctly set up
 107  * ``rte_fbarray`` structure, and remove the underlying file.
 108  *
 109  * Call this function to deallocate all resources associated with an
 110  * ``rte_fbarray`` structure within the current process. This will also
 111  * zero-fill data pointed to by ``arr`` pointer and remove the underlying file
 112  * backing the data, so it is expected that by the time this function is called,
 113  * all other processes have detached from this ``rte_fbarray``.
 114  *
 115  * @param arr
 116  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 117  *
 118  * @return
 119  *  - 0 on success.
 120  *  - -1 on failure, with ``rte_errno`` indicating reason for failure.
 121  */
 122 __rte_experimental
 123 int
 124 rte_fbarray_destroy(struct rte_fbarray *arr);
 125
 126
 127 /**
 128  * Deallocate resources for an already allocated and correctly set up
 129  * ``rte_fbarray`` structure.
 130  *
 131  * Call this function to deallocate all resources associated with an
 132  * ``rte_fbarray`` structure within current process.
 133  *
 134  * @param arr
 135  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 136  *
 137  * @return
 138  *  - 0 on success.
 139  *  - -1 on failure, with ``rte_errno`` indicating reason for failure.
 140  */
 141 __rte_experimental
 142 int
 143 rte_fbarray_detach(struct rte_fbarray *arr);
 144
 145
 146 /**
 147  * Get pointer to element residing at specified index.
 148  *
 149  * @param arr
 150  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 151  *
 152  * @param idx
 153  *   Index of an element to get a pointer to.
 154  *
 155  * @return
 156  *  - non-NULL pointer on success.
 157  *  - NULL on failure, with ``rte_errno`` indicating reason for failure.
 158  */
 159 __rte_experimental
 160 void *
 161 rte_fbarray_get(const struct rte_fbarray *arr, unsigned int idx);
 162
 163
 164 /**
 165  * Find index of a specified element within the array.
 166  *
 167  * @param arr
 168  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 169  *
 170  * @param elt
 171  *   Pointer to element to find index to.
 172  *
 173  * @return
 174  *  - non-negative integer on success.
 175  *  - -1 on failure, with ``rte_errno`` indicating reason for failure.
 176  */
 177 __rte_experimental
 178 int
 179 rte_fbarray_find_idx(const struct rte_fbarray *arr, const void *elt);
 180
 181
 182 /**
 183  * Mark specified element as used.
 184  *
 185  * @param arr
 186  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 187  *
 188  * @param idx
 189  *   Element index to mark as used.
 190  *
 191  * @return
 192  *  - 0 on success.
 193  *  - -1 on failure, with ``rte_errno`` indicating reason for failure.
 194  */
 195 __rte_experimental
 196 int
 197 rte_fbarray_set_used(struct rte_fbarray *arr, unsigned int idx);
 198
 199
 200 /**
 201  * Mark specified element as free.
 202  *
 203  * @param arr
 204  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 205  *
 206  * @param idx
 207  *   Element index to mark as free.
 208  *
 209  * @return
 210  *  - 0 on success.
 211  *  - -1 on failure, with ``rte_errno`` indicating reason for failure.
 212  */
 213 __rte_experimental
 214 int
 215 rte_fbarray_set_free(struct rte_fbarray *arr, unsigned int idx);
 216
 217
 218 /**
 219  * Check whether element at specified index is marked as used.
 220  *
 221  * @param arr
 222  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 223  *
 224  * @param idx
 225  *   Element index to check as used.
 226  *
 227  * @return
 228  *  - 1 if element is used.
 229  *  - 0 if element is unused.
 230  *  - -1 on failure, with ``rte_errno`` indicating reason for failure.
 231  */
 232 __rte_experimental
 233 int
 234 rte_fbarray_is_used(struct rte_fbarray *arr, unsigned int idx);
 235
 236
 237 /**
 238  * Find index of next free element, starting at specified index.
 239  *
 240  * @param arr
 241  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 242  *
 243  * @param start
 244  *   Element index to start search from.
 245  *
 246  * @return
 247  *  - non-negative integer on success.
 248  *  - -1 on failure, with ``rte_errno`` indicating reason for failure.
 249  */
 250 __rte_experimental
 251 int
 252 rte_fbarray_find_next_free(struct rte_fbarray *arr, unsigned int start);
 253
 254
 255 /**
 256  * Find index of next used element, starting at specified index.
 257  *
 258  * @param arr
 259  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 260  *
 261  * @param start
 262  *   Element index to start search from.
 263  *
 264  * @return
 265  *  - non-negative integer on success.
 266  *  - -1 on failure, with ``rte_errno`` indicating reason for failure.
 267  */
 268 __rte_experimental
 269 int
 270 rte_fbarray_find_next_used(struct rte_fbarray *arr, unsigned int start);
 271
 272
 273 /**
 274  * Find index of next chunk of ``n`` free elements, starting at specified index.
 275  *
 276  * @param arr
 277  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 278  *
 279  * @param start
 280  *   Element index to start search from.
 281  *
 282  * @param n
 283  *   Number of free elements to look for.
 284  *
 285  * @return
 286  *  - non-negative integer on success.
 287  *  - -1 on failure, with ``rte_errno`` indicating reason for failure.
 288  */
 289 __rte_experimental
 290 int
 291 rte_fbarray_find_next_n_free(struct rte_fbarray *arr, unsigned int start,
 292                 unsigned int n);
 293
 294
 295 /**
 296  * Find index of next chunk of ``n`` used elements, starting at specified index.
 297  *
 298  * @param arr
 299  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 300  *
 301  * @param start
 302  *   Element index to start search from.
 303  *
 304  * @param n
 305  *   Number of used elements to look for.
 306  *
 307  * @return
 308  *  - non-negative integer on success.
 309  *  - -1 on failure, with ``rte_errno`` indicating reason for failure.
 310  */
 311 __rte_experimental
 312 int
 313 rte_fbarray_find_next_n_used(struct rte_fbarray *arr, unsigned int start,
 314                 unsigned int n);
 315
 316
 317 /**
 318  * Find how many more free entries there are, starting at specified index.
 319  *
 320  * @param arr
 321  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 322  *
 323  * @param start
 324  *   Element index to start search from.
 325  *
 326  * @return
 327  *  - non-negative integer on success.
 328  *  - -1 on failure, with ``rte_errno`` indicating reason for failure.
 329  */
 330 __rte_experimental
 331 int
 332 rte_fbarray_find_contig_free(struct rte_fbarray *arr,
 333                 unsigned int start);
 334
 335
 336 /**
 337  * Find how many more used entries there are, starting at specified index.
 338  *
 339  * @param arr
 340  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 341  *
 342  * @param start
 343  *   Element index to start search from.
 344  *
 345  * @return
 346  *  - non-negative integer on success.
 347  *  - -1 on failure, with ``rte_errno`` indicating reason for failure.
 348  */
 349 __rte_experimental
 350 int
 351 rte_fbarray_find_contig_used(struct rte_fbarray *arr, unsigned int start);
 352
 353 /**
 354  * Find index of previous free element, starting at specified index.
 355  *
 356  * @param arr
 357  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 358  *
 359  * @param start
 360  *   Element index to start search from.
 361  *
 362  * @return
 363  *  - non-negative integer on success.
 364  *  - -1 on failure, with ``rte_errno`` indicating reason for failure.
 365  */
 366 __rte_experimental
 367 int
 368 rte_fbarray_find_prev_free(struct rte_fbarray *arr, unsigned int start);
 369
 370
 371 /**
 372  * Find index of previous used element, starting at specified index.
 373  *
 374  * @param arr
 375  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 376  *
 377  * @param start
 378  *   Element index to start search from.
 379  *
 380  * @return
 381  *  - non-negative integer on success.
 382  *  - -1 on failure, with ``rte_errno`` indicating reason for failure.
 383  */
 384 __rte_experimental
 385 int
 386 rte_fbarray_find_prev_used(struct rte_fbarray *arr, unsigned int start);
 387
 388
 389 /**
 390  * Find lowest start index of chunk of ``n`` free elements, down from specified
 391  * index.
 392  *
 393  * @param arr
 394  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 395  *
 396  * @param start
 397  *   Element index to start search from.
 398  *
 399  * @param n
 400  *   Number of free elements to look for.
 401  *
 402  * @return
 403  *  - non-negative integer on success.
 404  *  - -1 on failure, with ``rte_errno`` indicating reason for failure.
 405  */
 406 __rte_experimental
 407 int
 408 rte_fbarray_find_prev_n_free(struct rte_fbarray *arr, unsigned int start,
 409                 unsigned int n);
 410
 411
 412 /**
 413  * Find lowest start index of chunk of ``n`` used elements, down from specified
 414  * index.
 415  *
 416  * @param arr
 417  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 418  *
 419  * @param start
 420  *   Element index to start search from.
 421  *
 422  * @param n
 423  *   Number of used elements to look for.
 424  *
 425  * @return
 426  *  - non-negative integer on success.
 427  *  - -1 on failure, with ``rte_errno`` indicating reason for failure.
 428  */
 429 __rte_experimental
 430 int
 431 rte_fbarray_find_prev_n_used(struct rte_fbarray *arr, unsigned int start,
 432                 unsigned int n);
 433
 434
 435 /**
 436  * Find how many more free entries there are before specified index (like
 437  * ``rte_fbarray_find_contig_free`` but going in reverse).
 438  *
 439  * @param arr
 440  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 441  *
 442  * @param start
 443  *   Element index to start search from.
 444  *
 445  * @return
 446  *  - non-negative integer on success.
 447  *  - -1 on failure, with ``rte_errno`` indicating reason for failure.
 448  */
 449 __rte_experimental
 450 int
 451 rte_fbarray_find_rev_contig_free(struct rte_fbarray *arr,
 452                 unsigned int start);
 453
 454
 455 /**
 456  * Find how many more used entries there are before specified index (like
 457  * ``rte_fbarray_find_contig_used`` but going in reverse).
 458  *
 459  * @param arr
 460  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 461  *
 462  * @param start
 463  *   Element index to start search from.
 464  *
 465  * @return
 466  *  - non-negative integer on success.
 467  *  - -1 on failure, with ``rte_errno`` indicating reason for failure.
 468  */
 469 __rte_experimental
 470 int
 471 rte_fbarray_find_rev_contig_used(struct rte_fbarray *arr, unsigned int start);
 472
 473
 474 /**
 475  * Find index of biggest chunk of free elements, starting at specified index.
 476  *
 477  * @param arr
 478  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 479  *
 480  * @param start
 481  *   Element index to start search from.
 482  *
 483  * @return
 484  *  - non-negative integer on success.
 485  *  - -1 on failure, with ``rte_errno`` indicating reason for failure.
 486  */
 487 __rte_experimental
 488 int
 489 rte_fbarray_find_biggest_free(struct rte_fbarray *arr, unsigned int start);
 490
 491
 492 /**
 493  * Find index of biggest chunk of used elements, starting at specified index.
 494  *
 495  * @param arr
 496  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 497  *
 498  * @param start
 499  *   Element index to start search from.
 500  *
 501  * @return
 502  *  - non-negative integer on success.
 503  *  - -1 on failure, with ``rte_errno`` indicating reason for failure.
 504  */
 505 __rte_experimental
 506 int
 507 rte_fbarray_find_biggest_used(struct rte_fbarray *arr, unsigned int start);
 508
 509
 510 /**
 511  * Find index of biggest chunk of free elements before a specified index (like
 512  * ``rte_fbarray_find_biggest_free``, but going in reverse).
 513  *
 514  * @param arr
 515  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 516  *
 517  * @param start
 518  *   Element index to start search from.
 519  *
 520  * @return
 521  *  - non-negative integer on success.
 522  *  - -1 on failure, with ``rte_errno`` indicating reason for failure.
 523  */
 524 __rte_experimental
 525 int
 526 rte_fbarray_find_rev_biggest_free(struct rte_fbarray *arr, unsigned int start);
 527
 528
 529 /**
 530  * Find index of biggest chunk of used elements before a specified index (like
 531  * ``rte_fbarray_find_biggest_used``, but going in reverse).
 532  *
 533  * @param arr
 534  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 535  *
 536  * @param start
 537  *   Element index to start search from.
 538  *
 539  * @return
 540  *  - non-negative integer on success.
 541  *  - -1 on failure, with ``rte_errno`` indicating reason for failure.
 542  */
 543 __rte_experimental
 544 int
 545 rte_fbarray_find_rev_biggest_used(struct rte_fbarray *arr, unsigned int start);
 546
 547
 548 /**
 549  * Dump ``rte_fbarray`` metadata.
 550  *
 551  * @param arr
 552  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 553  *
 554  * @param f
 555  *   File object to dump information into.
 556  */
 557 __rte_experimental
 558 void
 559 rte_fbarray_dump_metadata(struct rte_fbarray *arr, FILE *f);
 560
 561 #ifdef __cplusplus
 562 }
 563 #endif
 564
 565 #endif /* RTE_FBARRAY_H */