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 register_tcp_functions_as_name "struct tcp_function_block *blk" \
41 "const char *name" "int wait"
42 .Fn register_tcp_functions_as_names "struct tcp_function_block *blk" \
43 "int wait" "const char *names[]" "int *num_names"
45 .Fn deregister_tcp_functions "struct tcp_function_block *blk"
49 framework allows a kernel developer to implement alternate TCP stacks.
50 The alternate stacks can be compiled in the kernel or can be implemented in
51 loadable kernel modules.
52 This functionality is intended to encourage experimentation with the TCP stack
53 and to allow alternate behaviors to be deployed for different TCP connections
56 A system administrator can set a system default stack.
57 By default, all TCP connections will use the system default stack.
58 Additionally, users can specify a particular stack to use on a per-connection
62 for details on setting the system default stack, or selecting a specific stack
63 for a given connection.)
65 This man page treats "TCP stacks" as synonymous with "function blocks".
67 A "TCP stack" is a collection of functions that implement a set of behavior.
68 Therefore, an alternate "function block" defines an alternate "TCP stack".
71 .Fn register_tcp_functions ,
72 .Fn register_tcp_functions_as_name ,
74 .Fn register_tcp_functions_as_names
75 functions request that the system add a specified function block
76 and register it for use with a given name.
77 Modules may register the same function block multiple times with different
79 However, names must be globally unique among all registered function blocks.
80 Also, modules may not ever modify the contents of the function block (including
81 the name) after it has been registered, unless the module first successfully
82 de-registers the function block.
85 .Fn register_tcp_functions
86 function requests that the system register the function block with the name
87 defined in the function block's
88 .Va tfb_tcp_block_name
90 Note that this is the only one of the three registration functions that
91 automatically registers the function block using the name defined in the
93 .Va tfb_tcp_block_name
95 If a module uses one of the other registration functions, it may request that
96 the system register the function block using the name defined in the
98 .Va tfb_tcp_block_name
99 field by explicitly providing that name.
102 .Fn register_tcp_functions_as_name
103 function requests that the system register the function block with the name
109 .Fn register_tcp_functions_as_names
110 function requests that the system register the function block with all the
111 names provided in the
116 argument provides a pointer to the number of names.
117 This function will either succeed in registering all of the names in the array,
118 or none of the names in the array.
121 argument is updated with the index number of the entry in the
123 array which the system was processing when it encountered the error.
126 .Fn deregister_tcp_functions
127 function requests that the system remove a specified function block from the
129 If this call succeeds, it will completely deregister the function block,
130 regardless of the number of names used to register the function block.
131 If the call fails because sockets are still using the specified function block,
132 the system will mark the function block as being in the process of being
134 This will prevent additional sockets from using the specified function block.
135 However, it will not impact sockets that are already using the function block.
138 modules must call one or more of the registration functions during
139 initialization and successfully call the
140 .Fn deregister_tcp_functions
141 function prior to allowing the module to be unloaded.
145 argument is a pointer to a
146 .Vt "struct tcp_function_block" ,
147 which is explained below (see
148 .Sx Function Block Structure ) .
151 argument is used as the
155 and must be set to one of the valid values defined in that man page.
156 .Ss Function Block Structure
158 .Fa blk argument is a pointer to a
159 .Vt "struct tcp_function_block" ,
160 which has the following members:
161 .Bd -literal -offset indent
162 struct tcp_function_block {
163 char tfb_tcp_block_name[TCP_FUNCTION_NAME_LEN_MAX];
164 int (*tfb_tcp_output)(struct tcpcb *);
165 void (*tfb_tcp_do_segment)(struct mbuf *, struct tcphdr *,
166 struct socket *, struct tcpcb *,
169 int (*tfb_tcp_ctloutput)(struct socket *so,
170 struct sockopt *sopt,
171 struct inpcb *inp, struct tcpcb *tp);
172 /* Optional memory allocation/free routine */
173 void (*tfb_tcp_fb_init)(struct tcpcb *);
174 void (*tfb_tcp_fb_fini)(struct tcpcb *, int);
175 /* Optional timers, must define all if you define one */
176 int (*tfb_tcp_timer_stop_all)(struct tcpcb *);
177 void (*tfb_tcp_timer_activate)(struct tcpcb *,
179 int (*tfb_tcp_timer_active)(struct tcpcb *, uint32_t);
180 void (*tfb_tcp_timer_stop)(struct tcpcb *, uint32_t);
181 /* Optional functions */
182 void (*tfb_tcp_rexmit_tmr)(struct tcpcb *);
183 void (*tfb_tcp_handoff_ok)(struct tcpcb *);
185 volatile uint32_t tfb_refcnt;
191 .Va tfb_tcp_block_name
192 field identifies the unique name of the TCP stack, and should be no longer than
193 TCP_FUNCTION_NAME_LEN_MAX-1 characters in length.
197 .Va tfb_tcp_do_segment ,
199 .Va tfb_tcp_ctloutput
200 fields are pointers to functions that perform the equivalent actions
205 .Fn tcp_default_ctloutput
206 functions, respectively.
207 Each of these function pointers must be non-NULL.
209 If a TCP stack needs to initialize data when a socket first selects the TCP
210 stack (or, when the socket is first opened), it should set a non-NULL
214 Likewise, if a TCP stack needs to cleanup data when a socket stops using the
215 TCP stack (or, when the socket is closed), it should set a non-NULL pointer
222 argument is non-NULL, the function to which it points is called when the
223 kernel is destroying the TCP control block or when the socket is transitioning
224 to use a different TCP stack.
225 The function is called with arguments of the TCP control block and an integer
227 The flag will be zero if the socket is transitioning to use another TCP stack
228 or one if the TCP control block is being destroyed.
230 If the TCP stack implements additional timers, the TCP stack should set a
231 non-NULL pointer in the
232 .Va tfb_tcp_timer_stop_all ,
233 .Va tfb_tcp_timer_activate ,
234 .Va tfb_tcp_timer_active ,
236 .Va tfb_tcp_timer_stop
238 These fields should all be
240 or should all contain pointers to functions.
242 .Va tfb_tcp_timer_activate ,
243 .Va tfb_tcp_timer_active ,
245 .Va tfb_tcp_timer_stop
246 functions will be called when the
247 .Fn tcp_timer_activate ,
248 .Fn tcp_timer_active ,
251 functions, respectively, are called with a timer type other than the standard
253 The functions defined by the TCP stack have the same semantics (both for
254 arguments and return values) as the normal timer functions they supplement.
256 Additionally, a stack may define its own actions to take when the retransmit
257 timer fires by setting a non-NULL function pointer in the
258 .Va tfb_tcp_rexmit_tmr
260 This function is called very early in the process of handling a retransmit
262 However, care must be taken to ensure the retransmit timer leaves the
263 TCP control block in a valid state for the remainder of the retransmit
266 A user may select a new TCP stack before calling
270 Optionally, a TCP stack may also allow a user to begin using the TCP stack for
271 a connection that is in a later state by setting a non-NULL function pointer in
273 .Va tfb_tcp_handoff_ok
275 If this field is non-NULL and a user attempts to select that TCP stack after
280 for that socket, the kernel will call the function pointed to by the
281 .Va tfb_tcp_handoff_ok
283 The function should return 0 if the user is allowed to switch the socket to use
284 the TCP stack. Otherwise, the function should return an error code, which will
285 be returned to the user.
287 .Va tfb_tcp_handoff_ok
290 and a user attempts to select the TCP stack after calling
294 for that socket, the operation will fail and the kernel will return
301 fields are used by the kernel's TCP code and will be initialized when the
302 TCP stack is registered.
303 .Ss Requirements for Alternate TCP Stacks
304 If the TCP stack needs to store data beyond what is stored in the default
305 TCP control block, the TCP stack can initialize its own per-connection storage.
310 control block structure has been reserved to hold a pointer to this
311 per-connection storage.
312 If the TCP stack uses this alternate storage, it should understand that the
315 pointer may not be initialized to
317 Therefore, it should use a
319 function to initialize this field.
320 Additionally, it should use a
322 function to deallocate storage when the socket is closed.
324 It is understood that alternate TCP stacks may keep different sets of data.
325 However, in order to ensure that data is available to both the user and the
326 rest of the system in a standardized format, alternate TCP stacks must
327 update all fields in the TCP control block to the greatest extent practical.
330 .Fn register_tcp_functions ,
331 .Fn register_tcp_functions_as_name ,
332 .Fn register_tcp_functions_as_names ,
334 .Fn deregister_tcp_functions
335 functions return zero on success and non-zero on failure.
337 .Fn deregister_tcp_functions
340 until no more connections are using the specified TCP stack.
342 .Fn deregister_tcp_functions
343 must be prepared to wait until all connections have stopped using the
347 .Fn register_tcp_functions
348 function will fail if:
351 Any of the members of the
353 argument are set incorrectly.
355 The function could not allocate memory for its internal data.
357 A function block is already registered with the same name.
360 .Fn deregister_tcp_functions
361 function will fail if:
366 argument references the kernel's compiled-in default function block.
368 The function block is still in use by one or more sockets, or is defined as
369 the current default function block.
373 argument references a function block that is not currently registered.
381 This framework first appeared in
387 framework was written by
388 .An Randall Stewart Aq Mt rrs@FreeBSD.org .
390 This manual page was written by
391 .An Jonathan Looney Aq Mt jtl@FreeBSD.org .