]>
Commit | Line | Data |
---|---|---|
11fdf7f2 TL |
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 | ||
9f95a23c TL |
454 | /** |
455 | * Find index of biggest chunk of free elements, starting at specified index. | |
456 | * | |
457 | * @param arr | |
458 | * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure. | |
459 | * | |
460 | * @param start | |
461 | * Element index to start search from. | |
462 | * | |
463 | * @return | |
464 | * - non-negative integer on success. | |
465 | * - -1 on failure, with ``rte_errno`` indicating reason for failure. | |
466 | */ | |
467 | int __rte_experimental | |
468 | rte_fbarray_find_biggest_free(struct rte_fbarray *arr, unsigned int start); | |
469 | ||
470 | ||
471 | /** | |
472 | * Find index of biggest chunk of used elements, starting at specified index. | |
473 | * | |
474 | * @param arr | |
475 | * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure. | |
476 | * | |
477 | * @param start | |
478 | * Element index to start search from. | |
479 | * | |
480 | * @return | |
481 | * - non-negative integer on success. | |
482 | * - -1 on failure, with ``rte_errno`` indicating reason for failure. | |
483 | */ | |
484 | int __rte_experimental | |
485 | rte_fbarray_find_biggest_used(struct rte_fbarray *arr, unsigned int start); | |
486 | ||
487 | ||
488 | /** | |
489 | * Find index of biggest chunk of free elements before a specified index (like | |
490 | * ``rte_fbarray_find_biggest_free``, but going in reverse). | |
491 | * | |
492 | * @param arr | |
493 | * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure. | |
494 | * | |
495 | * @param start | |
496 | * Element index to start search from. | |
497 | * | |
498 | * @return | |
499 | * - non-negative integer on success. | |
500 | * - -1 on failure, with ``rte_errno`` indicating reason for failure. | |
501 | */ | |
502 | int __rte_experimental | |
503 | rte_fbarray_find_rev_biggest_free(struct rte_fbarray *arr, unsigned int start); | |
504 | ||
505 | ||
506 | /** | |
507 | * Find index of biggest chunk of used elements before a specified index (like | |
508 | * ``rte_fbarray_find_biggest_used``, but going in reverse). | |
509 | * | |
510 | * @param arr | |
511 | * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure. | |
512 | * | |
513 | * @param start | |
514 | * Element index to start search from. | |
515 | * | |
516 | * @return | |
517 | * - non-negative integer on success. | |
518 | * - -1 on failure, with ``rte_errno`` indicating reason for failure. | |
519 | */ | |
520 | int __rte_experimental | |
521 | rte_fbarray_find_rev_biggest_used(struct rte_fbarray *arr, unsigned int start); | |
522 | ||
523 | ||
11fdf7f2 TL |
524 | /** |
525 | * Dump ``rte_fbarray`` metadata. | |
526 | * | |
527 | * @param arr | |
528 | * Valid pointer to allocated and correctly set up ``rte_fbarray`` structure. | |
529 | * | |
530 | * @param f | |
531 | * File object to dump information into. | |
532 | */ | |
533 | void __rte_experimental | |
534 | rte_fbarray_dump_metadata(struct rte_fbarray *arr, FILE *f); | |
535 | ||
536 | #ifdef __cplusplus | |
537 | } | |
538 | #endif | |
539 | ||
540 | #endif /* RTE_FBARRAY_H */ |