--- name: "mod_cc" section: "9" platform: "freebsd" package: "base" version: "16.0-CURRENT-20261027-61c70dc16a79" release: "FreeBSD 16.0-CURRENT (2026-10-27)" platforms: ["freebsd"] url: "https://new.carta.tech/CCV" --- # mod\_cc(9) Modular Congestion Control Part of [CCV(9)](/CCV/9.md). ## NAME **mod\_cc**, **DECLARE\_CC\_MODULE**, **CCV** – Modular Congestion Control ## SYNOPSIS **#include \** **#include \** **#include \** **DECLARE\_CC\_MODULE**(*ccname*, *ccalgo*); **CCV**(*ccv*, *what*); ## DESCRIPTION The **mod\_cc** framework allows congestion control algorithms to be implemented as dynamically loadable kernel modules via the [kld(4)](/kld/4.md) 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)](/mod_cc/4.md) for more details). **mod\_cc** modules are identified by an [ascii(7)](/ascii/7.md) 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); size_t (*cc_data_sz)(void); int (*cb_init) (struct cc_var *ccv, void *ptr); 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); int (*ctl_output)(struct cc_var *, struct sockopt *, void *); void (*rttsample)(struct cc_var *, uint32_t, uint32_t, uint32_t); void (*newround)(struct cc_var *, uint32_t); }; ``` 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 *cc\_data\_sz* function is called by the socket option code to get the size of data that the *cb\_init* function needs. The socket option code then preallocates the modules memory so that the *cb\_init* function will not fail (the socket option code uses M\_WAITOK with no locks held to do this). 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. Note that the ptr argument passed to the function should be checked to see if it is non-NULL, if so it is preallocated memory that the cb\_init function must use instead of calling malloc itself. 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 allocated 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 initialise 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 previously unacknowledged data. CC\_DUPACK indicates the received ACK acknowledges 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 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). The *post\_recovery* function is called after the TCP connection has recovered from a congestion event. It should be implemented to adjust state as required. The *after\_idle* function is called when data transfer resumes after an idle period. It should be implemented to adjust state as required. The *ctl\_output* function is called when [getsockopt(2)](/getsockopt/2.md) or [setsockopt(2)](/setsockopt/2.md) is called on a [tcp(4)](/tcp/4.md) socket with the *struct* *sockopt* pointer forwarded unmodified from the TCP control, and a *void* *\** pointer to algorithm specific argument. The *rttsample* function is called to pass round trip time information to the congestion controller. The additional arguments to the function include the microsecond RTT that is being noted, the number of times that the data being acknowledged was retransmitted as well as the flightsize at send. For transports that do not track flightsize at send, this variable will be the current cwnd at the time of the call. The *newround* function is called each time a new round trip time begins. The montonically increasing round number is also passed to the congestion controller as well. This can be used for various purposes by the congestion controller (e.g Hystart++). Note that currently not all TCP stacks call the *rttsample* and *newround* function so dependency on these functions is also dependent upon which TCP stack is in use. The **DECLARE\_CC\_MODULE**() macro provides a convenient wrapper around the [DECLARE\_MODULE(9)](/DECLARE_MODULE/9.md) 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. Note that if a module defines the *cb\_init* function it also must define a *cc\_data\_sz* function. This is because when switching from one congestion control module to another the socket option code will preallocate memory for the *cb\_init* function. If no memory is allocated by the modules *cb\_init* then the *cc\_data\_sz* function should return 0. The stack will skip calling any function pointer which is NULL, so there is no requirement to implement any of the function pointers (with the exception of the cb\_init \<-\> cc\_data\_sz dependency noted above). Using the C99 designated 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; uint16_t nsegs; uint8_t labc; }; ``` *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 protocols, though currently only [tcp(4)](/tcp/4.md) 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 **CCV**() macro exists as a convenience accessor. 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 variable 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-connection 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 received 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. Algorithms should use the absence of this flag being set to avoid accumulating a large difference between the congestion window and send window. The *nsegs* variable is used to pass in how much compression was done by the local LRO system. So for example if LRO pushed three in-order acknowledgements into one acknowledgement the variable would be set to three. The *labc* variable is used in conjunction with the CCF\_USE\_LOCAL\_ABC flag to override what labc variable the congestion controller will use for this particular acknowledgement. ## SEE ALSO [cc\_cdg(4)](/cc_cdg/4.md), [cc\_chd(4)](/cc_chd/4.md), [cc\_cubic(4)](/cc_cubic/4.md), [cc\_dctcp(4)](/cc_dctcp/4.md), [cc\_hd(4)](/cc_hd/4.md), [cc\_htcp(4)](/cc_htcp/4.md), [cc\_newreno(4)](/cc_newreno/4.md), [cc\_vegas(4)](/cc_vegas/4.md), [mod\_cc(4)](/mod_cc/4.md), [tcp(4)](/tcp/4.md) ## 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)](/sctp/4.md). ## 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 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: 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*⟩.