1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
|
/*
* Copyright 2022 The OpenSSL Project Authors. All Rights Reserved.
*
* Licensed under the Apache License 2.0 (the "License"). You may not use
* this file except in compliance with the License. You can obtain a copy
* in the file LICENSE in the source distribution or at
* https://www.openssl.org/source/license.html
*/
#ifndef OSSL_QUIC_CC_H
# define OSSL_QUIC_CC_H
#include "openssl/params.h"
#include "internal/time.h"
# ifndef OPENSSL_NO_QUIC
typedef struct ossl_cc_data_st OSSL_CC_DATA;
typedef struct ossl_cc_ack_info_st {
/* The time the packet being acknowledged was originally sent. */
OSSL_TIME tx_time;
/* The size in bytes of the packet being acknowledged. */
size_t tx_size;
} OSSL_CC_ACK_INFO;
typedef struct ossl_cc_loss_info_st {
/* The time the packet being lost was originally sent. */
OSSL_TIME tx_time;
/* The size in bytes of the packet which has been determined lost. */
size_t tx_size;
} OSSL_CC_LOSS_INFO;
typedef struct ossl_cc_ecn_info_st {
/*
* The time at which the largest acked PN (in the incoming ACK frame) was
* sent.
*/
OSSL_TIME largest_acked_time;
} OSSL_CC_ECN_INFO;
/* Parameter (read-write): Maximum datagram payload length in bytes. */
#define OSSL_CC_OPTION_MAX_DGRAM_PAYLOAD_LEN "max_dgram_payload_len"
/* Diagnostic (read-only): current congestion window size in bytes. */
#define OSSL_CC_OPTION_CUR_CWND_SIZE "cur_cwnd_size"
/* Diagnostic (read-only): minimum congestion window size in bytes. */
#define OSSL_CC_OPTION_MIN_CWND_SIZE "min_cwnd_size"
/* Diagnostic (read-only): current net bytes in flight. */
#define OSSL_CC_OPTION_CUR_BYTES_IN_FLIGHT "bytes_in_flight"
/* Diagnostic (read-only): method-specific state value. */
#define OSSL_CC_OPTION_CUR_STATE "cur_state"
/*
* Congestion control abstract interface.
*
* This interface is broadly based on the design described in RFC 9002. However,
* the demarcation between the ACKM and the congestion controller does not
* exactly match that delineated in the RFC 9002 psuedocode. Where aspects of
* the demarcation involve the congestion controller accessing internal state of
* the ACKM, the interface has been revised where possible to provide the
* information needed by the congestion controller and avoid needing to give the
* congestion controller access to the ACKM's internal data structures.
*
* Particular changes include:
*
* - In our implementation, it is the responsibility of the ACKM to determine
* if a loss event constitutes persistent congestion.
*
* - In our implementation, it is the responsibility of the ACKM to determine
* if the ECN-CE counter has increased. The congestion controller is simply
* informed when an ECN-CE event occurs.
*
* All of these changes are intended to avoid having a congestion controller
* have to access ACKM internal state.
*/
#define OSSL_CC_LOST_FLAG_PERSISTENT_CONGESTION (1U << 0)
typedef struct ossl_cc_method_st {
/*
* Instantiation.
*/
OSSL_CC_DATA *(*new)(OSSL_TIME (*now_cb)(void *arg),
void *now_cb_arg);
void (*free)(OSSL_CC_DATA *ccdata);
/*
* Reset of state.
*/
void (*reset)(OSSL_CC_DATA *ccdata);
/*
* Escape hatch for option configuration.
*
* params is an array of OSSL_PARAM structures.
*
* Returns 1 on success and 0 on failure.
*/
int (*set_input_params)(OSSL_CC_DATA *ccdata,
const OSSL_PARAM *params);
/*
* (Re)bind output (diagnostic) information.
*
* params is an array of OSSL_PARAM structures used to output values. The
* storage locations associated with each parameter are stored internally
* and updated whenever the state of the congestion controller is updated;
* thus, the storage locations associated with the OSSL_PARAMs passed in the
* call to this function must remain valid until the congestion controller
* is freed or those parameters are unbound. A given parameter name may be
* bound to only one location at a time. The params structures themselves
* do not need to remain allocated after this call returns.
*
* Returns 1 on success and 0 on failure.
*/
int (*bind_diagnostics)(OSSL_CC_DATA *ccdata,
OSSL_PARAM *params);
/*
* Unbind diagnostic information. The parameters with the given names are
* unbound, cancelling the effects of a previous call to bind_diagnostic().
* params is an array of OSSL_PARAMs. The values of the parameters are
* ignored. If a parameter is already unbound, there is no effect for that
* parameter but other parameters are still unbound.
*
* Returns 1 on success or 0 on failure.
*/
int (*unbind_diagnostics)(OSSL_CC_DATA *ccdata,
OSSL_PARAM *params);
/*
* Returns the amount of additional data (above and beyond the data
* currently in flight) which can be sent in bytes. Returns 0 if no more
* data can be sent at this time. The return value of this method
* can vary as time passes.
*/
uint64_t (*get_tx_allowance)(OSSL_CC_DATA *ccdata);
/*
* Returns the time at which the return value of get_tx_allowance might be
* higher than its current value. This is not a guarantee and spurious
* wakeups are allowed. Returns ossl_time_infinite() if there is no current
* wakeup deadline.
*/
OSSL_TIME (*get_wakeup_deadline)(OSSL_CC_DATA *ccdata);
/*
* The On Data Sent event. num_bytes should be the size of the packet in
* bytes (or the aggregate size of multiple packets which have just been
* sent).
*/
int (*on_data_sent)(OSSL_CC_DATA *ccdata,
uint64_t num_bytes);
/*
* The On Data Acked event. See OSSL_CC_ACK_INFO structure for details
* of the information to be passed.
*/
int (*on_data_acked)(OSSL_CC_DATA *ccdata,
const OSSL_CC_ACK_INFO *info);
/*
* The On Data Lost event. See OSSL_CC_LOSS_INFO structure for details
* of the information to be passed.
*
* Note: When the ACKM determines that a set of multiple packets has been
* lost, it is useful for a congestion control algorithm to be able to
* process this as a single loss event rather than multiple loss events.
* Thus, calling this function may cause the congestion controller to defer
* state updates under the assumption that subsequent calls to
* on_data_lost() representing further lost packets in the same loss event
* may be forthcoming. Always call on_data_lost_finished() after one or more
* calls to on_data_lost().
*/
int (*on_data_lost)(OSSL_CC_DATA *ccdata,
const OSSL_CC_LOSS_INFO *info);
/*
* To be called after a sequence of one or more on_data_lost() calls
* representing multiple packets in a single loss detection incident.
*
* Flags may be 0 or OSSL_CC_LOST_FLAG_PERSISTENT_CONGESTION.
*/
int (*on_data_lost_finished)(OSSL_CC_DATA *ccdata, uint32_t flags);
/*
* For use when a PN space is invalidated or a packet must otherwise be
* 'undone' for congestion control purposes without acting as a loss signal.
* Only the size of the packet is needed.
*/
int (*on_data_invalidated)(OSSL_CC_DATA *ccdata,
uint64_t num_bytes);
/*
* Called from the ACKM when detecting an increased ECN-CE value in an ACK
* frame. This indicates congestion.
*
* Note that this differs from the RFC's conceptual segregation of the loss
* detection and congestion controller functions, as in our implementation
* the ACKM is responsible for detecting increases to ECN-CE and simply
* tells the congestion controller when ECN-triggered congestion has
* occurred. This allows a slightly more efficient implementation and
* narrower interface between the ACKM and CC.
*/
int (*on_ecn)(OSSL_CC_DATA *ccdata,
const OSSL_CC_ECN_INFO *info);
} OSSL_CC_METHOD;
extern const OSSL_CC_METHOD ossl_cc_dummy_method;
extern const OSSL_CC_METHOD ossl_cc_newreno_method;
# endif
#endif
|
