Line data    Source code

       1             : #ifndef HEADER_fd_src_waltz_xdp_fd_xsk_aio_h
       2             : #define HEADER_fd_src_waltz_xdp_fd_xsk_aio_h
       3             : 
       4             : #if defined(__linux__)
       5             : 
       6             : #include "fd_xsk.h"
       7             : #include "../aio/fd_aio.h"
       8             : 
       9             : /* fd_xsk_aio_t is an fd_aio driver for AF_XDP.  May not be shared
      10             :    across thread groups. */
      11             : 
      12          15 : #define FD_XSK_AIO_ALIGN (32UL)
      13             : 
      14             : struct __attribute__((aligned(FD_XSK_AIO_ALIGN))) fd_xsk_aio_private;
      15             : typedef struct fd_xsk_aio_private fd_xsk_aio_t;
      16             : 
      17             : FD_PROTOTYPES_BEGIN
      18             : 
      19             : /* fd_xsk_aio_{align,footprint} return the required alignment and
      20             :    footprint of a memory region suitable for use an fd_xsk_aio_t where
      21             :    tx_depth is the depth of the TX ring buffer of the fd_xsk_t, and
      22             :    pkt_cnt is the max number of packets to handle at per
      23             :    fd_xsk_aio_service() operation. */
      24             : 
      25             : FD_FN_CONST ulong
      26             : fd_xsk_aio_align( void );
      27             : 
      28             : FD_FN_CONST ulong
      29             : fd_xsk_aio_footprint( ulong tx_depth,
      30             :                       ulong pkt_cnt );
      31             : 
      32             : 
      33             : /* fd_xsk_aio_new formats an unused memory region for use as an
      34             :    fd_xsk_aio_t.  mem must point to a memory region that matches
      35             :    fd_xsk_aio_align() and fd_xsk_aio_footprint().  pkt_cnt is the
      36             :    number of packets this fd_xsk_aio_t instance can handle per
      37             :    fd_xsk_aio_service() operation.  Returns handle suitable for
      38             :    fd_xsk_aio_join() on success. */
      39             : 
      40             : void *
      41             : fd_xsk_aio_new( void * mem,
      42             :                 ulong  tx_depth,
      43             :                 ulong  pkt_cnt );
      44             : 
      45             : /* fd_xsk_aio_join joins the caller to the xsk_aio/xsk pair.  xsk_aio
      46             :    points to the first byte of the memory region backing the
      47             :    fd_xsk_aio_t in the caller's address space.
      48             :    xsk must be a locally joined fd_xsk_t instance with a lifetime at
      49             :    least that of this xsk_aio join.  Returns a pointer in the local
      50             :    address space to the fd_xsk_aio_t on success or NULL on failure (logs
      51             :    details).  Reasons for failure include the xsk_aio is obviously not a
      52             :    local pointer to a memory region holding a fd_xsk_aio_t.  Every
      53             :    successful join should have a matching leave.  The lifetime of the
      54             :    join is until the matching leave of the caller's thread group is
      55             :    terminated.  The may only be one active join for a single
      56             :    fd_xsk_aio_t at any given time. U.B. if multiple xsk_aio are joined
      57             :    to the same xsk. */
      58             : 
      59             : fd_xsk_aio_t *
      60             : fd_xsk_aio_join( void *     xsk_aio,
      61             :                  fd_xsk_t * xsk );
      62             : 
      63             : /* fd_xsk_aio_leave leaves a current local join.  Any aio connections
      64             :    must be destroyed at this point.  Returns a pointer to the underlying
      65             :    shared memory region on success and NULL on failure (logs details).
      66             :    Reasons for failure include xsk_aio is NULL. */
      67             : 
      68             : void *
      69             : fd_xsk_aio_leave( fd_xsk_aio_t * xsk_aio );
      70             : 
      71             : /* fd_xsk_aio_delete unformats a memory region used as an fd_xsk_aio_t.
      72             :    Assumes nobody is joined to the region.  Returns a pointer to the
      73             :    underlying memory region or NULL if used obviously in error.  The
      74             :    ownership of the memory region is transferred to the caller on
      75             :    success.  Does not delete the underlying fd_xsk_t instance. */
      76             : void *
      77             : fd_xsk_aio_delete( void * xsk_aio );
      78             : 
      79             : /* fd_xsk_aio_set_rx sets the fd_aio_t instance called back when
      80             :    fd_xsk_t receives data.  Requires periodic fd_xsk_aio_service()
      81             :    calls to poll AF_XDP buffers for RX events and TX completions. */
      82             : 
      83             : void
      84             : fd_xsk_aio_set_rx( fd_xsk_aio_t *   xsk_aio,
      85             :                    fd_aio_t const * aio );
      86             : 
      87             : /* fd_xsk_aio_get_tx gets the fd_aio_t instance to send data out to the
      88             :    network via the underlying fd_xsk_t.  Each aio send does at most one
      89             :    call to fd_xsk_tx_enqueue and may yield FD_AIO_ERR_AGAIN if the XSK
      90             :    tx_depth or aio pkt_cnt buffers are too small.  If attempting to send
      91             :    any packet larger than the underlying XSK frame_sz (minus headroom),
      92             :    aborts the entire batch and yields FD_AIO_ERR_INVAL. */
      93             : 
      94             : FD_FN_CONST fd_aio_t const *
      95             : fd_xsk_aio_get_tx( fd_xsk_aio_t const * xsk_aio );
      96             : 
      97             : /* fd_xsk_aio_service services aio callbacks for incoming packets and
      98             :    handles completions for tx requests.  Returns 1 if any work was done
      99             :    (tx or rx was handled), otherwise 0. */
     100             : 
     101             : int
     102             : fd_xsk_aio_service( fd_xsk_aio_t * xsk_aio );
     103             : 
     104             : FD_PROTOTYPES_END
     105             : 
     106             : #endif /* defined(__linux__) */
     107             : #endif /* HEADER_fd_src_waltz_xdp_fd_xsk_aio_h */
     108             :