b8d60729de
NOTE: HEADS UP read the note below if your kernel config is not including GENERIC!! This patch does a bit of cleanup on TCP congestion control modules. There were some rather interesting surprises that one could get i.e. where you use a socket option to change from one CC (say cc_cubic) to another CC (say cc_vegas) and you could in theory get a memory failure and end up on cc_newreno. This is not what one would expect. The new code fixes this by requiring a cc_data_sz() function so we can malloc with M_WAITOK and pass in to the init function preallocated memory. The CC init is expected in this case *not* to fail but if it does and a module does break the "no fail with memory given" contract we do fall back to the CC that was in place at the time. This also fixes up a set of common newreno utilities that can be shared amongst other CC modules instead of the other CC modules reaching into newreno and executing what they think is a "common and understood" function. Lets put these functions in cc.c and that way we have a common place that is easily findable by future developers or bug fixers. This also allows newreno to evolve and grow support for its features i.e. ABE and HYSTART++ without having to dance through hoops for other CC modules, instead both newreno and the other modules just call into the common functions if they desire that behavior or roll there own if that makes more sense. Note: This commit changes the kernel configuration!! If you are not using GENERIC in some form you must add a CC module option (one of CC_NEWRENO, CC_VEGAS, CC_CUBIC, CC_CDG, CC_CHD, CC_DCTCP, CC_HTCP, CC_HD). You can have more than one defined as well if you desire. Note that if you create a kernel configuration that does not define a congestion control module and includes INET or INET6 the kernel compile will break. Also you need to define a default, generic adds 'options CC_DEFAULT=\"newreno\" but you can specify any string that represents the name of the CC module (same names that show up in the CC module list under net.inet.tcp.cc). If you fail to add the options CC_DEFAULT in your kernel configuration the kernel build will also break. Reviewed by: Michael Tuexen Sponsored by: Netflix Inc. RELNOTES:YES Differential Revision: https://reviews.freebsd.org/D32693
189 lines
6.8 KiB
Groff
189 lines
6.8 KiB
Groff
.\"
|
|
.\" 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 August 6, 2019
|
|
.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
|
|
.Dv 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.
|
|
.Pp
|
|
Algorithm specific parameters can be set or queried using the
|
|
.Dv TCP_CCALGOOPT
|
|
socket option (see
|
|
.Xr tcp 4
|
|
for details).
|
|
Callers must pass a pointer to an algorithm specific data, and specify
|
|
its size.
|
|
.Pp
|
|
Unloading a congestion control module will fail if it is used as a
|
|
default by any Vnet.
|
|
When unloading a module, the Vnet default is
|
|
used to switch a connection to an alternate congestion control.
|
|
Note that the new congestion control module may fail to initialize its
|
|
internal memory, if so it will fail the module unload.
|
|
If this occurs often times retrying the unload will succeed since the temporary
|
|
memory shortage as the new CC module malloc's memory, that prevented the
|
|
switch is often transient.
|
|
.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 abe_frlossreduce"
|
|
.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.
|
|
.It Va abe
|
|
Enable support for RFC 8511,
|
|
which alters the window decrease factor applied to the congestion window in
|
|
response to an ECN congestion signal.
|
|
Refer to individual congestion control man pages to determine if they implement
|
|
support for ABE and for configuration details.
|
|
.It Va abe_frlossreduce
|
|
If non-zero, apply standard beta instead of ABE-beta during ECN-signalled
|
|
congestion recovery episodes if loss also needs to be repaired.
|
|
.El
|
|
.Pp
|
|
Each congestion control module may also expose other MIB variables
|
|
to control their behaviour.
|
|
.Sh Kernel Configuration
|
|
.Pp
|
|
All of the available congestion control modules may also be loaded
|
|
via kernel configutation options.
|
|
A kernel configuration is required to have at least one congestion control
|
|
algorithm built into it via kernel option and a system default specified.
|
|
Compilation of the kernel will fail if these two conditions are not met.
|
|
.Sh Kernel Configuration Options
|
|
The framework exposes the following kernel configuration options.
|
|
.Bl -tag -width ".Va CC_NEWRENO"
|
|
.It Va CC_NEWRENO
|
|
This directive loads the newreno congestion control algorithm and is included
|
|
in GENERIC by default.
|
|
.It Va CC_CUBIC
|
|
This directive loads the cubic congestion control algorithm.
|
|
.It Va CC_VEGAS
|
|
This directive loads the vegas congestion control algorithm, note that
|
|
this algorithm also requires the TCP_HHOOK option as well.
|
|
.It Va CC_CDG
|
|
This directive loads the cdg congestion control algorithm, note that
|
|
this algorithm also requires the TCP_HHOOK option as well.
|
|
.It Va CC_DCTCP
|
|
This directive loads the dctcp congestion control algorithm.
|
|
.It Va CC_HD
|
|
This directive loads the hd congestion control algorithm, note that
|
|
this algorithm also requires the TCP_HHOOK option as well.
|
|
.It Va CC_CHD
|
|
This directive loads the chd congestion control algorithm, note that
|
|
this algorithm also requires the TCP_HHOOK option as well.
|
|
.It Va CC_HTCP
|
|
This directive loads the htcp congestion control algorithm.
|
|
.It Va CC_DEFAULT
|
|
This directive specifies the string that represents the name of the system default algorithm, the GENERIC kernel
|
|
defaults this to newreno.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr cc_cdg 4 ,
|
|
.Xr cc_chd 4 ,
|
|
.Xr cc_cubic 4 ,
|
|
.Xr cc_dctcp 4 ,
|
|
.Xr cc_hd 4 ,
|
|
.Xr cc_htcp 4 ,
|
|
.Xr cc_newreno 4 ,
|
|
.Xr cc_vegas 4 ,
|
|
.Xr tcp 4 ,
|
|
.Xr config 5 ,
|
|
.Xr config 8 ,
|
|
.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 Mt lstewart@FreeBSD.org ,
|
|
.An James Healy Aq Mt jimmy@deefa.com
|
|
and
|
|
.An David Hayes Aq Mt david.hayes@ieee.org .
|
|
.Pp
|
|
This manual page was written by
|
|
.An David Hayes Aq Mt david.hayes@ieee.org
|
|
and
|
|
.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org .
|