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