diff options
Diffstat (limited to 'share/man')
86 files changed, 3104 insertions, 1528 deletions
diff --git a/share/man/man3/CMSG_DATA.3 b/share/man/man3/CMSG_DATA.3 index 92c5b9736da3..efdff7abae60 100644 --- a/share/man/man3/CMSG_DATA.3 +++ b/share/man/man3/CMSG_DATA.3 @@ -165,7 +165,7 @@ main() close(hellofd[1]); if (read(hellofd[0], buf, HELLOLEN) == -1) - err(EX_IOERR, "faild to receive 'hello'"); + err(EX_IOERR, "failed to receive 'hello'"); printf("parent: received '%s'\\n", buf); break; } diff --git a/share/man/man3/Makefile b/share/man/man3/Makefile index fa4f751ce553..872aec1e83ab 100644 --- a/share/man/man3/Makefile +++ b/share/man/man3/Makefile @@ -320,6 +320,7 @@ MLINKS+= timeradd.3 timerclear.3 \ timeradd.3 timespecisset.3 \ timeradd.3 timespeccmp.3 MLINKS+= tree.3 RB_AUGMENT.3 \ + tree.3 RB_AUGMENT_CHECK.3 \ tree.3 RB_EMPTY.3 \ tree.3 RB_ENTRY.3 \ tree.3 RB_FIND.3 \ diff --git a/share/man/man3/intro.3 b/share/man/man3/intro.3 index d6dff3ab3782..aeb546ef4cad 100644 --- a/share/man/man3/intro.3 +++ b/share/man/man3/intro.3 @@ -28,7 +28,7 @@ .\" @(#)intro.3 8.1 (Berkeley) 6/5/93 .\" $FreeBSD$ .\" -.Dd December 18, 2021 +.Dd November 7, 2022 .Dt INTRO 3 .Os .Sh NAME @@ -231,6 +231,13 @@ See The POSIX threads library. See .Xr pthread 3 . +.It Em libstdthreads +.Pq Fl l Ns Ar stdthreads +The ISO C11 standard +.In threads.h +library. +See +.Xr thrd_create 3 . .It Em libsysdecode .Pq Fl l Ns Ar sysdecode The system argument decoding library. diff --git a/share/man/man3/pthread_schedparam.3 b/share/man/man3/pthread_schedparam.3 index 9d8b98a89d96..27ccb0de1ba9 100644 --- a/share/man/man3/pthread_schedparam.3 +++ b/share/man/man3/pthread_schedparam.3 @@ -27,7 +27,7 @@ .\" .\" $FreeBSD$ .\" -.Dd August 17, 2018 +.Dd October 17, 2022 .Dt PTHREAD_SCHEDPARAM 3 .Os .Sh NAME @@ -75,6 +75,8 @@ Invalid value for .Fa policy . .It Bq Er ENOTSUP Invalid value for scheduling parameters. +.It Bq Er EPERM +The calling thread does not have sufficient privilege to perform the operation. .It Bq Er ESRCH Non-existent thread .Fa thread . diff --git a/share/man/man3/tree.3 b/share/man/man3/tree.3 index 7e3727b2c365..0c329741848f 100644 --- a/share/man/man3/tree.3 +++ b/share/man/man3/tree.3 @@ -97,9 +97,12 @@ .Nm RB_FOREACH_REVERSE_SAFE , .Nm RB_INIT , .Nm RB_INSERT , +.Nm RB_INSERT_NEXT , +.Nm RB_INSERT_PREV , .Nm RB_REMOVE , .Nm RB_REINSERT , .Nm RB_AUGMENT +.Nm RB_AUGMENT_CHECK, .Nm RB_UPDATE_AUGMENT .Nd "implementations of splay and rank-balanced (wavl) trees" .Sh SYNOPSIS @@ -192,11 +195,17 @@ .Ft "struct TYPE *" .Fn RB_INSERT NAME "RB_HEAD *head" "struct TYPE *elm" .Ft "struct TYPE *" +.Fn RB_INSERT_NEXT NAME "RB_HEAD *head" "struct TYPE *elm" "struct TYPE *next" +.Ft "struct TYPE *" +.Fn RB_INSERT_PREV NAME "RB_HEAD *head" "struct TYPE *elm" "struct TYPE *prev" +.Ft "struct TYPE *" .Fn RB_REMOVE NAME "RB_HEAD *head" "struct TYPE *elm" .Ft "struct TYPE *" .Fn RB_REINSERT NAME "RB_HEAD *head" "struct TYPE *elm" .Ft "void" .Fn RB_AUGMENT NAME "struct TYPE *elm" +.Ft "bool" +.Fn RB_AUGMENT_CHECK NAME "struct TYPE *elm" .Ft "void" .Fn RB_UPDATE_AUGMENT NAME "struct TYPE *elm" .Sh DESCRIPTION @@ -512,6 +521,18 @@ macro inserts the new element into the tree. .Pp The +.Fn RB_INSERT_NEXT +macro inserts the new element +.Fa elm +into the tree immediately after a given element. +.Pp +The +.Fn RB_INSERT_PREV +macro inserts the new element +.Fa elm +into the tree immediately before a given element. +.Pp +The .Fn RB_REMOVE macro removes the element .Fa elm @@ -620,6 +641,22 @@ It is typically used to maintain some associative accumulation of tree elements, such as sums, minima, maxima, and the like. .Pp The +.Fn RB_AUGMENT_CHECK +macro updates augmentation data of the element +.Fa elm +in the tree. +By default, it does nothing and returns false. +If +.Fn RB_AUGMENT_CHECK +is defined, then when an element is inserted or removed from the tree, +it is invoked for every element in the tree that is the root of an +altered subtree, working from the bottom of the tree up toward the +top, until it returns false to indicate that it did not change the +element and so working further up the tree would change nothing. +It is typically used to maintain some associative accumulation of tree +elements, such as sums, minima, maxima, and the like. +.Pp +The .Fn RB_UPDATE_AUGMENT macro updates augmentation data of the element .Fa elm diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile index 192bab4155a2..1201aa809568 100644 --- a/share/man/man4/Makefile +++ b/share/man/man4/Makefile @@ -15,6 +15,7 @@ MAN= aac.4 \ ${_acpi_panasonic.4} \ ${_acpi_rapidstart.4} \ ${_acpi_sony.4} \ + acpi_ged.4 \ acpi_thermal.4 \ acpi_battery.4 \ ${_acpi_toshiba.4} \ @@ -167,6 +168,7 @@ MAN= aac.4 \ gdb.4 \ gem.4 \ genet.4 \ + genetlink.4 \ geom.4 \ geom_linux_lvm.4 \ geom_map.4 \ @@ -284,6 +286,7 @@ MAN= aac.4 \ mac.4 \ mac_biba.4 \ mac_bsdextended.4 \ + mac_ddb.4 \ mac_ifoff.4 \ mac_lomac.4 \ mac_mls.4 \ @@ -333,6 +336,7 @@ MAN= aac.4 \ netgdb.4 \ netgraph.4 \ netintro.4 \ + netlink.4 \ netmap.4 \ ${_nfe.4} \ ${_nfsmb.4} \ @@ -466,6 +470,7 @@ MAN= aac.4 \ rl.4 \ rndtest.4 \ route.4 \ + rtnetlink.4 \ rtsx.4 \ rtw88.4 \ rtw88fw.4 \ @@ -544,6 +549,7 @@ MAN= aac.4 \ targ.4 \ tcp.4 \ tcp_bbr.4 \ + tcp_rack.4 \ tdfx.4 \ termios.4 \ textdump.4 \ @@ -582,6 +588,7 @@ MAN= aac.4 \ vtnet.4 \ watchdog.4 \ ${_wbwd.4} \ + wg.4 \ witness.4 \ wlan.4 \ wlan_acl.4 \ @@ -759,6 +766,7 @@ MLINKS+=vr.4 if_vr.4 MLINKS+=vte.4 if_vte.4 MLINKS+=vtnet.4 if_vtnet.4 MLINKS+=watchdog.4 SW_WATCHDOG.4 +MLINKS+=wg.4 if_wg.4 MLINKS+=${_wpi.4} ${_if_wpi.4} MLINKS+=xl.4 if_xl.4 @@ -917,6 +925,7 @@ _ccd.4= ccd.4 _dtrace_provs= dtrace_audit.4 \ dtrace_io.4 \ dtrace_ip.4 \ + dtrace_kinst.4 \ dtrace_lockstat.4 \ dtrace_proc.4 \ dtrace_sched.4 \ diff --git a/share/man/man4/acpi_ged.4 b/share/man/man4/acpi_ged.4 new file mode 100644 index 000000000000..dd62e172ae8d --- /dev/null +++ b/share/man/man4/acpi_ged.4 @@ -0,0 +1,64 @@ +.\" Copyright (c) 2022 Takanori Watanabe +.\" +.\" 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 October 18, 2022 +.Dt ACPI_GED 4 +.Os +.Sh NAME +.Nm acpi_ged +.Nd "ACPI Generic Event Device" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device acpi_ged" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +acpi_ged_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for generic events interface. +This handles interrupts and evaluates the specific ACPI method. +This may generate optionally ACPI notify for another device. +.Sh SEE ALSO +.Xr acpi 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 14.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Takanori Watanabe Aq Mt takawata@FreeBSD.org diff --git a/share/man/man4/acpi_thermal.4 b/share/man/man4/acpi_thermal.4 index d1cf8ee60ef2..1b9395a24be3 100644 --- a/share/man/man4/acpi_thermal.4 +++ b/share/man/man4/acpi_thermal.4 @@ -24,7 +24,7 @@ .\" .\" $FreeBSD$ .\" -.Dd March 17, 2007 +.Dd November 21, 2022 .Dt ACPI_THERMAL 4 .Os .Sh NAME @@ -84,6 +84,9 @@ Current temperature for this zone. .It Va hw.acpi.thermal.tz%d._PSV Temperature to start passive cooling by throttling down CPU, etc. This value can be overridden by the user. +.It Va hw.acpi.thermal.tz%d._CR3 +Temperature to start critical suspend to RAM (S3). +This value can be overridden by the user. .It Va hw.acpi.thermal.tz%d._HOT Temperature to start critical suspend to disk (S4). This value can be overridden by the user. diff --git a/share/man/man4/altq.4 b/share/man/man4/altq.4 index 5e8989025cb3..a84152081ba4 100644 --- a/share/man/man4/altq.4 +++ b/share/man/man4/altq.4 @@ -25,7 +25,7 @@ .\" .\" $FreeBSD$ .\" -.Dd January 26, 2021 +.Dd November 10, 2022 .Dt ALTQ 4 .Os .Sh NAME @@ -138,7 +138,6 @@ They have been applied to the following hardware drivers: .Xr bge 4 , .Xr bxe 4 , .Xr cas 4 , -.Xr cxgbe 4 , .Xr dc 4 , .Xr em 4 , .Xr epair 4 , @@ -173,19 +172,14 @@ and .Xr xl 4 . .Pp The -.Xr tun 4 +.Xr tun 4 , +.Xr if_bridge 4 , +.Xr if_vlan 4 , and .Xr ng_iface 4 pseudo drivers also do support .Nm . .Pp -The -.Xr vlan 4 -driver does not directly support -.Nm , -but as packets (mbufs) are passed to the underlying interface, a queue -can be defined for the underlying interface, and any packets directed -to the queue will be processed at the interface level. An example: .Bd -literal -offset indent altq on igb0 cbq queue { def aq } diff --git a/share/man/man4/bridge.4 b/share/man/man4/bridge.4 index e193724928ca..e5313430b407 100644 --- a/share/man/man4/bridge.4 +++ b/share/man/man4/bridge.4 @@ -35,7 +35,7 @@ .\" .\" $FreeBSD$ .\" -.Dd November 17, 2021 +.Dd September 7, 2022 .Dt IF_BRIDGE 4 .Os .Sh NAME @@ -127,7 +127,9 @@ in .Xr rc.conf 5 . .Pp The MTU of the first member interface to be added is used as the bridge MTU. -All additional members are required to have exactly the same MTU value. +All additional members will have their MTU changed to match. +If the MTU of a bridge is changed after its creation, the MTU of all member +interfaces is also changed to match. .Pp The TOE, TSO, TXCSUM and TXCSUM6 capabilities on all interfaces added to the bridge are disabled if any of the interfaces do not support/enable them. @@ -511,4 +513,5 @@ Rapid Spanning Tree Protocol (RSTP) support was added by The .Nm driver currently supports only Ethernet and Ethernet-like (e.g., 802.11) -network devices, with exactly the same interface MTU size as the bridge device. +network devices, which can be configured with the same MTU size as the bridge +device. diff --git a/share/man/man4/cc_cubic.4 b/share/man/man4/cc_cubic.4 index 806d6aec2441..9ceaaa871777 100644 --- a/share/man/man4/cc_cubic.4 +++ b/share/man/man4/cc_cubic.4 @@ -30,7 +30,7 @@ .\" .\" $FreeBSD$ .\" -.Dd May 13, 2021 +.Dd September 13, 2022 .Dt CC_CUBIC 4 .Os .Sh NAME @@ -39,6 +39,7 @@ .Sh DESCRIPTION The CUBIC congestion control algorithm was designed to provide increased throughput in fast and long-distance networks. +The CUBIC congestion control algorithm is the default for TCP. It attempts to maintain fairness when competing with legacy NewReno TCP in lower speed scenarios where NewReno is able to operate adequately. .Pp diff --git a/share/man/man4/cc_dctcp.4 b/share/man/man4/cc_dctcp.4 index 8c23f2eaa134..c4c8eb7da623 100644 --- a/share/man/man4/cc_dctcp.4 +++ b/share/man/man4/cc_dctcp.4 @@ -28,7 +28,7 @@ .\" .\" $FreeBSD$ .\" -.Dd May 13, 2021 +.Dd November 8, 2022 .Dt CC_DCTCP 4 .Os .Sh NAME @@ -91,6 +91,11 @@ gain of 1 / ( 2 ^ .It Va slowstart A flag if the congestion window should be reduced by one half after slow start. Valid settings 0 and 1, default 0. +.It Va ect1 +Controls if a DCTCP session should use IP ECT(0) marking when sending out +segments (default), or ECT(1) marking making use of L4S infrastructure. +Changes to this setting will only affect new sessions, existing sessions will +retain their previous marking value. .El .Sh SEE ALSO .Xr cc_cdg 4 , diff --git a/share/man/man4/cc_newreno.4 b/share/man/man4/cc_newreno.4 index 76dd3b2559bb..0d0f0d000d38 100644 --- a/share/man/man4/cc_newreno.4 +++ b/share/man/man4/cc_newreno.4 @@ -30,7 +30,7 @@ .\" .\" $FreeBSD$ .\" -.Dd May 13, 2021 +.Dd September 13, 2022 .Dt CC_NEWRENO 4 .Os .Sh NAME @@ -39,7 +39,6 @@ .Sh SYNOPSIS .In netinet/cc/cc_newreno.h .Sh DESCRIPTION -The NewReno congestion control algorithm is the default for TCP. Details about the algorithm can be found in RFC5681. .Sh Socket Options The diff --git a/share/man/man4/cxgbe.4 b/share/man/man4/cxgbe.4 index 5f959299d2ad..975ef5fb5f7d 100644 --- a/share/man/man4/cxgbe.4 +++ b/share/man/man4/cxgbe.4 @@ -31,7 +31,7 @@ .\" .\" $FreeBSD$ .\" -.Dd November 10, 2021 +.Dd November 10, 2022 .Dt CXGBE 4 .Os .Sh NAME @@ -277,6 +277,7 @@ Controls the hardware response to congestion. 0 instructs the hardware to backpressure its pipeline on congestion. This usually results in the port emitting PAUSE frames. 1 instructs the hardware to drop frames destined for congested queues. +2 instructs the hardware to both backpressure the pipeline and drop frames. .It Va hw.cxgbe.pause_settings PAUSE frame settings. Bit 0 is rx_pause, bit 1 is tx_pause, bit 2 is pause_autoneg. @@ -397,7 +398,6 @@ If an issue is identified with this driver with a supported adapter, email all the specific information related to the issue to .Aq Mt support@chelsio.com . .Sh SEE ALSO -.Xr altq 4 , .Xr arp 4 , .Xr ccr 4 , .Xr cxgb 4 , diff --git a/share/man/man4/cxgbev.4 b/share/man/man4/cxgbev.4 index b2fcac6c632b..9f70bf9c46a6 100644 --- a/share/man/man4/cxgbev.4 +++ b/share/man/man4/cxgbev.4 @@ -31,7 +31,7 @@ .\" .\" $FreeBSD$ .\" -.Dd May 9, 2017 +.Dd November 10, 2022 .Dt CXGBEV 4 .Os .Sh NAME @@ -290,7 +290,6 @@ If an issue is identified with this driver with a supported adapter, email all the specific information related to the issue to .Aq Mt support@chelsio.com . .Sh SEE ALSO -.Xr altq 4 , .Xr arp 4 , .Xr cxgbe 4 , .Xr netintro 4 , diff --git a/share/man/man4/da.4 b/share/man/man4/da.4 index ed820c637750..ce7f269b79c0 100644 --- a/share/man/man4/da.4 +++ b/share/man/man4/da.4 @@ -25,7 +25,7 @@ .\" .\" $FreeBSD$ .\" -.Dd December 20, 2017 +.Dd September 10, 2022 .Dt DA 4 .Os .Sh NAME @@ -133,6 +133,29 @@ variables and .Xr loader 8 tunables: .Bl -tag -width 12 +.It Va kern.cam.da.default_timeout +This variable determines how long the +.Nm +driver will wait before timing out an outstanding command. +The units for this value are seconds, and the default is currently 60 +seconds. +.It Va kern.cam.da.disable_wp_protection +Disable detection of write-protected disks. +Default is disabled. +.Po +detection of write-protected disks is enabled +.Pc . +.It Va kern.cam.da.enable_biospeedup +Enable +.Dv BIO_SPEEDUP +processing. +Default is enabled. +.It Va kern.cam.da.enable_uma_ccbs +Use UMA for CCBs. +Default is enabled. +.It Va kern.cam.da.poll_period +Media polling period in seconds. +Default is 3 seconds. .It Va kern.cam.da.retry_count This variable determines how many times the .Nm @@ -142,19 +165,20 @@ the .Nm driver dump routine. This value currently defaults to 4. -.It Va kern.cam.da.default_timeout -This variable determines how long the +.It Va kern.cam.da.send_ordered +Send Ordered Tags. +On shutdown, step through all the .Nm -driver will wait before timing out an outstanding command. -The units for this value are seconds, and the default is currently 60 -seconds. +peripheral drivers, and if the device is still open, +sync the disk to physical media. +Default is enabled. .It Va kern.cam.sort_io_queue -.It Va kern.cam.da. Ns Ar X Ns Va .sort_io_queue +.It Va kern.cam.da . Ns Ar X Ns Va .sort_io_queue These variables determine whether request queue should be sorted trying to optimize head seeks. Set to 1 to enable sorting, 0 to disable, -1 to leave it as-is. The default is sorting enabled for HDDs and disabled for SSDs. -.It Va kern.cam.da. Ns Ar X Ns Va .delete_method +.It Va kern.cam.da . Ns Ar X Ns Va .delete_method This variable specifies method to handle BIO_DELETE requests: .Bl -tag -width "ATA_TRIM" .It ATA_TRIM @@ -170,7 +194,7 @@ WRITE SAME(10) command without UNMAP flag, .It DISABLE disable BIO_DELETE support. .El -.It Va kern.cam.da. Ns Ar X Ns Va .minimum_cmd_size +.It Va kern.cam.da . Ns Ar X Ns Va .minimum_cmd_size This variable determines what the minimum READ/WRITE CDB size is for a given .Nm diff --git a/share/man/man4/dcons.4 b/share/man/man4/dcons.4 index d228ad5c16b9..2b8292695649 100644 --- a/share/man/man4/dcons.4 +++ b/share/man/man4/dcons.4 @@ -102,7 +102,7 @@ for more details. If you want to use .Nm as a -.Xr gdb 1 +.Xr gdb 1 Pq Pa ports/devel/gdb port, add the following line into .Xr loader.conf 5 : .Bd -literal -offset indent diff --git a/share/man/man4/ddb.4 b/share/man/man4/ddb.4 index d7b51b270877..7d5da91fc684 100644 --- a/share/man/man4/ddb.4 +++ b/share/man/man4/ddb.4 @@ -26,7 +26,7 @@ .\" .\" $FreeBSD$ .\" -.Dd March 14, 2021 +.Dd November 10, 2022 .Dt DDB 4 .Os .Sh NAME @@ -58,7 +58,7 @@ representation, define: .Ed .Pp To enable the -.Xr gdb 1 +.Xr gdb 4 backend, so that remote debugging with .Xr kgdb 1 Pq Pa ports/devel/gdb is possible, include: @@ -69,7 +69,7 @@ is possible, include: The .Nm kernel debugger is an interactive debugger with a syntax inspired by -.Xr gdb 1 . +.Xr gdb 1 Pq Pa ports/devel/gdb . If linked into the running kernel, it can be invoked locally with the .Ql debug @@ -182,11 +182,8 @@ command line editing capabilities. In addition to the .Nm emacs -control keys, the usual -.Tn ANSI -arrow keys may be used to -browse through the history buffer, and move the cursor within the -current line. +control keys, the usual ANSI arrow keys may be used to browse through the +history buffer, and move the cursor within the current line. .Sh COMMANDS .Ss COMMON DEBUGGER COMMANDS .Bl -tag -width indent -compact @@ -246,8 +243,8 @@ The location is also displayed in hex at the beginning of each line. .It Cm i display as a disassembled instruction .It Cm I -display as an disassembled instruction with possible alternate formats depending on the -machine. +display as a disassembled instruction with possible alternate formats +depending on the machine. On i386, this selects the alternate format for the instruction decoding (16 bits in a 32-bit code segment and vice versa). .It Cm S @@ -541,6 +538,14 @@ Switch the debugger to the thread with ID if the argument is a decimal number, or address .Ar addr , otherwise. +.Pp +.It Ic watchdog Op Ar exp +Program the +.Xr watchdog 4 +timer to fire in +.Pf 2^ Ar exp +seconds. +If no argument is provided, the watchdog timer is disabled. .El .Ss SPECIALIZED HELPER COMMANDS .Bl -tag -width indent -compact @@ -548,11 +553,13 @@ otherwise. .Ic findstack .Ar addr .Xc -Prints the thread address for a thread kernel-mode stack of which contains the -specified address. -If the thread is not found, search the thread stack cache and prints the -cached stack address. -Otherwise, prints nothing. +Prints the address of the thread whose kernel-mode stack contains +.Ar addr , +if any. +.Pp +.It Ic show Cm active trace +.It acttrace +Show a stack trace for every thread running on a CPU. .Pp .It Ic show Cm all procs Ns Op Li / Ns Cm a .It Ic ps Ns Op Li / Ns Cm a @@ -607,6 +614,15 @@ addresses, and Resource IDs. Dump data about APIC IDT vector mappings. .\" .Pp +.It Ic show Cm badstacks +Walk the +.Xr witness 4 +graph and print any lock-order violations. +This command is only available if +.Xr witness 4 +is included in the kernel. +.\" +.Pp .It Ic show Cm breaks Show breakpoints set with the "break" command. .\" @@ -640,19 +656,18 @@ present at .Ar addr . .\" .Pp -.It Ic show Cm cbstat -Show brief information about the TTY subsystem. -.\" -.Pp -.It Ic show Cm cdev -Without argument, show the list of all created cdev's, consisting of devfs -node name and struct cdev address. -When address of cdev is supplied, show some internal devfs state of the cdev. +.It Ic show Cm cdev Op Ar addr +Show the internal devfs state of the cdev structure located at +.Ar addr . +If no argument is provided, show the list of all created cdevs, consisting of +the devfs node name and the +.Vt struct cdev +address. .\" .Pp .It Ic show Cm conifhk Lists hooks currently waiting for completion in -run_interrupt_driven_config_hooks(). +.Fn run_interrupt_driven_config_hooks . .\" .Pp .It Ic show Cm cpusets @@ -729,6 +744,13 @@ present at .Ar addr . .\" .Pp +.It Ic show Cm iosched Ar addr +Show information about the I/O scheduler +.Vt struct cam_iosched_softc +located at +.Ar addr . +.\" +.Pp .It Ic show Cm inodedeps Op Ar addr Show brief information about each inodedep structure. If @@ -756,13 +778,20 @@ Dump the interrupt statistics. Show interrupt lines and their respective kernel threads. .\" .Pp -.It Ic show Cm jails -Show the list of -.Xr jail 8 -instances. -In addition to what -.Xr jls 8 -shows, also list kernel internal details. +.It Ic show Cm ktr Ns Op Li / Ns Cm a Ns Cm v Ns Cm V +Print the contents of the +.Xr ktr 4 +trace buffer. +The +.Cm v +modifier will request fully verbose output, causing the file, line number, and +timestamp to be printed for each trace entry. +The +.Cm V +modifier will request only the timestamps to be printed. +The +.Cm a +modifier will request that the output be unpaginated. .\" .Pp .It Ic show Cm lapic @@ -773,24 +802,24 @@ Show information from the local APIC registers for this CPU. Show lock structure. The output format is as follows: .Bl -tag -width "flags" -.It Ic class: +.It Ic class : Class of the lock. Possible types include .Xr mutex 9 , .Xr rmlock 9 , .Xr rwlock 9 , .Xr sx 9 . -.It Ic name: +.It Ic name : Name of the lock. -.It Ic flags: +.It Ic flags : Flags passed to the lock initialization function. .Em flags values are lock class specific. -.It Ic state: +.It Ic state : Current state of a lock. .Em state values are lock class specific. -.It Ic owner: +.It Ic owner : Lock owner. .El .\" @@ -870,11 +899,14 @@ It is useful if you got a kernel panic, attached a serial cable to the machine and want to get the boot messages from before the system hang. .\" -.It Ic show Cm mount -Displays short info about all currently mounted file systems. .Pp -.It Ic show Cm mount Ar addr -Displays details about the given mount point. +.It Ic show Cm mount Op Ar addr +Displays details about the mount point located at +.Ar addr . +If no +.Ar addr +is specified, +displays short info about all currently mounted file systems. .\" .Pp .It Ic show Cm object Ns Oo Li / Ns Cm f Oc Ar addr @@ -932,16 +964,24 @@ Names of spin locks held. Dump process groups present within the system. .\" .Pp -.It Ic show Cm proc Op Ar addr -If no -.Op Ar addr -is specified, print information about the current process. -Otherwise, show information about the process at address +.It Ic show Cm prison Op Ar addr +Show the prison structure located at .Ar addr . +If no +.Ar addr +argument is specified, show information about all prisons in the system. .\" .Pp -.It Ic show Cm procvm -Show process virtual memory layout. +.It Ic show Cm proc Op Ar addr +Show information about the process structure located at address +.Ar addr , +or the current process if no argument is specified. +.\" +.Pp +.It Ic show Cm procvm Op Ar addr +Show process virtual memory layout for the process located at +.Ar addr , +or the current process if no argument is specified. .\" .Pp .It Ic show Cm protosw Ar addr @@ -994,36 +1034,26 @@ Now an alias for .Ic show Cm lockchain . .\" .Pp -.It Ic show Cm sleepq -.It Ic show Cm sleepqueue -Both commands provide the same functionality. -They show sleepqueue -.Vt struct sleepqueue -structure. -Sleepqueues are used within the -.Fx -kernel to implement sleepable -synchronization primitives (thread holding a lock might sleep or -be context switched), which at the time of writing are: -.Xr condvar 9 , -.Xr sx 9 -and standard -.Xr msleep 9 -interface. +.It Ic show Cm sleepq Ar addr +.It Ic show Cm sleepqueue Ar addr +Show the +.Xr sleepqueue 9 +structure located at +.Ar addr . .\" .Pp .It Ic show Cm sockbuf Ar addr +Show the socket buffer +.Va struct sockbuf +located at +.Ar addr . +.\" +.Pp .It Ic show Cm socket Ar addr -Those commands print -.Vt struct sockbuf -and +Show the socket object .Vt struct socket -objects placed at +located at .Ar addr . -Output consists of all values present in structures mentioned. -For exact interpretation and more details, visit -.Pa sys/socket.h -header file. .\" .Pp .It Ic show Cm sysregs @@ -1141,11 +1171,8 @@ and none have zero ref counts. .\" .Pp .It Ic show Cm vmopag -This is supposed to show physical addresses consumed by a -VM object. -Currently, it is not possible to use this command when -.Xr witness 4 -is compiled in the kernel. +Walk the list of VM objects in the system, printing the indices and physical +addresses of the VM pages belonging to each object. .\" .Pp .It Ic show Cm vnet Ar addr @@ -1155,11 +1182,11 @@ structure present at the address .Ar addr . .\" .Pp -.It Ic show Cm vnode Op Ar addr +.It Ic show Cm vnode Ar addr Prints vnode .Vt struct vnode structure lying at -.Op Ar addr . +.Ar addr . For the exact interpretation of the output, look at the .Pa sys/vnode.h header file. @@ -1187,10 +1214,14 @@ subsystem. .El .Ss OFFLINE DEBUGGING COMMANDS .Bl -tag -width indent -compact +.It Ic dump +Initiate a kernel core dump to the device(s) configured by +.Xr dumpon 8 . +.Pp .It Ic gdb Switches to remote GDB mode. In remote GDB mode, another machine is required that runs -.Xr gdb 1 +.Xr gdb 1 Pq Pa ports/devel/gdb using the remote debug feature, with a connection to the serial console port on the target machine. .Pp @@ -1552,8 +1583,8 @@ CR TILDE CTRL-R causes an immediate reboot. In all these sequences, CR represents Carriage Return and is usually sent by pressing the Enter or Return key. TILDE is the ASCII tilde character (~). -CTRL-x is Control x, send by pressing the Control key, then x, then releasing both. -and then releasing both. +CTRL-x is Control x, sent by pressing the Control key, then x, then releasing +both. .Pp The break-to-debugger behavior can be enabled by setting .Xr sysctl 8 @@ -1598,10 +1629,11 @@ directory. .Pa sys/vnode.h .El .Sh SEE ALSO -.Xr gdb 1 , +.Xr gdb 1 Pq Pa ports/devel/gdb , .Xr kgdb 1 Pq Pa ports/devel/gdb , .Xr acpi 4 , .Xr CAM 4 , +.Xr gdb 4 , .Xr mac_ddb 4 , .Xr mac_test 4 , .Xr netgraph 4 , diff --git a/share/man/man4/divert.4 b/share/man/man4/divert.4 index d8296995ca97..18da54ee9fc9 100644 --- a/share/man/man4/divert.4 +++ b/share/man/man4/divert.4 @@ -1,6 +1,6 @@ .\" $FreeBSD$ .\" -.Dd December 17, 2004 +.Dd August 30, 2022 .Dt DIVERT 4 .Os .Sh NAME @@ -11,7 +11,7 @@ .In sys/socket.h .In netinet/in.h .Ft int -.Fn socket PF_INET SOCK_RAW IPPROTO_DIVERT +.Fn socket PF_DIVERT SOCK_RAW 0 .Pp To enable support for divert sockets, place the following lines in the kernel configuration file: @@ -30,24 +30,30 @@ ipfw_load="YES" ipdivert_load="YES" .Ed .Sh DESCRIPTION -Divert sockets are similar to raw IP sockets, except that they -can be bound to a specific +Divert sockets allow to intercept and re-inject packets flowing through +the +.Xr ipfw 4 +firewall. +A divert socket can be bound to a specific .Nm port via the .Xr bind 2 system call. -The IP address in the bind is ignored; only the port -number is significant. +The sockaddr argument shall be sockaddr_in with sin_port set to the +desired value. +Note that the +.Nm +port has nothing to do with TCP/UDP ports. +It is just a cookie number, that allows to differentiate between different +divert points in the +.Xr ipfw 4 +ruleset. A divert socket bound to a divert port will receive all packets diverted -to that port by some (here unspecified) kernel mechanism(s). -Packets may also be written to a divert port, in which case they -re-enter kernel IP packet processing. +to that port by +.Xr ipfw 4 . +Packets may also be written to a divert port, in which case they re-enter +firewall processing at the next rule. .Pp -Divert sockets are normally used in conjunction with -.Fx Ns 's -packet filtering implementation and the -.Xr ipfw 8 -program. By reading from and writing to a divert socket, matching packets can be passed through an arbitrary ``filter'' as they travel through the host machine, special routing tricks can be done, etc. @@ -153,8 +159,9 @@ with the correct value. Packets written as incoming and having incorrect checksums will be dropped. Otherwise, all header fields are unchanged (and therefore in network order). .Pp -Binding to port numbers less than 1024 requires super-user access, as does -creating a socket of type SOCK_RAW. +Creating a +.Nm +socket requires super-user access. .Sh ERRORS Writing to a divert socket can return these errors, along with the usual errors possible when writing raw packets: diff --git a/share/man/man4/dtrace_kinst.4 b/share/man/man4/dtrace_kinst.4 new file mode 100644 index 000000000000..48253add6855 --- /dev/null +++ b/share/man/man4/dtrace_kinst.4 @@ -0,0 +1,89 @@ +.\" Copyright (c) 2022 Christos Margiolis <christos@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 October 01, 2022 +.Dt DTRACE_KINST 4 +.Os +.Sh NAME +.Nm dtrace_kinst +.Nd a DTrace provider for tracing arbitrary instructions in a given kernel +function. +.Sh SYNOPSIS +kinst::<function>:<instruction> +.Sh DESCRIPTION +.Pp +The DTrace +.Nm kinst +provider allows the user to trace any instruction in a given kernel function. +<function> corresponds to the function to be traced, and <instruction> is the +offset to the specific instruction, and can be obtained from the function's +disassembly using +.Xr kgdb 1 . +.Pp +.Nm kinst +creates probes on-demand, meaning it searches for and parses the function's +instructions each time +.Xr dtrace 1 +is run, and not at module load time. This is in contrast to FBT's load-time +parsing, since +.Nm kinst +can potentially create thousands of probes for just a single function, instead +of up to two (entry and return) in the case of FBT. +.Sh EXAMPLES +.Pp +Find the offset to the third instruction in +.Fn vm_fault +and trace it: +.Bd -literal -offset indent +# kgdb +(kgdb) disas /r vm_fault +Dump of assembler code for function vm_fault: + 0xffffffff80876df0 <+0>: 55 push %rbp + 0xffffffff80876df1 <+1>: 48 89 e5 mov %rsp,%rbp + 0xffffffff80876df4 <+4>: 41 57 push %r15 + +# dtrace -n 'kinst::vm_fault:4' +.Ed +.Pp +Trace all instructions in +.Fn amd64_syscall : +.Bd -literal -offset indent +# dtrace -n 'kinst::amd64_syscall:' +.Ed +.Sh IMPLEMENTATION NOTES +The provider is currently implemented only for amd64. +.Sh SEE ALSO +.Xr dtrace 1 , +.Xr kgdb 1 +.Sh HISTORY +The +.Nm kinst +provider first appeared in +.Fx +14.0. +.Sh AUTHORS +This manual page was written by +.An Christos Margiolis Aq Mt christos@FreeBSD.org . diff --git a/share/man/man4/gdb.4 b/share/man/man4/gdb.4 index de2f4d108048..47a1c9896843 100644 --- a/share/man/man4/gdb.4 +++ b/share/man/man4/gdb.4 @@ -37,7 +37,7 @@ The .Nm kernel debugger is a variation of -.Xr gdb 1 +.Xr gdb 1 Pq Pa ports/devel/gdb which understands some aspects of the .Fx kernel environment. @@ -90,7 +90,7 @@ on, In this mode, you need the .Fl k flag to indicate to -.Xr gdb 1 +.Xr gdb 1 Pq Pa ports/devel/gdb that the .Dq "dump file" .Pa /dev/mem @@ -336,9 +336,9 @@ The remote system continues to run. The user interface to .Nm is via -.Xr gdb 1 , +.Xr gdb 1 Pq Pa ports/devel/gdb , so -.Xr gdb 1 +.Xr gdb 1 Pq Pa ports/devel/gdb commands also work. This section discusses only the extensions for kernel debugging that get installed in the kernel build directory. @@ -387,7 +387,7 @@ are convenience commands which invoke .Ss "The current process environment" The following macros are convenience functions intended to make things easier than the standard -.Xr gdb 1 +.Xr gdb 1 Pq Pa ports/devel/gdb commands. .Bl -tag -width indent .It Ic f0 @@ -467,7 +467,7 @@ Show some PCB contents of the process .El .Ss "Examining data structures" You can use standard -.Xr gdb 1 +.Xr gdb 1 Pq Pa ports/devel/gdb commands to look at most data structures. The macros in this section are convenience functions which typically display the data in a more readable @@ -568,7 +568,7 @@ It does nothing else except to print a warning message to remind you to remove it again. .El .Sh SEE ALSO -.Xr gdb 1 , +.Xr gdb 1 Pq Pa ports/devel/gdb , .Xr ps 1 , .Xr ddb 4 , .Xr firewire 4 , @@ -581,7 +581,7 @@ This man page was written by .An Greg Lehey Aq Mt grog@FreeBSD.org . .Sh BUGS The -.Xr gdb 1 +.Xr gdb 1 Pq Pa ports/devel/gdb debugger was never designed to debug kernels, and it is not a very good match. Many problems exist. diff --git a/share/man/man4/genetlink.4 b/share/man/man4/genetlink.4 new file mode 100644 index 000000000000..2c5b9b99f994 --- /dev/null +++ b/share/man/man4/genetlink.4 @@ -0,0 +1,147 @@ +.\" +.\" Copyright (C) 2022 Alexander Chernikov <melifaro@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, 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 November 1, 2022 +.Dt GENETLINK 4 +.Os +.Sh NAME +.Nm genetlink +.Nd Generic Netlink +.Sh SYNOPSIS +.In netlink/netlink.h +.In netlink/netlink_generic.h +.Ft int +.Fn socket AF_NETLINK SOCK_DGRAM NETLINK_GENERIC +.Sh DESCRIPTION +The +.Dv NETLINK_GENERIC +is a "container" family, used for dynamic registration of other families +belonging to the various subsystems. +These subsystems provide a string family name during registration and +receive a dynamically-allocated family id. +Allocated family identifiers are then used by applications to get access to +functions provided by that subsystem via netlink. +There are standard methods for resolving string family names to family +identifiers. +A similar mechanism works for the notification groups provided by those +families. +.Pp +All generic netlink families share a common header: +.Bd -literal +struct genlmsghdr { + uint8_t cmd; /* command within the family */ + uint8_t version; /* ABI version for the cmd */ + uint16_t reserved; /* reserved: set to 0 */ +}; +.Ed +The family id is encoded in the +.Dv nlmsg_type +of the base netlink header. +The +.Va cmd +field is the command identifier within the family. +The +.Va version +field is the command version. +.Sh METHODS +The generic Netlink framework provides the base family, +.Dv GENL_ID_CTRL +("nlctrl") with a fixed family id. +This family is used to list the details of all registered families. +.Pp +The following messages are supported by the framework: +.Ss CTRL_CMD_GETFAMILY +Fetches a single family or all registered families, depending on the +.Dv NLM_F_DUMP +flag. +Each family is reported as +.Dv CTRL_CMD_NEWFAMILY +message. +The following filters are recognised by the kernel: +.Pp +.Bd -literal -offset indent -compact +CTRL_ATTR_FAMILY_ID (uint16_t) current family id assigned by kernel +CTRL_ATTR_FAMILY_NAME (string) family name +.Ed +.Ss TLVs +.Bl -tag -width indent +.It Dv CTRL_ATTR_FAMILY_ID +(uint16_t) Dynamically-assigned family identifier. +.It Dv CTRL_ATTR_FAMILY_NAME +(string) Family name. +.It Dv CTRL_ATTR_HDRSIZE +(uint32_t) Family mandatory header size (typically 0). +.It Dv CTRL_ATTR_MAXATTR +(uint32_t) Maximum attribute number valid for the family. +.It Dv CTRL_ATTR_OPS +(nested) List of the operations supported by the family. +The attribute consists of a list of nested TLVs, with attribute values +monotonically incremented, starting from 0. +The following attributes are present in each TLV: +.Bl -tag -width indent +.It Dv CTRL_ATTR_OP_ID +Operation (message) number. +.It Dv CTRL_ATTR_OP_FLAGS +Operation flags. +The following flags are supported: +.Bd -literal -offset indent -compact +GENL_ADMIN_PERM requires elevated permissions +GENL_CMD_CAP_DO operation is a modification request +GENL_CMD_CAP_DUMP operation is a get/dump request +.Ed +.El +.It Dv CTRL_ATTR_MCAST_GROUPS +(nested) List of the notification groups supported by the family. +The attribute consists of a list of nested TLVs, with attribute values +monotonically incremented, starting from 0. +The following attributes are present in each TLV: +.Bl -tag -width indent +.It Dv CTRL_ATTR_MCAST_GRP_ID +Group id that can be used in +.Dv NETLINK_ADD_MEMBERSHIP +.Xr setsockopt 2 . +.It Dv CTRL_ATTR_MCAST_GRP_NAME +(string) Human-readable name of the group. +.El +.El +.Ss Groups +The following groups are defined: +.Bd -literal -offset indent -compact +"notify" Notifies on family registrations/removal. +.Ed +.Sh SEE ALSO +.Xr netlink 4 +.Sh HISTORY +The +.Dv NETLINK_GENERIC +protocol family appeared in +.Fx 14.0 . +.Sh AUTHORS +The netlink was implementated by +.An -nosplit +.An Alexander Chernikov Aq Mt melifaro@FreeBSD.org . +It was derived from the Google Summer of Code 2021 project by +.An Ng Peng Nam Sean . diff --git a/share/man/man4/iichid.4 b/share/man/man4/iichid.4 index 526a6f444440..1bd75c2db883 100644 --- a/share/man/man4/iichid.4 +++ b/share/man/man4/iichid.4 @@ -76,7 +76,7 @@ In that case .Nm enables sampling mode with periodic polling of hardware by driver means. See dev.iichid.*.sampling_* -.Xr sysctl 4 +.Xr sysctl 8 variables for tuning of sampling parameters. .Sh HISTORY The diff --git a/share/man/man4/inet.4 b/share/man/man4/inet.4 index 31c80feecfaa..45da9301f86f 100644 --- a/share/man/man4/inet.4 +++ b/share/man/man4/inet.4 @@ -28,7 +28,7 @@ .\" From: @(#)inet.4 8.1 (Berkeley) 6/5/93 .\" $FreeBSD$ .\" -.Dd August 1, 2022 +.Dd September 8, 2022 .Dt INET 4 .Os .Sh NAME @@ -186,6 +186,8 @@ Defaults to off. .It Va fragpackets Integer: Current number of IPv4 fragment reassembly queue entries for the VNET (read-only). +.It Va fragttl +Integer: time to live for IPv4 packet fragments in the per-VNET reassemby queue. .It Va loopback_prefixlen Integer: prefix length of the address space reserved for loopback purposes. The default is 8, meaning that 127.0.0.0/8 is reserved for loopback, @@ -278,6 +280,8 @@ The number must be between 512 and 32768 inclusive. This is a per-VNET value. .It Va random_id_total Integer: count of IP IDs created (read-only, per-VNET). +.It Va reass_hashsize +Number of hash slots in the IPv4 reassembly queue (loader tunable). .It Va redirect Boolean: enable/disable sending of ICMP redirects in response to .Tn IP diff --git a/share/man/man4/ip.4 b/share/man/man4/ip.4 index d1c3b34b51a6..282b076a2bef 100644 --- a/share/man/man4/ip.4 +++ b/share/man/man4/ip.4 @@ -453,21 +453,6 @@ In scenarios such as benchmarking, this behavior may be undesirable. In these cases, .Va net.inet.ip.portrange.randomized can be used to toggle randomization off. -If more than -.Va net.inet.ip.portrange.randomcps -ports have been allocated in the last second, then return to sequential -port allocation. -Return to random allocation only once the current port allocation rate -drops below -.Va net.inet.ip.portrange.randomcps -for at least -.Va net.inet.ip.portrange.randomtime -seconds. -The default values for -.Va net.inet.ip.portrange.randomcps -and -.Va net.inet.ip.portrange.randomtime -are 10 port allocations per second and 45 seconds correspondingly. .Ss "Multicast Options" .Tn IP multicasting is supported only on diff --git a/share/man/man4/ip6.4 b/share/man/man4/ip6.4 index 9dd9007866a2..3c6c5969ecb5 100644 --- a/share/man/man4/ip6.4 +++ b/share/man/man4/ip6.4 @@ -229,7 +229,7 @@ Get or set whether a datagram's original destination address and port are returned as ancillary data along with the payload in subsequent .Xr recvmsg 2 calls. -The information is stored in the the ancillary data as a +The information is stored in the ancillary data as a .Tn sockaddr_in6 structure. .It Dv IPV6_PORTRANGE Fa "int *" diff --git a/share/man/man4/iwlwifi.4 b/share/man/man4/iwlwifi.4 index bfb3c00d9217..94614b3b15ff 100644 --- a/share/man/man4/iwlwifi.4 +++ b/share/man/man4/iwlwifi.4 @@ -186,7 +186,7 @@ Intel(R) Wi-Fi 6 AX204 160MHz .Nm will be a successor to .Xr iwm 4 -and may superseed that driver in the future. +and may supersede that driver in the future. It still complements the .Xr iwn 4 driver which supports older chipsets. diff --git a/share/man/man4/mod_cc.4 b/share/man/man4/mod_cc.4 index a00f17ede5e4..a03ff0630c15 100644 --- a/share/man/man4/mod_cc.4 +++ b/share/man/man4/mod_cc.4 @@ -29,7 +29,7 @@ .\" .\" $FreeBSD$ .\" -.Dd August 6, 2019 +.Dd September 13, 2022 .Dt MOD_CC 4 .Os .Sh NAME @@ -47,7 +47,7 @@ using the .Xr kld 4 facility. .Pp -The default algorithm is NewReno, and all connections use the default unless +The default algorithm is CUBIC, and all connections use the default unless explicitly overridden using the .Dv TCP_CONGESTION socket option (see @@ -127,7 +127,7 @@ For further explanation please see the internet-draft. .Pp Each congestion control module may also expose other MIB variables to control their behaviour. -Note that both newreno and cubic now support hystart++ based on the version 3 of the internet-draft. +Note that both NewReno and CUBIC now support Hystart++ based on the version 3 of the internet-draft. .Sh Kernel Configuration All of the available congestion control modules may also be loaded via kernel configutation options. @@ -138,10 +138,10 @@ Compilation of the kernel will fail if these two conditions are not met. The framework exposes the following kernel configuration options. .Bl -tag -width ".Va CC_NEWRENO" .It Va CC_NEWRENO -This directive loads the newreno congestion control algorithm and is included -in GENERIC by default. +This directive loads the NewReno congestion control algorithm. .It Va CC_CUBIC -This directive loads the cubic congestion control algorithm. +This directive loads the CUBIC congestion control algorithm and is included +in GENERIC by default. .It Va CC_VEGAS This directive loads the vegas congestion control algorithm, note that this algorithm also requires the TCP_HHOOK option as well. @@ -160,7 +160,7 @@ this algorithm also requires the TCP_HHOOK option as well. This directive loads the htcp congestion control algorithm. .It Va CC_DEFAULT This directive specifies the string that represents the name of the system default algorithm, the GENERIC kernel -defaults this to newreno. +defaults this to CUBIC. .El .Sh SEE ALSO .Xr cc_cdg 4 , diff --git a/share/man/man4/mpr.4 b/share/man/man4/mpr.4 index 3cc516397e33..e6bd863dfe35 100644 --- a/share/man/man4/mpr.4 +++ b/share/man/man4/mpr.4 @@ -2,7 +2,7 @@ .\" Copyright (c) 2010 Spectra Logic Corporation .\" Copyright (c) 2014 LSI Corp .\" Copyright (c) 2015-2017 Avago Technologies -.\" Copyright (c) 2015-2017 Broadcom Ltd. +.\" Copyright (c) 2015-2022 Broadcom Ltd. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -99,6 +99,10 @@ Broadcom Ltd./Avago Tech (LSI) SAS 3616 (16 Port SAS/PCIe) Broadcom Ltd./Avago Tech (LSI) SAS 3708 (8 Port SAS/PCIe) .It Broadcom Ltd./Avago Tech (LSI) SAS 3716 (16 Port SAS/PCIe) +.It +Broadcom Ltd./Avago Tech (LSI) SAS 3816 (16 Port SAS/PCIe) +.It +Broadcom Ltd./Avago Tech (LSI) SAS 3916 (16 Port SAS/PCIe) .El .Sh CONFIGURATION In all tunable descriptions below, X represents the adapter number. diff --git a/share/man/man4/netdump.4 b/share/man/man4/netdump.4 index a6150eb758e3..ba39452c7076 100644 --- a/share/man/man4/netdump.4 +++ b/share/man/man4/netdump.4 @@ -24,16 +24,18 @@ .\" .\" $FreeBSD$ .\" -.Dd August 25, 2020 +.Dd November 10, 2022 .Dt NETDUMP 4 .Os .Sh NAME .Nm netdump .Nd protocol for transmitting kernel dumps to a remote server .Sh SYNOPSIS -To compile netdump client support into the kernel, place the following line in +To compile netdump client support into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent +.Cd "options INET" +.Cd "options DEBUGNET" .Cd "options NETDUMP" .Ed .Sh DESCRIPTION diff --git a/share/man/man4/netgdb.4 b/share/man/man4/netgdb.4 index aaa2a2801ca7..81bc2fe969a1 100644 --- a/share/man/man4/netgdb.4 +++ b/share/man/man4/netgdb.4 @@ -24,18 +24,21 @@ .\" .\" $FreeBSD$ .\" -.Dd October 17, 2019 +.Dd November 10, 2022 .Dt NETGDB 4 .Os .Sh NAME .Nm netgdb .Nd protocol for debugging the kernel with GDB over the network .Sh SYNOPSIS -NetGDB support is compiled by default, if DDB, GDB, and INET are enabled. -To build a kernel without it, add the following line to your kernel -configuration file: +To compile NetGDB support into the kernel, place the following lines in your +kernel configuration file: .Bd -ragged -offset indent -.Cd "nooptions NETGDB" +.Cd "options DDB" +.Cd "options GDB" +.Cd "options INET" +.Cd "options DEBUGNET" +.Cd "options NETGDB" .Ed .Sh DESCRIPTION .Nm diff --git a/share/man/man4/netlink.4 b/share/man/man4/netlink.4 new file mode 100644 index 000000000000..bbfa55049e2e --- /dev/null +++ b/share/man/man4/netlink.4 @@ -0,0 +1,349 @@ +.\" +.\" Copyright (C) 2022 Alexander Chernikov <melifaro@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, 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 November 30, 2022 +.Dt NETLINK 4 +.Os +.Sh NAME +.Nm Netlink +.Nd Kernel network configuration protocol +.Sh SYNOPSIS +.In netlink/netlink.h +.In netlink/netlink_route.h +.Ft int +.Fn socket AF_NETLINK SOCK_DGRAM int family +.Sh DESCRIPTION +Netlink is a user-kernel message-based communication protocol primarily used +for network stack configuration. +Netlink is easily extendable and supports large dumps and event +notifications, all via a single socket. +The protocol is fully asynchronous, allowing one to issue and track multiple +requests at once. +Netlink consists of multiple families, which commonly group the commands +belonging to the particular kernel subsystem. +Currently, the supported families are: +.Pp +.Bd -literal -offset indent -compact +NETLINK_ROUTE network configuration, +NETLINK_GENERIC "container" family +.Ed +.Pp +The +.Dv NETLINK_ROUTE +family handles all interfaces, addresses, neighbors, routes, and VNETs +configuration. +More details can be found in +.Xr rtnetlink 4 . +The +.Dv NETLINK_GENERIC +family serves as a +.Do container Dc , +allowing registering other families under the +.Dv NETLINK_GENERIC +umbrella. +This approach allows using a single netlink socket to interact with +multiple netlink families at once. +More details can be found in +.Xr genetlink 4 . +.Pp +Netlink has its own sockaddr structure: +.Bd -literal +struct sockaddr_nl { + uint8_t nl_len; /* sizeof(sockaddr_nl) */ + sa_family_t nl_family; /* netlink family */ + uint16_t nl_pad; /* reserved, set to 0 */ + uint32_t nl_pid; /* automatically selected, set to 0 */ + uint32_t nl_groups; /* multicast groups mask to bind to */ +}; +.Ed +.Pp +Typically, filling this structure is not required for socket operations. +It is presented here for completeness. +.Sh PROTOCOL DESCRIPTION +The protocol is message-based. +Each message starts with the mandatory +.Va nlmsghdr +header, followed by the family-specific header and the list of +type-length-value pairs (TLVs). +TLVs can be nested. +All headers and TLVS are padded to 4-byte boundaries. +Each +.Xr send 2 or +.Xr recv 2 +system call may contain multiple messages. +.Ss BASE HEADER +.Bd -literal +struct nlmsghdr { + uint32_t nlmsg_len; /* Length of message including header */ + uint16_t nlmsg_type; /* Message type identifier */ + uint16_t nlmsg_flags; /* Flags (NLM_F_) */ + uint32_t nlmsg_seq; /* Sequence number */ + uint32_t nlmsg_pid; /* Sending process port ID */ +}; +.Ed +.Pp +The +.Va nlmsg_len +field stores the whole message length, in bytes, including the header. +This length has to be rounded up to the nearest 4-byte boundary when +iterating over messages. +The +.Va nlmsg_type +field represents the command/request type. +This value is family-specific. +The list of supported commands can be found in the relevant family +header file. +.Va nlmsg_seq +is a user-provided request identifier. +An application can track the operation result using the +.Dv NLMSG_ERROR +messages and matching the +.Va nlmsg_seq +. +The +.Va nlmsg_pid +field is the message sender id. +This field is optional for userland. +The kernel sender id is zero. +The +.Va nlmsg_flags +field contains the message-specific flags. +The following generic flags are defined: +.Pp +.Bd -literal -offset indent -compact +NLM_F_REQUEST Indicates that the message is an actual request to the kernel +NLM_F_ACK Request an explicit ACK message with an operation result +.Ed +.Pp +The following generic flags are defined for the "GET" request types: +.Pp +.Bd -literal -offset indent -compact +NLM_F_ROOT Return the whole dataset +NLM_F_MATCH Return all entries matching the criteria +.Ed +These two flags are typically used together, aliased to +.Dv NLM_F_DUMP +.Pp +The following generic flags are defined for the "NEW" request types: +.Pp +.Bd -literal -offset indent -compact +NLM_F_CREATE Create an object if none exists +NLM_F_EXCL Don't replace an object if it exists +NLM_F_REPLACE Replace an existing matching object +NLM_F_APPEND Append to an existing object +.Ed +.Pp +The following generic flags are defined for the replies: +.Pp +.Bd -literal -offset indent -compact +NLM_F_MULTI Indicates that the message is part of the message group +NLM_F_DUMP_INTR Indicates that the state dump was not completed +NLM_F_DUMP_FILTERED Indicates that the dump was filtered per request +NLM_F_CAPPED Indicates the original message was capped to its header +NLM_F_ACK_TLVS Indicates that extended ACK TLVs were included +.Ed +.Ss TLVs +Most messages encode their attributes as type-length-value pairs (TLVs). +The base TLV header: +.Bd -literal +struct nlattr { + uint16_t nla_len; /* Total attribute length */ + uint16_t nla_type; /* Attribute type */ +}; +.Ed +The TLV type +.Pq Va nla_type +scope is typically the message type or group within a family. +For example, the +.Dv RTN_MULTICAST +type value is only valid for +.Dv RTM_NEWROUTE +, +.Dv RTM_DELROUTE +and +.Dv RTM_GETROUTE +messages. +TLVs can be nested; in that case internal TLVs may have their own sub-types. +All TLVs are packed with 4-byte padding. +.Ss CONTROL MESSAGES +A number of generic control messages are reserved in each family. +.Pp +.Dv NLMSG_ERROR +reports the operation result if requested, optionally followed by +the metadata TLVs. +The value of +.Va nlmsg_seq +is set to its value in the original messages, while +.Va nlmsg_pid +is set to the socket pid of the original socket. +The operation result is reported via +.Vt "struct nlmsgerr": +.Bd -literal +struct nlmsgerr { + int error; /* Standard errno */ + struct nlmsghdr msg; /* Original message header */ +}; +.Ed +If the +.Dv NETLINK_CAP_ACK +socket option is not set, the remainder of the original message will follow. +If the +.Dv NETLINK_EXT_ACK +socket option is set, the kernel may add a +.Dv NLMSGERR_ATTR_MSG +string TLV with the textual error description, optionally followed by the +.Dv NLMSGERR_ATTR_OFFS +TLV, indicating the offset from the message start that triggered an error. +If the operation reply is a multipart message, then no +.Dv NLMSG_ERROR +reply is generated, only a +.Dv NLMSG_DONE +message, closing multipart sequence. +.Pp +.Dv NLMSG_DONE +indicates the end of the message group: typically, the end of the dump. +It contains a single +.Vt int +field, describing the dump result as a standard errno value. +.Sh SOCKET OPTIONS +Netlink supports a number of custom socket options, which can be set with +.Xr setsockopt 2 +with the +.Dv SOL_NETLINK +.Fa level : +.Bl -tag -width indent +.It Dv NETLINK_ADD_MEMBERSHIP +Subscribes to the notifications for the specific group (int). +.It Dv NETLINK_DROP_MEMBERSHIP +Unsubscribes from the notifications for the specific group (int). +.It Dv NETLINK_LIST_MEMBERSHIPS +Lists the memberships as a bitmask. +.It Dv NETLINK_CAP_ACK +Instructs the kernel to send the original message header in the reply +without the message body. +.It Dv NETLINK_EXT_ACK +Acknowledges ability to receive additional TLVs in the ACK message. +.El +.Pp +Additionally, netlink overrides the following socket options from the +.Dv SOL_SOCKET +.Fa level : +.Bl -tag -width indent +.It Dv SO_RCVBUF +Sets the maximum size of the socket receive buffer. +If the caller has +.Dv PRIV_NET_ROUTE +permission, the value can exceed the currently-set +.Va kern.ipc.maxsockbuf +value. +.El +.Sh SYSCTL VARIABLES +A set of +.Xr sysctl 8 +variables is available to tweak run-time parameters: +.Bl -tag -width indent +.It Va net.netlink.sendspace +Default send buffer for the netlink socket. +Note that the socket sendspace has to be at least as long as the longest +message that can be transmitted via this socket. +.El +.Bl -tag -width indent +.It Va net.netlink.recvspace +Default receive buffer for the netlink socket. +Note that the socket recvspace has to be least as long as the longest +message that can be received from this socket. +.El +.Sh DEBUGGING +Netlink implements per-functional-unit debugging, with different severities +controllable via the +.Va net.netlink.debug +branch. +These messages are logged in the kernel message buffer and can be seen in +.Xr dmesg 8 +. +The following severity levels are defined: +.Bl -tag -width indent +.It Dv LOG_DEBUG(7) +Rare events or per-socket errors are reported here. +This is the default level, not impacting production performance. +.It Dv LOG_DEBUG2(8) +Socket events such as groups memberships, privilege checks, commands and dumps +are logged. +This level does not incur significant performance overhead. +.It Dv LOG_DEBUG9(9) +All socket events, each dumped or modified entities are logged. +Turning it on may result in significant performance overhead. +.El +.Sh ERRORS +Netlink reports operation results, including errors and error metadata, by +sending a +.Dv NLMSG_ERROR +message for each request message. +The following errors can be returned: +.Bl -tag -width Er +.It Bq Er EPERM +when the current privileges are insufficient to perform the required operation; +.It Bo Er ENOBUFS Bc or Bo Er ENOMEM Bc +when the system runs out of memory for +an internal data structure; +.It Bq Er ENOTSUP +when the requested command is not supported by the family or +the family is not supported; +.It Bq Er EINVAL +when some necessary TLVs are missing or invalid, detailed info +may be provided in NLMSGERR_ATTR_MSG and NLMSGERR_ATTR_OFFS TLVs; +.It Bq Er ENOENT +when trying to delete a non-existent object. +.Pp +Additionally, a socket operation itself may fail with one of the errors +specified in +.Xr socket 2 +, +.Xr recv 2 +or +.Xr send 2 +. +.El +.Sh SEE ALSO +.Xr genetrlink 4 , +.Xr rtnetlink 4 +.Rs +.%A "J. Salim" +.%A "H. Khosravi" +.%A "A. Kleen" +.%A "A. Kuznetsov" +.%T "Linux Netlink as an IP Services Protocol" +.%O "RFC 3549" +.Re +.Sh HISTORY +The netlink protocol appeared in +.Fx 14.0 . +.Sh AUTHORS +The netlink was implemented by +.An -nosplit +.An Alexander Chernikov Aq Mt melifaro@FreeBSD.org . +It was derived from the Google Summer of Code 2021 project by +.An Ng Peng Nam Sean . diff --git a/share/man/man4/pci.4 b/share/man/man4/pci.4 index 3c2c08afe466..f7535aa86d12 100644 --- a/share/man/man4/pci.4 +++ b/share/man/man4/pci.4 @@ -24,7 +24,7 @@ .\" .\" $FreeBSD$ .\" -.Dd August 13, 2021 +.Dd October 4, 2022 .Dt PCI 4 .Os .Sh NAME @@ -572,6 +572,8 @@ MSI interrupts can be disabled by setting this tunable to 0. Enable support for extended Message Signalled Interrupts .Pq MSI-X . MSI-X interrupts can be disabled by setting this tunable to 0. +.It Va hw.pci.enable_pcie_ei Pq Defaults to 0 +Enable support for PCI-express Electromechanical Interlock. .It Va hw.pci.enable_pcie_hp Pq Defaults to 1 Enable support for native PCI-express HotPlug. .It Va hw.pci.honor_msi_blacklist Pq Defaults to 1 diff --git a/share/man/man4/re.4 b/share/man/man4/re.4 index 9b54c0c1f20b..234698089fcb 100644 --- a/share/man/man4/re.4 +++ b/share/man/man4/re.4 @@ -30,7 +30,7 @@ .\" .\" $FreeBSD$ .\" -.Dd September 21, 2016 +.Dd November 7, 2022 .Dt RE 4 .Os .Sh NAME @@ -285,3 +285,6 @@ avoid this problem. .Pp The RealTek 8169, 8169S and 8110S chips appear to only be capable of transmitting jumbo frames up to 7.5K in size. +.Pp +If this driver is causing problems then an updated driver from +the vendor can be found in ports under net/realtek-re-kmod. diff --git a/share/man/man4/rtnetlink.4 b/share/man/man4/rtnetlink.4 new file mode 100644 index 000000000000..9f20671719f0 --- /dev/null +++ b/share/man/man4/rtnetlink.4 @@ -0,0 +1,519 @@ +.\" +.\" Copyright (C) 2022 Alexander Chernikov <melifaro@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, 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 November 1, 2022 +.Dt RTNETLINK 4 +.Os +.Sh NAME +.Nm RTNetlink +.Nd Network configuration-specific Netlink family +.Sh SYNOPSIS +.In netlink/netlink.h +.In netlink/netlink_route.h +.Ft int +.Fn socket AF_NETLINK SOCK_DGRAM NETLINK_ROUTE +.Sh DESCRIPTION +The +.Dv NETLINK_ROUTE +family aims to be the primary configuration mechanism for all +network-related tasks. +Currently it supports configuring interfaces, interface addresses, routes, +nexthops and arp/ndp neighbors. +.Sh ROUTES +All route configuration messages share the common header: +.Bd -literal +struct rtmsg { + unsigned char rtm_family; /* address family */ + unsigned char rtm_dst_len; /* Prefix length */ + unsigned char rtm_src_len; /* Deprecated, set to 0 */ + unsigned char rtm_tos; /* Type of service (not used) */ + unsigned char rtm_table; /* deprecated, set to 0 */ + unsigned char rtm_protocol; /* Routing protocol id (RTPROT_) */ + unsigned char rtm_scope; /* Route distance (RT_SCOPE_) */ + unsigned char rtm_type; /* Route type (RTN_) */ + unsigned rtm_flags; /* Route flags (not supported) */ +}; +.Ed +.Pp +The +.Va rtm_family +specifies the route family to be operated on. +Currently, +.Dv AF_INET6 +and +.Dv AF_INET +are the only supported families. +The route prefix length is stored in +.Va rtm_dst_len +. +The caller should set the originator identity (one of the +.Dv RTPROT_ +values) in +.Va rtm_protocol +. +It is useful for users and for the application itself, allowing for easy +identification of self-originated routes. +The route scope has to be set via +.Va rtm_scope +field. +The supported values are: +.Bd -literal -offset indent -compact +RT_SCOPE_UNIVERSE Global scope +RT_SCOPE_LINK Link scope +.Ed +.Pp +Route type needs to be set. +The defined values are: +.Bd -literal -offset indent -compact +RTN_UNICAST Unicast route +RTN_MULTICAST Multicast route +RTN_BLACKHOLE Drops traffic towards destination +RTN_PROHIBIT Drops traffic and sends reject +.Ed +.Pp +The following messages are supported: +.Ss RTM_NEWROUTE +Adds a new route. +All NL flags are supported. +Extending a multipath route requires NLM_F_APPEND flag. +.Ss RTM_DELROUTE +Tries to delete a route. +The route is specified using a combination of +.Dv RTA_DST +TLV and +.Va rtm_dst_len . +.Ss RTM_GETROUTE +Fetches a single route or all routes in the current VNET, depending on the +.Dv NLM_F_DUMP +flag. +Each route is reported as +.Dv RTM_NEWROUTE +message. +The following filters are recognised by the kernel: +.Pp +.Bd -literal -offset indent -compact +rtm_family required family or AF_UNSPEC +RTA_TABLE fib number or RT_TABLE_UNSPEC to return all fibs +.Ed +.Ss TLVs +.Bl -tag -width indent +.It Dv RTA_DST +(binary) IPv4/IPv6 address, depending on the +.Va rtm_family . +.It Dv RTA_OIF +(uint32_t) transmit interface index. +.It Dv RTA_GATEWAY +(binary) IPv4/IPv6 gateway address, depending on the +.Va rtm_family . +.It Dv RTA_METRICS +(nested) Container attribute, listing route properties. +The only supported sub-attribute is +.Dv RTAX_MTU , which stores path MTU as uint32_t. +.It Dv RTA_MULTIPATH +This attribute contains multipath route nexthops with their weights. +These nexthops are represented as a sequence of +.Va rtnexthop +structures, each followed by +.Dv RTA_GATEWAY +or +.Dv RTA_VIA +attributes. +.Bd -literal +struct rtnexthop { + unsigned short rtnh_len; + unsigned char rtnh_flags; + unsigned char rtnh_hops; /* nexthop weight */ + int rtnh_ifindex; +}; +.Ed +.Pp +The +.Va rtnh_len +field specifies the total nexthop info length, including both +.Va struct rtnexthop +and the following TLVs. +The +.Va rtnh_hops +field stores relative nexthop weight, used for load balancing between group +members. +The +.Va rtnh_ifindex +field contains the index of the transmit interface. +.Pp +The following TLVs can follow the structure: +.Bd -literal -offset indent -compact +RTA_GATEWAY IPv4/IPv6 nexthop address of the gateway +RTA_VIA IPv6 nexthop address for IPv4 route +RTA_KNH_ID Kernel-specific index of the nexthop +.Ed +.It Dv RTA_KNH_ID +(uint32_t) (FreeBSD-specific) Auto-allocated kernel index of the nexthop. +.It Dv RTA_RTFLAGS +(uint32_t) (FreeBSD-specific) rtsock route flags. +.It Dv RTA_TABLE +(uint32_t) Fib number of the route. +Default route table is +.Dv RT_TABLE_MAIN . +To explicitely specify "all tables" one needs to set the value to +.Dv RT_TABLE_UNSPEC . +.It Dv RTA_EXPIRES +(uint32_t) seconds till path expiration. +.It Dv RTA_NH_ID +(uint32_t) useland nexthop or nexthop group index. +.El +.Ss Groups +The following groups are defined: +.Bd -literal -offset indent -compact +RTNLGRP_IPV4_ROUTE Notifies on IPv4 route arrival/removal/change +RTNLGRP_IPV6_ROUTE Notifies on IPv6 route arrival/removal/change +.Ed +.Sh NEXTHOPS +All nexthop/nexthop group configuration messages share the common header: +.Bd -literal +struct nhmsg { + unsigned char nh_family; /* transport family */ + unsigned char nh_scope; /* ignored on RX, filled by kernel */ + unsigned char nh_protocol; /* Routing protocol that installed nh */ + unsigned char resvd; + unsigned int nh_flags; /* RTNH_F_* flags from route.h */ +}; +.Ed +The +.Va nh_family +specificies the gateway address family. +It can be different from route address family for IPv4 routes with IPv6 +nexthops. +The +.Va nh_protocol +is similar to +.Va rtm_protocol +field, which designates originator application identity. +.Pp +The following messages are supported: +.Ss RTM_NEWNEXTHOP +Creates a new nexthop or nexthop group. +.Ss RTM_DELNEXTHOP +Deletes nexthop or nexthhop group. +The required object is specified by the +.Dv RTA_NH_ID +attribute. +.Ss RTM_GETNEXTHOP +Fetches a single nexthop or all nexthops/nexthop groups, depending on the +.Dv NLM_F_DUMP +flag. +The following filters are recognised by the kernel: +.Pp +.Bd -literal -offset indent -compact +RTA_NH_ID nexthop or nexthtop group id +NHA_GROUPS match only nexthtop groups +.Ed +.Ss TLVs +.Bl -tag -width indent +.It Dv RTA_NH_ID +(uint32_t) Nexthhop index used to identify particular nexthop or nexthop group. +Should be provided by userland at the nexthtop creation time. +.It Dv NHA_GROUP +This attribute designates the nexthtop group and contains all of its nexthtops +and their relative weights. +The attribute constists of a list of +.Va nexthop_grp +structures: +.Bd -literal +struct nexthop_grp { + uint32_t id; /* nexhop userland index */ + uint8_t weight; /* weight of this nexthop */ + uint8_t resvd1; + uint16_t resvd2; +}; +.Ed +.It Dv NHA_GROUP_TYPE +(uint16_t) Nexthtop group type, set to one of the following types: +.Bd -literal -offset indent -compact +NEXTHOP_GRP_TYPE_MPATH default multipath group +.Ed +.It Dv NHA_BLACKHOLE +(flag) Marks the nexthtop as blackhole. +.It Dv NHA_OIF +(uint32_t) Transmit interface index of the nexthtop. +.It Dv NHA_GATEWAY +(binary) IPv4/IPv6 gateway address +.It Dv NHA_GROUPS +(flag) Matches nexthtop groups during dump. +.El +.Ss Groups +The following groups are defined: +.Bd -literal -offset indent -compact +RTNLGRP_NEXTHOP Notifies on nexthop/groups arrival/removal/change +.Ed +.Sh INTERFACES +All interface configuration messages share the common header: +.Bd -literal +struct ifinfomsg { + unsigned char ifi_family; /* not used, set to 0 */ + unsigned char __ifi_pad; + unsigned short ifi_type; /* ARPHRD_* */ + int ifi_index; /* Inteface index */ + unsigned ifi_flags; /* IFF_* flags */ + unsigned ifi_change; /* IFF_* change mask */ +}; +.Ed +.Ss RTM_NEWLINK +Creates a new interface. +The only mandatory TLV is +.Dv IFLA_IFNAME . +.Ss RTM_DELLINK +Deletes the interface specified by +.Dv IFLA_IFNAME . +.Ss RTM_GETLINK +Fetches a single interface or all interfaces in the current VNET, depending on the +.Dv NLM_F_DUMP +flag. +Each interface is reported as a +.Dv RTM_NEWLINK +message. +The following filters are recognised by the kernel: +.Pp +.Bd -literal -offset indent -compact +ifi_index interface index +IFLA_IFNAME interface name +IFLA_ALT_IFNAME interface name +.Ed +.Ss TLVs +.Bl -tag -width indent +.It Dv IFLA_ADDRESS +(binary) Llink-level interface address (MAC). +.It Dv IFLA_BROADCAST +(binary) (readonly) Link-level broadcast address. +.It Dv IFLA_IFNAME +(string) New interface name. +.It Dv IFLA_LINK +(uint32_t) (readonly) Interface index. +.It Dv IFLA_MASTER +(uint32_t) Parent interface index. +.It Dv IFLA_LINKINFO +(nested) Interface type-specific attributes: +.Bd -literal -offset indent -compact +IFLA_INFO_KIND (string) interface type ("vlan") +IFLA_INFO_DATA (nested) custom attributes +.Ed +The following types and attributes are supported: +.Bl -tag -width indent +.It Dv vlan +.Bd -literal -offset indent -compact +IFLA_VLAN_ID (uint16_t) 802.1Q vlan id +IFLA_VLAN_PROTOCOL (uint16_t) Protocol: ETHERTYPE_VLAN or ETHERTYPE_QINQ +.Ed +.El +.It Dv IFLA_OPERSTATE +(uint8_t) Interface operational state per RFC 2863. +Can be one of the following: +.Bd -literal -offset indent -compact +IF_OPER_UNKNOWN status can not be determined +IF_OPER_NOTPRESENT some (hardware) component not present +IF_OPER_DOWN down +IF_OPER_LOWERLAYERDOWN some lower-level interface is down +IF_OPER_TESTING in some test mode +IF_OPER_DORMANT "up" but waiting for some condition (802.1X) +IF_OPER_UP ready to pass packets +.Ed +.It Dv IFLA_STATS64 +(readonly) Consists of the following 64-bit counters structure: +.Bd -literal +struct rtnl_link_stats64 { + uint64_t rx_packets; /* total RX packets (IFCOUNTER_IPACKETS) */ + uint64_t tx_packets; /* total TX packets (IFCOUNTER_OPACKETS) */ + uint64_t rx_bytes; /* total RX bytes (IFCOUNTER_IBYTES) */ + uint64_t tx_bytes; /* total TX bytes (IFCOUNTER_OBYTES) */ + uint64_t rx_errors; /* RX errors (IFCOUNTER_IERRORS) */ + uint64_t tx_errors; /* RX errors (IFCOUNTER_OERRORS) */ + uint64_t rx_dropped; /* RX drop (no space in ring/no bufs) (IFCOUNTER_IQDROPS) */ + uint64_t tx_dropped; /* TX drop (IFCOUNTER_OQDROPS) */ + uint64_t multicast; /* RX multicast packets (IFCOUNTER_IMCASTS) */ + uint64_t collisions; /* not supported */ + uint64_t rx_length_errors; /* not supported */ + uint64_t rx_over_errors; /* not supported */ + uint64_t rx_crc_errors; /* not supported */ + uint64_t rx_frame_errors; /* not supported */ + uint64_t rx_fifo_errors; /* not supported */ + uint64_t rx_missed_errors; /* not supported */ + uint64_t tx_aborted_errors; /* not supported */ + uint64_t tx_carrier_errors; /* not supported */ + uint64_t tx_fifo_errors; /* not supported */ + uint64_t tx_heartbeat_errors; /* not supported */ + uint64_t tx_window_errors; /* not supported */ + uint64_t rx_compressed; /* not supported */ + uint64_t tx_compressed; /* not supported */ + uint64_t rx_nohandler; /* dropped due to no proto handler (IFCOUNTER_NOPROTO) */ +}; +.Ed +.El +.Ss Groups +The following groups are defined: +.Bd -literal -offset indent -compact +RTNLGRP_LINK Notifies on interface arrival/removal/change +.Ed +.Sh INTERFACE ADDRESSES +All interface address configuration messages share the common header: +.Bd -literal +struct ifaddrmsg { + uint8_t ifa_family; /* Address family */ + uint8_t ifa_prefixlen; /* Prefix length */ + uint8_t ifa_flags; /* Address-specific flags */ + uint8_t ifa_scope; /* Address scope */ + uint32_t ifa_index; /* Link ifindex */ +}; +.Ed +.Pp +The +.Va ifa_family +specifies the address family of the interface address. +The +.Va ifa_prefixlen +specifies the prefix length if applicable for the address family. +The +.Va ifa_index +specifies the interface index of the target interface. +.Ss RTM_NEWADDR +Not supported +.Ss RTM_DELADDR +Not supported +.Ss RTM_GETADDR +.Ss TLVs +.Bl -tag -width indent +.It Dv IFA_ADDRESS +(binary) masked interface address or destination address for p2p interfaces. +.It Dv IFA_LOCAL +(binary) local interface address +.It Dv IFA_BROADCAST +(binary) broacast interface address +.El +.Ss Groups +The following groups are defined: +.Bd -literal -offset indent -compact +RTNLGRP_IPV4_IFADDR Notifies on IPv4 ifaddr arrival/removal/change +RTNLGRP_IPV6_IFADDR Notifies on IPv6 ifaddr arrival/removal/change +.Ed +.Sh NEIGHBORS +All neighbor configuration messages share the common header: +.Bd -literal +struct ndmsg { + uint8_t ndm_family; + uint8_t ndm_pad1; + uint16_t ndm_pad2; + int32_t ndm_ifindex; + uint16_t ndm_state; + uint8_t ndm_flags; + uint8_t ndm_type; +}; +.Ed +.Pp +The +.Va ndm_family +field specifies the address family (IPv4 or IPv6) of the neighbor. +The +.Va ndm_ifindex +specifies the interface to operate on. +The +.Va ndm_state +represents the entry state according to the neighbor model. +The state can be one of the following: +.Bd -literal -offset indent -compact +NUD_INCOMPLETE No lladdr, address resolution in progress +NUD_REACHABLE reachable & recently resolved +NUD_STALE has lladdr but it's stale +NUD_DELAY has lladdr, is stale, probes delayed +NUD_PROBE has lladdr, is stale, probes sent +NUD_FAILED unused +.Ed +.Pp +The +.Va ndm_flags +field stores the options specific to this entry. +Available flags: +.Bd -literal -offset indent -compact +NTF_SELF local station (LLE_IFADDR) +NTF_PROXY proxy entry (LLE_PUB) +NTF_STICKY permament entry (LLE_STATIC) +NTF_ROUTER dst indicated itself as a router +.Ed +.Ss RTM_NEWNEIGH +Creates new neighbor entry. +The mandatory options are +.Dv NDA_DST , +.Dv NDA_LLADDR +and +.Dv NDA_IFINDEX . +.Ss RTM_DELNEIGH +Deletes the neighbor entry. +The entry is specified by the combination of +.Dv NDA_DST +and +.Dv NDA_IFINDEX . +.Ss RTM_GETNEIGH +Fetches a single neighbor or all neighbors in the current VNET, depending on the +.Dv NLM_F_DUMP +flag. +Each entry is reported as +.Dv RTM_NEWNEIGH +message. +The following filters are recognised by the kernel: +.Pp +.Bd -literal -offset indent -compact +ndm_family required family or AF_UNSPEC +ndm_ifindex target ifindex +NDA_IFINDEX target ifindex +.Ed +.Ss TLVs +.Bl -tag -width indent +.It Dv NDA_DST +(binary) neighbor IPv4/IPv6 address. +.It Dv NDA_LLADDR +(binary) neighbor link-level address. +.It Dv NDA_IFINDEX +(uint32_t) interface index. +.It Dv NDA_FLAGS_EXT +(uint32_t) extended version of +.Va ndm_flags . +.El +.Ss Groups +The following groups are defined: +.Bd -literal -offset indent -compact +RTNLGRP_NEIGH Notifies on ARP/NDP neighbor arrival/removal/change +.Ed +.Sh SEE ALSO +.Xr netlink 4 , +.Xr route 4 +.Sh HISTORY +The +.Dv NETLINK_ROUTE +protocol family appeared in +.Fx 14.0 . +.Sh AUTHORS +The netlink was implementated by +.An -nosplit +.An Alexander Chernikov Aq Mt melifaro@FreeBSD.org . +It was derived from the Google Summer of Code 2021 project by +.An Ng Peng Nam Sean . diff --git a/share/man/man4/run.4 b/share/man/man4/run.4 index d27bca4b10b4..222f7c843e4b 100644 --- a/share/man/man4/run.4 +++ b/share/man/man4/run.4 @@ -211,7 +211,7 @@ ifconfig wlan create wlandev run0 wlanmode adhoc ssid my_net \e .Ed .Sh DIAGNOSTICS .Bl -diag -.It "run%d: faild load firmware of file runfw" +.It "run%d: failed load firmware of file runfw" For some reason, the driver was unable to read the microcode file from the filesystem. The file might be missing or corrupted. diff --git a/share/man/man4/snp.4 b/share/man/man4/snp.4 index ce0ef66c5721..3422b9ca5d6f 100644 --- a/share/man/man4/snp.4 +++ b/share/man/man4/snp.4 @@ -1,7 +1,7 @@ .\" .\" $FreeBSD$ .\" -.Dd November 5, 2008 +.Dd September 24, 2022 .Dt SNP 4 .Os .Sh NAME @@ -58,8 +58,6 @@ ioctl returns a positive value equal to the number of characters in a read buffer. Special values defined are: .Bl -tag -width ".Dv SNP_TTYCLOSE" -.It Dv SNP_OFLOW -device overflow occurred, device detached. .It Dv SNP_TTYCLOSE tty not attached. .It Dv SNP_DETACH @@ -89,11 +87,3 @@ Previous versions of .Nm were based on code written by .An Ugen J.S. Antsilevich Aq Mt ugen@NetVision.net.il . -.Sh BUGS -This version of -.Nm -does not return proper error codes when calling -.Dv FIONREAD . -It also does not allow -.Dv SNPSTTY -to detach itself from the TTY. diff --git a/share/man/man4/tcp.4 b/share/man/man4/tcp.4 index cdb58c7cbacc..dea7da9054d0 100644 --- a/share/man/man4/tcp.4 +++ b/share/man/man4/tcp.4 @@ -34,7 +34,7 @@ .\" From: @(#)tcp.4 8.1 (Berkeley) 6/5/93 .\" $FreeBSD$ .\" -.Dd August 1, 2022 +.Dd November 7, 2022 .Dt TCP 4 .Os .Sh NAME @@ -282,6 +282,7 @@ this packetization may cause significant delays. The boolean option .Dv TCP_NODELAY defeats this algorithm. + .It Dv TCP_MAXSEG By default, a sender- and .No receiver- Ns Tn TCP @@ -291,6 +292,17 @@ The .Dv TCP_MAXSEG option allows the user to determine the result of this negotiation, and to reduce it if desired. +.It Dv TCP_MAXUNACKTIME +This +.Xr setsockopt 2 +option accepts an argument of +.Vt "u_int" +to set the per-socket interval, in seconds, in which the connection must +make progress. Progress is defined by at least 1 byte being acknowledged within +the set time period. If a connection fails to make progress, then the +.Tn TCP +stack will terminate the connection with a reset. Note that the default +value for this is zero which indicates no progress checks should be made. .It Dv TCP_NOOPT .Tn TCP usually sends a number of options in each packet, corresponding to @@ -495,6 +507,13 @@ Outgoing connections will request ECN. Allow incoming connections to request ECN. Outgoing connections will not request ECN. (default) +.It 3 +Negotiate on incoming connection for Accurate ECN, ECN, or no ECN. +Outgoing connections will request Accurate ECN and fall back to +ECN depending on the capabilities of the server. +.It 4 +Negotiate on incoming connection for Accurate ECN, ECN, or no ECN. +Outgoing connections will not request ECN. .El .It Va ecn.maxretries Number of retries (SYN or SYN/ACK retransmits) before disabling ECN on a @@ -734,23 +753,6 @@ A value of 2 results in any packets to closed ports being logged. Any value not listed above disables the logging (default is 0, i.e., the logging is disabled). -.It Va maxtcptw -When a TCP connection enters the -.Dv TIME_WAIT -state, its associated socket structure is freed, since it is of -negligible size and use, and a new structure is allocated to contain a -minimal amount of information necessary for sustaining a connection in -this state, called the compressed TCP -.Dv TIME_WAIT -state. -Since this structure is smaller than a socket structure, it can save -a significant amount of system memory. -The -.Va net.inet.tcp.maxtcptw -MIB variable controls the maximum number of these structures allocated. -By default, it is initialized to -.Va kern.ipc.maxsockets -/ 5. .It Va minmss Minimum TCP Maximum Segment Size; used to prevent a denial of service attack from an unreasonably low MSS. @@ -767,7 +769,7 @@ application limited and the network bandwidth is not utilized completely. That prevents self-inflicted packet losses once the application starts to transmit data at a higher speed. .It Va nolocaltimewait -Suppress creation of compressed TCP +Suppress creation of TCP .Dv TIME_WAIT states for connections in which both endpoints are local. @@ -873,7 +875,18 @@ minimum, which gives us an effective minimum of 200ms (similar to The initial value is used before an RTT measurement has been performed. .It Va rfc1323 Implement the window scaling and timestamp options of RFC 1323/RFC 7323 -(default is true). +(default is 1). +Settings: +.Bl -tag -compact +.It 0 +Disable window scaling and timestamp option. +.It 1 +Enable window scaling and timestamp option. +.It 2 +Enable only window scaling. +.It 3 +Enable only timestamp option. +.El .It Va rfc3042 Enable the Limited Transmit algorithm as described in RFC 3042. It helps avoid timeouts on lossy links and also when the congestion window @@ -1041,6 +1054,7 @@ when trying to use a TCP function block that is not available; .Xr siftr 4 , .Xr syncache 4 , .Xr tcp_bbr 4 , +.Xr tcp_rack 4 , .Xr setkey 8 , .Xr sysctl 8 , .Xr tcp_functions 9 diff --git a/share/man/man4/tcp_bbr.4 b/share/man/man4/tcp_bbr.4 index 604e205820fb..48281ad0164f 100644 --- a/share/man/man4/tcp_bbr.4 +++ b/share/man/man4/tcp_bbr.4 @@ -1,5 +1,5 @@ .\" -.\" Copyright (c) 2020, Gordon Bergling +.\" Copyright (c) 2020, Gordon Bergling <gbe@FreeBSD.org> .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions @@ -24,7 +24,7 @@ .\" .\" $FreeBSD$ .\" -.Dd September 24, 2020 +.Dd November 7, 2022 .Dt TCP_BBR 4 .Os .Sh NAME @@ -129,6 +129,7 @@ Minimum RTO in ms. .Xr h_ertt 4 , .Xr mod_cc 4 , .Xr tcp 4 , +.Xr tcp_rack 4 , .Xr mod_cc 9 .Rs .%A "Neal Cardwell" diff --git a/share/man/man4/tcp_rack.4 b/share/man/man4/tcp_rack.4 new file mode 100644 index 000000000000..ce424ae73045 --- /dev/null +++ b/share/man/man4/tcp_rack.4 @@ -0,0 +1,159 @@ +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2022, Gordon Bergling <gbe@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, 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. +.\" +.Dd November 7, 2022 +.Dt TCP_RACK 4 +.Os +.Sh NAME +.Nm tcp_rack +.Nd TCP RACK-TLP Loss Detection Algorithm for TCP +.Sh SYNOPSIS +To use this TCP stack, place the following line in the +kernel configuration file: +.Bd -ragged -offset indent +.Cd "options TCPHPTS" +.Ed +.Pp +To load the TCP stack as a module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +tcp_rack_load="YES" +.Ed +.Pp +To enable the TCP stack, place the following line in the +.Xr sysctl.conf 5 : +.Bd -literal -offset indent +net.inet.tcp.functions_default=rack +.Ed +.Sh DESCRIPTION +RACK-TLP uses per-segment transmit timestamps and selective +acknowledgments (SACKs) and has two parts. +Recent Acknowledgment (RACK) starts fast recovery quickly +using time-based inferences derived from acknowledgment (ACK) +feedback, and Tail Loss Probe (TLP) leverages RACK +and sends a probe packet to trigger ACK feedback to avoid +retransmission timeout (RTO) events. +.Pp +Compared to the widely used duplicate acknowledgment (DupAck) +threshold approach, RACK-TLP detects losses more efficiently +when there are application-limited flights of data, lost +retransmissions, or data packet reordering events. +.Pp +It is intended to be an alternative to the +DupAck threshold approach. +.Sh MIB Variables +The algorithm exposes the following scopes in the +.Va net.inet.tcp.rack +branch of the +.Xr sysctl 3 +MIB: +.Bl -tag -width indent +.It Va net.inet.tcp.rack.misc +Misc related controls +.It Va net.inet.tcp.rack.features +Feature controls +.It Va net.inet.tcp.rack.measure +Measure related controls +.It Va net.inet.tcp.rack.timers +Timer related controls +.It Va net.inet.tcp.rack.tlp +TLP and Rack related Controls +.It Va net.inet.tcp.rack.timely +Rack Timely RTT Controls +.It Va net.inet.tcp.rack.hdwr_pacing +Pacing related Controls +.It Va net.inet.tcp.rack.pacing +Pacing related Controls +.It Va net.inet.tcp.rack.tp +Rack tracepoint facility +.It Va net.inet.tcp.rack.probertt +ProbeRTT related Controls +.It Va net.inet.tcp.rack.stats +Rack Counters +.It Va net.inet.tcp.rack.sack_attack +Rack Sack Attack Counters and Controls +.El +.Pp +Besides the variables within the above scopes the following +variables are also exposed in the +.Va net.inet.tcp.rack +branch: +.Bl -tag -width indent +.It Va net.inet.tcp.rack.clear +Clear counters +.It Va net.inet.tcp.rack.opts +RACK Option Stats +.It Va net.inet.tcp.rack.outsize +MSS send sizes +.It Va net.inet.tcp.rack.req_measure_cnt +If doing dynamic pacing, how many measurements +must be in before we start pacing? +.It Va net.inet.tcp.rack.use_pacing +If set we use pacing, if clear we use only the original burst mitigation +.It Va net.inet.tcp.rack.rate_sample_method +What method should we use for rate sampling 0=high, 1=low +.El +.Sh SEE ALSO +.Xr cc_chd 4 , +.Xr cc_cubic 4 , +.Xr cc_hd 4 , +.Xr cc_htcp 4 , +.Xr cc_newreno 4 , +.Xr cc_vegas 4 , +.Xr h_ertt 4 , +.Xr mod_cc 4 , +.Xr tcp 4 , +.Xr tcp_bbr 4 , +.Xr mod_cc 9 +.Rs +.%A "Neal Cardwell" +.%A "Yuchung Cheng" +.%A "Nandita Dukkipat" +.%A "Priyaranjan Jha" +.%T "The RACK-TLP Loss Detection Algorithm for TCP" +.%O "RFC 8985" +.%D "February 2021" +.Re +.Rs +.%A "Ahmed M. Abdelmoniem" +.%A "Brahim Bensaou" +.%T "T-RACKs: A Faster Recovery Mechanism for TCP in Data Center Networks" +.%O "https://arxiv.org/pdf/2102.07477.pdf" +.%D "February 2021" +.Re +.Sh HISTORY +The +.Nm +congestion control module first appeared in +.Fx 13.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +congestion control module was written by +.An Randall Stewart Aq Mt rrs@FreeBSD.org +and sponsored by Netflix, Inc. +This manual page was written by +.An Gordon Bergling Aq Mt gbe@FreeBSD.org . diff --git a/share/man/man4/ti.4 b/share/man/man4/ti.4 index a589ec048ebf..3209d9a0359f 100644 --- a/share/man/man4/ti.4 +++ b/share/man/man4/ti.4 @@ -299,7 +299,7 @@ driver also includes a character device interface that can be used for additional diagnostics, configuration and debugging. With this character device interface, and a specially patched version of -.Xr gdb 1 , +.Xr gdb 1 Pq Pa ports/devel/gdb , the user can debug firmware running on the Tigon board. .Pp diff --git a/share/man/man4/vmd.4 b/share/man/man4/vmd.4 index 74419fd87ffe..6c49e2b83ec0 100644 --- a/share/man/man4/vmd.4 +++ b/share/man/man4/vmd.4 @@ -27,7 +27,7 @@ .\" .\" $FreeBSD$ .\" -.Dd August 31, 2021 +.Dd October 6, 2022 .Dt VMD 4 .Os .Sh NAME @@ -57,6 +57,11 @@ The following tunables are settable via or .Xr sysctl 8 : .Bl -tag -width indent +.It Va hw.vmd.bypass_msi +By default all VMD devices remap children MSI/MSI-X interrupts into their +own. It creates additional isolation, but also complicates things due to +sharing, etc. Fortunately some VMD devices can bypass the remapping. +Defaults to 1. .It Va hw.vmd.max_msi Limits number of Message Signaled Interrupt (MSI) vectors allowed to each child device. diff --git a/share/man/man4/wg.4 b/share/man/man4/wg.4 new file mode 100644 index 000000000000..6d0d16d942df --- /dev/null +++ b/share/man/man4/wg.4 @@ -0,0 +1,218 @@ +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2020 Gordon Bergling <gbe@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, 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 November 11, 2022 +.Dt WG 4 +.Os +.Sh NAME +.Nm wg +.Nd "WireGuard protocol driver" +.Sh SYNOPSIS +To load the driver as a module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_wg_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides Virtual Private Network (VPN) interfaces for the secure +exchange of layer 3 traffic with other WireGuard peers using the WireGuard +protocol. +.Pp +A +.Nm +interface recognizes one or more peers, establishes a secure tunnel with +each on demand, and tracks each peer's UDP endpoint for exchanging encrypted +traffic with. +.Pp +The interfaces can be created at runtime using the +.Ic ifconfig Cm wg Ns Ar N Cm create +command. +The interface itself can be configured with +.Xr wg 8 . +.Pp +The following glossary provides a brief overview of WireGuard +terminology: +.Bl -tag -width indent -offset 3n +.It Peer +Peers exchange IPv4 or IPv6 traffic over secure tunnels. +Each +.Nm +interface may be configured to recognise one or more peers. +.It Key +Each peer uses its private key and corresponding public key to +identify itself to others. +A peer configures a +.Nm +interface with its own private key and with the public keys of its peers. +.It Pre-shared key +In addition to the public keys, each peer pair may be configured with a +unique pre-shared symmetric key. +This is used in their handshake to guard against future compromise of the +peers' encrypted tunnel if an attack on their +Diffie-Hellman exchange becomes feasible. +It is optional, but recommended. +.It Allowed IP addresses +A single +.Nm +interface may maintain concurrent tunnels connecting diverse networks. +The interface therefore implements rudimentary routing and reverse-path +filtering functions for its tunneled traffic. +These functions reference a set of allowed IP address ranges configured +against each peer. +.Pp +The interface will route outbound tunneled traffic to the peer configured +with the most specific matching allowed IP address range, or drop it +if no such match exists. +.Pp +The interface will accept tunneled traffic only from the peer +configured with the most specific matching allowed IP address range +for the incoming traffic, or drop it if no such match exists. +That is, tunneled traffic routed to a given peer cannot return through +another peer of the same +.Nm +interface. +This ensures that peers cannot spoof one another's traffic. +.It Handshake +Two peers handshake to mutually authenticate each other and to +establish a shared series of secret ephemeral encryption keys. +Either peer may initiate a handshake. +Handshakes occur only when there is traffic to send, and recur every +two minutes during transfers. +.It Connectionless +Due to the handshake behavior, there is no connected or disconnected +state. +.El +.Ss Keys +Private keys for WireGuard can be generated from any sufficiently +secure random source. +The Curve25519 keys and the pre-shared keys are both 32 bytes +long and are commonly encoded in base64 for ease of use. +.Pp +Keys can be generated with +.Xr wg 8 +as follows: +.Pp +.Dl $ wg genkey +.Pp +Although a valid Curve25519 key must have 5 bits set to +specific values, this is done by the interface and so it +will accept any random 32-byte base64 string. +.Sh EXAMPLES +Create a +.Nm +interface and set random private key. +.Bd -literal -offset indent +# ifconfig wg0 create +# wg genkey | wg set wg0 listen-port 54321 private-key /dev/stdin +.Ed +.Pp +Retrieve the associated public key from a +.Nm +interface. +.Bd -literal -offset indent +$ wg show wg0 public-key +.Ed +.Pp +Connect to a specific endpoint using its public-key and set the allowed IP address +.Bd -literal -offset indent +# wg set wg0 peer '7lWtsDdqaGB3EY9WNxRN3hVaHMtu1zXw71+bOjNOVUw=' endpoint 10.0.1.100:54321 allowed-ips 192.168.2.100/32 +.Ed +.Pp +Remove a peer +.Bd -literal -offset indent +# wg set wg0 peer '7lWtsDdqaGB3EY9WNxRN3hVaHMtu1zXw71+bOjNOVUw=' remove +.Ed +.Sh DIAGNOSTICS +The +.Nm +interface supports runtime debugging, which can be enabled with: +.Pp +.D1 Ic ifconfig Cm wg Ns Ar N Cm debug +.Pp +Some common error messages include: +.Bl -diag +.It "Handshake for peer X did not complete after 5 seconds, retrying" +Peer X did not reply to our initiation packet, for example because: +.Bl -bullet +.It +The peer does not have the local interface configured as a peer. +Peers must be able to mutually authenticate each other. +.It +The peer endpoint IP address is incorrectly configured. +.It +There are firewall rules preventing communication between hosts. +.El +.It "Invalid handshake initiation" +The incoming handshake packet could not be processed. +This is likely due to the local interface not containing +the correct public key for the peer. +.It "Invalid initiation MAC" +The incoming handshake initiation packet had an invalid MAC. +This is likely because the initiation sender has the wrong public key +for the handshake receiver. +.It "Packet has unallowed src IP from peer X" +After decryption, an incoming data packet has a source IP address that +is not assigned to the allowed IPs of Peer X. +.El +.Sh SEE ALSO +.Xr inet 4 , +.Xr ip 4 , +.Xr ipsec 4 , +.Xr netintro 4 , +.Xr ovpn 4 , +.Xr ipf 5 , +.Xr pf.conf 5 , +.Xr ifconfig 8 , +.Xr ipfw 8 , +.Xr wg 8 +.Rs +.%T WireGuard whitepaper +.%U https://www.wireguard.com/papers/wireguard.pdf +.Re +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 13.2 . +.Sh AUTHORS +.An -nosplit +The +.Nm +device driver was written by +.An Jason A. Donenfeld Aq Mt Jason@zx2c4.com , +.An Matt Dunwoodie Aq Mt ncon@nconroy.net , +and +.An Kyle Evans Aq Mt kevans@FreeBSD.org . +.Pp +This manual page was written by +.An Gordon Bergling Aq Mt gbe@FreeBSD.org +and is based on the +.Ox +manual page written by +.An David Gwynne Aq Mt dlg@openbsd.org . diff --git a/share/man/man4/xhci.4 b/share/man/man4/xhci.4 index d475c5e502fc..f30795e9cd02 100644 --- a/share/man/man4/xhci.4 +++ b/share/man/man4/xhci.4 @@ -1,5 +1,5 @@ .\" -.\" Copyright (c) 2011 Hans Petter Selasky. All rights reserved. +.\" Copyright (c) 2011-2022 Hans Petter Selasky. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions @@ -24,13 +24,14 @@ .\" .\" $FreeBSD$ .\" -.Dd April 24, 2018 +.Dd October 21, 2022 .Dt XHCI 4 .Os .Sh NAME .Nm xhci .Nd USB eXtensible Host Controller driver .Sh SYNOPSIS +.Cd "options USB_DEBUG" .Cd "device xhci" .Sh DESCRIPTION The @@ -48,7 +49,8 @@ The .Tn XHCI controller supports .Tn USB -connection speeds up to 5.0Gbps when using a USB 3.0 compliant device. +connection speeds from 5.0Gbps and above when using USB 3.x +compliant devices. .Sh HARDWARE The .Nm @@ -64,14 +66,37 @@ variables and tunables: .Bl -tag -width indent .It Va hw.usb.xhci.debug -Debug output level, where 0 is debugging disabled and larger values increase -debug message verbosity. -Default is 0. +Set debug output level, where 0 is debugging disabled and larger +values increase debug message verbosity. +The default value is 0. +.It Va hw.usb.xhci.dcepquirk +Set to enable quirk for deconfiguration of endpoints. +The default value is 0. +.It Va hw.usb.xhci.ctlquirk +Set to submit full USB control request as one job, up to 64kBytes. +Else the USB control request will be split into multiple smaller +requests. +The default value is 1. +.It Va hw.usb.xhci.streams +Set to enable USB streams support. +The default value is 0. +.It Va hw.usb.xhci.route +Set bitmap for switching EHCI ports to the XHCI controller. +The default value is 0. +.It Va hw.usb.xhci.polling +Set to use a timer to poll the interrupt handler. +The default value is 0. +.It Va hw.usb.xhci.dma32 +Set to only use 32-bit DMA for the XHCI controller. +The default value is 0. +.It Va hw.usb.xhci.ctlstep +Set to enable control endpoint status state stepping. +The default value is 0. .El .Sh SEE ALSO .Xr ehci 4 , .Xr ohci 4 , -.Xr uhci 4 , +.Xr uhci 4 and .Xr usb 4 .Sh HISTORY The diff --git a/share/man/man5/Makefile b/share/man/man5/Makefile index 9be4c8dc46b0..2d49d981c2f9 100644 --- a/share/man/man5/Makefile +++ b/share/man/man5/Makefile @@ -32,6 +32,7 @@ MAN= acct.5 \ hosts.lpd.5 \ intro.5 \ libmap.conf.5 \ + lindebugfs.5 \ link.5 \ linprocfs.5 \ linsysfs.5 \ diff --git a/share/man/man5/a.out.5 b/share/man/man5/a.out.5 index aa4c7da96929..606c96a4125a 100644 --- a/share/man/man5/a.out.5 +++ b/share/man/man5/a.out.5 @@ -386,7 +386,7 @@ The .Dv N_STAB mask selects bits of interest to symbolic debuggers such as -.Xr gdb 1 ; +.Xr gdb 1 Pq Pa ports/devel/gdb ; the values are described in .Xr stab 5 . .It Fa n_other @@ -429,7 +429,7 @@ so its minimum value (or the offset of the first string) is always 4 on 32-bit machines. .Sh SEE ALSO .Xr as 1 , -.Xr gdb 1 , +.Xr gdb 1 Pq Pa ports/devel/gdb , .Xr ld 1 , .Xr brk 2 , .Xr execve 2 , diff --git a/share/man/man5/core.5 b/share/man/man5/core.5 index f109b7932308..09dfbc12e8f6 100644 --- a/share/man/man5/core.5 +++ b/share/man/man5/core.5 @@ -177,7 +177,7 @@ command can be used: .Pp .Dl sysctl kern.corefile=/var/coredumps/\&%U/\&%N.core .Sh SEE ALSO -.Xr gdb 1 , +.Xr gdb 1 Pq Pa ports/devel/gdb , .Xr gzip 1 , .Xr kgdb 1 Pq Pa ports/devel/gdb , .Xr setrlimit 2 , diff --git a/share/man/man5/elf.5 b/share/man/man5/elf.5 index 95bc183a1f91..9a004bb3d08a 100644 --- a/share/man/man5/elf.5 +++ b/share/man/man5/elf.5 @@ -1387,7 +1387,7 @@ writeable and executable. .El .Sh SEE ALSO .Xr as 1 , -.Xr gdb 1 , +.Xr gdb 1 Pq Pa ports/devel/gdb , .Xr ld 1 , .Xr objdump 1 , .Xr readelf 1 , diff --git a/share/man/man5/hosts.5 b/share/man/man5/hosts.5 index ca7586f039b7..6bf643f6c5ce 100644 --- a/share/man/man5/hosts.5 +++ b/share/man/man5/hosts.5 @@ -28,7 +28,7 @@ .\" @(#)hosts.5 8.2 (Berkeley) 12/11/93 .\" $FreeBSD$ .\" -.Dd May 25, 2021 +.Dd September 15, 2022 .Dt HOSTS 5 .Os .Sh NAME @@ -87,9 +87,6 @@ file resides in .Xr inet 3 , .Xr nsswitch.conf 5 , .Xr ifconfig 8 -.Rs -.%T "Name Server Operations Guide for BIND" -.Re .Sh HISTORY The .Nm diff --git a/share/man/man5/lindebugfs.5 b/share/man/man5/lindebugfs.5 new file mode 100644 index 000000000000..0d93d6aec6b9 --- /dev/null +++ b/share/man/man5/lindebugfs.5 @@ -0,0 +1,95 @@ +.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD +.\" +.\" Copyright (c) 2022, Jake Freeland <jfree@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, 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. + +.Dd August 10, 2022 +.Dt LINDEBUGFS 5 +.Os +.Sh NAME +.Nm lindebugfs +.Nd Linux file system for debugging +.Sh SYNOPSIS +.Bd -literal +lindebugfs /sys/kernel/debug lindebugfs rw 0 0 +.Ed +.Sh DESCRIPTION +The debug file system, or debugfs, makes process debugging easier by +providing a simple API for data transfer between the kernel and user +space. +Debugfs is not a general-purpose file system and should not be used as +a storage medium. +Instead, developers can implement the debugfs interface in their code +to generate debug information about their program at runtime. +FreeBSD's +.Nm +uses the +.Xr pseudofs 9 +file system construction kit to model itself after Linux's debugfs. +The +.Nm +API is intended for use with programs that take advantage of FreeBSD's +LinuxKPI compatibility layer. +.Pp +When mounted, +.Nm +will populate with pseudo files from any running process that calls +.Nm debugfs_create_file() . +Since +.Nm +is a pseudo file system, file contents will be generated dynamically +based on program provided file operations. +The current +.Nm +implementation formally supports seq_file and simple_attr_file virtual +file formats. +.Sh EXAMPLES +Load the +.Nm +kernel module: +.Pp +.Dl "kldload lindebugfs" +.Pp +Mount the +.Nm +file system on +.Pa /sys/kernel/debug : +.Pp +.Dl "mount -t lindebugfs lindebugfs /sys/kernel/debug" +.Sh SEE ALSO +.Xr linprocfs 5 , +.Xr linsysfs 5 , +.Xr pseudofs 9 , +.Xr linux 4 , +.Xr mount 1 +.Sh HISTORY +The +.Nm +file system first appeared in +.Fx 12.1 . +.Sh AUTHORS +.An -nosplit +The initial implementation for +.Nm +was created by Matthew Macy. +This manual page was written by Jake Freeland. diff --git a/share/man/man5/make.conf.5 b/share/man/man5/make.conf.5 index b3623b29a950..2a29eeb5f5bf 100644 --- a/share/man/man5/make.conf.5 +++ b/share/man/man5/make.conf.5 @@ -24,7 +24,7 @@ .\" .\" $FreeBSD$ .\" -.Dd June 14, 2021 +.Dd November 15, 2022 .Dt MAKE.CONF 5 .Os .Sh NAME @@ -573,11 +573,7 @@ The script used by to start, stop, and restart .Xr sendmail 8 . The default value is -.Pa /etc/rc.sendmail . -This value should match the -.Dq Li mta_start_script -setting in -.Xr rc.conf 5 . +.Pa /etc/rc.d/sendmail . .It Va SENDMAIL_SUBMIT_MC .Pq Vt str The default diff --git a/share/man/man5/pf.conf.5 b/share/man/man5/pf.conf.5 index 267d84387fe9..c7446f53bb49 100644 --- a/share/man/man5/pf.conf.5 +++ b/share/man/man5/pf.conf.5 @@ -28,7 +28,7 @@ .\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" -.Dd March 9, 2022 +.Dd November 24, 2022 .Dt PF.CONF 5 .Os .Sh NAME @@ -710,6 +710,9 @@ see the .Ic group keyword in .Xr ifconfig 8 . +.It Ar bridge-to Aq interface +Packets matching this rule will be sent out of the specified interface without +futher processing. .It Ar proto Aq Ar protocol This rule applies only to packets of this protocol. Note that Ethernet protocol numbers are different from those used in @@ -829,6 +832,9 @@ packet, and only the completed packet is passed on to the filter. The advantage is that filter rules have to deal only with complete packets, and can ignore fragments. The drawback of caching fragments is the additional memory cost. +This is the default behaviour unless no fragment reassemble is specified. +.It Ar no fragment reassemble +Do not reassemble fragments. .It Ar reassemble tcp Statefully normalizes TCP connections. .Ar scrub reassemble tcp @@ -3076,8 +3082,9 @@ option = "set" ( [ "timeout" ( timeout | "{" timeout-list "}" ) ] | [ "keepcounters" ] ) ether-rule = "ether" etheraction [ ( "in" | "out" ) ] - [ "quick" ] [ "on" ifspec ] [ etherprotospec ] - etherhosts [ "l3" hosts ] [ etherfilteropt-list ] + [ "quick" ] [ "on" ifspec ] [ "bridge-to" interface-name ] + [ etherprotospec ] etherhosts [ "l3" hosts ] + [ etherfilteropt-list ] pf-rule = action [ ( "in" | "out" ) ] [ "log" [ "(" logopts ")"] ] [ "quick" ] diff --git a/share/man/man5/rc.conf.5 b/share/man/man5/rc.conf.5 index 473f5b16a30f..e67273cf0ea2 100644 --- a/share/man/man5/rc.conf.5 +++ b/share/man/man5/rc.conf.5 @@ -24,7 +24,7 @@ .\" .\" $FreeBSD$ .\" -.Dd July 7, 2022 +.Dd November 14, 2022 .Dt RC.CONF 5 .Os .Sh NAME @@ -239,6 +239,11 @@ such as PostgreSQL will not inherit the OOM killer protection. .Pp This variable has no effect on services running within a .Xr jail 8 . +.It Ao Ar name Ac Ns Va _umask +.Pq Vt int +Run the service using this +.Xr umask 1 +value. .It Ao Ar name Ac Ns Va _user .Pq Vt str Run the service under this user account. @@ -458,6 +463,34 @@ is mounted on normal systems. Clean the .Pa /var directory. +.It Va var_run_enable +.Pq Vt bool +Set to "YES" to enable saving of the +.Pa /var/run +directory strcucture into an mtree file at shutdown and the reload of the +.Pa /var/run +directory structure at boot. +.It Va var_run_autosave +.Pq Vt bool +In some cases it may be undesirable to save +.Pa /var/run +at shutdown. +When set to "NO" +.Pa /var/run +is loaded at reboot but not saved at shutdown. Typically in this scenario +a +.Pa service +.Pa var_run +.Pa save +would be performed to save a copy of the +.Pa /var/run +directory structure once, to be reload during all subsequent reboots. +.It Va var_run_mtree +.Pq Vt str +Where to save the +.Pa /var/run +mtree. The default location is +.Pa /var/db/mtree/BSD.var-run.mtree . .It Va local_startup .Pq Vt str List of directories to search for startup script files. @@ -2076,6 +2109,13 @@ A space-separated list of ZFS pool names for which new pool GUIDs should be assigned upon first boot. This is useful when using a ZFS pool copied from a template, such as a virtual machine image. +.It Va zpool_upgrade +.Pq Vt str +A space-separated list of ZFS pool names for which version should be upgraded +upon first boot. +This is useful when using a ZFS pool generated by the +.Xr makefs 8 +utility. .It Va gptboot_enable .Pq Vt bool If set to @@ -3511,19 +3551,6 @@ program. The default is .Dq Li -d , which causes missing directories to be created. -.It Va mta_start_script -.Pq Vt str -This variable specifies the full path to the script to run to start -a mail transfer agent. -The default is -.Pa /etc/rc.sendmail . -The -.Va sendmail_* -variables which -.Pa /etc/rc.sendmail -uses are documented in the -.Xr rc.sendmail 8 -manual page. .It Va dumpdev .Pq Vt str Indicates the device (usually a swap partition) to which a crash dump @@ -4674,6 +4701,162 @@ which means that the script will attempt to unlock all datasets. Define the total number of seconds to wait for the zfskeys script to unlock an encrypted dataset. The default is 10. +.It Va sendmail_enable +.Pq Vt str +If set to +.Dq Li YES , +run the +.Xr sendmail 8 +daemon at system boot time. +If set to +.Dq Li NO , +do not run a +.Xr sendmail 8 +daemon to listen for incoming network mail. +This does not preclude a +.Xr sendmail 8 +daemon listening on the SMTP port of the loopback interface. +The +.Dq Li NONE +option sets each +.Va sendmail_enable , +.Va sendmail_submit_enable , +.Va sendmail_outbound_enable , +.Va sendmail_msp_queue_enable +to +.Dq Li NO . +.It Va sendmail_cert_create +.Pq Vt str +If +.Va sendmail_enable +is set to +.Dq Li YES , +create a signed certificate +.Pa /etc/mail/certs/host.cert +representing +.Pa /etc/mail/certs/host.key +by the CA certificate in +.Pa /etc/mail/certs/cacert.pem . +This will enable connecting hosts to negotiate STARTTLS allowing incoming +email to be encrypted in transit. +.Xr sendmail 8 +needs to be configured to use these generated files. +The default configuration in +.Pa /etc/mail/freebsd.mc +has the required options in it. +.It Va sendmail_cert_cn +.Pq Vt str +If +.Va sendmail_enable +is set to +.Dq Li YES +and +.Va sendmail_cert_create +is set to +.Dq Li YES , +this is the Common Name (CN) of the certificate that will be created. +If +.Va sendmail_cert_cn +is not set, the system's hostname will be used. +If there is no hostname set, +.Dq Li amnesiac +will be used. +.It Va sendmail_flags +.Pq Vt str +If +.Va sendmail_enable +is set to +.Dq Li YES , +these are the flags to pass to the +.Xr sendmail 8 +daemon. +.It Va sendmail_submit_enable +.Pq Vt bool +If set to +.Dq Li YES +and +.Va sendmail_enable +is set to +.Dq Li NO , +run +.Xr sendmail 8 +using +.Va sendmail_submit_flags +instead of +.Va sendmail_flags . +This is intended to allow local mail submission via +a localhost-only listening SMTP service required for running +.Xr sendmail 8 +as a non-set-user-ID binary. +Note that this does not work inside +.Xr jail 2 +systems, as jails do not allow binding to just the localhost interface. +.It Va sendmail_submit_flags +.Pq Vt str +If +.Va sendmail_enable +is set to +.Dq Li NO +and +.Va sendmail_submit_enable +is set to +.Dq Li YES , +these are the flags to pass to the +.Xr sendmail 8 +daemon. +.It Va sendmail_outbound_enable +.Pq Vt bool +If set to +.Dq Li YES +and both +.Va sendmail_enable +and +.Va sendmail_submit_enable +are set to +.Dq Li NO , +run +.Xr sendmail 8 +using +.Va sendmail_outbound_flags +instead of +.Va sendmail_flags . +This is intended to allow local mail queue management +for systems that do not offer a listening SMTP service. +.It Va sendmail_outbound_flags +.Pq Vt str +If both +.Va sendmail_enable +and +.Va sendmail_submit_enable +are set to +.Dq Li NO +and +.Va sendmail_outbound_enable +is set to +.Dq Li YES , +these are the flags to pass to the +.Xr sendmail 8 +daemon. +.It Va sendmail_msp_queue_enable +.Pq Vt bool +If set to +.Dq Li YES , +start a client (MSP) queue runner +.Xr sendmail 8 +daemon at system boot time. +As of sendmail 8.12, a separate queue is used for command line +submissions. +The client queue runner ensures that nothing is +left behind in the submission queue. +.It Va sendmail_msp_queue_flags +.Pq Vt str +If +.Va sendmail_msp_queue_enable +is set to +daemon. +.Dq Li YES , +these are the flags to pass to the +.Xr sendmail 8 .El .Sh FILES .Bl -tag -width "/etc/defaults/rc.conf" -compact @@ -4685,12 +4868,13 @@ The default is 10. .El .Sh SEE ALSO .Xr chmod 1 , -.Xr gdb 1 , +.Xr gdb 1 Pq Pa ports/devel/gdb , .Xr info 1 , .Xr kbdcontrol 1 , .Xr limits 1 , .Xr protect 1 , .Xr sh 1 , +.Xr umask 1 , .Xr vi 1 , .Xr vidcontrol 1 , .Xr bridge 4 , @@ -4759,7 +4943,6 @@ The default is 10. .Xr quotacheck 8 , .Xr quotaon 8 , .Xr rc 8 , -.Xr rc.sendmail 8 , .Xr rc.subr 8 , .Xr rcorder 8 , .Xr rfcomm_pppd 8 , @@ -4773,6 +4956,7 @@ The default is 10. .Xr rwhod 8 , .Xr savecore 8 , .Xr sdpd 8 , +.Xr sendmail 8 , .Xr service 8 , .Xr sshd 8 , .Xr swapon 8 , diff --git a/share/man/man5/resolver.5 b/share/man/man5/resolver.5 index 468c635839c6..a0c1aea24b88 100644 --- a/share/man/man5/resolver.5 +++ b/share/man/man5/resolver.5 @@ -28,7 +28,7 @@ .\" @(#)resolver.5 8.1 (Berkeley) 6/5/93 .\" $FreeBSD$ .\" -.Dd November 9, 2021 +.Dd November 23, 2022 .Dt RESOLVER 5 .Os .Sh NAME @@ -46,8 +46,10 @@ by the resolver routines the first time they are invoked by a process. The file is designed to be human readable and contains a list of keywords with values that provide various types of resolver information. .Pp -On a normally configured system this file should not be necessary. -The only name server to be queried will be on the local machine, +On a normally configured system, setting this file manually should not +be necessary. +The only name server(s) to be queried will be on the local machine +or automatically configured using DHCP or a similar mechanism, the domain name is determined from the host name, and the domain search path is constructed from the domain name. .Pp @@ -132,7 +134,7 @@ in _res.options. sets .Dv RES_USEVC to use TCP instead of UDP for queries. -.It Sy ndots: Ns Ar n +.It Sy ndots : Ns Ar n sets a threshold for the number of dots which must appear in a name given to .Fn res_query (see @@ -148,7 +150,7 @@ meaning that if there are any dots in a name, the name will be tried first as an absolute name before any .Em search list elements are appended to it. -.It Sy timeout: Ns Ar n +.It Sy timeout : Ns Ar n sets the initial amount of time the resolver will wait for a response from a remote name server before retrying the query via a different name server. @@ -161,7 +163,7 @@ the allowed maximum is .Dv RES_MAXRETRANS (see .In resolv.h ) . -.It Sy attempts: Ns Ar n +.It Sy attempts : Ns Ar n sets the number of times the resolver will send a query to each of its name servers before giving up and returning an error to the calling application. @@ -180,7 +182,7 @@ the resolver from obeying the standard and .Sy search rules with the given name. -.It Sy reload-period: Ns Ar n +.It Sy reload-period : Ns Ar n The resolver checks the modification time of .Pa /etc/resolv.conf every @@ -220,14 +222,34 @@ The file resides in .Pa /etc . .El +.Sh EXAMPLES +A basic resolv.conf file could be in the following form. +.Bd -literal -offset indent +# The domain directive is only necessary, if your local +# router advertises something like localdomain and you have +# set up your hostnames via an external domain. +domain localdomain.tld + +# In case you a running a local dns server or caching name server +# like local-unbound(8) for example. +nameserver 127.0.0.1 + +# IP address of the local or ISP name service +nameserver 192.168.2.1 + +# Fallback nameservers, in this case these from Google. +nameserver 8.8.8.8 +nameserver 4.4.4.4 + +# Attach an OPT pseudo-RR for the EDNS0 extension, +# as specified in RFC 2671. +options edns0 +.Ed .Sh SEE ALSO .Xr gethostbyname 3 , .Xr resolver 3 , .Xr hostname 7 , .Xr resolvconf 8 -.Rs -.%T "Name Server Operations Guide for BIND" -.Re .Sh HISTORY The .Nm resolv.conf diff --git a/share/man/man5/src.conf.5 b/share/man/man5/src.conf.5 index 36fb474b6597..132a05065bd0 100644 --- a/share/man/man5/src.conf.5 +++ b/share/man/man5/src.conf.5 @@ -1,6 +1,6 @@ .\" DO NOT EDIT-- this file is @generated by tools/build/options/makeman. .\" $FreeBSD$ -.Dd July 6, 2022 +.Dd November 21, 2022 .Dt SRC.CONF 5 .Os .Sh NAME @@ -386,12 +386,6 @@ Build clang-format. .It Va WITHOUT_CLANG_FULL Avoid building the ARCMigrate, Rewriter and StaticAnalyzer components of the Clang C/C++ compiler. -.It Va WITHOUT_CLANG_IS_CC -Do not install links to the Clang C/C++ compiler as -.Pa /usr/bin/cc , -.Pa /usr/bin/c++ -and -.Pa /usr/bin/cpp . .It Va WITHOUT_CLEAN Do not clean before building world and/or kernel. .It Va WITHOUT_CPP @@ -495,6 +489,10 @@ When set, it enforces these options: .It .Va WITHOUT_GOOGLETEST .It +.Va WITHOUT_LLD +.It +.Va WITHOUT_LLDB +.It .Va WITHOUT_LLVM_COV .It .Va WITHOUT_OFED @@ -736,12 +734,12 @@ Do not build HTML docs. Do not build or install HyperV utilities. .Pp This is a default setting on -arm/armv6, arm/armv7, arm64/aarch64, powerpc/powerpc, powerpc/powerpc64, powerpc/powerpc64le, riscv/riscv64 and riscv/riscv64sf. +arm/armv6, arm/armv7, powerpc/powerpc, powerpc/powerpc64, powerpc/powerpc64le, riscv/riscv64 and riscv/riscv64sf. .It Va WITH_HYPERV Build or install HyperV utilities. .Pp This is a default setting on -amd64/amd64 and i386/i386. +amd64/amd64, arm64/aarch64 and i386/i386. .It Va WITHOUT_ICONV Do not build iconv as part of libc. .It Va WITHOUT_INCLUDES @@ -843,9 +841,8 @@ is set explicitly) Build some programs without Kerberos support, like .Xr ssh 1 , .Xr telnet 1 , -.Xr sshd 8 , and -.Xr telnetd 8 . +.Xr sshd 8 . .It Va WITH_KERNEL_RETPOLINE Enable the "retpoline" mitigation for CVE-2017-5715 in the kernel build. @@ -993,9 +990,6 @@ option should be used rather than this in most cases. Enable building .Xr loader 8 with support for verification based on certificates obtained from UEFI. -.It Va WITH_LOADER_FIREWIRE -Enable firewire support in /boot/loader on x86. -This option is a nop on all other platforms. .It Va WITHOUT_LOADER_GELI Disable inclusion of GELI crypto support in the boot chain binaries. .Pp @@ -1094,6 +1088,8 @@ and related programs. Build .Xr ls 1 without support for colors to distinguish file types. +.It Va WITHOUT_MACHDEP_OPTIMIZATIONS +Prefer machine-independent non-assembler code in libc and libm. .It Va WITHOUT_MAIL Do not build any mail support (MUA or MTA). When set, it enforces these options: @@ -1246,8 +1242,8 @@ is set explicitly) .It Va WITHOUT_NETGRAPH_SUPPORT Build libraries, programs, and kernel modules without netgraph support. .It Va WITHOUT_NIS -Do not build NIS also known as -.Xr yp 8 +Do not build +.Xr NIS 8 support and related programs. If set, you might need to adopt your .Xr nsswitch.conf 5 diff --git a/share/man/man7/arch.7 b/share/man/man7/arch.7 index c7c2e224b33d..493f197673f0 100644 --- a/share/man/man7/arch.7 +++ b/share/man/man7/arch.7 @@ -26,7 +26,7 @@ .\" .\" $FreeBSD$ .\" -.Dd November 25, 2021 +.Dd September 15, 2022 .Dt ARCH 7 .Os .Sh NAME @@ -169,7 +169,9 @@ or .Dv armv7 binaries if the CPU implements .Dv AArch32 -execution state, however +execution state, however older +.Dv armv4 +and .Dv armv5 binaries aren't supported. .Pp diff --git a/share/man/man7/ascii.7 b/share/man/man7/ascii.7 index 713a4922e759..12974283da61 100644 --- a/share/man/man7/ascii.7 +++ b/share/man/man7/ascii.7 @@ -28,7 +28,7 @@ .\" @(#)ascii.7 8.1 (Berkeley) 6/5/93 .\" $FreeBSD$ .\" -.Dd September 21, 2019 +.Dd November 12, 2022 .Dt ASCII 7 .Os .Sh NAME @@ -142,6 +142,44 @@ ESC ; [ { 11011 RS > ^ - 11110 US ? _ DEL 11111 .Ed +.Pp +The full +.Nm names +of the control character set: +.Bd -literal -offset left +NUL NULl +SOH Start Of Heading +STX Start Of Text +ETX End Of Text +EOT End Of Transmission +ENQ ENQuiry +ACK ACKnowledge +BEL BELl + BS BackSpace + HT Horizontal Tab + LF Line Feed (new line) + VT Vertical Tab + FF new page Form Feed + CR Carriage Return + SO Shift Out + SI Shift In +DLE Data Link Escape +DC1 Device Control 1 +DC2 Device Control 2 +DC3 Device Control 3 +DC4 Device Control 4 +NAK Negative AcKnowledge +SYN SYNchronous idle +ETB End of Transmission Block +CAN CANcel + EM End of Medium +SUB SUBstitute +ESC ESCape + FS File Separator + GS Group Separator + RS Record Separator + US Unit Separator +.Ed .Sh FILES .Bl -tag -width /usr/share/misc/ascii -compact .It Pa /usr/share/misc/ascii diff --git a/share/man/man7/development.7 b/share/man/man7/development.7 index 346772b4fbb0..85701ef77811 100644 --- a/share/man/man7/development.7 +++ b/share/man/man7/development.7 @@ -23,7 +23,7 @@ .\" .\" $FreeBSD$ .\" -.Dd July 21, 2022 +.Dd November 1, 2022 .Dt DEVELOPMENT 7 .Os .Sh NAME @@ -39,14 +39,14 @@ Doc is the documentation, such as the Handbook. To read more, see: .Pp -.Lk https://www.FreeBSD.org/doc/en/books/fdp-primer/ +.Lk https://docs.FreeBSD.org/en/books/fdp-primer/ .Pp Ports, described further in .Xr ports 7 , are the way to build, package, and install third party software. To read more, see: .Pp -.Lk https://www.FreeBSD.org/doc/en/books/porters-handbook/ +.Lk https://docs.FreeBSD.org/en/books/porters-handbook/ .Pp The last one, src, revolves around the source code for the base system, consisting of the kernel, and the libraries and utilities commonly called @@ -55,7 +55,7 @@ the world. The Committer's Guide, describing topics relevant to all committers, can be found at: .Pp -.Lk https://www.FreeBSD.org/doc/en/articles/committers-guide/ +.Lk https://docs.freebsd.org/en/articles/committers-guide/ .Pp .Fx src development takes place in the project-hosted @@ -69,7 +69,7 @@ The push URL is: .Pp There is also a list of public, read-only Git mirrors at: .Pp -.Lk https://docs.freebsd.org/en/books/handbook/mirrors/#external-mirrors +.Lk https://docs.FreeBSD.org/en/books/handbook/mirrors/#external-mirrors .Pp The .Ql main @@ -82,8 +82,9 @@ with an incremented major version number. Releases are then branched off STABLE and numbered with consecutive minor numbers. .Pp -Layout of the source tree is described in -.Xr hier 7 . +The layout of the source tree is described in its +.Pa README.md +file. Build instructions can be found in .Xr build 7 and diff --git a/share/man/man7/environ.7 b/share/man/man7/environ.7 index 9a77100ff6d3..7d188a795883 100644 --- a/share/man/man7/environ.7 +++ b/share/man/man7/environ.7 @@ -197,7 +197,7 @@ The full pathname of the user's login shell. .It Ev TERM The kind of terminal for which output is to be prepared. This information is used by commands, such as -.Xr nroff 1 +.Xr nroff 1 Pq Pa ports/textproc/groff or .Xr plot 1 which may exploit special terminal capabilities. diff --git a/share/man/man7/hier.7 b/share/man/man7/hier.7 index f33cf5ac62cc..bb00923118c1 100644 --- a/share/man/man7/hier.7 +++ b/share/man/man7/hier.7 @@ -28,14 +28,15 @@ .\" @(#)hier.7 8.1 (Berkeley) 6/5/93 .\" $FreeBSD$ .\" -.Dd August 4, 2022 +.Dd November 23, 2022 .Dt HIER 7 .Os .Sh NAME .Nm hier .Nd layout of file systems -.Sh DESCRIPTION +.Sh SYNOPSIS A sketch of the file system hierarchy. +.Sh DESCRIPTION .Bl -tag -width "/libexec/" .It Pa / root directory of the file system @@ -73,8 +74,6 @@ and .Xr zfs 8 zpool cache files .El -.It Pa /cdrom/ -default mount point for CD-ROM drives .It Pa /compat/ normally a link to .Pa /usr/compat . @@ -296,7 +295,7 @@ machine-specific C include files miscellaneous network C include files .Bl -tag -width Fl -compact .It Pa altq/ -C include files for alternate packet queueing; see +C include files for alternate packet queuing; see .Xr altq 4 .El .It Pa net80211/ @@ -332,7 +331,7 @@ definition of RPC service structures; see .Xr rpc 3 .It Pa security/ PAM; see -.Xr pam 8 +.Xr pam 3 .It Pa sys/ system C include files (kernel data structures) .\" .It Pa tcl/ @@ -380,14 +379,15 @@ miscellaneous utility data files .Pp .Bl -tag -width Fl -compact .It Pa gcc/ -.Xr gcc 1 -configuration data +GCC configuration data .It Pa ldscripts/ linker scripts; see .Xr ld 1 .It Pa pkgconfig/ -pc files +.Xr pc 5 Pq Pa ports/devel/pkgconf +files: collections of compiler flags, linker flags, and other +information relevant to library use .El .Pp .It Pa libexec/ @@ -464,16 +464,14 @@ see .Fx Ns -specific terms, proper names, and jargon .It Pa web2 -words from Webster's 2nd International +words from Webster's Second International .El .It Pa doc/ miscellaneous documentation; source for most of the printed .Bx manuals (available -from the -.Tn USENIX -association) +from the USENIX association) .Bl -tag -width Fl -compact .It Pa FAQ/ Frequently Asked Questions @@ -641,127 +639,10 @@ see .It Pa src/ .Fx source code; see -.Xr development 7 -.Pp -.Bl -tag -width "kerberos5/" -compact -.It Pa bin/ -source code for files in /bin -.It Pa cddl/ -utilities covered by the Common Development and Distribution License -.It Pa contrib/ -source code for contributed software -.It Pa crypto/ -source code for contributed cryptography software -.It Pa etc/ -source code for files in -.Pa /etc -.It Pa gnu/ -utilities covered by the GNU General Public License -.It Pa include/ -source code for files in -.Pa /usr/include -.It Pa kerberos5/ -build infrastructure for Kerberos version 5 -.It Pa lib/ -source code for files in -.Pa /lib -and -.Pa /usr/lib -.It Pa libexec/ -source code for files in -.Pa /usr/libexec -.It Pa release/ -files required to produce a -.Fx -release -.It Pa rescue/ -source code for files in -.Pa /rescue -.It Pa sbin/ -source code for files in -.Pa /sbin -.It Pa secure/ -build directory for files in -.Pa /usr/src/crypto -.It Pa share/ -source for files in -.Pa /usr/share -.It Pa stand/ -boot loader source code -.It Pa sys/ -kernel source code -.Bl -tag -width Fl -compact -.It Pa amd64/ -AMD64 architecture support -.It Pa arm/ -ARM architecture support -.It Pa arm64/ -ARMv8 architecture support -.It Pa cam/ -.Xr cam 4 -and -.Xr ctl 4 -.It Pa cddl/ -CDDL-licensed optional sources, including ZFS -and DTrace -.It Pa ddb/ -.Xr ddb 4 -.It Pa fs/ -most filesystems -.It Pa dev/ -device drivers -.It Pa geom/ -.Xr geom 4 -.It Pa i386/ -i386 (32 bit) architecture support -.It Pa kern/ -main part of the kernel -.It Pa net80211/ -.Xr net80211 4 -.It Pa netgraph/ -.Xr netgraph 4 -.It Pa netinet/ -.Xr inet 4 -.It Pa netinet6/ -.Xr inet6 4 -.It Pa netipsec/ -.Xr ipsec 4 -.It Pa netpfil/ -.Xr ipfw 4 -and -.Xr pf 4 -.It Pa opencrypto/ -.Xr crypto 7 -.It Pa powerpc/ -PowerPC/POWER architecture support -.It Pa riscv/ -RISC-V architecture support -.It Pa security/ -.Xr audit 4 -and -.Xr mac 4 -.It Pa sys/ -kernel headers -.It Pa ufs/ -Unix File System -.It Pa x86/ -code shared by AMD64 and i386 architectures -.El -.It Pa targets/ -support for experimental DIRDEPS_BUILD -.It Pa tests/ -source code for files in -.Pa /usr/tests -.It Pa tools/ -tools used for maintenance and testing of -.Fx -.It Pa usr.bin/ -source code for files in -.Pa /usr/bin -.It Pa usr.sbin/ -source code for files in -.Pa /usr/sbin -.El +.Xr development 7 . +The layout of the source tree is described by the top-level +.Pa README.md +file. .Pp .It Pa tests/ The diff --git a/share/man/man7/orders.7 b/share/man/man7/orders.7 index e8aa4d79f9f2..dca012a0a2cf 100644 --- a/share/man/man7/orders.7 +++ b/share/man/man7/orders.7 @@ -29,7 +29,7 @@ .\" .\" $FreeBSD$ .\" -.Dd August 6, 2011 +.Dd November 20, 2022 .Dt ORDERS 7 .Os .Sh NAME @@ -48,7 +48,9 @@ The following table lists common multiples of bytes. .It Exabyte Ta EB Ta 2^60 Ta 10^18 .It Zettabyte Ta ZB Ta 2^70 Ta 10^21 .It Yottabyte Ta YB Ta 2^80 Ta 10^24 -.El +.It Ronnabyte Ta RB Ta 2^90 Ta 10^27 +.It Quettabyte Ta QB Ta 2^100 Ta 10^30. +El .Pp The following table lists common bit rates as a power of ten. .Bl -column -offset 2n \ @@ -70,6 +72,8 @@ The following table lists common orders of magnitude as a power of ten. .Bl -column -offset 2n \ "Septillionth" "Order" "Prefix" "Symbol" "Decimal" .It Sy Name Ta Sy Order Ta Sy Prefix Ta Sy Symbol Ta Sy Decimal +.It Nonillionth Ta 10^-30 Ta quecto Ta q Ta 0.000000000000000000000000000001 +.It Octillionth Ta 10^-27 Ta ronto Ta r Ta 0.000000000000000000000000001 .It Septillionth Ta 10^-24 Ta yocto Ta y Ta 0.000000000000000000000001 .It Sextillionth Ta 10^-21 Ta zepto Ta z Ta 0.000000000000000000001 .It Quintillionth Ta 10^-18 Ta atto Ta a Ta 0.000000000000000001 @@ -91,6 +95,8 @@ The following table lists common orders of magnitude as a power of ten. .It Quintillion Ta 10^18 Ta exa Ta E Ta 1000000000000000000 .It Sextillion Ta 10^21 Ta zetta Ta Z Ta 1000000000000000000000 .It Septillion Ta 10^24 Ta yotta Ta Y Ta 1000000000000000000000000 +.It Octillion Ta 10^27 Ta ronna Ta R Ta 1000000000000000000000000000 +.It Nonillion Ta 10^30 Ta quetta Ta Q Ta 1000000000000000000000000000000 .El .Sh SEE ALSO .Xr units 1 , diff --git a/share/man/man7/release.7 b/share/man/man7/release.7 index be475979dd0f..855cf91697a1 100644 --- a/share/man/man7/release.7 +++ b/share/man/man7/release.7 @@ -24,7 +24,7 @@ .\" .\" $FreeBSD$ .\" -.Dd July 21, 2022 +.Dd October 28, 2022 .Dt RELEASE 7 .Os .Sh NAME @@ -365,6 +365,14 @@ is used, the resulting files compressed with .Xr xz 1 compress to roughly the same size, regardless of the specified disk image size. +.It Va VMFS +Set to specify the file system type to use. +Valid values are +.Va ufs +and +.Va zfs . +The default value is +.Va ufs . .It Va VMFORMATS Set to the target virtual disk image format(s) to create. By default, the diff --git a/share/man/man7/security.7 b/share/man/man7/security.7 index 49701bbe80f1..f87833ece112 100644 --- a/share/man/man7/security.7 +++ b/share/man/man7/security.7 @@ -28,7 +28,7 @@ .\" .\" $FreeBSD$ .\" -.Dd January 14, 2022 +.Dd September 29, 2022 .Dt SECURITY 7 .Os .Sh NAME @@ -97,9 +97,9 @@ It may not be able to take your machine down, but it can fill up your Internet pipe. .Pp A user account compromise is even more common than a DoS attack. -Many -sysadmins still run standard -.Xr telnetd 8 +Some +sysadmins still run +.Nm telnetd and .Xr ftpd 8 servers on their machines. @@ -338,8 +338,8 @@ virtually every server ever run as root, including basic system servers. If you are running a machine through which people only log in via .Xr sshd 8 and never log in via -.Xr telnetd 8 -then turn off those services! +.Nm telnetd +then turn off this service! .Pp .Fx now defaults to running diff --git a/share/man/man7/tuning.7 b/share/man/man7/tuning.7 index 63e09ecce098..6cfb0dd15bc4 100644 --- a/share/man/man7/tuning.7 +++ b/share/man/man7/tuning.7 @@ -24,7 +24,7 @@ .\" .\" $FreeBSD$ .\" -.Dd April 16, 2020 +.Dd October 11, 2022 .Dt TUNING 7 .Os .Sh NAME @@ -482,7 +482,7 @@ By default is set at the maximum allowable port number. .Pp The -.Va kern.ipc.somaxconn +.Va kern.ipc.soacceptqueue sysctl limits the size of the listen queue for accepting new TCP connections. The default value of 128 is typically too low for robust handling of new connections in a heavily loaded web server environment. diff --git a/share/man/man8/Makefile b/share/man/man8/Makefile index 1257f3ab97bf..cd3cb34b11d1 100644 --- a/share/man/man8/Makefile +++ b/share/man/man8/Makefile @@ -10,7 +10,6 @@ MAN= \ intro.8 \ nanobsd.8 \ rc.8 \ - rc.sendmail.8 \ rc.subr.8 \ rescue.8 \ ${_uefi.8} \ diff --git a/share/man/man8/rc.sendmail.8 b/share/man/man8/rc.sendmail.8 deleted file mode 100644 index d8dff43fdbe3..000000000000 --- a/share/man/man8/rc.sendmail.8 +++ /dev/null @@ -1,298 +0,0 @@ -.\" Copyright (c) 1995 -.\" Jordan K. Hubbard -.\" Copyright (c) 2002 The FreeBSD Project -.\" 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 October 19, 2013 -.Dt RC.SENDMAIL 8 -.Os -.Sh NAME -.Nm rc.sendmail -.Nd -.Xr sendmail 8 -startup script -.Sh DESCRIPTION -The -.Nm -script is used by -.Pa /etc/rc -at boot time to start -.Xr sendmail 8 . -It is meant to be -.Xr sendmail 8 -specific and not a generic script for all MTAs. -It is only called by -.Pa /etc/rc -if the -.Xr rc.conf 5 -.Va mta_start_script -variable is set to -.Pa /etc/rc.sendmail . -.Pp -The -.Nm -script can take an optional argument specifying the action to -perform. -The available actions are: -.Bl -tag -width ".Cm restart-mspq" -.It Cm start -Starts both the MTA and the MSP queue runner. -.It Cm stop -Stops both the MTA and the MSP queue runner. -.It Cm restart -Restarts both the MTA and the MSP queue runner. -.It Cm start-mta -Starts just the MTA. -.It Cm stop-mta -Stops just the MTA. -.It Cm restart-mta -Restarts just the MTA. -.It Cm start-mspq -Starts just the MSP queue runner. -.It Cm stop-mspq -Stops just the MSP queue runner. -.It Cm restart-mspq -Restarts just the MSP queue runner. -.El -.Pp -If no action is specified, -.Cm start -is assumed. -.Pp -The -.Nm -script is also used by -.Pa /etc/mail/Makefile -to enable the -.Pa Makefile Ns 's -.Cm start , stop , -and -.Cm restart -targets. -.Sh RC.CONF VARIABLES -The following variables affect the behavior of -.Nm . -They are defined in -.Pa /etc/defaults/rc.conf -and can be changed in -.Pa /etc/rc.conf . -.Bl -tag -width indent -.It Va sendmail_enable -.Pq Vt str -If set to -.Dq Li YES , -run the -.Xr sendmail 8 -daemon at system boot time. -If set to -.Dq Li NO , -do not run a -.Xr sendmail 8 -daemon to listen for incoming network mail. -This does not preclude a -.Xr sendmail 8 -daemon listening on the SMTP port of the loopback interface. -The -.Dq Li NONE -option is deprecated and should not be used. -It will be removed in a future release. -.It Va sendmail_cert_create -.Pq Vt str -If -.Va sendmail_enable -is set to -.Dq Li YES , -create a signed certificate -.Pa /etc/mail/certs/host.cert -representing -.Pa /etc/mail/certs/host.key -by the CA certificate in -.Pa /etc/mail/certs/cacert.pem . -This will enable connecting hosts to negotiate STARTTLS allowing incoming -email to be encrypted in transit. -.Xr sendmail 8 -needs to be configured to use these generated files. -The default configuration in -.Pa /etc/mail/freebsd.mc -has the required options in it. -.It Va sendmail_cert_cn -.Pq Vt str -If -.Va sendmail_enable -is set to -.Dq Li YES -and -.Va sendmail_cert_create -is set to -.Dq Li YES , -this is the Common Name (CN) of the certificate that will be created. -If -.Va sendmail_cert_cn -is not set, the system's hostname will be used. -If there is no hostname set, -.Dq Li amnesiac -will be used. -.It Va sendmail_flags -.Pq Vt str -If -.Va sendmail_enable -is set to -.Dq Li YES , -these are the flags to pass to the -.Xr sendmail 8 -daemon. -.It Va sendmail_submit_enable -.Pq Vt bool -If set to -.Dq Li YES -and -.Va sendmail_enable -is set to -.Dq Li NO , -run -.Xr sendmail 8 -using -.Va sendmail_submit_flags -instead of -.Va sendmail_flags . -This is intended to allow local mail submission via -a localhost-only listening SMTP service required for running -.Xr sendmail 8 -as a non-set-user-ID binary. -Note that this does not work inside -.Xr jail 2 -systems, as jails do not allow binding to just the localhost interface. -.It Va sendmail_submit_flags -.Pq Vt str -If -.Va sendmail_enable -is set to -.Dq Li NO -and -.Va sendmail_submit_enable -is set to -.Dq Li YES , -these are the flags to pass to the -.Xr sendmail 8 -daemon. -.It Va sendmail_outbound_enable -.Pq Vt bool -If set to -.Dq Li YES -and both -.Va sendmail_enable -and -.Va sendmail_submit_enable -are set to -.Dq Li NO , -run -.Xr sendmail 8 -using -.Va sendmail_outbound_flags -instead of -.Va sendmail_flags . -This is intended to allow local mail queue management -for systems that do not offer a listening SMTP service. -.It Va sendmail_outbound_flags -.Pq Vt str -If both -.Va sendmail_enable -and -.Va sendmail_submit_enable -are set to -.Dq Li NO -and -.Va sendmail_outbound_enable -is set to -.Dq Li YES , -these are the flags to pass to the -.Xr sendmail 8 -daemon. -.It Va sendmail_msp_queue_enable -.Pq Vt bool -If set to -.Dq Li YES , -start a client (MSP) queue runner -.Xr sendmail 8 -daemon at system boot time. -As of sendmail 8.12, a separate queue is used for command line -submissions. -The client queue runner ensures that nothing is -left behind in the submission queue. -.It Va sendmail_msp_queue_flags -.Pq Vt str -If -.Va sendmail_msp_queue_enable -is set to -.Dq Li YES , -these are the flags to pass to the -.Xr sendmail 8 -daemon. -.El -.Pp -These variables are used to determine how the -.Xr sendmail 8 -daemons are started: -.Bd -literal -offset indent -# MTA -if (${sendmail_enable} == NONE) - # Do nothing -else if (${sendmail_enable} == YES) - start sendmail with ${sendmail_flags} -else if (${sendmail_submit_enable} == YES) - start sendmail with ${sendmail_submit_flags} -else if (${sendmail_outbound_enable} == YES) - start sendmail with ${sendmail_outbound_flags} -endif - -# MSP Queue Runner -if (${sendmail_enable} != NONE && - [ -r /etc/mail/submit.cf] && - ${sendmail_msp_queue_enable} == YES) - start sendmail with ${sendmail_msp_queue_flags} -endif -.Ed -.Pp -To completely prevent any -.Xr sendmail 8 -daemons from starting, you must -set the following variables in -.Pa /etc/rc.conf : -.Bd -literal -offset indent -sendmail_enable="NO" -sendmail_submit_enable="NO" -sendmail_outbound_enable="NO" -sendmail_msp_queue_enable="NO" -.Ed -.Sh SEE ALSO -.Xr rc.conf 5 , -.Xr rc 8 , -.Xr sendmail 8 -.Sh HISTORY -The -.Nm -file appeared in -.Fx 4.6 . diff --git a/share/man/man8/rc.subr.8 b/share/man/man8/rc.subr.8 index 130962ecdcdf..f9c802679e00 100644 --- a/share/man/man8/rc.subr.8 +++ b/share/man/man8/rc.subr.8 @@ -29,7 +29,7 @@ .\" .\" $FreeBSD$ .\" -.Dd March 18, 2022 +.Dd August 16, 2022 .Dt RC.SUBR 8 .Os .Sh NAME @@ -685,6 +685,9 @@ This is a generic version of .Va ${name}_fib , or .Va ${name}_nice . +.It Va ${name}_setup +Command to be run prior to +.Va command . .It Ar argument Ns Va _cmd Shell commands which override the default method for .Ar argument . diff --git a/share/man/man9/EVENTHANDLER.9 b/share/man/man9/EVENTHANDLER.9 index b369e2f03258..82480ce1dc71 100644 --- a/share/man/man9/EVENTHANDLER.9 +++ b/share/man/man9/EVENTHANDLER.9 @@ -23,7 +23,7 @@ .\" SUCH DAMAGE. .\" $FreeBSD$ .\" -.Dd September 17, 2020 +.Dd October 7, 2022 .Dt EVENTHANDLER 9 .Os .Sh NAME @@ -258,150 +258,6 @@ The function removes all deregistered callbacks from the event list .Fa list . .El -.Ss Kernel Event Handlers -The following event handlers are present in the kernel: -.Bl -tag -width indent -.It Vt acpi_sleep_event -Callbacks invoked when the system is being sent to sleep. -.It Vt acpi_wakeup_event -Callbacks invoked when the system is being woken up. -.It Vt app_coredump_start -Callbacks invoked at start of application core dump. -.It Vt app_coredump_progress -Callbacks invoked during progress of application core dump. -.It Vt app_coredump_finish -Callbacks invoked at finish of application core dump. -.It Vt app_coredump_error -Callbacks invoked on error of application core dump. -.It Vt bpf_track -Callbacks invoked when a BPF listener attaches to/detaches from network interface. -.It Vt cpufreq_levels_changed -Callback invoked when cpu frequency levels have changed. -.It Vt cpufreq_post_change -Callback invoked after cpu frequency has changed. -.It Vt cpufreq_pre_change -Callback invoked before cpu frequency has changed. -.It Vt dcons_poll -Callback invoked to poll for dcons changes. -.It Vt device_attach -Callback invoked after a device has attached. -.It Vt device_detach -Callbacks invoked before and after a device has detached. -.It Vt dev_clone -Callbacks invoked when a new entry is created under -.Pa /dev . -.It Vt group_attach_event -Callback invoked when an interfance has been added to an interface group. -.It Vt group_change_event -Callback invoked when an change has been made to an interface group. -.It Vt group_detach_event -Callback invoked when an interfance has been removed from an interface group. -.It Vt ifaddr_event -Callbacks invoked when an address is set up on a network interface. -.It Vt ifaddr_event_ext -Callback invoked when an address has been added or removed from an interface. -.It Vt if_clone_event -Callbacks invoked when an interface is cloned. -.It Vt iflladdr_event -Callback invoked when an if link layer address event has happened. -.It Vt ifnet_arrival_event -Callbacks invoked when a new network interface appears. -.It Vt ifnet_departure_event -Callbacks invoked when a network interface is taken down. -.It Vt ifnet_link_event -Callback invoked when an interfance link event has happened. -.It Vt kld_load -Callbacks invoked after a linker file has been loaded. -.It Vt kld_unload -Callbacks invoked after a linker file has been successfully unloaded. -.It Vt kld_unload_try -Callbacks invoked before a linker file is about to be unloaded. -These callbacks may be used to return an error and prevent the unload from -proceeding. -.It Vt livedumper_start -Callback invoked before beginning a kernel dump of the live system. -.It Vt livedumper_dump -Callback invoked for each dumped block of data during a live kernel dump. -.It Vt livedumper_finish -Callback invoked once a live kernel dump has completed. -.It Vt lle_event -Callback invoked when a link layer event has happened. -.It Vt nmbclusters_change -Callback invoked when the number of mbuf clusters has changed. -.It Vt nmbufs_change -Callback invoked when the number of mbufs has changed. -.It Vt maxsockets_change -Callback invoked when the maximum number of sockets has changed. -.It Vt mountroot -Callback invoked when root has been mounted. -.It Vt power_profile_change -Callbacks invoked when the power profile of the system changes. -.It Vt power_resume -Callback invoked when the system has resumed. -.It Vt power_suspend -Callback invoked just before the system is suspended. -.It Vt process_ctor -Callback invoked when a process is created. -.It Vt process_dtor -Callback invoked when a process is destroyed. -.It Vt process_exec -Callbacks invoked when a process performs an -.Fn exec -operation. -.It Vt process_exit -Callbacks invoked when a process exits. -.It Vt process_fini -Callback invoked when a process memory is destroyed. -This is never called. -.It Vt process_fork -Callbacks invoked when a process forks a child. -.It Vt process_init -Callback invoked when a process is initialized. -.It Vt random_adaptor_attach -Callback invoked when a new random module has been loaded. -.It Vt register_framebuffer -Callback invoked when a new frame buffer is registered. -.It Vt route_redirect_event -Callback invoked when a route gets redirected to a new location. -.It Vt shutdown_pre_sync -Callbacks invoked at shutdown time, before file systems are synchronized. -.It Vt shutdown_post_sync -Callbacks invoked at shutdown time, after all file systems are synchronized. -.It Vt shutdown_final -Callbacks invoked just before halting the system. -.It Vt tcp_offload_listen_start -Callback invoked for TCP Offload to start listening for new connections. -.It Vt tcp_offload_listen_stop -Callback invoked ror TCP Offload to stop listening for new connections. -.It Vt thread_ctor -Callback invoked when a thread object is created. -.It Vt thread_dtor -Callback invoked when a thread object is destroyed. -.It Vt thread_init -Callback invoked when a thread object is initialized. -.It Vt thread_fini -Callback invoked when a thread object is deinitalized. -.It Vt usb_dev_configured -Callback invoked when a USB device is configured -.It Vt unregister_framebuffer -Callback invoked when a frame buffer is deregistered. -.It Vt vfs_mounted -Callback invoked when a file system is mounted. -.It Vt vfs_unmounted -Callback invoked when a file system is unmounted. -.It Vt vlan_config -Callback invoked when the vlan configuration has changed. -.It Vt vlan_unconfig -Callback invoked when a vlan is destroyed. -.It Vt vm_lowmem -Callbacks invoked when virtual memory is low. -.It Vt vxlan_start -Callback invoked when a vxlan interface starts. -.It Vt vxlan_stop -Callback invoked when a vxlan interface stops. -.It Vt watchdog_list -Callbacks invoked when the system watchdog timer is reinitialized. -.El .Sh RETURN VALUES The macro .Fn EVENTHANDLER_REGISTER diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index 1913f03a48fd..e651172be7eb 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -190,8 +190,8 @@ MAN= accept_filter.9 \ ifnet.9 \ inittodr.9 \ insmntque.9 \ + intr_event.9 \ intro.9 \ - ithread.9 \ kasan.9 \ KASSERT.9 \ kern_reboot.9 \ @@ -241,6 +241,7 @@ MAN= accept_filter.9 \ OF_package_to_path.9 \ ofw_bus_is_compatible.9 \ ofw_bus_status_okay.9 \ + ofw_graph.9 \ osd.9 \ owll.9 \ own.9 \ @@ -705,6 +706,14 @@ MLINKS+=bus_space.9 bus_space_alloc.9 \ bus_space.9 bus_space_copy_region_stream_8.9 \ bus_space.9 bus_space_free.9 \ bus_space.9 bus_space_map.9 \ + bus_space.9 bus_space_peek_1.9 \ + bus_space.9 bus_space_peek_2.9 \ + bus_space.9 bus_space_peek_4.9 \ + bus_space.9 bus_space_peek_8.9 \ + bus_space.9 bus_space_poke_1.9 \ + bus_space.9 bus_space_poke_2.9 \ + bus_space.9 bus_space_poke_4.9 \ + bus_space.9 bus_space_poke_8.9 \ bus_space.9 bus_space_read_1.9 \ bus_space.9 bus_space_read_2.9 \ bus_space.9 bus_space_read_4.9 \ @@ -1022,13 +1031,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 \ @@ -1313,12 +1319,12 @@ MLINKS+=ifnet.9 if_addmulti.9 \ ifnet.9 ifunit.9 \ ifnet.9 ifunit_ref.9 MLINKS+=insmntque.9 insmntque1.9 -MLINKS+=ithread.9 ithread_add_handler.9 \ - ithread.9 ithread_create.9 \ - ithread.9 ithread_destroy.9 \ - ithread.9 ithread_priority.9 \ - ithread.9 ithread_remove_handler.9 \ - ithread.9 ithread_schedule.9 +MLINKS+=intr_event.9 intr_event_add_handler.9 \ + intr_event.9 intr_event_create.9 \ + intr_event.9 intr_event_destroy.9 \ + intr_event.9 intr_event_handle.9 \ + intr_event.9 intr_event_remove_handler.9 \ + intr_event.9 intr_priority.9 MLINKS+=kernacc.9 useracc.9 MLINKS+=kernel_mount.9 free_mntarg.9 \ kernel_mount.9 mount_arg.9 \ @@ -1366,7 +1372,6 @@ MLINKS+=kqueue.9 knlist_add.9 \ kqueue.9 knlist_empty.9 \ kqueue.9 knlist_init.9 \ kqueue.9 knlist_init_mtx.9 \ - kqueue.9 knlist_init_rw_reader.9 \ kqueue.9 knlist_remove.9 \ kqueue.9 knlist_remove_inevent.9 \ kqueue.9 knote_fdclose.9 \ @@ -1413,13 +1418,19 @@ MLINKS+=make_dev.9 destroy_dev.9 \ make_dev.9 make_dev_p.9 \ make_dev.9 make_dev_s.9 MLINKS+=malloc.9 free.9 \ + malloc.9 malloc_aligned.9 \ malloc.9 malloc_domainset.9 \ + malloc.9 malloc_domainset_aligned.9 \ + malloc.9 malloc_domainset_exec.9 \ + malloc.9 malloc_exec.9 \ + malloc.9 malloc_usable_size.9 \ malloc.9 mallocarray.9 \ malloc.9 mallocarray_domainset.9 \ malloc.9 MALLOC_DECLARE.9 \ malloc.9 MALLOC_DEFINE.9 \ malloc.9 realloc.9 \ - malloc.9 reallocf.9 + malloc.9 reallocf.9 \ + malloc.9 zfree.9 MLINKS+=mbchain.9 mb_detach.9 \ mbchain.9 mb_done.9 \ mbchain.9 mb_fixhdr.9 \ @@ -1463,6 +1474,7 @@ MLINKS+=\ mbuf.9 MGET.9 \ mbuf.9 m_get.9 \ mbuf.9 m_get2.9 \ + mbuf.9 m_get3.9 \ mbuf.9 m_getjcl.9 \ mbuf.9 m_getcl.9 \ mbuf.9 MGETHDR.9 \ @@ -1693,6 +1705,12 @@ MLINKS+=ofw_bus_is_compatible.9 ofw_bus_is_compatible_strict.9 \ ofw_bus_is_compatible.9 ofw_bus_search_compatible.9 MLINKS+= ofw_bus_status_okay.9 ofw_bus_get_status.9 \ ofw_bus_status_okay.9 ofw_bus_node_status_okay.9 +MLINKS+=ofw_graph.9 ofw_graph_get_device_by_port_ep.9 \ + ofw_graph.9 ofw_graph_get_endpoint_by_idx.9 \ + ofw_graph.9 ofw_graph_get_port_by_idx.9 \ + ofw_graph.9 ofw_graph_get_remove_endpoint.9 \ + ofw_graph.9 ofw_graph_get_remove_parent.9 \ + ofw_graph.9 ofw_graph_port_get_num_endpoints.9 MLINKS+=osd.9 osd_call.9 \ osd.9 osd_del.9 \ osd.9 osd_deregister.9 \ @@ -2334,9 +2352,7 @@ MLINKS+=vm_map_lookup.9 vm_map_lookup_done.9 MLINKS+=vm_map_max.9 vm_map_min.9 \ vm_map_max.9 vm_map_pmap.9 MLINKS+=vm_map_stack.9 vm_map_growstack.9 -MLINKS+=vm_map_wire.9 vm_map_wire_mapped.9 \ - vm_page_wire.9 vm_page_unwire.9 \ - vm_page_wire.9 vm_page_unwire_noq.9 +MLINKS+=vm_map_wire.9 vm_map_unwire.9 MLINKS+=vm_page_alloc.9 vm_page_alloc_after.9 \ vm_page_alloc.9 vm_page_alloc_contig.9 \ vm_page_alloc.9 vm_page_alloc_contig_domain.9 \ @@ -2375,7 +2391,9 @@ MLINKS+=vm_page_free.9 vm_page_free_toq.9 \ vm_page_free.9 vm_page_free_zero.9 \ vm_page_free.9 vm_page_try_to_free.9 MLINKS+=vm_page_insert.9 vm_page_remove.9 -MLINKS+=vm_page_wire.9 vm_page_unwire.9 +MLINKS+=vm_page_wire.9 vm_page_unwire.9 \ + vm_page_wire.9 vm_page_unwire_noq.9 \ + vm_page_wire.9 vm_page_wire_mapped.9 MLINKS+=VOP_ACCESS.9 VOP_ACCESSX.9 MLINKS+=VOP_ATTRIB.9 VOP_GETATTR.9 \ VOP_ATTRIB.9 VOP_SETATTR.9 \ @@ -2436,7 +2454,6 @@ MLINKS+=superio.9 superio_devid.9 \ superio.9 superio_dev_enable.9 \ superio.9 superio_dev_enabled.9 \ superio.9 superio_find_dev.9 \ - superio.9 superio_find_dev.9 \ superio.9 superio_get_dma.9 \ superio.9 superio_get_iobase.9 \ superio.9 superio_get_irq.9 \ diff --git a/share/man/man9/VOP_LOCK.9 b/share/man/man9/VOP_LOCK.9 index db4608037ade..7368ebd49ccf 100644 --- a/share/man/man9/VOP_LOCK.9 +++ b/share/man/man9/VOP_LOCK.9 @@ -28,7 +28,7 @@ .\" .\" $FreeBSD$ .\" -.Dd February 25, 2008 +.Dd August 23, 2022 .Dt VOP_LOCK 9 .Os .Sh NAME @@ -44,7 +44,7 @@ .Ft int .Fn VOP_LOCK "struct vnode *vp" "int flags" .Ft int -.Fn VOP_UNLOCK "struct vnode *vp" "int flags" +.Fn VOP_UNLOCK "struct vnode *vp" .Ft int .Fn VOP_ISLOCKED "struct vnode *vp" .Ft int diff --git a/share/man/man9/cpuset.9 b/share/man/man9/cpuset.9 index 29dbc8fc733b..1320cd9f4350 100644 --- a/share/man/man9/cpuset.9 +++ b/share/man/man9/cpuset.9 @@ -24,7 +24,7 @@ .\" .\" $FreeBSD$ .\" -.Dd December 12, 2019 +.Dd September 23, 2022 .Dt CPUSET 9 .Os .Sh NAME @@ -110,9 +110,9 @@ Each CPU is represented by a single bit. The maximum number of CPUs representable by .Vt cpuset_t is -.Va MAXCPU . +.Va CPU_SETSIZE . Individual CPUs in cpusets are referenced with indices zero through -.Fa MAXCPU - 1 . +.Fa CPU_SETSIZE - 1 . .Pp The .Fn CPUSET_T_INITIALIZER diff --git a/share/man/man9/crypto_request.9 b/share/man/man9/crypto_request.9 index 1b7379245608..cb4d07189394 100644 --- a/share/man/man9/crypto_request.9 +++ b/share/man/man9/crypto_request.9 @@ -30,7 +30,7 @@ .\" .\" $FreeBSD$ .\" -.Dd January 4, 2022 +.Dd November 2, 2022 .Dt CRYPTO_REQUEST 9 .Os .Sh NAME @@ -441,17 +441,12 @@ the callback is invoked synchronously if the request was processed by a software driver or asynchronously if the request was processed by a hardware driver. .Pp -If a request was scheduled to the taskqueue via -.Dv CRYPTO_F_ASYNC , +If a request was scheduled to the taskqueue with +.Dv CRYPTO_ASYNC_ORDERED , callbacks are always invoked asynchronously ignoring .Dv CRYPTO_F_CBIMM and .Dv CRYPTO_F_CBIFSYNC . -In this case, -.Dv CRYPTO_F_ASYNC_KEEPORDER -may be set to ensure that callbacks for requests on a given session are -invoked in the same order that requests were queued to the session via -.Fn crypto_dispatch . This flag is used by IPsec to ensure that decrypted network packets are passed up the network stack in roughly the same order they were received. .Ss Other Request Fields diff --git a/share/man/man9/device_get_property.9 b/share/man/man9/device_get_property.9 index d925f5f224db..93c01f199477 100644 --- a/share/man/man9/device_get_property.9 +++ b/share/man/man9/device_get_property.9 @@ -25,7 +25,7 @@ .\" .\" $FreeBSD$ .\" -.Dd February 18, 2022 +.Dd September 29, 2022 .Dt DEVICE_GET_PROPERTY 9 .Os .Sh NAME @@ -54,6 +54,9 @@ Currently the following types are supported: The underlying property is a string of bytes. .It Dv DEVICE_PROP_ANY Wildcard property type. +.It Dv DEVICE_PROP_HANDLE +Following a reference the underlying property is a handle of the +respective bus. .It Dv DEVICE_PROP_UINT32 The underlying property is an array of unsigned 32 bit integers. The 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 <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 @@ -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 . diff --git a/share/man/man9/ifnet.9 b/share/man/man9/ifnet.9 index dd203cb5580b..a1a8acdc5b0b 100644 --- a/share/man/man9/ifnet.9 +++ b/share/man/man9/ifnet.9 @@ -736,9 +736,9 @@ This Ethernet interface supports TCP6 Segmentation offloading. A shorthand for .Pq Dv IFCAP_TSO4 | IFCAP_TSO6 . .It Dv IFCAP_TOE4 -This Ethernet interface supports TCP offloading. +This Ethernet interface supports TCP4 Offload Engine. .It Dv IFCAP_TOE6 -This Ethernet interface supports TCP6 offloading. +This Ethernet interface supports TCP6 Offload Engine. .It Dv IFCAP_TOE A shorthand for .Pq Dv IFCAP_TOE4 | IFCAP_TOE6 . @@ -753,13 +753,6 @@ as those sent by .It Dv IFCAP_WOL A shorthand for .Pq Dv IFCAP_WOL_UCAST | IFCAP_WOL_MCAST | IFCAP_WOL_MAGIC . -.It Dv IFCAP_TOE4 -This Ethernet interface supports TCP4 Offload Engine. -.It Dv IFCAP_TOE6 -This Ethernet interface supports TCP6 Offload Engine. -.It Dv IFCAP_TOE -A shorthand for -.Pq Dv IFCAP_TOE4 | IFCAP_TOE6 . .It Dv IFCAP_VLAN_HWFILTER This interface supports frame filtering in hardware on .Xr vlan 4 diff --git a/share/man/man9/intr_event.9 b/share/man/man9/intr_event.9 new file mode 100644 index 000000000000..70ea1e1bfc43 --- /dev/null +++ b/share/man/man9/intr_event.9 @@ -0,0 +1,475 @@ +.\" Copyright (c) 2001 John H. Baldwin <jhb@FreeBSD.org> +.\" Copyright (c) 2006 Tom Rhodes <trhodes@FreeBSD.org> +.\" Copyright (c) 2021 Mitchell Horne <mhorne@FreeBSD.org> +.\" Copyright (c) 2022 The FreeBSD Foundation +.\" +.\" Portions of this documentation were written by Mitchell Horne +.\" under sponsorship from the FreeBSD Foundation. +.\" +.\" 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 October 30, 2022 +.Dt INTR_EVENT 9 +.Os +.Sh NAME +.Nm intr_event_add_handler , +.Nm intr_event_create , +.Nm intr_event_destroy , +.Nm intr_event handle , +.Nm intr_event_remove_handler , +.Nm intr_priority +.Nd "kernel interrupt handler and thread API" +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.In sys/interrupt.h +.Ft int +.Fo intr_event_add_handler +.Fa "struct intr_event *ie" +.Fa "const char *name" +.Fa "driver_filter_t filter" +.Fa "driver_intr_t handler" +.Fa "void *arg" +.Fa "u_char pri" +.Fa "enum intr_type flags" +.Fa "void **cookiep" +.Fc +.Ft int +.Fo intr_event_create +.Fa "struct intr_event **event" +.Fa "void *source" +.Fa "int flags" +.Fa "int irq" +.Fa "void (*pre_ithread)(void *)" +.Fa "void (*post_ithread)(void *)" +.Fa "void (*post_filter)(void *)" +.Fa "int (*assign_cpu)(void *, int)" +.Fa "const char *fmt" +.Fa "..." +.Fc +.Ft int +.Fn intr_event_destroy "struct intr_event *ie" +.Ft int +.Fn intr_event_handle "struct intr_event *ie" "struct trapframe *frame" +.Ft int +.Fn intr_event_remove_handler "void *cookie" +.Ft u_char +.Fn intr_priority "enum intr_type flags" +.Sh DESCRIPTION +The interrupt event API provides methods to manage the registration and +execution of interrupt handlers and their associated thread contexts. +.Pp +Each interrupt event in the system corresponds to a single hardware or software +interrupt source. +Each interrupt event maintains a list of interrupt handlers, sorted by +priority, which will be invoked when handling the event. +An interrupt event will typically, but not always, have an associated +.Xr kthread 9 , +known as the interrupt thread. +Finally, each event contains optional callback functions which will be +invoked before and after the handler functions themselves. +.Pp +An interrupt handler contains two distinct handler functions: +the +.Em filter +and the thread +.Em handler . +The +.Em filter +function is run from interrupt context and is intended to perform quick +handling such as acknowledging or masking a hardware interrupt, +and queueing work for the ensuing thread +.Em handler . +Both functions are optional; each interrupt handler may choose to register a +filter, a thread handler, or both. +Each interrupt handler also consists of a name, +a set of flags, +and an opaque argument which will be passed to both the +.Em filter +and +.Em handler +functions. +.Ss Handler Constraints +The +.Em filter +function is executed inside a +.Xr critical 9 +section. +Therefore, filters may not yield the CPU for any reason, and may only use spin +locks to access shared data. +Allocating memory within a filter is not permitted. +.Pp +The +.Em handler +function executes from the context of the associated interrupt kernel thread. +Sleeping is not permitted, but the interrupt thread may be preempted by higher +priority threads. +Thus, threaded handler functions may obtain non-sleepable locks, as described +in +.Xr locking 9 . +Any memory or zone allocations in an interrupt thread must specify the +.Dv M_NOWAIT +flag, and any allocation errors must be handled. +.Pp +The exception to these constraints is software interrupt threads, which are +allowed to sleep but should be allocated and scheduled using the +.Xr swi 9 +interface. +.Ss Function Descriptions +The +.Fn intr_event_create +function creates a new interrupt event. +The +.Fa event +argument points to a +.Vt struct intr_event +pointer that will reference the newly created event upon success. +The +.Fa source +argument is an opaque pointer which will be passed to the +.Fa pre_ithread , +.Fa post_ithread , +and +.Fa post_filter +callbacks. +The +.Fa flags +argument is a mask of properties of this thread. +The only valid flag currently for +.Fn intr_event_create +is +.Dv IE_SOFT +to specify that this interrupt thread is a software interrupt. +The +.Fa enable +and +.Fa disable +arguments specify optional functions used to enable and disable this +interrupt thread's interrupt source. +The +.Fa irq +argument is the unique interrupt vector number corresponding to the event. +The +.Fa pre_ithread , +.Fa post_ithread , +and +.Fa post_filter +arguments are callback functions that are invoked at different +points while handling an interrupt. +This is described in more detail in the +.Sx Handler Callbacks +section, below. +They may be +.Va NULL +to specify no callback. +The +.Fa assign_cpu +argument points to a callback function that will be invoked when binding +an interrupt to a particular CPU. +It may be +.Va NULL +if binding is unsupported. +The +remaining arguments form a +.Xr printf 9 +argument list that is used to build the base name of the new interrupt thread. +The full name of an interrupt thread is formed by concatenating the base +name of the interrupt thread with the names of all of its interrupt handlers. +.Pp +The +.Fn intr_event_destroy +function destroys a previously created interrupt event by releasing its +resources. +.\" The following is not true (yet): +.\"and arranging for the backing kernel thread to terminate. +An interrupt event can only be destroyed if it has no handlers remaining. +.Pp +The +.Fn intr_event_add_handler +function adds a new handler to an existing interrupt event specified by +.Fa ie . +The +.Fa name +argument specifies a name for this handler. +The +.Fa filter +argument provide the filter function to execute. +The +.Fa handler +argument provides the handler function to be executed from the +event's interrupt thread. +The +.Fa arg +argument will be passed to the +.Fa filter +and +.Fa handler +functions when they are invoked. +The +.Fa pri +argument specifies the priority of this handler, +corresponding to the values defined in +.In sys/priority.h . +It determines the order this handler is called relative to the other handlers +for this event, as well as the scheduling priority of of the backing kernel +thread. +.Fa flags +argument can be used to specify properties of this handler as defined in +.In sys/bus.h . +If +.Fa cookiep +is not +.Dv NULL , +then it will be assigned a cookie that can be used later to remove this +handler. +.Pp +The +.Fn intr_event_handle +function is the main entry point into the interrupt handling code. +It must be called from an interrupt context. +The function will execute all filter handlers associated with the interrupt +event +.Fa ie , +and schedule the associated interrupt thread to run, if applicable. +The +.Fa frame +argument is used to pass a pointer to the +.Vt struct trapframe +containing the machine state at the time of the interrupt. +The main body of this function runs within a +.Xr critical 9 +section. +.Pp +The +.Fn intr_event_remove_handler +function removes an interrupt handler from the interrupt event specified by +.Fa ie . +The +.Fa cookie +argument, obtained from +.Fn intr_event_add_handler , +identifies the handler to remove. +.Pp +The +.Fn intr_priority +function translates the +.Dv INTR_TYPE_* +interrupt flags into interrupt thread scheduling priorities. +.Pp +The interrupt flags not related to the type of a particular interrupt +.Pq Dv INTR_TYPE_* +can be used to specify additional properties of both hardware and software +interrupt handlers. +The +.Dv INTR_EXCL +flag specifies that this handler cannot share an interrupt thread with +another handler. +The +.Dv INTR_MPSAFE +flag specifies that this handler is MP safe in that it does not need the +Giant mutex to be held while it is executed. +The +.Dv INTR_ENTROPY +flag specifies that the interrupt source this handler is tied to is a good +source of entropy, and thus that entropy should be gathered when an interrupt +from the handler's source triggers. +Presently, the +.Dv INTR_ENTROPY +flag is not valid for software interrupt handlers. +.Ss Handler Callbacks +Each +.Vt struct intr_event +is assigned three optional callback functions when it is created: +.Fa pre_ithread , +.Fa post_ithread , +and +.Fa post_filter . +These callbacks are intended to be defined by the interrupt controller driver, +to allow for actions such as masking and unmasking hardware interrupt signals. +.Pp +When an interrupt is triggered, all filters are run to determine if any +threaded interrupt handlers should be scheduled for execution by the associated +interrupt thread. If no threaded handlers are scheduled, the +.Fa post_filter +callback is invoked which should acknowledge the interrupt and permit it to +trigger in the future. +If any threaded handlers are scheduled, the +.Fa pre_ithread +callback is invoked instead. +This handler should acknowledge the interrupt, but it should also ensure that +the interrupt will not fire continuously until after the threaded handlers have +executed. +Typically this callback masks level-triggered interrupts in an interrupt +controller while leaving edge-triggered interrupts alone. +Once all threaded handlers have executed, +the +.Fa post_ithread +callback is invoked from the interrupt thread to enable future interrupts. +Typically this callback unmasks level-triggered interrupts in an interrupt +controller. +.Sh RETURN VALUES +The +.Fn intr_event_add_handler , +.Fn intr_event_create , +.Fn intr_event_destroy , +.Fn intr_event_handle , +and +.Fn intr_event_remove_handler +functions return zero on success and non-zero on failure. +The +.Fn intr_priority +function returns a process priority corresponding to the passed in interrupt +flags. +.Sh EXAMPLES +The +.Xr swi_add 9 +function demonstrates the use of +.Fn intr_event_create +and +.Fn intr_event_add_handler . +.Bd -literal -offset indent +int +swi_add(struct intr_event **eventp, const char *name, driver_intr_t handler, + void *arg, int pri, enum intr_type flags, void **cookiep) +{ + struct intr_event *ie; + int error = 0; + + if (flags & INTR_ENTROPY) + return (EINVAL); + + ie = (eventp != NULL) ? *eventp : NULL; + + if (ie != NULL) { + if (!(ie->ie_flags & IE_SOFT)) + return (EINVAL); + } else { + error = intr_event_create(&ie, NULL, IE_SOFT, 0, + NULL, NULL, NULL, swi_assign_cpu, "swi%d:", pri); + if (error) + return (error); + if (eventp != NULL) + *eventp = ie; + } + if (handler != NULL) { + error = intr_event_add_handler(ie, name, NULL, handler, arg, + PI_SWI(pri), flags, cookiep); + } + return (error); +} +.Ed +.Sh ERRORS +The +.Fn intr_event_add_handler +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa ie +or +.Fa name +arguments are +.Dv NULL . +.It Bq Er EINVAL +The +.Fa handler +and +.Fa filter +arguments are both +.Dv NULL . +.It Bq Er EINVAL +The +.Dv IH_EXCLUSIVE +flag is specified and the interrupt thread +.Fa ie +already has at least one handler, or the interrupt thread +.Fa ie +already has an exclusive handler. +.El +.Pp +The +.Fn intr_event_create +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +A flag other than +.Dv IE_SOFT +was specified in the +.Fa flags +parameter. +.El +.Pp +The +.Fn intr_event_destroy +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa ie +argument is +.Dv NULL . +.It Bq Er EBUSY +The interrupt event pointed to by +.Fa ie +has at least one handler which has not been removed with +.Fn intr_event_remove_handler . +.El +.Pp +The +.Fn intr_event_handle +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa ie +argument is +.Dv NULL . +.It Bq Er EINVAL +There are no interrupt handlers assigned to +.Fa ie . +.It Bq Er EINVAL +The interrupt was not acknowledged by any filter and has no associated thread +handler. +.El +.Pp +The +.Fn intr_event_remove_handler +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa cookie +argument is +.Dv NULL . +.El +.Sh SEE ALSO +.Xr critical 9 , +.Xr kthread 9 , +.Xr locking 9 , +.Xr malloc 9 , +.Xr swi 9 , +.Xr uma 9 +.Sh HISTORY +Interrupt threads and their corresponding API first appeared in +.Fx 5.0 . diff --git a/share/man/man9/ithread.9 b/share/man/man9/ithread.9 deleted file mode 100644 index 2a2e44f3d6af..000000000000 --- a/share/man/man9/ithread.9 +++ /dev/null @@ -1,350 +0,0 @@ -.\" Copyright (c) 2001 John H. Baldwin <jhb@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, 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 August 25, 2006 -.Dt ITHREAD 9 -.Os -.Sh NAME -.Nm ithread_add_handler , -.Nm ithread_create , -.Nm ithread_destroy , -.Nm ithread_priority , -.Nm ithread_remove_handler , -.Nm ithread_schedule -.Nd kernel interrupt threads -.Sh SYNOPSIS -.In sys/param.h -.In sys/bus.h -.In sys/interrupt.h -.Ft int -.Fo ithread_add_handler -.Fa "struct ithd *ithread" -.Fa "const char *name" -.Fa "driver_intr_t handler" -.Fa "void *arg" -.Fa "u_char pri" -.Fa "enum intr_type flags" -.Fa "void **cookiep" -.Fc -.Ft int -.Fo ithread_create -.Fa "struct ithd **ithread" -.Fa "int vector" -.Fa "int flags" -.Fa "void (*disable)(int)" -.Fa "void (*enable)(int)" -.Fa "const char *fmt" -.Fa "..." -.Fc -.Ft int -.Fn ithread_destroy "struct ithd *ithread" -.Ft u_char -.Fn ithread_priority "enum intr_type flags" -.Ft int -.Fn ithread_remove_handler "void *cookie" -.Ft int -.Fn ithread_schedule "struct ithd *ithread" "int do_switch" -.Sh DESCRIPTION -Interrupt threads are kernel threads that run a list of handlers when -triggered by either a hardware or software interrupt. -Each interrupt handler has a name, handler function, handler argument, -priority, and various flags. -Each interrupt thread maintains a list of handlers sorted by priority. -This results in higher priority handlers being executed prior to lower -priority handlers. -Each thread assumes the priority of its highest priority handler for its -process priority, or -.Dv PRIO_MAX -if it has no handlers. -Interrupt threads are also associated with a single interrupt source, -represented as a vector number. -.Pp -The -.Fn ithread_create -function creates a new interrupt thread. -The -.Fa ithread -argument points to an -.Vt struct ithd -pointer that will point to the newly created thread upon success. -The -.Fa vector -argument specifies the interrupt source to associate this thread with. -The -.Fa flags -argument is a mask of properties of this thread. -The only valid flag currently for -.Fn ithread_create -is -.Dv IT_SOFT -to specify that this interrupt thread is a software interrupt. -The -.Fa enable -and -.Fa disable -arguments specify optional functions used to enable and disable this -interrupt thread's interrupt source. -The functions receive the vector corresponding to the thread's interrupt -source as their only argument. -The remaining arguments form a -.Xr printf 9 -argument list that is used to build the base name of the new ithread. -The full name of an interrupt thread is formed by concatenating the base -name of an interrupt thread with the names of all of its interrupt handlers. -.Pp -The -.Fn ithread_destroy -function destroys a previously created interrupt thread by releasing its -resources and arranging for the backing kernel thread to terminate. -An interrupt thread can only be destroyed if it has no handlers remaining. -.Pp -The -.Fn ithread_add_handler -function adds a new handler to an existing interrupt thread specified by -.Fa ithread . -The -.Fa name -argument specifies a name for this handler. -The -.Fa handler -and -.Fa arg -arguments provide the function to execute for this handler and an argument -to pass to it. -The -.Fa pri -argument specifies the priority of this handler and is used both in sorting -it in relation to the other handlers for this thread and to specify the -priority of the backing kernel thread. -The -.Fa flags -argument can be used to specify properties of this handler as defined in -.In sys/bus.h . -If -.Fa cookiep -is not -.Dv NULL , -then it will be assigned a cookie that can be used later to remove this -handler. -.Pp -The -.Fn ithread_remove_handler -removes a handler from an interrupt thread. -The -.Fa cookie -argument specifies the handler to remove from its thread. -.Pp -The -.Fn ithread_schedule -function schedules an interrupt thread to run. -If the -.Fa do_switch -argument is non-zero and the interrupt thread is idle, then a context switch -will be forced after putting the interrupt thread on the run queue. -.Pp -The -.Fn ithread_priority -function translates the -.Dv INTR_TYPE_* -interrupt flags into interrupt handler priorities. -.Pp -The interrupt flags not related to the type of a particular interrupt -.Pq Dv INTR_TYPE_* -can be used to specify additional properties of both hardware and software -interrupt handlers. -The -.Dv INTR_EXCL -flag specifies that this handler cannot share an interrupt thread with -another handler. -The -.Dv INTR_MPSAFE -flag specifies that this handler is MP safe in that it does not need the -Giant mutex to be held while it is executed. -The -.Dv INTR_ENTROPY -flag specifies that the interrupt source this handler is tied to is a good -source of entropy, and thus that entropy should be gathered when an interrupt -from the handler's source triggers. -Presently, the -.Dv INTR_ENTROPY -flag is not valid for software interrupt handlers. -.Pp -It is not permitted to sleep in an interrupt thread; hence, any memory -or zone allocations in an interrupt thread should be specified with the -.Dv M_NOWAIT -flag set. -Any allocation errors must be handled thereafter. -.Sh RETURN VALUES -The -.Fn ithread_add_handler , -.Fn ithread_create , -.Fn ithread_destroy , -.Fn ithread_remove_handler , -and -.Fn ithread_schedule -functions return zero on success and non-zero on failure. -The -.Fn ithread_priority -function returns a process priority corresponding to the passed in interrupt -flags. -.Sh EXAMPLES -The -.Fn swi_add -function demonstrates the use of -.Fn ithread_create -and -.Fn ithread_add_handler . -.Bd -literal -offset indent -int -swi_add(struct ithd **ithdp, const char *name, driver_intr_t handler, - void *arg, int pri, enum intr_type flags, void **cookiep) -{ - struct proc *p; - struct ithd *ithd; - int error; - - if (flags & INTR_ENTROPY) - return (EINVAL); - - ithd = (ithdp != NULL) ? *ithdp : NULL; - - if (ithd != NULL) { - if ((ithd->it_flags & IT_SOFT) == 0) - return(EINVAL); - } else { - error = ithread_create(&ithd, pri, IT_SOFT, NULL, NULL, - "swi%d:", pri); - if (error) - return (error); - - if (ithdp != NULL) - *ithdp = ithd; - } - return (ithread_add_handler(ithd, name, handler, arg, pri + PI_SOFT, - flags, cookiep)); -} -.Ed -.Sh ERRORS -The -.Fn ithread_add_handler -function will fail if: -.Bl -tag -width Er -.It Bq Er EINVAL -Any of the -.Fa ithread , -.Fa handler , -or -.Fa name -arguments are -.Dv NULL . -.It Bq Er EINVAL -The -.Dv INTR_EXCL -flag is specified and the interrupt thread -.Fa ithread -already has at least one handler, or the interrupt thread -.Fa ithread -already has an exclusive handler. -.It Bq Er ENOMEM -Could not allocate needed memory for this handler. -.El -.Pp -The -.Fn ithread_create -function will fail if: -.Bl -tag -width Er -.It Bq Er EAGAIN -The system-imposed limit on the total -number of processes under execution would be exceeded. -The limit is given by the -.Xr sysctl 3 -MIB variable -.Dv KERN_MAXPROC . -.It Bq Er EINVAL -A flag other than -.Dv IT_SOFT -was specified in the -.Fa flags -parameter. -.It Bq Er ENOMEM -Could not allocate needed memory for this interrupt thread. -.El -.Pp -The -.Fn ithread_destroy -function will fail if: -.Bl -tag -width Er -.It Bq Er EINVAL -The -.Fa ithread -argument is -.Dv NULL . -.It Bq Er EINVAL -The interrupt thread pointed to by -.Fa ithread -has at least one handler. -.El -.Pp -The -.Fn ithread_remove_handler -function will fail if: -.Bl -tag -width Er -.It Bq Er EINVAL -The -.Fa cookie -argument is -.Dv NULL . -.El -.Pp -The -.Fn ithread_schedule -function will fail if: -.Bl -tag -width Er -.It Bq Er EINVAL -The -.Fa ithread -argument is -.Dv NULL . -.It Bq Er EINVAL -The interrupt thread pointed to by -.Fa ithread -has no interrupt handlers. -.El -.Sh SEE ALSO -.Xr kthread 9 , -.Xr malloc 9 , -.Xr swi 9 , -.Xr uma 9 -.Sh HISTORY -Interrupt threads and their corresponding API first appeared in -.Fx 5.0 . -.Sh BUGS -Currently -.Vt struct ithd -represents both an interrupt source and an interrupt thread. -There should be a separate -.Vt struct isrc -that contains a vector number, enable and disable functions, etc.\& that -an ithread holds a reference to. diff --git a/share/man/man9/kqueue.9 b/share/man/man9/kqueue.9 index 53f55b8efe03..15a430d4a5a3 100644 --- a/share/man/man9/kqueue.9 +++ b/share/man/man9/kqueue.9 @@ -24,14 +24,14 @@ .\" .\" $FreeBSD$ .\" -.Dd October 12, 2021 +.Dd August 20, 2022 .Dt KQUEUE 9 .Os .Sh NAME .Nm kqueue_add_filteropts , kqueue_del_filteropts , .Nm kqfd_register , .Nm knote_fdclose , -.Nm knlist_init , knlist_init_mtx , knlist_init_rw_reader , +.Nm knlist_init , knlist_init_mtx , .Nm knlist_add , knlist_remove , knlist_remove_inevent , knlist_empty , .Nm knlist_clear , knlist_delete , knlist_destroy , .Nm KNOTE_LOCKED , KNOTE_UNLOCKED @@ -57,8 +57,6 @@ .Ft void .Fn knlist_init_mtx "struct knlist *knl" "struct mtx *lock" .Ft void -.Fn knlist_init_rw_reader "struct knlist *knl" "struct rwlock *lock" -.Ft void .Fn knlist_add "struct knlist *knl" "struct knote *kn" "int islocked" .Ft void .Fn knlist_remove "struct knlist *knl" "struct knote *kn" "int islocked" @@ -260,10 +258,9 @@ is not required, but is commonly used. If used, the .Vt knlist must be initialized with either -.Fn knlist_init , -.Fn knlist_init_mtx +.Fn knlist_init or -.Fn knlist_init_rw_reader . +.Fn knlist_init_mtx . The .Vt knlist structure may be embedded into the object structure. @@ -308,19 +305,6 @@ style lock. .Pp The function -.Fn knlist_init_rw_reader -may be used to initialize a -.Vt knlist -when -.Fa lock -is a -.Xr rwlock 9 -read lock. -Lock is acquired via -.Fn rw_rlock -function. -.Pp -The function .Fn knlist_empty returns true when there are no .Vt knotes diff --git a/share/man/man9/ktr.9 b/share/man/man9/ktr.9 index cfe9cacf8611..2bb6f9991ee9 100644 --- a/share/man/man9/ktr.9 +++ b/share/man/man9/ktr.9 @@ -61,7 +61,7 @@ style fashion. These events can then be dumped with .Xr ddb 4 , -.Xr gdb 1 +.Xr gdb 1 Pq Pa ports/devel/gdb or .Xr ktrdump 8 . .Pp diff --git a/share/man/man9/malloc.9 b/share/man/man9/malloc.9 index c240344ea77e..26dcf3081f3e 100644 --- a/share/man/man9/malloc.9 +++ b/share/man/man9/malloc.9 @@ -29,16 +29,25 @@ .\" $NetBSD: malloc.9,v 1.3 1996/11/11 00:05:11 lukem Exp $ .\" $FreeBSD$ .\" -.Dd July 2, 2021 +.Dd October 12, 2022 .Dt MALLOC 9 .Os .Sh NAME .Nm malloc , +.Nm mallocarray , .Nm free , +.Nm zfree , .Nm realloc , .Nm reallocf , +.Nm malloc_usable_size , +.Nm malloc_aligned , +.Nm malloc_exec , +.Nm MALLOC_DECLARE , .Nm MALLOC_DEFINE , -.Nm MALLOC_DECLARE +.Nm malloc_domainset , +.Nm malloc_domainset_aligned , +.Nm malloc_domainset_exec , +.Nm mallocarray_domainset .Nd kernel memory management routines .Sh SYNOPSIS .In sys/types.h @@ -73,6 +82,7 @@ .Fn MALLOC_DEFINE type shortdesc longdesc .In sys/param.h .In sys/domainset.h +.In sys/malloc.h .Ft void * .Fn malloc_domainset "size_t size" "struct malloc_type *type" "struct domainset *ds" "int flags" .Ft void * @@ -116,7 +126,8 @@ Both and .Fn malloc_domainset_exec can be used to return executable memory. -Not all platforms enforce a distinction between executable and non-executable memory. +Not all platforms enforce a distinction between executable and non-executable +memory. .Pp The .Fn mallocarray diff --git a/share/man/man9/refcount.9 b/share/man/man9/refcount.9 index 9171062a70b6..0b5a26d6e3cd 100644 --- a/share/man/man9/refcount.9 +++ b/share/man/man9/refcount.9 @@ -32,7 +32,7 @@ .\" .\" $FreeBSD$ .\" -.Dd November 2, 2020 +.Dd October 12, 2022 .Dt REFCOUNT 9 .Os .Sh NAME @@ -48,7 +48,7 @@ .Fn refcount_init "volatile u_int *count" "u_int value" .Ft u_int .Fn refcount_load "volatile u_int *count" -.Ft void +.Ft u_int .Fn refcount_acquire "volatile u_int *count" .Ft bool .Fn refcount_acquire_checked "volatile u_int *count" @@ -91,6 +91,7 @@ qualifier. The .Fn refcount_acquire function is used to acquire a new reference. +It returns the counter value before the new reference was acquired. The caller is responsible for ensuring that it holds a valid reference while obtaining a new reference. For example, diff --git a/share/man/man9/sbuf.9 b/share/man/man9/sbuf.9 index 071e6f11e02e..fbef2d7ee168 100644 --- a/share/man/man9/sbuf.9 +++ b/share/man/man9/sbuf.9 @@ -358,7 +358,7 @@ function returns the current user flags. The .Fn sbuf_set_flags and -.Fn sbuf_get_flags +.Fn sbuf_clear_flags functions set or clear one or more user flags, respectively. The user flags are described under the .Fn sbuf_new diff --git a/share/man/man9/socket.9 b/share/man/man9/socket.9 index 1c3f75785013..3c24efb75dc9 100644 --- a/share/man/man9/socket.9 +++ b/share/man/man9/socket.9 @@ -26,7 +26,7 @@ .\" .\" $FreeBSD$ .\" -.Dd October 18, 2018 +.Dd September 6, 2022 .Dt SOCKET 9 .Os .Sh NAME @@ -171,8 +171,7 @@ are only useful for protocol implementors. .Pp Except where otherwise indicated, .Nm -functions may sleep, and are not appropriate for use in an -.Xr ithread 9 +functions may sleep, and are not appropriate for use in an interrupt thread context or while holding non-sleepable kernel locks. .Ss Creating and Destroying Sockets A new socket may be created using @@ -461,10 +460,8 @@ argument, and use the same flag name space as the .Xr sendmsg 2 system call. .Pp -Kernel callers running in -.Xr ithread 9 -context, or with a mutex held, will wish to use non-blocking sockets and pass -the +Kernel callers running in an interrupt thread context, or with a mutex held, +will wish to use non-blocking sockets and pass the .Dv MSG_DONTWAIT flag in order to prevent these functions from sleeping. .Pp @@ -593,7 +590,7 @@ data between user and kernel code. .Xr shutdown 2 , .Xr socket 2 , .Xr ng_ksocket 4 , -.Xr ithread 9 , +.Xr intr_event 9 , .Xr msleep 9 , .Xr ucred 9 .Sh HISTORY diff --git a/share/man/man9/swi.9 b/share/man/man9/swi.9 index 52a39fe61c86..6875fc890696 100644 --- a/share/man/man9/swi.9 +++ b/share/man/man9/swi.9 @@ -23,7 +23,7 @@ .\" .\" $FreeBSD$ .\" -.Dd July 25, 2020 +.Dd October 12, 2022 .Dt SWI 9 .Os .Sh NAME @@ -35,9 +35,7 @@ .In sys/param.h .In sys/bus.h .In sys/interrupt.h -.Vt "extern struct intr_event *tty_intr_event" ; .Vt "extern struct intr_event *clk_intr_event" ; -.Vt "extern void *vm_ih" ; .Ft int .Fo swi_add .Fa "struct intr_event **eventp" @@ -140,12 +138,6 @@ Instead, .Fa handler will be executed the next time that the software interrupt thread runs after being scheduled by another event. -Attaching a handler to the clock software interrupt thread and using this flag -when scheduling a software interrupt handler can be used to implement the -functionality performed by -.Fn setdelayed -in earlier versions of -.Fx . .It Dv SWI_FROMNMI Specifies that .Fn swi_sched @@ -155,24 +147,12 @@ On platforms allowing IPI sending from NMI context it immediately wakes via the IPI, otherwise it works just like SWI_DELAY. .El .Pp -The -.Va tty_intr_event -and -.Va clk_intr_event -variables contain pointers to the software interrupt handlers for the tty and -clock software interrupts, respectively. -.Va tty_intr_event -is used to hang tty software interrupt handlers off of the same thread. .Va clk_intr_event -is used to hang delayed handlers off of the clock software interrupt thread so -that the functionality of -.Fn setdelayed -can be obtained in conjunction with -.Dv SWI_DELAY . -The -.Va vm_ih -handler cookie is used to schedule software interrupt threads to run for the -VM subsystem. +is a pointer to the +.Vt struct intr_event +used to hang delayed handlers off of the clock interrupt, and is invoked +directly by +.Xr hardclock 9 . .Sh RETURN VALUES The .Fn swi_add @@ -227,7 +207,8 @@ is .Dv NULL . .El .Sh SEE ALSO -.Xr ithread 9 , +.Xr hardclock 9 , +.Xr intr_event 9 , .Xr taskqueue 9 .Sh HISTORY The @@ -250,7 +231,3 @@ The .Fn swi_remove function first appeared in .Fx 6.1 . -.Sh BUGS -Most of the global variables described in this manual page should not be -global, or at the very least should not be declared in -.In sys/interrupt.h . diff --git a/share/man/man9/vaccess.9 b/share/man/man9/vaccess.9 index 4bf377406903..85ee4cbdd692 100644 --- a/share/man/man9/vaccess.9 +++ b/share/man/man9/vaccess.9 @@ -25,7 +25,7 @@ .\" .\" $FreeBSD$ .\" -.Dd September 18, 2009 +.Dd August 23, 2022 .Dt VACCESS 9 .Os .Sh NAME @@ -42,7 +42,6 @@ .Fa "gid_t file_gid" .Fa "accmode_t accmode" .Fa "struct ucred *cred" -.Fa "int *privused" .Fc .Sh DESCRIPTION This call implements the logic for the @@ -59,19 +58,9 @@ owning UID owning GID .Fa file_gid , desired access mode -.Fa accmode , -requesting credential -.Fa cred , -and an optional call-by-reference -.Vt int -pointer returning whether or not -privilege was required for successful evaluation of the call; the -.Fa privused -pointer may be set to -.Dv NULL -by the caller in order not to be informed of -privilege information, or it may point to an integer that will be set to -1 if privilege is used, and 0 otherwise. +.Fa accmode +and requesting credential +.Fa cred . .Pp This call is intended to support implementations of .Xr VOP_ACCESS 9 , diff --git a/share/man/man9/zone.9 b/share/man/man9/zone.9 index e26b29976807..5c1b4d31d8aa 100644 --- a/share/man/man9/zone.9 +++ b/share/man/man9/zone.9 @@ -50,7 +50,7 @@ typedef void (*uma_free)(void *item, vm_size_t size, uint8_t pflag); .Ed .Ft uma_zone_t .Fo uma_zcreate -.Fa "char *name" "int size" +.Fa "char *name" "size_t size" .Fa "uma_ctor ctor" "uma_dtor dtor" "uma_init zinit" "uma_fini zfini" .Fa "int align" "uint16_t flags" .Fc |