1 /*- 2 * BSD LICENSE 3 * 4 * Copyright (c) Intel Corporation. 5 * All rights reserved. 6 * 7 * Redistribution and use in source and binary forms, with or without 8 * modification, are permitted provided that the following conditions 9 * are met: 10 * 11 * * Redistributions of source code must retain the above copyright 12 * notice, this list of conditions and the following disclaimer. 13 * * Redistributions in binary form must reproduce the above copyright 14 * notice, this list of conditions and the following disclaimer in 15 * the documentation and/or other materials provided with the 16 * distribution. 17 * * Neither the name of Intel Corporation nor the names of its 18 * contributors may be used to endorse or promote products derived 19 * from this software without specific prior written permission. 20 * 21 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 22 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 23 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 24 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 25 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 26 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 27 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 28 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 29 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 30 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 31 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 32 */ 33 34 /** \file 35 * Thread 36 */ 37 38 #ifndef SPDK_THREAD_H_ 39 #define SPDK_THREAD_H_ 40 41 #include "spdk/stdinc.h" 42 43 #include "spdk/cpuset.h" 44 #include "spdk/queue.h" 45 46 #ifdef __cplusplus 47 extern "C" { 48 #endif 49 50 enum spdk_thread_poller_rc { 51 SPDK_POLLER_IDLE, 52 SPDK_POLLER_BUSY, 53 }; 54 55 /** 56 * A stackless, lightweight thread. 57 */ 58 struct spdk_thread; 59 60 /** 61 * A function repeatedly called on the same spdk_thread. 62 */ 63 struct spdk_poller; 64 65 struct spdk_io_channel_iter; 66 67 /** 68 * A function that is called each time a new thread is created. 69 * The implementor of this function should frequently call 70 * spdk_thread_poll() on the thread provided. 71 * 72 * \param thread The new spdk_thread. 73 */ 74 typedef int (*spdk_new_thread_fn)(struct spdk_thread *thread); 75 76 /** 77 * SPDK thread operation type. 78 */ 79 enum spdk_thread_op { 80 /* Called each time a new thread is created. The implementor of this operation 81 * should frequently call spdk_thread_poll() on the thread provided. 82 */ 83 SPDK_THREAD_OP_NEW, 84 85 /* Called when SPDK thread needs to be rescheduled. (e.g., when cpumask of the 86 * SPDK thread is updated. 87 */ 88 SPDK_THREAD_OP_RESCHED, 89 }; 90 91 /** 92 * Function to be called for SPDK thread operation. 93 */ 94 typedef int (*spdk_thread_op_fn)(struct spdk_thread *thread, enum spdk_thread_op op); 95 96 /** 97 * Function to check whether the SPDK thread operation is supported. 98 */ 99 typedef bool (*spdk_thread_op_supported_fn)(enum spdk_thread_op op); 100 101 /** 102 * A function that will be called on the target thread. 103 * 104 * \param ctx Context passed as arg to spdk_thread_pass_msg(). 105 */ 106 typedef void (*spdk_msg_fn)(void *ctx); 107 108 /** 109 * Function to be called to pass a message to a thread. 110 * 111 * \param fn Callback function for a thread. 112 * \param ctx Context passed to fn. 113 * \param thread_ctx Context for the thread. 114 */ 115 typedef void (*spdk_thread_pass_msg)(spdk_msg_fn fn, void *ctx, 116 void *thread_ctx); 117 118 /** 119 * Callback function for a poller. 120 * 121 * \param ctx Context passed as arg to spdk_poller_register(). 122 * \return 0 to indicate that polling took place but no events were found; 123 * positive to indicate that polling took place and some events were processed; 124 * negative if the poller does not provide spin-wait information. 125 */ 126 typedef int (*spdk_poller_fn)(void *ctx); 127 128 /** 129 * Function to be called to start a poller for the thread. 130 * 131 * \param thread_ctx Context for the thread. 132 * \param fn Callback function for a poller. 133 * \param arg Argument passed to callback. 134 * \param period_microseconds Polling period in microseconds. 135 * 136 * \return a pointer to the poller on success, or NULL on failure. 137 */ 138 typedef struct spdk_poller *(*spdk_start_poller)(void *thread_ctx, 139 spdk_poller_fn fn, 140 void *arg, 141 uint64_t period_microseconds); 142 143 /** 144 * Function to be called to stop a poller. 145 * 146 * \param poller Poller to stop. 147 * \param thread_ctx Context for the thread. 148 */ 149 typedef void (*spdk_stop_poller)(struct spdk_poller *poller, void *thread_ctx); 150 151 /** 152 * Callback function to set poller into interrupt mode or back to poll mode. 153 * 154 * \param poller Poller to set interrupt or poll mode. 155 * \param cb_arg Argument passed to the callback function. 156 * \param interrupt_mode Set interrupt mode for true, or poll mode for false 157 */ 158 typedef void (*spdk_poller_set_interrupt_mode_cb)(struct spdk_poller *poller, void *cb_arg, 159 bool interrupt_mode); 160 161 /** 162 * Mark that the poller is capable of entering interrupt mode. 163 * 164 * When registering the poller set interrupt callback, the callback will get 165 * executed immediately if its spdk_thread is in the interrupt mode. 166 * 167 * \param poller The poller to register callback function. 168 * \param cb_fn Callback function called when the poller must transition into or out of interrupt mode 169 * \param cb_arg Argument passed to the callback function. 170 */ 171 void spdk_poller_register_interrupt(struct spdk_poller *poller, 172 spdk_poller_set_interrupt_mode_cb cb_fn, 173 void *cb_arg); 174 175 /** 176 * I/O channel creation callback. 177 * 178 * \param io_device I/O device associated with this channel. 179 * \param ctx_buf Context for the I/O device. 180 */ 181 typedef int (*spdk_io_channel_create_cb)(void *io_device, void *ctx_buf); 182 183 /** 184 * I/O channel destruction callback. 185 * 186 * \param io_device I/O device associated with this channel. 187 * \param ctx_buf Context for the I/O device. 188 */ 189 typedef void (*spdk_io_channel_destroy_cb)(void *io_device, void *ctx_buf); 190 191 /** 192 * I/O device unregister callback. 193 * 194 * \param io_device Unregistered I/O device. 195 */ 196 typedef void (*spdk_io_device_unregister_cb)(void *io_device); 197 198 /** 199 * Called on the appropriate thread for each channel associated with io_device. 200 * 201 * \param i I/O channel iterator. 202 */ 203 typedef void (*spdk_channel_msg)(struct spdk_io_channel_iter *i); 204 205 /** 206 * spdk_for_each_channel() callback. 207 * 208 * \param i I/O channel iterator. 209 * \param status 0 if it completed successfully, or negative errno if it failed. 210 */ 211 typedef void (*spdk_channel_for_each_cpl)(struct spdk_io_channel_iter *i, int status); 212 213 /** 214 * \brief Represents a per-thread channel for accessing an I/O device. 215 * 216 * An I/O device may be a physical entity (i.e. NVMe controller) or a software 217 * entity (i.e. a blobstore). 218 * 219 * This structure is not part of the API - all accesses should be done through 220 * spdk_io_channel function calls. 221 */ 222 struct spdk_io_channel { 223 struct spdk_thread *thread; 224 struct io_device *dev; 225 uint32_t ref; 226 uint32_t destroy_ref; 227 TAILQ_ENTRY(spdk_io_channel) tailq; 228 spdk_io_channel_destroy_cb destroy_cb; 229 230 /* 231 * Modules will allocate extra memory off the end of this structure 232 * to store references to hardware-specific references (i.e. NVMe queue 233 * pairs, or references to child device spdk_io_channels (i.e. 234 * virtual bdevs). 235 */ 236 }; 237 238 /** 239 * Initialize the threading library. Must be called once prior to allocating any threads. 240 * 241 * \param new_thread_fn Called each time a new SPDK thread is created. The implementor 242 * is expected to frequently call spdk_thread_poll() on the provided thread. 243 * \param ctx_sz For each thread allocated, an additional region of memory of 244 * size ctx_size will also be allocated, for use by the thread scheduler. A pointer 245 * to this region may be obtained by calling spdk_thread_get_ctx(). 246 * 247 * \return 0 on success. Negated errno on failure. 248 */ 249 int spdk_thread_lib_init(spdk_new_thread_fn new_thread_fn, size_t ctx_sz); 250 251 /** 252 * Initialize the threading library. Must be called once prior to allocating any threads 253 * 254 * Both thread_op_fn and thread_op_type_supported_fn have to be specified or not 255 * specified together. 256 * 257 * \param thread_op_fn Called for SPDK thread operation. 258 * \param thread_op_supported_fn Called to check whether the SPDK thread operation is supported. 259 * \param ctx_sz For each thread allocated, for use by the thread scheduler. A pointer 260 * to this region may be obtained by calling spdk_thread_get_ctx(). 261 * 262 * \return 0 on success. Negated errno on failure. 263 */ 264 int spdk_thread_lib_init_ext(spdk_thread_op_fn thread_op_fn, 265 spdk_thread_op_supported_fn thread_op_supported_fn, 266 size_t ctx_sz); 267 268 /** 269 * Release all resources associated with this library. 270 */ 271 void spdk_thread_lib_fini(void); 272 273 /** 274 * Creates a new SPDK thread object. 275 * 276 * \param name Human-readable name for the thread; can be retrieved with spdk_thread_get_name(). 277 * The string is copied, so the pointed-to data only needs to be valid during the 278 * spdk_thread_create() call. May be NULL to specify no name. 279 * \param cpumask Optional mask of CPU cores on which to schedule this thread. This is only 280 * a suggestion to the scheduler. The value is copied, so cpumask may be released when 281 * this function returns. May be NULL if no mask is required. 282 * 283 * \return a pointer to the allocated thread on success or NULL on failure.. 284 */ 285 struct spdk_thread *spdk_thread_create(const char *name, struct spdk_cpuset *cpumask); 286 287 /** 288 * Force the current system thread to act as if executing the given SPDK thread. 289 * 290 * \param thread The thread to set. 291 */ 292 void spdk_set_thread(struct spdk_thread *thread); 293 294 /** 295 * Mark the thread as exited, failing all future spdk_thread_send_msg(), 296 * spdk_poller_register(), and spdk_get_io_channel() calls. May only be called 297 * within an spdk poller or message. 298 * 299 * All I/O channel references associated with the thread must be released 300 * using spdk_put_io_channel(), and all active pollers associated with the thread 301 * should be unregistered using spdk_poller_unregister(), prior to calling 302 * this function. This function will complete these processing. The completion can 303 * be queried by spdk_thread_is_exited(). 304 * 305 * \param thread The thread to destroy. 306 * 307 * \return always 0. (return value was deprecated but keep it for ABI compatibility.) 308 */ 309 int spdk_thread_exit(struct spdk_thread *thread); 310 311 /** 312 * Returns whether the thread is marked as exited. 313 * 314 * \param thread The thread to query. 315 * 316 * \return true if marked as exited, false otherwise. 317 */ 318 bool spdk_thread_is_exited(struct spdk_thread *thread); 319 320 /** 321 * Destroy a thread, releasing all of its resources. May only be called 322 * on a thread previously marked as exited. 323 * 324 * \param thread The thread to destroy. 325 * 326 */ 327 void spdk_thread_destroy(struct spdk_thread *thread); 328 329 /** 330 * Return a pointer to this thread's context. 331 * 332 * \param thread The thread on which to get the context. 333 * 334 * \return a pointer to the per-thread context, or NULL if there is 335 * no per-thread context. 336 */ 337 void *spdk_thread_get_ctx(struct spdk_thread *thread); 338 339 /** 340 * Get the thread's cpumask. 341 * 342 * \param thread The thread to get the cpumask for. 343 * 344 * \return cpuset pointer 345 */ 346 struct spdk_cpuset *spdk_thread_get_cpumask(struct spdk_thread *thread); 347 348 /** 349 * Set the current thread's cpumask to the specified value. The thread may be 350 * rescheduled to one of the CPUs specified in the cpumask. 351 * 352 * This API requires SPDK thread operation supports SPDK_THREAD_OP_RESCHED. 353 * 354 * \param cpumask The new cpumask for the thread. 355 * 356 * \return 0 on success, negated errno otherwise. 357 */ 358 int spdk_thread_set_cpumask(struct spdk_cpuset *cpumask); 359 360 /** 361 * Return the thread object associated with the context handle previously 362 * obtained by calling spdk_thread_get_ctx(). 363 * 364 * \param ctx A context previously obtained by calling spdk_thread_get_ctx() 365 * 366 * \return The associated thread. 367 */ 368 struct spdk_thread *spdk_thread_get_from_ctx(void *ctx); 369 370 /** 371 * Perform one iteration worth of processing on the thread. This includes 372 * both expired and continuous pollers as well as messages. If the thread 373 * has exited, return immediately. 374 * 375 * \param thread The thread to process 376 * \param max_msgs The maximum number of messages that will be processed. 377 * Use 0 to process the default number of messages (8). 378 * \param now The current time, in ticks. Optional. If 0 is passed, this 379 * function will call spdk_get_ticks() to get the current time. 380 * The current time is used as start time and this function 381 * will call spdk_get_ticks() at its end to know end time to 382 * measure run time of this function. 383 * 384 * \return 1 if work was done. 0 if no work was done. 385 */ 386 int spdk_thread_poll(struct spdk_thread *thread, uint32_t max_msgs, uint64_t now); 387 388 /** 389 * Return the number of ticks until the next timed poller 390 * would expire. Timed pollers are pollers for which 391 * period_microseconds is greater than 0. 392 * 393 * \param thread The thread to check poller expiration times on 394 * 395 * \return Number of ticks. If no timed pollers, return 0. 396 */ 397 uint64_t spdk_thread_next_poller_expiration(struct spdk_thread *thread); 398 399 /** 400 * Returns whether there are any active pollers (pollers for which 401 * period_microseconds equals 0) registered to be run on the thread. 402 * 403 * \param thread The thread to check. 404 * 405 * \return 1 if there is at least one active poller, 0 otherwise. 406 */ 407 int spdk_thread_has_active_pollers(struct spdk_thread *thread); 408 409 /** 410 * Returns whether there are any pollers registered to be run 411 * on the thread. 412 * 413 * \param thread The thread to check. 414 * 415 * \return true if there is any active poller, false otherwise. 416 */ 417 bool spdk_thread_has_pollers(struct spdk_thread *thread); 418 419 /** 420 * Returns whether there are scheduled operations to be run on the thread. 421 * 422 * \param thread The thread to check. 423 * 424 * \return true if there are no scheduled operations, false otherwise. 425 */ 426 bool spdk_thread_is_idle(struct spdk_thread *thread); 427 428 /** 429 * Get count of allocated threads. 430 */ 431 uint32_t spdk_thread_get_count(void); 432 433 /** 434 * Get a handle to the current thread. 435 * 436 * This handle may be passed to other threads and used as the target of 437 * spdk_thread_send_msg(). 438 * 439 * \sa spdk_io_channel_get_thread() 440 * 441 * \return a pointer to the current thread on success or NULL on failure. 442 */ 443 struct spdk_thread *spdk_get_thread(void); 444 445 /** 446 * Get a thread's name. 447 * 448 * \param thread Thread to query. 449 * 450 * \return the name of the thread. 451 */ 452 const char *spdk_thread_get_name(const struct spdk_thread *thread); 453 454 /** 455 * Get a thread's ID. 456 * 457 * \param thread Thread to query. 458 * 459 * \return the ID of the thread.. 460 */ 461 uint64_t spdk_thread_get_id(const struct spdk_thread *thread); 462 463 /** 464 * Get the thread by the ID. 465 * 466 * \param id ID of the thread. 467 * \return Thread whose ID matches or NULL otherwise. 468 */ 469 struct spdk_thread *spdk_thread_get_by_id(uint64_t id); 470 471 struct spdk_thread_stats { 472 uint64_t busy_tsc; 473 uint64_t idle_tsc; 474 }; 475 476 /** 477 * Get statistics about the current thread. 478 * 479 * Copy cumulative thread stats values to the provided thread stats structure. 480 * 481 * \param stats User's thread_stats structure. 482 */ 483 int spdk_thread_get_stats(struct spdk_thread_stats *stats); 484 485 /** 486 * Return the TSC value from the end of the last time this thread was polled. 487 * 488 * \param thread Thread to query. 489 * 490 * \return TSC value from the end of the last time this thread was polled. 491 */ 492 uint64_t spdk_thread_get_last_tsc(struct spdk_thread *thread); 493 494 /** 495 * Send a message to the given thread. 496 * 497 * The message will be sent asynchronously - i.e. spdk_thread_send_msg will always return 498 * prior to `fn` being called. 499 * 500 * \param thread The target thread. 501 * \param fn This function will be called on the given thread. 502 * \param ctx This context will be passed to fn when called. 503 * 504 * \return 0 on success 505 * \return -ENOMEM if the message could not be allocated 506 * \return -EIO if the message could not be sent to the destination thread 507 */ 508 int spdk_thread_send_msg(const struct spdk_thread *thread, spdk_msg_fn fn, void *ctx); 509 510 /** 511 * Send a message to the given thread. Only one critical message can be outstanding at the same 512 * time. It's intended to use this function in any cases that might interrupt the execution of the 513 * application, such as signal handlers. 514 * 515 * The message will be sent asynchronously - i.e. spdk_thread_send_critical_msg will always return 516 * prior to `fn` being called. 517 * 518 * \param thread The target thread. 519 * \param fn This function will be called on the given thread. 520 * 521 * \return 0 on success 522 * \return -EIO if the message could not be sent to the destination thread, due to an already 523 * outstanding critical message 524 */ 525 int spdk_thread_send_critical_msg(struct spdk_thread *thread, spdk_msg_fn fn); 526 527 /** 528 * Send a message to each thread, serially. 529 * 530 * The message is sent asynchronously - i.e. spdk_for_each_thread will return 531 * prior to `fn` being called on each thread. 532 * 533 * \param fn This is the function that will be called on each thread. 534 * \param ctx This context will be passed to fn when called. 535 * \param cpl This will be called on the originating thread after `fn` has been 536 * called on each thread. 537 */ 538 void spdk_for_each_thread(spdk_msg_fn fn, void *ctx, spdk_msg_fn cpl); 539 540 /** 541 * Set current spdk_thread into interrupt mode or back to poll mode. 542 * 543 * Only valid when thread interrupt facility is enabled by 544 * spdk_interrupt_mode_enable(). 545 * 546 * \param enable_interrupt Set interrupt mode for true, or poll mode for false 547 */ 548 void spdk_thread_set_interrupt_mode(bool enable_interrupt); 549 550 /** 551 * Register a poller on the current thread. 552 * 553 * The poller can be unregistered by calling spdk_poller_unregister(). 554 * 555 * \param fn This function will be called every `period_microseconds`. 556 * \param arg Argument passed to fn. 557 * \param period_microseconds How often to call `fn`. If 0, call `fn` as often 558 * as possible. 559 * 560 * \return a pointer to the poller registered on the current thread on success 561 * or NULL on failure. 562 */ 563 struct spdk_poller *spdk_poller_register(spdk_poller_fn fn, 564 void *arg, 565 uint64_t period_microseconds); 566 567 /** 568 * Register a poller on the current thread with arbitrary name. 569 * 570 * The poller can be unregistered by calling spdk_poller_unregister(). 571 * 572 * \param fn This function will be called every `period_microseconds`. 573 * \param arg Argument passed to fn. 574 * \param period_microseconds How often to call `fn`. If 0, call `fn` as often 575 * as possible. 576 * \param name Human readable name for the poller. Pointer of the poller function 577 * name is set if NULL. 578 * 579 * \return a pointer to the poller registered on the current thread on success 580 * or NULL on failure. 581 */ 582 struct spdk_poller *spdk_poller_register_named(spdk_poller_fn fn, 583 void *arg, 584 uint64_t period_microseconds, 585 const char *name); 586 587 /* 588 * \brief Register a poller on the current thread with setting its name 589 * to the string of the poller function name. 590 */ 591 #define SPDK_POLLER_REGISTER(fn, arg, period_microseconds) \ 592 spdk_poller_register_named(fn, arg, period_microseconds, #fn) 593 594 /** 595 * Unregister a poller on the current thread. 596 * 597 * \param ppoller The poller to unregister. 598 */ 599 void spdk_poller_unregister(struct spdk_poller **ppoller); 600 601 /** 602 * Pause a poller on the current thread. 603 * 604 * The poller is not run until it is resumed with spdk_poller_resume(). It is 605 * perfectly fine to pause an already paused poller. 606 * 607 * \param poller The poller to pause. 608 */ 609 void spdk_poller_pause(struct spdk_poller *poller); 610 611 /** 612 * Resume a poller on the current thread. 613 * 614 * Resumes a poller paused with spdk_poller_pause(). It is perfectly fine to 615 * resume an unpaused poller. 616 * 617 * \param poller The poller to resume. 618 */ 619 void spdk_poller_resume(struct spdk_poller *poller); 620 621 /** 622 * Register the opaque io_device context as an I/O device. 623 * 624 * After an I/O device is registered, it can return I/O channels using the 625 * spdk_get_io_channel() function. 626 * 627 * \param io_device The pointer to io_device context. 628 * \param create_cb Callback function invoked to allocate any resources required 629 * for a new I/O channel. 630 * \param destroy_cb Callback function invoked to release the resources for an 631 * I/O channel. 632 * \param ctx_size The size of the context buffer allocated to store references 633 * to allocated I/O channel resources. 634 * \param name A string name for the device used only for debugging. Optional - 635 * may be NULL. 636 */ 637 void spdk_io_device_register(void *io_device, spdk_io_channel_create_cb create_cb, 638 spdk_io_channel_destroy_cb destroy_cb, uint32_t ctx_size, 639 const char *name); 640 641 /** 642 * Unregister the opaque io_device context as an I/O device. 643 * 644 * The actual unregistration might be deferred until all active I/O channels are 645 * destroyed. 646 * 647 * \param io_device The pointer to io_device context. 648 * \param unregister_cb An optional callback function invoked to release any 649 * references to this I/O device. 650 */ 651 void spdk_io_device_unregister(void *io_device, spdk_io_device_unregister_cb unregister_cb); 652 653 /** 654 * Get an I/O channel for the specified io_device to be used by the calling thread. 655 * 656 * The io_device context pointer specified must have previously been registered 657 * using spdk_io_device_register(). If an existing I/O channel does not exist 658 * yet for the given io_device on the calling thread, it will allocate an I/O 659 * channel and invoke the create_cb function pointer specified in spdk_io_device_register(). 660 * If an I/O channel already exists for the given io_device on the calling thread, 661 * its reference is returned rather than creating a new I/O channel. 662 * 663 * \param io_device The pointer to io_device context. 664 * 665 * \return a pointer to the I/O channel for this device on success or NULL on failure. 666 */ 667 struct spdk_io_channel *spdk_get_io_channel(void *io_device); 668 669 /** 670 * Release a reference to an I/O channel. This happens asynchronously. 671 * 672 * This must be called on the same thread that called spdk_get_io_channel() 673 * for the specified I/O channel. If this releases the last reference to the 674 * I/O channel, The destroy_cb function specified in spdk_io_device_register() 675 * will be invoked to release any associated resources. 676 * 677 * \param ch I/O channel to release a reference. 678 */ 679 void spdk_put_io_channel(struct spdk_io_channel *ch); 680 681 /** 682 * Get the context buffer associated with an I/O channel. 683 * 684 * \param ch I/O channel. 685 * 686 * \return a pointer to the context buffer. 687 */ 688 static inline void * 689 spdk_io_channel_get_ctx(struct spdk_io_channel *ch) 690 { 691 return (uint8_t *)ch + sizeof(*ch); 692 } 693 694 /** 695 * Get I/O channel from the context buffer. This is the inverse of 696 * spdk_io_channel_get_ctx(). 697 * 698 * \param ctx The pointer to the context buffer. 699 * 700 * \return a pointer to the I/O channel associated with the context buffer. 701 */ 702 struct spdk_io_channel *spdk_io_channel_from_ctx(void *ctx); 703 704 /** 705 * Get the thread associated with an I/O channel. 706 * 707 * \param ch I/O channel. 708 * 709 * \return a pointer to the thread associated with the I/O channel 710 */ 711 struct spdk_thread *spdk_io_channel_get_thread(struct spdk_io_channel *ch); 712 713 /** 714 * Call 'fn' on each channel associated with io_device. 715 * 716 * This happens asynchronously, so fn may be called after spdk_for_each_channel 717 * returns. 'fn' will be called for each channel serially, such that two calls 718 * to 'fn' will not overlap in time. After 'fn' has been called, call 719 * spdk_for_each_channel_continue() to continue iterating. 720 * 721 * \param io_device 'fn' will be called on each channel associated with this io_device. 722 * \param fn Called on the appropriate thread for each channel associated with io_device. 723 * \param ctx Context buffer registered to spdk_io_channel_iter that can be obatined 724 * form the function spdk_io_channel_iter_get_ctx(). 725 * \param cpl Called on the thread that spdk_for_each_channel was initially called 726 * from when 'fn' has been called on each channel. 727 */ 728 void spdk_for_each_channel(void *io_device, spdk_channel_msg fn, void *ctx, 729 spdk_channel_for_each_cpl cpl); 730 731 /** 732 * Get io_device from the I/O channel iterator. 733 * 734 * \param i I/O channel iterator. 735 * 736 * \return a pointer to the io_device. 737 */ 738 void *spdk_io_channel_iter_get_io_device(struct spdk_io_channel_iter *i); 739 740 /** 741 * Get I/O channel from the I/O channel iterator. 742 * 743 * \param i I/O channel iterator. 744 * 745 * \return a pointer to the I/O channel. 746 */ 747 struct spdk_io_channel *spdk_io_channel_iter_get_channel(struct spdk_io_channel_iter *i); 748 749 /** 750 * Get context buffer from the I/O channel iterator. 751 * 752 * \param i I/O channel iterator. 753 * 754 * \return a pointer to the context buffer. 755 */ 756 void *spdk_io_channel_iter_get_ctx(struct spdk_io_channel_iter *i); 757 758 /** 759 * Get the io_device for the specified I/O channel. 760 * 761 * \param ch I/O channel. 762 * 763 * \return a pointer to the io_device for the I/O channel 764 */ 765 void *spdk_io_channel_get_io_device(struct spdk_io_channel *ch); 766 767 /** 768 * Helper function to iterate all channels for spdk_for_each_channel(). 769 * 770 * \param i I/O channel iterator. 771 * \param status Status for the I/O channel iterator. 772 */ 773 void spdk_for_each_channel_continue(struct spdk_io_channel_iter *i, int status); 774 775 /** 776 * A representative for registered interrupt file descriptor. 777 */ 778 struct spdk_interrupt; 779 780 /** 781 * Callback function registered for interrupt file descriptor. 782 * 783 * \param ctx Context passed as arg to spdk_interrupt_register(). 784 * 785 * \return 0 to indicate that interrupt took place but no events were found; 786 * positive to indicate that interrupt took place and some events were processed; 787 * negative if no event information is provided. 788 */ 789 typedef int (*spdk_interrupt_fn)(void *ctx); 790 791 /** 792 * Register an spdk_interrupt on the current thread. The provided function 793 * will be called any time the associated file descriptor is written to. 794 * 795 * \param efd File descriptor of the spdk_interrupt. 796 * \param fn Called each time there are events in spdk_interrupt. 797 * \param arg Function argument for fn. 798 * \param name Human readable name for the spdk_interrupt. Pointer of the spdk_interrupt 799 * name is set if NULL. 800 * 801 * \return a pointer to the spdk_interrupt registered on the current thread on success 802 * or NULL on failure. 803 */ 804 struct spdk_interrupt *spdk_interrupt_register(int efd, spdk_interrupt_fn fn, 805 void *arg, const char *name); 806 807 /* 808 * \brief Register an spdk_interrupt on the current thread with setting its name 809 * to the string of the spdk_interrupt function name. 810 */ 811 #define SPDK_INTERRUPT_REGISTER(efd, fn, arg) \ 812 spdk_interrupt_register(efd, fn, arg, #fn) 813 814 /** 815 * Unregister an spdk_interrupt on the current thread. 816 * 817 * \param pintr The spdk_interrupt to unregister. 818 */ 819 void spdk_interrupt_unregister(struct spdk_interrupt **pintr); 820 821 enum spdk_interrupt_event_types { 822 SPDK_INTERRUPT_EVENT_IN = 0x001, 823 SPDK_INTERRUPT_EVENT_OUT = 0x004, 824 SPDK_INTERRUPT_EVENT_ET = 1u << 31 825 }; 826 827 /** 828 * Change the event_types associated with the spdk_interrupt on the current thread. 829 * 830 * \param intr The pointer to the spdk_interrupt registered on the current thread. 831 * \param event_types New event_types for the spdk_interrupt. 832 * 833 * \return 0 if success or -errno if failed. 834 */ 835 int spdk_interrupt_set_event_types(struct spdk_interrupt *intr, 836 enum spdk_interrupt_event_types event_types); 837 838 /** 839 * Return a file descriptor that becomes ready whenever any of the registered 840 * interrupt file descriptors are ready 841 * 842 * \param thread The thread to get. 843 * 844 * \return The spdk_interrupt fd of thread itself. 845 */ 846 int spdk_thread_get_interrupt_fd(struct spdk_thread *thread); 847 848 /** 849 * Set SPDK run as event driven mode 850 * 851 * \return 0 on success or -errno on failure 852 */ 853 int spdk_interrupt_mode_enable(void); 854 855 /** 856 * Reports whether interrupt mode is set. 857 * 858 * \return True if interrupt mode is set, false otherwise. 859 */ 860 bool spdk_interrupt_mode_is_enabled(void); 861 862 #ifdef __cplusplus 863 } 864 #endif 865 866 #endif /* SPDK_THREAD_H_ */ 867