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