1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2017-2018 Intel Corporation
11 * File-backed shared indexed array for DPDK.
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()``
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``.
40 #include <rte_compat.h>
41 #include <rte_rwlock.h>
43 #define RTE_FBARRAY_NAME_LEN 64
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 */
55 * Set up ``rte_fbarray`` structure and allocate underlying resources.
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.
63 * Valid pointer to allocated ``rte_fbarray`` structure.
66 * Unique name to be assigned to this array.
69 * Number of elements initially available in the array.
72 * Size of each element.
76 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
80 rte_fbarray_init(struct rte_fbarray *arr, const char *name, unsigned int len,
85 * Attach to a file backing an already allocated and correctly set up
86 * ``rte_fbarray`` structure.
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.
95 * Valid pointer to allocated and correctly set up rte_fbarray structure.
99 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
103 rte_fbarray_attach(struct rte_fbarray *arr);
107 * Deallocate resources for an already allocated and correctly set up
108 * ``rte_fbarray`` structure, and remove the underlying file.
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``.
117 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
121 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
125 rte_fbarray_destroy(struct rte_fbarray *arr);
129 * Deallocate resources for an already allocated and correctly set up
130 * ``rte_fbarray`` structure.
132 * Call this function to deallocate all resources associated with an
133 * ``rte_fbarray`` structure within current process.
136 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
140 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
144 rte_fbarray_detach(struct rte_fbarray *arr);
148 * Get pointer to element residing at specified index.
151 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
154 * Index of an element to get a pointer to.
157 * - non-NULL pointer on success.
158 * - NULL on failure, with ``rte_errno`` indicating reason for failure.
162 rte_fbarray_get(const struct rte_fbarray *arr, unsigned int idx);
166 * Find index of a specified element within the array.
169 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
172 * Pointer to element to find index to.
175 * - non-negative integer on success.
176 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
180 rte_fbarray_find_idx(const struct rte_fbarray *arr, const void *elt);
184 * Mark specified element as used.
187 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
190 * Element index to mark as used.
194 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
198 rte_fbarray_set_used(struct rte_fbarray *arr, unsigned int idx);
202 * Mark specified element as free.
205 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
208 * Element index to mark as free.
212 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
216 rte_fbarray_set_free(struct rte_fbarray *arr, unsigned int idx);
220 * Check whether element at specified index is marked as used.
223 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
226 * Element index to check as used.
229 * - 1 if element is used.
230 * - 0 if element is unused.
231 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
235 rte_fbarray_is_used(struct rte_fbarray *arr, unsigned int idx);
239 * Find index of next free element, starting at specified index.
242 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
245 * Element index to start search from.
248 * - non-negative integer on success.
249 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
253 rte_fbarray_find_next_free(struct rte_fbarray *arr, unsigned int start);
257 * Find index of next used element, starting at specified index.
260 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
263 * Element index to start search from.
266 * - non-negative integer on success.
267 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
271 rte_fbarray_find_next_used(struct rte_fbarray *arr, unsigned int start);
275 * Find index of next chunk of ``n`` free elements, starting at specified index.
278 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
281 * Element index to start search from.
284 * Number of free elements to look for.
287 * - non-negative integer on success.
288 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
292 rte_fbarray_find_next_n_free(struct rte_fbarray *arr, unsigned int start,
297 * Find index of next chunk of ``n`` used elements, starting at specified index.
300 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
303 * Element index to start search from.
306 * Number of used elements to look for.
309 * - non-negative integer on success.
310 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
314 rte_fbarray_find_next_n_used(struct rte_fbarray *arr, unsigned int start,
319 * Find how many more free entries there are, starting at specified index.
322 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
325 * Element index to start search from.
328 * - non-negative integer on success.
329 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
333 rte_fbarray_find_contig_free(struct rte_fbarray *arr,
338 * Find how many more used entries there are, starting at specified index.
341 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
344 * Element index to start search from.
347 * - non-negative integer on success.
348 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
352 rte_fbarray_find_contig_used(struct rte_fbarray *arr, unsigned int start);
355 * Find index of previous free element, starting at specified index.
358 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
361 * Element index to start search from.
364 * - non-negative integer on success.
365 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
369 rte_fbarray_find_prev_free(struct rte_fbarray *arr, unsigned int start);
373 * Find index of previous used element, starting at specified index.
376 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
379 * Element index to start search from.
382 * - non-negative integer on success.
383 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
387 rte_fbarray_find_prev_used(struct rte_fbarray *arr, unsigned int start);
391 * Find lowest start index of chunk of ``n`` free elements, down from specified
395 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
398 * Element index to start search from.
401 * Number of free elements to look for.
404 * - non-negative integer on success.
405 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
409 rte_fbarray_find_prev_n_free(struct rte_fbarray *arr, unsigned int start,
414 * Find lowest start index of chunk of ``n`` used elements, down from specified
418 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
421 * Element index to start search from.
424 * Number of used elements to look for.
427 * - non-negative integer on success.
428 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
432 rte_fbarray_find_prev_n_used(struct rte_fbarray *arr, unsigned int start,
437 * Find how many more free entries there are before specified index (like
438 * ``rte_fbarray_find_contig_free`` but going in reverse).
441 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
444 * Element index to start search from.
447 * - non-negative integer on success.
448 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
452 rte_fbarray_find_rev_contig_free(struct rte_fbarray *arr,
457 * Find how many more used entries there are before specified index (like
458 * ``rte_fbarray_find_contig_used`` but going in reverse).
461 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
464 * Element index to start search from.
467 * - non-negative integer on success.
468 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
472 rte_fbarray_find_rev_contig_used(struct rte_fbarray *arr, unsigned int start);
476 * Find index of biggest chunk of free elements, starting at specified index.
479 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
482 * Element index to start search from.
485 * - non-negative integer on success.
486 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
490 rte_fbarray_find_biggest_free(struct rte_fbarray *arr, unsigned int start);
494 * Find index of biggest chunk of used elements, starting at specified index.
497 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
500 * Element index to start search from.
503 * - non-negative integer on success.
504 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
508 rte_fbarray_find_biggest_used(struct rte_fbarray *arr, unsigned int start);
512 * Find index of biggest chunk of free elements before a specified index (like
513 * ``rte_fbarray_find_biggest_free``, but going in reverse).
516 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
519 * Element index to start search from.
522 * - non-negative integer on success.
523 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
527 rte_fbarray_find_rev_biggest_free(struct rte_fbarray *arr, unsigned int start);
531 * Find index of biggest chunk of used elements before a specified index (like
532 * ``rte_fbarray_find_biggest_used``, but going in reverse).
535 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
538 * Element index to start search from.
541 * - non-negative integer on success.
542 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
546 rte_fbarray_find_rev_biggest_used(struct rte_fbarray *arr, unsigned int start);
550 * Dump ``rte_fbarray`` metadata.
553 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
556 * File object to dump information into.
560 rte_fbarray_dump_metadata(struct rte_fbarray *arr, FILE *f);
566 #endif /* RTE_FBARRAY_H */