From owner-svn-src-stable@FreeBSD.ORG Fri Sep 23 05:28:09 2011 Return-Path: Delivered-To: svn-src-stable@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id F1E4E106564A; Fri, 23 Sep 2011 05:28:09 +0000 (UTC) (envelope-from lstewart@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:4f8:fff6::2c]) by mx1.freebsd.org (Postfix) with ESMTP id DE57D8FC15; Fri, 23 Sep 2011 05:28:09 +0000 (UTC) Received: from svn.freebsd.org (localhost [127.0.0.1]) by svn.freebsd.org (8.14.4/8.14.4) with ESMTP id p8N5S9hd056318; Fri, 23 Sep 2011 05:28:09 GMT (envelope-from lstewart@svn.freebsd.org) Received: (from lstewart@localhost) by svn.freebsd.org (8.14.4/8.14.4/Submit) id p8N5S90n056304; Fri, 23 Sep 2011 05:28:09 GMT (envelope-from lstewart@svn.freebsd.org) Message-Id: <201109230528.p8N5S90n056304@svn.freebsd.org> From: Lawrence Stewart Date: Fri, 23 Sep 2011 05:28:09 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-stable@freebsd.org, svn-src-stable-8@freebsd.org X-SVN-Group: stable-8 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cc: Subject: svn commit: r225738 - in stable/8: . share/man/man4 share/man/man7 share/man/man9 X-BeenThere: svn-src-stable@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: SVN commit messages for all the -stable branches of the src tree List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 23 Sep 2011 05:28:10 -0000 Author: lstewart Date: Fri Sep 23 05:28:09 2011 New Revision: 225738 URL: http://svn.freebsd.org/changeset/base/225738 Log: MFC r225583: Rename the cc.4 and cc.9 modular congestion control related man pages to mod_cc.4 and mod_cc.9 respectively to avoid any possible confusion with the cc.1 gcc man page. Update references to these man pages where required. Requested by: Grenville Armitage Added: stable/8/share/man/man4/mod_cc.4 - copied unchanged from r225583, head/share/man/man4/mod_cc.4 stable/8/share/man/man9/mod_cc.9 - copied unchanged from r225583, head/share/man/man9/mod_cc.9 Deleted: stable/8/share/man/man4/cc.4 stable/8/share/man/man9/cc.9 Modified: stable/8/ObsoleteFiles.inc (contents, props changed) stable/8/share/man/man4/Makefile stable/8/share/man/man4/cc_chd.4 stable/8/share/man/man4/cc_cubic.4 stable/8/share/man/man4/cc_hd.4 stable/8/share/man/man4/cc_htcp.4 stable/8/share/man/man4/cc_newreno.4 stable/8/share/man/man4/cc_vegas.4 stable/8/share/man/man4/h_ertt.4 stable/8/share/man/man4/tcp.4 stable/8/share/man/man9/Makefile Directory Properties: stable/8/ (props changed) stable/8/COPYRIGHT (props changed) stable/8/LOCKS (props changed) stable/8/MAINTAINERS (props changed) stable/8/Makefile (props changed) stable/8/Makefile.inc1 (props changed) stable/8/README (props changed) stable/8/UPDATING (props changed) stable/8/share/man/ (props changed) stable/8/share/man/man1/ (props changed) stable/8/share/man/man3/ (props changed) stable/8/share/man/man4/ (props changed) stable/8/share/man/man5/ (props changed) stable/8/share/man/man7/ (props changed) stable/8/share/man/man7/ports.7 (props changed) stable/8/share/man/man8/ (props changed) stable/8/share/man/man9/ (props changed) Modified: stable/8/ObsoleteFiles.inc ============================================================================== --- stable/8/ObsoleteFiles.inc Fri Sep 23 02:58:59 2011 (r225737) +++ stable/8/ObsoleteFiles.inc Fri Sep 23 05:28:09 2011 (r225738) @@ -14,6 +14,9 @@ # The file is partitioned: OLD_FILES first, then OLD_LIBS and OLD_DIRS last. # +# 20110915: rename congestion control manpages +OLD_FILES+=usr/share/man/man4/cc.4.gz +OLD_FILES+=usr/share/man/man9/cc.9.gz # 20101123: removed subblock.h from liblzma OLD_FILES+=usr/include/lzma/subblock.h # 20101114: Remove long-obsolete MAKEDEV.8 Modified: stable/8/share/man/man4/Makefile ============================================================================== --- stable/8/share/man/man4/Makefile Fri Sep 23 02:58:59 2011 (r225737) +++ stable/8/share/man/man4/Makefile Fri Sep 23 05:28:09 2011 (r225738) @@ -67,7 +67,6 @@ MAN= aac.4 \ cardbus.4 \ carp.4 \ cas.4 \ - cc.4 \ cc_chd.4 \ cc_cubic.4 \ cc_hd.4 \ @@ -225,6 +224,8 @@ MAN= aac.4 \ mmc.4 \ mmcsd.4 \ mn.4 \ + mod_cc.4 \ + mos.4 \ mouse.4 \ mps.4 \ mpt.4 \ Modified: stable/8/share/man/man4/cc_chd.4 ============================================================================== --- stable/8/share/man/man4/cc_chd.4 Fri Sep 23 02:58:59 2011 (r225737) +++ stable/8/share/man/man4/cc_chd.4 Fri Sep 23 05:28:09 2011 (r225738) @@ -29,7 +29,7 @@ .\" .\" $FreeBSD$ .\" -.Dd February 15, 2011 +.Dd September 15, 2011 .Dt CC_CHD 4 .Os .Sh NAME @@ -86,16 +86,16 @@ is used. Default is 1. .El .Sh SEE ALSO -.Xr cc 4 , .Xr cc_cubic 4 , .Xr cc_hd 4 , .Xr cc_htcp 4 , .Xr cc_newreno 4 , .Xr cc_vegas 4 , .Xr h_ertt 4 , +.Xr mod_cc 4 , .Xr tcp 4 , -.Xr cc 9 , -.Xr khelp 9 +.Xr khelp 9 , +.Xr mod_cc 9 .Rs .%A "D. A. Hayes" .%A "G. Armitage" Modified: stable/8/share/man/man4/cc_cubic.4 ============================================================================== --- stable/8/share/man/man4/cc_cubic.4 Fri Sep 23 02:58:59 2011 (r225737) +++ stable/8/share/man/man4/cc_cubic.4 Fri Sep 23 05:28:09 2011 (r225738) @@ -30,7 +30,7 @@ .\" .\" $FreeBSD$ .\" -.Dd February 15, 2011 +.Dd September 15, 2011 .Dt CC_CUBIC 4 .Os .Sh NAME @@ -62,14 +62,14 @@ section below. .Sh MIB Variables There are currently no tunable MIB variables. .Sh SEE ALSO -.Xr cc 4 , .Xr cc_chd 4 , .Xr cc_hd 4 , .Xr cc_htcp 4 , .Xr cc_newreno 4 , .Xr cc_vegas 4 , +.Xr mod_cc 4 , .Xr tcp 4 , -.Xr cc 9 +.Xr mod_cc 9 .Rs .%A "Sangtae Ha" .%A "Injong Rhee" Modified: stable/8/share/man/man4/cc_hd.4 ============================================================================== --- stable/8/share/man/man4/cc_hd.4 Fri Sep 23 02:58:59 2011 (r225737) +++ stable/8/share/man/man4/cc_hd.4 Fri Sep 23 05:28:09 2011 (r225738) @@ -29,7 +29,7 @@ .\" .\" $FreeBSD$ .\" -.Dd February 15, 2011 +.Dd September 15, 2011 .Dt CC_HD 4 .Os .Sh NAME @@ -69,16 +69,16 @@ Minimum queuing delay threshold (qmin) i Default is 5. .El .Sh SEE ALSO -.Xr cc 4 , .Xr cc_chd 4 , .Xr cc_cubic 4 , .Xr cc_htcp 4 , .Xr cc_newreno 4 , .Xr cc_vegas 4 , .Xr h_ertt 4 , +.Xr mod_cc 4 , .Xr tcp 4 , -.Xr cc 9 , -.Xr khelp 9 +.Xr khelp 9 , +.Xr mod_cc 9 .Rs .%A "L. Budzisz" .%A "R. Stanojevic" Modified: stable/8/share/man/man4/cc_htcp.4 ============================================================================== --- stable/8/share/man/man4/cc_htcp.4 Fri Sep 23 02:58:59 2011 (r225737) +++ stable/8/share/man/man4/cc_htcp.4 Fri Sep 23 05:28:09 2011 (r225738) @@ -30,7 +30,7 @@ .\" .\" $FreeBSD$ .\" -.Dd February 15, 2011 +.Dd September 15, 2011 .Dt CC_HTCP 4 .Os .Sh NAME @@ -69,14 +69,14 @@ window increase during congestion avoida Default is 0 (disabled). .El .Sh SEE ALSO -.Xr cc 4 , .Xr cc_chd 4 , .Xr cc_cubic 4 , .Xr cc_hd 4 , .Xr cc_newreno 4 , .Xr cc_vegas 4 , +.Xr mod_cc 4 , .Xr tcp 4 , -.Xr cc 9 +.Xr mod_cc 9 .Rs .%A "D. Leith" .%A "R. Shorten" Modified: stable/8/share/man/man4/cc_newreno.4 ============================================================================== --- stable/8/share/man/man4/cc_newreno.4 Fri Sep 23 02:58:59 2011 (r225737) +++ stable/8/share/man/man4/cc_newreno.4 Fri Sep 23 05:28:09 2011 (r225738) @@ -30,7 +30,7 @@ .\" .\" $FreeBSD$ .\" -.Dd February 15, 2011 +.Dd September 15, 2011 .Dt CC_NEWRENO 4 .Os .Sh NAME @@ -42,14 +42,14 @@ Details about the algorithm can be found .Sh MIB Variables There are currently no tunable MIB variables. .Sh SEE ALSO -.Xr cc 4 , .Xr cc_chd 4 , .Xr cc_cubic 4 , .Xr cc_hd 4 , .Xr cc_htcp 4 , .Xr cc_vegas 4 , +.Xr mod_cc 4 , .Xr tcp 4 , -.Xr cc 9 +.Xr mod_cc 9 .Sh ACKNOWLEDGEMENTS Development and testing of this software were made possible in part by grants from the FreeBSD Foundation and Cisco University Research Program Fund at Modified: stable/8/share/man/man4/cc_vegas.4 ============================================================================== --- stable/8/share/man/man4/cc_vegas.4 Fri Sep 23 02:58:59 2011 (r225737) +++ stable/8/share/man/man4/cc_vegas.4 Fri Sep 23 05:28:09 2011 (r225738) @@ -29,7 +29,7 @@ .\" .\" $FreeBSD$ .\" -.Dd February 15, 2011 +.Dd September 15, 2011 .Dt CC_VEGAS 4 .Os .Sh NAME @@ -94,16 +94,16 @@ When setting beta, the value must satisf Default is 3. .El .Sh SEE ALSO -.Xr cc 4 , .Xr cc_chd 4 , .Xr cc_cubic 4 , .Xr cc_hd 4 , .Xr cc_htcp 4 , .Xr cc_newreno 4 , .Xr h_ertt 4 , +.Xr mod_cc 4 , .Xr tcp 4 , -.Xr cc 9 , -.Xr khelp 9 +.Xr khelp 9 , +.Xr mod_cc 9 .Rs .%A "L. S. Brakmo" .%A "L. L. Peterson" Modified: stable/8/share/man/man4/h_ertt.4 ============================================================================== --- stable/8/share/man/man4/h_ertt.4 Fri Sep 23 02:58:59 2011 (r225737) +++ stable/8/share/man/man4/h_ertt.4 Fri Sep 23 05:28:09 2011 (r225738) @@ -108,10 +108,10 @@ consumers to unset the flag if they wish new measurements. .El .Sh SEE ALSO -.Xr cc 4 , .Xr cc_chd 4 , .Xr cc_hd 4 , .Xr cc_vegas 4 , +.Xr mod_cc 4 , .Xr hhook 9 , .Xr khelp 9 .Sh ACKNOWLEDGEMENTS Copied: stable/8/share/man/man4/mod_cc.4 (from r225583, head/share/man/man4/mod_cc.4) ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ stable/8/share/man/man4/mod_cc.4 Fri Sep 23 05:28:09 2011 (r225738, copy of r225583, head/share/man/man4/mod_cc.4) @@ -0,0 +1,117 @@ +.\" +.\" Copyright (c) 2010-2011 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" This documentation was written at the Centre for Advanced Internet +.\" Architectures, Swinburne University of Technology, Melbourne, Australia by +.\" David Hayes and Lawrence Stewart under sponsorship from the FreeBSD +.\" Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR +.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd September 15, 2011 +.Dt MOD_CC 4 +.Os +.Sh NAME +.Nm mod_cc +.Nd Modular congestion control +.Sh DESCRIPTION +The modular congestion control framework allows the TCP implementation to +dynamically change the congestion control algorithm used by new and existing +connections. +Algorithms are identified by a unique +.Xr ascii 7 +name. +Algorithm modules can be compiled into the kernel or loaded as kernel modules +using the +.Xr kld 4 +facility. +.Pp +The default algorithm is NewReno, and all connections use the default unless +explicitly overridden using the TCP_CONGESTION socket option (see +.Xr tcp 4 +for details). +The default can be changed using a +.Xr sysctl 3 +MIB variable detailed in the +.Sx MIB Variables +section below. +.Sh MIB Variables +The framework exposes the following variables in the +.Va net.inet.tcp.cc +branch of the +.Xr sysctl 3 +MIB: +.Bl -tag -width ".Va available" +.It Va available +Read-only list of currently available congestion control algorithms by name. +.It Va algorithm +Returns the current default congestion control algorithm when read, and changes +the default when set. +When attempting to change the default algorithm, this variable should be set to +one of the names listed by the +.Va net.inet.tcp.cc.available +MIB variable. +.El +.Sh SEE ALSO +.Xr cc_chd 4 , +.Xr cc_cubic 4 , +.Xr cc_hd 4 , +.Xr cc_htcp 4 , +.Xr cc_newreno 4 , +.Xr cc_vegas 4 , +.Xr tcp 4 , +.Xr mod_cc 9 +.Sh ACKNOWLEDGEMENTS +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. +.Sh HISTORY +The +.Nm +modular congestion control framework first appeared in +.Fx 9.0 . +.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: +.Pp +http://caia.swin.edu.au/urp/newtcp/ +.Sh AUTHORS +.An -nosplit +The +.Nm +facility was written by +.An Lawrence Stewart Aq lstewart@FreeBSD.org , +.An James Healy Aq jimmy@deefa.com +and +.An David Hayes Aq david.hayes@ieee.org . +.Pp +This manual page was written by +.An David Hayes Aq david.hayes@ieee.org +and +.An Lawrence Stewart Aq lstewart@FreeBSD.org . Modified: stable/8/share/man/man4/tcp.4 ============================================================================== --- stable/8/share/man/man4/tcp.4 Fri Sep 23 02:58:59 2011 (r225737) +++ stable/8/share/man/man4/tcp.4 Fri Sep 23 05:28:09 2011 (r225738) @@ -38,7 +38,7 @@ .\" From: @(#)tcp.4 8.1 (Berkeley) 6/5/93 .\" $FreeBSD$ .\" -.Dd February 15, 2011 +.Dd September 15, 2011 .Dt TCP 4 .Os .Sh NAME @@ -144,7 +144,7 @@ bandwidth-controlled window space. Select or query the congestion control algorithm that TCP will use for the connection. See -.Xr cc 4 +.Xr mod_cc 4 for details. .It Dv TCP_NODELAY Under most circumstances, @@ -249,7 +249,7 @@ The default congestion control algorithm is .Xr cc_newreno 4 . Other congestion control algorithms can be made available using the -.Xr cc 4 +.Xr mod_cc 4 framework. .Ss MIB Variables The @@ -576,10 +576,10 @@ address. .Xr socket 2 , .Xr sysctl 3 , .Xr blackhole 4 , -.Xr cc 4 , .Xr inet 4 , .Xr intro 4 , .Xr ip 4 , +.Xr mod_cc 4 , .Xr syncache 4 , .Xr setkey 8 .Rs Modified: stable/8/share/man/man9/Makefile ============================================================================== --- stable/8/share/man/man9/Makefile Fri Sep 23 02:58:59 2011 (r225737) +++ stable/8/share/man/man9/Makefile Fri Sep 23 05:28:09 2011 (r225738) @@ -44,7 +44,6 @@ MAN= accept_filter.9 \ BUS_SETUP_INTR.9 \ bus_space.9 \ byteorder.9 \ - cc.9 \ cd.9 \ condvar.9 \ config_intrhook.9 \ @@ -170,6 +169,7 @@ MAN= accept_filter.9 \ microtime.9 \ microuptime.9 \ mi_switch.9 \ + mod_cc.9 \ module.9 \ MODULE_DEPEND.9 \ MODULE_VERSION.9 \ Copied: stable/8/share/man/man9/mod_cc.9 (from r225583, head/share/man/man9/mod_cc.9) ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ stable/8/share/man/man9/mod_cc.9 Fri Sep 23 05:28:09 2011 (r225738, copy of r225583, head/share/man/man9/mod_cc.9) @@ -0,0 +1,333 @@ +.\" +.\" Copyright (c) 2008-2009 Lawrence Stewart +.\" Copyright (c) 2010-2011 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" Portions of this documentation were written at the Centre for Advanced +.\" Internet Architectures, Swinburne University of Technology, Melbourne, +.\" Australia by David Hayes and Lawrence Stewart under sponsorship from the +.\" FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR +.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd September 15, 2011 +.Dt MOD_CC 9 +.Os +.Sh NAME +.Nm mod_cc , +.Nm DECLARE_CC_MODULE , +.Nm CC_VAR +.Nd Modular Congestion Control +.Sh SYNOPSIS +.In netinet/cc.h +.In netinet/cc/cc_module.h +.Fn DECLARE_CC_MODULE "ccname" "ccalgo" +.Fn CC_VAR "ccv" "what" +.Sh DESCRIPTION +The +.Nm +framework allows congestion control algorithms to be implemented as dynamically +loadable kernel modules via the +.Xr kld 4 +facility. +Transport protocols can select from the list of available algorithms on a +connection-by-connection basis, or use the system default (see +.Xr mod_cc 4 +for more details). +.Pp +.Nm +modules are identified by an +.Xr ascii 7 +name and set of hook functions encapsulated in a +.Vt "struct cc_algo" , +which has the following members: +.Bd -literal -offset indent +struct cc_algo { + char name[TCP_CA_NAME_MAX]; + int (*mod_init) (void); + int (*mod_destroy) (void); + int (*cb_init) (struct cc_var *ccv); + 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); +}; +.Ed +.Pp +The +.Va name +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 +.In netinet/tcp.h +for compatibility reasons). +.Pp +The +.Va mod_init +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 +.Va mod_init +will cause the loading of the module to fail. +.Pp +The +.Va mod_destroy +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. +.Pp +The +.Va cb_init +function is called when a TCP control block +.Vt struct tcpcb +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 +.Va cb_init +will cause the connection set up to be aborted, terminating the connection as a +result. +.Pp +The +.Va cb_destroy +function is called when a TCP control block +.Vt struct tcpcb +is destroyed. +It should be implemented if a module needs to free memory allocated in +.Va cb_init . +.Pp +The +.Va conn_init +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. +.Pp +The +.Va ack_received +function is called when a TCP acknowledgement (ACK) packet is received. +Modules use the +.Fa type +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. +.Pp +The +.Va cong_signal +function is called when a congestion event is detected by the TCP stack. +Modules use the +.Fa type +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). +.Pp +The +.Va post_recovery +function is called after the TCP connection has recovered from a congestion event. +It should be implemented to adjust state as required. +.Pp +The +.Va after_idle +function is called when data transfer resumes after an idle period. +It should be implemented to adjust state as required. +.Pp +The +.Fn DECLARE_CC_MODULE +macro provides a convenient wrapper around the +.Xr DECLARE_MODULE 9 +macro, and is used to register a +.Nm +module with the +.Nm +framework. +The +.Fa ccname +argument specifies the module's name. +The +.Fa ccalgo +argument points to the module's +.Vt struct cc_algo . +.Pp +.Nm +modules must instantiate a +.Vt struct cc_algo , +but are only required to set the name field, and optionally any of the function +pointers. +The stack will skip calling any function pointer which is NULL, so there is no +requirement to implement any of the function pointers. +Using the C99 designated initialiser feature to set fields is encouraged. +.Pp +Each function pointer which deals with congestion control state is passed a +pointer to a +.Vt struct cc_var , +which has the following members: +.Bd -literal -offset indent +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; +}; +.Ed +.Pp +.Vt struct cc_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 +.Nm +modules to be shared between all congestion aware transport protocols, though +currently only +.Xr tcp 4 +is supported. +.Pp +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 +.Fn CC_VAR +macro exists as a convenience accessor. +The +.Fa ccv +argument points to the +.Vt struct cc_var +passed into the function by the +.Nm +framework. +The +.Fa what +argument specifies the name of the variable to access. +.Pp +Apart from the +.Va type +and +.Va ccv_container +fields, the remaining fields in +.Vt struct cc_var +are for use by +.Nm +modules. +.Pp +The +.Va cc_data +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 +.Va cb_init +hook function. +.Pp +The +.Va bytes_this_ack +field specifies the number of new bytes acknowledged by the most recently +received ACK packet. +It is only valid in the +.Va ack_received +hook function. +.Pp +The +.Va curack +field specifies the sequence number of the most recently received ACK packet. +It is only valid in the +.Va ack_received , +.Va cong_signal +and +.Va post_recovery +hook functions. +.Pp +The +.Va flags +field is used to pass useful information from the stack to a +.Nm +module. +The CCF_ABC_SENTAWND flag is relevant in +.Va ack_received +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 +.Va ack_received +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 abscence of this flag being set to avoid accumulating +a large difference between the congestion window and send window. +.Sh SEE ALSO +.Xr cc_chd 4 , +.Xr cc_cubic 4 , +.Xr cc_hd 4 , +.Xr cc_htcp 4 , +.Xr cc_newreno 4 , +.Xr cc_vegas 4 , +.Xr mod_cc 4 , +.Xr tcp 4 +.Sh ACKNOWLEDGEMENTS +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. +.Sh FUTURE WORK +Integrate with +.Xr sctp 4 . +.Sh HISTORY +The modular Congestion Control (CC) framework first appeared in +.Fx 9.0 . +.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: +.Pp +http://caia.swin.edu.au/urp/newtcp/ +.Sh AUTHORS +.An -nosplit +The +.Nm +framework was written by +.An Lawrence Stewart Aq lstewart@FreeBSD.org , +.An James Healy Aq jimmy@deefa.com +and +.An David Hayes Aq david.hayes@ieee.org . +.Pp +This manual page was written by +.An David Hayes Aq david.hayes@ieee.org +and +.An Lawrence Stewart Aq lstewart@FreeBSD.org .