diff --git a/share/man/man3/arb.3 b/share/man/man3/arb.3 index 9cce8940cdd1..e33ef3a37f7d 100644 --- a/share/man/man3/arb.3 +++ b/share/man/man3/arb.3 @@ -1,511 +1,511 @@ .\" $OpenBSD: tree.3,v 1.7 2002/06/12 01:09:20 provos Exp $ .\" .\" Copyright 2002 Niels Provos .\" Copyright 2018-2019 Netflix, Inc. .\" 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. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by Niels Provos. .\" 4. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 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 October 14, 2019 .Dt ARB 3 .Os .Sh NAME .Nm ARB_PROTOTYPE , .Nm ARB_PROTOTYPE_STATIC , .Nm ARB_PROTOTYPE_INSERT , .Nm ARB_PROTOTYPE_INSERT_COLOR , .Nm ARB_PROTOTYPE_REMOVE , .Nm ARB_PROTOTYPE_REMOVE_COLOR , .Nm ARB_PROTOTYPE_FIND , .Nm ARB_PROTOTYPE_NFIND , .Nm ARB_PROTOTYPE_NEXT , .Nm ARB_PROTOTYPE_PREV , .Nm ARB_PROTOTYPE_MINMAX , .Nm ARB_PROTOTYPE_REINSERT , .Nm ARB_GENERATE , .Nm ARB_GENERATE_STATIC , .Nm ARB_GENERATE_INSERT , .Nm ARB_GENERATE_INSERT_COLOR , .Nm ARB_GENERATE_REMOVE , .Nm ARB_GENERATE_REMOVE_COLOR , .Nm ARB_GENERATE_FIND , .Nm ARB_GENERATE_NFIND , .Nm ARB_GENERATE_NEXT , .Nm ARB_GENERATE_PREV , .Nm ARB_GENERATE_MINMAX , .Nm ARB_GENERATE_REINSERT , .Nm ARB8_ENTRY , .Nm ARB16_ENTRY , .Nm ARB32_ENTRY , .Nm ARB8_HEAD , .Nm ARB16_HEAD , .Nm ARB32_HEAD , .Nm ARB_ALLOCSIZE , .Nm ARB_INITIALIZER , .Nm ARB_ROOT , .Nm ARB_EMPTY , .Nm ARB_FULL , .Nm ARB_CURNODES , .Nm ARB_MAXNODES , .Nm ARB_NEXT , .Nm ARB_PREV , .Nm ARB_MIN , .Nm ARB_MAX , .Nm ARB_FIND , .Nm ARB_NFIND , .Nm ARB_LEFT , .Nm ARB_LEFTIDX , .Nm ARB_RIGHT , .Nm ARB_RIGHTIDX , .Nm ARB_PARENT , .Nm ARB_PARENTIDX , .Nm ARB_GETFREE , .Nm ARB_FREEIDX , .Nm ARB_FOREACH , .Nm ARB_FOREACH_FROM , .Nm ARB_FOREACH_SAFE , .Nm ARB_FOREACH_REVERSE , .Nm ARB_FOREACH_REVERSE_FROM , .Nm ARB_FOREACH_REVERSE_SAFE , .Nm ARB_INIT , .Nm ARB_INSERT , .Nm ARB_REMOVE , .Nm ARB_REINSERT , .Nm ARB_RESET_TREE .Nd "array-based red-black trees" .Sh SYNOPSIS .In sys/arb.h .Fn ARB_PROTOTYPE NAME TYPE FIELD CMP .Fn ARB_PROTOTYPE_STATIC NAME TYPE FIELD CMP .Fn ARB_PROTOTYPE_INSERT NAME TYPE ATTR .Fn ARB_PROTOTYPE_INSERT_COLOR NAME TYPE ATTR .Fn ARB_PROTOTYPE_REMOVE NAME TYPE ATTR .Fn ARB_PROTOTYPE_REMOVE_COLOR NAME TYPE ATTR .Fn ARB_PROTOTYPE_FIND NAME TYPE ATTR .Fn ARB_PROTOTYPE_NFIND NAME TYPE ATTR .Fn ARB_PROTOTYPE_NEXT NAME TYPE ATTR .Fn ARB_PROTOTYPE_PREV NAME TYPE ATTR .Fn ARB_PROTOTYPE_MINMAX NAME TYPE ATTR .Fn ARB_PROTOTYPE_REINSERT NAME TYPE ATTR .Fn ARB_GENERATE NAME TYPE FIELD CMP .Fn ARB_GENERATE_STATIC NAME TYPE FIELD CMP .Fn ARB_GENERATE_INSERT NAME TYPE FIELD CMP ATTR .Fn ARB_GENERATE_INSERT_COLOR NAME TYPE FIELD ATTR .Fn ARB_GENERATE_REMOVE NAME TYPE FIELD ATTR .Fn ARB_GENERATE_REMOVE_COLOR NAME TYPE FIELD ATTR .Fn ARB_GENERATE_FIND NAME TYPE FIELD CMP ATTR .Fn ARB_GENERATE_NFIND NAME TYPE FIELD CMP ATTR .Fn ARB_GENERATE_NEXT NAME TYPE FIELD ATTR .Fn ARB_GENERATE_PREV NAME TYPE FIELD ATTR .Fn ARB_GENERATE_MINMAX NAME TYPE FIELD ATTR .Fn ARB_GENERATE_REINSERT NAME TYPE FIELD CMP ATTR .Fn ARB<8|16|32>_ENTRY .Fn ARB<8|16|32>_HEAD HEADNAME TYPE .Ft "size_t" .Fn ARB_ALLOCSIZE "ARB_HEAD *head" "int<8|16|32>_t maxnodes" "struct TYPE *elm" .Fn ARB_INITIALIZER "ARB_HEAD *head" "int<8|16|32>_t maxnodes" .Ft "struct TYPE *" .Fn ARB_ROOT "ARB_HEAD *head" .Ft "bool" .Fn ARB_EMPTY "ARB_HEAD *head" .Ft "bool" .Fn ARB_FULL "ARB_HEAD *head" .Ft "int<8|16|32>_t" .Fn ARB_CURNODES "ARB_HEAD *head" .Ft "int<8|16|32>_t" .Fn ARB_MAXNODES "ARB_HEAD *head" .Ft "struct TYPE *" .Fn ARB_NEXT NAME "ARB_HEAD *head" "struct TYPE *elm" .Ft "struct TYPE *" .Fn ARB_PREV NAME "ARB_HEAD *head" "struct TYPE *elm" .Ft "struct TYPE *" .Fn ARB_MIN NAME "ARB_HEAD *head" .Ft "struct TYPE *" .Fn ARB_MAX NAME "ARB_HEAD *head" .Ft "struct TYPE *" .Fn ARB_FIND NAME "ARB_HEAD *head" "struct TYPE *elm" .Ft "struct TYPE *" .Fn ARB_NFIND NAME "ARB_HEAD *head" "struct TYPE *elm" .Ft "struct TYPE *" .Fn ARB_LEFT "struct TYPE *elm" "ARB_ENTRY NAME" .Ft "int<8|16|32>_t" .Fn ARB_LEFTIDX "struct TYPE *elm" "ARB_ENTRY NAME" .Ft "struct TYPE *" .Fn ARB_RIGHT "struct TYPE *elm" "ARB_ENTRY NAME" .Ft "int<8|16|32>_t" .Fn ARB_RIGHTIDX "struct TYPE *elm" "ARB_ENTRY NAME" .Ft "struct TYPE *" .Fn ARB_PARENT "struct TYPE *elm" "ARB_ENTRY NAME" .Ft "int<8|16|32>_t" .Fn ARB_PARENTIDX "struct TYPE *elm" "ARB_ENTRY NAME" .Ft "struct TYPE *" .Fn ARB_GETFREE "ARB_HEAD *head" "FIELD" .Ft "int<8|16|32>_t" .Fn ARB_FREEIDX "ARB_HEAD *head" .Fn ARB_FOREACH VARNAME NAME "ARB_HEAD *head" .Fn ARB_FOREACH_FROM "VARNAME" "NAME" "POS_VARNAME" .Fn ARB_FOREACH_SAFE "VARNAME" "NAME" "ARB_HEAD *head" "TEMP_VARNAME" .Fn ARB_FOREACH_REVERSE VARNAME NAME "ARB_HEAD *head" .Fn ARB_FOREACH_REVERSE_FROM "VARNAME" "NAME" "POS_VARNAME" .Fn ARB_FOREACH_REVERSE_SAFE "VARNAME" "NAME" "ARB_HEAD *head" "TEMP_VARNAME" .Ft void .Fn ARB_INIT "struct TYPE *elm" "FIELD" "ARB_HEAD *head" "int<8|16|32>_t maxnodes" .Ft "struct TYPE *" .Fn ARB_INSERT NAME "ARB_HEAD *head" "struct TYPE *elm" .Ft "struct TYPE *" .Fn ARB_REMOVE NAME "ARB_HEAD *head" "struct TYPE *elm" .Ft "struct TYPE *" .Fn ARB_REINSERT NAME "ARB_HEAD *head" "struct TYPE *elm" .Ft void .Fn ARB_RESET_TREE "ARB_HEAD *head" NAME "int<8|16|32>_t maxnodes" .Sh DESCRIPTION These macros define data structures for and array-based red-black trees. They use a single, continuous chunk of memory, and are useful e.g., when the tree needs to be transferred between userspace and kernel. .Pp In the macro definitions, .Fa TYPE is the name tag of a user defined structure that must contain a field of type .Vt ARB_ENTRY , named .Fa ENTRYNAME . The argument .Fa HEADNAME is the name tag of a user defined structure that must be declared using the .Fn ARB_HEAD macro. The argument .Fa NAME has to be a unique name prefix for every tree that is defined. .Pp The function prototypes are declared with .Fn ARB_PROTOTYPE , or .Fn ARB_PROTOTYPE_STATIC . The function bodies are generated with .Fn ARB_GENERATE , or .Fn ARB_GENERATE_STATIC . See the examples below for further explanation of how these macros are used. .Pp A red-black tree is a binary search tree with the node color as an extra attribute. It fulfills a set of conditions: .Bl -enum -offset indent .It Every search path from the root to a leaf consists of the same number of black nodes. .It Each red node (except for the root) has a black parent. .It Each leaf node is black. .El .Pp Every operation on a red-black tree is bounded as .Fn O "lg n" . The maximum height of a red-black tree is .Fn 2lg "n + 1" . .Pp .Fn ARB_* trees require entries to be allocated as an array, and uses array indices to link entries together. The maximum number of .Fn ARB_* tree entries is therefore constrained by the minimum of array size and choice of signed integer data type used to store array indices. Use .Fn ARB_ALLOCSIZE to compute the size of memory chunk to allocate. .Pp A red-black tree is headed by a structure defined by the .Fn ARB_HEAD macro. A structure is declared with either of the following: .Bd -ragged -offset indent .Fn ARB<8|16|32>_HEAD HEADNAME TYPE .Va head ; .Ed .Pp where .Fa HEADNAME is the name of the structure to be defined, and struct .Fa TYPE is the type of the elements to be inserted into the tree. .Pp The .Fn ARB_HEAD variant includes a suffix denoting the signed integer data type size .Pq in bits used to store array indices. For example, .Fn ARB_HEAD8 -creates a red-black tree head strucutre with 8-bit signed array indices capable +creates a red-black tree head structure with 8-bit signed array indices capable of indexing up to 128 entries. .Pp The .Fn ARB_ENTRY macro declares a structure that allows elements to be connected in the tree. Similarly to the .Fn ARB<8|16|32>_HEAD macro, the .Fn ARB_ENTRY variant includes a suffix denoting the signed integer data type size .Pq in bits used to store array indices. Entries should use the same number of bits as the tree head structure they will be linked into. .Pp In order to use the functions that manipulate the tree structure, their prototypes need to be declared with the .Fn ARB_PROTOTYPE or .Fn ARB_PROTOTYPE_STATIC macro, where .Fa NAME is a unique identifier for this particular tree. The .Fa TYPE argument is the type of the structure that is being managed by the tree. The .Fa FIELD argument is the name of the element defined by .Fn ARB_ENTRY . Individual prototypes can be declared with .Fn ARB_PROTOTYPE_INSERT , .Fn ARB_PROTOTYPE_INSERT_COLOR , .Fn ARB_PROTOTYPE_REMOVE , .Fn ARB_PROTOTYPE_REMOVE_COLOR , .Fn ARB_PROTOTYPE_FIND , .Fn ARB_PROTOTYPE_NFIND , .Fn ARB_PROTOTYPE_NEXT , .Fn ARB_PROTOTYPE_PREV , .Fn ARB_PROTOTYPE_MINMAX , and .Fn ARB_PROTOTYPE_REINSERT in case not all functions are required. The individual prototype macros expect .Fa NAME , .Fa TYPE , and .Fa ATTR arguments. The .Fa ATTR argument must be empty for global functions or .Fa static for static functions. .Pp The function bodies are generated with the .Fn ARB_GENERATE or .Fn ARB_GENERATE_STATIC macro. These macros take the same arguments as the .Fn ARB_PROTOTYPE and .Fn ARB_PROTOTYPE_STATIC macros, but should be used only once. As an alternative individual function bodies are generated with the .Fn ARB_GENERATE_INSERT , .Fn ARB_GENERATE_INSERT_COLOR , .Fn ARB_GENERATE_REMOVE , .Fn ARB_GENERATE_REMOVE_COLOR , .Fn ARB_GENERATE_FIND , .Fn ARB_GENERATE_NFIND , .Fn ARB_GENERATE_NEXT , .Fn ARB_GENERATE_PREV , .Fn ARB_GENERATE_MINMAX , and .Fn ARB_GENERATE_REINSERT macros. .Pp Finally, the .Fa CMP argument is the name of a function used to compare tree nodes with each other. The function takes two arguments of type .Vt "struct TYPE *" . If the first argument is smaller than the second, the function returns a value smaller than zero. If they are equal, the function returns zero. Otherwise, it should return a value greater than zero. The compare function defines the order of the tree elements. .Pp The .Fn ARB_INIT macro initializes the tree referenced by .Fa head , with the array length of .Fa maxnodes . .Pp The red-black tree can also be initialized statically by using the .Fn ARB_INITIALIZER macro: .Bd -ragged -offset indent .Fn ARB<8|16|32>_HEAD HEADNAME TYPE .Va head = .Fn ARB_INITIALIZER &head maxnodes ; .Ed .Pp The .Fn ARB_INSERT macro inserts the new element .Fa elm into the tree. .Pp The .Fn ARB_REMOVE macro removes the element .Fa elm from the tree pointed by .Fa head . .Pp The .Fn ARB_FIND and .Fn ARB_NFIND macros can be used to find a particular element in the tree. .Bd -literal -offset indent struct TYPE find, *res; find.key = 30; res = ARB_FIND(NAME, head, &find); .Ed .Pp The .Fn ARB_ROOT , .Fn ARB_MIN , .Fn ARB_MAX , .Fn ARB_NEXT , and .Fn ARB_PREV macros can be used to traverse the tree: .Pp .Dl "for (np = ARB_MIN(NAME, &head); np != NULL; np = ARB_NEXT(NAME, &head, np))" .Pp Or, for simplicity, one can use the .Fn ARB_FOREACH or .Fn ARB_FOREACH_REVERSE macro: .Bd -ragged -offset indent .Fn ARB_FOREACH np NAME head .Ed .Pp The macros .Fn ARB_FOREACH_SAFE and .Fn ARB_FOREACH_REVERSE_SAFE traverse the tree referenced by head in a forward or reverse direction respectively, assigning each element in turn to np. However, unlike their unsafe counterparts, they permit both the removal of np as well as freeing it from within the loop safely without interfering with the traversal. .Pp Both .Fn ARB_FOREACH_FROM and .Fn ARB_FOREACH_REVERSE_FROM may be used to continue an interrupted traversal in a forward or reverse direction respectively. The head pointer is not required. The pointer to the node from where to resume the traversal should be passed as their last argument, and will be overwritten to provide safe traversal. .Pp The .Fn ARB_EMPTY macro should be used to check whether a red-black tree is empty. .Pp Given that ARB trees have an intrinsic upper bound on the number of entries, some ARB-specific additional macros are defined. The .Fn ARB_FULL macro returns a boolean indicating whether the current number of tree entries equals the tree's maximum. The .Fn ARB_CURNODES and .Fn ARB_MAXNODES macros return the current and maximum number of entries respectively. The .Fn ARB_GETFREE macro returns a pointer to the next free entry in the array of entries, ready to be linked into the tree. The .Fn ARB_INSERT returns .Dv NULL if the element was inserted in the tree successfully, otherwise they return a pointer to the element with the colliding key. .Pp Accordingly, .Fn ARB_REMOVE returns the pointer to the removed element otherwise they return .Dv NULL to indicate an error. .Pp The .Fn ARB_REINSERT macro updates the position of the element .Fa elm in the tree. This must be called if a member of a .Nm tree is modified in a way that affects comparison, such as by modifying a node's key. This is a lower overhead alternative to removing the element and reinserting it again. .Pp The .Fn ARB_RESET_TREE macro discards the tree topology. It does not modify embedded object values or the free list. .Sh SEE ALSO .Xr queue 3 , .Xr tree 3 .Sh HISTORY The .Nm ARB macros first appeared in .Fx 13.0 . .Sh AUTHORS The .Nm ARB macros were implemented by .An Lawrence Stewart Aq Mt lstewart@FreeBSD.org , based on .Xr tree 3 macros written by .An Niels Provos . diff --git a/share/man/man4/acpi_asus_wmi.4 b/share/man/man4/acpi_asus_wmi.4 index 10db9ba6ca59..7d6aeaca948b 100644 --- a/share/man/man4/acpi_asus_wmi.4 +++ b/share/man/man4/acpi_asus_wmi.4 @@ -1,88 +1,88 @@ .\" .\" Copyright (c) 2012 Alexander Motin .\" 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. .\" .Dd July 2, 2012 .Dt ACPI_ASUS_WMI 4 .Os .Sh NAME .Nm acpi_asus_wmi .Nd Asus Laptop WMI Extras .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_asus_wmi" .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_asus_wmi_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for the extra WMI-controlled gadgets, such as hotkeys and leds, found on Asus laptops. It allows one to use the .Xr sysctl 8 interface to manipulate the brightness of the LCD panel and keyboard backlight, power on/off different internal components, such as WiFi, Bluetooth, camera, cardreader, etc, read some sensors. Hotkey events are passed to .Xr devd 8 for easy handling in userspace with the default configuration in .Pa /etc/devd/asus.conf . Some hotkey events, such as keyboard backlight and touchpad control, are handled inside the driver. .Sh SYSCTL VARIABLES The following sysctls are currently implemented: .Bl -tag -width indent .It Va dev.acpi_asus_wmi.0.handle_keys -Specifies whether driver should handle some harwdare keys, such as keyboard +Specifies whether driver should handle some hardware keys, such as keyboard backlight, internally. .El .Pp Number of other variables under the same sysctl branch are model-specific. .Pp Defaults for these variables can be set in .Xr sysctl.conf 5 , which is parsed at boot-time. .Sh SEE ALSO .Xr acpi 4 , .Xr acpi_asus 4 , .Xr acpi_video 4 , .Xr sysctl.conf 5 , .Xr devd 8 , .Xr sysctl 8 .Sh HISTORY The .Nm driver first appeared in .Fx 10.0 . .Sh AUTHORS .An Alexander Motin Aq Mt mav@FreeBSD.org diff --git a/share/man/man4/ads111x.4 b/share/man/man4/ads111x.4 index d140f6e95106..03468a4442da 100644 --- a/share/man/man4/ads111x.4 +++ b/share/man/man4/ads111x.4 @@ -1,239 +1,239 @@ .\" .\" Copyright (c) 2019 Ian Lepore .\" .\" 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 ``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 BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .Dd September 2, 2019 .Dt ADS111x 4 .Os .Sh NAME .Nm ads111x .Nd driver for ADS101x and ADS111x i2c analog to digital converters .Sh SYNOPSIS To compile this driver into the kernel, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "device ads111x" .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 ads111x_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for the ADS101x/ADS111x family of analog to digital converter (ADC) devices. The supported devices are all similar to each other, varying in features such as resolution and number of input channels. The devices offer a number of configuration options which can be set via hints, FDT data, and .Xr sysctl 8 . .Pp The .Xr sysctl 8 utility provides access to the voltage measurements made by the device. Each time the .Va dev.ads111x...voltage variable is accessed for a given channel, the driver switches the chip's internal mux to choose the right input pins for that channel, directs it to make a single measurement, and returns the measured value in microvolts. The amount of time required to make the measurement is a function of the sampling rate configured for the device. While device is directed to make a single measurement, it still averages the input values for the same amount of time as it would to emit one sample if it were in continuous mode. For example, if the sample rate were configured as 125 samples per second, a single measurement would require 8 milliseconds. .Pp For devices that support multiple input pins, the device datasheet -describes mux settings to control how those pins are interpeted when +describes mux settings to control how those pins are interpreted when making either single-ended or differential measurements. There are eight possible ways to combine the inputs from the four pins. The .Nm driver models that by creating a separate output channel for each of the eight combinations. To make a measurement on a given pin or pair of pins, you simply access the voltage variable for the channel number that corresponds the mux setting number (0 through 7) shown in the datasheet. When the driver is configured with hints or FDT data, it creates sysctl variables for just the channels specified in the config data. When there is no channel config data, it creates all eight possible channels so that you can access whichever one(s) you need. .Pp For devices that include an .Va alert output pin, the .Nm driver does not directly support the pin in terms of sensing or acting on changes in the pin state. However, you may connect the pin to a gpio input or fan controller or other external device, and use the driver's sysctl variables to configure behavior and threshold values for the pin. The driver avoids perturbing your settings as it does other manipulations to the config register. .Sh SYSCTL VARIABLES Sysctl variables are used to access the voltage measurements, and to change the configuration of the channels. All writeable variables may also be set as .Xr loader 8 tunables. Channel numbers in these sysctl variables range from 0 through 7. .Bl -tag -width indent .It Va dev.ads111x..config Provides access to the configuration register bits that control the alert pin configuration. Other bits which are controlled by the driver are masked out, and cannot be viewed or changed using this variable. .It Va dev.ads111x..lo_thresh Sets the low threshold for activating the alert pin. .It Va dev.ads111x..hi_thresh Sets the high threshold for activating the alert pin. .It Va dev.ads111x...rate_index Sets the sample rate for the channel. The device datasheet documents eight available sample rates, chosen by setting a value of 0 through 7 into the corresponding control register bits. This variable sets the value used for those bits when making a measurement on the given channel. .Pp Because measurements are always made in single-shot mode, think of this variable as controlling the averaging time for a single sample; the time to make a measurement is 1 / samplerate. .It Va dev.ads111x...gain_index Sets the programmable gain amplifier for the channel on devices which have an internal amplifier. The device datasheet documents eight available gain values, chosen by setting a value of 0 through 7 into the corresponding control register bits. This variable sets the value used for those bits when making a measurement on the given channel. .It Va dev.ads111x...voltage Reading this variable causes the device to make a measurement on the corresponding input pin(s) and return the voltage in microvolts. .Pp Note that this variable does not appear when you list multiple sysctl variables -- you must access it specifically by name, because accessing it triggers device I/O. .El .Sh HARDWARE The .Nm driver provides support for the following devices: .Pp .Bl -column -compact -offset indent "XXXXXXXX" "XXXXXXXX" .It ADS1013 Ta ADS1113 .It ADS1014 Ta ADS1114 .It ADS1015 Ta ADS1115 .El .Sh FDT CONFIGURATION On an .Xr fdt 4 based system, the .Nm device is defined as a slave device subnode of the i2c bus controller node. All properties documented in the .Va ads1015.txt bindings document can be used with the .Nm device. .Pp The following properties are required in the .Nm device subnode: .Bl -tag -width indent .It Va compatible One of the following: .Bl -column -compact -offset indent ".Dq ti,ads1013" ".Dq ti,ads1113" .It Dq ti,ads1013 Ta Dq ti,ads1113 .It Dq ti,ads1014 Ta Dq ti,ads1114 .It Dq ti,ads1015 Ta Dq ti,ads1115 .El .It Va reg I2c slave address of device. .El .Pp Specific channels can be configured by adding child nodes to the .Nm node, as described in the standard ads1015.txt bindings document. If no channels are configured, sysctl variables will be created for all possible channels supported by the device type, otherwise only the specified channels are created. .Ss Example including channel configuration .Bd -unfilled -offset indent adc@48 { compatible = "ti,ads1115"; reg = <0x48>; status = "okay"; #address-cells = <1>; #size-cells = <0>; channel@6 { reg = <6>; ti,gain = <3>; ti,datarate = <4>; }; channel@7 { reg = <7>; ti,gain = <1>; ti,datarate = <7>; }; }; .Ed .Sh HINTS CONFIGURATION On a .Xr device.hints 5 based system, such as .Li MIPS , these values are configurable for .Nm : .Bl -tag -width indent .It Va hint.ads111x..at The iicbus instance the .Nm instance is attached to. .It Va hint.ads111x...gain_index The amplifier gain, as described above for the sysctl variable .Va dev.ads111x...gain_index . .It Va hint.ads111x...rate_index The sample rate, as described above for the sysctl variable .Va dev.ads111x...rate_index . .El .Pp If no channels are configured, sysctl variables will be created for all possible channels supported by the device type, otherwise only the specified channels are created. .Sh SEE ALSO .Xr fdt 4 , .Xr sysctl 8 .Sh HISTORY The .Nm driver first appeared in .Fx 13.0 . diff --git a/share/man/man4/atkbdc.4 b/share/man/man4/atkbdc.4 index 2de2a14a640e..48067c98a5be 100644 --- a/share/man/man4/atkbdc.4 +++ b/share/man/man4/atkbdc.4 @@ -1,126 +1,126 @@ .\" .\" Copyright (c) 1999 .\" Kazutaka YOKOTA .\" 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 as .\" the first lines of this file unmodified. .\" 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 ``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 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 February 26, 2023 .Dt ATKBDC 4 .Os .Sh NAME .Nm atkbdc .Nd the AT keyboard controller interface .Sh SYNOPSIS .Cd "options KBD_RESETDELAY=N" .Cd "options KBD_MAXWAIT=N" .Cd "options KBD_DELAY1=N" .Cd "options KBD_DELAY2=N" .Cd "options KBDIO_DEBUG=N" .Cd "device atkbdc" .Pp In .Pa /boot/device.hints : .Cd hint.atkbdc.0.at="isa" .Cd hint.atkbdc.0.port="0x060" .Sh DESCRIPTION The keyboard controller .Nm provides I/O services for the AT keyboard and PS/2 mouse style pointing devices. This controller is required for the keyboard driver .Nm atkbd and the PS/2 pointing device driver .Nm psm . .Pp There can be only one .Nm device configured in the system. .Sh DRIVER CONFIGURATION .Ss Kernel Configuration Options The following kernel configuration options can be used to control the .Nm driver. They may be set in the kernel configuration file (see .Xr config 8 ) . .Bl -tag -width MOUSE .It Em KBD_RESETDELAY=X , KBD_MAXWAIT=Y The keyboard driver .Nm atkbd and the pointing device driver .Nm psm may ask the .Nm driver to reset these devices during the boot process. It sometimes takes a long time before these devices respond to the reset command. These options control how long the .Nm driver should wait before eventually giving up -- the driver will wait .Fa X * .Fa Y msecs at most. If the drivers seem unable to detect devices, you may want to increase these values. The default values are 200 msec for .Fa X and 5 for .Fa Y . .It Em KBD_DELAY1=X, KBD_DELAY2=Y -DELAY1 sets the intitial key repeat delay to +DELAY1 sets the initial key repeat delay to .Fa X . The default value is 500ms. DELAY2 sets the key repeat delay to .Fa Y . The default value is 100ms. .It Em KBDIO_DEBUG=N Sets the debug level to .Fa N . The default value is zero, which suppresses all debugging output. .El .\".Ss Driver Flags .\".Sh FILES .\".Sh EXAMPLE .\".Sh DIAGNOSTICS .\".Sh CAVEATS .\".Sh BUGS .Sh SEE ALSO .Xr atkbd 4 , .Xr psm 4 , .Xr config 8 .Sh HISTORY The .Nm driver first appeared in .Fx 3.1 . It is based on the kbdio module in .Fx 2.2 . .Sh AUTHORS The kbdio module, the .Nm driver and this manual page were written by .An Kazutaka Yokota Aq Mt yokota@FreeBSD.org . diff --git a/share/man/man4/bxe.4 b/share/man/man4/bxe.4 index c174b813bcc6..c82565e19583 100644 --- a/share/man/man4/bxe.4 +++ b/share/man/man4/bxe.4 @@ -1,342 +1,342 @@ .\" Copyright (c) 2014 Qlogic Corporation. 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 COPYRIGHT HOLDERS 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 COPYRIGHT OWNER 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 April 29, 2012 .Dt BXE 4 .Os .Sh NAME .Nm bxe .Nd QLogic NetXtreme II Ethernet 10Gb PCIe adapter driver .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device bxe" .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 if_bxe_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for PCIe 10Gb Ethernet adapters based on the QLogic NetXtreme II family of 10Gb chips. The driver supports Jumbo Frames, VLAN tagging, checksum offload (IPv4, TCP, UDP, IPv6-TCP, IPv6-UDP), MSI-X interrupts, TCP Segmentation Offload (TSO), Large Receive Offload (LRO), and Receive Side Scaling (RSS). .Sh HARDWARE The .Nm driver provides support for various NICs based on the QLogic NetXtreme II family of 10Gb Ethernet controller chips, including the following: .Pp .Bl -bullet -compact .It QLogic NetXtreme II BCM57710 10Gb .It QLogic NetXtreme II BCM57711 10Gb .It QLogic NetXtreme II BCM57711E 10Gb .It QLogic NetXtreme II BCM57712 10Gb .It QLogic NetXtreme II BCM57712-MF 10Gb .It QLogic NetXtreme II BCM57800 10Gb .It QLogic NetXtreme II BCM57800-MF 10Gb .It QLogic NetXtreme II BCM57810 10Gb .It QLogic NetXtreme II BCM57810-MF 10Gb .It QLogic NetXtreme II BCM57840 10Gb / 20Gb .It QLogic NetXtreme II BCM57840-MF 10Gb .El .Sh CONFIGURATION There a number of configuration parameters that can be set to tweak the driver's behavior. These parameters can be set via the .Xr loader.conf 5 file to take effect during the next system boot. The following parameters affect ALL instances of the driver. .Bl -tag -width indent .It Va hw.bxe.debug DEFAULT = 0 .br Sets the default logging level of the driver. See the Diagnostics and Debugging section below for more details. .It Va hw.bxe.interrupt_mode DEFAULT = 2 .br Sets the default interrupt mode: 0=IRQ, 1=MSI, 2=MSIX. If set to MSIX and allocation fails, the driver will roll back and attempt MSI allocation. If MSI allocation fails, the driver will roll back and attempt fixed level IRQ allocation. If IRQ allocation fails, then the driver load fails. With MSI/MSIX, the driver attempts to allocate a vector for each queue in addition to one more for default processing. .It Va hw.bxe.queue_count DEFAULT = 4 .br Sets the default number of fast path packet processing queues. Note that one MSI/MSIX interrupt vector is allocated per-queue. .It Va hw.bxe.max_rx_bufs DEFAULT = 0 .br Sets the maximum number of receive buffers to allocate per-queue. Zero(0) means to allocate a receive buffer for every buffer descriptor. By default this equates to 4080 buffers per-queue which is the maximum value for this config parameter. .It Va hw.bxe.hc_rx_ticks DEFAULT = 25 .br Sets the number of ticks for host interrupt coalescing in the receive path. .It Va hw.bxe.hc_tx_ticks DEFAULT = 50 .br Sets the number of ticks for host interrupt coalescing in the transmit path. .It Va hw.bxe.rx_budget DEFAULT = 0xffffffff .br Sets the maximum number of receive packets to process in an interrupt. If the budget is reached then the remaining/pending packets will be processed in a scheduled taskqueue. .It Va hw.bxe.max_aggregation_size DEFAULT = 32768 .br -Sets the maximum LRO aggregration byte size. +Sets the maximum LRO aggregation byte size. The higher the value the more packets the hardware will aggregate. Maximum is 65K. .It Va hw.bxe.mrrs DEFAULT = -1 .br Sets the PCI MRRS: -1=Auto, 0=128B, 1=256B, 2=512B, 3=1KB .It Va hw.bxe.autogreeen DEFAULT = 0 .br Set AutoGrEEEN: 0=HW_DEFAULT, 1=FORCE_ON, 2=FORCE_OFF .It Va hw.bxe.udp_rss DEFAULT = 0 .br Enable/Disable 4-tuple RSS for UDP: 0=DISABLED, 1=ENABLED .El .Pp Special care must be taken when modifying the number of queues and receive buffers. .Fx imposes a limit on the maximum number of .Xr mbuf 9 allocations. If buffer allocations fail, the interface initialization will fail and the interface will not be usable. The driver does not make a best effort for buffer allocations. It is an all or nothing effort. .Pp You can tweak the .Xr mbuf 9 allocation limit using .Xr sysctl 8 and view the current usage with .Xr netstat 1 as follows: .Bd -literal -offset indent # netstat -m # sysctl kern.ipc.nmbclusters # sysctl kern.ipc.nmbclusters=<#> .Ed .Pp There are additional configuration parameters that can be set on a per-instance basis to dynamically override the default configuration. The '#' below must be replaced with the driver instance / interface unit number: .Bl -tag -width indent .It Va dev.bxe.#.debug DEFAULT = 0 .br Sets the default logging level of the driver instance. See .Va hw.bxe.debug above and the Diagnostics and Debugging section below for more details. .It Va dev.bxe.#.rx_budget DEFAULT = 0xffffffff .br Sets the maximum number of receive packets to process in an interrupt for the driver instance. See .Va hw.bxe.rx_budget above for more details. .El .Pp Additional items can be configured using .Xr ifconfig 8 : .Bl -tag -width indent .It Va MTU - Maximum Transmission Unit DEFAULT = 1500 .br RANGE = 46-9184 .br # ifconfig bxe# mtu .It Va Promiscuous Mode DEFAULT = OFF .br # ifconfig bxe# [ promisc | -promisc ] .It Va Rx/Tx Checksum Offload DEFAULT = RX/TX CSUM ON .br Note that the Rx and Tx settings are not independent. .br # ifconfig bxe# [ rxcsum | -rxcsum | txcsum | -txcsum ] .It Va TSO - TCP Segmentation Offload DEFAULT = ON .br # ifconfig bxe# [ tso | -tso | tso6 | -tso6 ] .It Va LRO - TCP Large Receive Offload DEFAULT = ON .br # ifconfig bxe# [ lro | -lro ] .El .Sh DIAGNOSTICS AND DEBUGGING There are many statistics exposed by .Nm via .Xr sysctl 8 . .Pp To dump the default driver configuration: .Bd -literal -offset indent # sysctl -a | grep hw.bxe .Ed .Pp To dump every instance's configuration and detailed statistics: .Bd -literal -offset indent # sysctl -a | grep dev.bxe .Ed .Pp To dump information for a single instance (replace the '#' with the driver instance / interface unit number): .Bd -literal -offset indent # sysctl -a | grep dev.bxe.# .Ed .Pp To dump information for all the queues of a single instance: .Bd -literal -offset indent # sysctl -a | grep dev.bxe.#.queue .Ed .Pp To dump information for a single queue of a single instance (replace the additional '#' with the queue number): .Bd -literal -offset indent # sysctl -a | grep dev.bxe.#.queue.# .Ed .Pp The .Nm driver has the ability to dump a ton of debug messages to the system log. The default level of logging can be set with the .Va hw.bxe.debug .Xr sysctl 8 . Take care with this setting as it can result in too many logs being dumped. Since this parameter is the default one, it affects every instance and will dramatically change the timing in the driver. A better alternative to aid in debugging is to dynamically change the debug level of a specific instance with the .Va dev.bxe.#.debug .Xr sysctl 8 . This allows you to turn on/off logging of various debug groups on-the-fly. .Pp The different debug groups that can be toggled are: .Bd -literal -offset indent DBG_LOAD 0x00000001 /* load and unload */ DBG_INTR 0x00000002 /* interrupt handling */ DBG_SP 0x00000004 /* slowpath handling */ DBG_STATS 0x00000008 /* stats updates */ DBG_TX 0x00000010 /* packet transmit */ DBG_RX 0x00000020 /* packet receive */ DBG_PHY 0x00000040 /* phy/link handling */ DBG_IOCTL 0x00000080 /* ioctl handling */ DBG_MBUF 0x00000100 /* dumping mbuf info */ DBG_REGS 0x00000200 /* register access */ DBG_LRO 0x00000400 /* lro processing */ DBG_ASSERT 0x80000000 /* debug assert */ DBG_ALL 0xFFFFFFFF /* flying monkeys */ .Ed .Pp For example, to debug an issue in the receive path on bxe0: .Bd -literal -offset indent # sysctl dev.bxe.0.debug=0x22 .Ed .Pp When finished turn the logging back off: .Bd -literal -offset indent # sysctl dev.bxe.0.debug=0 .Ed .Sh SUPPORT For support questions please contact your QLogic approved reseller or QLogic Technical Support at .Pa http://support.qlogic.com , or by E-mail at .Aq Mt support@qlogic.com . .Sh SEE ALSO .Xr netstat 1 , .Xr altq 4 , .Xr arp 4 , .Xr netintro 4 , .Xr ng_ether 4 , .Xr vlan 4 , .Xr ifconfig 8 .Sh HISTORY The .Nm device driver first appeared in .Fx 9.0 . .Sh AUTHORS The .Nm driver was written by .An Eric Davis Aq Mt edavis@broadcom.com , .An David Christensen Aq Mt davidch@broadcom.com , and .An Gary Zambrano Aq Mt zambrano@broadcom.com . diff --git a/share/man/man4/cgem.4 b/share/man/man4/cgem.4 index 7937c2d818d9..1ca4f8fae9e8 100644 --- a/share/man/man4/cgem.4 +++ b/share/man/man4/cgem.4 @@ -1,300 +1,300 @@ .\" .\" Copyright (c) 2014 Thomas Skibo .\" 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. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" 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 January 10, 2021 .Dt CGEM 4 .Os .Sh NAME .Nm cgem .Nd "Cadence GEM Gigabit Ethernet driver" .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device ether" .Cd "device miibus" .Cd "device cgem" .Ed .Sh DESCRIPTION The .Nm driver provides support for the Cadence GEM (Gigabit Ethernet MAC). The Cadence GEM is used in some SoC (System on a Chip) devices such as the Xilinx Zynq-7000, the Xilinx Zynq UltraScale+, and the SiFive HiFive Unleashed. .Pp The .Nm driver supports the following media types: .Bl -tag -width ".Cm 10baseT/UTP" .It Cm autoselect Enable autoselection of the media type and options. The user can manually override the autoselected mode using .Xr ifconfig 8 or by adding media options to .Xr rc.conf 5 . .It Cm 10baseT/UTP Set 10Mbps operation. The .Xr ifconfig 8 .Cm mediaopt option can also be used to select either .Cm full-duplex or .Cm half-duplex modes. .It Cm 100baseTX Set 100Mbps (Fast Ethernet) operation. The .Xr ifconfig 8 .Cm mediaopt option can also be used to select either .Cm full-duplex or .Cm half-duplex modes. .It Cm 1000baseT Set 1000Mbps (Gigabit Ethernet) operation over twisted pair. The GEM supports 1000Mbps in .Cm full-duplex mode only. .El .Pp The .Nm driver supports the following media options: .Bl -tag -width ".Cm full-duplex" .It Cm full-duplex Force full-duplex operation. .It Cm half-duplex Force half-duplex operation. .El .Pp The driver provides support for TCP/UDP/IP checksum offloading (although disabled by default). The device and driver also support 1536-byte frames for VLANs (vlanmtu). .Sh SYSCTL VARIABLES The following variables are available as both .Xr sysctl 8 variables and .Xr loader 8 tunables: .Bl -tag -width "xxxxxxxx" .It Va dev.cgem.%d.rxbufs The number of receive buffers allocated to the hardware. The default value is 256. The maximum value is 511. If this number is increased while the interface is UP, it will not take effect until the next packet is received. If this number is decreased while the interface is UP, buffers will not be immediately removed from the receive buffer ring but the number of buffers will decrease as packets are received until it reaches the new value. .It Va dev.cgem.%d.rxhangwar This tunable enables a work-around to recover from receive hangs. The default value is 1. Set to 0 to disable the work-around. .El .Pp The following read-only variables are available as .Xr sysctl 8 variables: .Bl -tag -width "xxxxxxxx" .It Va dev.cgem.%d._rxoverruns This variable counts the number of receive packet buffer overrun interrupts. .It Va dev.cgem.%d._rxnobufs This variable counts the number of interrupts due to the GEM buffer ring going empty. .It Va dev.cgem.%d._rxdmamapfails This variable is the number of times bus_dmamap_load_mbuf_sg(9) failed in the receive path. .It Va dev.cgem.%d._txfull The number of times the GEM's transmit ring was full. .It Va dev.cgem.%d._txdmamapfails This variable is the number of times bus_dmamap_load_mbuf_sg(9) failed in the transmit path. .It Va dev.cgem.%d._txdefrags This variable is the number of times the driver needed to call m_defrag(9) because a packet queued for transmit had too many DMA segments. .It Va dev.cgem.%d._txdefragfails This variable is the number of times .Xr m_defrag 9 failed. .It Va dev.cgem.%d.stats.* The following variables are useful MAC counters supplied by the hardware: .It Va dev.cgem.%d.stats.tx_bytes A 64-bit counter of the number of bytes transmitted in frames without error. .It Va dev.cgem.%d.stats.tx_frames Counter of frames transmitted without error excluding pause frames. .It Va dev.cgem.%d.stats.tx_frames_bcast Counter of broadcast frames transmitted without error excluding pause frames. .It Va dev.cgem.%d.stats.tx_frames_multi Counter of multicast frames transmitted without error excluding pause frames. .It Va dev.cgem.%d.stats.tx_frames_pause Counter of pause frames transmitted without error. .It Va dev.cgem.%d.stats.tx_frames_64b Counter of 64 byte frames transmitted without error. .It Va dev.cgem.%d.stats.tx_frames_65to127b Counter of 65 to 127 byte frames transmitted without error. .It Va dev.cgem.%d.stats.tx_frames_128to255b Counter of 128 to 255 byte frames transmitted without error. .It Va dev.cgem.%d.stats.tx_frames_256to511b Counter of 256 to 511 byte frames transmitted without error. .It Va dev.cgem.%d.stats.tx_frames_512to1023b Counter of 512 to 1023 byte frames transmitted without error. .It Va dev.cgem.%d.stats.tx_frames_1024to1536b Counter of 1024 to 1536 byte frames transmitted without error. .It Va dev.cgem.%d.stats.tx_under_runs Counter of frames not transmitted due to a transmit underrun. .It Va dev.cgem.%d.stats.tx_single_collisn Counter of frames experiencing a single collision before being successfully transmitted. .It Va dev.cgem.%d.stats.tx_multi_collisn Counter of frames experiencing between 2 and 15 collisions before being successfully transmitted. .It Va dev.cgem.%d.stats.tx_excsv_collisn Counter of frames that failed to transmit because they experienced 16 collisions. .It Va dev.cgem.%d.stats.tx_late_collisn Counter of frames that experienced a late collision. .It Va dev.cgem.%d.stats.tx_deferred_frames Counter of frames experiencing deferral due to carrier sense being active on their first attempt at transmission. .It Va dev.cgem.%d.stats.tx_carrier_sense_errs Counter of frames transmitted where carrier sense was not seen during transmission or where carrier sense was deasserted after being asserted in a transmit frame without collision. .It Va dev.cgem.%d.stats.rx_bytes A 64-bit counter of bytes received without error excluding pause frames. .It Va dev.cgem.%d.stats.rx_frames Counter of frames received without error excluding pause frames. .It Va dev.cgem.%d.stats.rx_frames_bcast Counter of broadcast frames receive without error excluding pause frames. .It Va dev.cgem.%d.stats.rx_frames_multi Counter of multicast frames receive without error excluding pause frames. .It Va dev.cgem.%d.stats.rx_frames_pause -Counter of pause frames recevied without error. +Counter of pause frames received without error. .It Va dev.cgem.%d.stats.rx_frames_64b Counter of 64-byte frames received without error. .It Va dev.cgem.%d.stats.rx_frames_65to127b Counter of 65 to 127 byte frames received without error. .It Va dev.cgem.%d.stats.rx_frames_128to255b Counter of 128 to 255 byte frames received without error. .It Va dev.cgem.%d.stats.rx_frames_256to511b Counter of 256 to 511 byte frames received without error. .It Va dev.cgem.%d.stats.rx_frames_512to1023b Counter of 512 to 1023 byte frames received without error. .It Va dev.cgem.%d.stats.rx_frames_1024to1536b Counter of 1024 to 1536 byte frames received without error. .It Va dev.cgem.%d.stats.rx_frames_undersize Counter of frames received less than 64 bytes in length that do not also have either a CRC error or an alignment error. .It Va dev.cgem.%d.stats.rx_frames_oversize Counter of frames received exceeding 1536 bytes and do not also have either a CRC error or an alignment error. .It Va dev.cgem.%d.stats.rx_frames_jabber Counter of frames received exceeding 1536 bytes and also have either a CRC error, an alignment error, or a receive symbol error. .It Va dev.cgem.%d.stats.rx_frames_fcs_errs Counter of frames received with a bad CRC and are between 64 and 1536 bytes. .It Va dev.cgem.%d.stats.rx_frames_length_errs Counter of frames received that are shorter than that extracted from the length field. .It Va dev.cgem.%d.stats.rx_symbol_errs Counter of receive symbol errors. .It Va dev.cgem.%d.stats.rx_align_errs Counter of received frames that are not an integral number of bytes. .It Va dev.cgem.%d.stats.rx_resource_errs Counter of frames successfully receive by the MAC but could not be copied to memory because no receive buffer was available. .It Va dev.cgem.%d.stats.rx_overrun_errs Counter of frames that are address recognized but were not copied to memory due to a receive overrun. .It Va dev.cgem.%d.stats.rx_frames_ip_hdr_csum_errs Counter of frames discarded due to an incorrect IP header checksum when checksum offloading is enabled. .It Va dev.cgem.%d.stats.rx_frames_tcp_csum_errs Counter of frames discarded due to an incorrect TCP checksum when checksum offloading is enabled. .It Va dev.cgem.%d.stats.rx_frames_udp_csum_errs Counter of frames discarded due to an incorrect UDP checksum when checksum offloading is enabled. .El .Sh SEE ALSO .Xr miibus 4 , .Xr ifconfig 8 .Rs .%T "Zynq-7000 SoC Technical Reference Manual (Xilinx doc UG585)" .%U http://www.xilinx.com/support/documentation/user_guides/\:ug585-Zynq-7000-TRM.pdf .Re .Sh HISTORY The .Nm device driver first appeared in .Fx 10.0 . .Sh AUTHORS The .Nm driver and this manual page was written by .An Thomas Skibo Aq Mt thomasskibo@yahoo.com . .Sh BUGS The GEM can perform TCP/UDP/IP checksum offloading. However, when transmit checksum offloading is enabled, the GEM generates and replaces checksums for all packets it transmits. In a system that is forwarding packets, the device could potentially correct the checksum of packet that was corrupted in transit. For this reason, checksum offloading is disabled by default but can be enabled using ifconfig(8). .Pp When receive checksum offloading is enabled, the device will discard packets with bad TCP/UDP/IP checksums. The bad packets will not be counted in any .Xr netstat 1 statistics. There are .Xr sysctl 8 variables that count packets discarded by the hardware (see below). .Pp The GEM used in the Zynq-7000 has a bug such that the receiver can potentially freeze up under a high load. The issue is described in sec. 16.7 "Known Issues" of the Zynq-7000 SoC Technical Reference Manual (Xilinx UG585 v1.7). The .Nm driver implements the work-around suggested in the manual. It is believed that the bug does not exist in the Zynq UltraScale+ and SiFive SoCs so the work-around is disabled in those instances and enabled in all others. The work-around can be disabled by setting the .Va dev.cgem.%d.rxhangwar .Xr sysctl 8 variable to 0. diff --git a/share/man/man4/crypto.4 b/share/man/man4/crypto.4 index 930be4ab5ee8..b1423752718e 100644 --- a/share/man/man4/crypto.4 +++ b/share/man/man4/crypto.4 @@ -1,377 +1,377 @@ .\" $NetBSD: crypto.4,v 1.24 2014/01/27 21:23:59 pgoyette Exp $ .\" .\" Copyright (c) 2008 The NetBSD Foundation, Inc. .\" Copyright (c) 2014-2021 The FreeBSD Foundation .\" All rights reserved. .\" .\" Portions of this documentation were written by John-Mark Gurney .\" under sponsorship of the FreeBSD Foundation and .\" Rubicon Communications, LLC (Netgate). .\" .\" Portions of this documentation were written by Ararat River .\" Consulting, LLC under sponsorship of the FreeBSD Foundation. .\" .\" This code is derived from software contributed to The NetBSD Foundation .\" by Coyote Point Systems, Inc. .\" .\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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. .\" .\" .\" .\" Copyright (c) 2004 .\" Jonathan Stone . 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 Jonathan Stone 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 Jonathan Stone OR THE VOICES IN HIS HEAD .\" 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 October 6, 2021 .Dt CRYPTO 4 .Os .Sh NAME .Nm crypto , .Nm cryptodev .Nd user-mode access to hardware-accelerated cryptography .Sh SYNOPSIS .Cd device crypto .Cd device cryptodev .Pp .In sys/ioctl.h .In sys/time.h .In crypto/cryptodev.h .Sh DESCRIPTION The .Nm driver gives user-mode applications access to hardware-accelerated cryptographic transforms as implemented by the .Xr crypto 9 in-kernel interface. .Pp The .Pa /dev/crypto special device provides an .Xr ioctl 2 based interface. User-mode applications open the special device and then issue .Xr ioctl 2 calls on the descriptor. User-mode access to .Pa /dev/crypto is controlled by the .Ic kern.cryptodevallowsoft .Xr sysctl 8 variable. If this variable is zero, then user-mode sessions are only permitted to use cryptography coprocessors. .Sh THEORY OF OPERATION Use of the device requires a basic series of steps: .Bl -enum .It Open the .Pa /dev/crypto device. .It Create a session with .Dv CIOCGSESSION or .Dv CIOCGSESSION2 . Applications will require at least one symmetric session. Since cipher and MAC keys are tied to sessions, many applications will require more. .It Submit requests, synchronously with .Dv CIOCCRYPT or .Dv CIOCCRYPTAEAD . .It Optionally destroy a session with .Dv CIOCFSESSION . .It Close the .Pa /dev/crypto device. This will automatically close any remaining sessions associated with the -file desriptor. +file descriptor. .El .Sh SYMMETRIC-KEY OPERATION .Nm cryptodev provides a context-based API to traditional symmetric-key encryption (or privacy) algorithms, keyed and unkeyed one-way hash (HMAC and MAC) algorithms, encrypt-then-authenticate (ETA) fused operations, and authenticated encryption with additional data (AEAD) operations. For ETA operations, drivers perform both a privacy algorithm and an integrity-check algorithm in a single pass over the data: either a fused encrypt/HMAC-generate operation, or a fused HMAC-verify/decrypt operation. Similarly, for AEAD operations, drivers perform either an encrypt/MAC-generate operation or a MAC-verify/decrypt operation. .Pp The algorithm(s) and key(s) to use are specified when a session is created. Individual requests are able to specify per-request initialization vectors or nonces. .Ss Algorithms For a list of supported algorithms, see .Xr crypto 7 . .Ss IOCTL Request Descriptions .\" .Bl -tag -width CIOCGSESSION .\" .It Dv CIOCFINDDEV Fa struct crypt_find_op *fop .Bd -literal struct crypt_find_op { int crid; /* driver id + flags */ char name[32]; /* device/driver name */ }; .Ed If .Fa crid is -1, then find the driver named .Fa name and return the id in .Fa crid . If .Fa crid is not -1, return the name of the driver with .Fa crid in .Fa name . In either case, if the driver is not found, .Dv ENOENT is returned. .It Dv CIOCGSESSION Fa struct session_op *sessp .Bd -literal struct session_op { uint32_t cipher; /* e.g. CRYPTO_AES_CBC */ uint32_t mac; /* e.g. CRYPTO_SHA2_256_HMAC */ uint32_t keylen; /* cipher key */ const void *key; int mackeylen; /* mac key */ const void *mackey; uint32_t ses; /* returns: ses # */ }; .Ed Create a new cryptographic session on a file descriptor for the device; that is, a persistent object specific to the chosen privacy algorithm, integrity algorithm, and keys specified in .Fa sessp . The special value 0 for either privacy or integrity is reserved to indicate that the indicated operation (privacy or integrity) is not desired for this session. ETA sessions specify both privacy and integrity algorithms. AEAD sessions specify only a privacy algorithm. .Pp Multiple sessions may be bound to a single file descriptor. The session ID returned in .Fa sessp-\*[Gt]ses is supplied as a required field in the operation structure .Fa crypt_op for future encryption or hashing requests. .\" .Pp .\" This implementation will never return a session ID of 0 for a successful .\" creation of a session, which is a .\" .Nx .\" extension. .Pp For non-zero privacy algorithms, the privacy algorithm must be specified in .Fa sessp-\*[Gt]cipher , the key length in .Fa sessp-\*[Gt]keylen , and the key value in the octets addressed by .Fa sessp-\*[Gt]key . .Pp For keyed one-way hash algorithms, the one-way hash must be specified in .Fa sessp-\*[Gt]mac , the key length in .Fa sessp-\*[Gt]mackey , and the key value in the octets addressed by .Fa sessp-\*[Gt]mackeylen . .\" .Pp Support for a specific combination of fused privacy and integrity-check algorithms depends on whether the underlying hardware supports that combination. Not all combinations are supported by all hardware, even if the hardware supports each operation as a stand-alone non-fused operation. .It Dv CIOCGSESSION2 Fa struct session2_op *sessp .Bd -literal struct session2_op { uint32_t cipher; /* e.g. CRYPTO_AES_CBC */ uint32_t mac; /* e.g. CRYPTO_SHA2_256_HMAC */ uint32_t keylen; /* cipher key */ const void *key; int mackeylen; /* mac key */ const void *mackey; uint32_t ses; /* returns: ses # */ int crid; /* driver id + flags (rw) */ int ivlen; /* length of nonce/IV */ int maclen; /* length of MAC/tag */ int pad[2]; /* for future expansion */ }; .Ed This request is similar to CIOGSESSION but adds additional fields. .Pp .Fa sessp-\*[Gt]crid requests either a specific crypto device or a class of devices (software vs hardware). .Pp .Fa sessp-\*[Gt]ivlen specifies the length of the IV or nonce supplied with each request. If this field is set to zero, the default IV or nonce length is used. .Pp .Fa sessp-\*[Gt]maclen specifies the length of the MAC or authentication tag supplied or computed by each request. If this field is set to zero, the full MAC is used. .Pp The .Fa sessp-\*[Gt]pad field must be initialized to zero. .It Dv CIOCCRYPT Fa struct crypt_op *cr_op .Bd -literal struct crypt_op { uint32_t ses; uint16_t op; /* e.g. COP_ENCRYPT */ uint16_t flags; u_int len; const void *src; void *dst; void *mac; /* must be large enough for result */ const void *iv; }; .Ed Request an encryption/decryption (or hash) operation. To encrypt, set .Fa cr_op-\*[Gt]op to .Dv COP_ENCRYPT . To decrypt, set .Fa cr_op-\*[Gt]op to .Dv COP_DECRYPT . The field .Fa cr_op-\*[Gt]len supplies the length of the input buffer; the fields .Fa cr_op-\*[Gt]src , .Fa cr_op-\*[Gt]dst , .Fa cr_op-\*[Gt]mac , .Fa cr_op-\*[Gt]iv supply the addresses of the input buffer, output buffer, one-way hash, and initialization vector, respectively. .Pp If a session is using either fused encrypt-then-authenticate or an AEAD algorithm, decryption operations require the associated hash as an input. If the hash is incorrect, the operation will fail with .Dv EBADMSG and the output buffer will remain unchanged. .It Dv CIOCCRYPTAEAD Fa struct crypt_aead *cr_aead .Bd -literal struct crypt_aead { uint32_t ses; uint16_t op; /* e.g. COP_ENCRYPT */ uint16_t flags; u_int len; u_int aadlen; u_int ivlen; const void *src; void *dst; const void *aad; /* additional authenticated data */ void *tag; /* must fit for chosen TAG length */ const void *iv; }; .Ed The .Dv CIOCCRYPTAEAD is similar to the .Dv CIOCCRYPT but provides additional data in .Fa cr_aead-\*[Gt]aad to include in the authentication mode. .It Dv CIOCFSESSION Fa u_int32_t ses_id Destroys the session identified by .Fa ses_id . .El .Sh SEE ALSO .Xr aesni 4 , .Xr hifn 4 , .Xr ipsec 4 , .Xr padlock 4 , .Xr safe 4 , .Xr crypto 7 , .Xr geli 8 , .Xr crypto 9 .Sh HISTORY The .Nm driver first appeared in .Ox 3.0 . The .Nm driver was imported to .Fx 5.0 . .Sh BUGS Error checking and reporting is weak. .Pp The values specified for symmetric-key key sizes to .Dv CIOCGSESSION must exactly match the values expected by .Xr opencrypto 9 . The output buffer and MAC buffers supplied to .Dv CIOCCRYPT must follow whether privacy or integrity algorithms were specified for session: if you request a .No non- Ns Dv NULL algorithm, you must supply a suitably-sized buffer. diff --git a/share/man/man4/firewire.4 b/share/man/man4/firewire.4 index 4195d4da694c..8c4b65eb25bb 100644 --- a/share/man/man4/firewire.4 +++ b/share/man/man4/firewire.4 @@ -1,125 +1,125 @@ .\" Copyright (c) 1998-2002 Katsushi Kobayashi and Hidetoshi Shimokawa .\" 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. .\" 3. All advertising materials mentioning features or use of this software -.\" must display the acknowledgement as bellow: +.\" must display the acknowledgement as below: .\" .\" This product includes software developed by K. Kobayashi and H. Shimokawa .\" .\" 4. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 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 June 6, 2022 .Dt FIREWIRE 4 .Os .Sh NAME .Nm firewire .Nd IEEE1394 High-performance Serial Bus .Sh SYNOPSIS To compile this driver into the kernel, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "device firewire" .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 firewire_load="YES" .Ed .Sh DESCRIPTION .Fx provides machine-independent bus support and raw drivers for .Nm interfaces. .Pp The .Nm driver consists of two layers: the controller and the bus layer. The controller attaches to a physical bus (like .Xr pci 4 ) . The .Nm bus attaches to the controller. Additional drivers can be attached to the bus. .Pp Up to 63 devices, including the host itself, can be attached to a .Nm bus. The root node is dynamically assigned with a PHY device function. Also, the other .Nm bus specific parameters, e.g., node ID, cycle master, isochronous resource manager and bus manager, are dynamically assigned, after bus reset is initiated. On the .Nm bus, every device is identified by an EUI 64 address. .Pp Debugging over the firewire interface is possible with the .Xr dcons 4 driver. Please see .Lk https://docs.freebsd.org/en/books/developers-handbook/kerneldebug/#kerneldebug-dcons for details on how to setup debugging with firewire. .Sh FILES .Bl -tag -width "Pa /dev/fwmem0.0" -compact .It Pa /dev/fw0.0 .It Pa /dev/fwmem0.0 .El .Sh SEE ALSO .Xr dcons 4 , .Xr fwe 4 , .Xr fwip 4 , .Xr fwohci 4 , .Xr pci 4 , .Xr sbp 4 , .Xr eui64 5 , .Xr fwcontrol 8 , .Xr kldload 8 , .Xr sysctl 8 .Sh HISTORY The .Nm driver first appeared in .Fx 5.0 . .Sh AUTHORS .An -nosplit The .Nm driver was written by .An Katsushi Kobayashi and .An Hidetoshi Shimokawa for the .Fx project. .Sh BUGS See .Xr fwohci 4 for security notes. diff --git a/share/man/man4/fwohci.4 b/share/man/man4/fwohci.4 index 42c038f8cf60..ec14ddfdec85 100644 --- a/share/man/man4/fwohci.4 +++ b/share/man/man4/fwohci.4 @@ -1,154 +1,154 @@ .\" Copyright (c) 1998,1999,2000 Katsushi Kobayashi and Hidetoshi Shimokawa .\" 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. .\" 3. All advertising materials mentioning features or use of this software -.\" must display the acknowledgement as bellow: +.\" must display the acknowledgement as below: .\" .\" This product includes software developed by K. Kobayashi and H. Shimokawa .\" .\" 4. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 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 December 24, 2020 .Dt FWOHCI 4 .Os .Sh NAME .Nm fwohci .Nd OHCI FireWire chipset device driver .Sh SYNOPSIS To compile this driver into the kernel, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "device firewire" .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 firewire_load="YES" .Ed .Pp To disable physical access (see .Sx BUGS section for detail), put the following line in .Xr loader.conf 5 : .Bd -literal -offset indent hw.firewire.phydma_enable=0 .Ed .Sh HARDWARE The .Nm driver provides support for PCI/CardBus FireWire interface cards. The driver supports the following IEEE 1394 OHCI chipsets: .Pp .Bl -bullet -compact .It Adaptec AHA-894x/AIC-5800 .It Apple Pangea .It Apple UniNorth .It Intel 82372FB .It IOGEAR GUF320 .It Lucent / Agere FW322/323 .It NEC uPD72861 .It NEC uPD72870 .It NEC uPD72871/2 .It NEC uPD72873 .It NEC uPD72874 .It National Semiconductor CS4210 .It Ricoh R5C551 .It Ricoh R5C552 .It Sony CX3022 .It Sony i.LINK (CXD3222) .It Texas Instruments PCI4410A .It Texas Instruments PCI4450 .It Texas Instruments PCI4451 .It Texas Instruments TSB12LV22 .It Texas Instruments TSB12LV23 .It Texas Instruments TSB12LV26 .It Texas Instruments TSB43AA22 .It Texas Instruments TSB43AB21/A/AI/A-EP .It Texas Instruments TSB43AB22/A .It Texas Instruments TSB43AB23 .It Texas Instruments TSB82AA2 .It VIA Fire II (VT6306) .El .Sh SEE ALSO .Xr firewire 4 , .Xr fwe 4 , .Xr fwip 4 , .Xr sbp 4 , .Xr fwcontrol 8 , .Xr kldload 8 .Sh HISTORY The .Nm device driver first appeared in .Fx 5.0 . .Sh AUTHORS .An -nosplit The .Nm device driver was written by .An Katsushi Kobayashi and .An Hidetoshi Shimokawa . .Sh BUGS The driver allows physical access from any nodes on the bus by default. This means that any devices on the bus can read and modify any memory space which can be accessed by an IEEE 1394 OHCI chip. It is allowed mostly for .Xr sbp 4 devices. This should be changed to allow it only for specific devices. Anyway, FireWire is a bus and not expected to be connected with un-trustable devices because a node can monitor all the traffic. diff --git a/share/man/man4/genetlink.4 b/share/man/man4/genetlink.4 index b650e0fabbea..9cc5f3b9cbc1 100644 --- a/share/man/man4/genetlink.4 +++ b/share/man/man4/genetlink.4 @@ -1,145 +1,145 @@ .\" .\" Copyright (C) 2022 Alexander Chernikov . .\" .\" 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 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 13.2 . .Sh AUTHORS -The netlink was implementated by +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/gve.4 b/share/man/man4/gve.4 index 9bb1be1b9a53..54e59b86108b 100644 --- a/share/man/man4/gve.4 +++ b/share/man/man4/gve.4 @@ -1,215 +1,215 @@ .\" SPDX-License-Identifier: BSD-3-Clause .\" .\" Copyright (c) 2023 Google LLC .\" .\" 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. .\" .\" 3. Neither the name of the copyright holder nor the names of its contributors .\" may be used to endorse or promote products derived from this software without .\" specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS 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 COPYRIGHT HOLDER 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 April 26, 2023 .Dt GVE 4 .Os .Sh NAME .Nm gve .Nd "Ethernet driver for Google Virtual NIC (gVNIC)" .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device gve" .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 if_gve_load="YES" .Ed .Sh DESCRIPTION gVNIC is a virtual network interface designed specifically for Google Compute Engine (GCE). It is required to support per-VM Tier-1 networking performance, and for using certain VM shapes on GCE. .Pp .Nm is the driver for gVNIC. It supports the following features: .Pp .Bl -bullet -compact .It RX checksum offload .It TX chesksum offload .It TCP Segmentation Offload (TSO) .It Large Receive Offload (LRO) in software .It Jumbo frames .It Receive Side Scaling (RSS) .El .Pp For more information on configuring this device, see .Xr ifconfig 8 . .Sh HARDWARE .Nm binds to a single PCI device ID presented by gVNIC: .Pp .Bl -bullet -compact .It 0x1AE0:0x0042 .El .Sh DIAGNOSTICS The following messages are recorded during driver initialization: .Bl -diag .It "Enabled MSIX with %d vectors" .It "Configured device resources" .It "Successfully attached %s" .It "Deconfigured device resources" .El .Pp These messages are seen if driver initialization fails. Global (across-queues) allocation failures: .Bl -diag .It "Failed to configure device resources: err=%d" .It "No compatible queue formats" .It "Failed to allocate ifnet struct" .It "Failed to allocate admin queue mem" .It "Failed to alloc DMA mem for DescribeDevice" .It "Failed to allocate QPL page" .El .Pp irq and BAR allocation failures: .Bl -diag .It "Failed to acquire any msix vectors" .It "Tried to acquire %d msix vectors, got only %d" .It "Failed to setup irq %d for Tx queue %d " .It "Failed to setup irq %d for Rx queue %d " .It "Failed to allocate irq %d for mgmnt queue" .It "Failed to setup irq %d for mgmnt queue, err: %d" .It "Failed to allocate BAR0" .It "Failed to allocate BAR2" .It "Failed to allocate msix table" .El .Pp Rx queue-specific allocation failures: .Bl -diag .It "No QPL left for rx ring %d" .It "Failed to alloc queue resources for rx ring %d" .It "Failed to alloc desc ring for rx ring %d" .It "Failed to alloc data ring for rx ring %d" .El .Pp Tx queue-specific allocation failures: .Bl -diag .It "No QPL left for tx ring %d" .It "Failed to alloc queue resources for tx ring %d" .It "Failed to alloc desc ring for tx ring %d" .It "Failed to vmap fifo, qpl_id = %d" .El .El .Pp The following messages are recorded when the interface detach fails: .Bl -diag .It "Failed to deconfigure device resources: err=%d" .El .Pp If bootverbose is on, the following messages are recorded when the interface is being brought up: .Bl -diag .It "Created %d rx queues" .It "Created %d tx queues" .It "MTU set to %d" .El .Pp The following messages are recorded when the interface is being brought down: .Bl -diag .It "Destroyed %d rx queues" .It "Destroyed %d tx queues" .El .Pp These messages are seen if errors are encountered when bringing the interface up or down: .Bl -diag .It "Failed to destroy rxq %d, err: %d" .It "Failed to destroy txq %d, err: %d" .It "Failed to create rxq %d, err: %d" .It "Failed to create txq %d, err: %d" .It "Failed to set MTU to %d" .It "Invalid new MTU setting. new mtu: %d max mtu: %d min mtu: %d" .It "Cannot bring the iface up when detached" .It "Reached max number of registered pages %lu > %lu" .It "Failed to init lro for rx ring %d" .El .Pp These messages are seen if any admin queue command fails: .Bl -diag .It "AQ command(%u): failed with status %d" .It "AQ command(%u): unknown status code %d" .It "AQ commands timed out, need to reset AQ" .It "Unknown AQ command opcode %d" .El .Pp These messages are recorded when the device is being reset due to an error: .Bl -diag .It "Scheduling reset task!" .It "Waiting until admin queue is released." .It "Admin queue released" .El .Pp If it was the NIC that requested the reset, this message is recorded: .Bl -diag .It "Device requested reset" .El .Pp If the reset fails during the reinitialization phase, this message is recorded: .Bl -diag .It "Restore failed!" .El .Pp -These two messages correspoond to the NIC alerting the driver to link state changes: +These two messages correspond to the NIC alerting the driver to link state changes: .Bl -diag .It "Device link is up." .It "Device link is down." .El .Pp Apart from these messages, the driver exposes per-queue packet and error counters as sysctl nodes. Global (across queues) counters can be read using .Xr netstat 8 . .Sh LIMITATIONS .Nm does not support the transmission of VLAN-tagged packets. All VLAN-tagged traffic is dropped. .Sh SUPPORT Please email gvnic-drivers@google.com with the specifics of the issue encountered. .El .Sh SEE ALSO .Xr ifconfig 8 , .Xr netstat 8 .Sh HISTORY The .Nm device driver first appeared in .Fx 14.0 . .Sh AUTHORS The .Nm driver was written by Google. diff --git a/share/man/man4/hv_storvsc.4 b/share/man/man4/hv_storvsc.4 index bcc704167f7e..dc77a822757f 100644 --- a/share/man/man4/hv_storvsc.4 +++ b/share/man/man4/hv_storvsc.4 @@ -1,88 +1,88 @@ .\" .\" Copyright (c) 2012 Microsoft Corp. .\" 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. .\" .Dd September 10, 2013 .Dt HYPER-V 4 .Os .Sh NAME .Nm hv_storvsc .Nd Hyper-V Storage Virtual Service Consumer .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in the system kernel configuration file: .Bd -ragged -offset indent .Cd "device hyperv" .Ed .Sh DESCRIPTION The .Nm driver implements the virtual store device for .Fx guest partitions running on Hyper-V. .Fx guest partitions running on Hyper-V do not have direct access to storage devices attached to the Hyper-V server. Although a .Fx guest can access storage devices using Hyper-V's full emulation mode, the performance in this mode tends to be unsatisfactory. .Pp To counter the above issues, the .Nm driver implements a storage Virtual Service Consumer (VSC) that relays storage requests from the guest partition to the storage Virtual Service Provider (VSP) hosted in the root partition using the high performance data exchange infrastructure provided by .Xr hv_vmbus 4 driver. The VSP in the root partition then forwards the storage related requests to the physical storage device. .Pp -This driver functions by presenting a SCSI HBA interface to the Comman Access +This driver functions by presenting a SCSI HBA interface to the Common Access Method (CAM) layer. CAM control blocks (CCBs) are converted into VSCSI protocol messages which are delivered to the root partition VSP over the Hyper-V VMBus. .Sh SEE ALSO .Xr hv_ata_pci_disengage 4 , .Xr hv_netvsc 4 , .Xr hv_utils 4 , .Xr hv_vmbus 4 .Sh HISTORY Support for .Nm first appeared in .Fx 10.0 . The driver was developed through a joint effort between Citrix Incorporated, Microsoft Corporation, and Network Appliance Incorporated. .Sh AUTHORS .An -nosplit .Fx support for .Nm was first added by .An Microsoft BSD Integration Services Team Aq Mt bsdic@microsoft.com . diff --git a/share/man/man4/hv_vss.4 b/share/man/man4/hv_vss.4 index 600fd10eb426..33c7c2abb3c1 100644 --- a/share/man/man4/hv_vss.4 +++ b/share/man/man4/hv_vss.4 @@ -1,373 +1,373 @@ .\" Copyright (c) 2016 Microsoft Corp. .\" 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. .Dd October 12, 2016 .Dt HV_VSS 4 .Os .Sh NAME .Nm hv_vss .Nd Hyper-V Volume Shadow Copy Service API .Sh SYNOPSIS .In dev/hyperv/hv_snapshot.h .Bd -literal #define VSS_SUCCESS 0x00000000 #define VSS_FAIL 0x00000001 enum hv_vss_op_t { HV_VSS_NONE = 0, HV_VSS_CHECK, HV_VSS_FREEZE, HV_VSS_THAW, HV_VSS_COUNT }; struct hv_vss_opt_msg { uint32_t opt; /* operation */ uint32_t status; /* 0 for success, 1 for error */ uint64_t msgid; /* an ID used to identify the transaction */ uint8_t reserved[48]; /* reserved values are all zeroes */ }; .Ed .Sh DESCRIPTION The freeze or thaw functionality of application is important to guarantee the application consistent backup. On windows platform, VSS is defined to do live backup. But for VM guest running on Hyper-V, the corresponding VSS is not defined yet. For example, a running database server instance, it knows when the applications' freeze/thaw should start or finish. But it is not aware of the freeze/thaw notification from Hyper-V host. The .Nm is designed to notify application freeze/thaw request. Thus, it plays a role of broker to forward the freeze/thaw command from Hyper-V host to userland application if it registered VSS service on .Fx VM, and sends the result back to Hyper-V host. .Pp Generally, .Xr hv_vss_daemon 8 takes the responsibility to freeze/thaw UFS file system, and it is automatically launched after system boots. When Hyper-V host wants to take a snapshot of the .Fx VM, it will first send VSS capability check to .Fx VM. The .Nm received the request and forward the request to userland application if it is registered. Only after .Nm received the VSS_SUCCESS response from application, the .Xr hv_vss_daemon 8 will be informed to check whether file system freeze/thaw is supported. Any error occurs during this period, .Nm will inform Hyper-V host that VSS is not supported. In addition, there is a default timeout limit before sending response to Hyper-V host. If the total response time from application and .Xr hv_vss_daemon 8 exceeds this value, timeout -will occurs and VSS unsupported is responsed to Hyper-V host. +will occur and VSS unsupported is responded to Hyper-V host. .Pp After Hyper-V host confirmed the .Fx VM supports VSS, it will send freeze request to VM, and .Nm will first forward it to application. After application finished freezing, it should inform .Nm and file system level freezing will be triggered by .Xr hv_vss_daemon 8 . After all freezing on both application and .Xr hv_vss_daemon 8 were finished, the .Nm will inform Hyper-V host that freezing is done. Of course, there is a timeout limit as same as VSS capability is set to make sure freezing on .Fx VM is not hang. If there is any error occurs or timeout happened, the freezing is failed on Hyper-V side. .Pp Hyper-V host will send thaw request after taking the snapshot, typically, this period is very short in order not to block the running application. .Nm firstly thaw the file system by notifying .Xr hv_vss_daemon 8 , then notifies user registered application. There is also a timeout check before sending response to Hyper-V host. .Pp All the default timeout limit used in VSS capability check, freeze or thaw is the same. It is 15 seconds currently. .Sh NOTES .Nm only support UFS currently. If any of file system partition is non UFS, the VSS capability check will fail. If application does not register VSS, .Nm only support backup for file system level consistent. The device should be closed before it was opened again. If you want to simultaneously open "/dev/hv_appvss_dev" two or more times, an error (-1) will be returned, and errno was set. .Pp If .Xr hv_vss_daemon 8 was killed after system boots, the VSS functionality will not work. .Sh EXAMPLES The following is a complete example which does nothing except for waiting 2 seconds when receiving those notifications from .Nm .Bd -literal #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #define UNDEF_FREEZE_THAW (0) #define FREEZE (1) #define THAW (2) #define CHECK (3) #define VSS_LOG(priority, format, args...) do { \\ if (is_debugging == 1) { \\ if (is_daemon == 1) \\ syslog(priority, format, ## args); \\ else \\ printf(format, ## args); \\ } else { \\ if (priority < LOG_DEBUG) { \\ if (is_daemon == 1) \\ syslog(priority, format, ## args); \\ else \\ printf(format, ## args); \\ } \\ } \\ } while(0) #define CHECK_TIMEOUT 1 #define CHECK_FAIL 2 #define FREEZE_TIMEOUT 1 #define FREEZE_FAIL 2 #define THAW_TIMEOUT 1 #define THAW_FAIL 2 static int is_daemon = 1; static int is_debugging = 0; static int simu_opt_waiting = 2; // seconds #define GENERIC_OPT(TIMEOUT, FAIL) \\ do { \\ sleep(simu_opt_waiting); \\ if (opt == CHECK_TIMEOUT) { \\ sleep(simu_opt_waiting * 10); \\ VSS_LOG(LOG_INFO, "%s timeout simulation\\n", \\ __func__); \\ return (0); \\ } else if (opt == CHECK_FAIL) { \\ VSS_LOG(LOG_INFO, "%s failure simulation\\n", \\ __func__); \\ return (CHECK_FAIL); \\ } else { \\ VSS_LOG(LOG_INFO, "%s success simulation\\n", \\ __func__); \\ return (0); \\ } \\ } while (0) static int check(int opt) { GENERIC_OPT(CHECK_TIMEOUT, CHECK_FAIL); } static int freeze(int opt) { GENERIC_OPT(FREEZE_TIMEOUT, FREEZE_FAIL); } static int thaw(int opt) { GENERIC_OPT(THAW_TIMEOUT, THAW_FAIL); } static void usage(const char* cmd) { fprintf(stderr, "%s -f <0|1|2>: simulate app freeze." " 0: successful, 1: freeze timeout, 2: freeze failed\\n" " -c <0|1|2>: simulate vss feature check" " -t <0|1|2>: simulate app thaw." " 0: successful, 1: freeze timeout, 2: freeze failed\\n" " -d : enable debug mode\\n" " -n : run this tool under non-daemon mode\\n", cmd); } int main(int argc, char* argv[]) { int ch, freezesimuop = 0, thawsimuop = 0, checksimuop = 0, fd, r, error; uint32_t op; struct pollfd app_vss_fd[1]; struct hv_vss_opt_msg userdata; while ((ch = getopt(argc, argv, "f:c:t:dnh")) != -1) { switch (ch) { case 'f': /* Run as regular process for debugging purpose. */ freezesimuop = (int)strtol(optarg, NULL, 10); break; case 't': thawsimuop = (int)strtol(optarg, NULL, 10); break; case 'c': checksimuop = (int)strtol(optarg, NULL, 10); break; case 'd': is_debugging = 1; break; case 'n': is_daemon = 0; break; case 'h': default: usage(argv[0]); exit(0); } } openlog("APPVSS", 0, LOG_USER); /* Become daemon first. */ if (is_daemon == 1) daemon(1, 0); else VSS_LOG(LOG_DEBUG, "Run as regular process.\\n"); VSS_LOG(LOG_INFO, "HV_VSS starting; pid is: %d\\n", getpid()); fd = open(VSS_DEV(APP_VSS_DEV_NAME), O_RDWR); if (fd < 0) { VSS_LOG(LOG_ERR, "Fail to open %s, error: %d %s\\n", VSS_DEV(APP_VSS_DEV_NAME), errno, strerror(errno)); exit(EXIT_FAILURE); } app_vss_fd[0].fd = fd; app_vss_fd[0].events = POLLIN | POLLRDNORM; while (1) { r = poll(app_vss_fd, 1, INFTIM); VSS_LOG(LOG_DEBUG, "poll returned r = %d, revent = 0x%x\\n", r, app_vss_fd[0].revents); if (r == 0 || (r < 0 && errno == EAGAIN) || (r < 0 && errno == EINTR)) { /* Nothing to read */ continue; } if (r < 0) { /* * For poll return failure other than EAGAIN, * we want to exit. */ VSS_LOG(LOG_ERR, "Poll failed.\\n"); perror("poll"); exit(EIO); } /* Read from character device */ error = ioctl(fd, IOCHVVSSREAD, &userdata); if (error < 0) { VSS_LOG(LOG_ERR, "Read failed.\\n"); perror("pread"); exit(EIO); } if (userdata.status != 0) { VSS_LOG(LOG_ERR, "data read error\\n"); continue; } op = userdata.opt; switch (op) { case HV_VSS_CHECK: error = check(checksimuop); break; case HV_VSS_FREEZE: error = freeze(freezesimuop); break; case HV_VSS_THAW: error = thaw(thawsimuop); break; default: VSS_LOG(LOG_ERR, "Illegal operation: %d\\n", op); error = VSS_FAIL; } if (error) userdata.status = VSS_FAIL; else userdata.status = VSS_SUCCESS; error = ioctl(fd, IOCHVVSSWRITE, &userdata); if (error != 0) { VSS_LOG(LOG_ERR, "Fail to write to device\\n"); exit(EXIT_FAILURE); } else { VSS_LOG(LOG_INFO, "Send response %d for %s to kernel\\n", userdata.status, op == HV_VSS_FREEZE ? "Freeze" : (op == HV_VSS_THAW ? "Thaw" : "Check")); } } return 0; } .Ed .Sh SEE ALSO .Xr hv_utils 4 , .Xr hv_vss_daemon 8 .Sh HISTORY The daemon was introduced in October 2016 and developed by Microsoft Corp. .Sh AUTHORS .An -nosplit .Fx support for .Nm was first added by .An Microsoft BSD Integration Services Team Aq Mt bsdic@microsoft.com . diff --git a/share/man/man4/iflib.4 b/share/man/man4/iflib.4 index 4fad38d2c01f..0114263e6ca2 100644 --- a/share/man/man4/iflib.4 +++ b/share/man/man4/iflib.4 @@ -1,213 +1,213 @@ .Dd September 27, 2018 .Dt IFLIB 4 .Os .Sh NAME .Nm iflib .Nd Network Interface Driver Framework .Sh SYNOPSIS .Cd "device pci" .Cd "device iflib" .Sh DESCRIPTION .Nm is a framework for network interface drivers for .Fx . It is designed to remove a large amount of the boilerplate that is often needed for modern network interface devices, allowing driver authors to focus on the specific code needed for their hardware. This allows for a shared set of .Xr sysctl 8 names, rather than each driver naming them individually. .Sh SYSCTL VARIABLES These variables must be set before loading the driver, either via .Xr loader.conf 5 or through the use of .Xr kenv 1 . They are all prefixed by .Va dev.X.Y.iflib\&. where X is the driver name, and Y is the instance number. .Bl -tag -width indent .It Va override_nrxds Override the number of RX descriptors for each queue. The value is a comma separated list of positive integers. Some drivers only use a single value, but others may use more. These numbers must be powers of two, and zero means to use the default. Individual drivers may have additional restrictions on allowable values. Defaults to all zeros. .It Va override_ntxds Override the number of TX descriptors for each queue. The value is a comma separated list of positive integers. Some drivers only use a single value, but others may use more. These numbers must be powers of two, and zero means to use the default. Individual drivers may have additional restrictions on allowable values. Defaults to all zeros. .It Va override_qs_enable When set, allows the number of transmit and receive queues to be different. If not set, the lower of the number of TX or RX queues will be used for both. .It Va override_nrxqs Set the number of RX queues. If zero, the number of RX queues is derived from the number of cores on the socket connected to the controller. Defaults to 0. .It Va override_ntxqs Set the number of TX queues. If zero, the number of TX queues is derived from the number of cores on the socket connected to the controller. .It Va disable_msix Disables MSI-X interrupts for the device. .It Va core_offset Specifies a starting core offset to assign queues to. If the value is unspecified or 65535, cores are assigned sequentially across controllers. .It Va separate_txrx Requests that RX and TX queues not be paired on the same core. If this is zero or not set, an RX and TX queue pair will be assigned to each core. When set to a non-zero value, TX queues are assigned to cores following the last RX queue. .El .Pp These .Xr sysctl 8 variables can be changed at any time: .Bl -tag -width indent .It Va tx_abdicate Controls how the transmit ring is serviced. If set to zero, when a frame is submitted to the transmission ring, the same task that is submitting it will service the ring unless there's already a task servicing the TX ring. This ensures that whenever there is a pending transmission, the transmit ring is being serviced. This results in higher transmit throughput. If set to a non-zero value, task returns immediately and the transmit ring is serviced by a different task. This returns control to the caller faster and under high receive load, may result in fewer dropped RX frames. .It Va rx_budget Sets the maximum number of frames to be received at a time. Zero (the default) indicates the default (currently 16) should be used. .El .Pp There are also some global sysctls which can change behaviour for all drivers, and may be changed at any time. .Bl -tag -width indent .It Va net.iflib.min_tx_latency If this is set to a non-zero value, iflib will avoid any attempt to combine multiple transmits, and notify the hardware as quickly as possible of new descriptors. This will lower the maximum throughput, but will also lower transmit latency. .It Va net.iflib.no_tx_batch Some NICs allow processing completed transmit descriptors in batches. Doing so usually increases the transmit throughput by reducing the number of transmit interrupts. Setting this to a non-zero value will disable the use of this feature. .El .Pp These .Xr sysctl 8 variables are read-only: .Bl -tag -width indent .It Va driver_version A string indicating the internal version of the driver. .El .Pp There are a number of queue state .Xr sysctl 8 variables as well: .Bl -tag -width indent .It Va txqZ The following are repeated for each transmit queue, where Z is the transmit queue instance number: .Bl -tag -width indent .It Va r_abdications Number of consumer abdications in the MP ring for this queue. An abdication occurs on every ring submission when tx_abdicate is true. .It Va r_restarts Number of consumer restarts in the MP ring for this queue. A restart occurs when an attempt to drain a non-empty ring fails, and the ring is already in the STALLED state. .It Va r_stalls Number of consumer stalls in the MP ring for this queue. A stall occurs when an attempt to drain a non-empty ring fails. .It Va r_starts Number of normal consumer starts in the MP ring for this queue. A start occurs when the MP ring transitions from IDLE to BUSY. .It Va r_drops Number of drops in the MP ring for this queue. A drop occurs when there is an attempt to add an entry to an MP ring with no available space. .It Va r_enqueues Number of entries which have been enqueued to the MP ring for this queue. .It Va ring_state MP (soft) ring state. -This privides a snapshot of the current MP ring state, including the producer +This provides a snapshot of the current MP ring state, including the producer head and tail indexes, the consumer index, and the state. The state is one of "IDLE", "BUSY", "STALLED", or "ABDICATED". .It Va txq_cleaned The number of transmit descriptors which have been reclaimed. Total cleaned. .It Va txq_processed The number of transmit descriptors which have been processed, but may not yet have been reclaimed. .It Va txq_in_use Descriptors which have been added to the transmit queue, but have not yet been cleaned. This value will include both untransmitted descriptors as well as descriptors which have been processed. .It Va txq_cidx_processed The transmit queue consumer index of the next descriptor to process. .It Va txq_cidx The transmit queue consumer index of the oldest descriptor to reclaim. .It Va txq_pidx The transmit queue producer index where the next descriptor to transmit will be inserted. .It Va no_tx_dma_setup Number of times DMA mapping a transmit mbuf failed for reasons other than .Er EFBIG . .It Va txd_encap_efbig Number of times DMA mapping a transmit mbuf failed due to requiring too many segments. .It Va tx_map_failed Number of times DMA mapping a transmit mbuf failed for any reason (sum of no_tx_dma_setup and txd_encap_efbig) .It Va no_desc_avail Number of times a descriptor couldn't be added to the transmit ring because the transmit ring was full. .It Va mbuf_defrag_failed Number of times both .Xr m_collapse 9 and .Xr m_defrag 9 failed after an .Er EFBIG error result from DMA mapping a transmit mbuf. .It Va m_pullups Number of times .Xr m_pullup 9 was called attempting to parse a header. .It Va mbuf_defrag Number of times .Xr m_defrag 9 was called. .El .It Va rxqZ The following are repeated for each receive queue, where Z is the receive queue instance number: .Bl -tag -width indent .It Va rxq_fl0.credits Credits currently available in the receive ring. .It Va rxq_fl0.cidx Current receive ring consumer index. .It Va rxq_fl0.pidx Current receive ring producer index. .El .El .Pp Additional OIDs useful for driver and iflib development are exposed when the INVARIANTS and/or WITNESS options are enabled in the kernel. .Sh SEE ALSO .Xr iflib 9 .Sh HISTORY This framework was introduced in .Fx 11.0 . diff --git a/share/man/man4/ip.4 b/share/man/man4/ip.4 index 8e9ed6725a80..c52715a43380 100644 --- a/share/man/man4/ip.4 +++ b/share/man/man4/ip.4 @@ -1,952 +1,952 @@ .\" Copyright (c) 1983, 1991, 1993 .\" The Regents of the University of California. 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. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 9, 2021 .Dt IP 4 .Os .Sh NAME .Nm ip .Nd Internet Protocol .Sh SYNOPSIS .In sys/types.h .In sys/socket.h .In netinet/in.h .Ft int .Fn socket AF_INET SOCK_RAW proto .Sh DESCRIPTION .Tn IP is the transport layer protocol used by the Internet protocol family. Options may be set at the .Tn IP level when using higher-level protocols that are based on .Tn IP (such as .Tn TCP and .Tn UDP ) . It may also be accessed through a .Dq raw socket when developing new protocols, or special-purpose applications. .Pp There are several .Tn IP-level .Xr setsockopt 2 and .Xr getsockopt 2 options. .Dv IP_OPTIONS may be used to provide .Tn IP options to be transmitted in the .Tn IP header of each outgoing packet or to examine the header options on incoming packets. .Tn IP options may be used with any socket type in the Internet family. The format of .Tn IP options to be sent is that specified by the .Tn IP protocol specification (RFC-791), with one exception: the list of addresses for Source Route options must include the first-hop gateway at the beginning of the list of gateways. The first-hop gateway address will be extracted from the option list and the size adjusted accordingly before use. To disable previously specified options, use a zero-length buffer: .Bd -literal setsockopt(s, IPPROTO_IP, IP_OPTIONS, NULL, 0); .Ed .Pp .Dv IP_TOS may be used to set the differential service codepoint (DSCP) and the -explicit congestion notfication (ECN) codepoint. +explicit congestion notification (ECN) codepoint. Setting the ECN codepoint - the two least significant bits - on a socket using a transport protocol implementing ECN has no effect. .Pp .Dv IP_TTL configures the time-to-live (TTL) field in the .Tn IP header for .Dv SOCK_STREAM , SOCK_DGRAM , and certain types of .Dv SOCK_RAW sockets. For example, .Bd -literal int tos = IPTOS_DSCP_EF; /* see */ setsockopt(s, IPPROTO_IP, IP_TOS, &tos, sizeof(tos)); int ttl = 60; /* max = 255 */ setsockopt(s, IPPROTO_IP, IP_TTL, &ttl, sizeof(ttl)); .Ed .Pp .Dv IP_IPSEC_POLICY controls IPSec policy for sockets. For example, .Bd -literal const char *policy = "in ipsec ah/transport//require"; char *buf = ipsec_set_policy(policy, strlen(policy)); setsockopt(s, IPPROTO_IP, IP_IPSEC_POLICY, buf, ipsec_get_policylen(buf)); .Ed .Pp .Dv IP_MINTTL may be used to set the minimum acceptable TTL a packet must have when received on a socket. All packets with a lower TTL are silently dropped. This option is only really useful when set to 255, preventing packets from outside the directly connected networks reaching local listeners on sockets. .Pp .Dv IP_DONTFRAG may be used to set the Don't Fragment flag on IP packets. Currently this option is respected only on .Xr udp 4 and raw .Nm sockets, unless the .Dv IP_HDRINCL option has been set. On .Xr tcp 4 sockets, the Don't Fragment flag is controlled by the Path MTU Discovery option. Sending a packet larger than the MTU size of the egress interface, determined by the destination address, returns an .Er EMSGSIZE error. .Pp If the .Dv IP_ORIGDSTADDR option is enabled on a .Dv SOCK_DGRAM socket, the .Xr recvmsg 2 call will return the destination .Tn IP address and destination port for a .Tn UDP datagram. The .Vt msg_control field in the .Vt msghdr structure points to a buffer that contains a .Vt cmsghdr structure followed by the .Tn sockaddr_in structure. The .Vt cmsghdr fields have the following values: .Bd -literal cmsg_len = CMSG_LEN(sizeof(struct sockaddr_in)) cmsg_level = IPPROTO_IP cmsg_type = IP_ORIGDSTADDR .Ed .Pp If the .Dv IP_RECVDSTADDR option is enabled on a .Dv SOCK_DGRAM socket, the .Xr recvmsg 2 call will return the destination .Tn IP address for a .Tn UDP datagram. The .Vt msg_control field in the .Vt msghdr structure points to a buffer that contains a .Vt cmsghdr structure followed by the .Tn IP address. The .Vt cmsghdr fields have the following values: .Bd -literal cmsg_len = CMSG_LEN(sizeof(struct in_addr)) cmsg_level = IPPROTO_IP cmsg_type = IP_RECVDSTADDR .Ed .Pp The source address to be used for outgoing .Tn UDP datagrams on a socket can be specified as ancillary data with a type code of .Dv IP_SENDSRCADDR . The msg_control field in the msghdr structure should point to a buffer that contains a .Vt cmsghdr structure followed by the .Tn IP address. The cmsghdr fields should have the following values: .Bd -literal cmsg_len = CMSG_LEN(sizeof(struct in_addr)) cmsg_level = IPPROTO_IP cmsg_type = IP_SENDSRCADDR .Ed .Pp The socket should be either bound to .Dv INADDR_ANY and a local port, and the address supplied with .Dv IP_SENDSRCADDR -should't be +shouldn't be .Dv INADDR_ANY , or the socket should be bound to a local address and the address supplied with .Dv IP_SENDSRCADDR should be .Dv INADDR_ANY . In the latter case bound address is overridden via generic source address selection logic, which would choose IP address of interface closest to destination. .Pp For convenience, .Dv IP_SENDSRCADDR is defined to have the same value as .Dv IP_RECVDSTADDR , so the .Dv IP_RECVDSTADDR control message from .Xr recvmsg 2 can be used directly as a control message for .Xr sendmsg 2 . .\" .Pp If the .Dv IP_ONESBCAST option is enabled on a .Dv SOCK_DGRAM or a .Dv SOCK_RAW socket, the destination address of outgoing broadcast datagrams on that socket will be forced to the undirected broadcast address, .Dv INADDR_BROADCAST , before transmission. This is in contrast to the default behavior of the system, which is to transmit undirected broadcasts via the first network interface with the .Dv IFF_BROADCAST flag set. .Pp This option allows applications to choose which interface is used to transmit an undirected broadcast datagram. For example, the following code would force an undirected broadcast to be transmitted via the interface configured with the broadcast address 192.168.2.255: .Bd -literal char msg[512]; struct sockaddr_in sin; int onesbcast = 1; /* 0 = disable (default), 1 = enable */ setsockopt(s, IPPROTO_IP, IP_ONESBCAST, &onesbcast, sizeof(onesbcast)); sin.sin_addr.s_addr = inet_addr("192.168.2.255"); sin.sin_port = htons(1234); sendto(s, msg, sizeof(msg), 0, &sin, sizeof(sin)); .Ed .Pp It is the application's responsibility to set the .Dv IP_TTL option to an appropriate value in order to prevent broadcast storms. The application must have sufficient credentials to set the .Dv SO_BROADCAST socket level option, otherwise the .Dv IP_ONESBCAST option has no effect. .Pp If the .Dv IP_BINDANY option is enabled on a .Dv SOCK_STREAM , .Dv SOCK_DGRAM or a .Dv SOCK_RAW socket, one can .Xr bind 2 to any address, even one not bound to any available network interface in the system. This functionality (in conjunction with special firewall rules) can be used for implementing a transparent proxy. The .Dv PRIV_NETINET_BINDANY privilege is needed to set this option. .Pp If the .Dv IP_RECVTTL option is enabled on a .Dv SOCK_DGRAM socket, the .Xr recvmsg 2 call will return the .Tn IP .Tn TTL (time to live) field for a .Tn UDP datagram. The msg_control field in the msghdr structure points to a buffer that contains a cmsghdr structure followed by the .Tn TTL . The cmsghdr fields have the following values: .Bd -literal cmsg_len = CMSG_LEN(sizeof(u_char)) cmsg_level = IPPROTO_IP cmsg_type = IP_RECVTTL .Ed .\" .Pp If the .Dv IP_RECVTOS option is enabled on a .Dv SOCK_DGRAM socket, the .Xr recvmsg 2 call will return the .Tn IP .Tn TOS (type of service) field for a .Tn UDP datagram. The msg_control field in the msghdr structure points to a buffer that contains a cmsghdr structure followed by the .Tn TOS . The cmsghdr fields have the following values: .Bd -literal cmsg_len = CMSG_LEN(sizeof(u_char)) cmsg_level = IPPROTO_IP cmsg_type = IP_RECVTOS .Ed .\" .Pp If the .Dv IP_RECVIF option is enabled on a .Dv SOCK_DGRAM socket, the .Xr recvmsg 2 call returns a .Vt "struct sockaddr_dl" corresponding to the interface on which the packet was received. The .Va msg_control field in the .Vt msghdr structure points to a buffer that contains a .Vt cmsghdr structure followed by the .Vt "struct sockaddr_dl" . The .Vt cmsghdr fields have the following values: .Bd -literal cmsg_len = CMSG_LEN(sizeof(struct sockaddr_dl)) cmsg_level = IPPROTO_IP cmsg_type = IP_RECVIF .Ed .Pp .Dv IP_PORTRANGE may be used to set the port range used for selecting a local port number on a socket with an unspecified (zero) port number. It has the following possible values: .Bl -tag -width IP_PORTRANGE_DEFAULT .It Dv IP_PORTRANGE_DEFAULT use the default range of values, normally .Dv IPPORT_HIFIRSTAUTO through .Dv IPPORT_HILASTAUTO . This is adjustable through the sysctl setting: .Va net.inet.ip.portrange.first and .Va net.inet.ip.portrange.last . .It Dv IP_PORTRANGE_HIGH use a high range of values, normally .Dv IPPORT_HIFIRSTAUTO and .Dv IPPORT_HILASTAUTO . This is adjustable through the sysctl setting: .Va net.inet.ip.portrange.hifirst and .Va net.inet.ip.portrange.hilast . .It Dv IP_PORTRANGE_LOW use a low range of ports, which are normally restricted to privileged processes on .Ux systems. The range is normally from .Dv IPPORT_RESERVED \- 1 down to .Li IPPORT_RESERVEDSTART in descending order. This is adjustable through the sysctl setting: .Va net.inet.ip.portrange.lowfirst and .Va net.inet.ip.portrange.lowlast . .El .Pp The range of privileged ports which only may be opened by root-owned processes may be modified by the .Va net.inet.ip.portrange.reservedlow and .Va net.inet.ip.portrange.reservedhigh sysctl settings. The values default to the traditional range, 0 through .Dv IPPORT_RESERVED \- 1 (0 through 1023), respectively. Note that these settings do not affect and are not accounted for in the use or calculation of the other .Va net.inet.ip.portrange values above. Changing these values departs from .Ux tradition and has security consequences that the administrator should carefully evaluate before modifying these settings. .Pp Ports are allocated at random within the specified port range in order to increase the difficulty of random spoofing attacks. 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. .Ss "Multicast Options" .Tn IP multicasting is supported only on .Dv AF_INET sockets of type .Dv SOCK_DGRAM and .Dv SOCK_RAW , and only on networks where the interface driver supports multicasting. .Pp The .Dv IP_MULTICAST_TTL option changes the time-to-live (TTL) for outgoing multicast datagrams in order to control the scope of the multicasts: .Bd -literal u_char ttl; /* range: 0 to 255, default = 1 */ setsockopt(s, IPPROTO_IP, IP_MULTICAST_TTL, &ttl, sizeof(ttl)); .Ed .Pp Datagrams with a TTL of 1 are not forwarded beyond the local network. Multicast datagrams with a TTL of 0 will not be transmitted on any network, but may be delivered locally if the sending host belongs to the destination group and if multicast loopback has not been disabled on the sending socket (see below). Multicast datagrams with TTL greater than 1 may be forwarded to other networks if a multicast router is attached to the local network. .Pp For hosts with multiple interfaces, where an interface has not been specified for a multicast group membership, each multicast transmission is sent from the primary network interface. The .Dv IP_MULTICAST_IF option overrides the default for subsequent transmissions from a given socket: .Bd -literal struct in_addr addr; setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, &addr, sizeof(addr)); .Ed .Pp where "addr" is the local .Tn IP address of the desired interface or .Dv INADDR_ANY to specify the default interface. .Pp To specify an interface by index, an instance of .Vt ip_mreqn may be passed instead. The .Vt imr_ifindex member should be set to the index of the desired interface, or 0 to specify the default interface. The kernel differentiates between these two structures by their size. .Pp The use of .Vt IP_MULTICAST_IF is .Em not recommended , as multicast memberships are scoped to each individual interface. It is supported for legacy use only by applications, such as routing daemons, which expect to be able to transmit link-local IPv4 multicast datagrams (224.0.0.0/24) on multiple interfaces, without requesting an individual membership for each interface. .Pp .\" An interface's local IP address and multicast capability can be obtained via the .Dv SIOCGIFCONF and .Dv SIOCGIFFLAGS ioctls. Normal applications should not need to use this option. .Pp If a multicast datagram is sent to a group to which the sending host itself belongs (on the outgoing interface), a copy of the datagram is, by default, looped back by the IP layer for local delivery. The .Dv IP_MULTICAST_LOOP option gives the sender explicit control over whether or not subsequent datagrams are looped back: .Bd -literal u_char loop; /* 0 = disable, 1 = enable (default) */ setsockopt(s, IPPROTO_IP, IP_MULTICAST_LOOP, &loop, sizeof(loop)); .Ed .Pp This option improves performance for applications that may have no more than one instance on a single host (such as a routing daemon), by eliminating the overhead of receiving their own transmissions. It should generally not be used by applications for which there may be more than one instance on a single host (such as a conferencing program) or for which the sender does not belong to the destination group (such as a time querying program). .Pp The sysctl setting .Va net.inet.ip.mcast.loop controls the default setting of the .Dv IP_MULTICAST_LOOP socket option for new sockets. .Pp A multicast datagram sent with an initial TTL greater than 1 may be delivered to the sending host on a different interface from that on which it was sent, if the host belongs to the destination group on that other interface. The loopback control option has no effect on such delivery. .Pp A host must become a member of a multicast group before it can receive datagrams sent to the group. To join a multicast group, use the .Dv IP_ADD_MEMBERSHIP option: .Bd -literal struct ip_mreqn mreqn; setsockopt(s, IPPROTO_IP, IP_ADD_MEMBERSHIP, &mreqn, sizeof(mreqn)); .Ed .Pp where .Fa mreqn is the following structure: .Bd -literal struct ip_mreqn { struct in_addr imr_multiaddr; /* IP multicast address of group */ struct in_addr imr_interface; /* local IP address of interface */ int imr_ifindex; /* interface index */ } .Ed .Pp .Va imr_ifindex should be set to the index of a particular multicast-capable interface if the host is multihomed. If .Va imr_ifindex is non-zero, value of .Va imr_interface is ignored. Otherwise, if .Va imr_ifindex is 0, kernel will use IP address from .Va imr_interface to lookup the interface. Value of .Va imr_interface may be set to .Va INADDR_ANY to choose the default interface, although this is not recommended; this is considered to be the first interface corresponding to the default route. Otherwise, the first multicast-capable interface configured in the system will be used. .Pp Legacy .Vt "struct ip_mreq" , that lacks .Va imr_ifindex field is also supported by .Dv IP_ADD_MEMBERSHIP setsockopt. In this case kernel would behave as if .Va imr_ifindex was set to zero: .Va imr_interface will be used to lookup interface. .Pp Prior to .Fx 7.0 , if the .Va imr_interface member is within the network range .Li 0.0.0.0/8 , it is treated as an interface index in the system interface MIB, as per the RIP Version 2 MIB Extension (RFC-1724). In versions of .Fx since 7.0, this behavior is no longer supported. Developers should instead use the RFC 3678 multicast source filter APIs; in particular, .Dv MCAST_JOIN_GROUP . .Pp Up to .Dv IP_MAX_MEMBERSHIPS memberships may be added on a single socket. Membership is associated with a single interface; programs running on multihomed hosts may need to join the same group on more than one interface. .Pp To drop a membership, use: .Bd -literal struct ip_mreq mreq; setsockopt(s, IPPROTO_IP, IP_DROP_MEMBERSHIP, &mreq, sizeof(mreq)); .Ed .Pp where .Fa mreq contains the same values as used to add the membership. Memberships are dropped when the socket is closed or the process exits. .\" TODO: Update this piece when IPv4 source-address selection is implemented. .Pp The IGMP protocol uses the primary IP address of the interface as its identifier for group membership. This is the first IP address configured on the interface. If this address is removed or changed, the results are undefined, as the IGMP membership state will then be inconsistent. If multiple IP aliases are configured on the same interface, they will be ignored. .Pp This shortcoming was addressed in IPv6; MLDv2 requires that the unique link-local address for an interface is used to identify an MLDv2 listener. .Ss "Source-Specific Multicast Options" Since .Fx 8.0 , the use of Source-Specific Multicast (SSM) is supported. These extensions require an IGMPv3 multicast router in order to make best use of them. If a legacy multicast router is present on the link, .Fx will simply downgrade to the version of IGMP spoken by the router, and the benefits of source filtering on the upstream link will not be present, although the kernel will continue to squelch transmissions from blocked sources. .Pp Each group membership on a socket now has a filter mode: .Bl -tag -width MCAST_EXCLUDE .It Dv MCAST_EXCLUDE Datagrams sent to this group are accepted, unless the source is in a list of blocked source addresses. .It Dv MCAST_INCLUDE Datagrams sent to this group are accepted only if the source is in a list of accepted source addresses. .El .Pp Groups joined using the legacy .Dv IP_ADD_MEMBERSHIP option are placed in exclusive-mode, and are able to request that certain sources are blocked or allowed. This is known as the .Em delta-based API . .Pp To block a multicast source on an existing group membership: .Bd -literal struct ip_mreq_source mreqs; setsockopt(s, IPPROTO_IP, IP_BLOCK_SOURCE, &mreqs, sizeof(mreqs)); .Ed .Pp where .Fa mreqs is the following structure: .Bd -literal struct ip_mreq_source { struct in_addr imr_multiaddr; /* IP multicast address of group */ struct in_addr imr_sourceaddr; /* IP address of source */ struct in_addr imr_interface; /* local IP address of interface */ } .Ed .Va imr_sourceaddr should be set to the address of the source to be blocked. .Pp To unblock a multicast source on an existing group: .Bd -literal struct ip_mreq_source mreqs; setsockopt(s, IPPROTO_IP, IP_UNBLOCK_SOURCE, &mreqs, sizeof(mreqs)); .Ed .Pp The .Dv IP_BLOCK_SOURCE and .Dv IP_UNBLOCK_SOURCE options are .Em not permitted for inclusive-mode group memberships. .Pp To join a multicast group in .Dv MCAST_INCLUDE mode with a single source, or add another source to an existing inclusive-mode membership: .Bd -literal struct ip_mreq_source mreqs; setsockopt(s, IPPROTO_IP, IP_ADD_SOURCE_MEMBERSHIP, &mreqs, sizeof(mreqs)); .Ed .Pp To leave a single source from an existing group in inclusive mode: .Bd -literal struct ip_mreq_source mreqs; setsockopt(s, IPPROTO_IP, IP_DROP_SOURCE_MEMBERSHIP, &mreqs, sizeof(mreqs)); .Ed If this is the last accepted source for the group, the membership will be dropped. .Pp The .Dv IP_ADD_SOURCE_MEMBERSHIP and .Dv IP_DROP_SOURCE_MEMBERSHIP options are .Em not accepted for exclusive-mode group memberships. However, both exclusive and inclusive mode memberships support the use of the .Em full-state API documented in RFC 3678. For management of source filter lists using this API, please refer to .Xr sourcefilter 3 . .Pp The sysctl settings .Va net.inet.ip.mcast.maxsocksrc and .Va net.inet.ip.mcast.maxgrpsrc are used to specify an upper limit on the number of per-socket and per-group source filter entries which the kernel may allocate. .\"----------------------- .Ss "Raw IP Sockets" Raw .Tn IP sockets are connectionless, and are normally used with the .Xr sendto 2 and .Xr recvfrom 2 calls, though the .Xr connect 2 call may also be used to fix the destination for future packets (in which case the .Xr read 2 or .Xr recv 2 and .Xr write 2 or .Xr send 2 system calls may be used). .Pp If .Fa proto is 0, the default protocol .Dv IPPROTO_RAW is used for outgoing packets, and only incoming packets destined for that protocol are received. If .Fa proto is non-zero, that protocol number will be used on outgoing packets and to filter incoming packets. .Pp Outgoing packets automatically have an .Tn IP header prepended to them (based on the destination address and the protocol number the socket is created with), unless the .Dv IP_HDRINCL option has been set. Unlike in previous .Bx releases, incoming packets are received with .Tn IP header and options intact, leaving all fields in network byte order. .Pp .Dv IP_HDRINCL indicates the complete IP header is included with the data and may be used only with the .Dv SOCK_RAW type. .Bd -literal #include #include int hincl = 1; /* 1 = on, 0 = off */ setsockopt(s, IPPROTO_IP, IP_HDRINCL, &hincl, sizeof(hincl)); .Ed .Pp Unlike previous .Bx releases, the program must set all the fields of the IP header, including the following: .Bd -literal ip->ip_v = IPVERSION; ip->ip_hl = hlen >> 2; ip->ip_id = 0; /* 0 means kernel set appropriate value */ ip->ip_off = htons(offset); ip->ip_len = htons(len); .Ed .Pp The packet should be provided as is to be sent over wire. This implies all fields, including .Va ip_len and .Va ip_off to be in network byte order. See .Xr byteorder 3 for more information on network byte order. If the .Va ip_id field is set to 0 then the kernel will choose an appropriate value. If the header source address is set to .Dv INADDR_ANY , the kernel will choose an appropriate address. .Sh ERRORS A socket operation may fail with one of the following errors returned: .Bl -tag -width Er .It Bq Er EISCONN when trying to establish a connection on a socket which already has one, or when trying to send a datagram with the destination address specified and the socket is already connected; .It Bq Er ENOTCONN when trying to send a datagram, but no destination address is specified, and the socket has not been connected; .It Bq Er ENOBUFS when the system runs out of memory for an internal data structure; .It Bq Er EADDRNOTAVAIL when an attempt is made to create a socket with a network address for which no network interface exists. .It Bq Er EACCES when an attempt is made to create a raw IP socket by a non-privileged process. .El .Pp The following errors specific to .Tn IP may occur when setting or getting .Tn IP options: .Bl -tag -width Er .It Bq Er EINVAL An unknown socket option name was given. .It Bq Er EINVAL The IP option field was improperly formed; an option field was shorter than the minimum value or longer than the option buffer provided. .El .Pp The following errors may occur when attempting to send .Tn IP datagrams via a .Dq raw socket with the .Dv IP_HDRINCL option set: .Bl -tag -width Er .It Bq Er EINVAL The user-supplied .Va ip_len field was not equal to the length of the datagram written to the socket. .El .Sh SEE ALSO .Xr getsockopt 2 , .Xr recv 2 , .Xr send 2 , .Xr byteorder 3 , .Xr CMSG_DATA 3 , .Xr sourcefilter 3 , .Xr icmp 4 , .Xr igmp 4 , .Xr inet 4 , .Xr intro 4 , .Xr multicast 4 .Rs .%A D. Thaler .%A B. Fenner .%A B. Quinn .%T "Socket Interface Extensions for Multicast Source Filters" .%N RFC 3678 .%D Jan 2004 .Re .Sh HISTORY The .Nm protocol appeared in .Bx 4.2 . The .Vt ip_mreqn structure appeared in .Tn Linux 2.4 . .Sh BUGS Before .Fx 10.0 packets received on raw IP sockets had the .Va ip_hl subtracted from the .Va ip_len field. .Pp Before .Fx 11.0 packets received on raw IP sockets had the .Va ip_len and .Va ip_off fields converted to host byte order. Packets written to raw IP sockets were expected to have .Va ip_len and .Va ip_off in host byte order. diff --git a/share/man/man4/mlx5io.4 b/share/man/man4/mlx5io.4 index 4ccbf7f99b0b..66a767d97d31 100644 --- a/share/man/man4/mlx5io.4 +++ b/share/man/man4/mlx5io.4 @@ -1,189 +1,189 @@ .\" .\" Copyright (c) 2018, 2019 Mellanox Technologies .\" 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. .\" .Dd October 2, 2019 .Dt mlx5io 4 .Os .Sh NAME .Nm mlx5io .Nd IOCTL interface to manage Connect-X 4/5/6 Mellanox network adapters .Sh SYNOPSIS .In dev/mlx5/mlx5io.h .Sh DESCRIPTION The .Nm interface is provided for management of the Connect-X4, 5 and 6 network adapters in the aspects not covered by the generic network configuration, mostly related to the PCIe attachment and internal card working. Interface consists of the commands, which are passed by means of .Xr ioctl 2 on the file descriptor, opened from the .Pa /dev/mlx5ctl device node. .Pp The following commands are implemented: .Bl -tag -width indent .It Dv MLX5_FWDUMP_FORCE Take the snapshot of the firmware registers state and store it in the kernel buffer. The buffer must be empty, in other words, no dumps should be written so far, or existing dump cleared with the .Dv MLX5_FWDUMP_RESET command for the specified device. The argument for the command should point to the .Vt struct mlx5_tool_addr structure, containing the PCIe bus address of the device. .Bd -literal struct mlx5_tool_addr { uint32_t domain; uint8_t bus; uint8_t slot; uint8_t func; }; .Ed .It Dv MLX5_FWDUMP_RESET Clear the stored firmware dump, preparing the kernel buffer for the next dump. The argument for the command should point to the .Vt struct mlx5_tool_addr structure, containing the PCIe bus address of the device. .It Dv MLX5_FWDUMP_GET Fetch the stored firmware dump into the user memory. The argument to the command should point to the input/output .Vt struct mlx5_fwdump_get structure. Its .Dv devaddr field specifies the address of the device, the .Dv buf fields points to the array of .Vt struct mlx5_fwdump_reg of records of the registers values, the size of the array is specified in the .Dv reg_cnt field. .Bd -literal struct mlx5_fwdump_get { struct mlx5_tool_addr devaddr; struct mlx5_fwdump_reg *buf; size_t reg_cnt; size_t reg_filled; /* out */ }; .Ed .Pp -On successfull return, the +On successful return, the .Dv reg_filled field reports the number of the .Dv buf array elements actually filled with the registers values. If .Dv buf contains the .Dv NULL pointer, no registers are filled, but .Dv reg_filled still contains the number of registers that should be passed for the complete dump. .Pp The .Vt struct mlx5_fwdump_reg element contains the address of the register in the field .Dv addr , and its value in the field .Dv val . .Bd -literal struct mlx5_fwdump_reg { uint32_t addr; uint32_t val; }; .Ed .It Dv MLX5_FW_UPDATE Requests firmware update (flash) on the adapter specified by the .Dv devaddr using the firmware image in .Dv MFA2 format. The argument for the ioctl command is the .Vt struct mlx5_fw_update with the following definition. .Bd -literal struct mlx5_fw_update { struct mlx5_tool_addr devaddr; void *img_fw_data; size_t img_fw_data_len; }; .Ed Image address in memory is passed in .Dv img_fw_data , the length of the image is specified in .Dv img_fw_data_len field. .It Dv MLX5_FW_RESET Requests PCIe link-level reset on the device. The address of the device is specified by the .Vt struct mlx5_tool_addr structure, which should be passed as an argument. .It Dv MLX5_EEPROM_GET Fetch EEPROM information. The argument to the command should point to the input/output .Vt struct mlx5_eeprom_get structure where, the .Dv devaddr field specifies the address of the device. .Bd -literal struct mlx5_eeprom_get { struct mlx5_tool_addr devaddr; size_t eeprom_info_page_valid; uint32_t *eeprom_info_buf; size_t eeprom_info_out_len; }; .Ed .Pp -On successfull return, the +On successful return, the .Dv eeprom_info_out_len field reports the length of the EEPROM information. .Dv eeprom_info_buf field contains the actual EEPROM information. .Dv eeprom_info_page_valid field reports the third page validity. .El .Sh FILES The .Pa /dev/mlx5ctl .Xr devfs 5 node is used to pass commands to the driver. .Sh RETURN VALUES If successful, the IOCTL returns zero. Otherwise, -1 is returned and the global variable .Va errno is set to indicate the error. .Sh SEE ALSO .Xr errno 2 , .Xr ioctl 2 , .Xr mlx5en 4 , .Xr mlx5ib 4 , .Xr mlx5tool 8 and .Xr pci 9 . diff --git a/share/man/man4/mod_cc.4 b/share/man/man4/mod_cc.4 index cbc98bd6803a..f17c6100ce23 100644 --- a/share/man/man4/mod_cc.4 +++ b/share/man/man4/mod_cc.4 @@ -1,207 +1,207 @@ .\" .\" Copyright (c) 2010-2011 The FreeBSD Foundation .\" .\" This documentation was written at the Centre for Advanced Internet .\" Architectures, Swinburne University of Technology, Melbourne, Australia by .\" David Hayes and Lawrence Stewart 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. .\" .Dd September 13, 2022 .Dt MOD_CC 4 .Os .Sh NAME .Nm mod_cc .Nd Modular congestion control .Sh DESCRIPTION The modular congestion control framework allows the TCP implementation to dynamically change the congestion control algorithm used by new and existing connections. Algorithms are identified by a unique .Xr ascii 7 name. Algorithm modules can be compiled into the kernel or loaded as kernel modules using the .Xr kld 4 facility. .Pp The default algorithm is CUBIC, and all connections use the default unless explicitly overridden using the .Dv TCP_CONGESTION socket option (see .Xr tcp 4 for details). The default can be changed using a .Xr sysctl 3 MIB variable detailed in the .Sx MIB Variables section below. .Pp Algorithm specific parameters can be set or queried using the .Dv TCP_CCALGOOPT socket option (see .Xr tcp 4 for details). Callers must pass a pointer to an algorithm specific data, and specify its size. .Pp Unloading a congestion control module will fail if it is used as a default by any Vnet. When unloading a module, the Vnet default is used to switch a connection to an alternate congestion control. Note that the new congestion control module may fail to initialize its internal memory, if so it will fail the module unload. If this occurs often times retrying the unload will succeed since the temporary memory shortage as the new CC module malloc's memory, that prevented the switch is often transient. .Sh MIB Variables The framework exposes the following variables in the .Va net.inet.tcp.cc branch of the .Xr sysctl 3 MIB: .Bl -tag -width ".Va hystartplusplus.css_growth_div" .It Va available Read-only list of currently available congestion control algorithms by name. .It Va algorithm Returns the current default congestion control algorithm when read, and changes the default when set. When attempting to change the default algorithm, this variable should be set to one of the names listed by the .Va net.inet.tcp.cc.available MIB variable. .It Va abe Enable support for RFC 8511, which alters the window decrease factor applied to the congestion window in response to an ECN congestion signal. Refer to individual congestion control man pages to determine if they implement support for ABE and for configuration details. .It Va abe_frlossreduce If non-zero, apply standard beta instead of ABE-beta during ECN-signalled congestion recovery episodes if loss also needs to be repaired. .It Va hystartplusplus.bblogs This boolean controls if black box logging will be done for hystart++ events. If set to zero (the default) no logging is performed. If set to one then black box logs will be generated on all hystart++ events. .It Va hystartplusplus.css_rounds This value controls the number of rounds that CSS runs for. The default value matches the current internet-draft of 5. .It Va hystartplusplus.css_growth_div This value controls the divisor applied to slowstart during CSS. The default value matches the current internet-draft of 4. .It Va hystartplusplus.n_rttsamples This value controls how many rtt samples must be collected in each round for hystart++ to be active. The default value matches the current internet-draft of 8. .It Va hystartplusplus.maxrtt_thresh This value controls the maximum rtt variance clamp when considering if CSS is needed. The default value matches the current internet-draft of 16000 (in microseconds). For further explanation please see the internet-draft. .It Va hystartplusplus.minrtt_thresh This value controls the minimum rtt variance clamp when considering if CSS is needed. The default value matches the current internet-draft of 4000 (in microseconds). For further explanation please see the internet-draft. .El .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. .Sh Kernel Configuration All of the available congestion control modules may also be loaded -via kernel configutation options. +via kernel configuration options. A kernel configuration is required to have at least one congestion control algorithm built into it via kernel option and a system default specified. Compilation of the kernel will fail if these two conditions are not met. .Sh Kernel Configuration Options 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. .It Va CC_CUBIC 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. .It Va CC_CDG This directive loads the cdg congestion control algorithm, note that this algorithm also requires the TCP_HHOOK option as well. .It Va CC_DCTCP This directive loads the dctcp congestion control algorithm. .It Va CC_HD This directive loads the hd congestion control algorithm, note that this algorithm also requires the TCP_HHOOK option as well. .It Va CC_CHD This directive loads the chd congestion control algorithm, note that this algorithm also requires the TCP_HHOOK option as well. .It Va CC_HTCP 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 CUBIC. .El .Sh SEE ALSO .Xr cc_cdg 4 , .Xr cc_chd 4 , .Xr cc_cubic 4 , .Xr cc_dctcp 4 , .Xr cc_hd 4 , .Xr cc_htcp 4 , .Xr cc_newreno 4 , .Xr cc_vegas 4 , .Xr tcp 4 , .Xr config 5 , .Xr config 8 , .Xr mod_cc 9 .Sh ACKNOWLEDGEMENTS Development and testing of this software were made possible in part by grants from the FreeBSD Foundation and Cisco University Research Program Fund at Community Foundation Silicon Valley. .Sh HISTORY The .Nm modular congestion control framework first appeared in .Fx 9.0 . .Pp The framework was first released in 2007 by James Healy and Lawrence Stewart whilst working on the NewTCP research project at Swinburne University of Technology's Centre for Advanced Internet Architectures, Melbourne, Australia, which was made possible in part by a grant from the Cisco University Research Program Fund at Community Foundation Silicon Valley. More details are available at: .Pp http://caia.swin.edu.au/urp/newtcp/ .Sh AUTHORS .An -nosplit The .Nm facility was written by .An Lawrence Stewart Aq Mt lstewart@FreeBSD.org , .An James Healy Aq Mt jimmy@deefa.com and .An David Hayes Aq Mt david.hayes@ieee.org . .Pp This manual page was written by .An David Hayes Aq Mt david.hayes@ieee.org and .An Lawrence Stewart Aq Mt lstewart@FreeBSD.org . diff --git a/share/man/man4/ng_bridge.4 b/share/man/man4/ng_bridge.4 index 1999214c30bc..45bc6b3cb6a7 100644 --- a/share/man/man4/ng_bridge.4 +++ b/share/man/man4/ng_bridge.4 @@ -1,268 +1,268 @@ .\" Copyright (c) 2000 Whistle Communications, Inc. .\" All rights reserved. .\" .\" Subject to the following obligations and disclaimer of warranty, use and .\" redistribution of this software, in source or object code forms, with or .\" without modifications are expressly permitted by Whistle Communications; .\" provided, however, that: .\" 1. Any and all reproductions of the source or object code must include the .\" copyright notice above and the following disclaimer of warranties; and .\" 2. No rights are granted, in any manner or form, to use Whistle .\" Communications, Inc. trademarks, including the mark "WHISTLE .\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as .\" such appears in the above copyright notice or in the software. .\" .\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, .\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. .\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY .\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS .\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. .\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES .\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING .\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, .\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY .\" OF SUCH DAMAGE. .\" .\" Author: Archie Cobbs .\" .Dd May 13, 2021 .Dt NG_BRIDGE 4 .Os .Sh NAME .Nm ng_bridge .Nd Ethernet bridging netgraph node type .Sh SYNOPSIS .In sys/types.h .In netgraph/ng_bridge.h .Sh DESCRIPTION The .Nm bridge node type performs Ethernet bridging over one or more links. Each link (represented by a connected hook) is used to transmit and receive raw Ethernet frames. As packets are received, the node learns which link each host resides on. Packets unicast to a known host are directed out the appropriate link only, and other links are spared the traffic. This behavior is in contrast to a hub, which always forwards every received packet to every other link. .Sh LOOP DETECTION The .Nm bridge node incorporates a simple loop detection algorithm. A loop is when two ports are connected to the same physical medium. Loops are important to avoid because of packet storms, which severely degrade performance. A packet storm results when the same packet is sent and received over and over again. If a host is detected on link A, and is then detected on link B within a certain time period after first being detected on link A, then link B is considered to be a looped back link. The time period is called the minimum stable time. .Pp A looped back link will be temporarily muted, i.e., all traffic received on that link is ignored. .Sh IPFW PROCESSING Processing of IP packets via the .Xr ipfirewall 4 mechanism on a per-link basis is not yet implemented. .Sh HOOKS This node type supports an unlimited number of hooks. Each connected hook represents a bridged link. The hooks are named .Ar link0 , .Ar link1 , etc. Typically these hooks are connected to the .Ar lower hooks of one or more .Xr ng_ether 4 nodes. To connect the host machine to a bridged network, simply connect the .Ar upper hook of an .Xr ng_ether 4 node to the bridge node. .Pp Instead of naming a hook .Ar linkX the hook might be also named .Ar uplinkX . The node does not learn MAC addresses on uplink hooks, which keeps the internal address table small. This way it is desirable to connect the .Ar lower hook of an .Xr ng_ether 4 node to an .Ar uplink hook of the bridge, and ignore the complexity of the outside world. Frames with unknown MACs are always sent out to .Ar uplink hooks, so no functionality is lost. .Pp Frames with unknown destination MAC addresses are replicated to any available hook, unless the first connected hook is an .Ar uplink hook. In this case the node assumes, that all unknown MAC addresses are -located soley on the +located solely on the .Ar uplink hooks and only those hooks will be used to send out frames with unknown destination MACs. If the first connected hook is an .Ar link hook, the node will replicate such frames to all types of hooks, even if .Ar uplink hooks are connected later. .Sh CONTROL MESSAGES This node type supports the generic control messages, plus the following: .Bl -tag -width foo .It Dv NGM_BRIDGE_SET_CONFIG Pq Ar setconfig Set the node configuration. This command takes a .Vt "struct ng_bridge_config" as an argument: .Bd -literal -offset 0n /* Node configuration structure */ struct ng_bridge_config { u_char debugLevel; /* debug level */ uint32_t loopTimeout; /* link loopback mute time */ uint32_t maxStaleness; /* max host age before nuking */ uint32_t minStableAge; /* min time for a stable host */ }; .Ed .Pp The .Va debugLevel field sets the debug level on the node. At level of 2 or greater, detected loops are logged. The default level is 1. .Pp The .Va loopTimeout determines how long (in seconds) a looped link is muted. The default is 60 seconds. The .Va maxStaleness parameter determines how long a period of inactivity before a host's entry is forgotten. The default is 15 minutes. The .Va minStableAge determines how quickly a host must jump from one link to another before we declare a loopback condition. The default is one second. .It Dv NGM_BRIDGE_GET_CONFIG Pq Ar getconfig Returns the current configuration as a .Vt "struct ng_bridge_config" . .It Dv NGM_BRIDGE_RESET Pq Ar reset Causes the node to forget all hosts and unmute all links. The node configuration is not changed. .It Dv NGM_BRIDGE_GET_STATS Pq Ar getstats This command takes a four byte link number as an argument and returns a .Vt "struct ng_bridge_link_stats" containing statistics for the corresponding .Ar link , which must be currently connected: .Bd -literal -offset 0n /* Statistics structure (one for each link) */ struct ng_bridge_link_stats { uint64_t recvOctets; /* total octets rec'd on link */ uint64_t recvPackets; /* total pkts rec'd on link */ uint64_t recvMulticasts; /* multicast pkts rec'd on link */ uint64_t recvBroadcasts; /* broadcast pkts rec'd on link */ uint64_t recvUnknown; /* pkts rec'd with unknown dest addr */ uint64_t recvRunts; /* pkts rec'd less than 14 bytes */ uint64_t recvInvalid; /* pkts rec'd with bogus source addr */ uint64_t xmitOctets; /* total octets xmit'd on link */ uint64_t xmitPackets; /* total pkts xmit'd on link */ uint64_t xmitMulticasts; /* multicast pkts xmit'd on link */ uint64_t xmitBroadcasts; /* broadcast pkts xmit'd on link */ uint64_t loopDrops; /* pkts dropped due to loopback */ uint64_t loopDetects; /* number of loop detections */ uint64_t memoryFailures; /* times couldn't get mem or mbuf */ }; .Ed .Pp Negative numbers refer to the .Ar uplink hooks. So querying for -7 will get the statistics for hook .Ar uplink7 . .It Dv NGM_BRIDGE_CLR_STATS Pq Ar clrstats This command takes a four byte link number as an argument and clears the statistics for that link. .It Dv NGM_BRIDGE_GETCLR_STATS Pq Ar getclrstats Same as .Dv NGM_BRIDGE_GET_STATS , but also atomically clears the statistics as well. .It Dv NGM_BRIDGE_GET_TABLE Pq Ar gettable Returns the current host mapping table used to direct packets, in a .Vt "struct ng_bridge_host_ary" . .It Dv NGM_BRIDGE_SET_PERSISTENT Pq Ar setpersistent This command sets the persistent flag on the node, and takes no arguments. .It Dv NGM_BRIDGE_MOVE_HOST Pq Ar movehost This command takes a .Vt "struct ng_bridge_move_host" as an argument. It assigns the MAC .Va addr to the .Va hook . If the .Va hook is the empty string, the incoming hook of the control message is used as fallback. .Pp If necessary, the MAC is removed from the currently assigned hook and moved to the new one. If the MAC is moved faster than .Va minStableAge , the hook is considered as a loop and will block traffic for .Va loopTimeout seconds. .Bd -literal -offset 0n struct ng_bridge_move_host { u_char addr[ETHER_ADDR_LEN]; /* ethernet address */ char hook[NG_HOOKSIZ]; /* link where addr can be found */ }; .Ed .El .Sh SHUTDOWN This node shuts down upon receipt of a .Dv NGM_SHUTDOWN control message, or when all hooks have been disconnected. Setting the persistent flag via a .Dv NGM_BRIDGE_SET_PERSISTENT control message disables automatic node shutdown when the last hook gets disconnected. .Sh FILES .Bl -tag -width XXXXXXXX -compact .It Pa /usr/share/examples/netgraph/ether.bridge Example script showing how to set up a bridging network .El .Sh SEE ALSO .Xr if_bridge 4 , .Xr netgraph 4 , .Xr ng_ether 4 , .Xr ng_hub 4 , .Xr ng_one2many 4 , .Xr ngctl 8 .Sh HISTORY The .Nm node type was implemented in .Fx 4.2 . .Sh AUTHORS .An Archie Cobbs Aq Mt archie@FreeBSD.org diff --git a/share/man/man4/ng_macfilter.4 b/share/man/man4/ng_macfilter.4 index 9a5c4b6885e0..904f194f7fec 100644 --- a/share/man/man4/ng_macfilter.4 +++ b/share/man/man4/ng_macfilter.4 @@ -1,220 +1,220 @@ .\" Copyright (c) 2012-2017 Pekka Nikander .\" Copyright (c) 2018 Retina b.v. .\" 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. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" 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 December 10, 2018 .Dt NG_MACFILTER 4 .Os .Sh NAME .Nm ng_macfilter .Nd packet filtering netgraph node using ethernet MAC addresses .Sh SYNOPSIS .In sys/types.h .In netgraph/ng_macfilter.h .Sh DESCRIPTION The .Nm macfilter allows routing ethernet packets over different hooks based on the sender MAC address. .Pp This processing is done when traffic flows from the .Dq ether hook through .Nm macfilter to one of the outgoing hooks. Outbound hooks can be added to and remove from .Nm macfilter and arbitrarily named. By default one hook called .Dq default is present and used for all packets which have no MAC address in the MAC table. By adding MAC addresses to the MAC table traffic coming from this host can be directed out other hooks. .Nm macfilter keeps track of packets and bytes from and to this MAC address in the MAC table. .Pp Packets are not altered in any way. If hooks are not connected, packets are dropped. .Sh HOOKS This node type by default has an .Dv ether hook, to be connected to the .Dv lower hook of the NIC, and a .Dv default -hook where packets are sent if the MAC adddress is not found in the table. +hook where packets are sent if the MAC address is not found in the table. .Nm macfilter supports up to .Dv NG_MACFILTER_UPPER_NUM hooks to be connected to the NIC's upper hook. Other nodes can be inserted to provide additional processing. All outbound can be combined back into one by using .Dv ng_one2many . .Sh CONTROL MESSAGES This node type supports the generic control messages, plus the following: .Bl -tag -width foo .It Dv NGM_MACFILTER_RESET Pq Ic reset Resets the MAC table in the node. .It Dv NGM_MACFILTER_DIRECT Pq Ic direct Takes the following argument struct: .Bd -literal -offset indent struct ngm_macfilter_direct { u_char ether[ETHER_ADDR_LEN]; /* MAC address */ u_char hookname[NG_HOOKSIZ]; /* Upper hook name*/ }; .Ed The given ethernet MAC address will be forwarded out the named hook. .It Dv NGM_MACFILTER_DIRECT_HOOKID Pq Ic directi Takes the following argument struct: .Bd -literal -offset indent struct ngm_macfilter_direct_hookid { u_char ether[ETHER_ADDR_LEN]; /* MAC address */ u_int16_t hookid; /* Upper hook hookid */ }; .Ed The given ethernet MAC address will be forwarded out the hook at id .Dv hookid . .It Dv NGM_MACFILTER_GET_MACS Pq Ic getmacs Returns the list of MAC addresses in the node in the following structure: .Bd -literal -offset indent struct ngm_macfilter_mac { u_char ether[ETHER_ADDR_LEN]; /* MAC address */ u_int16_t hookid; /* Upper hook hookid */ u_int64_t packets_in; /* packets in from downstream */ u_int64_t bytes_in; /* bytes in from upstream */ u_int64_t packets_out; /* packets out towards downstream */ u_int64_t bytes_out; /* bytes out towards downstream */ }; struct ngm_macfilter_macs { u_int32_t n; /* Number of entries in macs */ struct ngm_macfilter_mac macs[]; /* Macs table */ }; .Ed .It Dv NGM_MACFILTER_GETCLR_MACS Pq Ic getclrmacs Same as above, but will also atomically clear the .Dv packets_in , .Dv bytes_in , .Dv packets_out , and .Dv bytes_out fields in the table. .It Dv NGM_MACFILTER_CLR_STATS Pq Ic clrmacs Will clear the per MAC address packet and byte counters. .It Dv NGM_MACFILTER_GET_HOOKS Pq Ic gethooks Will return a list of hooks and their hookids in an array of the following struct's: .Bd -literal -offset indent struct ngm_macfilter_hook { u_char hookname[NG_HOOKSIZ]; /* Upper hook name*/ u_int16_t hookid; /* Upper hook hookid */ u_int32_t maccnt; /* Number of mac addresses associated with hook */ }; .Ed .El .Sh SHUTDOWN This node shuts down upon receipt of a .Dv NGM_SHUTDOWN control message or when all have been disconnected. .Sh EXAMPLES The following netgraph configuration will apply .Xr ipfw 8 tag 42 to each packet that is routed over the .Dq accepted hook. The graph looks like the following: .Bd -literal -offset indent /-------[combiner]---------\\ | / \\ [em0] | [tagger] \\ / | \\-----[macfilter]------/ .Ed .Pp Commands: .Bd -literal -offset indent ngctl mkpeer em0: macfilter lower ether ngctl name em0:lower macfilter # Funnel both streams back into ether:upper ngctl mkpeer em0: one2many upper one ngctl name em0:upper recombiner # Connect macfilter:default to recombiner:many0 ngctl connect macfilter: recombiner: default many0 # Connect macfilter:accepted to tagger:in ngctl mkpeer macfilter: tag accepted in ngctl name macfilter:accepted tagger # Connect tagger:out to recombiner:many1 ngctl connect tagger: recombiner: out many1 # Mark tag all traffic through tagger in -> out with an ipfw tag 42 ngctl msg tagger: sethookin '{ thisHook="in" ifNotMatch="out" }' ngctl msg tagger: sethookout '{ thisHook="out" tag_cookie=1148380143 tag_id=42 }' # Pass traffic from ether:upper / combiner:one via combiner:many0 on to # macfilter:default and on to ether:lower. ngctl msg recombiner: setconfig '{ xmitAlg=3 failAlg=1 enabledLinks=[ 1 1 ] }' .Ed .Pp .Em Note : The tag_cookie 1148380143 was retrieved from .Dv MTAG_IPFW in .Pa /usr/include/netinet/ip_var.h . .Pp The following command can be used to add a MAC address to be output via .Dv macfilter:accepted : .Bd -literal -offset indent ngctl msg macfilter: direct '{ hookname="known" ether=08:00:27:92:eb:aa }' .Ed .Pp The following command can be used to retrieve the packet and byte counters : .Bd -literal -offset indent ngctl msg macfilter: getmacs .Ed .Pp It will return the contents of the MAC table: .Bd -literal -offset indent Rec'd response "getmacs" (4) from "[54]:": Args: { n=1 macs=[ { ether=08:00:27:92:eb:aa hookid=1 packets_in=3571 bytes_in=592631 packets_out=3437 bytes_out=777142 } ] } .Ed .Sh SEE ALSO .Xr divert 4 , .Xr ipfw 4 , .Xr netgraph 4 , .Xr ng_ether 4 , .Xr ng_one2many 4 , .Xr ng_tag 4 , .Xr ngctl 8 .Sh AUTHORS .An -nosplit The original version of this code was written by Pekka Nikander, and subsequently modified heavily by .An Nick Hibma Aq Mt n_hibma@FreeBSD.org . .Sh BUGS None known. diff --git a/share/man/man4/ng_pptpgre.4 b/share/man/man4/ng_pptpgre.4 index c97dc313d369..935b9ec9334b 100644 --- a/share/man/man4/ng_pptpgre.4 +++ b/share/man/man4/ng_pptpgre.4 @@ -1,198 +1,198 @@ .\" Copyright (c) 1996-1999 Whistle Communications, Inc. .\" All rights reserved. .\" .\" Subject to the following obligations and disclaimer of warranty, use and .\" redistribution of this software, in source or object code forms, with or .\" without modifications are expressly permitted by Whistle Communications; .\" provided, however, that: .\" 1. Any and all reproductions of the source or object code must include the .\" copyright notice above and the following disclaimer of warranties; and .\" 2. No rights are granted, in any manner or form, to use Whistle .\" Communications, Inc. trademarks, including the mark "WHISTLE .\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as .\" such appears in the above copyright notice or in the software. .\" .\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, .\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. .\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY .\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS .\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. .\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES .\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING .\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, .\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY .\" OF SUCH DAMAGE. .\" .\" Author: Archie Cobbs .\" $Whistle: ng_pptpgre.8,v 1.2 1999/12/08 00:20:53 archie Exp $ .\" .Dd November 4, 2018 .Dt NG_PPTPGRE 4 .Os .Sh NAME .Nm ng_pptpgre .Nd PPTP GRE protocol netgraph node type .Sh SYNOPSIS .In sys/types.h .In netgraph/ng_pptpgre.h .Sh DESCRIPTION The .Nm pptpgre node type performs Generic Routing Encapsulation (GRE) over IP for the PPTP protocol as specified by RFC 2637. This involves packet encapsulation, sequencing, acknowledgement, and an adaptive timeout sliding window mechanism. This node type does not handle any of the TCP control protocol or call negotiation defined by PPTP. .Pp This node type expects to receive complete IP packets, including the IP header, on the .Dq Li lower hook, but it transmits outgoing frames without any IP header. The typical use for this node type would be to connect the .Dq Li upper hook to one of the link hooks of a .Xr ng_ppp 4 node, and the .Dq Li lower hook to the .Dq Li "inet/raw/gre" hook of a .Xr ng_ksocket 4 node. .Sh HOOKS This node type supports the following hooks: .Bl -tag -width ".Va session_hhhh" .It Va session_hhhh Session 0xhhhh data packets to the upper protocol layers .It Va upper Same as session_hhhh, but for single session with configurable cid (legacy) .It Va lower Connection to the lower protocol layers .El .Sh CONTROL MESSAGES This node type supports the generic control messages, plus the following: .Bl -tag -width foo .It Dv NGM_PPTPGRE_SET_CONFIG Pq Ic setconfig This command resets and configures hook for a session. If corresponding session_hhhh hook is not connected, upper hook will be configured. This command takes a .Vt "struct ng_pptpgre_conf" as an argument: .Bd -literal /* Configuration for a session */ struct ng_pptpgre_conf { u_char enabled; /* enables traffic flow */ u_char enableDelayedAck; /* enables delayed acks */ u_char enableAlwaysAck; /* always include ack with data */ u_char enableWindowing; /* enable windowing algorithm */ uint16_t cid; /* my call id */ uint16_t peerCid; /* peer call id */ uint16_t recvWin; /* peer recv window size */ uint16_t peerPpd; /* peer packet processing delay (in 1/10 of a second) */ }; .Ed .Pp The .Va enabled field enables traffic flow through the node. The .Va enableDelayedAck field enables delayed acknowledgement (maximum 250 milliseconds), which is a useful optimization and should generally be turned on. .Va enableAlwaysAck field enables sending acknowledgements with every data packet, which is probably helpful as well. .Pp .Va enableWindowing enables the PPTP packet windowing mechanism specified by the protocol. Disabling this will cause the node to violate the protocol, possibly confusing other PPTP peers, but often results in better performance. The windowing mechanism is a design error in the PPTP protocol; L2TP, the successor to PPTP, removes it. .Pp The remaining fields are as supplied by the PPTP virtual call setup process. .It Dv NGM_PPTPGRE_GET_CONFIG Pq Ic getconfig Takes two byte argument as cid and returns the current configuration as a .Vt "struct ng_pptpgre_conf" . .It Dv NGM_PPTPGRE_GET_STATS Pq Ic getstats This command returns a .Vt "struct ng_pptpgre_stats" containing various node statistics. .It Dv NGM_PPTPGRE_CLR_STATS Pq Ic clrstats This command resets the node statistics. .It Dv NGM_PPTPGRE_GETCLR_STATS Pq Ic getclrstats This command atomically gets and resets the node statistics, returning a .Vt "struct ng_pptpgre_stats" . .El .Sh SHUTDOWN This node shuts down upon receipt of a .Dv NGM_SHUTDOWN control message, or when both hooks have been disconnected. .Sh SYSCTL VARIABLES A set of .Xr sysctl 8 variables controls ability of this node to deal with some amount of packet reorder that sometimes happens in transit. Packet reorder results in packet drops (unless the order is restored) as PPP protocol can not deliver reordered data. These variables are shown below together with their default value and meaning: .Bl -tag -width indent .It Va net.graph.pptpgre.reorder_max: 1 Defines maximum length of node's private reorder queue used to keep data waiting for late packets. Zero value disables reordering. Default value allows the node to restore the order for two packets swapped in transit. Greater values allow the node to deliver packets being late after more packets in sequence at cost of increased kernel memory usage. .It Va net.graph.pptpgre.reorder_timeout: 1 -Defines time value in miliseconds used to wait for late packets. +Defines time value in milliseconds used to wait for late packets. .El .Sh SEE ALSO .Xr netgraph 4 , .Xr ng_ksocket 4 , .Xr ng_ppp 4 , .Xr ngctl 8 , .Xr sysctl 8 .Rs .%A K. Hamzeh .%A G. Pall .%A W. Verthein .%A J. Taarud .%A W. Little .%A G. Zorn .%T "Point-to-Point Tunneling Protocol (PPTP)" .%O RFC 2637 .Re .Rs .%A S. Hanks .%A T. \&Li .%A D. Farinacci .%A P. Traina .%T "Generic Routing Encapsulation over IPv4 networks" .%O RFC 1702 .Re .Sh HISTORY The .Nm node type was implemented in .Fx 4.0 . .Sh AUTHORS .An Archie Cobbs Aq Mt archie@FreeBSD.org .Sh BUGS The node should not expect incoming GRE packets to have an IP header. This behavior is inherited from the (converse) behavior of raw IP sockets. An intermediate node that strips IP headers in one direction should be used instead. diff --git a/share/man/man4/ng_vlan_rotate.4 b/share/man/man4/ng_vlan_rotate.4 index f1ed605c46b6..37bd6c17122a 100644 --- a/share/man/man4/ng_vlan_rotate.4 +++ b/share/man/man4/ng_vlan_rotate.4 @@ -1,250 +1,250 @@ .\"- .\" SPDX-License-Identifier: BSD-2-Clause .\" .\" Copyright (c) 2019-2021 IKS Service GmbH .\" .\" 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. .\" .\" Author: Lutz Donnerhacke .\" .Dd January 26, 2021 .Dt NG_VLAN_ROTATE 4 .Os .Sh NAME .Nm ng_vlan_rotate .Nd IEEE 802.1ad VLAN manipulation netgraph node type .Sh SYNOPSIS .In sys/types.h .In netgraph.h .In netgraph/ng_vlan_rotate.h .Sh DESCRIPTION The .Nm node type manipulates the order of VLAN tags of frames tagged according to the IEEE 802.1ad (an extension of IEEE 802.1Q) standard between different hooks. .Pp Each node has four special hooks, .Va original , .Va ordered , .Va excessive , and .Va incomplete . .Pp A frame tagged with an arbitrary number of .Dv ETHERTYPE_VLAN , .Dv ETHERTYPE_QINQ , and .Dv 0x9100 tags received on the .Va original hook will be rearranged to a new order of those tags and is sent out the .Dq ordered hook. After successful processing the .Va histogram counter for the observed stack size increments. .Pp If it contains fewer VLANs in the stack than the configured .Va min limit, the frame is sent out to the .Va incomplete hook and the .Va incomplete counter increments. .Pp If there are more VLANs in the stack than the configured .Va max limit, the frame is sent out to the .Va excessive hook and the .Va excessive counter increments. .Pp If the destination hook is not connected, the frame is dropped and the .Va drops counter increments. .Pp For Ethernet frames received on the .Va ordered hook, the transformation is reversed and is passed to the .Va original hook. Please note that this process is identical to the one described above, besides the ordered/original hooks are swapped and the transformation is reversed. .Pp An Ethernet frame received on the .Va incomplete or .Va excessive hook is forwarded to the .Va original hook without any modification. .Pp This node supports only one operation at the moment: Rotation of the VLANs in the stack. Setting the configuration parameter .Va rot to a positive value, the stack will roll up by this amount. Negative values will roll down. A typical scenario is setting the value to 1 in order to bring the innermost VLAN tag to the outmost level. Rotation includes the VLAN id, the ether type, and the QOS parameters pcp and cfi. Typical QOS handling refers to the outmost setting, so be careful to keep your QOS intact. .Sh HOOKS This node type supports the following hooks: .Bl -tag -width incomplete .It Va original Typically this hook would be connected to a .Xr ng_ether 4 node, using the .Va lower hook connected to a carrier network. .It Va ordered Typically this hook would be connected to a .Xr ng_vlan 4 type node using the .Va downstream hook in order to separate services. .It Va excessive see below. .It Va incomplete Typically those hooks would be attached to a .Xr ng_eiface 4 type node using the .Va ether hook for anomaly monitoring purposes. .El .Sh CONTROL MESSAGES This node type supports the generic control messages, plus the following: .Bl -tag -width foo .It Dv NGM_VLANROTATE_GET_CONF Pq Ic getconf Read the current configuration. .It Dv NGM_VLANROTATE_SET_CONF Pq Ic setconf Set the current configuration. .It Dv NGM_VLANROTATE_GET_STAT Pq Ic getstat Read the current statistics. .It Dv NGM_VLANROTATE_CLR_STAT Pq Ic clrstat Zeroize the statistics. .It Dv NGM_VLANROTATE_GETCLR_STAT Pq Ic getclrstat Read the current statistics and zeroize it in one step. .El .Sh EXAMPLES The first example demonstrates how to rotate double or triple tagged frames so that the innermost C-VLAN can be used as service discriminator. The single or double tagged frames (C-VLAN removed) are sent out to an -interface pointing to different infrastucture. +interface pointing to different infrastructure. .Bd -literal #!/bin/sh BNG_IF=ixl3 VOIP_IF=bge2 ngctl -f- < 00:01:02:03:04:05, ethertype 802.1Q-9100 (0x9100), length 110: vlan 2, p 1, ethertype 802.1Q-QinQ, vlan 101, p 0, ethertype 802.1Q, vlan 123, p 7, ethertype IPv4, (tos 0x0, ttl 64, id 15994, offset 0, flags [none], proto ICMP (1), length 84) 192.168.140.101 > 192.168.140.1: ICMP echo request, id 40234, seq 0, length 64 .Ed .Pp The frame ejected on the .Va ordered hook will look like this: .Bd -literal 00:00:00:00:01:01 > 00:01:02:03:04:05, ethertype 802.1Q (0x8100), length 110: vlan 123, p 7, ethertype 802.1Q-9100, vlan 2, p 1, ethertype 802.1Q-QinQ, vlan 101, p 0, ethertype IPv4, (tos 0x0, ttl 64, id 15994, offset 0, flags [none], proto ICMP (1), length 84) 192.168.140.101 > 192.168.140.1: ICMP echo request, id 40234, seq 0, length 64 .Ed .Pp Hence, the frame pushed out to the .Dv VOIP_IF will have this form: .Bd -literal 00:00:00:00:01:01 > 00:01:02:03:04:05, ethertype 802.1Q-9100, vlan 2, p 1, ethertype 802.1Q-QinQ, vlan 101, p 0, ethertype IPv4, (tos 0x0, ttl 64, id 15994, offset 0, flags [none], proto ICMP (1), length 84) 192.168.140.101 > 192.168.140.1: ICMP echo request, id 40234, seq 0, length 64 .Ed .Pp The second example distinguishes between double tagged and single tagged frames. .Bd -literal #!/bin/sh IN_IF=bge1 ngctl -f- < .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" .Dd September 25, 2015 .Dt OTUS 4 .Os .Sh NAME .Nm otus .Nd Atheros AR9170 USB IEEE 802.11a/b/g/n wireless network device .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device ehci" .Cd "device uhci" .Cd "device ohci" .Cd "device usb" .Cd "device otus" .Cd "device wlan" .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 if_otus_load="YES" .Ed .Sh DESCRIPTION The .Nm driver supports USB 2.0 wireless network devices based on the Atheros AR9170 chipset. .Pp The Atheros AR9170 is a draft-802.11n adapter that uses an external radio to operate in either 2.4GHz only or 2.4GHz and 5GHz. .Pp The AR9101 radio supports 1T1R operation in 2GHz only. .Pp The AR9102 radio supports 2T2R operation in 2GHz only. .Pp The AR9104 radio supports 2T2R operation both 2GHz and 5GHz. .Pp These are the modes the .Nm driver can operate in: .Bl -tag -width "IBSS-masterXX" .It BSS mode Also known as .Em infrastructure mode, this is used when associating with an access point, through which all traffic passes. This mode is the default. .El .Pp The .Nm driver can be configured to use Wired Equivalent Privacy (WEP) or Wi-Fi Protected Access (WPA-PSK and WPA2-PSK). WPA is the de facto encryption standard for wireless networks. It is strongly recommended that WEP not be used as the sole mechanism to secure wireless communication, due to serious weaknesses in it. .Pp The .Nm driver can be configured at runtime with .Xr ifconfig 8 . .Sh FILES The driver needs at least version 1.0 of the following firmware files, which is loaded when an interface is attached: .Pp .Bl -tag -width Ds -offset indent -compact .It Pa /boot/kernel/otusfw-init.ko .It Pa /boot/kernel/otusfw-main.ko .El .Sh HARDWARE The .Nm -driver provices support for Atheros AR9170 USB IEEE 802.11b/g/n +driver provides support for Atheros AR9170 USB IEEE 802.11b/g/n wireless network adapters, including: .Pp .Bl -tag -width Ds -offset indent -compact .It 3Com 3CRUSBN275 .It Arcadyan WN7512 .\" .It AVM FRITZ!WLAN USB Stick N .It CACE AirPcap \&Nx .It D-Link DWA-130 rev \&D1 .It D-Link DWA-160 rev A1 .It D-Link DWA-160 rev A2 .It IO-Data WN-GDN/US2 .It NEC Aterm WL300NU-G .It Netgear WNDA3100 .It Netgear WN111 v2 .It Planex GW-US300 .It SMC Networks SMCWUSB-N2 .It TP-Link TL-WN821N v1, v2 .It Ubiquiti SR71 USB .It Unex DNUA-81 .It Z-Com UB81 .It Z-Com UB82 .It ZyXEL NWD-271N .El .Sh EXAMPLES Join an existing BSS network (i.e., connect to an access point): .Bd -literal -offset indent ifconfig wlan create wlandev otus0 inet 192.168.0.20 \e netmask 0xffffff00 .Ed .Pp Join a specific BSS network with network name .Dq Li my_net : .Pp .Dl "ifconfig wlan create wlandev otus0 ssid my_net up" .Pp Join a specific BSS network with 64-bit WEP encryption: .Bd -literal -offset indent ifconfig wlan create wlandev otus0 ssid my_net \e wepmode on wepkey 0x1234567890 weptxkey 1 up .Ed .Sh DIAGNOSTICS .Bl -diag .It "%s: failed load firmware of file otusfw-main" For some reason, the driver was unable to read the microcode file from the filesystem. The file might be missing or corrupted. .El .Sh SEE ALSO .Xr intro 1 , .Xr netintro 4 , .Xr otusfw 4 , .Xr usb 4 , .Xr wlan 4 , .Xr arp 8 , .Xr hostapd 8 , .Xr ifconfig 8 , .Xr wpa_supplicant 8 .Sh HISTORY The .Nm driver first appeared in .Ox 4.6 . .Sh AUTHORS .An -nosplit The .Nm driver was written by .An Damien Bergamini Aq Mt damien@openbsd.org and ported by .An Adrian Chadd Aq Mt adrian@freebsd.org . .Sh CAVEATS The .Nm driver only supports 802.11a/b/g operations. 802.11n operation is not supported at this time. diff --git a/share/man/man4/proto.4 b/share/man/man4/proto.4 index a76f830b7bb3..889c07cdef81 100644 --- a/share/man/man4/proto.4 +++ b/share/man/man4/proto.4 @@ -1,473 +1,473 @@ .\" .\" Copyright (c) 2014, 2015 Marcel Moolenaar .\" 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 ``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 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 7, 2015 .Dt PROTO 4 .Os .\" .Sh NAME .Nm proto .Nd Generic prototyping and diagnostics driver .\" .Sh SYNOPSIS To compile this driver into the kernel, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "device proto" .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 proto_load="YES" .Ed .Pp To have the driver attach to a device instead of its regular driver, mention it in the list of devices assigned to the following loader variable: .Bd -ragged -offset indent hw.proto.attach="desc[,desc]" .Ed .\" .Sh DESCRIPTION The .Nm device driver attaches to PCI or ISA devices when no other device drivers are present for those devices and it creates device special files for all resources associated with the device. The driver itself has no knowledge of the device it attaches to. Programs can open these device special files and perform register-level reads and writes. As such, the .Nm device driver is nothing but a conduit or gateway between user space programs and the hardware device. .Pp Examples for why this is useful include hardware diagnostics and prototyping. In both these use cases, it is far more convenient to develop and run the logic in user space. Especially hardware diagnostics requires a somewhat user-friendly interface and adequate reporting. Neither is done easily as kernel code. .Ss I/O port resources Device special files created for I/O port resources allow .Xr lseek 2 , .Xr read 2 , .Xr write 2 and .Xr ioctl 2 operations to be performed on them. The .Xr read 2 and .Xr write 2 system calls are used to perform input and output (resp.) on the port. The amount of data that can be read or written at any single time is either 1, 2 or 4 bytes. While the .Nm driver does not prevent reading or writing 8 bytes at a time for some architectures, it should not be assumed that such actually produces correct results. The .Xr lseek 2 system call is used to select the port number, relative to the I/O port region being represented by the device special file. If, for example, the device special file corresponds to an I/O port region from 0x3f8 to 0x3ff inclusive, then an offset of 4 given to lseek with a whence value of SEEK_SET will target port 0x3fc on the next read or write operation. The .Xr ioctl 2 system call can be used for the .Dv PROTO_IOC_REGION request. This ioctl request returns the extend of the resource covered by this device special file. The extend is returned in the following structure: .Bd -literal struct proto_ioc_region { unsigned long address; unsigned long size; }; .Ed .Ss Memory mapped I/O resources The device special files created for memory mapped I/O resources behave in the same way as those created for I/O port resources. Additionally, device special files for memory mapped I/O resources allow the memory to be mapped into the process' address space using .Xr mmap 2 . Reads and writes to the memory address returned by .Xr mmap 2 go directly to the hardware. As such the use of .Xr read 2 and .Xr write 2 can be avoided, reducing the access overhead significantly. Alignment and access width constraints put forth by the underlying device apply. Also, make sure the compiler does not optimize memory accesses away or has them coalesced into bigger accesses. .Ss DMA pseudo resource A device special file named .Pa busdma is created for the purpose of doing DMA. It only supports .Xr ioctl 2 and only for the .Dv PROTO_IOC_BUSDMA request. This device special file does not support .Xr read 2 nor .Xr write 2 . The .Dv PROTO_IOC_BUSDMA request has an argument that is both in and out and is defined as follows: .Bd -literal struct proto_ioc_busdma { unsigned int request; unsigned long key; union { struct { unsigned long align; unsigned long bndry; unsigned long maxaddr; unsigned long maxsz; unsigned long maxsegsz; unsigned int nsegs; unsigned int datarate; unsigned int flags; } tag; struct { unsigned long tag; unsigned int flags; unsigned long virt_addr; unsigned long virt_size; unsigned int phys_nsegs; unsigned long phys_addr; unsigned long bus_addr; unsigned int bus_nsegs; } md; struct { unsigned int op; unsigned long base; unsigned long size; } sync; } u; unsigned long result; }; .Ed The .Va request field is used to specify which DMA operation is to be performed. The .Va key field is used to specify which object the operation applies to. An object is either a tag or a memory descriptor (md). The following DMA operations are defined: .Bl -tag -width XXXX .It PROTO_IOC_BUSDMA_TAG_CREATE Create a root tag. The .Va result field is set on output with the key of the DMA tag. The tag is created with the constraints given by the .Va tag sub-structure. These constraints correspond roughly to those that can be given to the .Xr bus_dma_tag_create 9 function. .It PROTO_IOC_BUSDMA_TAG_DERIVE Create a derived tag. The .Va key field is used to identify the parent tag from which to derive the new tag. The key of the derived tag is returned in the .Va result field. The derived tag combines the constraints of the parent tag with those given by the .Va tag sub-structure. The combined constraints are written back to the .Va tag sub-structure on return. .It PROTO_IOC_BUSDMA_TAG_DESTROY Destroy a root or derived tag previously created. The .Va key field specifies the tag to destroy. A tag can only be destroyed when not referenced anymore. This means that derived tags that have this tag as a parent and memory descriptors created from this tag must be destroyed first. .It PROTO_IOC_BUSDMA_MEM_ALLOC Allocate memory that satisfies the constraints put forth by the tag given in the .Va tag field of the .Va md sub-structure. The key of the memory descriptor for this memory is returned in the .Va result field. The .Va md sub-structure is filled on return with details of the allocation. The kernel virtual address and the size of the allocated memory are returned in the .Va virt_addr and .Va virt_size fields. -The number of contigous physical memory segments and the address of the first +The number of contiguous physical memory segments and the address of the first segment are returned in the .Va phys_nsegs and .Va phys_addr fields. Allocated memory is automatically loaded and thus mapped into bus space. The number of bus segments and the address of the first segment are returned in the .Va bus_nsegs and .Va bus_addr fields. The behaviour of this operation banks heavily on how .Xr bus_dmamem_alloc 9 is implemented, which means that memory is currently always allocated as a -single contigous region of physical memory. -In practice this also tends to give a single contigous region in bus space. +single contiguous region of physical memory. +In practice this also tends to give a single contiguous region in bus space. This may change over time. .It PROTO_IOC_BUSDMA_MEM_FREE Free previously allocated memory and destroy the memory descriptor. The .Nm driver is not in a position to track whether the memory has been mapped in the process' address space, so the application is responsible for unmapping the memory before it is freed. The .Nm driver also cannot protect against the hardware writing to or reading from the memory, even after it has been freed. When the memory is reused for other purposes it can be corrupted or cause the hardware to behave in unpredictable ways when DMA has not stopped completely before freeing. .It PROTO_IOC_BUSDMA_MD_CREATE Create an empty memory descriptor with the tag specified in the .Va tag field of the .Va md sub-structure. The key of the memory descriptor is returned in the .Va result field. .It PROTO_IOC_BUSDMA_MD_DESTROY Destroy the previously created memory descriptor specified by the .Va key field. When the memory descriptor is still loaded, it is unloaded first. .It PROTO_IOC_BUSDMA_MD_LOAD -Load a contigous region of memory in the memory descriptor specified by the +Load a contiguous region of memory in the memory descriptor specified by the .Va key field. The size and address in the process' virtual address space are specified by the .Va virt_size and .Va virt_addr fields. On return, the .Va md sub-structure contains the result of the operation. The number of physical segments and the address of the first segment is returned in the .Va phys_nsegs and .Va phys_addr fields. The number of bus space segments and the address of the first segment in bus space is returned in the .Va bus_nsegs and .Va bus_addr fields. .It PROTO_IOC_BUSDMA_MD_UNLOAD Unload the memory descriptor specified by the .Va key field. .It PROTO_IOC_BUSDMA_SYNC Guarantee that all hardware components have a coherent view of the memory tracked by the memory descriptor, specified by the .Va key field. A sub-section of the memory can be targeted by specifying the relative offset and size of the memory to make coherent. The offset and size are given by the .Va base and .Va size fields of the .Va sync sub-structure. The .Va op field holds the sync operation to be performed. This is similar to the .Xr bus_dmamap_sync 9 function. .El .Ss PCI configuration space Access to PCI configuration space is possible through the .Pa pcicfg device special file. The device special file supports .Xr lseek 2 , .Xr read 2 and .Xr write 2 . Usage is the asme as for I/O port resources. .Sh FILES All device special files corresponding to a PCI device are located under .Pa /dev/proto/pci::: with .Pa pci::: representing the location of the PCI device in the PCI hierarchy. A PCI location includes: .Pp .Bl -tag -width XXXXXX -compact -offset indent .It The PCI domain number .It The PCI bus number .It The PCI slot or device number .It The PCI function number .El .Pp Every PCI device has a device special file called .Pa pcicfg . This device special file gives access to the PCI configuration space. A device special file called .Pa busdma is also created. This device special file provides the interfaces needed for doing DMA. For each valid base address register (BAR), a device special file is created that contains the BAR offset and the resource type. A resource type can be either .Pa io or .Pa mem representing I/O port or memory mapped I/O space (resp.) .Pp ISA devices do not have a location. Instead, they are identified by the first I/O port address or first memory mapped I/O address. Consequently, all device special files corresponding to an ISA device are located under .Pa /dev/proto/isa: with .Pa addr the address in hexadecimal notation. For each I/O port or memory mapped I/O address, a device special file is created that contains the resource identification used by the kernel and the resource type. The resource type can be either .Pa io or .Pa mem representing I/O port or memory mapped I/O space (resp.) When the device has a DMA channel assigned to it, a device special file with the name .Pa busdma is created as well. This device special file provides the interfaces needed for doing DMA. .Pp If the ISA device is not a Plug-and-Play device nor present in the ACPI device tree, it must have the appropriate hints so that the kernel can reserve the resources for it. .\" .Sh EXAMPLES A single function PCI device in domain 0, on bus 1, in slot 2 and having a single memory mapped I/O region will have the following device special files: .Pp .Bl -tag -width XXXXXX -compact -offset indent .It Pa /dev/proto/pci0:1:2:0/10.mem .It Pa /dev/proto/pci0:1:2:0/pcicfg .El .Pp A legacy floppy controller will have the following device files: .Pp .Bl -tag -width XXXXXX -compact -offset indent .It Pa /dev/proto/isa:0x3f0/00.io .It Pa /dev/proto/isa:0x3f0/01.io .It Pa /dev/proto/isa:0x3f0/busdma .El .\" .Sh SEE ALSO .Xr ioctl 2 , .Xr lseek 2 , .Xr mmap 2 , .Xr read 2 , .Xr write 2 , .Xr bus_dma_tag_create 9 , .Xr bus_dmamap_sync 9 , .Xr bus_dmamem_alloc 9 .\" .Sh AUTHORS The .Nm device driver and this manual page were written by .An Marcel Moolenaar Aq Mt marcel@xcllnt.net . .Sh SECURITY CONSIDERATIONS Because programs have direct access to the hardware, the .Nm driver is inherently insecure. It is not advisable to use this driver on a production machine. .\" .Sh MISSING FUNCTIONALITY The .Nm driver does not fully support memory descriptors that need multiple physical memory segments or multiple bus space segments. At the very least, an operation is needed on the DMA pseudo resource for the application to obtain all segments. .Pp The .Nm driver does not yet support interrupts. Since interrupts cannot be handled by the driver itself, they must be converted into signals and delivered to the program that has registered for interrupts. A satisfactory mechanism for keeping the interrupt masked during the signal handling is still being worked out. .Pp DMA support for devices other than busmaster devices is not present yet. The details of how a program is to interact with the DMA controller still need to be fleshed out. diff --git a/share/man/man4/rsu.4 b/share/man/man4/rsu.4 index 34cebc598c0a..b523bfe4aa0e 100644 --- a/share/man/man4/rsu.4 +++ b/share/man/man4/rsu.4 @@ -1,196 +1,196 @@ .\" $OpenBSD: rsu.4,v 1.11 2013/02/14 07:40:42 jmc Exp $ .\" .\" Copyright (c) 2010 Damien Bergamini .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" .Dd May 23, 2021 .Dt RSU 4 .Os .Sh NAME .Nm rsu .Nd Realtek RTL8188SU/RTL8192SU USB IEEE 802.11b/g/n wireless network device .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device ehci" .Cd "device uhci" .Cd "device ohci" .Cd "device usb" .Cd "device rsu" .Cd "device rsufw" .Cd "device wlan" .Ed .Pp Alternatively, to load the driver as a module at boot time, place the following lines in .Xr loader.conf 5 : .Bd -literal -offset indent if_rsu_load="YES" rsu-rtl8712fw_load="YES" .Ed .Sh DESCRIPTION The .Nm driver supports USB 2.0 wireless network devices based on Realtek RTL8188SU, RTL8191SU and RTL8192SU chipsets. .Pp The RTL8188SU is a highly integrated 802.11n adapter that combines a MAC, a 1T1R capable baseband and an RF in a single chip. It operates in the 2GHz spectrum only. .Pp The RTL8191SU is a highly integrated multiple-in, single-out (MISO) 802.11n adapter that combines a MAC, a 1T2R capable baseband and an RF in a single chip. It operates in the 2GHz spectrum only. .Pp The RTL8192SU is a highly integrated multiple-in, multiple-out (MIMO) 802.11n adapter that combines a MAC, a 2T2R capable baseband and an RF in a single chip. It operates in the 2GHz spectrum only. .Pp These are the modes the .Nm driver can operate in: .Bl -tag -width "IBSS-masterXX" .It BSS mode Also known as .Em infrastructure mode, this is used when associating with an access point, through which all traffic passes. This mode is the default. .It monitor mode In this mode the driver is able to receive packets without associating with an access point. This disables the internal receive filter and enables the card to capture packets from networks which it wouldn't normally have access to, or to scan for access points. .El .Pp The .Nm driver can be configured to use Wired Equivalent Privacy (WEP) or Wi-Fi Protected Access (WPA-PSK and WPA2-PSK). WPA is the de facto encryption standard for wireless networks. It is strongly recommended that WEP not be used as the sole mechanism to secure wireless communication, due to serious weaknesses in it. .Pp The .Nm driver can be configured at runtime with .Xr ifconfig 8 . .Sh FILES .Bl -tag -width ".Pa /usr/share/doc/legal/realtek.LICENSE" -compact .It Pa /usr/share/doc/legal/realtek.LICENSE .Nm firmware license .El .Pp The driver needs at least version 1.2 of the following firmware file, which is loaded when an interface is attached: .Pp .Bl -tag -width Ds -offset indent -compact .It Pa /boot/kernel/rsu-rtl8712fw.ko .El .Sh HARDWARE The .Nm -driver provices support for Realtek RTL8188SU/RTL8192SU USB IEEE 802.11b/g/n +driver provides support for Realtek RTL8188SU/RTL8192SU USB IEEE 802.11b/g/n wireless network adapters, including: .Pp .Bl -tag -width Ds -offset indent -compact .It ASUS USB-N10 .It ASUS WL-167G V3 .It Belkin F7D1101 v1 .It D-Link DWA-131 A1 .It EDUP EP-MS150N(W) .It Edimax EW-7622UMN .It Hercules HWGUn-54 .It Hercules HWNUm-300 .It Planex GW-USNano .It Sitecom WL-349 v1 .It Sitecom WL-353 .It Sweex LW154 .It TRENDnet TEW-646UBH .It TRENDnet TEW-648UB .It TRENDnet TEW-649UB .El .Sh EXAMPLES Join an existing BSS network (i.e., connect to an access point): .Bd -literal -offset indent ifconfig wlan create wlandev rsu0 inet 192.168.0.20 \e netmask 0xffffff00 .Ed .Pp Join a specific BSS network with network name .Dq Li my_net : .Pp .Dl "ifconfig wlan create wlandev rsu0 ssid my_net up" .Pp Join a specific BSS network with 64-bit WEP encryption: .Bd -literal -offset indent ifconfig wlan create wlandev rsu0 ssid my_net \e wepmode on wepkey 0x1234567890 weptxkey 1 up .Ed .Sh DIAGNOSTICS .Bl -diag .It "%s: failed load firmware of file rsu-rtl8712fw" For some reason, the driver was unable to read the microcode file from the filesystem. The file might be missing or corrupted. .It "device timeout" A frame dispatched to the hardware for transmission did not complete in time. The driver will reset the hardware. This should not happen. .El .Sh SEE ALSO .Xr intro 1 , .Xr netintro 4 , .Xr rsufw 4 , .Xr usb 4 , .Xr wlan 4 , .Xr arp 8 , .Xr hostapd 8 , .Xr ifconfig 8 , .Xr wpa_supplicant 8 .Sh HISTORY The .Nm driver first appeared in .Ox 4.9 and .Fx 10.0 . .Sh AUTHORS .An -nosplit The .Nm driver was written by .An Damien Bergamini Aq Mt damien@openbsd.org and ported by .An Rui Paulo Aq Mt rpaulo@freebsd.org . The 802.11n support was added by .An Adrian Chadd Aq Mt adrian@freebsd.org . .Sh CAVEATS The .Nm driver currently does not support 802.11n transmit aggregation, either A-MSDU or A-MPDU. .Pp The .Nm driver does not capture management frames in non-monitor modes; without this limitation some firmware functions (e.g., 'join bss') will not work properly. diff --git a/share/man/man4/rtnetlink.4 b/share/man/man4/rtnetlink.4 index 720a9cc75ef2..83521b50c9b5 100644 --- a/share/man/man4/rtnetlink.4 +++ b/share/man/man4/rtnetlink.4 @@ -1,539 +1,539 @@ .\" .\" Copyright (C) 2022 Alexander Chernikov . .\" .\" 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 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_RAW 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 +To explicitly 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. +specifies 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 consists 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 */ + int ifi_index; /* Interface 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 . The following attributes are returned inside the nested .Dv NLMSGERR_ATTR_COOKIE : .Pp .Bd -literal -offset indent -compact IFLA_NEW_IFINDEX (uint32) created interface index IFLA_IFNAME (string) created interface name .Ed .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_IFALIAS (string) Interface description. .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 Fetches interface addresses in the current VNET matching conditions. Each address is reported as a .Dv RTM_NEWADDR message. The following filters are recognised by the kernel: .Pp .Bd -literal -offset indent -compact ifa_family required family or AF_UNSPEC ifa_index matching interface index or 0 .Ed .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. Set for IPv4 and p2p addresses. .It Dv IFA_LABEL (string) interface name. .It Dv IFA_BROADCAST -(binary) broacast interface address. +(binary) broadcast 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_STICKY permanent 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 13.2 . .Sh AUTHORS -The netlink was implementated by +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/sndstat.4 b/share/man/man4/sndstat.4 index ba130dacaecb..8325490da162 100644 --- a/share/man/man4/sndstat.4 +++ b/share/man/man4/sndstat.4 @@ -1,275 +1,275 @@ .\" .\" SPDX-License-Identifier: BSD-2-Clause .\" .\" This software was developed by Ka Ho Ng .\" under sponsorship from the FreeBSD Foundation. .\" .\" Copyright (c) 2020 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. .\" .\" Note: The date here should be updated whenever a non-trivial .\" change is made to the manual page. .Dd April 15, 2021 .Dt SNDSTAT 4 .Os .Sh NAME .Nm sndstat .Nd "nvlist-based PCM audio device enumeration interface" .Sh SYNOPSIS To compile the driver into the kernel, place the following lines in the kernel configuration file: .Bd -ragged -offset indent .Cd "device sound" .Ed .Sh DESCRIPTION The ioctl interface provided by .Pa /dev/sndstat device allows callers to enumerate PCM audio devices available for use. In other words, it provides means to get the list of all audio devices available to the system. .Sh IOCTLS For ioctl calls that take an argument, the following structure is used: .Bd -literal -offset indent struct sndstioc_nv_arg { size_t nbytes; void *buf; }; .Ed .Pp Here is an example of an nvlist object with explanations of the common fields: .Bd -literal -offset indent dsps (NVLIST ARRAY): 1 from_user (BOOL): FALSE nameunit (STRING): [pcm0] devnode (STRING): [dsp0] desc (STRING): [Generic (0x8086) (Analog Line-out)] pchan (NUMBER): 1 (1) (0x1) rchan (NUMBER): 0 (0) (0x0) info_play (NVLIST): min_rate (NUMBER): 48000 (48000) (0xbb80) max_rate (NUMBER): 48000 (48000) (0xbb80) formats (NUMBER): 16 (16) (0x10) min_chn (NUMBER): 2 (2) (0x2) max_chn (NUMBER): 2 (2) (0x2) provider_info (NVLIST): unit (NUMBER): 0 (0) (0x0) bitperfect (BOOL): FALSE pvchan (NUMBER): 1 (1) (0x1) rvchan (NUMBER): 0 (0) (0x0) provider (STRING): [sound(4)] , .Ed .Bl -tag -width ".Dv provider_info" .It Dv from_user Whether the PCM audio device node is created by in-kernel audio subsystem or userspace providers. .It Dv nameunit The device identification in the form of subsystem plus a unit number. .It Dv devnode The PCM audio device node relative path in devfs. .It Dv desc -The descripton of the PCM audio device. +The description of the PCM audio device. .It Dv pchan The number of playback channels supported by hardware. This can be 0 if this PCM audio device does not support playback at all. .It Dv rchan The number of recording channels supported by hardware. This can be 0 if this PCM audio device does not support recording at all. .It Dv info_play Supported configurations in playback direction. This exists only if this PCM audio device supports playback. There are a number of name/value pairs inside this field: .Bl -tag -width ".Dv min_rate" .It Dv min_rate Minimum supported sampling rate. .It Dv max_rate Maximum supported sampling rate. .It Dv formats Supported sample formats. .It Dv min_chn Minimum supported number of channels in channel layout .It Dv max_chn Maximum supported number of channels in channel layout .El .It Dv info_rec Supported configurations in recording direction. This exists only if this PCM audio device supports recording. There are a number of name/value pairs inside this field: .Bl -tag -width ".Dv min_rate" .It Dv min_rate Minimum supported sampling rate. .It Dv max_rate Maximum supported sampling rate. .It Dv formats Supported sample formats. .It Dv min_chn Minimum supported number of channels in channel layout .It Dv max_chn Maximum supported number of channels in channel layout .El .It Dv provider_info Provider-specific fields. This field may not exist if the PCM audio device is not provided by in-kernel interface. This field will not exist if the provider field is an empty string. .It Dv provider A string specifying the provider of the PCm audio device. .El .Pp The following ioctls are provided for use: .Bl -tag -width ".Dv SNDSTIOC_FLUSH_USER_DEVS" .It Dv SNDSTIOC_REFRESH_DEVS Drop any previously fetched PCM audio devices list snapshots. This ioctl takes no arguments. .It Dv SNDSTIOC_GET_DEVS Generate and/or return PCM audio devices list snapshots to callers. This ioctl takes a pointer to .Fa struct sndstioc_nv_arg as the first and the only argument. Callers need to provide a sufficiently large buffer to hold a serialized nvlist. If there is no existing PCM audio device list snapshot available in the internal structure of the opened sndstat. .Fa fd , a new PCM audio device list snapshot will be automatically generated. Callers have to set .Fa nbytes to either 0 or the size of buffer provided. In case .Fa nbytes is 0, the buffer size required to hold a serialized nvlist stream of current snapshot will be returned in .Fa nbytes , and .Fa buf will be ignored. Otherwise, if the buffer is not sufficiently large, the ioctl returns success, and .Fa nbytes will be set to 0. If the buffer provided is sufficiently large, .Fa nbytes will be set to the size of the serialized nvlist written to the provided buffer. Once a PCM audio device list snapshot is returned to user-space successfully, the snapshot stored in the subsystem's internal structure of the given .Fa fd will be freed. .It Dv SNDSTIOC_ADD_USER_DEVS Add a list of PCM audio devices provided by callers to .Pa /dev/sndstat device. This ioctl takes a pointer to .Fa struct sndstioc_nv_arg as the first and the only argument. Callers have to provide a buffer holding a serialized nvlist. .Fa nbytes should be set to the length in bytes of the serialized nvlist. .Fa buf should be pointed to a buffer storing the serialized nvlist. Userspace-backed PCM audio device nodes should be listed inside the serialized nvlist. .It Dv SNDSTIOC_FLUSH_USER_DEVS Flush any PCM audio devices previously added by callers. This ioctl takes no arguments. .El .Sh FILES .Bl -tag -width ".Pa /dev/sndstat" -compact .It Pa /dev/sndstat .El .Sh EXAMPLES The following code enumerates all available PCM audio devices: .Bd -literal -offset indent #include #include #include #include #include #include #include #include #include int main() { int fd; struct sndstioc_nv_arg arg; const nvlist_t * const *di; size_t i, nitems; nvlist_t *nvl; /* Open sndstat node in read-only first */ fd = open("/dev/sndstat", O_RDONLY); if (ioctl(fd, SNDSTIOC_REFRESH_DEVS, NULL)) err(1, "ioctl(fd, SNDSTIOC_REFRESH_DEVS, NULL)"); /* Get the size of snapshot, when nbytes = 0 */ arg.nbytes = 0; arg.buf = NULL; if (ioctl(fd, SNDSTIOC_GET_DEVS, &arg)) err(1, "ioctl(fd, SNDSTIOC_GET_DEVS, &arg)"); /* Get snapshot data */ arg.buf = malloc(arg.nbytes); if (arg.buf == NULL) err(EX_OSERR, "malloc"); if (ioctl(fd, SNDSTIOC_GET_DEVS, &arg)) err(1, "ioctl(fd, SNDSTIOC_GET_DEVS, &arg)"); /* Deserialize the nvlist stream */ nvl = nvlist_unpack(arg.buf, arg.nbytes, 0); free(arg.buf); /* Get DSPs array */ di = nvlist_get_nvlist_array(nvl, SNDST_DSPS, &nitems); for (i = 0; i < nitems; i++) { const char *nameunit, *devnode, *desc; /* * Examine each device nvlist item */ nameunit = nvlist_get_string(di[i], SNDST_DSPS_NAMEUNIT); devnode = nvlist_get_string(di[i], SNDST_DSPS_DEVNODE); desc = nvlist_get_string(di[i], SNDST_DSPS_DESC); printf("Name unit: `%s`, Device node: `%s`, Description: `%s`\n", nameunit, devnode, desc); } nvlist_destroy(nvl); return (0); } .Ed .Sh SEE ALSO .Xr sound 4 , .Xr nv 9 .Sh HISTORY The nvlist-based ioctls support for .Nm device first appeared in .Fx 13.0 . .Sh AUTHORS This manual page was written by .An Ka Ho Ng Aq Mt khng@FreeBSD.org . diff --git a/share/man/man4/tcp.4 b/share/man/man4/tcp.4 index 4ebdbac3a3ca..39db12752937 100644 --- a/share/man/man4/tcp.4 +++ b/share/man/man4/tcp.4 @@ -1,1091 +1,1091 @@ .\" Copyright (c) 1983, 1991, 1993 .\" The Regents of the University of California. .\" Copyright (c) 2010-2011 The FreeBSD Foundation .\" All rights reserved. .\" .\" Portions of this documentation were written at the Centre for Advanced .\" Internet Architectures, Swinburne University of Technology, Melbourne, .\" Australia by David Hayes 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. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 30, 2023 .Dt TCP 4 .Os .Sh NAME .Nm tcp .Nd Internet Transmission Control Protocol .Sh SYNOPSIS .In sys/types.h .In sys/socket.h .In netinet/in.h .In netinet/tcp.h .Ft int .Fn socket AF_INET SOCK_STREAM 0 .Sh DESCRIPTION The .Tn TCP protocol provides reliable, flow-controlled, two-way transmission of data. It is a byte-stream protocol used to support the .Dv SOCK_STREAM abstraction. .Tn TCP uses the standard Internet address format and, in addition, provides a per-host collection of .Dq "port addresses" . Thus, each address is composed of an Internet address specifying the host and network, with a specific .Tn TCP port on the host identifying the peer entity. .Pp Sockets utilizing the .Tn TCP protocol are either .Dq active or .Dq passive . Active sockets initiate connections to passive sockets. By default, .Tn TCP sockets are created active; to create a passive socket, the .Xr listen 2 system call must be used after binding the socket with the .Xr bind 2 system call. Only passive sockets may use the .Xr accept 2 call to accept incoming connections. Only active sockets may use the .Xr connect 2 call to initiate connections. .Pp Passive sockets may .Dq underspecify their location to match incoming connection requests from multiple networks. This technique, termed .Dq "wildcard addressing" , allows a single server to provide service to clients on multiple networks. To create a socket which listens on all networks, the Internet address .Dv INADDR_ANY must be bound. The .Tn TCP port may still be specified at this time; if the port is not specified, the system will assign one. Once a connection has been established, the socket's address is fixed by the peer entity's location. The address assigned to the socket is the address associated with the network interface through which packets are being transmitted and received. Normally, this address corresponds to the peer entity's network. .Pp .Tn TCP supports a number of socket options which can be set with .Xr setsockopt 2 and tested with .Xr getsockopt 2 : .Bl -tag -width ".Dv TCP_FUNCTION_BLK" .It Dv TCP_INFO Information about a socket's underlying TCP session may be retrieved by passing the read-only option .Dv TCP_INFO to .Xr getsockopt 2 . It accepts a single argument: a pointer to an instance of .Vt "struct tcp_info" . .Pp This API is subject to change; consult the source to determine which fields are currently filled out by this option. .Fx specific additions include send window size, receive window size, and bandwidth-controlled window space. .It Dv TCP_CCALGOOPT Set or query congestion control algorithm specific parameters. See .Xr mod_cc 4 for details. .It Dv TCP_CONGESTION Select or query the congestion control algorithm that TCP will use for the connection. See .Xr mod_cc 4 for details. .It Dv TCP_FASTOPEN Enable or disable TCP Fast Open (TFO). To use this option, the kernel must be built with the .Dv TCP_RFC7413 option. .Pp This option can be set on the socket either before or after the .Xr listen 2 is invoked. Clearing this option on a listen socket after it has been set has no effect on existing TFO connections or TFO connections in progress; it only prevents new TFO connections from being established. .Pp For passively-created sockets, the .Dv TCP_FASTOPEN socket option can be queried to determine whether the connection was established using TFO. Note that connections that are established via a TFO .Tn SYN , but that fall back to using a non-TFO .Tn SYN|ACK will have the .Dv TCP_FASTOPEN socket option set. .Pp In addition to the facilities defined in RFC7413, this implementation supports a pre-shared key (PSK) mode of operation in which the TFO server requires the -client to be in posession of a shared secret in order for the client to be able +client to be in possession of a shared secret in order for the client to be able to successfully open TFO connections with the server. This is useful, for example, in environments where TFO servers are exposed to both internal and external clients and only wish to allow TFO connections from internal clients. .Pp In the PSK mode of operation, the server generates and sends TFO cookies to requesting clients as usual. However, when validating cookies received in TFO SYNs from clients, the server requires the client-supplied cookie to equal .Bd -literal -offset left SipHash24(key=\fI16-byte-psk\fP, msg=\fIcookie-sent-to-client\fP) .Ed .Pp Multiple concurrent valid pre-shared keys are supported so that time-based rolling PSK invalidation policies can be implemented in the system. The default number of concurrent pre-shared keys is 2. .Pp This can be adjusted with the .Dv TCP_RFC7413_MAX_PSKS kernel option. .It Dv TCP_FUNCTION_BLK Select or query the set of functions that TCP will use for this connection. This allows a user to select an alternate TCP stack. The alternate TCP stack must already be loaded in the kernel. To list the available TCP stacks, see .Va functions_available in the .Sx MIB (sysctl) Variables section further down. To list the default TCP stack, see .Va functions_default in the .Sx MIB (sysctl) Variables section. .It Dv TCP_KEEPINIT This .Xr setsockopt 2 option accepts a per-socket timeout argument of .Vt "u_int" in seconds, for new, non-established .Tn TCP connections. For the global default in milliseconds see .Va keepinit in the .Sx MIB (sysctl) Variables section further down. .It Dv TCP_KEEPIDLE This .Xr setsockopt 2 option accepts an argument of .Vt "u_int" for the amount of time, in seconds, that the connection must be idle before keepalive probes (if enabled) are sent for the connection of this socket. If set on a listening socket, the value is inherited by the newly created socket upon .Xr accept 2 . For the global default in milliseconds see .Va keepidle in the .Sx MIB (sysctl) Variables section further down. .It Dv TCP_KEEPINTVL This .Xr setsockopt 2 option accepts an argument of .Vt "u_int" to set the per-socket interval, in seconds, between keepalive probes sent to a peer. If set on a listening socket, the value is inherited by the newly created socket upon .Xr accept 2 . For the global default in milliseconds see .Va keepintvl in the .Sx MIB (sysctl) Variables section further down. .It Dv TCP_KEEPCNT This .Xr setsockopt 2 option accepts an argument of .Vt "u_int" and allows a per-socket tuning of the number of probes sent, with no response, before the connection will be dropped. If set on a listening socket, the value is inherited by the newly created socket upon .Xr accept 2 . For the global default see the .Va keepcnt in the .Sx MIB (sysctl) Variables section further down. .It Dv TCP_NODELAY Under most circumstances, .Tn TCP sends data when it is presented; when outstanding data has not yet been acknowledged, it gathers small amounts of output to be sent in a single packet once an acknowledgement is received. For a small number of clients, such as window systems that send a stream of mouse events which receive no replies, 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 will negotiate among themselves to determine the maximum segment size to be used for each connection. 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 various .Tn TCP extensions which are provided in this implementation. The boolean option .Dv TCP_NOOPT is provided to disable .Tn TCP option use on a per-connection basis. .It Dv TCP_NOPUSH By convention, the .No sender- Ns Tn TCP will set the .Dq push bit, and begin transmission immediately (if permitted) at the end of every user call to .Xr write 2 or .Xr writev 2 . When this option is set to a non-zero value, .Tn TCP will delay sending any data at all until either the socket is closed, or the internal send buffer is filled. .It Dv TCP_MD5SIG This option enables the use of MD5 digests (also known as TCP-MD5) on writes to the specified socket. Outgoing traffic is digested; digests on incoming traffic are verified. When this option is enabled on a socket, all inbound and outgoing TCP segments must be signed with MD5 digests. .Pp One common use for this in a .Fx router deployment is to enable based routers to interwork with Cisco equipment at peering points. Support for this feature conforms to RFC 2385. .Pp In order for this option to function correctly, it is necessary for the administrator to add a tcp-md5 key entry to the system's security associations database (SADB) using the .Xr setkey 8 utility. This entry can only be specified on a per-host basis at this time. .Pp If an SADB entry cannot be found for the destination, the system does not send any outgoing segments and drops any inbound segments. However, during connection negotiation, a non-signed segment will be accepted if an SADB entry does not exist between hosts. When a non-signed segment is accepted, the established connection is not protected with MD5 digests. .It Dv TCP_STATS Manage collection of connection level statistics using the .Xr stats 3 framework. .Pp Each dropped segment is taken into account in the TCP protocol statistics. .It Dv TCP_TXTLS_ENABLE Enable in-kernel Transport Layer Security (TLS) for data written to this socket. See .Xr ktls 4 for more details. .It Dv TCP_TXTLS_MODE The integer argument can be used to get or set the current TLS transmit mode of a socket. See .Xr ktls 4 for more details. .It Dv TCP_RXTLS_ENABLE Enable in-kernel TLS for data read from this socket. See .Xr ktls 4 for more details. .It Dv TCP_REUSPORT_LB_NUMA Changes NUMA affinity filtering for an established TCP listen socket. This option takes a single integer argument which specifies the NUMA domain to filter on for this listen socket. -The argument can also have the follwing special values: +The argument can also have the following special values: .Bl -tag -width "Dv TCP_REUSPORT_LB_NUMA" .It Dv TCP_REUSPORT_LB_NUMA_NODOM Remove NUMA filtering for this listen socket. .It Dv TCP_REUSPORT_LB_NUMA_CURDOM Filter traffic associated with the domain where the calling thread is currently executing. This is typically used after a process or thread inherits a listen socket from its parent, and sets its CPU affinity to a particular core. .El .It Dv TCP_REMOTE_UDP_ENCAPS_PORT Set and get the remote UDP encapsulation port. It can only be set on a closed TCP socket. .El .Pp The option level for the .Xr setsockopt 2 call is the protocol number for .Tn TCP , available from .Xr getprotobyname 3 , or .Dv IPPROTO_TCP . All options are declared in .In netinet/tcp.h . .Pp Options at the .Tn IP transport level may be used with .Tn TCP ; see .Xr ip 4 . Incoming connection requests that are source-routed are noted, and the reverse source route is used in responding. .Pp The default congestion control algorithm for .Tn TCP is .Xr cc_newreno 4 . Other congestion control algorithms can be made available using the .Xr mod_cc 4 framework. .Ss MIB (sysctl) Variables The .Tn TCP protocol implements a number of variables in the .Va net.inet.tcp branch of the .Xr sysctl 3 MIB, which can also be read or modified with .Xr sysctl 8 . .Bl -tag -width ".Va v6pmtud_blackhole_mss" .It Va always_keepalive Assume that .Dv SO_KEEPALIVE is set on all .Tn TCP connections, the kernel will periodically send a packet to the remote host to verify the connection is still up. .It Va blackhole If enabled, disable sending of RST when a connection is attempted to a port where there is no socket accepting connections. See .Xr blackhole 4 . .It Va blackhole_local See .Xr blackhole 4 . .It Va cc A number of variables for congestion control are under the .Va net.inet.tcp.cc node. See .Xr mod_cc 4 . .It Va cc.newreno Variables for NewReno congestion control are under the .Va net.inet.tcp.cc.newreno node. See .Xr cc_newreno 4 . .It Va delacktime Maximum amount of time, in milliseconds, before a delayed ACK is sent. .It Va delayed_ack Delay ACK to try and piggyback it onto a data packet or another ACK. .It Va do_prr Perform SACK loss recovery using the Proportional Rate Reduction (PRR) algorithm described in RFC6937. This improves the effectiveness of retransmissions particular in environments with ACK thinning or burst loss events, as chances to run out of the ACK clock are reduced, preventing lengthy and performance reducing RTO based loss recovery (default is true). .It Va do_tcpdrain Flush packets in the .Tn TCP reassembly queue if the system is low on mbufs. .It Va drop_synfin Drop TCP packets with both SYN and FIN set. .It Va ecn.enable Enable support for TCP Explicit Congestion Notification (ECN). ECN allows a TCP sender to reduce the transmission rate in order to avoid packet drops. .Bl -tag -compact .It 0 Disable ECN. .It 1 Allow incoming connections to request ECN. Outgoing connections will request ECN. .It 2 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 specific connection. This is needed to help with connection establishment when a broken firewall is in the network path. .It Va fast_finwait2_recycle Recycle .Tn TCP .Dv FIN_WAIT_2 connections faster when the socket is marked as .Dv SBS_CANTRCVMORE (no user process has the socket open, data received on the socket cannot be read). The timeout used here is .Va finwait2_timeout . .It Va fastopen.acceptany When non-zero, all client-supplied TFO cookies will be considered to be valid. The default is 0. .It Va fastopen.autokey When this and .Va net.inet.tcp.fastopen.server_enable are non-zero, a new key will be automatically generated after this specified seconds. The default is 120. .It Va fastopen.ccache_bucket_limit The maximum number of entries in a client cookie cache bucket. The default value can be tuned with the .Dv TCP_FASTOPEN_CCACHE_BUCKET_LIMIT_DEFAULT kernel option or by setting .Va net.inet.tcp.fastopen_ccache_bucket_limit in the .Xr loader 8 . .It Va fastopen.ccache_buckets The number of client cookie cache buckets. Read-only. The value can be tuned with the .Dv TCP_FASTOPEN_CCACHE_BUCKETS_DEFAULT kernel option or by setting .Va fastopen.ccache_buckets in the .Xr loader 8 . .It Va fastopen.ccache_list Print the client cookie cache. Read-only. .It Va fastopen.client_enable When zero, no new active (i.e., client) TFO connections can be created. On the transition from enabled to disabled, the client cookie cache is cleared and disabled. The transition from enabled to disabled does not affect any active TFO connections in progress; it only prevents new ones from being established. The default is 0. .It Va fastopen.keylen The key length in bytes. Read-only. .It Va fastopen.maxkeys The maximum number of keys supported. Read-only, .It Va fastopen.maxpsks The maximum number of pre-shared keys supported. Read-only. .It Va fastopen.numkeys The current number of keys installed. Read-only. .It Va fastopen.numpsks The current number of pre-shared keys installed. Read-only. .It Va fastopen.path_disable_time When a failure occurs while trying to create a new active (i.e., client) TFO connection, new active connections on the same path, as determined by the tuple .Brq client_ip, server_ip, server_port , will be forced to be non-TFO for this many seconds. Note that the path disable mechanism relies on state stored in client cookie cache entries, so it is possible for the disable time for a given path to be reduced if the corresponding client cookie cache entry is reused due to resource pressure before the disable period has elapsed. The default is .Dv TCP_FASTOPEN_PATH_DISABLE_TIME_DEFAULT . .It Va fastopen.psk_enable When non-zero, pre-shared key (PSK) mode is enabled for all TFO servers. On the transition from enabled to disabled, all installed pre-shared keys are removed. The default is 0. .It Va fastopen.server_enable When zero, no new passive (i.e., server) TFO connections can be created. On the transition from enabled to disabled, all installed keys and pre-shared keys are removed. On the transition from disabled to enabled, if .Va fastopen.autokey is non-zero and there are no keys installed, a new key will be generated immediately. The transition from enabled to disabled does not affect any passive TFO connections in progress; it only prevents new ones from being established. The default is 0. .It Va fastopen.setkey Install a new key by writing .Va net.inet.tcp.fastopen.keylen bytes to this sysctl. .It Va fastopen.setpsk Install a new pre-shared key by writing .Va net.inet.tcp.fastopen.keylen bytes to this sysctl. .It Va finwait2_timeout Timeout to use for fast recycling of .Tn TCP .Dv FIN_WAIT_2 connections .Pq Va fast_finwait2_recycle . Defaults to 60 seconds. .It Va functions_available List of available TCP function blocks (TCP stacks). .It Va functions_default The default TCP function block (TCP stack). .It Va functions_inherit_listen_socket_stack Determines whether to inherit listen socket's TCP stack or use the current system default TCP stack, as defined by .Va functions_default . Default is true. .It Va hostcache The TCP host cache is used to cache connection details and metrics to improve future performance of connections between the same hosts. At the completion of a TCP connection, a host will cache information for the connection for some defined period of time. There are a number of .Va hostcache variables under this node. See .Va hostcache.enable . .It Va hostcache.bucketlimit The maximum number of entries for the same hash. Defaults to 30. .It Va hostcache.cachelimit Overall entry limit for hostcache. Defaults to .Va hashsize * .Va bucketlimit . .It Va hostcache.count The current number of entries in the host cache. .It Va hostcache.enable Enable/disable the host cache: .Bl -tag -compact .It 0 Disable the host cache. .It 1 Enable the host cache. (default) .El .It Va hostcache.expire Time in seconds, how long a entry should be kept in the host cache since last accessed. Defaults to 3600 (1 hour). .It Va hostcache.hashsize Size of TCP hostcache hashtable. This number has to be a power of two, or will be rejected. Defaults to 512. .It Va hostcache.histo Provide a Histogram of the hostcache hash utilization. .It Va hostcache.list Provide a complete list of all current entries in the host cache. .It Va hostcache.prune Time in seconds between pruning expired host cache entries. Defaults to 300 (5 minutes). .It Va hostcache.purge -Expire all entires on next pruning of host cache entries. +Expire all entries on next pruning of host cache entries. Any non-zero setting will be reset to zero, once the purge is running. .Bl -tag -compact .It 0 Do not purge all entries when pruning the host cache (default). .It 1 Purge all entries when doing the next pruning. .It 2 Purge all entries and also reseed the hash salt. .El .It Va hostcache.purgenow Immediately purge all entries once set to any value. Setting this to 2 will also reseed the hash salt. .It Va icmp_may_rst Certain .Tn ICMP unreachable messages may abort connections in .Tn SYN-SENT state. .It Va initcwnd_segments Enable the ability to specify initial congestion window in number of segments. The default value is 10 as suggested by RFC 6928. Changing the value on the fly would not affect connections using congestion window from the hostcache. Caution: This regulates the burst of packets allowed to be sent in the first RTT. The value should be relative to the link capacity. Start with small values for lower-capacity links. Large bursts can cause buffer overruns and packet drops if routers have small buffers or the link is experiencing congestion. .It Va insecure_rst Use criteria defined in RFC793 instead of RFC5961 for accepting RST segments. Default is false. .It Va insecure_syn Use criteria defined in RFC793 instead of RFC5961 for accepting SYN segments. Default is false. .It Va isn_reseed_interval The interval (in seconds) specifying how often the secret data used in RFC 1948 initial sequence number calculations should be reseeded. By default, this variable is set to zero, indicating that no reseeding will occur. Reseeding should not be necessary, and will break .Dv TIME_WAIT recycling for a few minutes. .It Va keepcnt Number of keepalive probes sent, with no response, before a connection is dropped. The default is 8 packets. .It Va keepidle Amount of time, in milliseconds, that the connection must be idle before sending keepalive probes (if enabled). The default is 7200000 msec (7.2M msec, 2 hours). .It Va keepinit Timeout, in milliseconds, for new, non-established .Tn TCP connections. The default is 75000 msec (75K msec, 75 sec). .It Va keepintvl The interval, in milliseconds, between keepalive probes sent to remote machines, when no response is received on a .Va keepidle probe. The default is 75000 msec (75K msec, 75 sec). .It Va log_in_vain Log any connection attempts to ports where there is no socket accepting connections. The value of 1 limits the logging to .Tn SYN (connection establishment) packets only. A value of 2 results in any .Tn TCP 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 minmss Minimum TCP Maximum Segment Size; used to prevent a denial of service attack from an unreasonably low MSS. .It Va msl The Maximum Segment Lifetime, in milliseconds, for a packet. .It Va mssdflt The default value used for the TCP Maximum Segment Size .Pq Dq MSS for IPv4 when no advice to the contrary is received from MSS negotiation. .It Va newcwd Enable the New Congestion Window Validation mechanism as described in RFC 7661. This gently reduces the congestion window during periods, where TCP is 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 TCP .Dv TIME_WAIT states for connections in which both endpoints are local. .It Va path_mtu_discovery Enable Path MTU Discovery. .It Va pcbcount Number of active protocol control blocks (read-only). .It Va perconn_stats_enable Controls the default collection of statistics for all connections using the .Xr stats 3 framework. 0 disables, 1 enables, 2 enables random sampling across log id connection groups with all connections in a group receiving the same setting. .It Va perconn_stats_sample_rates A CSV list of template_spec=percent key-value pairs which controls the per template sampling rates when .Xr stats 3 sampling is enabled. .It Va persmax Maximum persistence interval, msec. .It Va persmin Minimum persistence interval, msec. .It Va pmtud_blackhole_detection Enable automatic path MTU blackhole detection. In case of retransmits of MSS sized segments, the OS will lower the MSS to check if it's an MTU problem. If the current MSS is greater than the configured value to try .Po Va net.inet.tcp.pmtud_blackhole_mss and .Va net.inet.tcp.v6pmtud_blackhole_mss .Pc , it will be set to this value, otherwise, the MSS will be set to the default values .Po Va net.inet.tcp.mssdflt and .Va net.inet.tcp.v6mssdflt .Pc . Settings: .Bl -tag -compact .It 0 Disable path MTU blackhole detection. .It 1 Enable path MTU blackhole detection for IPv4 and IPv6. .It 2 Enable path MTU blackhole detection only for IPv4. .It 3 Enable path MTU blackhole detection only for IPv6. .El .It Va pmtud_blackhole_mss MSS to try for IPv4 if PMTU blackhole detection is turned on. .It Va reass.cursegments The current total number of segments present in all reassembly queues. .It Va reass.maxqueuelen The maximum number of segments allowed in each reassembly queue. By default, the system chooses a limit based on each TCP connection's receive buffer size and maximum segment size (MSS). The actual limit applied to a session's reassembly queue will be the lower of the system-calculated automatic limit and the user-specified .Va reass.maxqueuelen limit. .It Va reass.maxsegments The maximum limit on the total number of segments across all reassembly queues. The limit can be adjusted as a tunable. .It Va recvbuf_auto Enable automatic receive buffer sizing as a connection progresses. .It Va recvbuf_max Maximum size of automatic receive buffer. .It Va recvspace Initial .Tn TCP receive window (buffer size). .It Va retries Maximum number of consecutive timer based retransmits sent after a data segment is lost (default and maximum is 12). .It Va rexmit_drop_options Drop TCP options from third and later retransmitted SYN segments of a connection. .It Va rexmit_initial , rexmit_min , rexmit_slop Adjust the retransmit timer calculation for .Tn TCP . The slop is typically added to the raw calculation to take into account occasional variances that the .Tn SRTT (smoothed round-trip time) is unable to accommodate, while the minimum specifies an absolute minimum. While a number of .Tn TCP RFCs suggest a 1 second minimum, these RFCs tend to focus on streaming behavior, and fail to deal with the fact that a 1 second minimum has severe detrimental effects over lossy interactive connections, such as a 802.11b wireless link, and over very fast but lossy connections for those cases not covered by the fast retransmit code. For this reason, we use 200ms of slop and a near-0 minimum, which gives us an effective minimum of 200ms (similar to .Tn Linux ) . 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 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 is small, as happens on short transfers. .It Va rfc3390 Enable support for RFC 3390, which allows for a variable-sized starting congestion window on new connections, depending on the maximum segment size. This helps throughput in general, but particularly affects short transfers and high-bandwidth large propagation-delay connections. .It Va rfc6675_pipe Deprecated and superseded by .Va sack.revised .It Va sack.enable Enable support for RFC 2018, TCP Selective Acknowledgment option, which allows the receiver to inform the sender about all successfully arrived segments, allowing the sender to retransmit the missing segments only. .It Va sack.globalholes Global number of TCP SACK holes currently allocated. .It Va sack.globalmaxholes Maximum number of SACK holes per system, across all connections. Defaults to 65536. .It Va sack.lrd Enable Lost Retransmission Detection for SACK-enabled sessions, enabled by default. Under severe congestion, a retransmission can be lost which then leads to a mandatory Retransmission Timeout (RTO), followed by slow-start. LRD will try to resend the repeatedly lost packet, preventing the time-consuming RTO and performance reducing slow-start or purge of the SACK scoreboard. .It Va sack.maxholes Maximum number of SACK holes per connection. Defaults to 128. .It Va sack.revised Enables three updated mechanisms from RFC6675 (default is true). Calculate the bytes in flight using the algorithm described in RFC 6675, and is also an improvement when Proportional Rate Reduction is enabled. Next, Rescue Retransmission helps timely loss recovery, when the trailing segments of a transmission are lost, while no additional data is ready to be sent. In case a partial ACK without a SACK block is received during SACK loss recovery, the trailing segment is immediately resent, rather than waiting for a Retransmission timeout. Finally, SACK loss recovery is also engaged, once two segments plus one byte are SACKed - even if no traditional duplicate ACKs were observed. .It Va sendbuf_auto Enable automatic send buffer sizing. .It Va sendbuf_auto_lowat Modify threshold for auto send buffer growth to account for .Dv SO_SNDLOWAT . .It Va sendbuf_inc Incrementor step size of automatic send buffer. .It Va sendbuf_max Maximum size of automatic send buffer. .It Va sendspace Initial .Tn TCP send window (buffer size). .It Va syncache Variables under the .Va net.inet.tcp.syncache node are documented in .Xr syncache 4 . .It Va syncookies Determines whether or not .Tn SYN cookies should be generated for outbound .Tn SYN-ACK packets. .Tn SYN cookies are a great help during .Tn SYN flood attacks, and are enabled by default. (See .Xr syncookies 4 . ) .It Va syncookies_only See .Xr syncookies 4 . .It Va tcbhashsize Size of the .Tn TCP control-block hash table (read-only). This is tuned using the kernel option .Dv TCBHASHSIZE or by setting .Va net.inet.tcp.tcbhashsize in the .Xr loader 8 . .It Va tolerate_missing_ts Tolerate the missing of timestamps (RFC 1323/RFC 7323) for .Tn TCP segments belonging to .Tn TCP connections for which support of .Tn TCP timestamps has been negotiated. As of June 2021, several TCP stacks are known to violate RFC 7323, including modern widely deployed ones. Therefore the default is 1, i.e., the missing of timestamps is tolerated. .It Va ts_offset_per_conn When initializing the TCP timestamps, use a per connection offset instead of a per host pair offset. Default is to use per connection offsets as recommended in RFC 7323. .It Va tso Enable TCP Segmentation Offload. .It Va udp_tunneling_overhead The overhead taken into account when using UDP encapsulation. Since MSS clamping by middleboxes will most likely not work, values larger than 8 (the size of the UDP header) are also supported. Supported values are between 8 and 1024. The default is 8. .It Va udp_tunneling_port The local UDP encapsulation port. A value of 0 indicates that UDP encapsulation is disabled. The default is 0. .It Va v6mssdflt The default value used for the TCP Maximum Segment Size .Pq Dq MSS for IPv6 when no advice to the contrary is received from MSS negotiation. .It Va v6pmtud_blackhole_mss MSS to try for IPv6 if PMTU blackhole detection is turned on. See .Va pmtud_blackhole_detection . .El .Sh ERRORS A socket operation may fail with one of the following errors returned: .Bl -tag -width Er .It Bq Er EISCONN when trying to establish a connection on a socket which already has one; .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 ETIMEDOUT when a connection was dropped due to excessive retransmissions; .It Bq Er ECONNRESET when the remote peer forces the connection to be closed; .It Bq Er ECONNREFUSED when the remote peer actively refuses connection establishment (usually because no process is listening to the port); .It Bq Er EADDRINUSE when an attempt is made to create a socket with a port which has already been allocated; .It Bq Er EADDRNOTAVAIL when an attempt is made to create a socket with a network address for which no network interface exists; .It Bq Er EAFNOSUPPORT when an attempt is made to bind or connect a socket to a multicast address. .It Bq Er EINVAL when trying to change TCP function blocks at an invalid point in the session; .It Bq Er ENOENT when trying to use a TCP function block that is not available; .El .Sh SEE ALSO .Xr getsockopt 2 , .Xr socket 2 , .Xr stats 3 , .Xr sysctl 3 , .Xr blackhole 4 , .Xr inet 4 , .Xr intro 4 , .Xr ip 4 , .Xr ktls 4 , .Xr mod_cc 4 , .Xr siftr 4 , .Xr syncache 4 , .Xr tcp_bbr 4 , .Xr tcp_rack 4 , .Xr setkey 8 , .Xr sysctl 8 , .Xr tcp_functions 9 .Rs .%A "V. Jacobson" .%A "B. Braden" .%A "D. Borman" .%T "TCP Extensions for High Performance" .%O "RFC 1323" .Re .Rs .%A "D. Borman" .%A "B. Braden" .%A "V. Jacobson" .%A "R. Scheffenegger" .%T "TCP Extensions for High Performance" .%O "RFC 7323" .Re .Rs .%A "A. Heffernan" .%T "Protection of BGP Sessions via the TCP MD5 Signature Option" .%O "RFC 2385" .Re .Rs .%A "K. Ramakrishnan" .%A "S. Floyd" .%A "D. Black" .%T "The Addition of Explicit Congestion Notification (ECN) to IP" .%O "RFC 3168" .Re .Sh HISTORY The .Tn TCP protocol appeared in .Bx 4.2 . The RFC 1323 extensions for window scaling and timestamps were added in .Bx 4.4 . The .Dv TCP_INFO option was introduced in .Tn Linux 2.6 and is .Em subject to change . diff --git a/share/man/man4/watchdog.4 b/share/man/man4/watchdog.4 index f711d4d176d1..2cd66bb8ba85 100644 --- a/share/man/man4/watchdog.4 +++ b/share/man/man4/watchdog.4 @@ -1,204 +1,204 @@ .\" Copyright (c) 2004 Poul-Henning Kamp .\" Copyright (c) 2003, 2004 Sean M. Kelly .\" 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 REGENTS 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 REGENTS 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 January 2, 2018 .Dt WATCHDOG 4 .Os .Sh NAME .Nm watchdog .Nd "hardware and software watchdog" .Sh SYNOPSIS .In sys/watchdog.h .Sh DESCRIPTION The .Nm facility is used for controlling hardware and software watchdogs. .Pp The device .Pa /dev/fido supports several optional .Xr ioctl 2 calls for configuration, and responds to a single operational .Xr ioctl call, .Dv WDIOCPATPAT . It takes a single argument which represents a timeout value specified as a power of two nanoseconds, or-ed with a flag selecting active or passive control of the watchdog. .Pp .Dv WD_ACTIVE indicates that the .Nm will be kept from timing out from userland, for instance by the .Xr watchdogd 8 daemon. .Dv WD_PASSIVE indicates that the .Nm will be kept from timing out from the kernel. .Pp The .Dv WDIOCPATPAT .Xr ioctl 2 call will return success if just one of the available .Xr watchdog 9 implementations supports setting the timeout to the specified timeout. This means that at least one watchdog is armed. By default, this will be a hardware watchdog if one is present, but if no hardware watchdog is able to process the request, a default software watchdog is enabled. If the call fails, for instance if none of .Xr watchdog 9 implementations support the timeout length, all watchdogs are disabled and must be explicitly re-enabled. .Pp To disable the watchdogs pass .Dv WD_TO_NEVER . If disarming the watchdog(s) failed an error is returned. The watchdog might still be armed! .Pp The optional configuration .Xr ioctl commands are listed here, along with the type of the parameter used. Examples of their use can be found in .Xr watchdogd 8 . .Bl -tag -width "WDIOC_SETSOFTTIMEOUTACT int " .It Dv WDIOC_SETTIMEOUT Fa int set/reset the timer .It Dv WDIOC_GETTIMEOUT Fa int get total timeout .It Dv WDIOC_GETTIMELEFT Fa int get time left .It Dv WDIOC_GETPRETIMEOUT Fa int get the pre-timeout .It Dv WDIOC_SETPRETIMEOUT Fa int set the pre-timeout .It Dv WDIOC_SETPRETIMEOUTACT Fa int Set the action when a pre-timeout occurs (see .Li WD_SOFT_* below). .It Dv WDIOC_SETSOFT Fa int Use an internal software watchdog instead of hardware. There is also an external software watchdog, which is used by default if no hardware watchdog was attached. .It Dv WDIOC_SETSOFTTIMEOUTACT Fa int -Set the action whan a soft timeout occurs. +Set the action when a soft timeout occurs. .El .Pp The actions that may be specified for the pre-timeout or the internal software watchdog are listed here. Multiple actions can be specified by ORing values together. .Bl -tag -width WD_SOFT_PRINT .It Dv WD_SOFT_PANIC panic .It Dv WD_SOFT_DDB enter debugger .It Dv WD_SOFT_LOG log(9) .It Dv WD_SOFT_PRINT printf(9) .El .Sh RETURN VALUES The .Dv WDIOCPATPAT .Xr ioctl returns zero on success and non-zero on failure. .Bl -tag -width Er .It Bq Er EOPNOTSUPP No watchdog present in the kernel or none of the watchdogs supports the requested timeout value (timeout value other than 0). .It Bq Er EOPNOTSUPP Watchdog could not be disabled (timeout value of 0). .It Bq Er EINVAL Invalid flag combination passed. .El .Pp The configuration .Xr ioctl operations return zero on success and non-zero on failure. .Sh EXAMPLES .Bd -literal -offset indent #include #include #define WDPATH "/dev/" _PATH_WATCHDOG int wdfd = -1; static void wd_init(void) { wdfd = open(WDPATH, O_RDWR); if (wdfd == -1) err(1, WDPATH); } static void wd_reset(u_int timeout) { if (ioctl(wdfd, WDIOCPATPAT, &timeout) == -1) err(1, "WDIOCPATPAT"); } /* in main() */ wd_init(); wd_reset(WD_ACTIVE|WD_TO_8SEC); /* potential freeze point */ wd_reset(WD_TO_NEVER); .Ed .Pp Enables a watchdog to recover from a potentially freezing piece of code. .Pp .Dl "options SW_WATCHDOG" .Pp in your kernel config forces a software watchdog in the kernel to be configured even if a hardware watchdog is configured, dropping to KDB or panicking when firing, depending on the KDB and KDB_UNATTENDED kernel configuration options. .Sh SEE ALSO .Xr watchdogd 8 , .Xr watchdog 9 .Sh HISTORY The .Nm code first appeared in .Fx 5.1 . .Sh AUTHORS .An -nosplit The .Nm facility was written by .An Poul-Henning Kamp Aq Mt phk@FreeBSD.org . The software watchdog code and this manual page were written by .An Sean Kelly Aq Mt smkelly@FreeBSD.org . Some contributions were made by .An Jeff Roberson Aq Mt jeff@FreeBSD.org . .Sh BUGS The .Dv WD_PASSIVE option has not yet been implemented. diff --git a/share/man/man4/wg.4 b/share/man/man4/wg.4 index d0d871e52220..7682d4c37147 100644 --- a/share/man/man4/wg.4 +++ b/share/man/man4/wg.4 @@ -1,217 +1,217 @@ .\" SPDX-License-Identifier: BSD-2-Clause .\" .\" Copyright (c) 2020 Gordon Bergling .\" .\" 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 June 12, 2023 .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. +interface may be configured to recognize 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 , .An Kyle Evans Aq Mt kevans@FreeBSD.org , and .An Matt Macy Aq Mt mmacy@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/man5/elf.5 b/share/man/man5/elf.5 index 2aebd1b27702..7ad469a03c3b 100644 --- a/share/man/man5/elf.5 +++ b/share/man/man5/elf.5 @@ -1,1421 +1,1421 @@ .\" Copyright (c) 1999 Jeroen Ruigrok van der Werven .\" 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. .\" .Dd July 25, 2022 .Dt ELF 5 .Os .Sh NAME .Nm elf .Nd format of ELF executable binary files .Sh SYNOPSIS .In elf.h .Sh DESCRIPTION The header file .In elf.h defines the format of ELF executable binary files. Amongst these files are normal executable files, relocatable object files, core files and shared libraries. .Pp An executable file using the ELF file format consists of an ELF header, followed by a program header table or a section header table, or both. The ELF header is always at offset zero of the file. The program header table and the section header table's offset in the file are defined in the ELF header. The two tables describe the rest of the particularities of the file. .Pp Applications which wish to process ELF binary files for their native architecture only should include .In elf.h in their source code. These applications should need to refer to all the types and structures by their generic names .Dq Elf_xxx and to the macros by .Dq ELF_xxx . Applications written this way can be compiled on any architecture, regardless whether the host is 32-bit or 64-bit. .Pp Should an application need to process ELF files of an unknown architecture then the application needs to include both .In sys/elf32.h and .In sys/elf64.h instead of .In elf.h . Furthermore, all types and structures need to be identified by either .Dq Elf32_xxx or .Dq Elf64_xxx . The macros need to be identified by .Dq ELF32_xxx or .Dq ELF64_xxx . .Pp Whatever the system's architecture is, it will always include .In sys/elf_common.h as well as .In sys/elf_generic.h . .Pp These header files describe the above mentioned headers as C structures and also include structures for dynamic sections, relocation sections and symbol tables. .Pp The following types are being used for 32-bit architectures: .Bd -literal -offset indent Elf32_Addr Unsigned 32-bit program address Elf32_Half Unsigned 16-bit field Elf32_Lword Unsigned 64-bit field Elf32_Off Unsigned 32-bit file offset Elf32_Sword Signed 32-bit field or integer Elf32_Word Unsigned 32-bit field or integer .Ed .Pp For 64-bit architectures we have the following types: .Bd -literal -offset indent Elf64_Addr Unsigned 64-bit program address Elf64_Half Unsigned 16-bit field Elf64_Lword Unsigned 64-bit field Elf64_Off Unsigned 64-bit file offset Elf64_Sword Signed 32-bit field Elf64_Sxword Signed 64-bit field or integer Elf64_Word Unsigned 32-bit field Elf64_Xword Unsigned 64-bit field or integer .Ed .Pp All data structures that the file format defines follow the .Dq natural size and alignment guidelines for the relevant class. If necessary, data structures contain explicit padding to ensure 4-byte alignment for 4-byte objects, to force structure sizes to a multiple of 4, etc. .Pp The ELF header is described by the type Elf32_Ehdr or Elf64_Ehdr: .Bd -literal -offset indent typedef struct { unsigned char e_ident[EI_NIDENT]; Elf32_Half e_type; Elf32_Half e_machine; Elf32_Word e_version; Elf32_Addr e_entry; Elf32_Off e_phoff; Elf32_Off e_shoff; Elf32_Word e_flags; Elf32_Half e_ehsize; Elf32_Half e_phentsize; Elf32_Half e_phnum; Elf32_Half e_shentsize; Elf32_Half e_shnum; Elf32_Half e_shstrndx; } Elf32_Ehdr; .Ed .Bd -literal -offset indent typedef struct { unsigned char e_ident[EI_NIDENT]; Elf64_Half e_type; Elf64_Half e_machine; Elf64_Word e_version; Elf64_Addr e_entry; Elf64_Off e_phoff; Elf64_Off e_shoff; Elf64_Word e_flags; Elf64_Half e_ehsize; Elf64_Half e_phentsize; Elf64_Half e_phnum; Elf64_Half e_shentsize; Elf64_Half e_shnum; Elf64_Half e_shstrndx; } Elf64_Ehdr; .Ed .Pp The fields have the following meanings: .Pp .Bl -tag -width "e_phentsize" -compact -offset indent .It Dv e_ident This array of bytes specifies to interpret the file, independent of the processor or the file's remaining contents. Within this array everything is named by macros, which start with the prefix .Sy EI_ and may contain values which start with the prefix .Sy ELF . The following macros are defined: .Pp .Bl -tag -width "EI_ABIVERSION" -compact .It Dv EI_MAG0 The first byte of the magic number. It must be filled with .Sy ELFMAG0 . .It Dv EI_MAG1 The second byte of the magic number. It must be filled with .Sy ELFMAG1 . .It Dv EI_MAG2 The third byte of the magic number. It must be filled with .Sy ELFMAG2 . .It Dv EI_MAG3 The fourth byte of the magic number. It must be filled with .Sy ELFMAG3 . .It Dv EI_CLASS The fifth byte identifies the architecture for this binary: .Pp .Bl -tag -width "ELFCLASSNONE" -compact .It Dv ELFCLASSNONE This class is invalid. .It Dv ELFCLASS32 This defines the 32-bit architecture. It supports machines with files and virtual address spaces up to 4 Gigabytes. .It Dv ELFCLASS64 This defines the 64-bit architecture. .El .It Dv EI_DATA The sixth byte specifies the data encoding of the processor-specific data in the file. Currently these encodings are supported: .Pp .Bl -tag -width "ELFDATA2LSB" -compact .It Dv ELFDATANONE Unknown data format. .It Dv ELFDATA2LSB Two's complement, little-endian. .It Dv ELFDATA2MSB Two's complement, big-endian. .El .It Dv EI_VERSION The version number of the ELF specification: .Pp .Bl -tag -width "EV_CURRENT" -compact .It Dv EV_NONE Invalid version. .It Dv EV_CURRENT Current version. .El .It Dv EI_OSABI This byte identifies the operating system and ABI to which the object is targeted. Some fields in other ELF structures have flags and values that have platform specific meanings; the interpretation of those fields is determined by the value of this byte. The following values are currently defined: .Pp .Bl -tag -width "ELFOSABI_STANDALONE" -compact .It Dv ELFOSABI_SYSV UNIX System V ABI. .It Dv ELFOSABI_HPUX HP-UX operating system ABI. .It Dv ELFOSABI_NETBSD .Nx operating system ABI. .It Dv ELFOSABI_LINUX GNU/Linux operating system ABI. .It Dv ELFOSABI_HURD GNU/Hurd operating system ABI. .It Dv ELFOSABI_86OPEN 86Open Common IA32 ABI. .It Dv ELFOSABI_SOLARIS Solaris operating system ABI. .It Dv ELFOSABI_MONTEREY Monterey project ABI. .It Dv ELFOSABI_IRIX IRIX operating system ABI. .It Dv ELFOSABI_FREEBSD .Fx operating system ABI. .It Dv ELFOSABI_TRU64 TRU64 UNIX operating system ABI. .It Dv ELFOSABI_ARM ARM architecture ABI. .It Dv ELFOSABI_STANDALONE Standalone (embedded) ABI. .El .It Dv EI_ABIVERSION This byte identifies the version of the ABI to which the object is targeted. This field is used to distinguish among incompatible versions of an ABI. The interpretation of this version number is dependent on the ABI identified by the EI_OSABI field. Applications conforming to this specification use the value 0. .It Dv EI_PAD Start of padding. These bytes are reserved and set to zero. Programs which read them should ignore them. The value for EI_PAD will change in the future if currently unused bytes are given meanings. .It Dv EI_BRAND Start of architecture identification. .It Dv EI_NIDENT The size of the e_ident array. .El .Pp .It Dv e_type This member of the structure identifies the object file type: .Pp .Bl -tag -width "ET_NONE" -compact .It Dv ET_NONE An unknown type. .It Dv ET_REL A relocatable file. .It Dv ET_EXEC An executable file. .It Dv ET_DYN A shared object. .It Dv ET_CORE A core file. .El .Pp .It Dv e_machine This member specifies the required architecture for an individual file: .Pp .Bl -tag -width "EM_MIPS_RS4_BE" -compact .It Dv EM_NONE An unknown machine. .It Dv EM_M32 AT&T WE 32100. .It Dv EM_SPARC Sun Microsystems SPARC. .It Dv EM_386 Intel 80386. .It Dv EM_68K Motorola 68000. .It Dv EM_88K Motorola 88000. .It Dv EM_486 Intel 80486. .It Dv EM_860 Intel 80860. .It Dv EM_MIPS MIPS RS3000 (big-endian only). .It Dv EM_MIPS_RS4_BE MIPS RS4000 (big-endian only). .It Dv EM_SPARC64 SPARC v9 64-bit unofficial. .It Dv EM_PARISC HPPA. .It Dv EM_PPC PowerPC. .It Dv EM_ALPHA Compaq [DEC] Alpha. .El .Pp .It Dv e_version This member identifies the file version: .Pp .Bl -tag -width "EV_CURRENT" -compact .It Dv EV_NONE Invalid version .It Dv EV_CURRENT Current version .El .It Dv e_entry This member gives the virtual address to which the system first transfers control, thus starting the process. If the file has no associated entry point, this member holds zero. .It Dv e_phoff This member holds the program header table's file offset in bytes. If the file has no program header table, this member holds zero. .It Dv e_shoff This member holds the section header table's file offset in bytes. If the file has no section header table this member holds zero. .It Dv e_flags This member holds processor-specific flags associated with the file. Flag names take the form EF_`machine_flag'. Currently no flags have been defined. .It Dv e_ehsize This member holds the ELF header's size in bytes. .It Dv e_phentsize This member holds the size in bytes of one entry in the file's program header table; all entries are the same size. .It Dv e_phnum This member holds the number of entries in the program header table. If the file is using extended program header numbering, then the .Sy e_phnum member will contain the value .Dv PN_XNUM and the actual number of program header table entries will be stored in the .Sy sh_info member of the section header at index .Dv SHN_UNDEF . The product of .Sy e_phentsize and the number of program header table entries gives the program header table's size in bytes. If a file has no program header, .Sy e_phnum holds the value zero. .It Dv e_shentsize This member holds a sections header's size in bytes. A section header is one entry in the section header table; all entries are the same size. .It Dv e_shnum This member holds the number of entries in the section header table. If the file is using extended section numbering, then the .Sy e_shnum member will be zero and the actual section number will be stored in the .Sy sh_size member of the section header at index .Dv SHN_UNDEF . If a file has no section header table, both the .Sy e_shnum and the .Sy e_shoff fields of the ELF header will be zero. The product of .Sy e_shentsize and the number of sections in the file gives the section header table's size in bytes. .It Dv e_shstrndx This member holds the section header table index of the entry associated with the section name string table. If extended section numbering is being used, this field will hold the value .Sy SHN_XINDEX , and the actual section header table index will be present in the .Sy sh_link field of the section header entry at index .Dv SHN_UNDEF . If the file has no section name string table, this member holds the value .Sy SHN_UNDEF . .El .Pp An executable or shared object file's program header table is an array of structures, each describing a segment or other information the system needs to prepare the program for execution. An object file .Em segment contains one or more .Em sections . Program headers are meaningful only for executable and shared object files. A file specifies its own program header size with the ELF header's .Sy e_phentsize and .Sy e_phnum members. As with the Elf executable header, the program header also has different versions depending on the architecture: .Bd -literal -offset indent typedef struct { Elf32_Word p_type; Elf32_Off p_offset; Elf32_Addr p_vaddr; Elf32_Addr p_paddr; Elf32_Word p_filesz; Elf32_Word p_memsz; Elf32_Word p_flags; Elf32_Word p_align; } Elf32_Phdr; .Ed .Bd -literal -offset indent typedef struct { Elf64_Word p_type; Elf64_Word p_flags; Elf64_Off p_offset; Elf64_Addr p_vaddr; Elf64_Addr p_paddr; Elf64_Xword p_filesz; Elf64_Xword p_memsz; Elf64_Xword p_align; } Elf64_Phdr; .Ed .Pp The main difference between the 32-bit and the 64-bit program header lies only in the location of a .Sy p_flags member in the total struct. .Pp .Bl -tag -width "p_offset" -compact -offset indent .It Dv p_type This member of the Phdr struct tells what kind of segment this array element describes or how to interpret the array element's information. .Pp .Bl -tag -width "PT_DYNAMIC" -compact .It Dv PT_NULL The array element is unused and the other members' values are undefined. This lets the program header have ignored entries. .It Dv PT_LOAD The array element specifies a loadable segment, described by .Sy p_filesz and .Sy p_memsz . The bytes from the file are mapped to the beginning of the memory segment. If the segment's memory size .Pq Sy p_memsz is larger than the file size .Pq Sy p_filesz , the .Dq extra bytes are defined to hold the value 0 and to follow the segment's initialized area. The file size may not be larger than the memory size. Loadable segment entries in the program header table appear in ascending order, sorted on the .Sy p_vaddr member. .It Dv PT_DYNAMIC The array element specifies dynamic linking information. .It Dv PT_INTERP The array element specifies the location and size of a null-terminated path name to invoke as an interpreter. This segment type is meaningful only for executable files (though it may occur for shared objects). However it may not occur more than once in a file. If it is present it must precede any loadable segment entry. .It Dv PT_NOTE The array element specifies the location and size for auxiliary information. .It Dv PT_SHLIB This segment type is reserved but has unspecified semantics. Programs that contain an array element of this type do not conform to the ABI. .It Dv PT_PHDR The array element, if present, specifies the location and size of the program header table itself, both in the file and in the memory image of the program. This segment type may not occur more than once in a file. Moreover, it may only occur if the program header table is part of the memory image of the program. If it is present it must precede any loadable segment entry. .It Dv PT_LOPROC This value up to and including .Sy PT_HIPROC are reserved for processor-specific semantics. .It Dv PT_HIPROC This value down to and including .Sy PT_LOPROC are reserved for processor-specific semantics. .El .Pp .It Dv p_offset This member holds the offset from the beginning of the file at which the first byte of the segment resides. .It Dv p_vaddr This member holds the virtual address at which the first byte of the segment resides in memory. .It Dv p_paddr On systems for which physical addressing is relevant, this member is reserved for the segment's physical address. Under .Bx this member is not used and must be zero. .It Dv p_filesz This member holds the number of bytes in the file image of the segment. It may be zero. .It Dv p_memsz This member holds the number of bytes in the memory image of the segment. It may be zero. .It Dv p_flags This member holds flags relevant to the segment: .Pp .Bl -tag -width "PF_X" -compact .It Dv PF_X An executable segment. .It Dv PF_W A writable segment. .It Dv PF_R A readable segment. .El .Pp A text segment commonly has the flags .Sy PF_X and .Sy PF_R . A data segment commonly has .Sy PF_X , .Sy PF_W and .Sy PF_R . .It Dv p_align This member holds the value to which the segments are aligned in memory and in the file. Loadable process segments must have congruent values for .Sy p_vaddr and .Sy p_offset , modulo the page size. Values of zero and one mean no alignment is required. Otherwise, .Sy p_align should be a positive, integral power of two, and .Sy p_vaddr should equal .Sy p_offset , modulo .Sy p_align . .El .Pp An file's section header table lets one locate all the file's sections. The section header table is an array of Elf32_Shdr or Elf64_Shdr structures. The ELF header's .Sy e_shoff member gives the byte offset from the beginning of the file to the section header table. .Sy e_shnum holds the number of entries the section header table contains. .Sy e_shentsize holds the size in bytes of each entry. .Pp A section header table index is a subscript into this array. Some section header table indices are reserved. An object file does not have sections for these special indices: .Pp .Bl -tag -width "SHN_LORESERVE" -compact .It Dv SHN_UNDEF This value marks an undefined, missing, irrelevant, or otherwise meaningless section reference. For example, a symbol .Dq defined relative to section number .Sy SHN_UNDEF is an undefined symbol. .It Dv SHN_LORESERVE This value specifies the lower bound of the range of reserved indices. .It Dv SHN_LOPROC This value up to and including .Sy SHN_HIPROC are reserved for processor-specific semantics. .It Dv SHN_HIPROC This value down to and including .Sy SHN_LOPROC are reserved for processor-specific semantics. .It Dv SHN_ABS This value specifies absolute values for the corresponding reference. For example, symbols defined relative to section number .Sy SHN_ABS have absolute values and are not affected by relocation. .It Dv SHN_COMMON Symbols defined relative to this section are common symbols, such as FORTRAN COMMON or unallocated C external variables. .It Dv SHN_HIRESERVE This value specifies the upper bound of the range of reserved indices. The system reserves indices between .Sy SHN_LORESERVE and .Sy SHN_HIRESERVE , inclusive. The section header table does not contain entries for the reserved indices. .El .Pp The section header has the following structure: .Bd -literal -offset indent typedef struct { Elf32_Word sh_name; Elf32_Word sh_type; Elf32_Word sh_flags; Elf32_Addr sh_addr; Elf32_Off sh_offset; Elf32_Word sh_size; Elf32_Word sh_link; Elf32_Word sh_info; Elf32_Word sh_addralign; Elf32_Word sh_entsize; } Elf32_Shdr; .Ed .Bd -literal -offset indent typedef struct { Elf64_Word sh_name; Elf64_Word sh_type; Elf64_Xword sh_flags; Elf64_Addr sh_addr; Elf64_Off sh_offset; Elf64_Xword sh_size; Elf64_Word sh_link; Elf64_Word sh_info; Elf64_Xword sh_addralign; Elf64_Xword sh_entsize; } Elf64_Shdr; .Ed .Pp .Bl -tag -width "sh_addralign" -compact .It Dv sh_name This member specifies the name of the section. Its value is an index into the section header string table section, giving the location of a null-terminated string. .It Dv sh_type This member categorizes the section's contents and semantics. .Pp .Bl -tag -width "SHT_PROGBITS" -compact .It Dv SHT_NULL This value marks the section header as inactive. It does not have an associated section. Other members of the section header have undefined values. .It Dv SHT_PROGBITS The section holds information defined by the program, whose format and meaning are determined solely by the program. .It Dv SHT_SYMTAB This section holds a symbol table. Typically, .Sy SHT_SYMTAB provides symbols for link editing, though it may also be used for dynamic linking. As a complete symbol table, it may contain many symbols unnecessary for dynamic linking. An object file can also contain a .Sy SHN_DYNSYM section. .It Dv SHT_STRTAB This section holds a string table. An object file may have multiple string table sections. .It Dv SHT_RELA This section holds relocation entries with explicit addends, such as type .Sy Elf32_Rela for the 32-bit class of object files. An object may have multiple relocation sections. .It Dv SHT_HASH This section holds a symbol hash table. All object participating in dynamic linking must contain a symbol hash table. An object file may have only one hash table. .It Dv SHT_DYNAMIC This section holds information for dynamic linking. An object file may have only one dynamic section. .It Dv SHT_NOTE This section holds information that marks the file in some way. .It Dv SHT_NOBITS A section of this type occupies no space in the file but otherwise resembles .Sy SHN_PROGBITS . Although this section contains no bytes, the .Sy sh_offset member contains the conceptual file offset. .It Dv SHT_REL This section holds relocation offsets without explicit addends, such as type .Sy Elf32_Rel for the 32-bit class of object files. An object file may have multiple relocation sections. .It Dv SHT_SHLIB This section is reserved but has unspecified semantics. .It Dv SHT_DYNSYM This section holds a minimal set of dynamic linking symbols. An object file can also contain a .Sy SHN_SYMTAB section. .It Dv SHT_LOPROC This value up to and including .Sy SHT_HIPROC are reserved for processor-specific semantics. .It Dv SHT_HIPROC This value down to and including .Sy SHT_LOPROC are reserved for processor-specific semantics. .It Dv SHT_LOUSER This value specifies the lower bound of the range of indices reserved for application programs. .It Dv SHT_HIUSER This value specifies the upper bound of the range of indices reserved for application programs. Section types between .Sy SHT_LOUSER and .Sy SHT_HIUSER may be used by the application, without conflicting with current or future system-defined section types. .El .Pp .It Dv sh_flags Sections support one-bit flags that describe miscellaneous attributes. If a flag bit is set in .Sy sh_flags , the attribute is .Dq on for the section. Otherwise, the attribute is .Dq off or does not apply. Undefined attributes are set to zero. .Pp .Bl -tag -width "SHF_EXECINSTR" -compact .It Dv SHF_WRITE This section contains data that should be writable during process execution. .It Dv SHF_ALLOC The section occupies memory during process execution. Some control sections do not reside in the memory image of an object file. This attribute is off for those sections. .It Dv SHF_EXECINSTR The section contains executable machine instructions. .It Dv SHF_MASKPROC All bits included in this mask are reserved for processor-specific semantics. .It Dv SHF_COMPRESSED The section data is compressed. .El .Pp .It Dv sh_addr If the section will appear in the memory image of a process, this member holds the address at which the section's first byte should reside. Otherwise, the member contains zero. .It Dv sh_offset This member's value holds the byte offset from the beginning of the file to the first byte in the section. One section type, .Sy SHT_NOBITS , occupies no space in the file, and its .Sy sh_offset member locates the conceptual placement in the file. .It Dv sh_size This member holds the section's size in bytes. Unless the section type is .Sy SHT_NOBITS , the section occupies .Sy sh_size bytes in the file. A section of type .Sy SHT_NOBITS may have a non-zero size, but it occupies no space in the file. .It Dv sh_link This member holds a section header table index link, whose interpretation depends on the section type. .It Dv sh_info This member holds extra information, whose interpretation depends on the section type. .It Dv sh_addralign Some sections have address alignment constraints. If a section holds a doubleword, the system must ensure doubleword alignment for the entire section. That is, the value of .Sy sh_addr must be congruent to zero, modulo the value of .Sy sh_addralign . Only zero and positive integral powers of two are allowed. Values of zero or one mean the section has no alignment constraints. .It Dv sh_entsize Some sections hold a table of fixed-sized entries, such as a symbol table. For such a section, this member gives the size in bytes for each entry. This member contains zero if the section does not hold a table of fixed-size entries. .El .Pp Various sections hold program and control information: .Bl -tag -width ".shstrtab" -compact .It .bss (Block Started by Symbol) This section holds uninitialized data that contributes to the program's memory image. By definition, the system initializes the data with zeros when the program begins to run. This section is of type .Sy SHT_NOBITS . The attributes types are .Sy SHF_ALLOC and .Sy SHF_WRITE . .It .comment This section holds version control information. This section is of type .Sy SHT_PROGBITS . No attribute types are used. .It .data This section holds initialized data that contribute to the program's memory image. This section is of type .Sy SHT_PROGBITS . The attribute types are .Sy SHF_ALLOC and .Sy SHF_WRITE . .It .data1 This section holds initialized data that contribute to the program's memory image. This section is of type .Sy SHT_PROGBITS . The attribute types are .Sy SHF_ALLOC and .Sy SHF_WRITE . .It .debug This section holds information for symbolic debugging. The contents are unspecified. This section is of type .Sy SHT_PROGBITS . No attribute types are used. .It .dynamic This section holds dynamic linking information. The section's attributes will include the .Sy SHF_ALLOC bit. Whether the .Sy SHF_WRITE bit is set is processor-specific. This section is of type .Sy SHT_DYNAMIC . See the attributes above. .It .dynstr This section holds strings needed for dynamic linking, most commonly the strings that represent the names associated with symbol table entries. This section is of type .Sy SHT_STRTAB . The attribute type used is .Sy SHF_ALLOC . .It .dynsym This section holds the dynamic linking symbol table. This section is of type .Sy SHT_DYNSYM . The attribute used is .Sy SHF_ALLOC . .It .fini This section holds executable instructions that contribute to the process termination code. When a program exits normally the system arranges to execute the code in this section. This section is of type .Sy SHT_PROGBITS . The attributes used are .Sy SHF_ALLOC and .Sy SHF_EXECINSTR . .It .got This section holds the global offset table. This section is of type .Sy SHT_PROGBITS . The attributes are processor-specific. .It .hash This section holds a symbol hash table. This section is of type .Sy SHT_HASH . The attribute used is .Sy SHF_ALLOC . .It .init This section holds executable instructions that contribute to the process initialization code. When a program starts to run the system arranges to execute the code in this section before calling the main program entry point. This section is of type .Sy SHT_PROGBITS . The attributes used are .Sy SHF_ALLOC and .Sy SHF_EXECINSTR . .It .interp This section holds the pathname of a program interpreter. If the file has a loadable segment that includes the section, the section's attributes will include the .Sy SHF_ALLOC bit. Otherwise, that bit will be off. This section is of type .Sy SHT_PROGBITS . .It .line This section holds line number information for symbolic debugging, which describes the correspondence between the program source and the machine code. The contents are unspecified. This section is of type .Sy SHT_PROGBITS . No attribute types are used. .It .note This section holds information in the .Dq Note Section format described below. This section is of type .Sy SHT_NOTE . No attribute types are used. .It .plt This section holds the procedure linkage table. This section is of type .Sy SHT_PROGBITS . The attributes are processor-specific. .It .relNAME This section holds relocation information as described below. If the file has a loadable segment that includes relocation, the section's attributes will include the .Sy SHF_ALLOC bit. Otherwise the bit will be off. By convention, .Dq NAME is supplied by the section to which the relocations apply. Thus a relocation section for .Sy .text normally would have the name .Sy .rel.text . This section is of type .Sy SHT_REL . .It .relaNAME This section holds relocation information as described below. If the file has a loadable segment that includes relocation, the section's attributes will include the .Sy SHF_ALLOC bit. Otherwise the bit will be off. By convention, .Dq NAME is supplied by the section to which the relocations apply. Thus a relocation section for .Sy .text normally would have the name .Sy .rela.text . This section is of type .Sy SHT_RELA . .It .rodata This section holds read-only data that typically contributes to a non-writable segment in the process image. This section is of type .Sy SHT_PROGBITS . The attribute used is .Sy SHF_ALLOC . .It .rodata1 This section holds read-only data that typically contributes to a non-writable segment in the process image. This section is of type .Sy SHT_PROGBITS . The attribute used is .Sy SHF_ALLOC . .It .shstrtab This section holds section names. This section is of type .Sy SHT_STRTAB . No attribute types are used. .It .strtab This section holds strings, most commonly the strings that represent the names associated with symbol table entries. If the file has a loadable segment that includes the symbol string table, the section's attributes will include the .Sy SHF_ALLOC bit. Otherwise the bit will be off. This section is of type .Sy SHT_STRTAB . .It .symtab This section holds a symbol table. If the file has a loadable segment that includes the symbol table, the section's attributes will include the .Sy SHF_ALLOC bit. Otherwise the bit will be off. This section is of type .Sy SHT_SYMTAB . .It .text This section holds the .Dq text , or executable instructions, of a program. This section is of type .Sy SHT_PROGBITS . The attributes used are .Sy SHF_ALLOC and .Sy SHF_EXECINSTR . .It .jcr This section holds information about Java classes that must be registered. .It .eh_frame This section holds information used for C++ exception-handling. .El .Pp A section with the .Dv SHF_COMPRESSED flag set contains a compressed copy of the section data. Compressed section data begins with an .Vt Elf64_Chdr or .Vt Elf32_Chdr structure which encodes the compression algorithm and some characteristics of the uncompressed data. .Bd -literal -offset indent typedef struct { Elf32_Word ch_type; Elf32_Word ch_size; Elf32_Word ch_addralign; } Elf32_Chdr; .Ed .Bd -literal -offset indent typedef struct { Elf64_Word ch_type; Elf64_Word ch_reserved; Elf64_Xword ch_size; Elf64_Xword ch_addralign; } Elf64_Chdr; .Ed .Pp .Bl -tag -width "ch_addralign" -compact .It Dv ch_type The compression algorithm used. A value of .Dv ELFCOMPRESS_ZLIB indicates that the data is compressed using .Xr zlib 3 . A value of .Dv ELFCOMPRESS_ZSTD indicates that the data is compressed using Zstandard. .It Dv ch_size The size, in bytes, of the uncompressed section data. This corresponds to the .Sy sh_size field of a section header containing uncompressed data. .It Dv ch_addralign The address alignment of the uncompressed section data. This corresponds to the .Sy sh_addralign field of a section header containing uncompressed data. .El .Pp String table sections hold null-terminated character sequences, commonly called strings. The object file uses these strings to represent symbol and section names. One references a string as an index into the string table section. The first byte, which is index zero, is defined to hold a null character. Similarly, a string table's last byte is defined to hold a null character, ensuring null termination for all strings. .Pp An object file's symbol table holds information needed to locate and relocate a program's symbolic definitions and references. A symbol table index is a subscript into this array. .Bd -literal -offset indent typedef struct { Elf32_Word st_name; Elf32_Addr st_value; Elf32_Word st_size; unsigned char st_info; unsigned char st_other; Elf32_Half st_shndx; } Elf32_Sym; .Ed .Bd -literal -offset indent typedef struct { Elf64_Word st_name; unsigned char st_info; unsigned char st_other; Elf64_Half st_shndx; Elf64_Addr st_value; Elf64_Xword st_size; } Elf64_Sym; .Ed .Pp .Bl -tag -width "st_value" -compact .It Dv st_name This member holds an index into the object file's symbol string table, which holds character representations of the symbol names. If the value is non-zero, it represents a string table index that gives the symbol name. Otherwise, the symbol table has no name. .It Dv st_value This member gives the value of the associated symbol. .It Dv st_size Many symbols have associated sizes. This member holds zero if the symbol has no size or an unknown size. .It Dv st_info This member specifies the symbol's type and binding attributes: .Pp .Bl -tag -width "STT_SECTION" -compact .It Dv STT_NOTYPE The symbol's type is not defined. .It Dv STT_OBJECT The symbol is associated with a data object. .It Dv STT_FUNC The symbol is associated with a function or other executable code. .It Dv STT_SECTION The symbol is associated with a section. Symbol table entries of this type exist primarily for relocation and normally have .Sy STB_LOCAL bindings. .It Dv STT_FILE By convention the symbol's name gives the name of the source file associated with the object file. A file symbol has .Sy STB_LOCAL bindings, its section index is .Sy SHN_ABS , and it precedes the other .Sy STB_LOCAL symbols of the file, if it is present. .It Dv STT_LOPROC This value up to and including .Sy STT_HIPROC are reserved for processor-specific semantics. .It Dv STT_HIPROC This value down to and including .Sy STT_LOPROC are reserved for processor-specific semantics. .El .Pp .Bl -tag -width "STB_GLOBAL" -compact .It Dv STB_LOCAL Local symbols are not visible outside the object file containing their definition. Local symbols of the same name may exist in multiple file without interfering with each other. .It Dv STB_GLOBAL Global symbols are visible to all object files being combined. One file's definition of a global symbol will satisfy another file's undefined reference to the same symbol. .It Dv STB_WEAK Weak symbols resemble global symbols, but their definitions have lower precedence. .It Dv STB_LOPROC This value up to and including .Sy STB_HIPROC are reserved for processor-specific semantics. .It Dv STB_HIPROC This value down to and including .Sy STB_LOPROC are reserved for processor-specific semantics. .Pp There are macros for packing and unpacking the binding and type fields: .Pp .Bl -tag -width "ELF32_ST_INFO(bind, type)" -compact .It Xo .Fn ELF32_ST_BIND info .Xc or .Fn ELF64_ST_BIND info extract a binding from an st_info value. .It Xo .Fn ELF64_ST_TYPE info .Xc or .Fn ELF32_ST_TYPE info extract a type from an st_info value. .It Xo .Fn ELF32_ST_INFO bind type .Xc or .Fn ELF64_ST_INFO bind type convert a binding and a type into an st_info value. .El .El .Pp .It Dv st_other This member currently holds zero and has no defined meaning. .It Dv st_shndx Every symbol table entry is .Dq defined in relation to some section. This member holds the relevant section header table index. .El .Pp Relocation is the process of connecting symbolic references with symbolic definitions. Relocatable files must have information that describes how to modify their section contents, thus allowing executable and shared object files to hold the right information for a process' program image. Relocation entries are these data. .Pp Relocation structures that do not need an addend: .Bd -literal -offset indent typedef struct { Elf32_Addr r_offset; Elf32_Word r_info; } Elf32_Rel; .Ed .Bd -literal -offset indent typedef struct { Elf64_Addr r_offset; Elf64_Xword r_info; } Elf64_Rel; .Ed .Pp Relocation structures that need an addend: .Bd -literal -offset indent typedef struct { Elf32_Addr r_offset; Elf32_Word r_info; Elf32_Sword r_addend; } Elf32_Rela; .Ed .Bd -literal -offset indent typedef struct { Elf64_Addr r_offset; Elf64_Xword r_info; Elf64_Sxword r_addend; } Elf64_Rela; .Ed .Pp .Bl -tag -width "r_offset" -compact .It Dv r_offset This member gives the location at which to apply the relocation action. For a relocatable file, the value is the byte offset from the beginning of the section to the storage unit affected by the relocation. For an executable file or shared object, the value is the virtual address of the storage unit affected by the relocation. .It Dv r_info This member gives both the symbol table index with respect to which the relocation must be made and the type of relocation to apply. Relocation types are processor-specific. When the text refers to a relocation entry's relocation type or symbol table index, it means the result of applying .Sy ELF_[32|64]_R_TYPE or .Sy ELF[32|64]_R_SYM , respectively to the entry's .Sy r_info member. .It Dv r_addend This member specifies a constant addend used to compute the value to be stored into the relocatable field. .El .Ss Note Section ELF note sections consist of entries with the following format: .Bl -column -offset indent "namesz" "32 bits" "Null-terminated originator name" .Sy Field Ta Sy Size Ta Sy Description .It Va namesz Ta 32 bits Ta Size of "name" .It Va descsz Ta 32 bits Ta Size of "desc" .It Va type Ta 32 bits Ta OS-dependent note type .It Va name Ta Va namesz Ta Null-terminated originator name .It Va desc Ta Va descsz Ta OS-dependent note data .El .Pp The .Va name and .Va desc -fields are padded to ensure 4-byte alignemnt. +fields are padded to ensure 4-byte alignment. .Va namesz and .Va descsz specify the unpadded length. .Pp .Fx defines the following ELF note types .Po with corresponding interpretation of .Va desc Pc : .Bl -tag -width 4n .It Dv NT_FREEBSD_ABI_TAG Pq Value: 1 Indicates the OS ABI version in a form of a 32-bit integer containing expected ABI version .Po i.e., .Dv __FreeBSD_version Pc . .It Dv NT_FREEBSD_NOINIT_TAG Pq Value: 2 Indicates that the C startup does not call initialization routines, and thus .Xr rtld 1 must do so. .Va desc is ignored. .It Dv NT_FREEBSD_ARCH_TAG Pq Value: 3 Contains the MACHINE_ARCH that the executable was built for. .It Dv NT_FREEBSD_FEATURE_CTL Pq Value: 4 Contains a bitmask of mitigations and features to enable: .Bl -tag -width 4n .It NT_FREEBSD_FCTL_ASLR_DISABLE Pq Value: 0x01 Request that address randomization (ASLR) not be performed. See .Xr security 7 . .It NT_FREEBSD_FCTL_PROTMAX_DISABLE Pq Value: 0x02 Request that .Xr mmap 2 calls not set PROT_MAX to the initial value of the .Fa prot argument. .It NT_FREEBSD_FCTL_STKGAP_DISABLE Pq Value: 0x04 Disable stack gap. .It NT_FREEBSD_FCTL_WXNEEDED Pq Value: 0x08 Indicate that the binary requires mappings that are simultaneously writeable and executable. .El .El .Sh SEE ALSO .Xr as 1 , .Xr gdb 1 Pq Pa ports/devel/gdb , .Xr ld 1 , .Xr objdump 1 , .Xr readelf 1 , .Xr execve 2 , .Xr zlib 3 , .Xr ar 5 , .Xr core 5 .Rs .%A Hewlett Packard .%B Elf-64 Object File Format .Re .Rs .%A Santa Cruz Operation .%B System V Application Binary Interface .Re .Rs .%A Unix System Laboratories .%T Object Files .%B "Executable and Linking Format (ELF)" .Re .Sh HISTORY The ELF header files made their appearance in .Fx 2.2.6 . ELF in itself first appeared in .At V . The ELF format is an adopted standard. .Sh AUTHORS This manual page was written by .An Jeroen Ruigrok van der Werven Aq Mt asmodai@FreeBSD.org with inspiration from BSDi's .Bsx .Nm manpage. diff --git a/share/man/man7/build.7 b/share/man/man7/build.7 index 6846b38c99a6..596c64da0673 100644 --- a/share/man/man7/build.7 +++ b/share/man/man7/build.7 @@ -1,915 +1,915 @@ .\" Copyright (c) 2000 .\" Mike W. Meyer .\" .\" 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 ``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 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 1, 2023 .Dt BUILD 7 .Os .Sh NAME .Nm build .Nd General instructions on how to build the system .Sh DESCRIPTION The sources for the .Fx system and its applications are contained in three different directories, normally .Pa /usr/src , .Pa /usr/doc , and .Pa /usr/ports . These directories may be initially empty or non-existent until updated with Git .Po installed from packages with .Xr pkg 7 or from .Xr ports 7 Pc . Directory .Pa /usr/src contains the .Dq "base system" sources, which is loosely defined as the things required to rebuild the system to a useful state. Directory .Pa /usr/doc contains the source for the system documentation, excluding the manual pages. Directory .Pa /usr/ports contains a tree that provides a consistent interface for building and installing third party applications. For more information about the ports build process, see .Xr ports 7 . .Pp The .Xr make 1 command is used in each of these directories to build and install the things in that directory. Issuing the .Xr make 1 command in any directory issues the .Xr make 1 command recursively in all subdirectories. With no target specified, the items in the directories are built and no further action is taken. .Pp A source tree is allowed to be read-only. As described in .Xr make 1 , objects are usually built in a separate object directory hierarchy specified by the environment variable .Va MAKEOBJDIRPREFIX , or under .Pa /usr/obj if variable .Va MAKEOBJDIRPREFIX is not set. The canonical object directory is described in the documentation for the .Cm buildworld target below. .Pp The build may be controlled by defining .Xr make 1 variables described in the .Sx ENVIRONMENT section below, and by the variables documented in .Xr make.conf 5 . .Pp The default components included in the build are specified in the file .Pa /etc/src.conf in the source tree. To override the default file, include the SRCCONF option in the make steps, pointing to a custom src.conf file. For more information see .Xr src.conf 5 . .Pp The following list provides the names and actions for the targets supported by the build system: .Bl -tag -width ".Cm cleandepend" .It Cm analyze Run Clang static analyzer against all objects and present output on stdout. .It Cm check Run tests for a given subdirectory. The default directory used is .Pa ${.OBJDIR} , but the check directory can be changed with .Pa ${CHECKDIR} . .It Cm checkworld Run the .Fx test suite on installed world. .It Cm clean Remove any files created during the build process. .It Cm cleandepend Remove the .Pa ${.OBJDIR}/${DEPENDFILE}* files generated by prior .Dq Li "make" and .Dq Li "make depend" steps. .It Cm cleandir Remove the canonical object directory if it exists, or perform actions equivalent to .Dq Li "make clean cleandepend" if it does not. This target will also remove an .Pa obj link in .Pa ${.CURDIR} if that exists. .Pp It is advisable to run .Dq Li "make cleandir" twice: the first invocation will remove the canonical object directory and the second one will clean up .Pa ${.CURDIR} . .It Cm depend Generate a list of build dependencies in file .Pa ${.OBJDIR}/${DEPENDFILE} . Per-object dependencies are generated at build time and stored in .Pa ${.OBJDIR}/${DEPENDFILE}.${OBJ} . .It Cm install Install the results of the build to the appropriate location in the installation directory hierarchy specified in variable .Va DESTDIR . .It Cm obj Create the canonical object directory associated with the current directory. .It Cm objlink Create a symbolic link to the canonical object directory in .Pa ${.CURDIR} . .It Cm tags Generate a tags file using the program specified in the .Xr make 1 variable .Va CTAGS . The build system supports .Xr ctags 1 and .Nm "GNU Global" . .El .Pp The other supported targets under directory .Pa /usr/src are: .Bl -tag -width ".Cm distributeworld" .It Cm buildenv Spawn an interactive shell with environment variables set up for building the system or individual components. For cross-building the target architecture needs to be specified with .Xr make 1 variables .Va TARGET_ARCH and .Va TARGET . .Pp This target is only useful after a complete toolchain (including the compiler, linker, assembler, headers and libraries) has been built; see the .Cm toolchain target below. .It Cm buildworld Build everything but the kernel, configure files in .Pa etc , and .Pa release . The object directory can be changed from the default .Pa /usr/obj by setting the .Pa MAKEOBJDIRPREFIX .Xr make 1 variable. The actual build location prefix used depends on the .Va WITH_UNIFIED_OBJDIR option from .Xr src.conf 5 . If enabled it is .Pa ${MAKEOBJDIRPREFIX}${.CURDIR}/${TARGET}.${TARGET_ARCH} for all builds. If disabled it is .Pa ${MAKEOBJDIRPREFIX}${.CURDIR} for native builds, and .Pa ${MAKEOBJDIRPREFIX}/${TARGET}.${TARGET_ARCH}${.CURDIR} for cross builds and native builds with variable .Va CROSS_BUILD_TESTING set. .It Cm cleankernel Attempts to clean up targets built by a preceding .Cm buildkernel , or similar step, built from the same source directory and .Va KERNCONF . .It Cm cleanworld Attempt to clean up targets built by a preceding .Cm buildworld , or similar step, built from this source directory. .It Cm cleanuniverse When .Va WITH_UNIFIED_OBJDIR is enabled, attempt to clean up targets built by a preceding .Cm buildworld , .Cm universe , or similar step, for any architecture built from this source directory. .It Cm distributeworld Distribute everything compiled by a preceding .Cm buildworld step. Files are placed in the directory hierarchy specified by .Xr make 1 variable .Va DISTDIR . This target is used while building a release; see .Xr release 7 . .It Cm native-xtools This target builds a cross-toolchain for the given .Sy TARGET and .Sy TARGET_ARCH , as well as a select list of static userland tools for the host system. This is intended to be used in a jail where QEMU is used to improve performance by avoiding emulating binaries that do not need to be emulated. .Sy TARGET and .Sy TARGET_ARCH should be defined. .It Cm native-xtools-install Installs the results to .Pa ${DESTDIR}/${NXTP} where .Va NXTP defaults to .Pa nxb-bin . .Sy TARGET and .Sy TARGET_ARCH must be defined. .It Cm packageworld Archive the results of .Cm distributeworld , placing the results in .Va DISTDIR . This target is used while building a release; see .Xr release 7 . .It Cm installworld Install everything built by a preceding .Cm buildworld step into the directory hierarchy pointed to by .Xr make 1 variable .Va DESTDIR . .Pp If installing onto an NFS file system and running .Xr make 1 with the .Fl j option, make sure that .Xr rpc.lockd 8 is running on both client and server. See .Xr rc.conf 5 on how to make it start at boot time. .It Cm toolchain Create the build toolchain needed to build the rest of the system. For cross-architecture builds, this step creates a cross-toolchain. .It Cm universe For each architecture, execute a .Cm buildworld followed by a .Cm buildkernel for all kernels for that architecture, including .Pa LINT . This command takes a long time. .It Cm kernels Like .Cm universe with .Va WITHOUT_WORLDS defined so only the kernels for each architecture are built. .It Cm worlds Like .Cm universe with .Va WITHOUT_KERNELS defined so only the worlds for each architecture are built. .It Cm targets Print a list of supported .Va TARGET / .Va TARGET_ARCH pairs for world and kernel targets. .It Cm tinderbox Execute the same targets as .Cm universe . In addition print a summary of all failed targets at the end and exit with an error if there were any. .It Cm toolchains Create a build toolchain for each architecture supported by the build system. .It Cm xdev Builds and installs a cross-toolchain and sysroot for the given .Sy TARGET and .Sy TARGET_ARCH . The sysroot contains target library and headers. The target is an alias for .Cm xdev-build and .Cm xdev-install . The location of the files installed can be controlled with .Va DESTDIR . The target location in .Va DESTDIR is .Pa ${DESTDIR}/${XDTP} where .Va XDTP defaults to .Pa /usr/${XDDIR} and .Va XDDIR defaults to .Pa ${TARGET_ARCH}-freebsd . .It Cm xdev-build Builds for the .Cm xdev target. .It Cm xdev-install Installs the files for the .Cm xdev target. .It Cm xdev-links Installs autoconf-style symlinks to .Pa ${DESTDIR}/usr/bin pointing into the xdev toolchain in .Pa ${DESTDIR}/${XDTP} . .El .Pp Kernel specific build targets in .Pa /usr/src are: .Bl -tag -width ".Cm distributekernel" .It Cm buildkernel Rebuild the kernel and the kernel modules. The object directory can be changed from the default .Pa /usr/obj by setting the .Pa MAKEOBJDIRPREFIX .Xr make 1 variable. .It Cm installkernel Install the kernel and the kernel modules to directory .Pa ${DESTDIR}/boot/kernel , renaming any pre-existing directory with this name to .Pa kernel.old if it contained the currently running kernel. The target directory under .Pa ${DESTDIR} may be modified using the .Va INSTKERNNAME and .Va KODIR .Xr make 1 variables. .It Cm distributekernel Install the kernel to the directory .Pa ${DISTDIR}/kernel/boot/kernel . This target is used while building a release; see .Xr release 7 . .It Cm packagekernel Archive the results of .Cm distributekernel , placing the results in .Va DISTDIR . This target is used while building a release; see .Xr release 7 . .It Cm kernel Equivalent to .Cm buildkernel followed by .Cm installkernel .It Cm kernel-toolchain Rebuild the tools needed for kernel compilation. Use this if you did not do a .Cm buildworld first. .It Cm reinstallkernel Reinstall the kernel and the kernel modules, overwriting the contents of the target directory. As with the .Cm installkernel target, the target directory can be specified using the .Xr make 1 variable .Va INSTKERNNAME . .El .Pp Convenience targets for cleaning up the install destination directory denoted by variable .Va DESTDIR include: .Bl -tag -width ".Cm delete-old-libs" .It Cm check-old Print a list of old files and directories in the system. .It Cm delete-old Delete obsolete base system files and directories interactively. When .Li -DBATCH_DELETE_OLD_FILES is specified at the command line, the delete operation will be non-interactive. The variables .Va DESTDIR , .Va TARGET_ARCH and .Va TARGET should be set as with .Dq Li "make installworld" . .It Cm delete-old-libs Delete obsolete base system libraries interactively. This target should only be used if no third party software uses these libraries. When .Li -DBATCH_DELETE_OLD_FILES is specified at the command line, the delete operation will be non-interactive. The variables .Va DESTDIR , .Va TARGET_ARCH and .Va TARGET should be set as with .Dq Li "make installworld" . .El .Sh ENVIRONMENT Variables that influence all builds include: .Bl -tag -width ".Va MAKEOBJDIRPREFIX" .It Va DEBUG_FLAGS Defines a set of debugging flags that will be used to build all userland binaries under .Pa /usr/src . When .Va DEBUG_FLAGS is defined, the .Cm install and .Cm installworld targets install binaries from the current .Va MAKEOBJDIRPREFIX without stripping, so that debugging information is retained in the installed binaries. .It Va DESTDIR The directory hierarchy prefix where built objects will be installed. If not set, .Va DESTDIR defaults to the empty string. .It Va MAKEOBJDIRPREFIX Defines the prefix for directory names in the tree of built objects. Defaults to .Pa /usr/obj if not defined. This variable should only be set in the environment or .Pa /etc/src-env.conf and not via .Pa /etc/make.conf or .Pa /etc/src.conf or the command line. .It Va WITHOUT_WERROR If defined, compiler warnings will not cause the build to halt, even if the makefile says otherwise. .It Va WITH_CTF If defined, the build process will run the DTrace CTF conversion tools on built objects. .El .Pp Additionally, builds in .Pa /usr/src are influenced by the following .Xr make 1 variables: .Bl -tag -width ".Va LOCAL_MODULES_DIR" .It Va CROSS_TOOLCHAIN Requests use of an external toolchain to build either the world or kernel. This value of this variable can either be the full path to a file, or the base name of a file in .Pa ${LOCALBASE}/share/toolchains . The file should be a make file which sets variables to request an external toolchain such as .Va XCC . .Pp External toolchains are available in ports for both LLVM and GCC/binutils. For external toolchains available in ports, .Va CROSS_TOOLCHAIN should be set to the name of the package. LLVM toolchain packages use the name llvm. GCC toolchains provide separate packages for each architecture and use the name ${MACHINE_ARCH}-gcc. .It Va KERNCONF Overrides which kernel to build and install for the various kernel make targets. It defaults to .Cm GENERIC . .It Va KERNCONFDIR Overrides the directory in which .Va KERNCONF and any files included by .Va KERNCONF should be found. Defaults to .Pa sys/${ARCH}/conf . .It Va KERNFAST If set, the build target .Cm buildkernel defaults to setting .Va NO_KERNELCLEAN , .Va NO_KERNELCONFIG , and .Va NO_KERNELOBJ . When set to a value other than .Cm 1 then .Va KERNCONF is set to the value of .Va KERNFAST . .It Va LOCAL_DIRS If set, this variable supplies a list of additional directories relative to the root of the source tree to build as part of the .Cm everything target. The directories are built in parallel with each other, and with the base system directories. Insert a .Va .WAIT directive at the beginning of the .Va LOCAL_DIRS list to ensure all base system directories are built first. .Va .WAIT may also be used as needed elsewhere within the list. .It Va LOCAL_ITOOLS If set, this variable supplies a list of additional tools that are used by the .Cm installworld and .Cm distributeworld targets. .It Va LOCAL_LIB_DIRS If set, this variable supplies a list of additional directories relative to the root of the source tree to build as part of the .Cm libraries target. The directories are built in parallel with each other, and with the base system libraries. Insert a .Va .WAIT directive at the beginning of the .Va LOCAL_DIRS list to ensure all base system libraries are built first. .Va .WAIT may also be used as needed elsewhere within the list. .It Va LOCAL_MTREE If set, this variable supplies a list of additional mtrees relative to the root of the source tree to use as part of the .Cm hierarchy target. .It Va LOCAL_LEGACY_DIRS If set, this variable supplies a list of additional directories relative to the root of the source tree to build as part of the .Cm legacy target. .It Va LOCAL_BSTOOL_DIRS If set, this variable supplies a list of additional directories relative to the root of the source tree to build as part of the .Cm bootstrap-tools target. .It Va LOCAL_TOOL_DIRS If set, this variable supplies a list of additional directories relative to the root of the source tree to build as part of the .Cm build-tools target. .It Va LOCAL_XTOOL_DIRS If set, this variable supplies a list of additional directories relative to the root of the source tree to build as part of the .Cm cross-tools target. .It Va PORTS_MODULES A list of ports with kernel modules that should be built and installed as part of the .Cm buildkernel and .Cm installkernel process. .Bd -literal -offset indent make PORTS_MODULES=emulators/virtualbox-ose-kmod kernel .Ed .It Va LOCAL_MODULES A list of external kernel modules that should be built and installed as part of the .Cm buildkernel and .Cm installkernel process. Defaults to the list of sub-directories of .Va LOCAL_MODULES_DIR . .It Va LOCAL_MODULES_DIR The directory in which to search for the kernel modules specified by .Va LOCAL_MODULES . Each kernel module should consist of a directory containing a makefile. Defaults to .Pa ${LOCALBASE}/sys/modules . .It Va SRCCONF Specify a file to override the default .Pa /etc/src.conf . The src.conf file controls the components to build. See .Xr src.conf 5 .It Va STRIPBIN Command to use at install time when stripping binaries. Be sure to add any additional tools required to run .Va STRIPBIN to the .Va LOCAL_ITOOLS .Xr make 1 variable before running the .Cm distributeworld or .Cm installworld targets. See .Xr install 1 for more details. .It Va SUBDIR_OVERRIDE Override the default list of sub-directories and only build the sub-directory named in this variable. If combined with .Cm buildworld then all libraries and includes, and some of the build tools will still build as well. Specifying .Cm -DNO_LIBS , and .Cm -DWORLDFAST will only build the specified directory as was done historically. When combined with .Cm buildworld -it is necesarry to override +it is necessary to override .Va LOCAL_LIB_DIRS with any custom directories containing libraries. This allows building a subset of the system in the same way as .Cm buildworld does using its sysroot handling. This variable can also be useful when debugging failed builds. .Bd -literal -offset indent make some-target SUBDIR_OVERRIDE=foo/bar .Ed .It Va SYSDIR Specify the location of the kernel source to override the default .Pa /usr/src/sys . The kernel source is located in the .Pa sys subdirectory of the source tree checked out from the .Pa src.git repository. .It Va TARGET The target hardware platform. This is analogous to the .Dq Nm uname Fl m output. This is necessary to cross-build some target architectures. For example, cross-building for ARM64 machines requires .Va TARGET_ARCH Ns = Ns Li aarch64 and .Va TARGET Ns = Ns Li arm64 . If not set, .Va TARGET defaults to the current hardware platform, unless .Va TARGET_ARCH is also set, in which case it defaults to the appropriate value for that architecture. .It Va TARGET_ARCH The target machine processor architecture. This is analogous to the .Dq Nm uname Fl p output. Set this to cross-build for a different architecture. If not set, .Va TARGET_ARCH defaults to the current machine architecture, unless .Va TARGET is also set, in which case it defaults to the appropriate value for that platform. Typically, one only needs to set .Va TARGET . .El .Pp Builds under directory .Pa /usr/src are also influenced by defining one or more of the following symbols, using the .Fl D option of .Xr make 1 : .Bl -tag -width ".Va LOADER_DEFAULT_INTERP" .It Va LOADER_DEFAULT_INTERP Defines what interpreter the default loader program will have. Valid values include .Dq 4th , .Dq lua , and .Dq simp . This creates the default link for .Pa /boot/loader to the loader with that interpreter. It also determines what interpreter is compiled into .Pa userboot . .It Va NO_CLEANDIR If set, the build targets that clean parts of the object tree use the equivalent of .Dq make clean instead of .Dq make cleandir . .It Va NO_CLEAN If set, no object tree files are cleaned at all. This is the default when .Va WITH_META_MODE is used with .Xr filemon 4 loaded. See .Xr src.conf 5 for more details. Setting .Va NO_CLEAN implies .Va NO_KERNELCLEAN , so when .Va NO_CLEAN is set no kernel objects are cleaned either. .It Va NO_CTF If set, the build process does not run the DTrace CTF conversion tools on built objects. .It Va NO_SHARE If set, the build does not descend into the .Pa /usr/src/share subdirectory (i.e., manual pages, locale data files, timezone data files and other .Pa /usr/src/share files will not be rebuild from their sources). .It Va NO_KERNELCLEAN If set, the build process does not run .Dq make clean as part of the .Cm buildkernel target. .It Va NO_KERNELCONFIG If set, the build process does not run .Xr config 8 as part of the .Cm buildkernel target. .It Va NO_KERNELOBJ If set, the build process does not run .Dq make obj as part of the .Cm buildkernel target. .It Va NO_LIBS If set, the libraries phase will be skipped. .It Va NO_OBJWALK If set, no object directories will be created. This should only be used if object directories were created in a previous build and no new directories are connected. .It Va UNIVERSE_TOOLCHAIN Requests use of the toolchain built as part of the .Cm universe target as an external toolchain. .It Va WORLDFAST If set, the build target .Cm buildworld defaults to setting .Va NO_CLEAN , .Va NO_OBJWALK , and will skip most bootstrap phases. It will only bootstrap libraries and build all of userland. This option should be used only when it is known that none of the bootstrap needs changed and that no new directories have been connected to the build. .El .Pp Builds under directory .Pa /usr/doc are influenced by the following .Xr make 1 variables: .Bl -tag -width ".Va DOC_LANG" .It Va DOC_LANG If set, restricts the documentation build to the language subdirectories specified as its content. The default action is to build documentation for all languages. .El .Pp Builds using the .Cm universe and related targets are influenced by the following .Xr make 1 variables: .Bl -tag -width ".Va USE_GCC_TOOLCHAINS" .It Va JFLAG Pass the value of this variable to each .Xr make 1 invocation used to build worlds and kernels. This can be used to enable multiple jobs within a single architecture's build while still building each architecture serially. .It Va MAKE_JUST_KERNELS Only build kernels for each supported architecture. .It Va MAKE_JUST_WORLDS Only build worlds for each supported architecture. .It Va WITHOUT_WORLDS Only build kernels for each supported architecture. .It Va WITHOUT_KERNELS Only build worlds for each supported architecture. .It Va UNIVERSE_TARGET Execute the specified .Xr make 1 target for each supported architecture instead of the default action of building a world and one or more kernels. This variable implies .Va WITHOUT_KERNELS . .It Va USE_GCC_TOOLCHAINS Use external GCC toolchains to build the requested targets. If the required toolchain package for a supported architecture is not installed, the build for that architecture is skipped. .It Va TARGETS Only build the listed targets instead of each supported architecture. .It Va EXTRA_TARGETS In addition to the supported architectures, build the semi-supported architectures. A semi-supported architecture has build support in the .Fx tree, but receives significantly less testing and is generally for fringe uses that do not have a wide appeal. .El .Sh FILES .Bl -tag -width ".Pa /usr/share/examples/etc/make.conf" -compact .It Pa /usr/doc/Makefile .It Pa /usr/doc/share/mk/doc.project.mk .It Pa /usr/ports/Mk/bsd.port.mk .It Pa /usr/ports/Mk/bsd.sites.mk .It Pa /usr/share/examples/etc/make.conf .It Pa /usr/src/Makefile .It Pa /usr/src/Makefile.inc1 .El .Sh EXAMPLES For an .Dq approved method of updating your system from the latest sources, please see the .Sx COMMON ITEMS section in .Pa src/UPDATING . .Pp The following sequence of commands can be used to cross-build the system for the armv6 architecture on an amd64 host: .Bd -literal -offset indent cd /usr/src make TARGET_ARCH=armv6 buildworld buildkernel make TARGET_ARCH=armv6 DESTDIR=/clients/arm installworld installkernel .Ed .Sh HISTORY The .Nm manpage first appeared in .Fx 4.3 . .Sh SEE ALSO .Xr cc 1 , .Xr install 1 , .Xr make 1 , .Xr make.conf 5 , .Xr src.conf 5 , .Xr arch 7 , .Xr pkg 7 , .Xr ports 7 , .Xr release 7 , .Xr tests 7 , .Xr config 8 , .Xr etcupdate 8 , .Xr reboot 8 , .Xr shutdown 8 .Sh AUTHORS .An Mike W. Meyer Aq Mt mwm@mired.org diff --git a/share/man/man7/mitigations.7 b/share/man/man7/mitigations.7 index 950d84042c71..1cea86e352c5 100644 --- a/share/man/man7/mitigations.7 +++ b/share/man/man7/mitigations.7 @@ -1,367 +1,367 @@ .\" Copyright © 2023 The FreeBSD Foundation .\" .\" This documentation was written by Ed Maste , and .\" Olivier Certner at Kumacom SAS, under .\" sponsorship of 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. .\" .Dd October 6, 2023 .Dt MITIGATIONS 7 .Os .Sh NAME .Nm mitigations .Nd FreeBSD Security Vulnerability Mitigations .Sh SYNOPSIS In .Fx , various security mitigations are employed to limit the impact of vulnerabilities and protect the system from malicious attacks. Some of these mitigations have run-time controls to enable them on a global or per-process basis, some are optionally enabled or disabled at compile time, and some are inherent to the implementation and have no controls. .Pp The following vulnerability mitigations are covered in this document: .Bl -bullet -compact .It Address Space Layout Randomization (ASLR) .It Position Independent Executable (PIE) .It Write XOR Execute page protection policy .It .Dv PROT_MAX .It Relocation Read-Only (RELRO) .It Bind Now .\".It .\"Stack Smashing Protection (SSP) .\".It .\"Supervisor Mode Memory Protection .It Hardware Vulnerability Mitigation Controls .It Capsicum .El .Pp Please note that the effectiveness and availability of these mitigations may vary depending on the .Fx version and system configuration. .Sh DESCRIPTION Security vulnerability mitigations are techniques employed in .Fx to limit the potential impact of security vulnerabilities in software and hardware. It is essential to understand that mitigations do not directly address the underlying security issues. They are not a substitute for secure coding practices. Mitigations serve as an additional layer of defense, helping to reduce the likelihood of a successful exploitation of vulnerabilities by making it more difficult for attackers to achieve their objectives. .Pp This manual page describes the security mitigations implemented in .Fx to enhance the overall security of the operating system. Each mitigation is designed to protect against specific types of attacks and vulnerabilities. .\" .Sh SOFTWARE VULNERABILITY MITIGATIONS .Ss Address Space Layout Randomization (ASLR) Address Space Layout Randomization (ASLR) is a security mitigation technique that works by randomizing the memory addresses where system and application code, data, and libraries are loaded, making it more challenging for attackers to predict the memory layout and exploit vulnerabilities. .Pp ASLR introduces randomness into the memory layout during process execution, reducing the predictability of memory addresses. ASLR is intended to make exploitation more difficult in the event that an attacker discovers a software vulnerability, such as a buffer overflow. .Pp ASLR can be enabled on both a global and per-process basis. Global control is provided by a separate set of .Xr sysctl 8 knobs for 32- and 64-bit processes. It can be or disabled on a per-process basis via .Xr proccontrol 1 . Note that an ASLR mode change takes effect upon address space change, i.e., upon .Xr execve 2 . .Pp Global controls for 32-bit processes: .Bl -tag -width kern.elf32.aslr.pie_enable .It Va kern.elf32.aslr.enable Enable ASLR for 32-bit ELF binaries, other than Position Independent -Exectutable (PIE) binaries. +Executable (PIE) binaries. .It Va kern.elf32.aslr.pie_enable Enable ASLR for 32-bit Position Independent Executable (PIE) ELF binaries. .It Va kern.elf32.aslr.honor_sbrk Reserve the legacy .Xr sbrk 2 region for compatibility with older binaries. .It Va kern.elf32.aslr.stack Randomize the stack location for 32-bit ELF binaries. .El .Pp Global controls for 64-bit processes: .Bl -tag -width kern.elf64.aslr.pie_enable .It Va kern.elf64.aslr.enable Enable ASLR for 64-bit ELF binaries, other than Position Independent -Exectutable (PIE) binaries. +Executable (PIE) binaries. .It Va kern.elf64.aslr.pie_enable Enable ASLR for 64-bit Position Independent Executable (PIE) ELF binaries. .It Va kern.elf64.aslr.honor_sbrk Reserve the legacy .Xr sbrk 2 region for compatibility with older binaries. .It Va kern.elf64.aslr.stack Randomize the stack location for 64-bit ELF binaries. .El .Pp To execute a command with ASLR enabled or disabled: .Pp proccontrol .Fl m Ar aslr .Op Fl s Ar enable | disable .Ar command .\" .Ss Position Independent Executable (PIE) PIE binaries are executable files that do not have a fixed load address. They can be loaded at an arbitrary memory address by the .Xr rtld run-time linker. With ASLR they are loaded at a random address on each execution. .\" .Ss Write XOR Execute page protection policy Write XOR Execute (W^X) is a vulnerability mitigation strategy that strengthens the security of the system by controlling memory access permissions. .Pp Under the W^X mitigation, memory pages may be writable (W) or executable (E), but not both at the same time. This means that code execution is prevented in areas of memory that are designated as writable, and writing or modification of memory is restricted in areas marked for execution. Applications that perform Just In Time (JIT) compilation need to be adapted to be compatible with W^X. .Pp There are separate .Xr sysctl 8 knobs to control W^X policy enforcement for 32- and 64-bit processes. The W^X policy is enabled by setting the appropriate .Dv allow_wx sysctl to 0. .Bl -tag -width kern.elf64.allow_wx .It Va kern.elf32.allow_wx Allow 32-bit processes to map pages simultaneously writable and executable. .It Va kern.elf64.allow_wx Allow 64-bit processes to map pages simultaneously writable and executable. .El .\" .Ss PROT_MAX .Dv PROT_MAX is a FreeBSD-specific extension to .Xr mmap 2 . .Dv PROT_MAX provides the ability to set the maximum protection of a region allocated by .Xr mmap and later altered by .Xr mprotect . For example, memory allocated originally with an mmap prot argument of PROT_MAX(PROT_READ | PROT_WRITE) | PROT_READ may be made writable by a future .Xr mprotect call, but may not be made executable. .\" .Ss Relocation Read-Only (RELRO) Relocation Read-Only (RELRO) is a mitigation tool that makes certain portions of a program's address space that contain ELF metadata read-only, after relocation processing by .Xr rtld 1 . .Pp When enabled in isolation the RELRO option provides .Em partial RELRO support. In this case the Procedure Linkage Table (PLT)-related part of the Global Offset Table (GOT) (in the section typically named .got.plt) remains writable. .Pp RELRO is enabled by default. The .Xr src.conf 5 build-time option .Va WITHOUT_RELRO may be used to disable it. .Ss BIND_NOW The .Va WITH_BIND_NOW .Xr src.conf 5 build-time option causes binaries to be built with the .Dv DF_BIND_NOW flag set. The run-time loader .Xr rtld 1 will then perform all relocation processing when the process starts, instead of on demand (on the first access to each symbol). .Pp When enabled in combination with .Dv RELRO (which is enabled by default) this provides .Em full RELRO . The entire GOT (.got and .got.plt) are made read-only at program startup, preventing attacks on the relocation table. Note that this results in a nonstandard Application Binary Interface (ABI), and it is possible that some applications may not function correctly. .\" .\".Ss Stack Smashing Protection (SSP) .\" .\".Ss Supervisor mode memory protection .\" .Ss Hardware vulnerability controls See .Xr security 7 for more information. .\" .Ss Capsicum Capsicum is a lightweight OS capability and sandbox framework. See .Xr capsicum 4 for more information. .Pp .Sh HARDWARE VULNERABILITY MITIGATIONS Recent years have seen an unending stream of new hardware vulnerabilities, notably CPU ones generally caused by detectable microarchitectural side-effects of speculative execution which leak private data from some other thread or process or sometimes even internal CPU state that is normally inaccessible. Hardware vendors usually address these vulnerabilities as they are discovered by releasing microcode updates, which may then be bundled into platform firmware updates .Pq historically called BIOS updates for PCs . .Pp The best defense overall against hardware vulnerabilities is to timely apply these updates when available and to disable the affected hardware's problematic functionalities when possible (e.g., CPU Simultaneous Multi-Threading). Software mitigations are only partial substitutes for these, but they can be helpful on out-of-support hardware or as complements for just-discovered vulnerabilities not yet addressed by vendors. Some software mitigations depend on hardware capabilities provided by a microcode update. .Pp FreeBSD's usual policy is to apply by default all OS-level mitigations that do not require recompilation, except those the particular hardware it is running on is known not to be vulnerable to .Pq which sometimes requires firmware updates , or those that are extremely detrimental to performance in proportion to the protection they actually provide. OS-level mitigations generally can have noticeable performance impacts on specific workloads. If your threat model allows it, you may want to try disabling some of them in order to possibly get better performance. Conversely, minimizing the risks may require you to explicitly enable the most expensive ones. The description of each vulnerability/mitigation indicates whether it is enabled or disabled by default and under which conditions. It also lists the knobs to tweak to force a particular status. .Ss Zenbleed The .Dq Zenbleed vulnerability exclusively affects AMD processors based on the Zen2 microarchitecture. In contrast with, e.g., Meltdown and the different variants of Spectre, which leak data by leaving microarchitectural traces, Zenbleed is a genuine hardware bug affecting the CPU's architectural state. With particular sequences of instructions whose last ones are mispredicted by speculative execution, it is possible to make appear in an XMM register data previously put in some XMM register by some preceding or concurrent task executing on the same physical core .Po disabling Simultaneous Muti-Threading .Pq SMT is thus not a sufficient protection .Pc . .Pp According to the vulnerability's discoverer, all Zen2-based processors are affected .Po see .Lk https://lock.cmpxchg8b.com/zenbleed.html .Pc . As of August 2023, AMD has not publicly listed any corresponding errata but has issued a security bulletin .Pq AMD-SB-7008 entitled .Dq Cross-Process Information Leak indicating that platform firmware fixing the vulnerability will be distributed to manufacturers no sooner than the end of 2023, except for Rome processors for which it is already available. No standalone CPU microcodes have been announced so far. The only readily-applicable fix mentioned by the discoverer is to set a bit of an undocumented MSR, which reportedly completely stops XMM register leaks. .Pp .Fx currently sets this bit by default on all Zen2 processors. In the future, it might set it by default only on those Zen2 processors whose microcode has not been updated to revisions fixing the vulnerability, once such microcode updates have been actually released and community-tested. To this mitigation are associated the following knobs: .Bl -tag -width indent .It Va machdep.mitigations.zenbleed.enable A read-write integer tunable and sysctl indicating whether the mitigation should be forcibly disabled (0), enabled (1) or if it is left to .Fx to selectively apply it (2). Any other integer value is silently converted to and treated as value 2. Note that this setting is silently ignored when running on non-Zen2 processors to ease applying a common configuration to heterogeneous machines. .It Va machdep.mitigations.zenbleed.state A read-only string indicating the current mitigation state. It can be either .Dq Not applicable , if the processor is not Zen2-based, .Dq Mitigation enabled or .Dq Mitigation disabled . This state is automatically updated each time the sysctl .Va machdep.mitigations.zenbleed.enable is written to. Note that it can become inaccurate if the chicken bit is set or cleared directly via .Xr cpuctl 4 .Po which includes the .Xr cpucontrol 8 utility .Pc . .El .Pp The performance impact and threat models related to these mitigations should be considered when configuring and deploying them in a .Fx system. .Pp .Sh SEE ALSO .Xr elfctl 1 , .Xr proccontrol 1 , .Xr rtld 1 , .Xr mmap 2 , .Xr src.conf 5 , .Xr sysctl.conf 5 , .Xr security 7 , .Xr cpucontrol 8 , .Xr sysctl 8