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 #ifndef OSSL_QUIC_CC_H 10 # define OSSL_QUIC_CC_H 11 12 #include "openssl/params.h" 13 #include "internal/time.h" 14 15 typedef struct ossl_cc_data_st *OSSL_CC_DATA; 16 17 typedef struct ossl_cc_method_st { 18 void *dummy; 19 20 /* 21 * Create a new OSSL_CC_DATA object to handle the congestion control 22 * calculations. 23 * 24 * |settings| are mandatory settings that will cause the 25 * new() call to fail if they are not understood). 26 * |options| are optional settings that will not 27 * cause the new() call to fail if they are not understood. 28 * |changeables| contain additional parameters that the congestion 29 * control algorithms need that can be updated during the 30 * connection lifetime - for example size of the datagram payload. 31 * To avoid calling a function with OSSL_PARAM array every time 32 * these parameters are changed the addresses of these param 33 * values are considered permanent and the values can be updated 34 * any time. 35 */ 36 OSSL_CC_DATA *(*new)(OSSL_PARAM *settings, OSSL_PARAM *options, 37 OSSL_PARAM *changeables); 38 39 /* 40 * Release the OSSL_CC_DATA. 41 */ 42 void (*free)(OSSL_CC_DATA *ccdata); 43 44 /* 45 * Reset the congestion control state. 46 * |flags| to support different level of reset (partial/full). 47 */ 48 void (*reset)(OSSL_CC_DATA *ccdata, int flags); 49 50 /* 51 * Set number of packets exempted from CC - used for probing 52 * |numpackets| is a small value (2). 53 * Returns 0 on error, 1 otherwise. 54 */ 55 int (*set_exemption)(OSSL_CC_DATA *ccdata, int numpackets); 56 57 /* 58 * Get current number of packets exempted from CC. 59 * Returns negative value on error, the number otherwise. 60 */ 61 int (*get_exemption)(OSSL_CC_DATA *ccdata); 62 63 /* 64 * Returns 1 if sending is allowed, 0 otherwise. 65 */ 66 int (*can_send)(OSSL_CC_DATA *ccdata); 67 68 /* 69 * Returns number of bytes allowed to be sent. 70 * |time_since_last_send| is time since last send operation 71 * in microseconds. 72 * |time_valid| is 1 if the |time_since_last_send| holds 73 * a meaningful value, 0 otherwise. 74 */ 75 size_t (*get_send_allowance)(OSSL_CC_DATA *ccdata, 76 OSSL_TIME time_since_last_send, 77 int time_valid); 78 79 /* 80 * Returns the maximum number of bytes allowed to be in flight. 81 */ 82 size_t (*get_bytes_in_flight_max)(OSSL_CC_DATA *ccdata); 83 84 /* 85 * To be called when a packet with retransmittable data was sent. 86 * |num_retransmittable_bytes| is the number of bytes sent 87 * in the packet that are retransmittable. 88 * Returns 1 on success, 0 otherwise. 89 */ 90 int (*on_data_sent)(OSSL_CC_DATA *ccdata, 91 size_t num_retransmittable_bytes); 92 93 /* 94 * To be called when retransmittable data was invalidated. 95 * I.E. they are not considered in-flight anymore but 96 * are neither acknowledged nor lost. In particular used when 97 * 0RTT data was rejected. 98 * |num_retransmittable_bytes| is the number of bytes 99 * of the invalidated data. 100 * Returns 1 if sending is unblocked (can_send returns 1), 0 101 * otherwise. 102 */ 103 int (*on_data_invalidated)(OSSL_CC_DATA *ccdata, 104 size_t num_retransmittable_bytes); 105 106 /* 107 * To be called when sent data was acked. 108 * |time_now| is current time in microseconds. 109 * |largest_pn_acked| is the largest packet number of the acked 110 * packets. 111 * |num_retransmittable_bytes| is the number of retransmittable 112 * packet bytes that were newly acked. 113 * Returns 1 if sending is unblocked (can_send returns 1), 0 114 * otherwise. 115 */ 116 int (*on_data_acked)(OSSL_CC_DATA *ccdata, 117 OSSL_TIME time_now, 118 uint64_t last_pn_acked, 119 size_t num_retransmittable_bytes); 120 121 /* 122 * To be called when sent data is considered lost. 123 * |largest_pn_lost| is the largest packet number of the lost 124 * packets. 125 * |largest_pn_sent| is the largest packet number sent on this 126 * connection. 127 * |num_retransmittable_bytes| is the number of retransmittable 128 * packet bytes that are newly considered lost. 129 * |persistent_congestion| is 1 if the congestion is considered 130 * persistent (see RFC 9002 Section 7.6), 0 otherwise. 131 */ 132 void (*on_data_lost)(OSSL_CC_DATA *ccdata, 133 uint64_t largest_pn_lost, 134 uint64_t largest_pn_sent, 135 size_t num_retransmittable_bytes, 136 int persistent_congestion); 137 138 /* 139 * To be called when all lost data from the previous call to 140 * on_data_lost() was actually acknowledged. 141 * This reverts the size of the congestion window to the state 142 * before the on_data_lost() call. 143 * Returns 1 if sending is unblocked, 0 otherwise. 144 */ 145 int (*on_spurious_congestion_event)(OSSL_CC_DATA *ccdata); 146 } OSSL_CC_METHOD; 147 148 extern const OSSL_CC_METHOD ossl_cc_dummy_method; 149 150 #endif 151
