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