include/internal/quic_cfq.h

   1 /*
   2  * Copyright 2022 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_CFQ_H
  11 # define OSSL_QUIC_CFQ_H
  12
  13 # include <openssl/ssl.h>
  14 # include "internal/quic_types.h"
  15
  16 /*
  17  * QUIC Control Frame Queue Item
  18  * =============================
  19  *
  20  * The CFQ item structure has a public and a private part. This structure
  21  * documents the public part.
  22  */
  23 typedef struct quic_cfq_item_st QUIC_CFQ_ITEM;
  24
  25 struct quic_cfq_item_st {
  26     /*
  27      * These fields are not used by the CFQ, but are a convenience to assist the
  28      * TXPIM in keeping a list of GCR control frames which were sent in a
  29      * packet. They may be used for any purpose.
  30      */
  31     QUIC_CFQ_ITEM  *pkt_prev, *pkt_next;
  32
  33     /* All other fields are private; use ossl_quic_cfq_item_* accessors. */
  34 };
  35
  36 #define QUIC_CFQ_STATE_NEW      0
  37 #define QUIC_CFQ_STATE_TX       1
  38
  39 /* Returns the frame type of a CFQ item. */
  40 uint64_t ossl_quic_cfq_item_get_frame_type(QUIC_CFQ_ITEM *item);
  41
  42 /* Returns a pointer to the encoded buffer of a CFQ item. */
  43 const unsigned char *ossl_quic_cfq_item_get_encoded(QUIC_CFQ_ITEM *item);
  44
  45 /* Returns the length of the encoded buffer in bytes. */
  46 size_t ossl_quic_cfq_item_get_encoded_len(QUIC_CFQ_ITEM *item);
  47
  48 /* Returns the CFQ item state, a QUIC_CFQ_STATE_* value. */
  49 int ossl_quic_cfq_item_get_state(QUIC_CFQ_ITEM *item);
  50
  51 /* Returns the PN space for the CFQ item. */
  52 uint32_t ossl_quic_cfq_item_get_pn_space(QUIC_CFQ_ITEM *item);
  53
  54 /*
  55  * QUIC Control Frame Queue
  56  * ========================
  57  */
  58 typedef struct quic_cfq_st QUIC_CFQ;
  59
  60 QUIC_CFQ *ossl_quic_cfq_new(void);
  61 void ossl_quic_cfq_free(QUIC_CFQ *cfq);
  62
  63 /*
  64  * Input Side
  65  * ----------
  66  */
  67
  68 /*
  69  * Enqueue a frame to the CFQ.
  70  *
  71  * encoded points to the opaque encoded frame.
  72  *
  73  * free_cb is called by the CFQ when the buffer is no longer needed;
  74  * free_cb_arg is an opaque value passed to free_cb.
  75  *
  76  * priority determines the relative ordering of control frames in a packet.
  77  * Lower numerical values for priority mean that a frame should come earlier in
  78  * a packet. pn_space is a QUIC_PN_SPACE_* value.
  79  *
  80  * On success, returns a QUIC_CFQ_ITEM pointer which acts as a handle to
  81  * the queued frame. On failure, returns NULL.
  82  *
  83  * The frame is initially in the TX state, so there is no need to call
  84  * ossl_quic_cfq_mark_tx() immediately after calling this function.
  85  *
  86  * The frame type is duplicated as the frame_type argument here, even though it
  87  * is also encoded into the buffer. This allows the caller to determine the
  88  * frame type if desired without having to decode the frame.
  89  */
  90 typedef void (cfq_free_cb)(unsigned char *buf, size_t buf_len, void *arg);
  91
  92 QUIC_CFQ_ITEM *ossl_quic_cfq_add_frame(QUIC_CFQ            *cfq,
  93                                        uint32_t             priority,
  94                                        uint32_t             pn_space,
  95                                        uint64_t             frame_type,
  96                                        const unsigned char *encoded,
  97                                        size_t               encoded_len,
  98                                        cfq_free_cb         *free_cb,
  99                                        void                *free_cb_arg);
 100
 101 /*
 102  * Effects an immediate transition of the given CFQ item to the TX state.
 103  */
 104 void ossl_quic_cfq_mark_tx(QUIC_CFQ *cfq, QUIC_CFQ_ITEM *item);
 105
 106 /*
 107  * Effects an immediate transition of the given CFQ item to the NEW state,
 108  * allowing the frame to be retransmitted. If priority is not UINT32_MAX,
 109  * the priority is changed to the given value.
 110  */
 111 void ossl_quic_cfq_mark_lost(QUIC_CFQ *cfq, QUIC_CFQ_ITEM *item,
 112                              uint32_t priority);
 113
 114 /*
 115  * Releases a CFQ item. The item may be in either state (NEW or TX) prior to the
 116  * call. The QUIC_CFQ_ITEM pointer must not be used following this call.
 117  */
 118 void ossl_quic_cfq_release(QUIC_CFQ *cfq, QUIC_CFQ_ITEM *item);
 119
 120 /*
 121  * Output Side
 122  * -----------
 123  */
 124
 125 /*
 126  * Gets the highest priority CFQ item in the given PN space awaiting
 127  * transmission. If there are none, returns NULL.
 128  */
 129 QUIC_CFQ_ITEM *ossl_quic_cfq_get_priority_head(QUIC_CFQ *cfq, uint32_t pn_space);
 130
 131 /*
 132  * Given a CFQ item, gets the next CFQ item awaiting transmission in priority
 133  * order in the given PN space. In other words, given the return value of
 134  * ossl_quic_cfq_get_priority_head(), returns the next-lower priority item.
 135  * Returns NULL if the given item is the last item in priority order.
 136  */
 137 QUIC_CFQ_ITEM *ossl_quic_cfq_item_get_priority_next(QUIC_CFQ_ITEM *item,
 138                                                     uint32_t pn_space);
 139
 140 #endif