Changeset View
Changeset View
Standalone View
Standalone View
share/man/man9/mod_cc.9
Show First 20 Lines • Show All 62 Lines • ▼ Show 20 Lines | |||||
name and set of hook functions encapsulated in a | name and set of hook functions encapsulated in a | ||||
.Vt "struct cc_algo" , | .Vt "struct cc_algo" , | ||||
which has the following members: | which has the following members: | ||||
.Bd -literal -offset indent | .Bd -literal -offset indent | ||||
struct cc_algo { | struct cc_algo { | ||||
char name[TCP_CA_NAME_MAX]; | char name[TCP_CA_NAME_MAX]; | ||||
int (*mod_init) (void); | int (*mod_init) (void); | ||||
int (*mod_destroy) (void); | int (*mod_destroy) (void); | ||||
int (*cb_init) (struct cc_var *ccv); | size_t (*cc_data_sz)(void); | ||||
int (*cb_init) (struct cc_var *ccv, void *ptr); | |||||
void (*cb_destroy) (struct cc_var *ccv); | void (*cb_destroy) (struct cc_var *ccv); | ||||
void (*conn_init) (struct cc_var *ccv); | void (*conn_init) (struct cc_var *ccv); | ||||
void (*ack_received) (struct cc_var *ccv, uint16_t type); | void (*ack_received) (struct cc_var *ccv, uint16_t type); | ||||
void (*cong_signal) (struct cc_var *ccv, uint32_t type); | void (*cong_signal) (struct cc_var *ccv, uint32_t type); | ||||
void (*post_recovery) (struct cc_var *ccv); | void (*post_recovery) (struct cc_var *ccv); | ||||
void (*after_idle) (struct cc_var *ccv); | void (*after_idle) (struct cc_var *ccv); | ||||
int (*ctl_output)(struct cc_var *, struct sockopt *, void *); | 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); | |||||
}; | }; | ||||
.Ed | .Ed | ||||
.Pp | .Pp | ||||
The | The | ||||
.Va name | .Va name | ||||
field identifies the unique name of the algorithm, and should be no longer than | 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 | TCP_CA_NAME_MAX-1 characters in length (the TCP_CA_NAME_MAX define lives in | ||||
.In netinet/tcp.h | .In netinet/tcp.h | ||||
Show All 12 Lines | |||||
The | The | ||||
.Va mod_destroy | .Va mod_destroy | ||||
function is called prior to unloading an existing module from the kernel. | 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 | It should be implemented if a module needs to clean up any global state before | ||||
being removed from the kernel. | being removed from the kernel. | ||||
The return value is currently ignored. | The return value is currently ignored. | ||||
.Pp | .Pp | ||||
The | The | ||||
.Va cc_data_sz | |||||
function is called by the socket option code to get the size of | |||||
data that the | |||||
.Va cb_init | .Va cb_init | ||||
function needs. | |||||
gbe: New sentence, new line. | |||||
The socket option code then preallocates the modules memory so that the | |||||
.Va cb_init | |||||
function will not fail (the socket option code uses M_WAITOK with | |||||
no locks held to do this). | |||||
.Pp | |||||
The | |||||
.Va cb_init | |||||
function is called when a TCP control block | function is called when a TCP control block | ||||
.Vt struct tcpcb | .Vt struct tcpcb | ||||
is created. | is created. | ||||
It should be implemented if a module needs to allocate memory for storing | It should be implemented if a module needs to allocate memory for storing | ||||
private per-connection state. | private per-connection state. | ||||
Returning a non-zero value from | Returning a non-zero value from | ||||
.Va cb_init | .Va cb_init | ||||
will cause the connection set up to be aborted, terminating the connection as a | will cause the connection set up to be aborted, terminating the connection as a | ||||
result. | 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. | |||||
.Pp | .Pp | ||||
The | The | ||||
.Va cb_destroy | .Va cb_destroy | ||||
function is called when a TCP control block | function is called when a TCP control block | ||||
.Vt struct tcpcb | .Vt struct tcpcb | ||||
is destroyed. | is destroyed. | ||||
It should be implemented if a module needs to free memory allocated in | It should be implemented if a module needs to free memory allocated in | ||||
.Va cb_init . | .Va cb_init . | ||||
▲ Show 20 Lines • Show All 52 Lines • ▼ Show 20 Lines | |||||
.Xr tcp 4 | .Xr tcp 4 | ||||
socket with the | socket with the | ||||
.Va struct sockopt | .Va struct sockopt | ||||
pointer forwarded unmodified from the TCP control, and a | pointer forwarded unmodified from the TCP control, and a | ||||
.Va void * | .Va void * | ||||
pointer to algorithm specific argument. | pointer to algorithm specific argument. | ||||
.Pp | .Pp | ||||
The | The | ||||
.Va rttsample | |||||
function is called to pass round trip time information to the | |||||
congestion controller. | |||||
Done Inline ActionsNew sentence, new line. gbe: New sentence, new line. | |||||
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. | |||||
.Pp | |||||
The | |||||
.Va 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. | |||||
Done Inline ActionsNew sentence, new line. gbe: New sentence, new line. | |||||
This can be used for various purposes by the congestion controller (e.g Hystart++). | |||||
.Pp | |||||
Note that currently not all TCP stacks call the | |||||
.Va rttsample | |||||
and | |||||
.Va newround | |||||
function so dependancy on these functions is also | |||||
dependant upon which TCP stack is in use. | |||||
.Pp | |||||
The | |||||
.Fn DECLARE_CC_MODULE | .Fn DECLARE_CC_MODULE | ||||
macro provides a convenient wrapper around the | macro provides a convenient wrapper around the | ||||
.Xr DECLARE_MODULE 9 | .Xr DECLARE_MODULE 9 | ||||
macro, and is used to register a | macro, and is used to register a | ||||
.Nm | .Nm | ||||
module with the | module with the | ||||
.Nm | .Nm | ||||
framework. | framework. | ||||
The | The | ||||
.Fa ccname | .Fa ccname | ||||
argument specifies the module's name. | argument specifies the module's name. | ||||
The | The | ||||
.Fa ccalgo | .Fa ccalgo | ||||
argument points to the module's | argument points to the module's | ||||
.Vt struct cc_algo . | .Vt struct cc_algo . | ||||
.Pp | .Pp | ||||
.Nm | .Nm | ||||
modules must instantiate a | modules must instantiate a | ||||
.Vt struct cc_algo , | .Vt struct cc_algo , | ||||
but are only required to set the name field, and optionally any of the function | but are only required to set the name field, and optionally any of the function | ||||
pointers. | pointers. | ||||
Note that if a module defines the | |||||
.Va cb_init | |||||
function it also must define a | |||||
.Va cc_data_sz | |||||
function. | |||||
Done Inline ActionsNew sentence, new line. gbe: New sentence, new line. | |||||
This is because when switching from one congestion control | |||||
module to another the socket option code will preallocate memory for the | |||||
.Va cb_init | |||||
function. If no memory is allocated by the modules | |||||
.Va cb_init | |||||
then the | |||||
.Va cc_data_sz | |||||
function should return 0. | |||||
.Pp | |||||
The stack will skip calling any function pointer which is NULL, so there is no | The stack will skip calling any function pointer which is NULL, so there is no | ||||
requirement to implement any of the function pointers. | requirement to implement any of the function pointers (with the exception of | ||||
the cb_init <-> cc_data_sz dependancy noted above). | |||||
Using the C99 designated initialiser feature to set fields is encouraged. | Using the C99 designated initialiser feature to set fields is encouraged. | ||||
.Pp | .Pp | ||||
Each function pointer which deals with congestion control state is passed a | Each function pointer which deals with congestion control state is passed a | ||||
pointer to a | pointer to a | ||||
.Vt struct cc_var , | .Vt struct cc_var , | ||||
which has the following members: | which has the following members: | ||||
.Bd -literal -offset indent | .Bd -literal -offset indent | ||||
struct cc_var { | struct cc_var { | ||||
void *cc_data; | void *cc_data; | ||||
int bytes_this_ack; | int bytes_this_ack; | ||||
tcp_seq curack; | tcp_seq curack; | ||||
uint32_t flags; | uint32_t flags; | ||||
int type; | int type; | ||||
union ccv_container { | union ccv_container { | ||||
struct tcpcb *tcp; | struct tcpcb *tcp; | ||||
struct sctp_nets *sctp; | struct sctp_nets *sctp; | ||||
} ccvc; | } ccvc; | ||||
uint16_t nsegs; | |||||
uint8_t labc; | |||||
}; | }; | ||||
.Ed | .Ed | ||||
.Pp | .Pp | ||||
.Vt struct cc_var | .Vt struct cc_var | ||||
groups congestion control related variables into a single, embeddable structure | groups congestion control related variables into a single, embeddable structure | ||||
and adds a layer of indirection to accessing transport protocol control blocks. | and adds a layer of indirection to accessing transport protocol control blocks. | ||||
The eventual goal is to allow a single set of | The eventual goal is to allow a single set of | ||||
.Nm | .Nm | ||||
▲ Show 20 Lines • Show All 67 Lines • ▼ Show 20 Lines | |||||
It is the module's responsibility to clear the flag after it has processed the | It is the module's responsibility to clear the flag after it has processed the | ||||
signal. | signal. | ||||
The CCF_CWND_LIMITED flag is relevant in | The CCF_CWND_LIMITED flag is relevant in | ||||
.Va ack_received | .Va ack_received | ||||
and is set when the connection's ability to send data is currently constrained | and is set when the connection's ability to send data is currently constrained | ||||
by the value of the congestion window. | by the value of the congestion window. | ||||
Algorithms should use the absence of this flag being set to avoid accumulating | Algorithms should use the absence of this flag being set to avoid accumulating | ||||
a large difference between the congestion window and send window. | a large difference between the congestion window and send window. | ||||
.Pp | |||||
The | |||||
.Va nsegs | |||||
variable is used to pass in how much compression was done by the local | |||||
LRO system. | |||||
Done Inline ActionsNew sentence, new line. gbe: New sentence, new line. | |||||
So for example if LRO pushed three in-order acknowledgements into | |||||
one acknowledgement the variable would be set to three. | |||||
.Pp | |||||
The | |||||
.Va 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. | |||||
.Sh SEE ALSO | .Sh SEE ALSO | ||||
.Xr cc_cdg 4 , | .Xr cc_cdg 4 , | ||||
.Xr cc_chd 4 , | .Xr cc_chd 4 , | ||||
.Xr cc_cubic 4 , | .Xr cc_cubic 4 , | ||||
.Xr cc_dctcp 4 , | .Xr cc_dctcp 4 , | ||||
.Xr cc_hd 4 , | .Xr cc_hd 4 , | ||||
.Xr cc_htcp 4 , | .Xr cc_htcp 4 , | ||||
.Xr cc_newreno 4 , | .Xr cc_newreno 4 , | ||||
Show All 36 Lines |
New sentence, new line.