home | help
MOD_CC(9)		    Kernel Developer's Manual		       MOD_CC(9)

NAME
     mod_cc, DECLARE_CC_MODULE, CC_VAR -- Modular Congestion Control

SYNOPSIS
     #include <netinet/cc.h>
     #include <netinet/cc/cc_module.h>

     DECLARE_CC_MODULE(ccname, ccalgo);

     CC_VAR(ccv, what);

DESCRIPTION
     The mod_cc framework allows congestion control algorithms to be implemented
     as  dynamically loadable kernel modules via the 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 mod_cc(4) for more  de-
     tails).

     mod_cc modules are identified by an ascii(7) name and set of hook functions
     encapsulated in a struct cc_algo, which has the following members:

	   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);
	   };

     The  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 <netinet/tcp.h> for compatibility reasons).

     The 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 mod_init will
     cause the loading of the module to fail.

     The 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.

     The cb_init function is called when a TCP control	block  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
     cb_init will cause the connection set up to  be  aborted,	terminating  the
     connection as a result.

     The  cb_destroy function is called when a TCP control block struct tcpcb is
     destroyed.  It should be implemented if a module needs to free memory allo-
     cated in cb_init.

     The conn_init function is called when a new connection has been established
     and variables are being initialised.  It  should  be  implemented	to  ini-
     tialise  congestion  control  algorithm variables for the newly established
     connection.

     The ack_received function is called when a TCP acknowledgement (ACK) packet
     is received.  Modules use the 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 pre-
     viously unacknowledged data.  CC_DUPACK indicates the received ACK acknowl-
     edges data we have already received an ACK for.

     The cong_signal function is called when a congestion event is  detected  by
     the  TCP stack.  Modules use the type argument as an input to their conges-
     tion 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 re-
     ported 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).

     The post_recovery function is called after the TCP connection has recovered
     from  a  congestion event.  It should be implemented to adjust state as re-
     quired.

     The after_idle function is called when data transfer resumes after an  idle
     period.  It should be implemented to adjust state as required.

     The  DECLARE_CC_MODULE() macro provides a convenient wrapper around the DE-
     CLARE_MODULE(9) macro, and is used to register a  mod_cc  module  with  the
     mod_cc  framework.   The  ccname argument specifies the module's name.  The
     ccalgo argument points to the module's struct cc_algo.

     mod_cc modules must instantiate a 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 re-
     quirement to implement any of the function pointers.  Using the C99  desig-
     nated initialiser feature to set fields is encouraged.

     Each function pointer which deals with congestion control state is passed a
     pointer to a struct cc_var, which has the following members:

	   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;
	   };

     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
     mod_cc  modules  to be shared between all congestion aware transport proto-
     cols, though currently only tcp(4) is supported.

     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 CC_VAR() macro exists as a convenience acces-
     sor.  The ccv argument points to the struct cc_var passed into the function
     by the mod_cc framework.  The what argument specifies the name of the vari-
     able to access.

     Apart from the type and  ccv_container  fields,  the  remaining  fields  in
     struct cc_var are for use by mod_cc modules.

     The cc_data field is available for algorithms requiring additional per-con-
     nection  state to attach a dynamic memory pointer to.  The memory should be
     allocated and attached in the module's cb_init hook function.

     The bytes_this_ack field specifies the number of new bytes acknowledged  by
     the   most  recently  received  ACK  packet.   It	is  only  valid  in  the
     ack_received hook function.

     The curack field specifies the sequence number of	the  most  recently  re-
     ceived  ACK  packet.  It is only valid in the ack_received, cong_signal and
     post_recovery hook functions.

     The flags field is used to pass useful information  from  the  stack  to  a
     mod_cc  module.   The CCF_ABC_SENTAWND flag is relevant in 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  ack_received and is set when the connection's ability to send
     data is currently constrained by the value of the congestion window.  Algo-
     rithms should use the abscence of this flag being set to avoid accumulating
     a large difference between the congestion window and send window.

SEE ALSO
     cc_chd(4), cc_cubic(4), cc_hd(4), cc_htcp(4),  cc_newreno(4),  cc_vegas(4),
     mod_cc(4), tcp(4)

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.

FUTURE WORK
     Integrate with sctp(4).

HISTORY
     The   modular   Congestion   Control   (CC)  framework  first  appeared  in
     FreeBSD 9.0.

     The framework was first released in 2007 by James Healy and Lawrence  Stew-
     art  whilst  working on the NewTCP research project at Swinburne University
     of Technology's Centre for Advanced Internet Architectures, Melbourne, Aus-
     tralia, which was made possible in part by a grant from the  Cisco  Univer-
     sity  Research  Program  Fund at Community Foundation Silicon Valley.  More
     details are available at:

     http://caia.swin.edu.au/urp/newtcp/

AUTHORS
     The    mod_cc    framework    was	  written    by     Lawrence	 Stewart
     <lstewart@FreeBSD.org>,  James  Healy  <jimmy@deefa.com>  and  David  Hayes
     <david.hayes@ieee.org>.

     This manual page was written  by  David  Hayes  <david.hayes@ieee.org>  and
     Lawrence Stewart <lstewart@FreeBSD.org>.

FreeBSD 8.3		       September 15, 2011		       MOD_CC(9)

home | help