Line data    Source code

       1             : #ifndef HEADER_fd_src_waltz_quic_fd_quic_log_user_h
       2             : #define HEADER_fd_src_waltz_quic_fd_quic_log_user_h
       3             : 
       4             : /* fd_quic_log_user.h defines an ABI for extracting high frequency logs
       5             :    from an fd_quic instance.
       6             : 
       7             :    This header does not provide APIs to write logs.  For those, look in
       8             :    fd_quic_log_internal.h (as the name implies, currently not stable). */
       9             : 
      10             : #include "fd_quic_log.h"
      11             : #include "../../../tango/mcache/fd_mcache.h"
      12             : 
      13             : /* FIXME: Consider custom ring buffer layout instead of using mainline
      14             :           fd_frag_meta_t?  Would allow moving most log information into
      15             :           the metadata ring, obsoleting the need for a separate data
      16             :           cache ring. */
      17             : 
      18             : /* fd_quic_log_rx_t contains parameters of a consumer-side join to a
      19             :    quic_log interface. */
      20             : 
      21             : struct fd_quic_log_rx {
      22             :   fd_frag_meta_t const * mcache;
      23             :   ulong const *          mcache_seq;
      24             :   void *                 base;
      25             :   ulong                  data_lo_laddr;
      26             :   ulong                  data_hi_laddr;
      27             :   ulong                  seq;
      28             :   ulong                  depth;
      29             : };
      30             : 
      31             : typedef struct fd_quic_log_rx fd_quic_log_rx_t;
      32             : 
      33             : /* FD_QUIC_LOG_ALIGN describes the expected alignment of a quic_log. */
      34             : 
      35       10935 : #define FD_QUIC_LOG_ALIGN (64UL)
      36             : 
      37             : /* FD_QUIC_LOG_MAGIC is used to signal the layout of shared memory
      38             :    region of a quic_log. */
      39             : 
      40        2130 : #define FD_QUIC_LOG_MAGIC (0x9002c4662f7e58b5UL)
      41             : 
      42             : FD_PROTOTYPES_BEGIN
      43             : 
      44             : /* fd_quic_log_rx_join joins the caller to a quic_log as a consumer.
      45             :    shmlog points to a quic_log_abi object in the local address space.
      46             :    On success, fills rx with join info and returns rx.  On failure,
      47             :    returns NULL.  Reasons for failure include shmlog is a NULL pointer,
      48             :    misaligned, or does obviously not point to a quic_log_abi object. */
      49             : 
      50             : fd_quic_log_rx_t *
      51             : fd_quic_log_rx_join( fd_quic_log_rx_t * rx,
      52             :                      void *             shmlog );
      53             : 
      54             : /* fd_quic_log_rx_leave leaves a local consumer-side join to a quic_log. */
      55             : 
      56             : void *
      57             : fd_quic_log_rx_leave( fd_quic_log_rx_t * log );
      58             : 
      59             : /* fd_quic_log_rx_data_const returns a pointer to the data record.  log
      60             :    is a local join to a quic_log object.  The chunk value is taken from
      61             :    a frag_meta received via the mcache of this quic_log object/ */
      62             : 
      63             : FD_FN_CONST static inline void const *
      64             : fd_quic_log_rx_data_const( fd_quic_log_rx_t const * rx,
      65           0 :                            ulong                    chunk ) {
      66           0 :   return fd_chunk_to_laddr_const( rx->base, chunk );
      67           0 : }
      68             : 
      69             : /* fd_quic_log_rx_is_safe returns 0 if a log message read is guaranteed
      70             :    to be out of bounds.  Otherwise returns 1 (does not imply that the
      71             :    read is guaranteed to be within bounds, though). */
      72             : 
      73             : FD_FN_PURE static inline int
      74             : fd_quic_log_rx_is_safe( fd_quic_log_rx_t const * rx,
      75             :                         ulong                    chunk,
      76           0 :                         ulong                    sz ) {
      77           0 :   ulong msg_lo  = (ulong)fd_chunk_to_laddr_const( rx->base, chunk );
      78           0 :   ulong msg_hi  = msg_lo + sz;
      79           0 :   ulong msg_min = rx->data_lo_laddr;
      80           0 :   ulong msg_max = rx->data_hi_laddr;
      81           0 :   return msg_lo>=msg_min && msg_hi<=msg_max && msg_lo<=msg_hi;
      82           0 : }
      83             : 
      84             : /* fd_quic_log_sig_event extracts the event ID from the 'sig' field of
      85             :    a frag_meta record.  (bits 0..16) */
      86             : 
      87             : static inline uint
      88           0 : fd_quic_log_sig_event( ulong sig ) {
      89           0 :   return (uint)( sig & USHORT_MAX );
      90           0 : }
      91             : 
      92             : /* FIXME high-level API for reads */
      93             : 
      94             : /* fd_quic_log_rx_tail reads the last record relative to seq[0].
      95             :    This function is only useful when producer and consumer run on the
      96             :    same thread. */
      97             : 
      98             : static inline fd_frag_meta_t const *
      99             : fd_quic_log_rx_tail( fd_quic_log_rx_t const * rx,
     100           0 :                      ulong                    idx ) {
     101           0 :   ulong seq = fd_mcache_seq_query( rx->mcache_seq ) - 1UL - idx;
     102           0 :   return rx->mcache + fd_mcache_line_idx( seq, rx->depth );
     103           0 : }
     104             : 
     105             : FD_PROTOTYPES_END
     106             : 
     107             : #endif /* HEADER_fd_src_waltz_quic_fd_quic_log_user_h */