svn commit: r225738 - in stable/8: . share/man/man4 share/man/man7
share/man/man9
Lawrence Stewart
lstewart at FreeBSD.org
Fri Sep 23 05:28:10 UTC 2011
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 at FreeBSD.org ,
+.An James Healy Aq jimmy at deefa.com
+and
+.An David Hayes Aq david.hayes at ieee.org .
+.Pp
+This manual page was written by
+.An David Hayes Aq david.hayes at ieee.org
+and
+.An Lawrence Stewart Aq lstewart at 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 <lstewart at FreeBSD.org>
+.\" 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 at FreeBSD.org ,
+.An James Healy Aq jimmy at deefa.com
+and
+.An David Hayes Aq david.hayes at ieee.org .
+.Pp
+This manual page was written by
+.An David Hayes Aq david.hayes at ieee.org
+and
+.An Lawrence Stewart Aq lstewart at FreeBSD.org .
More information about the svn-src-stable-8
mailing list