From nobody Wed Sep 14 21:13:01 2022 X-Original-To: dev-commits-src-main@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4MSY2k0V8hz4cB7w; Wed, 14 Sep 2022 21:13:02 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4MSY2j70yDz3jss; Wed, 14 Sep 2022 21:13:01 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1663189982; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=ba1HctHU2zVCZlLNp82HmG8MktBmOkH0yU1BvmO66L4=; b=pdS75Jcggu4Q5I/tRycQ4BG3Ns/DgOTn6YQAIRIYWYluht3zjhpDXFqnkDeTUD6XnyT6tK Nqa+X1yzTSJX5yHPXtcw7CBrZcuEHUwWWnoWwvE/d4YjkysPgQ2Ml8RjqCc6gkDtwvuCTT fh7SY/USQnP1qcLWmBcB8B6aE120lCtOsPzafd404Gyd7bNBlvbCkhkVqrQhEhDI/CKXcC ywBAKqwsuXYPqtL4gklka6v1RRhwdZC11HlsgkiMu3VFEK097WCGeaJg8Xs4f50gBVkaPv dhEjPpwGL2BAzRU6UHuLD5Ru5q6QvH2CxY7Xus+npWieAHMlvW08Lcm/Q++dQA== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4MSY2j5kLSznpc; Wed, 14 Sep 2022 21:13:01 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 28ELD1YP007792; Wed, 14 Sep 2022 21:13:01 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 28ELD12Z007791; Wed, 14 Sep 2022 21:13:01 GMT (envelope-from git) Date: Wed, 14 Sep 2022 21:13:01 GMT Message-Id: <202209142113.28ELD12Z007791@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Gleb Smirnoff Subject: git: b3ee318b79d5 - main - domains: rewrite documentation to describe present state List-Id: Commit messages for the main branch of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-main List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-dev-commits-src-main@freebsd.org X-BeenThere: dev-commits-src-main@freebsd.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: glebius X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: b3ee318b79d54a59190d35b8c76a63a8fb81b903 Auto-Submitted: auto-generated ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1663189982; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=ba1HctHU2zVCZlLNp82HmG8MktBmOkH0yU1BvmO66L4=; b=G1LSdMfMjh6I7cq5O7hfvclGxu5rEAzZGQrHsOpn791MjmhMo6L4LNH9N3IKmXMHPe646v L/IquhL3VurbciQGVsHBmowELFG8kWifY/qtRAYqg5VD6Lr7EjbnTtBmQnBb/L94gpj5Gn rOhG5jABIjWtnggTQ8LEW5AXg/j1FkyT6qR1KggWYia5lo6oxOy7SPp/BIWGw4XrHTo4sr QKb6vk7+xH0v69WELIjBg+v4At6Ab/J69lFTrxvk6Zxg85Y7vZJQ7v8DAs1BAtrWb73OT0 w3X1QxewvBCh3WWr6RWLuZK0F2u1kXzmj3p85mk/kMHJxL3Qu2hS26RVt3VMZg== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1663189982; a=rsa-sha256; cv=none; b=qzynGVmGjvvjt8/8LqiLN6q1m3+X0ecu/OS2iqpa2F1hcg/vWSpvM8yNng5hmTVXTCXSOj +z14Z+bWetSYNHo1ISqMmpElOxCGK9HxwUqgfIC2tMBJJ8Qb53Zvka6nE427vCFBppTM7Z 6otuwu3Fk6TVnpTyPopNTXQyrp1sXPusoqN9EHcEEQXrf6QYG2otykTtNGynUsvLAbMjeF oxMf5epZc9/n6gfOTrxwjQAsBq+MTobfmVbjP6ta8u4KNPJcLcQxP4CWRG3/gpEnLPwA70 R4KSuAqA381oJsEf02YETO6Y/7ql7uLhbVpFhdeF7I0UewdAirhYSMkbjLS1Pw== ARC-Authentication-Results: i=1; mx1.freebsd.org; none X-ThisMailContainsUnwantedMimeParts: N The branch main has been updated by glebius: URL: https://cgit.FreeBSD.org/src/commit/?id=b3ee318b79d54a59190d35b8c76a63a8fb81b903 commit b3ee318b79d54a59190d35b8c76a63a8fb81b903 Author: Gleb Smirnoff AuthorDate: 2022-09-14 21:11:40 +0000 Commit: Gleb Smirnoff CommitDate: 2022-09-14 21:12:24 +0000 domains: rewrite documentation to describe present state Reviewed by: debdrup, pauamma Differential revision: https://reviews.freebsd.org/D36513 --- ObsoleteFiles.inc | 7 + share/man/man9/Makefile | 9 +- share/man/man9/domain.9 | 330 +++++++++++++++++++++++------------------------- 3 files changed, 167 insertions(+), 179 deletions(-) diff --git a/ObsoleteFiles.inc b/ObsoleteFiles.inc index 68d832e8a507..42ab6e54c44d 100644 --- a/ObsoleteFiles.inc +++ b/ObsoleteFiles.inc @@ -52,6 +52,13 @@ # xargs -n1 | sort | uniq -d; # done +# 20220814: domain(9) updated +OLD_FILES+=usr/share/man/man9/domain_init.9.gz +OLD_FILES+=usr/share/man/man9/pfctlinput.9.gz +OLD_FILES+=usr/share/man/man9/pffinddomain.9.gz +OLD_FILES+=usr/share/man/man9/pffindproto.9.gz +OLD_FILES+=usr/share/man/man9/pffindtype.9.gz + # 20220825: awk tests moved to subdirs OLD_FILES+=usr/tests/usr.bin/awk/awk_test OLD_FILES+=usr/tests/usr.bin/awk/d_assign_NF.awk diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index 69f8817b5245..8ac34b2a83e4 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -1022,13 +1022,10 @@ MLINKS+=dnv.9 dnvlist.9 \ dnv.9 dnvlist_take_number.9 \ dnv.9 dnvlist_take_nvlist.9 \ dnv.9 dnvlist_take_string.9 -MLINKS+=domain.9 DOMAIN_SET.9 \ +MLINKS+=domain.9 protosw.9 \ domain.9 domain_add.9 \ - domain.9 domain_init.9 \ - domain.9 pfctlinput.9 \ - domain.9 pffinddomain.9 \ - domain.9 pffindproto.9 \ - domain.9 pffindtype.9 + domain.9 protosw_register.9 \ + domain.9 protosw_unregister.9 \ MLINKS+=drbr.9 drbr_free.9 \ drbr.9 drbr_enqueue.9 \ drbr.9 drbr_dequeue.9 \ diff --git a/share/man/man9/domain.9 b/share/man/man9/domain.9 index 2d42e0b8cb40..5912a7d5e717 100644 --- a/share/man/man9/domain.9 +++ b/share/man/man9/domain.9 @@ -1,5 +1,6 @@ .\" .\" Copyright (C) 2001 Chad David . All rights reserved. +.\" Copyright (C) 2022 Gleb Smirnoff .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions @@ -26,221 +27,204 @@ .\" .\" $FreeBSD$ .\" -.Dd January 3, 2022 +.Dd September 14, 2022 .Dt DOMAIN 9 .Os .Sh NAME -.Nm domain_add , -.Nm domain_init , -.Nm pfctlinput , -.Nm pffinddomain , -.Nm pffindproto , -.Nm pffindtype , -.Nm DOMAIN_SET -.Nd "network domain management" +.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 "void *data" +.Fn domain_add "struct domain *dom" .Ft void -.Fn domain_init "void *data" +.Fn domain_remove "struct domain *dom" .Ft void -.Fn pfctlinput "int cmd" "struct sockaddr *sa" -.Ft struct domain * -.Fn pffinddomain "int family" -.Ft struct protosw * -.Fn pffindproto "int family" "int protocol" "int type" -.Ft struct protosw * -.Fn pffindtype "int family" "int type" -.Ft void -.Fn DOMAIN_SET "name" +.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 -Network protocols installed in the system are maintained within what -are called domains -(for example the -.Va inetdomain -and -.Va localdomain ) . +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 { - int dom_family; /* AF_xxx */ - char *dom_name; - int dom_flags; - int (*dom_probe)(void); /* check for support (optional) */ - int (*dom_externalize) /* externalize access rights */ - (struct mbuf *, struct mbuf **); - void (*dom_dispose) /* dispose of internalized rights */ - (struct mbuf *); - struct protosw *dom_protosw, *dom_protoswNPROTOSW; - struct domain *dom_next; - int (*dom_rtattach) /* initialize routing table */ - (void **, int); - int (*dom_rtdetach) /* clean up routing table */ - (void **, int); - void *(*dom_ifattach)(struct ifnet *); - void (*dom_ifdetach)(struct ifnet *, void *); - int (*dom_ifmtu)(struct ifnet *); - /* af-dependent data on ifnet */ + /* + * 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 an array of protocol switch structures +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; /* socket type used for */ - struct domain *pr_domain; /* domain protocol a member of */ - short pr_protocol; /* protocol number */ - short pr_flags; /* see below */ -/* protocol-protocol hooks */ - pr_input_t *pr_input; /* input to protocol (from below) */ - pr_output_t *pr_output; /* output to protocol (from above) */ - pr_ctlinput_t *pr_ctlinput; /* control input (from below) */ - pr_ctloutput_t *pr_ctloutput; /* control output (from above) */ -/* utility hooks */ - pr_fasttimo_t *pr_fasttimo; /* fast timeout (200ms) */ - pr_slowtimo_t *pr_slowtimo; /* slow timeout (500ms) */ - pr_drain_t *pr_drain; /* flush any excess space possible */ - - struct pr_usrreqs *pr_usrreqs; /* user-protocol hook */ + 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 a new domain, -lookups of specific protocols and protocol types within those domains, -and handle control messages from the system. -.Pp -.Fn pfctlinput -is called by the system whenever an event occurs that could affect every -domain. -Examples of those types of events are routing table changes, interface -shutdowns or certain -.Tn ICMP -message types. -When called, -.Fn pfctlinput -calls the protocol specific -.Fn pr_ctlinput -function for each protocol in that has defined one, in every domain. +The following functions handle the registration of new domains and protocols. .Pp .Fn domain_add adds a new protocol domain to the system. -The argument -.Fa data -is cast directly to -.Vt "struct domain *" -within the function, but is declared -.Vt "void *" -in order to prevent compiler warnings when new domains are registered with -.Fn SYSINIT . In most cases .Fn domain_add is not called directly, instead .Fn DOMAIN_SET -is used. -.Pp -If the new domain has defined a probe routine, it is called first in +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 -marked as supported. -Unsupported domains do not proceed with the initialization process and are not -discoverable by -.Fn pffinddomain , -.Fn pffindtype , -or -.Fn pffindproto . -.Pp -.Fn domain_init -is called after -.Fn domain_add -during boot and for each -.Xr vnet 9 . -If the new domain has defined an initialization routine, it is called during -.Fn domain_init ; -as well, each of the protocols within the domain that have defined an -initialization routine will have theirs called. -Note that domain initialization cannot fail at this time. -.Pp +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 pffinddomain -finds a domain by family. -If the domain cannot be found, -.Dv NULL -is returned. -.Pp -.Fn pffindtype -and -.Fn pffindproto -look up a protocol by its number or by its type. -In most cases, if the protocol or type cannot be found, -.Dv NULL -is returned, but -.Fn pffindproto -may return the default if the requested type is -.Dv SOCK_RAW , -a protocol switch type of -.Dv SOCK_RAW -is found, and the domain has a default raw protocol. -.Pp -Both functions are called by -.Fn socreate -in order to resolve the protocol for the socket currently being created. -.Pp -.Fn DOMAIN_SET -is a macro that simplifies the registration of a domain via -.Fn SYSINIT . -The code resulting from the macro expects there to be a domain structure -named -.Dq Fa name Ns Li domain -where -.Fa name -is the argument to -.Fn DOMAIN_SET : -.Bd -literal -struct domain localdomain = -{ AF_LOCAL, "local", unp_init, unp_externalize, unp_dispose, - localsw, &localsw[sizeof(localsw)/sizeof(localsw[0])] }; - -DOMAIN_SET(local); +.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 -Both -.Fn pffindtype +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 -.Fn pffindproto -return a -.Vt "struct protosw *" -for the protocol requested. -If the protocol or socket type is not found, -.Dv NULL -is returned. -In the case of -.Fn pffindproto , -the default protocol may be returned for -.Dv SOCK_RAW -types if the domain has a default raw protocol. +.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 socket 2 , +.Xr SYSINIT 9 .Sh HISTORY -The functions -.Fn domain_add , -.Fn pfctlinput , -.Fn pffinddomain , -.Fn pffindproto , -.Fn pffindtype -and -.Fn DOMAIN_SET -first appeared in -.Fx 4.4 . +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 . +.An Chad David Aq Mt davidc@acns.ab.ca +and +.An Gleb Smirnoff Aq Mt glebius@FreeBSD.org .