include/internal/quic_txpim.h

   1 /*
   2  * Copyright 2022-2024 The OpenSSL Project Authors. All Rights Reserved.
   3  *
   4  * Licensed under the Apache License 2.0 (the "License").  You may not use
   5  * this file except in compliance with the License.  You can obtain a copy
   6  * in the file LICENSE in the source distribution or at
   7  * https://www.openssl.org/source/license.html
   8  */
   9
  10 #ifndef OSSL_QUIC_TXPIM_H
  11 # define OSSL_QUIC_TXPIM_H
  12
  13 # include <openssl/ssl.h>
  14 # include "internal/quic_types.h"
  15 # include "internal/quic_predef.h"
  16 # include "internal/quic_cfq.h"
  17 # include "internal/quic_ackm.h"
  18
  19 # ifndef OPENSSL_NO_QUIC
  20
  21 /*
  22  * QUIC Transmitted Packet Information Manager
  23  * ===========================================
  24  */
  25
  26 typedef struct quic_txpim_pkt_st {
  27     /* ACKM-specific data. Caller should fill this. */
  28     OSSL_ACKM_TX_PKT    ackm_pkt;
  29
  30     /* Linked list of CFQ items in this packet. */
  31     QUIC_CFQ_ITEM      *retx_head;
  32
  33     /* Reserved for FIFD use. */
  34     QUIC_FIFD          *fifd;
  35
  36     /* QUIC_PKT_TYPE value. For diagnostic use only. */
  37     unsigned char       pkt_type;
  38
  39     /* Regenerate-strategy frames. */
  40     unsigned int        had_handshake_done_frame    : 1;
  41     unsigned int        had_max_data_frame          : 1;
  42     unsigned int        had_max_streams_bidi_frame  : 1;
  43     unsigned int        had_max_streams_uni_frame   : 1;
  44     unsigned int        had_ack_frame               : 1;
  45     unsigned int        had_conn_close              : 1;
  46
  47     /* Private data follows. */
  48 } QUIC_TXPIM_PKT;
  49
  50 /* Represents a range of bytes in an application or CRYPTO stream. */
  51 typedef struct quic_txpim_chunk_st {
  52     /* The stream ID, or UINT64_MAX for the CRYPTO stream. */
  53     uint64_t        stream_id;
  54     /*
  55      * The inclusive range of bytes in the stream. Exceptionally, if end <
  56      * start, designates a frame of zero length (used for FIN-only frames). In
  57      * this case end is the number of the final byte (i.e., one less than the
  58      * final size of the stream).
  59      */
  60     uint64_t        start, end;
  61     /*
  62      * Whether a FIN was sent for this stream in the packet. Not valid for
  63      * CRYPTO stream.
  64      */
  65     unsigned int    has_fin : 1;
  66     /*
  67      * If set, a STOP_SENDING frame was sent for this stream ID. (If no data was
  68      * sent for the stream, set end < start.)
  69      */
  70     unsigned int    has_stop_sending : 1;
  71     /*
  72      * If set, a RESET_STREAM frame was sent for this stream ID. (If no data was
  73      * sent for the stream, set end < start.)
  74      */
  75     unsigned int    has_reset_stream : 1;
  76 } QUIC_TXPIM_CHUNK;
  77
  78 QUIC_TXPIM *ossl_quic_txpim_new(void);
  79
  80 /*
  81  * Frees the TXPIM. All QUIC_TXPIM_PKTs which have been handed out by the TXPIM
  82  * must be released via a call to ossl_quic_txpim_pkt_release() before calling
  83  * this function.
  84  */
  85 void ossl_quic_txpim_free(QUIC_TXPIM *txpim);
  86
  87 /*
  88  * Allocates a new QUIC_TXPIM_PKT structure from the pool. Returns NULL on
  89  * failure. The returned structure is cleared of all data and is in a fresh
  90  * initial state.
  91  */
  92 QUIC_TXPIM_PKT *ossl_quic_txpim_pkt_alloc(QUIC_TXPIM *txpim);
  93
  94 /*
  95  * Releases the TXPIM packet, returning it to the pool.
  96  */
  97 void ossl_quic_txpim_pkt_release(QUIC_TXPIM *txpim, QUIC_TXPIM_PKT *fpkt);
  98
  99 /* Clears the chunk list of the packet, removing all entries. */
 100 void ossl_quic_txpim_pkt_clear_chunks(QUIC_TXPIM_PKT *fpkt);
 101
 102 /* Appends a chunk to the packet. The structure is copied. */
 103 int ossl_quic_txpim_pkt_append_chunk(QUIC_TXPIM_PKT *fpkt,
 104                                      const QUIC_TXPIM_CHUNK *chunk);
 105
 106 /* Adds a CFQ item to the packet by prepending it to the retx_head list. */
 107 void ossl_quic_txpim_pkt_add_cfq_item(QUIC_TXPIM_PKT *fpkt,
 108                                       QUIC_CFQ_ITEM *item);
 109
 110 /*
 111  * Returns a pointer to an array of stream chunk information structures for the
 112  * given packet. The caller must call ossl_quic_txpim_pkt_get_num_chunks() to
 113  * determine the length of this array. The returned pointer is invalidated
 114  * if the chunk list is mutated, for example via a call to
 115  * ossl_quic_txpim_pkt_append_chunk() or ossl_quic_txpim_pkt_clear_chunks().
 116  *
 117  * The chunks are sorted by (stream_id, start) in ascending order.
 118  */
 119 const QUIC_TXPIM_CHUNK *ossl_quic_txpim_pkt_get_chunks(const QUIC_TXPIM_PKT *fpkt);
 120
 121 /*
 122  * Returns the number of entries in the array returned by
 123  * ossl_quic_txpim_pkt_get_chunks().
 124  */
 125 size_t ossl_quic_txpim_pkt_get_num_chunks(const QUIC_TXPIM_PKT *fpkt);
 126
 127 /*
 128  * Returns the number of QUIC_TXPIM_PKTs allocated by the given TXPIM that have
 129  * yet to be returned to the TXPIM.
 130  */
 131 size_t ossl_quic_txpim_get_in_use(const QUIC_TXPIM *txpim);
 132
 133 # endif
 134
 135 #endif