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 int __rte_experimental
  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 int __rte_experimental
 101 rte_fbarray_attach(struct rte_fbarray *arr);
 102
 103
 104 /**
 105  * Deallocate resources for an already allocated and correctly set up
 106  * ``rte_fbarray`` structure, and remove the underlying file.
 107  *
 108  * Call this function to deallocate all resources associated with an
 109  * ``rte_fbarray`` structure within the current process. This will also
 110  * zero-fill data pointed to by ``arr`` pointer and remove the underlying file
 111  * backing the data, so it is expected that by the time this function is called,
 112  * all other processes have detached from this ``rte_fbarray``.
 113  *
 114  * @param arr
 115  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 116  *
 117  * @return
 118  *  - 0 on success.
 119  *  - -1 on failure, with ``rte_errno`` indicating reason for failure.
 120  */
 121 int __rte_experimental
 122 rte_fbarray_destroy(struct rte_fbarray *arr);
 123
 124
 125 /**
 126  * Deallocate resources for an already allocated and correctly set up
 127  * ``rte_fbarray`` structure.
 128  *
 129  * Call this function to deallocate all resources associated with an
 130  * ``rte_fbarray`` structure within current process.
 131  *
 132  * @param arr
 133  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 134  *
 135  * @return
 136  *  - 0 on success.
 137  *  - -1 on failure, with ``rte_errno`` indicating reason for failure.
 138  */
 139 int __rte_experimental
 140 rte_fbarray_detach(struct rte_fbarray *arr);
 141
 142
 143 /**
 144  * Get pointer to element residing at specified index.
 145  *
 146  * @param arr
 147  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 148  *
 149  * @param idx
 150  *   Index of an element to get a pointer to.
 151  *
 152  * @return
 153  *  - non-NULL pointer on success.
 154  *  - NULL on failure, with ``rte_errno`` indicating reason for failure.
 155  */
 156 void * __rte_experimental
 157 rte_fbarray_get(const struct rte_fbarray *arr, unsigned int idx);
 158
 159
 160 /**
 161  * Find index of a specified element within the array.
 162  *
 163  * @param arr
 164  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 165  *
 166  * @param elt
 167  *   Pointer to element to find index to.
 168  *
 169  * @return
 170  *  - non-negative integer on success.
 171  *  - -1 on failure, with ``rte_errno`` indicating reason for failure.
 172  */
 173 int __rte_experimental
 174 rte_fbarray_find_idx(const struct rte_fbarray *arr, const void *elt);
 175
 176
 177 /**
 178  * Mark specified element as used.
 179  *
 180  * @param arr
 181  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 182  *
 183  * @param idx
 184  *   Element index to mark as used.
 185  *
 186  * @return
 187  *  - 0 on success.
 188  *  - -1 on failure, with ``rte_errno`` indicating reason for failure.
 189  */
 190 int __rte_experimental
 191 rte_fbarray_set_used(struct rte_fbarray *arr, unsigned int idx);
 192
 193
 194 /**
 195  * Mark specified element as free.
 196  *
 197  * @param arr
 198  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 199  *
 200  * @param idx
 201  *   Element index to mark as free.
 202  *
 203  * @return
 204  *  - 0 on success.
 205  *  - -1 on failure, with ``rte_errno`` indicating reason for failure.
 206  */
 207 int __rte_experimental
 208 rte_fbarray_set_free(struct rte_fbarray *arr, unsigned int idx);
 209
 210
 211 /**
 212  * Check whether element at specified index is marked as used.
 213  *
 214  * @param arr
 215  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 216  *
 217  * @param idx
 218  *   Element index to check as used.
 219  *
 220  * @return
 221  *  - 1 if element is used.
 222  *  - 0 if element is unused.
 223  *  - -1 on failure, with ``rte_errno`` indicating reason for failure.
 224  */
 225 int __rte_experimental
 226 rte_fbarray_is_used(struct rte_fbarray *arr, unsigned int idx);
 227
 228
 229 /**
 230  * Find index of next free element, starting at specified index.
 231  *
 232  * @param arr
 233  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 234  *
 235  * @param start
 236  *   Element index to start search from.
 237  *
 238  * @return
 239  *  - non-negative integer on success.
 240  *  - -1 on failure, with ``rte_errno`` indicating reason for failure.
 241  */
 242 int __rte_experimental
 243 rte_fbarray_find_next_free(struct rte_fbarray *arr, unsigned int start);
 244
 245
 246 /**
 247  * Find index of next used element, starting at specified index.
 248  *
 249  * @param arr
 250  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 251  *
 252  * @param start
 253  *   Element index to start search from.
 254  *
 255  * @return
 256  *  - non-negative integer on success.
 257  *  - -1 on failure, with ``rte_errno`` indicating reason for failure.
 258  */
 259 int __rte_experimental
 260 rte_fbarray_find_next_used(struct rte_fbarray *arr, unsigned int start);
 261
 262
 263 /**
 264  * Find index of next chunk of ``n`` free elements, starting at specified index.
 265  *
 266  * @param arr
 267  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 268  *
 269  * @param start
 270  *   Element index to start search from.
 271  *
 272  * @param n
 273  *   Number of free elements to look for.
 274  *
 275  * @return
 276  *  - non-negative integer on success.
 277  *  - -1 on failure, with ``rte_errno`` indicating reason for failure.
 278  */
 279 int __rte_experimental
 280 rte_fbarray_find_next_n_free(struct rte_fbarray *arr, unsigned int start,
 281                 unsigned int n);
 282
 283
 284 /**
 285  * Find index of next chunk of ``n`` used elements, starting at specified index.
 286  *
 287  * @param arr
 288  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 289  *
 290  * @param start
 291  *   Element index to start search from.
 292  *
 293  * @param n
 294  *   Number of used elements to look for.
 295  *
 296  * @return
 297  *  - non-negative integer on success.
 298  *  - -1 on failure, with ``rte_errno`` indicating reason for failure.
 299  */
 300 int __rte_experimental
 301 rte_fbarray_find_next_n_used(struct rte_fbarray *arr, unsigned int start,
 302                 unsigned int n);
 303
 304
 305 /**
 306  * Find how many more free entries there are, starting at specified index.
 307  *
 308  * @param arr
 309  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 310  *
 311  * @param start
 312  *   Element index to start search from.
 313  *
 314  * @return
 315  *  - non-negative integer on success.
 316  *  - -1 on failure, with ``rte_errno`` indicating reason for failure.
 317  */
 318 int __rte_experimental
 319 rte_fbarray_find_contig_free(struct rte_fbarray *arr,
 320                 unsigned int start);
 321
 322
 323 /**
 324  * Find how many more used entries there are, starting at specified index.
 325  *
 326  * @param arr
 327  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 328  *
 329  * @param start
 330  *   Element index to start search from.
 331  *
 332  * @return
 333  *  - non-negative integer on success.
 334  *  - -1 on failure, with ``rte_errno`` indicating reason for failure.
 335  */
 336 int __rte_experimental
 337 rte_fbarray_find_contig_used(struct rte_fbarray *arr, unsigned int start);
 338
 339 /**
 340  * Find index of previous free element, starting at specified index.
 341  *
 342  * @param arr
 343  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 344  *
 345  * @param start
 346  *   Element index to start search from.
 347  *
 348  * @return
 349  *  - non-negative integer on success.
 350  *  - -1 on failure, with ``rte_errno`` indicating reason for failure.
 351  */
 352 int __rte_experimental
 353 rte_fbarray_find_prev_free(struct rte_fbarray *arr, unsigned int start);
 354
 355
 356 /**
 357  * Find index of previous used element, starting at specified index.
 358  *
 359  * @param arr
 360  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 361  *
 362  * @param start
 363  *   Element index to start search from.
 364  *
 365  * @return
 366  *  - non-negative integer on success.
 367  *  - -1 on failure, with ``rte_errno`` indicating reason for failure.
 368  */
 369 int __rte_experimental
 370 rte_fbarray_find_prev_used(struct rte_fbarray *arr, unsigned int start);
 371
 372
 373 /**
 374  * Find lowest start index of chunk of ``n`` free elements, down from specified
 375  * index.
 376  *
 377  * @param arr
 378  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 379  *
 380  * @param start
 381  *   Element index to start search from.
 382  *
 383  * @param n
 384  *   Number of free elements to look for.
 385  *
 386  * @return
 387  *  - non-negative integer on success.
 388  *  - -1 on failure, with ``rte_errno`` indicating reason for failure.
 389  */
 390 int __rte_experimental
 391 rte_fbarray_find_prev_n_free(struct rte_fbarray *arr, unsigned int start,
 392                 unsigned int n);
 393
 394
 395 /**
 396  * Find lowest start index of chunk of ``n`` used elements, down from specified
 397  * index.
 398  *
 399  * @param arr
 400  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 401  *
 402  * @param start
 403  *   Element index to start search from.
 404  *
 405  * @param n
 406  *   Number of used elements to look for.
 407  *
 408  * @return
 409  *  - non-negative integer on success.
 410  *  - -1 on failure, with ``rte_errno`` indicating reason for failure.
 411  */
 412 int __rte_experimental
 413 rte_fbarray_find_prev_n_used(struct rte_fbarray *arr, unsigned int start,
 414                 unsigned int n);
 415
 416
 417 /**
 418  * Find how many more free entries there are before specified index (like
 419  * ``rte_fbarray_find_contig_free`` but going in reverse).
 420  *
 421  * @param arr
 422  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 423  *
 424  * @param start
 425  *   Element index to start search from.
 426  *
 427  * @return
 428  *  - non-negative integer on success.
 429  *  - -1 on failure, with ``rte_errno`` indicating reason for failure.
 430  */
 431 int __rte_experimental
 432 rte_fbarray_find_rev_contig_free(struct rte_fbarray *arr,
 433                 unsigned int start);
 434
 435
 436 /**
 437  * Find how many more used entries there are before specified index (like
 438  * ``rte_fbarray_find_contig_used`` 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 int __rte_experimental
 451 rte_fbarray_find_rev_contig_used(struct rte_fbarray *arr, unsigned int start);
 452
 453
 454 /**
 455  * Dump ``rte_fbarray`` metadata.
 456  *
 457  * @param arr
 458  *   Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
 459  *
 460  * @param f
 461  *   File object to dump information into.
 462  */
 463 void __rte_experimental
 464 rte_fbarray_dump_metadata(struct rte_fbarray *arr, FILE *f);
 465
 466 #ifdef __cplusplus
 467 }
 468 #endif
 469
 470 #endif /* RTE_FBARRAY_H */