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_FC_H 11 # define OSSL_QUIC_FC_H 12 13 # include <openssl/ssl.h> 14 # include "internal/time.h" 15 16 # ifndef OPENSSL_NO_QUIC 17 18 /* 19 * TX Flow Controller (TXFC) 20 * ========================= 21 * 22 * For discussion, see doc/designs/quic-design/quic-fc.md. 23 */ 24 typedef struct quic_txfc_st QUIC_TXFC; 25 26 struct quic_txfc_st { 27 QUIC_TXFC *parent; /* stream-level iff non-NULL */ 28 uint64_t swm, cwm; 29 char has_become_blocked; 30 }; 31 32 /* 33 * Initialises a TX flow controller. conn_txfc should be non-NULL and point to 34 * the connection-level flow controller if the TXFC is for stream-level flow 35 * control, and NULL otherwise. 36 */ 37 int ossl_quic_txfc_init(QUIC_TXFC *txfc, QUIC_TXFC *conn_txfc); 38 39 /* 40 * Gets the parent (i.e., connection-level) TX flow controller. Returns NULL if 41 * called on a connection-level TX flow controller. 42 */ 43 QUIC_TXFC *ossl_quic_txfc_get_parent(QUIC_TXFC *txfc); 44 45 /* 46 * Bump the credit watermark (CWM) value. This is the 'On TX Window Updated' 47 * operation. This function is a no-op if it has already been called with an 48 * equal or higher CWM value. 49 * 50 * It returns 1 iff the call resulted in the CWM being bumped and 0 if it was 51 * not increased because it has already been called with an equal or higher CWM 52 * value. This is not an error per se but may indicate a local programming error 53 * or a protocol error in a remote peer. 54 */ 55 int ossl_quic_txfc_bump_cwm(QUIC_TXFC *txfc, uint64_t cwm); 56 57 /* 58 * Get the number of bytes by which we are in credit. This is the number of 59 * controlled bytes we are allowed to send. (Thus if this function returns 0, we 60 * are currently blocked.) 61 * 62 * If called on a stream-level TXFC, ossl_quic_txfc_get_credit is called on 63 * the connection-level TXFC as well, and the lesser of the two values is 64 * returned. The consumed value is the amount already consumed on the connection 65 * level TXFC. 66 */ 67 uint64_t ossl_quic_txfc_get_credit(QUIC_TXFC *txfc, uint64_t consumed); 68 69 /* 70 * Like ossl_quic_txfc_get_credit(), but when called on a stream-level TXFC, 71 * retrieves only the stream-level credit value and does not clamp it based on 72 * connection-level flow control. Any credit value is reduced by the consumed 73 * amount. 74 */ 75 uint64_t ossl_quic_txfc_get_credit_local(QUIC_TXFC *txfc, uint64_t consumed); 76 77 /* 78 * Consume num_bytes of credit. This is the 'On TX' operation. This should be 79 * called when we transmit any controlled bytes. Calling this with an argument 80 * of 0 is a no-op. 81 * 82 * We must never transmit more controlled bytes than we are in credit for (see 83 * the return value of ossl_quic_txfc_get_credit()). If you call this function 84 * with num_bytes greater than our current credit, this function consumes the 85 * remainder of the credit and returns 0. This indicates a serious programming 86 * error on the caller's part. Otherwise, the function returns 1. 87 * 88 * If called on a stream-level TXFC, ossl_quic_txfc_consume_credit() is called 89 * on the connection-level TXFC also. If the call to that function on the 90 * connection-level TXFC returns zero, this function will also return zero. 91 */ 92 int ossl_quic_txfc_consume_credit(QUIC_TXFC *txfc, uint64_t num_bytes); 93 94 /* 95 * Like ossl_quic_txfc_consume_credit(), but when called on a stream-level TXFC, 96 * consumes only from the stream-level credit and does not inform the 97 * connection-level TXFC. 98 */ 99 int ossl_quic_txfc_consume_credit_local(QUIC_TXFC *txfc, uint64_t num_bytes); 100 101 /* 102 * This flag is provided for convenience. A caller is not required to use it. It 103 * is a boolean flag set whenever our credit drops to zero. If clear is 1, the 104 * flag is cleared. The old value of the flag is returned. Callers may use this 105 * to determine if they need to send a DATA_BLOCKED or STREAM_DATA_BLOCKED 106 * frame, which should contain the value returned by ossl_quic_txfc_get_cwm(). 107 */ 108 int ossl_quic_txfc_has_become_blocked(QUIC_TXFC *txfc, int clear); 109 110 /* 111 * Get the current CWM value. This is mainly only needed when generating a 112 * DATA_BLOCKED or STREAM_DATA_BLOCKED frame, or for diagnostic purposes. 113 */ 114 uint64_t ossl_quic_txfc_get_cwm(QUIC_TXFC *txfc); 115 116 /* 117 * Get the current spent watermark (SWM) value. This is purely for diagnostic 118 * use and should not be needed in normal circumstances. 119 */ 120 uint64_t ossl_quic_txfc_get_swm(QUIC_TXFC *txfc); 121 122 /* 123 * RX Flow Controller (RXFC) 124 * ========================= 125 */ 126 typedef struct quic_rxfc_st QUIC_RXFC; 127 128 struct quic_rxfc_st { 129 /* 130 * swm is the sent/received watermark, which tracks how much we have 131 * received from the peer. rwm is the retired watermark, which tracks how 132 * much has been passed to the application. esrwm is the rwm value at which 133 * the current auto-tuning epoch started. hwm is the highest stream length 134 * (STREAM frame offset + payload length) we have seen from a STREAM frame 135 * yet. 136 */ 137 uint64_t cwm, swm, rwm, esrwm, hwm, cur_window_size, max_window_size; 138 OSSL_TIME epoch_start; 139 OSSL_TIME (*now)(void *arg); 140 void *now_arg; 141 QUIC_RXFC *parent; 142 unsigned char error_code, has_cwm_changed, is_fin, standalone; 143 }; 144 145 /* 146 * Initialises an RX flow controller. conn_rxfc should be non-NULL and point to 147 * a connection-level RXFC if the RXFC is for stream-level flow control, and 148 * NULL otherwise. initial_window_size and max_window_size specify the initial 149 * and absolute maximum window sizes, respectively. Window size values are 150 * expressed in bytes and determine how much credit the RXFC extends to the peer 151 * to transmit more data at a time. 152 */ 153 int ossl_quic_rxfc_init(QUIC_RXFC *rxfc, QUIC_RXFC *conn_rxfc, 154 uint64_t initial_window_size, 155 uint64_t max_window_size, 156 OSSL_TIME (*now)(void *arg), 157 void *now_arg); 158 159 /* 160 * Initialises an RX flow controller which is used by itself and not under a 161 * connection-level RX flow controller. This can be used for stream count 162 * enforcement as well as CRYPTO buffer enforcement. 163 */ 164 int ossl_quic_rxfc_init_standalone(QUIC_RXFC *rxfc, 165 uint64_t initial_window_size, 166 OSSL_TIME (*now)(void *arg), 167 void *now_arg); 168 169 /* 170 * Gets the parent (i.e., connection-level) RXFC. Returns NULL if called on a 171 * connection-level RXFC. 172 */ 173 QUIC_RXFC *ossl_quic_rxfc_get_parent(QUIC_RXFC *rxfc); 174 175 /* 176 * Changes the current maximum window size value. 177 */ 178 void ossl_quic_rxfc_set_max_window_size(QUIC_RXFC *rxfc, 179 size_t max_window_size); 180 181 /* 182 * To be called whenever a STREAM frame is received. 183 * 184 * end is the value (offset + len), where offset is the offset field of the 185 * STREAM frame and len is the length of the STREAM frame's payload in bytes. 186 * 187 * is_fin should be 1 if the STREAM frame had the FIN flag set and 0 otherwise. 188 * 189 * This function may be used on a stream-level RXFC only. The connection-level 190 * RXFC will have its state updated by the stream-level RXFC. 191 * 192 * You should check ossl_quic_rxfc_has_error() on both connection-level and 193 * stream-level RXFCs after calling this function, as an incoming STREAM frame 194 * may cause flow control limits to be exceeded by an errant peer. This 195 * function still returns 1 in this case, as this is not a caller error. 196 * 197 * Returns 1 on success or 0 on failure. 198 */ 199 int ossl_quic_rxfc_on_rx_stream_frame(QUIC_RXFC *rxfc, 200 uint64_t end, int is_fin); 201 202 /* 203 * To be called whenever controlled bytes are retired, i.e. when bytes are 204 * dequeued from a QUIC stream and passed to the application. num_bytes 205 * is the number of bytes which were passed to the application. 206 * 207 * You should call this only on a stream-level RXFC. This function will update 208 * the connection-level RXFC automatically. 209 * 210 * rtt should be the current best understanding of the RTT to the peer, as 211 * offered by the Statistics Manager. 212 * 213 * You should check ossl_quic_rxfc_has_cwm_changed() after calling this 214 * function, as it may have caused the RXFC to decide to grant more flow control 215 * credit to the peer. 216 * 217 * Returns 1 on success and 0 on failure. 218 */ 219 int ossl_quic_rxfc_on_retire(QUIC_RXFC *rxfc, 220 uint64_t num_bytes, 221 OSSL_TIME rtt); 222 223 /* 224 * Returns the current CWM which the RXFC thinks the peer should have. 225 * 226 * Note that the RXFC will increase this value in response to events, at which 227 * time a MAX_DATA or MAX_STREAM_DATA frame must be generated. Use 228 * ossl_quic_rxfc_has_cwm_changed() to detect this condition. 229 * 230 * This value increases monotonically. 231 */ 232 uint64_t ossl_quic_rxfc_get_cwm(const QUIC_RXFC *rxfc); 233 234 /* 235 * Returns the current SWM. This is the total number of bytes the peer has 236 * transmitted to us. This is intended for diagnostic use only; you should 237 * not need it. 238 */ 239 uint64_t ossl_quic_rxfc_get_swm(const QUIC_RXFC *rxfc); 240 241 /* 242 * Returns the current RWM. This is the total number of bytes that has been 243 * retired. This is intended for diagnostic use only; you should not need it. 244 */ 245 uint64_t ossl_quic_rxfc_get_rwm(const QUIC_RXFC *rxfc); 246 247 /* 248 * Returns the current credit. This is the CWM minus the SWM. This is intended 249 * for diagnostic use only; you should not need it. 250 */ 251 uint64_t ossl_quic_rxfc_get_credit(const QUIC_RXFC *rxfc); 252 253 /* 254 * Returns the CWM changed flag. If clear is 1, the flag is cleared and the old 255 * value is returned. 256 */ 257 int ossl_quic_rxfc_has_cwm_changed(QUIC_RXFC *rxfc, int clear); 258 259 /* 260 * Returns a QUIC_ERR_* error code if a flow control error has been detected. 261 * Otherwise, returns QUIC_ERR_NO_ERROR. If clear is 1, the error is cleared 262 * and the old value is returned. 263 * 264 * May return one of the following values: 265 * 266 * QUIC_ERR_FLOW_CONTROL_ERROR: 267 * This indicates a flow control protocol violation by the remote peer; the 268 * connection should be terminated in this event. 269 * QUIC_ERR_FINAL_SIZE: 270 * The peer attempted to change the stream length after ending the stream. 271 */ 272 int ossl_quic_rxfc_get_error(QUIC_RXFC *rxfc, int clear); 273 274 /* 275 * Returns 1 if the RXFC is a stream-level RXFC and the RXFC knows the final 276 * size for the stream in bytes. If this is the case and final_size is non-NULL, 277 * writes the final size to *final_size. Otherwise, returns 0. 278 */ 279 int ossl_quic_rxfc_get_final_size(const QUIC_RXFC *rxfc, uint64_t *final_size); 280 281 # endif 282 283 #endif 284