freebsd-src/share/man/man9/domain.9

.\"
.\" Copyright (C) 2001 Chad David <davidc@acns.ab.ca>. All rights reserved.
.\" Copyright (C) 2022 Gleb Smirnoff <glebius@FreeBSD.org>
.\"
.\" 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(s), this list of conditions and the following disclaimer as
.\"    the first lines of this file unmodified other than the possible
.\"    addition of one or more copyright notices.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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.
.\"
.Dd September 14, 2022
.Dt DOMAIN 9
.Os
.Sh NAME
.Nm domain ,
.Nm protosw
.Nd "programming interface for kernel socket implementation"
.Sh SYNOPSIS
.In sys/param.h
.In sys/kernel.h
.In sys/protosw.h
.In sys/domain.h
.Ft void
.Fn domain_add "struct domain *dom"
.Ft void
.Fn domain_remove "struct domain *dom"
.Ft void
.Fn DOMAIN_SET "domain"
.Ft int
.Fn protosw_register "struct domain *dom" "struct protosw *pr"
.Ft int
.Fn protosw_unregister "struct protosw *pr"
.Sh DESCRIPTION
The
.Nm
subsystem allows implementation of communication protocols that are exposed to
the userland via the
.Xr socket 2
API.
When an application performs a
.Fn socket "domain" "type" "protocol"
syscall, the kernel searches for a
.Nm
matching the
.Ar domain
argument, then within this domain, searches for a protocol
matching
.Ar type .
If the third argument,
.Ar protocol ,
is not
.Dv 0 ,
that value must also match.
The structure found must implement certain methods, so that
.Xr socket 2
API works for this particular kind of a socket.
.Pp
A minimal
.Nm
structure implementing a domain shall be initialized with sparse C99
initializer and has public fields as follows:
.Bd -literal
struct domain {
    /*
     * Mandatory fields.
     */
    int	dom_family;	/* PF_xxx, first argument of socket(2) */
    char	*dom_name;	/* text name of the domain */
    u_int	dom_nprotosw;	/* length of dom_protosw[] */
    /*
     * Following methods are optional.
     */
    int	(*dom_probe)(void);			/* check for support */
    struct rib_head *(*dom_rtattach)(uint32_t);	/* init route table */
    void (*dom_rtdetach)(struct rib_head *);	/* clean up table */
    void *(*dom_ifattach)(struct ifnet *);	/* interface attach */
    void (*dom_ifdetach)(struct ifnet *, void *);/* & detach callbacks */
    int	(*dom_ifmtu)(struct ifnet *);		/* mtu change */
    /*
     * Mandatory variable size array of pointers to protosw structs.
     */
    struct  protosw *dom_protosw[];
};
.Ed
.Pp
Each domain contains the
.Va dom_protosw
array of protocol switch structures
.Pq Vt "struct protosw *" ,
one for each socket type supported.
The array may have
.Dv NULL
spacers for loadable protocols.
Sparse C99 initializers shall be used to initialize
.Nm protosw
structures.
The structure has mandatory field
.Va pr_type
and mandatory
.Va pr_attach
method.
The rest of the methods are optional, but a meaningful protocol should
implement some.
.Bd -literal
struct protosw {
    short	pr_type;	/* second argument of socket(2) */
    short	pr_protocol;	/* third argument of socket(2) or 0 */
    short	pr_flags;	/* see protosw.h */
    pr_soreceive_t  *pr_soreceive;  /* recv(2) */
    pr_rcvd_t       *pr_rcvd;       /* soreceive_generic() if PR_WANTRCV */
    pr_sosend_t     *pr_sosend;     /* send(2) */
    pr_send_t       *pr_send;       /* send(2) via sosend_generic() */
    pr_ready_t      *pr_ready;      /* sendfile/ktls readyness */
    pr_sopoll_t     *pr_sopoll;     /* poll(2) */
    pr_attach_t     *pr_attach;     /* creation: socreate(), sonewconn() */
    pr_detach_t     *pr_detach;     /* destruction: sofree() */
    pr_connect_t    *pr_connect;    /* connect(2) */
    pr_disconnect_t *pr_disconnect; /* sodisconnect() */
    pr_close_t      *pr_close;      /* close(2) */
    pr_shutdown_t   *pr_shutdown;   /* shutdown(2) */
    pr_abort_t      *pr_abort;      /* abrupt tear down: soabort() */
    pr_aio_queue_t  *pr_aio_queue;  /* aio(9) */
    pr_bind_t       *pr_bind;       /* bind(2) */
    pr_bindat_t     *pr_bindat;     /* bindat(2) */
    pr_listen_t     *pr_listen;     /* listen(2) */
    pr_accept_t     *pr_accept;     /* accept(2) */
    pr_connectat_t  *pr_connectat;  /* connectat(2) */
    pr_connect2_t   *pr_connect2;   /* socketpair(2) */
    pr_control_t    *pr_control;    /* ioctl(2) */
    pr_rcvoob_t     *pr_rcvoob;     /* soreceive_rcvoob() */
    pr_ctloutput_t  *pr_ctloutput;  /* control output (from above) */
    pr_peeraddr_t   *pr_peeraddr;   /* getpeername(2) */
    pr_sockaddr_t   *pr_sockaddr;   /* getsockname(2) */
    pr_sense_t      *pr_sense;      /* stat(2) */
};
.Ed
.Pp
The following functions handle the registration of new domains and protocols.
.Pp
.Fn domain_add
adds a new protocol domain to the system.
In most cases
.Fn domain_add
is not called directly, instead
.Fn DOMAIN_SET
is used, which is a wrapper around
.Fn SYSINIT
macro.
If the new domain has defined a
.Va dom_probe
routine, it is called first in
.Fn domain_add
to determine if the domain should be supported on the current system.
If the probe routine returns a non-0 value, then the domain will not be added.
Once a domain is added it cannot be completely unloaded.
This is because there is
no reference counting system in place to determine if there are any
active references from sockets within that domain.
However, the exprimental
.Fn domain_remove
exists, and unloadable domains may be supported in the future.
.Pp
.Fn protosw_register
dynamically adds a protocol to a domain, if the latter
has an empty slot in its
.Va dom_protosw .
Dynamically added protocol can later be unloaded with
.Fn protosw_unregister .
.Ed
.Sh RETURN VALUES
The
.Fn domain_add
never fails, but it may not add a domain if its
.Va dom_probe
fails.
.Pp
The
.Fn protosw_register
function may fail if:
.Bl -tag -width Er
.It Bq Er EEXIST
A protocol with the same value of
.Va pr_type
and
.Va pr_protocol
already exists in the domain.
.It Bq Er ENOMEM
The domain doesn't have any NULL slots in its
.Va dom_protosw .
.El
.Sh SEE ALSO
.Xr socket 2 ,
.Xr SYSINIT 9
.Sh HISTORY
The
.Nm
subsystem first appeared in
.Bx 4.3
as the part of the very first
.Xr socket 2
API implementation.
.Pp
The
.Nm
subsystem and this manual page were significantly rewritten in
.Fx 14 .
.Sh AUTHORS
This manual page was written by
.An Chad David Aq Mt davidc@acns.ab.ca
and
.An Gleb Smirnoff Aq Mt glebius@FreeBSD.org .