table of contents
TCP_FUNCTIONS(9) | Kernel Developer's Manual | TCP_FUNCTIONS(9) |
NAME¶
tcp_functions
—
SYNOPSIS¶
#include <netinet/tcp.h>
#include <netinet/tcp_var.h>
int
register_tcp_functions
(struct
tcp_function_block *blk,
int wait);
int
deregister_tcp_functions
(struct
tcp_function_block *blk);
DESCRIPTION¶
Thetcp_functions
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.
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 tcp(4) for details on setting the system default stack, or selecting a specific stack for a given connection.)
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".
tcp_functions
modules must call the
register_tcp_functions
() function during
initialization and successfully call the
deregister_tcp_functions
() function prior to
allowing the module to be unloaded.
The register_tcp_functions
() function
requests that the system add a specified function block to the system.
The 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.
The blk argument is a pointer to a struct tcp_function_block, which is explained below (see Function Block Structure). The wait argument is used as the flags argument to malloc(9), and must be set to one of the valid values defined in that man page.
Function Block Structure¶
The blk argument is a pointer to a struct tcp_function_block, which has the following members: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; };
The 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.
The tfb_tcp_output,
tfb_tcp_do_segment, and
tfb_tcp_ctloutput fields are pointers to functions
that perform the equivalent actions as the default
tcp_output
(),
tcp_do_segment
(), and
tcp_default_ctloutput
() functions, respectively.
Each of these function pointers must be non-NULL.
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 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 tfb_tcp_fb_fini field.
If the TCP stack implements additional timers, the TCP stack
should set a non-NULL pointer in the
tfb_tcp_timer_stop_all,
tfb_tcp_timer_activate,
tfb_tcp_timer_active, and
tfb_tcp_timer_stop fields. These fields should all be
NULL
or should all contain pointers to functions.
The tfb_tcp_timer_activate,
tfb_tcp_timer_active, and
tfb_tcp_timer_stop functions will be called when the
tcp_timer_activate
(),
tcp_timer_active
(), and
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.
Additionally, a stack may define its own actions to take when the retransmit timer fires by setting a non-NULL function pointer in the 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.
The tfb_refcnt and tfb_flags fields are used by the kernel's TCP code and will be initialized when the TCP stack is registered.
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 t_fb_ptr field in the 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 t_fb_ptr pointer may not be initialized toNULL
. Therefore, it should
use a tfb_tcp_fb_init function to initialize this field.
Additionally, it should use a tfb_tcp_fb_fini function
to deallocate storage when the socket is closed.
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.
RETURN VALUES¶
Theregister_tcp_functions
() and
deregister_tcp_functions
() functions return zero on
success and non-zero on failure. In particular, the
deregister_tcp_functions
() will return
EBUSY
until no more connections are using the
specified TCP stack. A module calling
deregister_tcp_functions
() must be prepared to wait
until all connections have stopped using the specified TCP stack.
ERRORS¶
Theregister_tcp_functions
() function will fail if:
- [
EINVAL
] - Any of the members of the blk argument are set incorrectly.
- [
ENOMEM
] - The function could not allocate memory for its internal data.
- [
EALREADY
] - A function block is already registered with the same name.
deregister_tcp_functions
() function will fail if:
SEE ALSO¶
malloc(9), tcp(4)HISTORY¶
This framework first appeared in FreeBSD 11.0.AUTHORS¶
Thetcp_functions
framework was written by
Randall Stewart
<rrs@FreeBSD.org>.
This manual page was written by Jonathan Looney <jtl@FreeBSD.org>.
June 28, 2016 | Linux 4.9.0-9-amd64 |