2 .\" Copyright (c) 2008-2009 Lawrence Stewart <lstewart@FreeBSD.org>
3 .\" Copyright (c) 2010-2011 The FreeBSD Foundation
4 .\" All rights reserved.
6 .\" Portions of this documentation were written at the Centre for Advanced
7 .\" Internet Architectures, Swinburne University of Technology, Melbourne,
8 .\" Australia by David Hayes and Lawrence Stewart under sponsorship from the
9 .\" FreeBSD Foundation.
11 .\" Redistribution and use in source and binary forms, with or without
12 .\" modification, are permitted provided that the following conditions
14 .\" 1. Redistributions of source code must retain the above copyright
15 .\" notice, this list of conditions and the following disclaimer.
16 .\" 2. Redistributions in binary form must reproduce the above copyright
17 .\" notice, this list of conditions and the following disclaimer in the
18 .\" documentation and/or other materials provided with the distribution.
20 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR
24 .\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
39 .Nm DECLARE_CC_MODULE ,
41 .Nd Modular Congestion Control
45 .In netinet/cc/cc_module.h
46 .Fn DECLARE_CC_MODULE "ccname" "ccalgo"
51 framework allows congestion control algorithms to be implemented as dynamically
52 loadable kernel modules via the
55 Transport protocols can select from the list of available algorithms on a
56 connection-by-connection basis, or use the system default (see
61 modules are identified by an
63 name and set of hook functions encapsulated in a
64 .Vt "struct cc_algo" ,
65 which has the following members:
66 .Bd -literal -offset indent
68 char name[TCP_CA_NAME_MAX];
69 int (*mod_init) (void);
70 int (*mod_destroy) (void);
71 size_t (*cc_data_sz)(void);
72 int (*cb_init) (struct cc_var *ccv, void *ptr);
73 void (*cb_destroy) (struct cc_var *ccv);
74 void (*conn_init) (struct cc_var *ccv);
75 void (*ack_received) (struct cc_var *ccv, uint16_t type);
76 void (*cong_signal) (struct cc_var *ccv, uint32_t type);
77 void (*post_recovery) (struct cc_var *ccv);
78 void (*after_idle) (struct cc_var *ccv);
79 int (*ctl_output)(struct cc_var *, struct sockopt *, void *);
80 void (*rttsample)(struct cc_var *, uint32_t, uint32_t, uint32_t);
81 void (*newround)(struct cc_var *, uint32_t);
87 field identifies the unique name of the algorithm, and should be no longer than
88 TCP_CA_NAME_MAX-1 characters in length (the TCP_CA_NAME_MAX define lives in
90 for compatibility reasons).
94 function is called when a new module is loaded into the system but before the
95 registration process is complete.
96 It should be implemented if a module needs to set up some global state prior to
97 being available for use by new connections.
98 Returning a non-zero value from
100 will cause the loading of the module to fail.
104 function is called prior to unloading an existing module from the kernel.
105 It should be implemented if a module needs to clean up any global state before
106 being removed from the kernel.
107 The return value is currently ignored.
111 function is called by the socket option code to get the size of
115 The socket option code then preallocates the modules memory so that the
117 function will not fail (the socket option code uses M_WAITOK with
118 no locks held to do this).
122 function is called when a TCP control block
125 It should be implemented if a module needs to allocate memory for storing
126 private per-connection state.
127 Returning a non-zero value from
129 will cause the connection set up to be aborted, terminating the connection as a
131 Note that the ptr argument passed to the function should be checked to
132 see if it is non-NULL, if so it is preallocated memory that the cb_init function
133 must use instead of calling malloc itself.
137 function is called when a TCP control block
140 It should be implemented if a module needs to free memory allocated in
145 function is called when a new connection has been established and variables are
147 It should be implemented to initialise congestion control algorithm variables
148 for the newly established connection.
152 function is called when a TCP acknowledgement (ACK) packet is received.
155 argument as an input to their congestion management algorithms.
156 The ACK types currently reported by the stack are CC_ACK and CC_DUPACK.
157 CC_ACK indicates the received ACK acknowledges previously unacknowledged data.
158 CC_DUPACK indicates the received ACK acknowledges data we have already received
163 function is called when a congestion event is detected by the TCP stack.
166 argument as an input to their congestion management algorithms.
167 The congestion event types currently reported by the stack are CC_ECN, CC_RTO,
168 CC_RTO_ERR and CC_NDUPACK.
169 CC_ECN is reported when the TCP stack receives an explicit congestion notification
171 CC_RTO is reported when the retransmission time out timer fires.
172 CC_RTO_ERR is reported if the retransmission time out timer fired in error.
173 CC_NDUPACK is reported if N duplicate ACKs have been received back-to-back,
174 where N is the fast retransmit duplicate ack threshold (N=3 currently as per
179 function is called after the TCP connection has recovered from a congestion event.
180 It should be implemented to adjust state as required.
184 function is called when data transfer resumes after an idle period.
185 It should be implemented to adjust state as required.
189 function is called when
197 pointer forwarded unmodified from the TCP control, and a
199 pointer to algorithm specific argument.
203 function is called to pass round trip time information to the
204 congestion controller.
205 The additional arguments to the function include the microsecond RTT
206 that is being noted, the number of times that the data being
207 acknowledged was retransmitted as well as the flightsize at send.
208 For transports that do not track flightsize at send, this variable
209 will be the current cwnd at the time of the call.
213 function is called each time a new round trip time begins.
214 The montonically increasing round number is also passed to the
215 congestion controller as well.
216 This can be used for various purposes by the congestion controller (e.g Hystart++).
218 Note that currently not all TCP stacks call the
222 function so dependancy on these functions is also
223 dependant upon which TCP stack is in use.
226 .Fn DECLARE_CC_MODULE
227 macro provides a convenient wrapper around the
229 macro, and is used to register a
236 argument specifies the module's name.
239 argument points to the module's
243 modules must instantiate a
245 but are only required to set the name field, and optionally any of the function
247 Note that if a module defines the
249 function it also must define a
252 This is because when switching from one congestion control
253 module to another the socket option code will preallocate memory for the
256 If no memory is allocated by the modules
260 function should return 0.
262 The stack will skip calling any function pointer which is NULL, so there is no
263 requirement to implement any of the function pointers (with the exception of
264 the cb_init <-> cc_data_sz dependancy noted above).
265 Using the C99 designated initialiser feature to set fields is encouraged.
267 Each function pointer which deals with congestion control state is passed a
270 which has the following members:
271 .Bd -literal -offset indent
278 union ccv_container {
280 struct sctp_nets *sctp;
288 groups congestion control related variables into a single, embeddable structure
289 and adds a layer of indirection to accessing transport protocol control blocks.
290 The eventual goal is to allow a single set of
292 modules to be shared between all congestion aware transport protocols, though
297 To aid the eventual transition towards this goal, direct use of variables from
298 the transport protocol's data structures is strongly discouraged.
299 However, it is inevitable at the current time to require access to some of these
300 variables, and so the
302 macro exists as a convenience accessor.
305 argument points to the
307 passed into the function by the
312 argument specifies the name of the variable to access.
318 fields, the remaining fields in
326 field is available for algorithms requiring additional per-connection state to
327 attach a dynamic memory pointer to.
328 The memory should be allocated and attached in the module's
334 field specifies the number of new bytes acknowledged by the most recently
336 It is only valid in the
342 field specifies the sequence number of the most recently received ACK packet.
343 It is only valid in the
352 field is used to pass useful information from the stack to a
355 The CCF_ABC_SENTAWND flag is relevant in
357 and is set when appropriate byte counting (RFC3465) has counted a window's worth
358 of bytes has been sent.
359 It is the module's responsibility to clear the flag after it has processed the
361 The CCF_CWND_LIMITED flag is relevant in
363 and is set when the connection's ability to send data is currently constrained
364 by the value of the congestion window.
365 Algorithms should use the absence of this flag being set to avoid accumulating
366 a large difference between the congestion window and send window.
370 variable is used to pass in how much compression was done by the local
372 So for example if LRO pushed three in-order acknowledgements into
373 one acknowledgement the variable would be set to three.
377 variable is used in conjunction with the CCF_USE_LOCAL_ABC flag
378 to override what labc variable the congestion controller will use
379 for this particular acknowledgement.
392 Development and testing of this software were made possible in part by grants
393 from the FreeBSD Foundation and Cisco University Research Program Fund at
394 Community Foundation Silicon Valley.
399 The modular Congestion Control (CC) framework first appeared in
402 The framework was first released in 2007 by James Healy and Lawrence Stewart
403 whilst working on the NewTCP research project at Swinburne University of
404 Technology's Centre for Advanced Internet Architectures, Melbourne, Australia,
405 which was made possible in part by a grant from the Cisco University Research
406 Program Fund at Community Foundation Silicon Valley.
407 More details are available at:
409 http://caia.swin.edu.au/urp/newtcp/
414 framework was written by
415 .An Lawrence Stewart Aq Mt lstewart@FreeBSD.org ,
416 .An James Healy Aq Mt jimmy@deefa.com
418 .An David Hayes Aq Mt david.hayes@ieee.org .
420 This manual page was written by
421 .An David Hayes Aq Mt david.hayes@ieee.org
423 .An Lawrence Stewart Aq Mt lstewart@FreeBSD.org .