286 lines
9.1 KiB
Groff
286 lines
9.1 KiB
Groff
|
.\"
|
||
|
|
.\" Copyright (c) 2016 Jonathan Looney <jtl@FreeBSD.org>
|
||
|
|
.\" All rights reserved.
|
||
|
|
.\"
|
||
|
|
.\" Redistribution and use in source and binary forms, with or without
|
||
|
|
.\" modification, are permitted provided that the following conditions
|
||
|
|
.\" are met:
|
||
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
||
|
|
.\" notice, this list of conditions and the following disclaimer.
|
||
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
||
|
|
.\" documentation and/or other materials provided with the distribution.
|
||
|
|
.\"
|
||
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
||
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR
|
||
|
|
.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
||
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
||
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
||
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
||
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
||
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
||
|
|
.\" SUCH DAMAGE.
|
||
|
|
.\"
|
||
|
|
.\" $FreeBSD$
|
||
|
|
.\"
|
||
|
|
.Dd June 28, 2016
|
||
|
|
.Dt TCP_FUNCTIONS 9
|
||
|
|
.Os
|
||
|
|
.Sh NAME
|
||
|
|
.Nm tcp_functions
|
||
|
|
.Nd Alternate TCP Stack Framework
|
||
|
|
.Sh SYNOPSIS
|
||
|
|
.In netinet/tcp.h
|
||
|
|
.In netinet/tcp_var.h
|
||
|
|
.Ft int
|
||
|
|
.Fn register_tcp_functions "struct tcp_function_block *blk" "int wait"
|
||
|
|
.Ft int
|
||
|
|
.Fn deregister_tcp_functions "struct tcp_function_block *blk"
|
||
|
|
.Sh DESCRIPTION
|
||
|
|
The
|
||
|
|
.Nm
|
||
|
|
framework allows a kernel developer to implement alternate TCP stacks.
|
||
|
|
The alternate stacks can be compiled in the kernel or can be implemented in
|
||
|
|
loadable kernel modules.
|
||
|
|
This functionality is intended to encourage experimentation with the TCP stack
|
||
|
|
and to allow alternate behaviors to be deployed for different TCP connections
|
||
|
|
on a single system.
|
||
|
|
.Pp
|
||
|
|
A system administrator can set a system default stack.
|
||
|
|
By default, all TCP connections will use the system default stack.
|
||
|
|
Additionally, users can specify a particular stack to use on a per-connection
|
||
|
|
basis.
|
||
|
|
(See
|
||
|
|
.Xr tcp 4
|
||
|
|
for details on setting the system default stack, or selecting a specific stack
|
||
|
|
for a given connection.)
|
||
|
|
.Pp
|
||
|
|
This man page treats "TCP stacks" as synonymous with "function blocks".
|
||
|
|
This is intentional.
|
||
|
|
A "TCP stack" is a collection of functions that implement a set of behavior.
|
||
|
|
Therefore, an alternate "function block" defines an alternate "TCP stack".
|
||
|
|
.Pp
|
||
|
|
.Nm
|
||
|
|
modules must call the
|
||
|
|
.Fn register_tcp_functions
|
||
|
|
function during initialization and successfully call the
|
||
|
|
.Fn deregister_tcp_functions
|
||
|
|
function prior to allowing the module to be unloaded.
|
||
|
|
.Pp
|
||
|
|
The
|
||
|
|
.Fn register_tcp_functions
|
||
|
|
function requests that the system add a specified function block to the system.
|
||
|
|
.Pp
|
||
|
|
The
|
||
|
|
.Fn deregister_tcp_functions
|
||
|
|
function requests that the system remove a specified function block from the
|
||
|
|
system.
|
||
|
|
If the call fails because sockets are still using the specified function block,
|
||
|
|
the system will mark the function block as being in the process of being
|
||
|
|
removed.
|
||
|
|
This will prevent additional sockets from using the specified function block.
|
||
|
|
However, it will not impact sockets that are already using the function block.
|
||
|
|
.Pp
|
||
|
|
The
|
||
|
|
.Fa blk
|
||
|
|
argument is a pointer to a
|
||
|
|
.Vt "struct tcp_function_block" ,
|
||
|
|
which is explained below (see
|
||
|
|
.Sx Function Block Structure ) .
|
||
|
|
The
|
||
|
|
.Fa wait
|
||
|
|
argument is used as the
|
||
|
|
.Fa flags
|
||
|
|
argument to
|
||
|
|
.Xr malloc 9 ,
|
||
|
|
and must be set to one of the valid values defined in that man page.
|
||
|
|
.Ss Function Block Structure
|
||
|
|
The
|
||
|
|
.Fa blk argument is a pointer to a
|
||
|
|
.Vt "struct tcp_function_block" ,
|
||
|
|
which has the following members:
|
||
|
|
.Bd -literal -offset indent
|
||
|
|
struct tcp_function_block {
|
||
|
|
char tfb_tcp_block_name[TCP_FUNCTION_NAME_LEN_MAX];
|
||
|
|
int (*tfb_tcp_output)(struct tcpcb *);
|
||
|
|
void (*tfb_tcp_do_segment)(struct mbuf *, struct tcphdr *,
|
||
|
|
struct socket *, struct tcpcb *,
|
||
|
|
int, int, uint8_t,
|
||
|
|
int);
|
||
|
|
int (*tfb_tcp_ctloutput)(struct socket *so,
|
||
|
|
struct sockopt *sopt,
|
||
|
|
struct inpcb *inp, struct tcpcb *tp);
|
||
|
|
/* Optional memory allocation/free routine */
|
||
|
|
void (*tfb_tcp_fb_init)(struct tcpcb *);
|
||
|
|
void (*tfb_tcp_fb_fini)(struct tcpcb *);
|
||
|
|
/* Optional timers, must define all if you define one */
|
||
|
|
int (*tfb_tcp_timer_stop_all)(struct tcpcb *);
|
||
|
|
void (*tfb_tcp_timer_activate)(struct tcpcb *,
|
||
|
|
uint32_t, u_int);
|
||
|
|
int (*tfb_tcp_timer_active)(struct tcpcb *, uint32_t);
|
||
|
|
void (*tfb_tcp_timer_stop)(struct tcpcb *, uint32_t);
|
||
|
|
void (*tfb_tcp_rexmit_tmr)(struct tcpcb *);
|
||
|
|
volatile uint32_t tfb_refcnt;
|
||
|
|
uint32_t tfb_flags;
|
||
|
|
};
|
||
|
|
.Ed
|
||
|
|
.Pp
|
||
|
|
The
|
||
|
|
.Va tfb_tcp_block_name
|
||
|
|
field identifies the unique name of the TCP stack, and should be no longer than
|
||
|
|
TCP_FUNCTION_NAME_LEN_MAX-1 characters in length.
|
||
|
|
.Pp
|
||
|
|
The
|
||
|
|
.Va tfb_tcp_output ,
|
||
|
|
.Va tfb_tcp_do_segment ,
|
||
|
|
and
|
||
|
|
.Va tfb_tcp_ctloutput
|
||
|
|
fields are pointers to functions that perform the equivalent actions
|
||
|
|
as the default
|
||
|
|
.Fn tcp_output ,
|
||
|
|
.Fn tcp_do_segment ,
|
||
|
|
and
|
||
|
|
.Fn tcp_default_ctloutput
|
||
|
|
functions, respectively.
|
||
|
|
Each of these function pointers must be non-NULL.
|
||
|
|
.Pp
|
||
|
|
If a TCP stack needs to initialize data when a socket first selects the TCP
|
||
|
|
stack (or, when the socket is first opened), it should set a non-NULL
|
||
|
|
pointer in the
|
||
|
|
.Va tfb_tcp_fb_init
|
||
|
|
field.
|
||
|
|
Likewise, if a TCP stack needs to cleanup data when a socket stops using the
|
||
|
|
TCP stack (or, when the socket is closed), it should set a non-NULL pointer
|
||
|
|
in the
|
||
|
|
.Va tfb_tcp_fb_fini
|
||
|
|
field.
|
||
|
|
.Pp
|
||
|
|
If the TCP stack implements additional timers, the TCP stack should set a
|
||
|
|
non-NULL pointer in the
|
||
|
|
.Va tfb_tcp_timer_stop_all ,
|
||
|
|
.Va tfb_tcp_timer_activate ,
|
||
|
|
.Va tfb_tcp_timer_active ,
|
||
|
|
and
|
||
|
|
.Va tfb_tcp_timer_stop
|
||
|
|
fields.
|
||
|
|
These fields should all be
|
||
|
|
.Dv NULL
|
||
|
|
or should all contain pointers to functions.
|
||
|
|
The
|
||
|
|
.Va tfb_tcp_timer_activate ,
|
||
|
|
.Va tfb_tcp_timer_active ,
|
||
|
|
and
|
||
|
|
.Va tfb_tcp_timer_stop
|
||
|
|
functions will be called when the
|
||
|
|
.Fn tcp_timer_activate ,
|
||
|
|
.Fn tcp_timer_active ,
|
||
|
|
and
|
||
|
|
.Fn tcp_timer_stop
|
||
|
|
functions, respectively, are called with a timer type other than the standard
|
||
|
|
types.
|
||
|
|
The functions defined by the TCP stack have the same semantics (both for
|
||
|
|
arguments and return values) as the normal timer functions they supplement.
|
||
|
|
.Pp
|
||
|
|
Additionally, a stack may define its own actions to take when the retransmit
|
||
|
|
timer fires by setting a non-NULL function pointer in the
|
||
|
|
.Va tfb_tcp_rexmit_tmr
|
||
|
|
field.
|
||
|
|
This function is called very early in the process of handling a retransmit
|
||
|
|
timer.
|
||
|
|
However, care must be taken to ensure the retransmit timer leaves the
|
||
|
|
TCP control block in a valid state for the remainder of the retransmit
|
||
|
|
timer logic.
|
||
|
|
.Pp
|
||
|
|
The
|
||
|
|
.Va tfb_refcnt
|
||
|
|
and
|
||
|
|
.Va tfb_flags
|
||
|
|
fields are used by the kernel's TCP code and will be initialized when the
|
||
|
|
TCP stack is registered.
|
||
|
|
.Ss Requirements for Alternate TCP Stacks
|
||
|
|
If the TCP stack needs to store data beyond what is stored in the default
|
||
|
|
TCP control block, the TCP stack can initialize its own per-connection storage.
|
||
|
|
The
|
||
|
|
.Va t_fb_ptr
|
||
|
|
field in the
|
||
|
|
.Vt "struct tcpcb"
|
||
|
|
control block structure has been reserved to hold a pointer to this
|
||
|
|
per-connection storage.
|
||
|
|
If the TCP stack uses this alternate storage, it should understand that the
|
||
|
|
value of the
|
||
|
|
.Va t_fb_ptr
|
||
|
|
pointer may not be initialized to
|
||
|
|
.Dv NULL .
|
||
|
|
Therefore, it should use a
|
||
|
|
.Va tfb_tcp_fb_init
|
||
|
|
function to initialize this field.
|
||
|
|
Additionally, it should use a
|
||
|
|
.Va tfb_tcp_fb_fini
|
||
|
|
function to deallocate storage when the socket is closed.
|
||
|
|
.Pp
|
||
|
|
It is understood that alternate TCP stacks may keep different sets of data.
|
||
|
|
However, in order to ensure that data is available to both the user and the
|
||
|
|
rest of the system in a standardized format, alternate TCP stacks must
|
||
|
|
update all fields in the TCP control block to the greatest extent practical.
|
||
|
|
.Sh RETURN VALUES
|
||
|
|
The
|
||
|
|
.Fn register_tcp_functions
|
||
|
|
and
|
||
|
|
.Fn deregister_tcp_functions
|
||
|
|
functions return zero on success and non-zero on failure.
|
||
|
|
In particular, the
|
||
|
|
.Fn deregister_tcp_functions
|
||
|
|
will return
|
||
|
|
.Er EBUSY
|
||
|
|
until no more connections are using the specified TCP stack.
|
||
|
|
A module calling
|
||
|
|
.Fn deregister_tcp_functions
|
||
|
|
must be prepared to wait until all connections have stopped using the
|
||
|
|
specified TCP stack.
|
||
|
|
.Sh ERRORS
|
||
|
|
The
|
||
|
|
.Fn register_tcp_functions
|
||
|
|
function will fail if:
|
||
|
|
.Bl -tag -width Er
|
||
|
|
.It Bq Er EINVAL
|
||
|
|
Any of the members of the
|
||
|
|
.Fa blk
|
||
|
|
argument are set incorrectly.
|
||
|
|
.It Bq Er ENOMEM
|
||
|
|
The function could not allocate memory for its internal data.
|
||
|
|
.It Bq Er EALREADY
|
||
|
|
A function block is already registered with the same name.
|
||
|
|
.El
|
||
|
|
The
|
||
|
|
.Fn deregister_tcp_functions
|
||
|
|
function will fail if:
|
||
|
|
.Bl -tag -width Er
|
||
|
|
.It Bq Er EPERM
|
||
|
|
The
|
||
|
|
.Fa blk
|
||
|
|
argument references the kernel's compiled-in default function block.
|
||
|
|
.It Bq Er EBUSY
|
||
|
|
The function block is still in use by one or more sockets, or is defined as
|
||
|
|
the current default function block.
|
||
|
|
.It Bq Er ENOENT
|
||
|
|
The
|
||
|
|
.Fa blk
|
||
|
|
argument references a function block that is not currently registered.
|
||
|
|
.Sh SEE ALSO
|
||
|
|
.Xr malloc 9 ,
|
||
|
|
.Xr tcp 4
|
||
|
|
.Sh HISTORY
|
||
|
|
This framework first appeared in
|
||
|
|
.Fx 11.0 .
|
||
|
|
.Sh AUTHORS
|
||
|
|
.An -nosplit
|
||
|
|
The
|
||
|
|
.Nm
|
||
|
|
framework was written by
|
||
|
|
.An Randall Stewart Aq Mt rrs@FreeBSD.org .
|
||
|
|
.Pp
|
||
|
|
This manual page was written by
|
||
|
|
.An Jonathan Looney Aq Mt jtl@FreeBSD.org .
|