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