Line data Source code
1 : /* SPDX-License-Identifier: BSD-3-Clause
2 : * Copyright (C) 2016 Intel Corporation.
3 : * All rights reserved.
4 : * Copyright (c) 2022, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
5 : */
6 :
7 : /** \file
8 : * Thread
9 : */
10 :
11 : #ifndef SPDK_THREAD_H_
12 : #define SPDK_THREAD_H_
13 :
14 : #include "spdk/config.h"
15 : #include "spdk/fd_group.h"
16 : #include "spdk/stdinc.h"
17 : #include "spdk/assert.h"
18 : #include "spdk/cpuset.h"
19 : #include "spdk/env.h"
20 : #include "spdk/util.h"
21 : #include "spdk/likely.h"
22 :
23 : #ifdef __cplusplus
24 : extern "C" {
25 : #endif
26 :
27 : /**
28 : * Pollers should always return a value of this type
29 : * indicating whether they did real work or not.
30 : */
31 : enum spdk_thread_poller_rc {
32 : SPDK_POLLER_IDLE,
33 : SPDK_POLLER_BUSY,
34 : };
35 :
36 : /**
37 : * A stackless, lightweight thread.
38 : */
39 : struct spdk_thread;
40 :
41 : /**
42 : * A function repeatedly called on the same spdk_thread.
43 : */
44 : struct spdk_poller;
45 :
46 : struct spdk_io_channel_iter;
47 :
48 : /**
49 : * A function that is called each time a new thread is created.
50 : * The implementer of this function should frequently call
51 : * spdk_thread_poll() on the thread provided.
52 : *
53 : * \param thread The new spdk_thread.
54 : */
55 : typedef int (*spdk_new_thread_fn)(struct spdk_thread *thread);
56 :
57 : /**
58 : * SPDK thread operation type.
59 : */
60 : enum spdk_thread_op {
61 : /* Called each time a new thread is created. The implementer of this operation
62 : * should frequently call spdk_thread_poll() on the thread provided.
63 : */
64 : SPDK_THREAD_OP_NEW,
65 :
66 : /* Called when SPDK thread needs to be rescheduled. (e.g., when cpumask of the
67 : * SPDK thread is updated.
68 : */
69 : SPDK_THREAD_OP_RESCHED,
70 : };
71 :
72 : /**
73 : * Function to be called for SPDK thread operation.
74 : */
75 : typedef int (*spdk_thread_op_fn)(struct spdk_thread *thread, enum spdk_thread_op op);
76 :
77 : /**
78 : * Function to check whether the SPDK thread operation is supported.
79 : */
80 : typedef bool (*spdk_thread_op_supported_fn)(enum spdk_thread_op op);
81 :
82 : /**
83 : * A function that will be called on the target thread.
84 : *
85 : * \param ctx Context passed as arg to spdk_thread_pass_msg().
86 : */
87 : typedef void (*spdk_msg_fn)(void *ctx);
88 :
89 : /**
90 : * Function to be called to pass a message to a thread.
91 : *
92 : * \param fn Callback function for a thread.
93 : * \param ctx Context passed to fn.
94 : * \param thread_ctx Context for the thread.
95 : */
96 : typedef void (*spdk_thread_pass_msg)(spdk_msg_fn fn, void *ctx,
97 : void *thread_ctx);
98 :
99 : /**
100 : * Callback function for a poller.
101 : *
102 : * \param ctx Context passed as arg to spdk_poller_register().
103 : * \return value of type `enum spdk_thread_poller_rc` (ex: SPDK_POLLER_IDLE
104 : * if no work was done or SPDK_POLLER_BUSY if work was done.)
105 : */
106 : typedef int (*spdk_poller_fn)(void *ctx);
107 :
108 : /**
109 : * Callback function to set poller into interrupt mode or back to poll mode.
110 : *
111 : * \param poller Poller to set interrupt or poll mode.
112 : * \param cb_arg Argument passed to the callback function.
113 : * \param interrupt_mode Set interrupt mode for true, or poll mode for false
114 : */
115 : typedef void (*spdk_poller_set_interrupt_mode_cb)(struct spdk_poller *poller, void *cb_arg,
116 : bool interrupt_mode);
117 :
118 : /**
119 : * Mark that the poller is capable of entering interrupt mode.
120 : *
121 : * When registering the poller set interrupt callback, the callback will get
122 : * executed immediately if its spdk_thread is in the interrupt mode.
123 : *
124 : * Callers may pass NULL for the cb_fn, signifying that no callback is
125 : * necessary when the interrupt mode changes.
126 : *
127 : * \param poller The poller to register callback function.
128 : * \param cb_fn Callback function called when the poller must transition into or out of interrupt mode
129 : * \param cb_arg Argument passed to the callback function.
130 : */
131 : void spdk_poller_register_interrupt(struct spdk_poller *poller,
132 : spdk_poller_set_interrupt_mode_cb cb_fn,
133 : void *cb_arg);
134 :
135 : /**
136 : * I/O channel creation callback.
137 : *
138 : * \param io_device I/O device associated with this channel.
139 : * \param ctx_buf Context for the I/O device.
140 : */
141 : typedef int (*spdk_io_channel_create_cb)(void *io_device, void *ctx_buf);
142 :
143 : /**
144 : * I/O channel destruction callback.
145 : *
146 : * \param io_device I/O device associated with this channel.
147 : * \param ctx_buf Context for the I/O device.
148 : */
149 : typedef void (*spdk_io_channel_destroy_cb)(void *io_device, void *ctx_buf);
150 :
151 : /**
152 : * I/O device unregister callback.
153 : *
154 : * \param io_device Unregistered I/O device.
155 : */
156 : typedef void (*spdk_io_device_unregister_cb)(void *io_device);
157 :
158 : /**
159 : * Called on the appropriate thread for each channel associated with io_device.
160 : *
161 : * \param i I/O channel iterator.
162 : */
163 : typedef void (*spdk_channel_msg)(struct spdk_io_channel_iter *i);
164 :
165 : /**
166 : * spdk_for_each_channel() callback.
167 : *
168 : * \param i I/O channel iterator.
169 : * \param status 0 if it completed successfully, or negative errno if it failed.
170 : */
171 : typedef void (*spdk_channel_for_each_cpl)(struct spdk_io_channel_iter *i, int status);
172 :
173 : #define SPDK_IO_CHANNEL_STRUCT_SIZE 96
174 :
175 : /**
176 : * Message memory pool size definitions
177 : */
178 : #define SPDK_MSG_MEMPOOL_CACHE_SIZE 1024
179 : /* Power of 2 minus 1 is optimal for memory consumption */
180 : #define SPDK_DEFAULT_MSG_MEMPOOL_SIZE (262144 - 1)
181 :
182 : /**
183 : * Initialize the threading library. Must be called once prior to allocating any threads.
184 : *
185 : * \param new_thread_fn Called each time a new SPDK thread is created. The implementer
186 : * is expected to frequently call spdk_thread_poll() on the provided thread.
187 : * \param ctx_sz For each thread allocated, an additional region of memory of
188 : * size ctx_size will also be allocated, for use by the thread scheduler. A pointer
189 : * to this region may be obtained by calling spdk_thread_get_ctx().
190 : *
191 : * \return 0 on success. Negated errno on failure.
192 : */
193 : int spdk_thread_lib_init(spdk_new_thread_fn new_thread_fn, size_t ctx_sz);
194 :
195 : /**
196 : * Initialize the threading library. Must be called once prior to allocating any threads
197 : *
198 : * Both thread_op_fn and thread_op_type_supported_fn have to be specified or not
199 : * specified together.
200 : *
201 : * \param thread_op_fn Called for SPDK thread operation.
202 : * \param thread_op_supported_fn Called to check whether the SPDK thread operation is supported.
203 : * \param ctx_sz For each thread allocated, for use by the thread scheduler. A pointer
204 : * to this region may be obtained by calling spdk_thread_get_ctx().
205 : * \param msg_mempool_size Size of the allocated spdk_msg_mempool.
206 : *
207 : * \return 0 on success. Negated errno on failure.
208 : */
209 : int spdk_thread_lib_init_ext(spdk_thread_op_fn thread_op_fn,
210 : spdk_thread_op_supported_fn thread_op_supported_fn,
211 : size_t ctx_sz, size_t msg_mempool_size);
212 :
213 : /**
214 : * Release all resources associated with this library.
215 : */
216 : void spdk_thread_lib_fini(void);
217 :
218 : /**
219 : * Creates a new SPDK thread object.
220 : *
221 : * Note that the first thread created via spdk_thread_create() will be designated as
222 : * the app thread. Other SPDK libraries may place restrictions on certain APIs to
223 : * only be called in the context of this app thread.
224 : *
225 : * \param name Human-readable name for the thread; can be retrieved with spdk_thread_get_name().
226 : * The string is copied, so the pointed-to data only needs to be valid during the
227 : * spdk_thread_create() call. May be NULL to specify no name.
228 : * \param cpumask Optional mask of CPU cores on which to schedule this thread. This is only
229 : * a suggestion to the scheduler. The value is copied, so cpumask may be released when
230 : * this function returns. May be NULL if no mask is required.
231 : *
232 : * \return a pointer to the allocated thread on success or NULL on failure..
233 : */
234 : struct spdk_thread *spdk_thread_create(const char *name, const struct spdk_cpuset *cpumask);
235 :
236 : /**
237 : * Return the app thread.
238 : *
239 : * The app thread is the first thread created using spdk_thread_create().
240 : *
241 : * \return a pointer to the app thread, or NULL if no thread has been created yet.
242 : */
243 : struct spdk_thread *spdk_thread_get_app_thread(void);
244 :
245 : /**
246 : * Check if the specified spdk_thread is the app thread.
247 : *
248 : * \param thread The thread to check. If NULL, check the current spdk_thread.
249 : * \return true if the specified spdk_thread is the app thread, false otherwise.
250 : */
251 : bool spdk_thread_is_app_thread(struct spdk_thread *thread);
252 :
253 : /**
254 : * Force the current system thread to act as if executing the given SPDK thread.
255 : *
256 : * \param thread The thread to set.
257 : */
258 : void spdk_set_thread(struct spdk_thread *thread);
259 :
260 : /**
261 : * Bind or unbind spdk_thread to its current CPU core.
262 : *
263 : * If spdk_thread is bound, it couldn't be rescheduled to other CPU cores until it is unbound.
264 : *
265 : * \param thread The thread to bind or not.
266 : * \param bind true for bind, false for unbind.
267 : */
268 : void spdk_thread_bind(struct spdk_thread *thread, bool bind);
269 :
270 : /**
271 : * Returns whether the thread is bound to its current CPU core.
272 : *
273 : * \param thread The thread to query.
274 : *
275 : * \return true if bound, false otherwise
276 : */
277 : bool spdk_thread_is_bound(struct spdk_thread *thread);
278 :
279 : /**
280 : * Mark the thread as exited, failing all future spdk_thread_send_msg(),
281 : * spdk_poller_register(), and spdk_get_io_channel() calls. May only be called
282 : * within an spdk poller or message.
283 : *
284 : * All I/O channel references associated with the thread must be released
285 : * using spdk_put_io_channel(), and all active pollers associated with the thread
286 : * should be unregistered using spdk_poller_unregister(), prior to calling
287 : * this function. This function will complete these processing. The completion can
288 : * be queried by spdk_thread_is_exited().
289 : *
290 : * Note that this function must not be called on the app thread until after it
291 : * has been called for all other threads.
292 : *
293 : * \param thread The thread to exit.
294 : *
295 : * \return always 0. (return value was deprecated but keep it for ABI compatibility.)
296 : */
297 : int spdk_thread_exit(struct spdk_thread *thread);
298 :
299 : /**
300 : * Returns whether the thread is marked as exited.
301 : *
302 : * A thread is exited only after it has spdk_thread_exit() called on it, and
303 : * it has been polled until any outstanding operations targeting this
304 : * thread have completed. This may include poller unregistrations, io channel
305 : * unregistrations, or outstanding spdk_thread_send_msg calls.
306 : *
307 : * \param thread The thread to query.
308 : *
309 : * \return true if marked as exited, false otherwise.
310 : */
311 : bool spdk_thread_is_exited(struct spdk_thread *thread);
312 :
313 : /**
314 : * Returns whether the thread is still running.
315 : *
316 : * A thread is considered running until it has * spdk_thread_exit() called on it.
317 : *
318 : * \param thread The thread to query.
319 : *
320 : * \return true if still running, false otherwise.
321 : */
322 : bool spdk_thread_is_running(struct spdk_thread *thread);
323 :
324 : /**
325 : * Destroy a thread, releasing all of its resources. May only be called
326 : * on a thread previously marked as exited.
327 : *
328 : * \param thread The thread to destroy.
329 : *
330 : */
331 : void spdk_thread_destroy(struct spdk_thread *thread);
332 :
333 : /**
334 : * Return a pointer to this thread's context.
335 : *
336 : * \param thread The thread on which to get the context.
337 : *
338 : * \return a pointer to the per-thread context, or NULL if there is
339 : * no per-thread context.
340 : */
341 : void *spdk_thread_get_ctx(struct spdk_thread *thread);
342 :
343 : /**
344 : * Get the thread's cpumask.
345 : *
346 : * \param thread The thread to get the cpumask for.
347 : *
348 : * \return cpuset pointer
349 : */
350 : struct spdk_cpuset *spdk_thread_get_cpumask(struct spdk_thread *thread);
351 :
352 : /**
353 : * Set the current thread's cpumask to the specified value. The thread may be
354 : * rescheduled to one of the CPUs specified in the cpumask.
355 : *
356 : * This API requires SPDK thread operation supports SPDK_THREAD_OP_RESCHED.
357 : *
358 : * \param cpumask The new cpumask for the thread.
359 : *
360 : * \return 0 on success, negated errno otherwise.
361 : */
362 : int spdk_thread_set_cpumask(struct spdk_cpuset *cpumask);
363 :
364 : /**
365 : * Return the thread object associated with the context handle previously
366 : * obtained by calling spdk_thread_get_ctx().
367 : *
368 : * \param ctx A context previously obtained by calling spdk_thread_get_ctx()
369 : *
370 : * \return The associated thread.
371 : */
372 : struct spdk_thread *spdk_thread_get_from_ctx(void *ctx);
373 :
374 : /**
375 : * Perform one iteration worth of processing on the thread. This includes
376 : * both expired and continuous pollers as well as messages. If the thread
377 : * has exited, return immediately.
378 : *
379 : * \param thread The thread to process
380 : * \param max_msgs The maximum number of messages that will be processed.
381 : * Use 0 to process the default number of messages (8).
382 : * \param now The current time, in ticks. Optional. If 0 is passed, this
383 : * function will call spdk_get_ticks() to get the current time.
384 : * The current time is used as start time and this function
385 : * will call spdk_get_ticks() at its end to know end time to
386 : * measure run time of this function.
387 : *
388 : * \return 1 if work was done. 0 if no work was done.
389 : */
390 : int spdk_thread_poll(struct spdk_thread *thread, uint32_t max_msgs, uint64_t now);
391 :
392 : /**
393 : * Return the number of ticks until the next timed poller
394 : * would expire. Timed pollers are pollers for which
395 : * period_microseconds is greater than 0.
396 : *
397 : * \param thread The thread to check poller expiration times on
398 : *
399 : * \return Number of ticks. If no timed pollers, return 0.
400 : */
401 : uint64_t spdk_thread_next_poller_expiration(struct spdk_thread *thread);
402 :
403 : /**
404 : * Returns whether there are any active pollers (pollers for which
405 : * period_microseconds equals 0) registered to be run on the thread.
406 : *
407 : * \param thread The thread to check.
408 : *
409 : * \return 1 if there is at least one active poller, 0 otherwise.
410 : */
411 : int spdk_thread_has_active_pollers(struct spdk_thread *thread);
412 :
413 : /**
414 : * Returns whether there are any pollers registered to be run
415 : * on the thread.
416 : *
417 : * \param thread The thread to check.
418 : *
419 : * \return true if there is any active poller, false otherwise.
420 : */
421 : bool spdk_thread_has_pollers(struct spdk_thread *thread);
422 :
423 : /**
424 : * Returns whether there are scheduled operations to be run on the thread.
425 : *
426 : * \param thread The thread to check.
427 : *
428 : * \return true if there are no scheduled operations, false otherwise.
429 : */
430 : bool spdk_thread_is_idle(struct spdk_thread *thread);
431 :
432 : /**
433 : * Get count of allocated threads.
434 : */
435 : uint32_t spdk_thread_get_count(void);
436 :
437 : /**
438 : * Get a handle to the current thread.
439 : *
440 : * This handle may be passed to other threads and used as the target of
441 : * spdk_thread_send_msg().
442 : *
443 : * \sa spdk_io_channel_get_thread()
444 : *
445 : * \return a pointer to the current thread on success or NULL on failure.
446 : */
447 : struct spdk_thread *spdk_get_thread(void);
448 :
449 : /**
450 : * Get a thread's name.
451 : *
452 : * \param thread Thread to query.
453 : *
454 : * \return the name of the thread.
455 : */
456 : const char *spdk_thread_get_name(const struct spdk_thread *thread);
457 :
458 : /**
459 : * Get a thread's ID.
460 : *
461 : * \param thread Thread to query.
462 : *
463 : * \return the ID of the thread..
464 : */
465 : uint64_t spdk_thread_get_id(const struct spdk_thread *thread);
466 :
467 : /**
468 : * Get the thread by the ID.
469 : *
470 : * \param id ID of the thread.
471 : * \return Thread whose ID matches or NULL otherwise.
472 : */
473 : struct spdk_thread *spdk_thread_get_by_id(uint64_t id);
474 :
475 : struct spdk_thread_stats {
476 : uint64_t busy_tsc;
477 : uint64_t idle_tsc;
478 : };
479 :
480 : /**
481 : * Get statistics about the current thread.
482 : *
483 : * Copy cumulative thread stats values to the provided thread stats structure.
484 : *
485 : * \param stats User's thread_stats structure.
486 : */
487 : int spdk_thread_get_stats(struct spdk_thread_stats *stats);
488 :
489 : /**
490 : * Return the TSC value from the end of the last time this thread was polled.
491 : *
492 : * \param thread Thread to query. If NULL, use current thread.
493 : *
494 : * \return TSC value from the end of the last time this thread was polled.
495 : */
496 : uint64_t spdk_thread_get_last_tsc(struct spdk_thread *thread);
497 :
498 : /**
499 : * Send a message to the given thread.
500 : *
501 : * The message will be sent asynchronously - i.e. spdk_thread_send_msg will always return
502 : * prior to `fn` being called.
503 : *
504 : * \param thread The target thread.
505 : * \param fn This function will be called on the given thread.
506 : * \param ctx This context will be passed to fn when called.
507 : *
508 : * \return 0 on success
509 : * \return -ENOMEM if the message could not be allocated
510 : * \return -EIO if the message could not be sent to the destination thread
511 : */
512 : int spdk_thread_send_msg(const struct spdk_thread *thread, spdk_msg_fn fn, void *ctx);
513 :
514 : /**
515 : * Send a message to the given thread. Only one critical message can be outstanding at the same
516 : * time. It's intended to use this function in any cases that might interrupt the execution of the
517 : * application, such as signal handlers.
518 : *
519 : * The message will be sent asynchronously - i.e. spdk_thread_send_critical_msg will always return
520 : * prior to `fn` being called.
521 : *
522 : * \param thread The target thread.
523 : * \param fn This function will be called on the given thread.
524 : *
525 : * \return 0 on success
526 : * \return -EIO if the message could not be sent to the destination thread, due to an already
527 : * outstanding critical message
528 : */
529 : int spdk_thread_send_critical_msg(struct spdk_thread *thread, spdk_msg_fn fn);
530 :
531 : /**
532 : * Run the msg callback on the given thread. If this happens to be the current
533 : * thread, the callback is executed immediately; otherwise a message is sent to
534 : * the thread, and it's run asynchronously.
535 : *
536 : * \param thread The target thread.
537 : * \param fn This function will be called on the given thread.
538 : * \param ctx This context will be passed to fn when called.
539 : *
540 : * \return 0 on success
541 : * \return -ENOMEM if the message could not be allocated
542 : * \return -EIO if the message could not be sent to the destination thread
543 : */
544 : static inline int
545 117 : spdk_thread_exec_msg(const struct spdk_thread *thread, spdk_msg_fn fn, void *ctx)
546 : {
547 117 : assert(thread != NULL);
548 :
549 117 : if (spdk_get_thread() == thread) {
550 115 : fn(ctx);
551 115 : return 0;
552 : }
553 :
554 2 : return spdk_thread_send_msg(thread, fn, ctx);
555 : }
556 :
557 : /**
558 : * Send a message to each thread, serially.
559 : *
560 : * The message is sent asynchronously - i.e. spdk_for_each_thread will return
561 : * prior to `fn` being called on each thread.
562 : *
563 : * \param fn This is the function that will be called on each thread.
564 : * \param ctx This context will be passed to fn when called.
565 : * \param cpl This will be called on the originating thread after `fn` has been
566 : * called on each thread.
567 : */
568 : void spdk_for_each_thread(spdk_msg_fn fn, void *ctx, spdk_msg_fn cpl);
569 :
570 : /**
571 : * Set current spdk_thread into interrupt mode or back to poll mode.
572 : *
573 : * Only valid when thread interrupt facility is enabled by
574 : * spdk_interrupt_mode_enable().
575 : *
576 : * \param enable_interrupt Set interrupt mode for true, or poll mode for false
577 : */
578 : void spdk_thread_set_interrupt_mode(bool enable_interrupt);
579 :
580 : /**
581 : * Get trace id.
582 : *
583 : * \param thread Thread to get trace_id from.
584 : *
585 : * \return Trace id of the specified thread.
586 : */
587 : uint16_t spdk_thread_get_trace_id(struct spdk_thread *thread);
588 :
589 : /**
590 : * Register a poller on the current thread.
591 : *
592 : * The poller can be unregistered by calling spdk_poller_unregister().
593 : *
594 : * \param fn This function will be called every `period_microseconds`.
595 : * \param arg Argument passed to fn.
596 : * \param period_microseconds How often to call `fn`. If 0, call `fn` as often
597 : * as possible.
598 : *
599 : * \return a pointer to the poller registered on the current thread on success
600 : * or NULL on failure.
601 : */
602 : struct spdk_poller *spdk_poller_register(spdk_poller_fn fn,
603 : void *arg,
604 : uint64_t period_microseconds);
605 :
606 : /**
607 : * Register a poller on the current thread with arbitrary name.
608 : *
609 : * The poller can be unregistered by calling spdk_poller_unregister().
610 : *
611 : * \param fn This function will be called every `period_microseconds`.
612 : * \param arg Argument passed to fn.
613 : * \param period_microseconds How often to call `fn`. If 0, call `fn` as often
614 : * as possible.
615 : * \param name Human readable name for the poller. Pointer of the poller function
616 : * name is set if NULL.
617 : *
618 : * \return a pointer to the poller registered on the current thread on success
619 : * or NULL on failure.
620 : */
621 : struct spdk_poller *spdk_poller_register_named(spdk_poller_fn fn,
622 : void *arg,
623 : uint64_t period_microseconds,
624 : const char *name);
625 :
626 : /*
627 : * \brief Register a poller on the current thread with setting its name
628 : * to the string of the poller function name. The poller being registered
629 : * should return a value of type `enum spdk_thread_poller_rc`. See
630 : * \ref spdk_poller_fn for more information.
631 : */
632 : #define SPDK_POLLER_REGISTER(fn, arg, period_microseconds) \
633 : spdk_poller_register_named(fn, arg, period_microseconds, #fn)
634 :
635 : /**
636 : * Unregister a poller on the current thread.
637 : *
638 : * This function will also write NULL to the spdk_poller pointer pointed
639 : * to by ppoller, to help encourage a poller pointer not getting reused
640 : * after it has been unregistered.
641 : *
642 : * It is OK to pass a ppoller parameter that points to NULL, in this case
643 : * the function is a nop.
644 : *
645 : * \param ppoller The poller to unregister.
646 : */
647 : void spdk_poller_unregister(struct spdk_poller **ppoller);
648 :
649 : /**
650 : * Pause a poller on the current thread.
651 : *
652 : * The poller is not run until it is resumed with spdk_poller_resume(). It is
653 : * perfectly fine to pause an already paused poller.
654 : *
655 : * \param poller The poller to pause.
656 : */
657 : void spdk_poller_pause(struct spdk_poller *poller);
658 :
659 : /**
660 : * Resume a poller on the current thread.
661 : *
662 : * Resumes a poller paused with spdk_poller_pause(). It is perfectly fine to
663 : * resume an unpaused poller.
664 : *
665 : * \param poller The poller to resume.
666 : */
667 : void spdk_poller_resume(struct spdk_poller *poller);
668 :
669 : /**
670 : * Register the opaque io_device context as an I/O device.
671 : *
672 : * After an I/O device is registered, it can return I/O channels using the
673 : * spdk_get_io_channel() function.
674 : *
675 : * \param io_device The pointer to io_device context.
676 : * \param create_cb Callback function invoked to allocate any resources required
677 : * for a new I/O channel.
678 : * \param destroy_cb Callback function invoked to release the resources for an
679 : * I/O channel.
680 : * \param ctx_size The size of the context buffer allocated to store references
681 : * to allocated I/O channel resources.
682 : * \param name A string name for the device used only for debugging. Optional -
683 : * may be NULL.
684 : */
685 : void spdk_io_device_register(void *io_device, spdk_io_channel_create_cb create_cb,
686 : spdk_io_channel_destroy_cb destroy_cb, uint32_t ctx_size,
687 : const char *name);
688 :
689 : /**
690 : * Unregister the opaque io_device context as an I/O device.
691 : *
692 : * The actual unregistration might be deferred until all active I/O channels are
693 : * destroyed.
694 : *
695 : * \param io_device The pointer to io_device context.
696 : * \param unregister_cb An optional callback function invoked to release any
697 : * references to this I/O device.
698 : */
699 : void spdk_io_device_unregister(void *io_device, spdk_io_device_unregister_cb unregister_cb);
700 :
701 : /**
702 : * Get an I/O channel for the specified io_device to be used by the calling thread.
703 : *
704 : * The io_device context pointer specified must have previously been registered
705 : * using spdk_io_device_register(). If an existing I/O channel does not exist
706 : * yet for the given io_device on the calling thread, it will allocate an I/O
707 : * channel and invoke the create_cb function pointer specified in spdk_io_device_register().
708 : * If an I/O channel already exists for the given io_device on the calling thread,
709 : * its reference is returned rather than creating a new I/O channel.
710 : *
711 : * \param io_device The pointer to io_device context.
712 : *
713 : * \return a pointer to the I/O channel for this device on success or NULL on failure.
714 : */
715 : struct spdk_io_channel *spdk_get_io_channel(void *io_device);
716 :
717 : /**
718 : * Release a reference to an I/O channel. This happens asynchronously.
719 : *
720 : * This must be called on the same thread that called spdk_get_io_channel()
721 : * for the specified I/O channel. If this releases the last reference to the
722 : * I/O channel, The destroy_cb function specified in spdk_io_device_register()
723 : * will be invoked to release any associated resources.
724 : *
725 : * \param ch I/O channel to release a reference.
726 : */
727 : void spdk_put_io_channel(struct spdk_io_channel *ch);
728 :
729 : /**
730 : * Get the context buffer associated with an I/O channel.
731 : *
732 : * \param ch I/O channel.
733 : *
734 : * \return a pointer to the context buffer.
735 : */
736 : static inline void *
737 111550 : spdk_io_channel_get_ctx(struct spdk_io_channel *ch)
738 : {
739 111550 : if (spdk_unlikely(!ch)) {
740 0 : assert(false);
741 : return NULL;
742 : }
743 :
744 111550 : return (uint8_t *)ch + SPDK_IO_CHANNEL_STRUCT_SIZE;
745 : }
746 :
747 : /**
748 : * Get I/O channel from the context buffer. This is the inverse of
749 : * spdk_io_channel_get_ctx().
750 : *
751 : * \param ctx The pointer to the context buffer.
752 : *
753 : * \return a pointer to the I/O channel associated with the context buffer.
754 : */
755 : struct spdk_io_channel *spdk_io_channel_from_ctx(void *ctx);
756 :
757 : /**
758 : * Get the thread associated with an I/O channel.
759 : *
760 : * \param ch I/O channel.
761 : *
762 : * \return a pointer to the thread associated with the I/O channel
763 : */
764 : struct spdk_thread *spdk_io_channel_get_thread(struct spdk_io_channel *ch);
765 :
766 : /**
767 : * Call 'fn' on each channel associated with io_device.
768 : *
769 : * This happens asynchronously, so fn may be called after spdk_for_each_channel
770 : * returns. 'fn' will be called for each channel serially, such that two calls
771 : * to 'fn' will not overlap in time. After 'fn' has been called, call
772 : * spdk_for_each_channel_continue() to continue iterating.
773 : *
774 : * \param io_device 'fn' will be called on each channel associated with this io_device.
775 : * \param fn Called on the appropriate thread for each channel associated with io_device.
776 : * \param ctx Context buffer registered to spdk_io_channel_iter that can be obtained
777 : * form the function spdk_io_channel_iter_get_ctx().
778 : * \param cpl Called on the thread that spdk_for_each_channel was initially called
779 : * from when 'fn' has been called on each channel.
780 : */
781 : void spdk_for_each_channel(void *io_device, spdk_channel_msg fn, void *ctx,
782 : spdk_channel_for_each_cpl cpl);
783 :
784 : /**
785 : * Get io_device from the I/O channel iterator.
786 : *
787 : * \param i I/O channel iterator.
788 : *
789 : * \return a pointer to the io_device.
790 : */
791 : void *spdk_io_channel_iter_get_io_device(struct spdk_io_channel_iter *i);
792 :
793 : /**
794 : * Get I/O channel from the I/O channel iterator.
795 : *
796 : * \param i I/O channel iterator.
797 : *
798 : * \return a pointer to the I/O channel.
799 : */
800 : struct spdk_io_channel *spdk_io_channel_iter_get_channel(struct spdk_io_channel_iter *i);
801 :
802 : /**
803 : * Get context buffer from the I/O channel iterator.
804 : *
805 : * \param i I/O channel iterator.
806 : *
807 : * \return a pointer to the context buffer.
808 : */
809 : void *spdk_io_channel_iter_get_ctx(struct spdk_io_channel_iter *i);
810 :
811 : /**
812 : * Get the io_device for the specified I/O channel.
813 : *
814 : * \param ch I/O channel.
815 : *
816 : * \return a pointer to the io_device for the I/O channel
817 : */
818 : void *spdk_io_channel_get_io_device(struct spdk_io_channel *ch);
819 :
820 : /**
821 : * Helper function to iterate all channels for spdk_for_each_channel().
822 : *
823 : * \param i I/O channel iterator.
824 : * \param status Status for the I/O channel iterator;
825 : * for non 0 status remaining iterations are terminated.
826 : */
827 : void spdk_for_each_channel_continue(struct spdk_io_channel_iter *i, int status);
828 :
829 : /**
830 : * A representative for registered interrupt file descriptor.
831 : */
832 : struct spdk_interrupt;
833 :
834 : /**
835 : * Callback function registered for interrupt file descriptor.
836 : *
837 : * \param ctx Context passed as arg to spdk_interrupt_register().
838 : *
839 : * \return 0 to indicate that interrupt took place but no events were found;
840 : * positive to indicate that interrupt took place and some events were processed;
841 : * negative if no event information is provided.
842 : */
843 : typedef int (*spdk_interrupt_fn)(void *ctx);
844 :
845 : /**
846 : * Register an spdk_interrupt on the current thread.
847 : *
848 : * The provided function will be called any time a SPDK_INTERRUPT_EVENT_IN event
849 : * triggers on the associated file descriptor.
850 : *
851 : * \param efd File descriptor of the spdk_interrupt.
852 : * \param fn Called each time there are events in spdk_interrupt.
853 : * \param arg Function argument for fn.
854 : * \param name Human readable name for the spdk_interrupt. Pointer of the spdk_interrupt
855 : * name is set if NULL.
856 : *
857 : * \return a pointer to the spdk_interrupt registered on the current thread on success
858 : * or NULL on failure.
859 : */
860 : struct spdk_interrupt *spdk_interrupt_register(int efd, spdk_interrupt_fn fn,
861 : void *arg, const char *name);
862 :
863 : /**
864 : * Register an spdk_interrupt with specific event types on the current thread.
865 : *
866 : * The provided function will be called any time one of specified event types triggers on
867 : * the associated file descriptor.
868 : * Event types argument is a bit mask composed by ORing together
869 : * enum spdk_interrupt_event_types values.
870 : *
871 : * \param efd File descriptor of the spdk_interrupt.
872 : * \param events Event notification types.
873 : * \param fn Called each time there are events in spdk_interrupt.
874 : * \param arg Function argument for fn.
875 : * \param name Human readable name for the spdk_interrupt. Pointer of the spdk_interrupt
876 : * name is set if NULL.
877 : *
878 : * \return a pointer to the spdk_interrupt registered on the current thread on success
879 : * or NULL on failure.
880 : */
881 : struct spdk_interrupt *spdk_interrupt_register_for_events(int efd, uint32_t events,
882 : spdk_interrupt_fn fn, void *arg, const char *name);
883 :
884 : /**
885 : * Register an spdk_interrupt with specific event type stated in spdk_event_handler_opts argument
886 : * on the current thread.
887 : *
888 : * The provided function will be called any time one of specified event types from
889 : * spdk_event_handler_opts argument triggers on the associated file descriptor.
890 : * Event types argument in spdk_event_handler_opts is a bit mask composed by ORing together
891 : * enum spdk_interrupt_event_types values.
892 : *
893 : * \param efd File descriptor of the spdk_interrupt.
894 : * \param fn Called each time there are events in spdk_interrupt.
895 : * \param arg Function argument for fn.
896 : * \param name Human readable name for the spdk_interrupt. Pointer of the spdk_interrupt
897 : * name is set if NULL.
898 : * \param opts Extended event handler option.
899 : *
900 : * \return a pointer to the spdk_interrupt registered on the current thread on success
901 : * or NULL on failure.
902 : */
903 : struct spdk_interrupt *spdk_interrupt_register_ext(int efd, spdk_interrupt_fn fn, void *arg,
904 : const char *name, struct spdk_event_handler_opts *opts);
905 :
906 : /*
907 : * \brief Register an spdk_interrupt on the current thread with setting its name
908 : * to the string of the spdk_interrupt function name.
909 : */
910 : #define SPDK_INTERRUPT_REGISTER(efd, fn, arg) \
911 : spdk_interrupt_register(efd, fn, arg, #fn)
912 :
913 : /*
914 : * \brief Register an spdk_interrupt on the current thread with specific event types
915 : * and with setting its name to the string of the spdk_interrupt function name.
916 : */
917 : #define SPDK_INTERRUPT_REGISTER_FOR_EVENTS(efd, events, fn, arg) \
918 : spdk_interrupt_register_for_events(efd, events, fn, arg, #fn)
919 :
920 : /*
921 : * \brief Register an spdk_interrupt on the current thread with specific event types provided
922 : * in opts and with setting its name to the string of the spdk_interrupt function name.
923 : */
924 : #define SPDK_INTERRUPT_REGISTER_EXT(efd, fn, arg, opts) \
925 : spdk_interrupt_register_ext(efd, fn, arg, #fn, opts)
926 :
927 : /**
928 : * Register an interrupt listening for all events associated with an fd_group on current thread.
929 : *
930 : * \param fgrp fd_group describing the events to listen for.
931 : * \param name Name of the interrupt.
932 : *
933 : * return Pointer to spdk_interrupt or NULL in case of failure.
934 : */
935 : struct spdk_interrupt *spdk_interrupt_register_fd_group(struct spdk_fd_group *fgrp,
936 : const char *name);
937 :
938 : /**
939 : * Unregister an spdk_interrupt on the current thread.
940 : *
941 : * \param pintr The spdk_interrupt to unregister.
942 : */
943 : void spdk_interrupt_unregister(struct spdk_interrupt **pintr);
944 :
945 : enum spdk_interrupt_event_types {
946 : #ifdef __linux__
947 : SPDK_INTERRUPT_EVENT_IN = EPOLLIN,
948 : SPDK_INTERRUPT_EVENT_OUT = EPOLLOUT,
949 : SPDK_INTERRUPT_EVENT_ET = EPOLLET
950 : #else
951 : SPDK_INTERRUPT_EVENT_IN = 0x001,
952 : SPDK_INTERRUPT_EVENT_OUT = 0x004,
953 : SPDK_INTERRUPT_EVENT_ET = 1u << 31
954 : #endif
955 : };
956 :
957 : /**
958 : * Change the event_types associated with the spdk_interrupt on the current thread.
959 : *
960 : * \param intr The pointer to the spdk_interrupt registered on the current thread.
961 : * \param event_types New event_types for the spdk_interrupt.
962 : *
963 : * \return 0 if success or -errno if failed.
964 : */
965 : int spdk_interrupt_set_event_types(struct spdk_interrupt *intr,
966 : enum spdk_interrupt_event_types event_types);
967 :
968 : /**
969 : * Return a file descriptor that becomes ready whenever any of the registered
970 : * interrupt file descriptors are ready
971 : *
972 : * \param thread The thread to get.
973 : *
974 : * \return The spdk_interrupt fd of thread itself.
975 : */
976 : int spdk_thread_get_interrupt_fd(struct spdk_thread *thread);
977 :
978 : /**
979 : * Return an fd_group that becomes ready whenever any of the registered
980 : * interrupt file descriptors are ready
981 : *
982 : *
983 : * \param thread The thread to get.
984 : *
985 : * \return The spdk_fd_group of the thread itself.
986 : */
987 : struct spdk_fd_group *spdk_thread_get_interrupt_fd_group(struct spdk_thread *thread);
988 :
989 : /**
990 : * Set SPDK run as event driven mode
991 : *
992 : * \return 0 on success or -errno on failure
993 : */
994 : int spdk_interrupt_mode_enable(void);
995 :
996 : /**
997 : * Reports whether interrupt mode is set.
998 : *
999 : * \return True if interrupt mode is set, false otherwise.
1000 : */
1001 : bool spdk_interrupt_mode_is_enabled(void);
1002 :
1003 : /**
1004 : * A spinlock augmented with safety checks for use with SPDK.
1005 : *
1006 : * SPDK code that uses spdk_spinlock runs from an SPDK thread, which itself is associated with a
1007 : * pthread. There are typically many SPDK threads associated with each pthread. The SPDK application
1008 : * may migrate SPDK threads between pthreads from time to time to balance the load on those threads.
1009 : * Migration of SPDK threads only happens when the thread is off CPU, and as such it is only safe to
1010 : * hold a lock so long as an SPDK thread stays on CPU.
1011 : *
1012 : * It is not safe to lock a spinlock, return from the event or poller, then unlock it at some later
1013 : * time because:
1014 : *
1015 : * - Even though the SPDK thread may be the same, the SPDK thread may be running on different
1016 : * pthreads during lock and unlock. A pthread spinlock may consider this to be an unlock by a
1017 : * non-owner, which results in undefined behavior.
1018 : * - A lock that is acquired by a poller or event may be needed by another poller or event that
1019 : * runs on the same pthread. This can lead to deadlock or detection of deadlock.
1020 : * - A lock that is acquired by a poller or event that is needed by another poller or event that
1021 : * runs on a second pthread will block the second pthread from doing any useful work until the
1022 : * lock is released. Because the lock holder and the lock acquirer are on the same pthread, this
1023 : * would lead to deadlock.
1024 : *
1025 : * If an SPDK spinlock is used erroneously, the program will abort.
1026 : */
1027 : struct spdk_spinlock {
1028 : pthread_spinlock_t spinlock;
1029 : struct spdk_thread *thread;
1030 : struct spdk_spinlock_internal *internal;
1031 : bool initialized;
1032 : bool destroyed;
1033 : };
1034 :
1035 : /**
1036 : * Initialize an spdk_spinlock.
1037 : *
1038 : * \param sspin The SPDK spinlock to initialize.
1039 : */
1040 : void spdk_spin_init(struct spdk_spinlock *sspin);
1041 :
1042 : /**
1043 : * Destroy an spdk_spinlock.
1044 : *
1045 : * \param sspin The SPDK spinlock to initialize.
1046 : */
1047 : void spdk_spin_destroy(struct spdk_spinlock *sspin);
1048 :
1049 : /**
1050 : * Lock an SPDK spin lock.
1051 : *
1052 : * \param sspin An SPDK spinlock.
1053 : */
1054 : void spdk_spin_lock(struct spdk_spinlock *sspin);
1055 :
1056 : /**
1057 : * Unlock an SPDK spinlock.
1058 : *
1059 : * \param sspin An SPDK spinlock.
1060 : */
1061 : void spdk_spin_unlock(struct spdk_spinlock *sspin);
1062 :
1063 : /**
1064 : * Determine if the caller holds this SPDK spinlock.
1065 : *
1066 : * \param sspin An SPDK spinlock.
1067 : * \return true if spinlock is held by this thread, else false
1068 : */
1069 : bool spdk_spin_held(struct spdk_spinlock *sspin);
1070 :
1071 : struct spdk_iobuf_opts {
1072 : /** Maximum number of small buffers */
1073 : uint64_t small_pool_count;
1074 : /** Maximum number of large buffers */
1075 : uint64_t large_pool_count;
1076 : /** Size of a single small buffer */
1077 : uint32_t small_bufsize;
1078 : /** Size of a single large buffer */
1079 : uint32_t large_bufsize;
1080 :
1081 : /**
1082 : * The size of spdk_iobuf_opts according to the caller of this library is used for ABI
1083 : * compatibility. The library uses this field to know how many fields in this
1084 : * structure are valid. And the library will populate any remaining fields with default values.
1085 : * New added fields should be put at the end of the struct.
1086 : */
1087 : size_t opts_size;
1088 :
1089 : /** Enable per-NUMA node buffer pools */
1090 : uint8_t enable_numa;
1091 : };
1092 :
1093 : struct spdk_iobuf_pool_stats {
1094 : /** Buffer got from local per-thread cache */
1095 : uint64_t cache;
1096 : /** Buffer got from the main shared pool */
1097 : uint64_t main;
1098 : /** Buffer missed and request to get buffer was queued */
1099 : uint64_t retry;
1100 : };
1101 :
1102 : struct spdk_iobuf_module_stats {
1103 : struct spdk_iobuf_pool_stats small_pool;
1104 : struct spdk_iobuf_pool_stats large_pool;
1105 : const char *module;
1106 : };
1107 :
1108 : struct spdk_iobuf_entry;
1109 :
1110 : typedef void (*spdk_iobuf_get_cb)(struct spdk_iobuf_entry *entry, void *buf);
1111 :
1112 : /** iobuf queue entry */
1113 : struct spdk_iobuf_entry {
1114 : spdk_iobuf_get_cb cb_fn;
1115 : const void *module;
1116 : STAILQ_ENTRY(spdk_iobuf_entry) stailq;
1117 : };
1118 :
1119 : struct spdk_iobuf_buffer {
1120 : STAILQ_ENTRY(spdk_iobuf_buffer) stailq;
1121 : };
1122 :
1123 : typedef STAILQ_HEAD(, spdk_iobuf_entry) spdk_iobuf_entry_stailq_t;
1124 : typedef STAILQ_HEAD(, spdk_iobuf_buffer) spdk_iobuf_buffer_stailq_t;
1125 :
1126 : struct spdk_iobuf_pool_cache {
1127 : /** Buffer pool */
1128 : struct spdk_ring *pool;
1129 : /** Buffer cache */
1130 : spdk_iobuf_buffer_stailq_t cache;
1131 : /** Number of elements in the cache */
1132 : uint32_t cache_count;
1133 : /** Size of the cache */
1134 : uint32_t cache_size;
1135 : /** Buffer wait queue */
1136 : spdk_iobuf_entry_stailq_t *queue;
1137 : /** Buffer size */
1138 : uint32_t bufsize;
1139 : /** Pool usage statistics */
1140 : struct spdk_iobuf_pool_stats stats;
1141 : };
1142 :
1143 : struct spdk_iobuf_node_cache {
1144 : /** Small buffer memory pool cache */
1145 : struct spdk_iobuf_pool_cache small;
1146 : /** Large buffer memory pool cache */
1147 : struct spdk_iobuf_pool_cache large;
1148 : };
1149 :
1150 : #ifndef SPDK_CONFIG_MAX_NUMA_NODES
1151 : /* Set this default temporarily, for users that may pull latest code without
1152 : * re-running configure.
1153 : */
1154 : #define SPDK_CONFIG_MAX_NUMA_NODES 1
1155 : #endif
1156 :
1157 : /** iobuf channel */
1158 : struct spdk_iobuf_channel {
1159 : /** Module pointer */
1160 : const void *module;
1161 : /** Parent IO channel */
1162 : struct spdk_io_channel *parent;
1163 : /* Buffer cache */
1164 : struct spdk_iobuf_node_cache cache[SPDK_CONFIG_MAX_NUMA_NODES];
1165 : };
1166 :
1167 : /**
1168 : * Initialize and allocate iobuf pools.
1169 : *
1170 : * \return 0 on success, negative errno otherwise.
1171 : */
1172 : int spdk_iobuf_initialize(void);
1173 :
1174 : typedef void (*spdk_iobuf_finish_cb)(void *cb_arg);
1175 :
1176 : /**
1177 : * Clean up and free iobuf pools.
1178 : *
1179 : * \param cb_fn Callback to be executed once the clean up is completed.
1180 : * \param cb_arg Callback argument.
1181 : */
1182 : void spdk_iobuf_finish(spdk_iobuf_finish_cb cb_fn, void *cb_arg);
1183 :
1184 : /**
1185 : * Set iobuf options. These options will be used during `spdk_iobuf_initialize()`.
1186 : *
1187 : * \param opts Options describing the size of the pools to reserve.
1188 : *
1189 : * \return 0 on success, negative errno otherwise.
1190 : */
1191 : int spdk_iobuf_set_opts(const struct spdk_iobuf_opts *opts);
1192 :
1193 : /**
1194 : * Get iobuf options.
1195 : *
1196 : * \param opts Output parameter for options.
1197 : * \param opts_size sizeof(*opts)
1198 : */
1199 : void spdk_iobuf_get_opts(struct spdk_iobuf_opts *opts, size_t opts_size);
1200 :
1201 : /**
1202 : * Register a module as an iobuf pool user. Only registered users can request buffers from the
1203 : * iobuf pool.
1204 : *
1205 : * \name Name of the module.
1206 : *
1207 : * \return 0 on success, negative errno otherwise.
1208 : */
1209 : int spdk_iobuf_register_module(const char *name);
1210 :
1211 : /**
1212 : * Unregister an iobuf pool user from a module.
1213 : *
1214 : * \name Name of the module.
1215 : *
1216 : * \return 0 on success, negative errno otherwise.
1217 : */
1218 : int spdk_iobuf_unregister_module(const char *name);
1219 :
1220 : /**
1221 : * Initialize an iobuf channel.
1222 : *
1223 : * \param ch iobuf channel to initialize.
1224 : * \param name Name of the module registered via `spdk_iobuf_register_module()`.
1225 : * \param small_cache_size Number of small buffers to be cached by this channel.
1226 : * \param large_cache_size Number of large buffers to be cached by this channel.
1227 : *
1228 : * \return 0 on success, negative errno otherwise.
1229 : */
1230 : int spdk_iobuf_channel_init(struct spdk_iobuf_channel *ch, const char *name,
1231 : uint32_t small_cache_size, uint32_t large_cache_size);
1232 :
1233 : /**
1234 : * Release resources tied to an iobuf channel.
1235 : *
1236 : * \param ch iobuf channel.
1237 : */
1238 : void spdk_iobuf_channel_fini(struct spdk_iobuf_channel *ch);
1239 :
1240 : typedef int (*spdk_iobuf_for_each_entry_fn)(struct spdk_iobuf_channel *ch,
1241 : struct spdk_iobuf_entry *entry, void *ctx);
1242 :
1243 : /**
1244 : * Iterate over all entries on a given channel and execute a callback on those that were requested.
1245 : * The iteration is stopped if the callback returns non-zero status.
1246 : *
1247 : * \param ch iobuf channel to iterate over.
1248 : * \param cb_fn Callback to execute on each entry on the channel that was requested.
1249 : * \param cb_ctx Argument passed to `cb_fn`.
1250 : *
1251 : * \return status of the last callback.
1252 : */
1253 : int spdk_iobuf_for_each_entry(struct spdk_iobuf_channel *ch,
1254 : spdk_iobuf_for_each_entry_fn cb_fn, void *cb_ctx);
1255 :
1256 : /**
1257 : * Abort an outstanding request waiting for a buffer.
1258 : *
1259 : * \param ch iobuf channel on which the entry is waiting.
1260 : * \param entry Entry to remove from the wait queue.
1261 : * \param len Length of the requested buffer (must be the exact same value as specified in
1262 : * `spdk_iobuf_get()`.
1263 : */
1264 : void spdk_iobuf_entry_abort(struct spdk_iobuf_channel *ch, struct spdk_iobuf_entry *entry,
1265 : uint64_t len);
1266 :
1267 : /**
1268 : * Get a buffer from the iobuf pool. If no buffers are available and entry with cb_fn provided
1269 : * then the request is queued until a buffer becomes available.
1270 : *
1271 : * \param ch iobuf channel.
1272 : * \param len Length of the buffer to retrieve. The user is responsible for making sure the length
1273 : * doesn't exceed large_bufsize.
1274 : * \param entry Wait queue entry (optional).
1275 : * \param cb_fn Callback to be executed once a buffer becomes available. If a buffer is available
1276 : * immediately, it is NOT executed. Mandatory only if entry provided.
1277 : *
1278 : * \return pointer to a buffer or NULL if no buffers are currently available.
1279 : */
1280 : void *spdk_iobuf_get(struct spdk_iobuf_channel *ch, uint64_t len, struct spdk_iobuf_entry *entry,
1281 : spdk_iobuf_get_cb cb_fn);
1282 :
1283 : /**
1284 : * Release a buffer back to the iobuf pool. If there are outstanding requests waiting for a buffer,
1285 : * this buffer will be passed to one of them.
1286 : *
1287 : * \param ch iobuf channel.
1288 : * \param buf Buffer to release
1289 : * \param len Length of the buffer (must be the exact same value as specified in `spdk_iobuf_get()`).
1290 : */
1291 : void spdk_iobuf_put(struct spdk_iobuf_channel *ch, void *buf, uint64_t len);
1292 :
1293 : typedef void (*spdk_iobuf_get_stats_cb)(struct spdk_iobuf_module_stats *modules,
1294 : uint32_t num_modules, void *cb_arg);
1295 :
1296 : /**
1297 : * Get iobuf statistics.
1298 : *
1299 : * \param cb_fn Callback to be executed once stats are gathered.
1300 : * \param cb_arg Argument passed to the callback function.
1301 : *
1302 : * \return 0 on success, negative errno otherwise.
1303 : */
1304 : int spdk_iobuf_get_stats(spdk_iobuf_get_stats_cb cb_fn, void *cb_arg);
1305 :
1306 : typedef void (*spdk_post_poller_fn)(void *fn_arg);
1307 :
1308 : /**
1309 : * Register a function to be called after the current SPDK poller has completed. Once called,
1310 : * this function is de-registered and won't called until the next registration call.
1311 : *
1312 : * \param fn Function to call
1313 : * \param fn_arg Function argument
1314 : */
1315 : void spdk_thread_register_post_poller_handler(spdk_post_poller_fn fn, void *fn_arg);
1316 :
1317 : #ifdef __cplusplus
1318 : }
1319 : #endif
1320 :
1321 : #endif /* SPDK_THREAD_H_ */
|
