Line data    Source code

       1             : #ifndef HEADER_fd_src_util_io_fd_io_uring_setup_h
       2             : #define HEADER_fd_src_util_io_fd_io_uring_setup_h
       3             : 
       4             : /* fd_io_uring_setup.h provides an API to setup Linux io_uring
       5             :    instances. */
       6             : 
       7             : #include "fd_io_uring.h"
       8             : #include <linux/io_uring.h>
       9             : #include "../../util/fd_util_base.h"
      10             : 
      11             : FD_PROTOTYPES_BEGIN
      12             : 
      13             : /* IORING_SETUP_NO_MMAP related ***************************************/
      14             : 
      15             : /* fd_io_uring_shmem_{align,footprint} return the required alignment
      16             :    and footprint for a user-managed shared memory region suitable to
      17             :    hold io_uring data structures.  This includes the submission queue
      18             :    array, the submission queue entries, and the completion queue.
      19             :    {sq,cq}_depth must be powers of two.  footprint returns non-zero on
      20             :    success, and 0 (silently) if {sq,cq}_depth are invalid. */
      21             : 
      22             : ulong
      23             : fd_io_uring_shmem_align( void );
      24             : 
      25             : ulong
      26             : fd_io_uring_shmem_footprint( ulong sq_depth,
      27             :                              ulong cq_depth );
      28             : 
      29             : /* fd_io_uring_shmem_setup adds a user-managed shared memory region to
      30             :    params.  params is zero initialized by the caller.  shmem points to
      31             :    a region allocated according to the above align/footprint
      32             :    requirements.  Sets the IORING_SETUP_NO_MMAP flag, which instructs
      33             :    the kernel to map user memory instead of allocating new rings.
      34             : 
      35             :    Returns params on success.  On failure, returns NULL.  Reasons for
      36             :    failure include obviously invalid shmem pointer or invalid
      37             :    {sq,cq}_depth.  Logs reason for failure to WARNING. */
      38             : 
      39             : fd_io_uring_params_t *
      40             : fd_io_uring_shmem_setup( fd_io_uring_params_t * params,
      41             :                          void *                 shmem,
      42             :                          ulong                  sq_depth,
      43             :                          ulong                  cq_depth );
      44             : 
      45             : /* Setup API **********************************************************/
      46             : 
      47             : /* fd_io_uring_params_init initializes default io_uring parameters that
      48             :    are compatible with this library.
      49             : 
      50             :    - Custom completion queue depth
      51             :    - Single issuer thread
      52             :    - Rings disabled on startup */
      53             : 
      54             : FD_FN_UNUSED static fd_io_uring_params_t *
      55             : fd_io_uring_params_init( fd_io_uring_params_t * params,
      56           0 :                          uint                   depth ) {
      57           0 :   memset( params, 0, sizeof(fd_io_uring_params_t) );
      58           0 :   params->flags      |= IORING_SETUP_CQSIZE;
      59           0 :   params->sq_entries  = depth;
      60           0 :   params->cq_entries  = depth;
      61           0 :   params->flags      |= IORING_SETUP_SINGLE_ISSUER;
      62             :   params->flags      |= IORING_SETUP_R_DISABLED;
      63           0 :   return params;
      64           0 : }
      65             : 
      66             : /* fd_io_uring_init_shmem creates a new io_uring instance (using
      67             :    io_uring_setup(2)) with a user-allocated ring.  shmem points to the
      68             :    io_uring_shmem allocated ring with {sq,cq}_depth ring space. */
      69             : 
      70             : fd_io_uring_t *
      71             : fd_io_uring_init_shmem(
      72             :     fd_io_uring_t *        ring,
      73             :     fd_io_uring_params_t * params, /* modified */
      74             :     void *                 shmem,
      75             :     ulong                  sq_depth,
      76             :     ulong                  cq_depth
      77             : );
      78             : 
      79             : /* fd_io_uring_init_mmap creates a new io_uring instance (using
      80             :    io_uring_setup(2)) with a kernel-allocated ring.  The kernel ring is
      81             :    mapped into userspace using mmap.  Uses up MEMLOCK quota. */
      82             : 
      83             : fd_io_uring_t *
      84             : fd_io_uring_init_mmap(
      85             :     fd_io_uring_t *        ring,
      86             :     fd_io_uring_params_t * params /* modified */
      87             : );
      88             : 
      89             : /* fd_io_uring_fini destroys an io_uring instance (using close(2)).  If
      90             :    the ring was created with fd_io_uring_init_mmap, calls munmap(2) to
      91             :    unregister the kernel rings. */
      92             : 
      93             : void *
      94             : fd_io_uring_fini( fd_io_uring_t * ring );
      95             : 
      96             : FD_PROTOTYPES_END
      97             : 
      98             : #endif /* HEADER_fd_src_util_io_fd_io_uring_setup_h */