2 .\" Copyright (c) 2016 Jonathan Looney <jtl@FreeBSD.org>
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR
18 .\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33 .Nd Alternate TCP Stack Framework
38 .Fn register_tcp_functions "struct tcp_function_block *blk" "int wait"
40 .Fn deregister_tcp_functions "struct tcp_function_block *blk"
44 framework allows a kernel developer to implement alternate TCP stacks.
45 The alternate stacks can be compiled in the kernel or can be implemented in
46 loadable kernel modules.
47 This functionality is intended to encourage experimentation with the TCP stack
48 and to allow alternate behaviors to be deployed for different TCP connections
51 A system administrator can set a system default stack.
52 By default, all TCP connections will use the system default stack.
53 Additionally, users can specify a particular stack to use on a per-connection
57 for details on setting the system default stack, or selecting a specific stack
58 for a given connection.)
60 This man page treats "TCP stacks" as synonymous with "function blocks".
62 A "TCP stack" is a collection of functions that implement a set of behavior.
63 Therefore, an alternate "function block" defines an alternate "TCP stack".
67 .Fn register_tcp_functions
68 function during initialization and successfully call the
69 .Fn deregister_tcp_functions
70 function prior to allowing the module to be unloaded.
73 .Fn register_tcp_functions
74 function requests that the system add a specified function block to the system.
77 .Fn deregister_tcp_functions
78 function requests that the system remove a specified function block from the
80 If the call fails because sockets are still using the specified function block,
81 the system will mark the function block as being in the process of being
83 This will prevent additional sockets from using the specified function block.
84 However, it will not impact sockets that are already using the function block.
88 argument is a pointer to a
89 .Vt "struct tcp_function_block" ,
90 which is explained below (see
91 .Sx Function Block Structure ) .
94 argument is used as the
98 and must be set to one of the valid values defined in that man page.
99 .Ss Function Block Structure
101 .Fa blk argument is a pointer to a
102 .Vt "struct tcp_function_block" ,
103 which has the following members:
104 .Bd -literal -offset indent
105 struct tcp_function_block {
106 char tfb_tcp_block_name[TCP_FUNCTION_NAME_LEN_MAX];
107 int (*tfb_tcp_output)(struct tcpcb *);
108 void (*tfb_tcp_do_segment)(struct mbuf *, struct tcphdr *,
109 struct socket *, struct tcpcb *,
112 int (*tfb_tcp_ctloutput)(struct socket *so,
113 struct sockopt *sopt,
114 struct inpcb *inp, struct tcpcb *tp);
115 /* Optional memory allocation/free routine */
116 void (*tfb_tcp_fb_init)(struct tcpcb *);
117 void (*tfb_tcp_fb_fini)(struct tcpcb *);
118 /* Optional timers, must define all if you define one */
119 int (*tfb_tcp_timer_stop_all)(struct tcpcb *);
120 void (*tfb_tcp_timer_activate)(struct tcpcb *,
122 int (*tfb_tcp_timer_active)(struct tcpcb *, uint32_t);
123 void (*tfb_tcp_timer_stop)(struct tcpcb *, uint32_t);
124 void (*tfb_tcp_rexmit_tmr)(struct tcpcb *);
125 volatile uint32_t tfb_refcnt;
131 .Va tfb_tcp_block_name
132 field identifies the unique name of the TCP stack, and should be no longer than
133 TCP_FUNCTION_NAME_LEN_MAX-1 characters in length.
137 .Va tfb_tcp_do_segment ,
139 .Va tfb_tcp_ctloutput
140 fields are pointers to functions that perform the equivalent actions
145 .Fn tcp_default_ctloutput
146 functions, respectively.
147 Each of these function pointers must be non-NULL.
149 If a TCP stack needs to initialize data when a socket first selects the TCP
150 stack (or, when the socket is first opened), it should set a non-NULL
154 Likewise, if a TCP stack needs to cleanup data when a socket stops using the
155 TCP stack (or, when the socket is closed), it should set a non-NULL pointer
160 If the TCP stack implements additional timers, the TCP stack should set a
161 non-NULL pointer in the
162 .Va tfb_tcp_timer_stop_all ,
163 .Va tfb_tcp_timer_activate ,
164 .Va tfb_tcp_timer_active ,
166 .Va tfb_tcp_timer_stop
168 These fields should all be
170 or should all contain pointers to functions.
172 .Va tfb_tcp_timer_activate ,
173 .Va tfb_tcp_timer_active ,
175 .Va tfb_tcp_timer_stop
176 functions will be called when the
177 .Fn tcp_timer_activate ,
178 .Fn tcp_timer_active ,
181 functions, respectively, are called with a timer type other than the standard
183 The functions defined by the TCP stack have the same semantics (both for
184 arguments and return values) as the normal timer functions they supplement.
186 Additionally, a stack may define its own actions to take when the retransmit
187 timer fires by setting a non-NULL function pointer in the
188 .Va tfb_tcp_rexmit_tmr
190 This function is called very early in the process of handling a retransmit
192 However, care must be taken to ensure the retransmit timer leaves the
193 TCP control block in a valid state for the remainder of the retransmit
200 fields are used by the kernel's TCP code and will be initialized when the
201 TCP stack is registered.
202 .Ss Requirements for Alternate TCP Stacks
203 If the TCP stack needs to store data beyond what is stored in the default
204 TCP control block, the TCP stack can initialize its own per-connection storage.
209 control block structure has been reserved to hold a pointer to this
210 per-connection storage.
211 If the TCP stack uses this alternate storage, it should understand that the
214 pointer may not be initialized to
216 Therefore, it should use a
218 function to initialize this field.
219 Additionally, it should use a
221 function to deallocate storage when the socket is closed.
223 It is understood that alternate TCP stacks may keep different sets of data.
224 However, in order to ensure that data is available to both the user and the
225 rest of the system in a standardized format, alternate TCP stacks must
226 update all fields in the TCP control block to the greatest extent practical.
229 .Fn register_tcp_functions
231 .Fn deregister_tcp_functions
232 functions return zero on success and non-zero on failure.
234 .Fn deregister_tcp_functions
237 until no more connections are using the specified TCP stack.
239 .Fn deregister_tcp_functions
240 must be prepared to wait until all connections have stopped using the
244 .Fn register_tcp_functions
245 function will fail if:
248 Any of the members of the
250 argument are set incorrectly.
252 The function could not allocate memory for its internal data.
254 A function block is already registered with the same name.
257 .Fn deregister_tcp_functions
258 function will fail if:
263 argument references the kernel's compiled-in default function block.
265 The function block is still in use by one or more sockets, or is defined as
266 the current default function block.
270 argument references a function block that is not currently registered.
275 This framework first appeared in
281 framework was written by
282 .An Randall Stewart Aq Mt rrs@FreeBSD.org .
284 This manual page was written by
285 .An Jonathan Looney Aq Mt jtl@FreeBSD.org .