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``.
39 #include <rte_compat.h>
40 #include <rte_rwlock.h>
42 #define RTE_FBARRAY_NAME_LEN 64
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 */
54 * Set up ``rte_fbarray`` structure and allocate underlying resources.
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.
62 * Valid pointer to allocated ``rte_fbarray`` structure.
65 * Unique name to be assigned to this array.
68 * Number of elements initially available in the array.
71 * Size of each element.
75 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
79 rte_fbarray_init(struct rte_fbarray *arr, const char *name, unsigned int len,
84 * Attach to a file backing an already allocated and correctly set up
85 * ``rte_fbarray`` structure.
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.
94 * Valid pointer to allocated and correctly set up rte_fbarray structure.
98 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
102 rte_fbarray_attach(struct rte_fbarray *arr);
106 * Deallocate resources for an already allocated and correctly set up
107 * ``rte_fbarray`` structure, and remove the underlying file.
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``.
116 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
120 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
124 rte_fbarray_destroy(struct rte_fbarray *arr);
128 * Deallocate resources for an already allocated and correctly set up
129 * ``rte_fbarray`` structure.
131 * Call this function to deallocate all resources associated with an
132 * ``rte_fbarray`` structure within current process.
135 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
139 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
143 rte_fbarray_detach(struct rte_fbarray *arr);
147 * Get pointer to element residing at specified index.
150 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
153 * Index of an element to get a pointer to.
156 * - non-NULL pointer on success.
157 * - NULL on failure, with ``rte_errno`` indicating reason for failure.
161 rte_fbarray_get(const struct rte_fbarray *arr, unsigned int idx);
165 * Find index of a specified element within the array.
168 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
171 * Pointer to element to find index to.
174 * - non-negative integer on success.
175 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
179 rte_fbarray_find_idx(const struct rte_fbarray *arr, const void *elt);
183 * Mark specified element as used.
186 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
189 * Element index to mark as used.
193 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
197 rte_fbarray_set_used(struct rte_fbarray *arr, unsigned int idx);
201 * Mark specified element as free.
204 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
207 * Element index to mark as free.
211 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
215 rte_fbarray_set_free(struct rte_fbarray *arr, unsigned int idx);
219 * Check whether element at specified index is marked as used.
222 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
225 * Element index to check as used.
228 * - 1 if element is used.
229 * - 0 if element is unused.
230 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
234 rte_fbarray_is_used(struct rte_fbarray *arr, unsigned int idx);
238 * Find index of next free element, starting at specified index.
241 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
244 * Element index to start search from.
247 * - non-negative integer on success.
248 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
252 rte_fbarray_find_next_free(struct rte_fbarray *arr, unsigned int start);
256 * Find index of next used element, starting at specified index.
259 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
262 * Element index to start search from.
265 * - non-negative integer on success.
266 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
270 rte_fbarray_find_next_used(struct rte_fbarray *arr, unsigned int start);
274 * Find index of next chunk of ``n`` free elements, starting at specified index.
277 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
280 * Element index to start search from.
283 * Number of free elements to look for.
286 * - non-negative integer on success.
287 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
291 rte_fbarray_find_next_n_free(struct rte_fbarray *arr, unsigned int start,
296 * Find index of next chunk of ``n`` used elements, starting at specified index.
299 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
302 * Element index to start search from.
305 * Number of used elements to look for.
308 * - non-negative integer on success.
309 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
313 rte_fbarray_find_next_n_used(struct rte_fbarray *arr, unsigned int start,
318 * Find how many more free entries there are, starting at specified index.
321 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
324 * Element index to start search from.
327 * - non-negative integer on success.
328 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
332 rte_fbarray_find_contig_free(struct rte_fbarray *arr,
337 * Find how many more used entries there are, starting at specified index.
340 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
343 * Element index to start search from.
346 * - non-negative integer on success.
347 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
351 rte_fbarray_find_contig_used(struct rte_fbarray *arr, unsigned int start);
354 * Find index of previous free element, starting at specified index.
357 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
360 * Element index to start search from.
363 * - non-negative integer on success.
364 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
368 rte_fbarray_find_prev_free(struct rte_fbarray *arr, unsigned int start);
372 * Find index of previous used element, starting at specified index.
375 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
378 * Element index to start search from.
381 * - non-negative integer on success.
382 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
386 rte_fbarray_find_prev_used(struct rte_fbarray *arr, unsigned int start);
390 * Find lowest start index of chunk of ``n`` free elements, down from specified
394 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
397 * Element index to start search from.
400 * Number of free elements to look for.
403 * - non-negative integer on success.
404 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
408 rte_fbarray_find_prev_n_free(struct rte_fbarray *arr, unsigned int start,
413 * Find lowest start index of chunk of ``n`` used elements, down from specified
417 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
420 * Element index to start search from.
423 * Number of used elements to look for.
426 * - non-negative integer on success.
427 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
431 rte_fbarray_find_prev_n_used(struct rte_fbarray *arr, unsigned int start,
436 * Find how many more free entries there are before specified index (like
437 * ``rte_fbarray_find_contig_free`` but going in reverse).
440 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
443 * Element index to start search from.
446 * - non-negative integer on success.
447 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
451 rte_fbarray_find_rev_contig_free(struct rte_fbarray *arr,
456 * Find how many more used entries there are before specified index (like
457 * ``rte_fbarray_find_contig_used`` but going in reverse).
460 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
463 * Element index to start search from.
466 * - non-negative integer on success.
467 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
471 rte_fbarray_find_rev_contig_used(struct rte_fbarray *arr, unsigned int start);
475 * Find index of biggest chunk of free elements, starting at specified index.
478 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
481 * Element index to start search from.
484 * - non-negative integer on success.
485 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
489 rte_fbarray_find_biggest_free(struct rte_fbarray *arr, unsigned int start);
493 * Find index of biggest chunk of used elements, starting at specified index.
496 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
499 * Element index to start search from.
502 * - non-negative integer on success.
503 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
507 rte_fbarray_find_biggest_used(struct rte_fbarray *arr, unsigned int start);
511 * Find index of biggest chunk of free elements before a specified index (like
512 * ``rte_fbarray_find_biggest_free``, but going in reverse).
515 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
518 * Element index to start search from.
521 * - non-negative integer on success.
522 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
526 rte_fbarray_find_rev_biggest_free(struct rte_fbarray *arr, unsigned int start);
530 * Find index of biggest chunk of used elements before a specified index (like
531 * ``rte_fbarray_find_biggest_used``, but going in reverse).
534 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
537 * Element index to start search from.
540 * - non-negative integer on success.
541 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
545 rte_fbarray_find_rev_biggest_used(struct rte_fbarray *arr, unsigned int start);
549 * Dump ``rte_fbarray`` metadata.
552 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
555 * File object to dump information into.
559 rte_fbarray_dump_metadata(struct rte_fbarray *arr, FILE *f);
565 #endif /* RTE_FBARRAY_H */