Skip site navigation (1)Skip section navigation (2)
Date:      Fri, 23 Sep 2011 05:28:09 +0000 (UTC)
From:      Lawrence Stewart <lstewart@FreeBSD.org>
To:        src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-stable@freebsd.org, svn-src-stable-8@freebsd.org
Subject:   svn commit: r225738 - in stable/8: . share/man/man4 share/man/man7 share/man/man9
Message-ID:  <201109230528.p8N5S90n056304@svn.freebsd.org>

next in thread | raw e-mail | index | archive | help
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 <lstewart@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@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 .



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201109230528.p8N5S90n056304>