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.
78 rte_fbarray_init(struct rte_fbarray *arr, const char *name, unsigned int len,
83 * Attach to a file backing an already allocated and correctly set up
84 * ``rte_fbarray`` structure.
86 * Call this function to attach to file that will be backing the data in the
87 * current process. The structure must have been previously correctly set up
88 * with a call to ``rte_fbarray_init()``. Calls to ``rte_fbarray_attach()`` are
89 * usually meant to be performed in a multiprocessing scenario, with data
90 * pointed to by ``arr`` pointer allocated in shared memory.
93 * Valid pointer to allocated and correctly set up rte_fbarray structure.
97 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
100 rte_fbarray_attach(struct rte_fbarray *arr);
104 * Deallocate resources for an already allocated and correctly set up
105 * ``rte_fbarray`` structure, and remove the underlying file.
107 * Call this function to deallocate all resources associated with an
108 * ``rte_fbarray`` structure within the current process. This will also
109 * zero-fill data pointed to by ``arr`` pointer and remove the underlying file
110 * backing the data, so it is expected that by the time this function is called,
111 * all other processes have detached from this ``rte_fbarray``.
114 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
118 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
121 rte_fbarray_destroy(struct rte_fbarray *arr);
125 * Deallocate resources for an already allocated and correctly set up
126 * ``rte_fbarray`` structure.
128 * Call this function to deallocate all resources associated with an
129 * ``rte_fbarray`` structure within current process.
132 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
136 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
139 rte_fbarray_detach(struct rte_fbarray *arr);
143 * Get pointer to element residing at specified index.
146 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
149 * Index of an element to get a pointer to.
152 * - non-NULL pointer on success.
153 * - NULL on failure, with ``rte_errno`` indicating reason for failure.
156 rte_fbarray_get(const struct rte_fbarray *arr, unsigned int idx);
160 * Find index of a specified element within the array.
163 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
166 * Pointer to element to find index to.
169 * - non-negative integer on success.
170 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
173 rte_fbarray_find_idx(const struct rte_fbarray *arr, const void *elt);
177 * Mark specified element as used.
180 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
183 * Element index to mark as used.
187 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
190 rte_fbarray_set_used(struct rte_fbarray *arr, unsigned int idx);
194 * Mark specified element as free.
197 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
200 * Element index to mark as free.
204 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
207 rte_fbarray_set_free(struct rte_fbarray *arr, unsigned int idx);
211 * Check whether element at specified index is marked as used.
214 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
217 * Element index to check as used.
220 * - 1 if element is used.
221 * - 0 if element is unused.
222 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
225 rte_fbarray_is_used(struct rte_fbarray *arr, unsigned int idx);
229 * Find index of next free element, starting at specified index.
232 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
235 * Element index to start search from.
238 * - non-negative integer on success.
239 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
242 rte_fbarray_find_next_free(struct rte_fbarray *arr, unsigned int start);
246 * Find index of next used element, starting at specified index.
249 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
252 * Element index to start search from.
255 * - non-negative integer on success.
256 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
259 rte_fbarray_find_next_used(struct rte_fbarray *arr, unsigned int start);
263 * Find index of next chunk of ``n`` free elements, starting at specified index.
266 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
269 * Element index to start search from.
272 * Number of free elements to look for.
275 * - non-negative integer on success.
276 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
279 rte_fbarray_find_next_n_free(struct rte_fbarray *arr, unsigned int start,
284 * Find index of next chunk of ``n`` used elements, starting at specified index.
287 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
290 * Element index to start search from.
293 * Number of used elements to look for.
296 * - non-negative integer on success.
297 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
300 rte_fbarray_find_next_n_used(struct rte_fbarray *arr, unsigned int start,
305 * Find how many more free entries there are, starting at specified index.
308 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
311 * Element index to start search from.
314 * - non-negative integer on success.
315 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
318 rte_fbarray_find_contig_free(struct rte_fbarray *arr,
323 * Find how many more used entries there are, starting at specified index.
326 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
329 * Element index to start search from.
332 * - non-negative integer on success.
333 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
336 rte_fbarray_find_contig_used(struct rte_fbarray *arr, unsigned int start);
339 * Find index of previous free element, starting at specified index.
342 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
345 * Element index to start search from.
348 * - non-negative integer on success.
349 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
352 rte_fbarray_find_prev_free(struct rte_fbarray *arr, unsigned int start);
356 * Find index of previous used element, starting at specified index.
359 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
362 * Element index to start search from.
365 * - non-negative integer on success.
366 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
369 rte_fbarray_find_prev_used(struct rte_fbarray *arr, unsigned int start);
373 * Find lowest start index of chunk of ``n`` free elements, down from specified
377 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
380 * Element index to start search from.
383 * Number of free elements to look for.
386 * - non-negative integer on success.
387 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
390 rte_fbarray_find_prev_n_free(struct rte_fbarray *arr, unsigned int start,
395 * Find lowest start index of chunk of ``n`` used elements, down from specified
399 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
402 * Element index to start search from.
405 * Number of used elements to look for.
408 * - non-negative integer on success.
409 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
412 rte_fbarray_find_prev_n_used(struct rte_fbarray *arr, unsigned int start,
417 * Find how many more free entries there are before specified index (like
418 * ``rte_fbarray_find_contig_free`` but going in reverse).
421 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
424 * Element index to start search from.
427 * - non-negative integer on success.
428 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
431 rte_fbarray_find_rev_contig_free(struct rte_fbarray *arr,
436 * Find how many more used entries there are before specified index (like
437 * ``rte_fbarray_find_contig_used`` 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.
450 rte_fbarray_find_rev_contig_used(struct rte_fbarray *arr, unsigned int start);
454 * Find index of biggest chunk of free elements, starting at specified index.
457 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
460 * Element index to start search from.
463 * - non-negative integer on success.
464 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
467 rte_fbarray_find_biggest_free(struct rte_fbarray *arr, unsigned int start);
471 * Find index of biggest chunk of used elements, starting at specified index.
474 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
477 * Element index to start search from.
480 * - non-negative integer on success.
481 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
484 rte_fbarray_find_biggest_used(struct rte_fbarray *arr, unsigned int start);
488 * Find index of biggest chunk of free elements before a specified index (like
489 * ``rte_fbarray_find_biggest_free``, but going in reverse).
492 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
495 * Element index to start search from.
498 * - non-negative integer on success.
499 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
502 rte_fbarray_find_rev_biggest_free(struct rte_fbarray *arr, unsigned int start);
506 * Find index of biggest chunk of used elements before a specified index (like
507 * ``rte_fbarray_find_biggest_used``, but going in reverse).
510 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
513 * Element index to start search from.
516 * - non-negative integer on success.
517 * - -1 on failure, with ``rte_errno`` indicating reason for failure.
520 rte_fbarray_find_rev_biggest_used(struct rte_fbarray *arr, unsigned int start);
524 * Dump ``rte_fbarray`` metadata.
527 * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure.
530 * File object to dump information into.
533 rte_fbarray_dump_metadata(struct rte_fbarray *arr, FILE *f);
539 #endif /* RTE_FBARRAY_H */