diff options
Diffstat (limited to 'static/freebsd/man9/mod_cc.9 3.html')
| -rw-r--r-- | static/freebsd/man9/mod_cc.9 3.html | 281 |
1 files changed, 0 insertions, 281 deletions
diff --git a/static/freebsd/man9/mod_cc.9 3.html b/static/freebsd/man9/mod_cc.9 3.html deleted file mode 100644 index 6e448911..00000000 --- a/static/freebsd/man9/mod_cc.9 3.html +++ /dev/null @@ -1,281 +0,0 @@ -<table class="head"> - <tr> - <td class="head-ltitle">MOD_CC(9)</td> - <td class="head-vol">Kernel Developer's Manual</td> - <td class="head-rtitle">MOD_CC(9)</td> - </tr> -</table> -<div class="manual-text"> -<section class="Sh"> -<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> -<p class="Pp"><code class="Nm">mod_cc</code>, - <code class="Nm">DECLARE_CC_MODULE</code>, <code class="Nm">CCV</code> - — <span class="Nd">Modular Congestion Control</span></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> -<p class="Pp"><code class="In">#include - <<a class="In">netinet/tcp.h</a>></code> - <br/> - <code class="In">#include <<a class="In">netinet/cc/cc.h</a>></code> - <br/> - <code class="In">#include - <<a class="In">netinet/cc/cc_module.h</a>></code></p> -<p class="Pp"><code class="Fn">DECLARE_CC_MODULE</code>(<var class="Fa" style="white-space: nowrap;">ccname</var>, - <var class="Fa" style="white-space: nowrap;">ccalgo</var>);</p> -<p class="Pp"><code class="Fn">CCV</code>(<var class="Fa" style="white-space: nowrap;">ccv</var>, - <var class="Fa" style="white-space: nowrap;">what</var>);</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> -<p class="Pp">The <code class="Nm">mod_cc</code> framework allows congestion - control algorithms to be implemented as dynamically loadable kernel modules - via the <a class="Xr">kld(4)</a> facility. Transport protocols can select - from the list of available algorithms on a connection-by-connection basis, - or use the system default (see <a class="Xr">mod_cc(4)</a> for more - details).</p> -<p class="Pp"><code class="Nm">mod_cc</code> modules are identified by an - <a class="Xr">ascii(7)</a> name and set of hook functions encapsulated in a - <var class="Vt">struct cc_algo</var>, which has the following members:</p> -<div class="Bd Pp Bd-indent Li"> -<pre>struct cc_algo { - char name[TCP_CA_NAME_MAX]; - int (*mod_init) (void); - int (*mod_destroy) (void); - size_t (*cc_data_sz)(void); - int (*cb_init) (struct cc_var *ccv, void *ptr); - void (*cb_destroy) (struct cc_var *ccv); - void (*conn_init) (struct cc_var *ccv); - void (*ack_received) (struct cc_var *ccv, uint16_t type); - void (*cong_signal) (struct cc_var *ccv, uint32_t type); - void (*post_recovery) (struct cc_var *ccv); - void (*after_idle) (struct cc_var *ccv); - int (*ctl_output)(struct cc_var *, struct sockopt *, void *); - void (*rttsample)(struct cc_var *, uint32_t, uint32_t, uint32_t); - void (*newround)(struct cc_var *, uint32_t); -};</pre> -</div> -<p class="Pp">The <var class="Va">name</var> field identifies the unique name of - the algorithm, and should be no longer than TCP_CA_NAME_MAX-1 characters in - length (the TCP_CA_NAME_MAX define lives in - <code class="In"><<a class="In">netinet/tcp.h</a>></code> for - compatibility reasons).</p> -<p class="Pp">The <var class="Va">mod_init</var> function is called when a new - module is loaded into the system but before the registration process is - complete. It should be implemented if a module needs to set up some global - state prior to being available for use by new connections. Returning a - non-zero value from <var class="Va">mod_init</var> will cause the loading of - the module to fail.</p> -<p class="Pp">The <var class="Va">mod_destroy</var> function is called prior to - unloading an existing module from the kernel. It should be implemented if a - module needs to clean up any global state before being removed from the - kernel. The return value is currently ignored.</p> -<p class="Pp">The <var class="Va">cc_data_sz</var> function is called by the - socket option code to get the size of data that the - <var class="Va">cb_init</var> function needs. The socket option code then - preallocates the modules memory so that the <var class="Va">cb_init</var> - function will not fail (the socket option code uses M_WAITOK with no locks - held to do this).</p> -<p class="Pp">The <var class="Va">cb_init</var> function is called when a TCP - control block <var class="Vt">struct tcpcb</var> is created. It should be - implemented if a module needs to allocate memory for storing private - per-connection state. Returning a non-zero value from - <var class="Va">cb_init</var> will cause the connection set up to be - aborted, terminating the connection as a result. Note that the ptr argument - passed to the function should be checked to see if it is non-NULL, if so it - is preallocated memory that the cb_init function must use instead of calling - malloc itself.</p> -<p class="Pp">The <var class="Va">cb_destroy</var> function is called when a TCP - control block <var class="Vt">struct tcpcb</var> is destroyed. It should be - implemented if a module needs to free memory allocated in - <var class="Va">cb_init</var>.</p> -<p class="Pp">The <var class="Va">conn_init</var> function is called when a new - connection has been established and variables are being initialised. It - should be implemented to initialise congestion control algorithm variables - for the newly established connection.</p> -<p class="Pp">The <var class="Va">ack_received</var> function is called when a - TCP acknowledgement (ACK) packet is received. Modules use the - <var class="Fa">type</var> argument as an input to their congestion - management algorithms. The ACK types currently reported by the stack are - CC_ACK and CC_DUPACK. CC_ACK indicates the received ACK acknowledges - previously unacknowledged data. CC_DUPACK indicates the received ACK - acknowledges data we have already received an ACK for.</p> -<p class="Pp">The <var class="Va">cong_signal</var> function is called when a - congestion event is detected by the TCP stack. Modules use the - <var class="Fa">type</var> argument as an input to their congestion - management algorithms. The congestion event types currently reported by the - stack are CC_ECN, CC_RTO, CC_RTO_ERR and CC_NDUPACK. CC_ECN is reported when - the TCP stack receives an explicit congestion notification (RFC3168). CC_RTO - is reported when the retransmission time out timer fires. CC_RTO_ERR is - reported if the retransmission time out timer fired in error. CC_NDUPACK is - reported if N duplicate ACKs have been received back-to-back, where N is the - fast retransmit duplicate ack threshold (N=3 currently as per RFC5681).</p> -<p class="Pp">The <var class="Va">post_recovery</var> function is called after - the TCP connection has recovered from a congestion event. It should be - implemented to adjust state as required.</p> -<p class="Pp">The <var class="Va">after_idle</var> function is called when data - transfer resumes after an idle period. It should be implemented to adjust - state as required.</p> -<p class="Pp">The <var class="Va">ctl_output</var> function is called when - <a class="Xr">getsockopt(2)</a> or <a class="Xr">setsockopt(2)</a> is called - on a <a class="Xr">tcp(4)</a> socket with the <var class="Va">struct - sockopt</var> pointer forwarded unmodified from the TCP control, and a - <var class="Va">void *</var> pointer to algorithm specific argument.</p> -<p class="Pp">The <var class="Va">rttsample</var> function is called to pass - round trip time information to the congestion controller. The additional - arguments to the function include the microsecond RTT that is being noted, - the number of times that the data being acknowledged was retransmitted as - well as the flightsize at send. For transports that do not track flightsize - at send, this variable will be the current cwnd at the time of the call.</p> -<p class="Pp">The <var class="Va">newround</var> function is called each time a - new round trip time begins. The montonically increasing round number is also - passed to the congestion controller as well. This can be used for various - purposes by the congestion controller (e.g Hystart++).</p> -<p class="Pp">Note that currently not all TCP stacks call the - <var class="Va">rttsample</var> and <var class="Va">newround</var> function - so dependency on these functions is also dependent upon which TCP stack is - in use.</p> -<p class="Pp" id="DECLARE_CC_MODULE">The - <a class="permalink" href="#DECLARE_CC_MODULE"><code class="Fn">DECLARE_CC_MODULE</code></a>() - macro provides a convenient wrapper around the - <a class="Xr">DECLARE_MODULE(9)</a> macro, and is used to register a - <code class="Nm">mod_cc</code> module with the - <code class="Nm">mod_cc</code> framework. The <var class="Fa">ccname</var> - argument specifies the module's name. The <var class="Fa">ccalgo</var> - argument points to the module's <var class="Vt">struct cc_algo</var>.</p> -<p class="Pp"><code class="Nm">mod_cc</code> modules must instantiate a - <var class="Vt">struct cc_algo</var>, but are only required to set the name - field, and optionally any of the function pointers. Note that if a module - defines the <var class="Va">cb_init</var> function it also must define a - <var class="Va">cc_data_sz</var> function. This is because when switching - from one congestion control module to another the socket option code will - preallocate memory for the <var class="Va">cb_init</var> function. If no - memory is allocated by the modules <var class="Va">cb_init</var> then the - <var class="Va">cc_data_sz</var> function should return 0.</p> -<p class="Pp">The stack will skip calling any function pointer which is NULL, so - there is no requirement to implement any of the function pointers (with the - exception of the cb_init <-> cc_data_sz dependency noted above). Using - the C99 designated initialiser feature to set fields is encouraged.</p> -<p class="Pp">Each function pointer which deals with congestion control state is - passed a pointer to a <var class="Vt">struct cc_var</var>, which has the - following members:</p> -<div class="Bd Pp Bd-indent Li"> -<pre>struct cc_var { - void *cc_data; - int bytes_this_ack; - tcp_seq curack; - uint32_t flags; - int type; - union ccv_container { - struct tcpcb *tcp; - struct sctp_nets *sctp; - } ccvc; - uint16_t nsegs; - uint8_t labc; -};</pre> -</div> -<p class="Pp"><var class="Vt">struct cc_var</var> groups congestion control - related variables into a single, embeddable structure and adds a layer of - indirection to accessing transport protocol control blocks. The eventual - goal is to allow a single set of <code class="Nm">mod_cc</code> modules to - be shared between all congestion aware transport protocols, though currently - only <a class="Xr">tcp(4)</a> is supported.</p> -<p class="Pp" id="CCV">To aid the eventual transition towards this goal, direct - use of variables from the transport protocol's data structures is strongly - discouraged. However, it is inevitable at the current time to require access - to some of these variables, and so the - <a class="permalink" href="#CCV"><code class="Fn">CCV</code></a>() macro - exists as a convenience accessor. The <var class="Fa">ccv</var> argument - points to the <var class="Vt">struct cc_var</var> passed into the function - by the <code class="Nm">mod_cc</code> framework. The - <var class="Fa">what</var> argument specifies the name of the variable to - access.</p> -<p class="Pp">Apart from the <var class="Va">type</var> and - <var class="Va">ccv_container</var> fields, the remaining fields in - <var class="Vt">struct cc_var</var> are for use by - <code class="Nm">mod_cc</code> modules.</p> -<p class="Pp">The <var class="Va">cc_data</var> field is available for - algorithms requiring additional per-connection state to attach a dynamic - memory pointer to. The memory should be allocated and attached in the - module's <var class="Va">cb_init</var> hook function.</p> -<p class="Pp">The <var class="Va">bytes_this_ack</var> field specifies the - number of new bytes acknowledged by the most recently received ACK packet. - It is only valid in the <var class="Va">ack_received</var> hook - function.</p> -<p class="Pp">The <var class="Va">curack</var> field specifies the sequence - number of the most recently received ACK packet. It is only valid in the - <var class="Va">ack_received</var>, <var class="Va">cong_signal</var> and - <var class="Va">post_recovery</var> hook functions.</p> -<p class="Pp">The <var class="Va">flags</var> field is used to pass useful - information from the stack to a <code class="Nm">mod_cc</code> module. The - CCF_ABC_SENTAWND flag is relevant in <var class="Va">ack_received</var> and - is set when appropriate byte counting (RFC3465) has counted a window's worth - of bytes has been sent. It is the module's responsibility to clear the flag - after it has processed the signal. The CCF_CWND_LIMITED flag is relevant in - <var class="Va">ack_received</var> and is set when the connection's ability - to send data is currently constrained by the value of the congestion window. - Algorithms should use the absence of this flag being set to avoid - accumulating a large difference between the congestion window and send - window.</p> -<p class="Pp">The <var class="Va">nsegs</var> variable is used to pass in how - much compression was done by the local LRO system. So for example if LRO - pushed three in-order acknowledgements into one acknowledgement the variable - would be set to three.</p> -<p class="Pp">The <var class="Va">labc</var> variable is used in conjunction - with the CCF_USE_LOCAL_ABC flag to override what labc variable the - congestion controller will use for this particular acknowledgement.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE - ALSO</a></h1> -<p class="Pp"><a class="Xr">cc_cdg(4)</a>, <a class="Xr">cc_chd(4)</a>, - <a class="Xr">cc_cubic(4)</a>, <a class="Xr">cc_dctcp(4)</a>, - <a class="Xr">cc_hd(4)</a>, <a class="Xr">cc_htcp(4)</a>, - <a class="Xr">cc_newreno(4)</a>, <a class="Xr">cc_vegas(4)</a>, - <a class="Xr">mod_cc(4)</a>, <a class="Xr">tcp(4)</a></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="ACKNOWLEDGEMENTS"><a class="permalink" href="#ACKNOWLEDGEMENTS">ACKNOWLEDGEMENTS</a></h1> -<p class="Pp">Development and testing of this software were made possible in - part by grants from the FreeBSD Foundation and Cisco University Research - Program Fund at Community Foundation Silicon Valley.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="FUTURE_WORK"><a class="permalink" href="#FUTURE_WORK">FUTURE - WORK</a></h1> -<p class="Pp">Integrate with <a class="Xr">sctp(4)</a>.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> -<p class="Pp">The modular Congestion Control (CC) framework first appeared in - <span class="Ux">FreeBSD 9.0</span>.</p> -<p class="Pp">The framework was first released in 2007 by James Healy and - Lawrence Stewart whilst working on the NewTCP research project at Swinburne - University of Technology's Centre for Advanced Internet Architectures, - Melbourne, Australia, which was made possible in part by a grant from the - Cisco University Research Program Fund at Community Foundation Silicon - Valley. More details are available at:</p> -<p class="Pp">http://caia.swin.edu.au/urp/newtcp/</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> -<p class="Pp">The <code class="Nm">mod_cc</code> framework was written by - <span class="An">Lawrence Stewart</span> - <<a class="Mt" href="mailto:lstewart@FreeBSD.org">lstewart@FreeBSD.org</a>>, - <span class="An">James Healy</span> - <<a class="Mt" href="mailto:jimmy@deefa.com">jimmy@deefa.com</a>> and - <span class="An">David Hayes</span> - <<a class="Mt" href="mailto:david.hayes@ieee.org">david.hayes@ieee.org</a>>.</p> -<p class="Pp">This manual page was written by <span class="An">David - Hayes</span> - <<a class="Mt" href="mailto:david.hayes@ieee.org">david.hayes@ieee.org</a>> - and <span class="An">Lawrence Stewart</span> - <<a class="Mt" href="mailto:lstewart@FreeBSD.org">lstewart@FreeBSD.org</a>>.</p> -</section> -</div> -<table class="foot"> - <tr> - <td class="foot-date">May 13, 2021</td> - <td class="foot-os">FreeBSD 15.0</td> - </tr> -</table> |