share/man/man9/tcp_functions.9

   1 .\"
   2 .\" Copyright (c) 2016 Jonathan Looney <jtl@FreeBSD.org>
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   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.
  13 .\"
  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
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd June 28, 2016
  29 .Dt TCP_FUNCTIONS 9
  30 .Os
  31 .Sh NAME
  32 .Nm tcp_functions
  33 .Nd Alternate TCP Stack Framework
  34 .Sh SYNOPSIS
  35 .In netinet/tcp.h
  36 .In netinet/tcp_var.h
  37 .Ft int
  38 .Fn register_tcp_functions "struct tcp_function_block *blk" "int wait"
  39 .Ft int
  40 .Fn deregister_tcp_functions "struct tcp_function_block *blk"
  41 .Sh DESCRIPTION
  42 The
  43 .Nm
  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
  49 on a single system.
  50 .Pp
  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
  54 basis.
  55 (See
  56 .Xr tcp 4
  57 for details on setting the system default stack, or selecting a specific stack
  58 for a given connection.)
  59 .Pp
  60 This man page treats "TCP stacks" as synonymous with "function blocks".
  61 This is intentional.
  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".
  64 .Pp
  65 .Nm
  66 modules must call the
  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.
  71 .Pp
  72 The
  73 .Fn register_tcp_functions
  74 function requests that the system add a specified function block to the system.
  75 .Pp
  76 The
  77 .Fn deregister_tcp_functions
  78 function requests that the system remove a specified function block from the
  79 system.
  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
  82 removed.
  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.
  85 .Pp
  86 The
  87 .Fa blk
  88 argument is a pointer to a
  89 .Vt "struct tcp_function_block" ,
  90 which is explained below (see
  91 .Sx Function Block Structure ) .
  92 The
  93 .Fa wait
  94 argument is used as the
  95 .Fa flags
  96 argument to
  97 .Xr malloc 9 ,
  98 and must be set to one of the valid values defined in that man page.
  99 .Ss Function Block Structure
 100 The
 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 *,
 110                             int, int, uint8_t,
 111                             int);
 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 *, int);
 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 *,
 121                             uint32_t, u_int);
 122         int     (*tfb_tcp_timer_active)(struct tcpcb *, uint32_t);
 123         void    (*tfb_tcp_timer_stop)(struct tcpcb *, uint32_t);
 124         /* Optional functions */
 125         void    (*tfb_tcp_rexmit_tmr)(struct tcpcb *);
 126         void    (*tfb_tcp_handoff_ok)(struct tcpcb *);
 127         /* System use */
 128         volatile uint32_t tfb_refcnt;
 129         uint32_t  tfb_flags;
 130 };
 131 .Ed
 132 .Pp
 133 The
 134 .Va tfb_tcp_block_name
 135 field identifies the unique name of the TCP stack, and should be no longer than
 136 TCP_FUNCTION_NAME_LEN_MAX-1 characters in length.
 137 .Pp
 138 The
 139 .Va tfb_tcp_output ,
 140 .Va tfb_tcp_do_segment ,
 141 and
 142 .Va tfb_tcp_ctloutput
 143 fields are pointers to functions that perform the equivalent actions
 144 as the default
 145 .Fn tcp_output ,
 146 .Fn tcp_do_segment ,
 147 and
 148 .Fn tcp_default_ctloutput
 149 functions, respectively.
 150 Each of these function pointers must be non-NULL.
 151 .Pp
 152 If a TCP stack needs to initialize data when a socket first selects the TCP
 153 stack (or, when the socket is first opened), it should set a non-NULL
 154 pointer in the
 155 .Va tfb_tcp_fb_init
 156 field.
 157 Likewise, if a TCP stack needs to cleanup data when a socket stops using the
 158 TCP stack (or, when the socket is closed), it should set a non-NULL pointer
 159 in the
 160 .Va tfb_tcp_fb_fini
 161 field.
 162 .Pp
 163 If the
 164 .Va tfb_tcp_fb_fini
 165 argument is non-NULL, the function to which it points is called when the
 166 kernel is destroying the TCP control block or when the socket is transitioning
 167 to use a different TCP stack.
 168 The function is called with arguments of the TCP control block and an integer
 169 flag.
 170 The flag will be zero if the socket is transitioning to use another TCP stack
 171 or one if the TCP control block is being destroyed.
 172 .Pp
 173 If the TCP stack implements additional timers, the TCP stack should set a
 174 non-NULL pointer in the
 175 .Va tfb_tcp_timer_stop_all ,
 176 .Va tfb_tcp_timer_activate ,
 177 .Va tfb_tcp_timer_active ,
 178 and
 179 .Va tfb_tcp_timer_stop
 180 fields.
 181 These fields should all be
 182 .Dv NULL
 183 or should all contain pointers to functions.
 184 The
 185 .Va tfb_tcp_timer_activate ,
 186 .Va tfb_tcp_timer_active ,
 187 and
 188 .Va tfb_tcp_timer_stop
 189 functions will be called when the
 190 .Fn tcp_timer_activate ,
 191 .Fn tcp_timer_active ,
 192 and
 193 .Fn tcp_timer_stop
 194 functions, respectively, are called with a timer type other than the standard
 195 types.
 196 The functions defined by the TCP stack have the same semantics (both for
 197 arguments and return values) as the normal timer functions they supplement.
 198 .Pp
 199 Additionally, a stack may define its own actions to take when the retransmit
 200 timer fires by setting a non-NULL function pointer in the
 201 .Va tfb_tcp_rexmit_tmr
 202 field.
 203 This function is called very early in the process of handling a retransmit
 204 timer.
 205 However, care must be taken to ensure the retransmit timer leaves the
 206 TCP control block in a valid state for the remainder of the retransmit
 207 timer logic.
 208 .Pp
 209 A user may select a new TCP stack before calling
 210 .Xr connect 2
 211 or
 212 .Xr listen 2 .
 213 Optionally, a TCP stack may also allow a user to begin using the TCP stack for
 214 a connection that is in a later state by setting a non-NULL function pointer in
 215 the
 216 .Va tfb_tcp_handoff_ok
 217 field.
 218 If this field is non-NULL and a user attempts to select that TCP stack after
 219 calling
 220 .Xr connect 2
 221 or
 222 .Xr listen 2
 223 for that socket, the kernel will call the function pointed to by the
 224 .Va tfb_tcp_handoff_ok
 225 field.
 226 The function should return 0 if the user is allowed to switch the socket to use
 227 the TCP stack. Otherwise, the function should return an error code, which will
 228 be returned to the user.
 229 If the
 230 .Va tfb_tcp_handoff_ok
 231 field is
 232 .Dv NULL
 233 and a user attempts to select the TCP stack after calling
 234 .Xr connect 2
 235 or
 236 .Xr listen 2
 237 for that socket, the operation will fail and the kernel will return
 238 .Er EINVAL .
 239 .Pp
 240 The
 241 .Va tfb_refcnt
 242 and
 243 .Va tfb_flags
 244 fields are used by the kernel's TCP code and will be initialized when the
 245 TCP stack is registered.
 246 .Ss Requirements for Alternate TCP Stacks
 247 If the TCP stack needs to store data beyond what is stored in the default
 248 TCP control block, the TCP stack can initialize its own per-connection storage.
 249 The
 250 .Va t_fb_ptr
 251 field in the
 252 .Vt "struct tcpcb"
 253 control block structure has been reserved to hold a pointer to this
 254 per-connection storage.
 255 If the TCP stack uses this alternate storage, it should understand that the
 256 value of the
 257 .Va t_fb_ptr
 258 pointer may not be initialized to
 259 .Dv NULL .
 260 Therefore, it should use a
 261 .Va tfb_tcp_fb_init
 262 function to initialize this field.
 263 Additionally, it should use a
 264 .Va tfb_tcp_fb_fini
 265 function to deallocate storage when the socket is closed.
 266 .Pp
 267 It is understood that alternate TCP stacks may keep different sets of data.
 268 However, in order to ensure that data is available to both the user and the
 269 rest of the system in a standardized format, alternate TCP stacks must
 270 update all fields in the TCP control block to the greatest extent practical.
 271 .Sh RETURN VALUES
 272 The
 273 .Fn register_tcp_functions
 274 and
 275 .Fn deregister_tcp_functions
 276 functions return zero on success and non-zero on failure.
 277 In particular, the
 278 .Fn deregister_tcp_functions
 279 will return
 280 .Er EBUSY
 281 until no more connections are using the specified TCP stack.
 282 A module calling
 283 .Fn deregister_tcp_functions
 284 must be prepared to wait until all connections have stopped using the
 285 specified TCP stack.
 286 .Sh ERRORS
 287 The
 288 .Fn register_tcp_functions
 289 function will fail if:
 290 .Bl -tag -width Er
 291 .It Bq Er EINVAL
 292 Any of the members of the
 293 .Fa blk
 294 argument are set incorrectly.
 295 .It Bq Er ENOMEM
 296 The function could not allocate memory for its internal data.
 297 .It Bq Er EALREADY
 298 A function block is already registered with the same name.
 299 .El
 300 The
 301 .Fn deregister_tcp_functions
 302 function will fail if:
 303 .Bl -tag -width Er
 304 .It Bq Er EPERM
 305 The
 306 .Fa blk
 307 argument references the kernel's compiled-in default function block.
 308 .It Bq Er EBUSY
 309 The function block is still in use by one or more sockets, or is defined as
 310 the current default function block.
 311 .It Bq Er ENOENT
 312 The
 313 .Fa blk
 314 argument references a function block that is not currently registered.
 315 .El
 316 .Sh SEE ALSO
 317 .Xr connect 2 ,
 318 .Xr listen 2 ,
 319 .Xr tcp 4 ,
 320 .Xr malloc 9
 321 .Sh HISTORY
 322 This framework first appeared in
 323 .Fx 11.0 .
 324 .Sh AUTHORS
 325 .An -nosplit
 326 The
 327 .Nm
 328 framework was written by
 329 .An Randall Stewart Aq Mt rrs@FreeBSD.org .
 330 .Pp
 331 This manual page was written by
 332 .An Jonathan Looney Aq Mt jtl@FreeBSD.org .