diff --git a/share/man/man4/acpi_hp.4 b/share/man/man4/acpi_hp.4 index bfb9a0f3257a..a3f320e4b3d8 100644 --- a/share/man/man4/acpi_hp.4 +++ b/share/man/man4/acpi_hp.4 @@ -1,289 +1,288 @@ .\" Copyright (c) 2009 Michael Gmelin .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd June 19, 2015 .Dt ACPI_HP 4 .Os .Sh NAME .Nm acpi_hp .Nd "ACPI extras driver for HP laptops" .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_hp" .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_hp_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for ACPI-controlled features found on HP laptops that use a WMI enabled BIOS (e.g., HP Compaq 8510p and 6510p). .Pp The main purpose of this driver is to provide an interface, accessible via .Xr sysctl 8 , .Xr devd 8 and .Xr devfs 8 , through which applications can determine and change the status of various laptop components and BIOS settings. -.Pp .Ss Xr devd 8 Events Devd events received by .Xr devd 8 provide the following information: .Pp .Bl -tag -width "subsystem" -offset indent -compact .It system .Qq Li ACPI .It subsystem .Qq Li HP .It type The source of the event in the ACPI namespace. The value depends on the model. .It notify Event code (see below). .El .Pp Event codes: .Pp .Bl -tag -width "0xc0" -offset indent -compact .It Li 0xc0 WLAN on air status changed to 0 (not on air) .It Li 0xc1 WLAN on air status changed to 1 (on air) .It Li 0xd0 Bluetooth on air status changed to 0 (not on air) .It Li 0xd1 Bluetooth on air status changed to 1 (on air) .It Li 0xe0 WWAN on air status changed to 0 (not on air) .It Li 0xe1 WWAN on air status changed to 1 (on air) .El .Ss Xr devfs 8 Device You can read /dev/hpcmi to see your current BIOS settings. The detail level can be adjusted by setting the sysctl .Va cmi_detail as described below. .Sh SYSCTL VARIABLES The following sysctls are currently implemented: .Ss WLAN: .Bl -tag -width indent .It Va dev.acpi_hp.0.wlan_enabled Toggle WLAN chip activity. .It Va dev.acpi_hp.0.wlan_radio (read-only) WLAN radio status (controlled by hardware switch) .It Va dev.acpi_hp.0.wlan_on_air (read-only) WLAN on air (chip enabled, hardware switch enabled + enabled in BIOS) .It Va dev.acpi_hp.0.wlan_enabled_if_radio_on If set to 1, the WLAN chip will be enabled if the radio is turned on .It Va dev.acpi_hp.0.wlan_disable_if_radio_off If set to 1, the WLAN chip will be disabled if the radio is turned off .El .Ss Bluetooth: .Bl -tag -width indent .It Va dev.acpi_hp.0.bt_enabled Toggle Bluetooth chip activity. .It Va dev.acpi_hp.0.bt_radio (read-only) Bluetooth radio status (controlled by hardware switch) .It Va dev.acpi_hp.0.bt_on_air (read-only) Bluetooth on air (chip enabled, hardware switch enabled + enabled in BIOS) .It Va dev.acpi_hp.0.bt_enabled_if_radio_on If set to 1, the Bluetooth chip will be enabled if the radio is turned on .It Va dev.acpi_hp.0.bt_disable_if_radio_off If set to 1, the Bluetooth chip will be disabled if the radio is turned off .El .Ss WWAN: .Bl -tag -width indent .It Va dev.acpi_hp.0.wwan_enabled Toggle WWAN chip activity. .It Va dev.acpi_hp.0.wwan_radio (read-only) WWAN radio status (controlled by hardware switch) .It Va dev.acpi_hp.0.wwan_on_air (read-only) WWAN on air (chip enabled, hardware switch enabled + enabled in BIOS) .It Va dev.acpi_hp.0.wwan_enabled_if_radio_on If set to 1, the WWAN chip will be enabled if the radio is turned on .It Va dev.acpi_hp.0.wwan_disable_if_radio_off If set to 1, the WWAN chip will be disabled if the radio is turned off .El .Ss Misc: .Bl -tag -width indent .It Va dev.acpi_hp.0.als_enabled Toggle ambient light sensor (ALS) .It Va dev.acpi_hp.0.display (read-only) Display status (bitmask) .It Va dev.acpi_hp.0.hdd_temperature (read-only) HDD temperature .It Va dev.acpi_hp.0.is_docked (read-only) Docking station status (1 if docked) .It Va dev.acpi_hp.0.cmi_detail Bitmask to control detail level in /dev/hpcmi output (values can be ORed). .Bl -tag -width "0x01" -offset indent -compact .It Li 0x01 Show path component of BIOS setting .It Li 0x02 Show a list of valid options for the BIOS setting .It Li 0x04 Show additional flags of BIOS setting (ReadOnly etc.) .It Li 0x08 Query highest BIOS entry instance. This is broken on many HP models and therefore disabled by default. .El .It Va dev.acpi_hp.0.verbose (read-only) Set verbosity level .El .Pp Defaults for these sysctls can be set in .Xr sysctl.conf 5 . .Sh HARDWARE The .Nm driver has been reported to support the following hardware: .Pp .Bl -bullet -compact .It HP Compaq 8510p .It HP Compaq nx7300 .El .Pp It should work on most HP laptops that feature a WMI enabled BIOS. .Sh FILES .Bl -tag -width ".Pa /dev/hpcmi" .It Pa /dev/hpcmi Interface to read BIOS settings .El .Sh EXAMPLES The following can be added to .Xr devd.conf 5 in order disable the LAN interface when WLAN on air and reenable if it is not: .Bd -literal -offset indent notify 0 { match "system" "ACPI"; match "subsystem" "HP"; match "notify" "0xc0"; action "ifconfig em0 up"; }; notify 0 { match "system" "ACPI"; match "subsystem" "HP"; match "notify" "0xc1"; action "ifconfig em0 down"; }; .Ed .Pp Enable the ambient light sensor: .Bd -literal -offset indent sysctl dev.acpi_hp.0.als_enabled=1 .Ed .Pp Enable Bluetooth: .Bd -literal -offset indent sysctl dev.acpi_hp.0.bt_enabled=1 .Ed .Pp Get BIOS settings: .Bd -literal -offset indent cat /dev/hpcmi Serial Port Disable Infrared Port Enable Parallel Port Disable Flash Media Reader Disable USB Ports including Express Card slot Enable 1394 Port Enable Cardbus Slot Disable Express Card Slot Disable (...) .Ed .Pp Set maximum detail level for /dev/hpcmi output: .Bd -literal -offset indent sysctl dev.acpi_hp.0.cmi_detail=7 .Ed .Sh SEE ALSO .Xr acpi 4 , .Xr acpi_wmi 4 , .Xr sysctl.conf 5 , .Xr devd 8 , .Xr devfs 8 , .Xr sysctl 8 .Sh HISTORY The .Nm device driver first appeared in .Fx 8.0 . .Sh AUTHORS .An -nosplit The .Nm driver was written by .An Michael Gmelin Aq Mt freebsd@grem.de . .Pp It has been inspired by hp-wmi driver, which implements a subset of these features (hotkeys) on Linux. .Bl -tag -width indent .It HP CMI whitepaper: https://h20331.www2.hp.com/Hpsub/downloads/cmi_whitepaper.pdf .It wmi-hp for Linux: https://www.kernel.org .It WMI and ACPI: http://www.microsoft.com/whdc/system/pnppwr/wmi/wmi-acpi.mspx .El .Pp This manual page was written by .An Michael Gmelin Aq Mt freebsd@grem.de . .Sh BUGS This driver is experimental and has only been tested on i386 on an HP Compaq 8510p which featured all supported wireless devices (WWAN/BT/WLAN). Expect undefined results when operating on different hardware. .Pp Loading the driver is slow. Reading from .Pa /dev/hpcmi is even slower. .Pp Additional features like HP specific sensor readings or writing BIOS settings are not supported. diff --git a/share/man/man4/ahci.4 b/share/man/man4/ahci.4 index 58b9fea7c838..ba2bde4e34bd 100644 --- a/share/man/man4/ahci.4 +++ b/share/man/man4/ahci.4 @@ -1,211 +1,211 @@ .\" Copyright (c) 2009-2013 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. .\" .\" $FreeBSD$ .\" .Dd December 17, 2021 .Dt AHCI 4 .Os .Sh NAME .Nm ahci .Nd Serial ATA Advanced Host Controller Interface 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 pci" .Cd "device scbus" .Cd "device ahci" .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 ahci_load="YES" .Ed .Pp The following tunables are settable from the .Xr loader 8 : .Bl -ohang .It Va hint.ahci. Ns Ar X Ns Va .msi controls Message Signaled Interrupts (MSI) usage by the specified controller. .Pp .Bl -tag -width 4n -offset indent -compact .It 0 MSI disabled; .It 1 single MSI vector used, if supported; .It 2 multiple MSI vectors used, if supported (default); .El .It Va hint.ahci. Ns Ar X Ns Va .ccc controls Command Completion Coalescing (CCC) usage by the specified controller. Non-zero value enables CCC and defines maximum time (in ms), request can wait for interrupt, if there are some more requests present on controller queue. CCC reduces number of context switches on systems with many parallel requests, but it can decrease disk performance on some workloads due to additional command latency. .It Va hint.ahci. Ns Ar X Ns Va .direct controls whether the driver should use direct command completion from interrupt thread(s), or queue them to CAM completion threads. Default value depends on number of MSI interrupts supported and number of implemented SATA ports. .It Va hint.ahci. Ns Ar X Ns Va .em controls whether the driver should implement virtual enclosure management device on top of SGPIO or other interface. Default value depends on controller capabilities. .It Va hint.ahcich. Ns Ar X Ns Va .pm_level controls SATA interface Power Management for the specified channel, allowing some power to be saved at the cost of additional command latency. Possible values: .Pp .Bl -tag -width 4n -offset indent -compact .It 0 interface Power Management is disabled (default); .It 1 device is allowed to initiate PM state change, host is passive; .It 2 host initiates PARTIAL PM state transition every time port becomes idle; .It 3 host initiates SLUMBER PM state transition every time port becomes idle. .It 4 driver initiates PARTIAL PM state transition 1ms after port becomes idle; .It 5 driver initiates SLUMBER PM state transition 125ms after port becomes idle. .El .Pp Some controllers, such as ICH8, do not implement modes 2 and 3 with NCQ used. Because of artificial entering latency, performance degradation in modes 4 and 5 is much smaller then in modes 2 and 3. .Pp Note that interface Power Management complicates device presence detection. A manual bus reset/rescan may be needed after device hot-plug, unless hardware implements Cold Presence Detection. .It Va hint.ahcich. Ns Ar X Ns Va .sata_rev setting to nonzero value limits maximum SATA revision (speed). Values 1, 2 and 3 are respectively 1.5, 3 and 6Gbps. .It Va hw.ahci.force setting to nonzero value forces driver attach to some known AHCI-capable chips even if they are configured for legacy IDE emulation. Default is 1. .El .Sh DESCRIPTION This driver provides the .Xr CAM 4 subsystem with native access to the .Tn SATA ports of AHCI-compatible controllers. Each SATA port found is represented to CAM as a separate bus with one target, or, if HBA supports Port Multipliers, 16 targets. Most of the bus-management details are handled by the SATA-specific transport of CAM. Connected ATA disks are handled by the ATA protocol disk peripheral driver .Xr ada 4 . ATAPI devices are handled by the SCSI protocol peripheral drivers .Xr cd 4 , .Xr da 4 , .Xr sa 4 , etc. .Pp Driver features include support for Serial ATA and ATAPI devices, Port Multipliers (including FIS-based switching, when supported), hardware command queues (up to 32 commands per port), Native Command Queuing, SATA interface Power Management, device hot-plug and Message Signaled Interrupts. .Pp Driver supports "LED" enclosure management messages, defined by the AHCI. When supported by hardware, it allows to control per-port activity, locate and fault LEDs via the .Xr led 4 API or emulated .Xr ses 4 device for localization and status reporting purposes. Supporting AHCI controllers may transmit that information to the backplane controllers via SGPIO interface. Backplane controllers interpret received statuses in some way (IBPI standard) to report them using present indicators. .Sh HARDWARE The .Nm driver supports AHCI compatible controllers having PCI class 1 (mass storage), subclass 6 (SATA) and programming interface 1 (AHCI). .Pp Also, in cooperation with atamarvell and atajmicron drivers of ata(4), it supports AHCI part of legacy-PATA + AHCI-SATA combined controllers, such as JMicron JMB36x and Marvell 88SE61xx. .Pp The .Nm driver also supports AHCI devices that act as PCI bridges for .Xr nvme 4 using Intel Rapid Storage Technology (RST). To use the .Xr nvme 4 device, either one must set the SATA mode in the BIOS to AHCI (from RST), or one must accept the performance with RST enabled due to interrupt sharing. .Fx will automatically detect AHCI devices with this extension that are in RST mode. When that happens, .Nm will attach .Xr nvme 4 children to the -.Xr ahci 4 +.Nm device. .Sh FILES .Bl -tag -width /dev/led/ahcich*.locate .It Pa /dev/led/ahci*.*.act activity LED device nodes .It Pa /dev/led/ahci*.*.fault fault LED device nodes .It Pa /dev/led/ahci*.*.locate locate LED device nodes .El .Sh SYSCTL .Bl -tag .It Pa dev.ahcich.X.disable_phy Set to 1 to disable the phy for the drive on channel X. Set to 0 to enable the phy. Useful for turning off troublemakers. Also useful for debugging when you need the ada drive to come and go. .El .Sh SEE ALSO .Xr ada 4 , .Xr ata 4 , .Xr cam 4 , .Xr cd 4 , .Xr da 4 , .Xr sa 4 , .Xr ses 4 .Sh HISTORY The .Nm driver first appeared in .Fx 8.0 . .Sh AUTHORS .An Alexander Motin Aq Mt mav@FreeBSD.org diff --git a/share/man/man4/altq.4 b/share/man/man4/altq.4 index d39f0816395d..5e8989025cb3 100644 --- a/share/man/man4/altq.4 +++ b/share/man/man4/altq.4 @@ -1,211 +1,210 @@ .\" .\" Copyright (c) 2004 Max Laier .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd January 26, 2021 .Dt ALTQ 4 .Os .Sh NAME .Nm ALTQ .Nd "alternate queuing of network packets" .Sh SYNOPSIS .Cd options ALTQ .Pp .Cd options ALTQ_CBQ .Cd options ALTQ_CODEL .Cd options ALTQ_RED .Cd options ALTQ_RIO .Cd options ALTQ_HFSC .Cd options ALTQ_CDNR .Cd options ALTQ_PRIQ .Cd options ALTQ_FAIRQ .Sh DESCRIPTION The .Nm system is a framework which provides several disciplines for queuing outgoing network packets. This is done by modifications to the interface packet queues. See .Xr altq 9 for details. .Pp The user interface for .Nm is implemented by the .Xr pfctl 8 utility, so please refer to the .Xr pfctl 8 and the .Xr pf.conf 5 man pages for a complete description of the .Nm capabilities and how to use it. .Ss Kernel Options The following options in the kernel configuration file are related to .Nm operation: .Pp .Bl -tag -width ".Dv ALTQ_DEBUG" -compact .It Dv ALTQ Enable .Nm . .It Dv ALTQ_CBQ Build the .Dq "Class Based Queuing" discipline. .It Dv ALTQ_CODEL Build the .Dq "Controlled Delay" discipline. .It Dv ALTQ_RED Build the .Dq "Random Early Detection" extension. .It Dv ALTQ_RIO Build .Dq "Random Early Drop" for input and output. .It Dv ALTQ_HFSC Build the .Dq "Hierarchical Packet Scheduler" discipline. .It Dv ALTQ_CDNR Build the traffic conditioner. This option is meaningless at the moment as the conditioner is not used by any of the available disciplines or consumers. .It Dv ALTQ_PRIQ Build the .Dq "Priority Queuing" discipline. .It Dv ALTQ_FAIRQ Build the .Dq "Fair Queuing" discipline. .It Dv ALTQ_NOPCC Required if the TSC is unusable. .It Dv ALTQ_DEBUG Enable additional debugging facilities. .El .Pp Note that .Nm Ns -disciplines cannot be loaded as kernel modules. In order to use a certain discipline you have to build it into a custom kernel. The .Xr pf 4 interface, that is required for the configuration process of .Nm can be loaded as a module. .Sh SUPPORTED DEVICES The driver modifications described in .Xr altq 9 are required to use a certain network card with .Nm . They have been applied to the following hardware drivers: .Xr ae 4 , .Xr age 4 , .Xr alc 4 , .Xr ale 4 , .Xr an 4 , .Xr aue 4 , .Xr axe 4 , .Xr bce 4 , .Xr bfe 4 , .Xr bge 4 , .Xr bxe 4 , .Xr cas 4 , .Xr cxgbe 4 , .Xr dc 4 , .Xr em 4 , .Xr epair 4 , .Xr et 4 , .Xr fxp 4 , .Xr gem 4 , .Xr igb 4 , .Xr ixgbe 4 , .Xr jme 4 , .Xr le 4 , .Xr liquidio 4 , .Xr msk 4 , .Xr mxge 4 , .Xr my 4 , .Xr nfe 4 , .Xr nge 4 , .Xr npe 4 , .Xr qlxgb 4 , .Xr re 4 , .Xr rl 4 , .Xr sge 4 , .Xr sis 4 , .Xr sk 4 , .Xr ste 4 , .Xr stge 4 , .Xr ti 4 , .Xr udav 4 , .Xr vge 4 , .Xr vr 4 , .Xr vte 4 , and .Xr xl 4 . .Pp The .Xr tun 4 and .Xr ng_iface 4 pseudo drivers also do support .Nm . .Pp The .Xr vlan 4 driver does not directly support .Nm , but as packets (mbufs) are passed to the underlying interface, a queue can be defined for the underlying interface, and any packets directed to the queue will be processed at the interface level. An example: -.Pp .Bd -literal -offset indent altq on igb0 cbq queue { def aq } queue def bandwidth 90% cbq (default borrow) queue aq bandwidth 10Mb cbq pass in on igb0.10 proto udp all queue aq keep state .Ed .Sh SEE ALSO .Xr pf 4 , .Xr pf.conf 5 , .Xr ipfw 8 , .Xr pfctl 8 , .Xr altq 9 .Sh HISTORY The .Nm system first appeared in March 1997 and found home in the KAME project (https://www.kame.net). It was imported to .Fx in 5.3 . diff --git a/share/man/man4/cc_newreno.4 b/share/man/man4/cc_newreno.4 index 71d3a239ecd1..76dd3b2559bb 100644 --- a/share/man/man4/cc_newreno.4 +++ b/share/man/man4/cc_newreno.4 @@ -1,171 +1,170 @@ .\" .\" Copyright (c) 2009 Lawrence Stewart .\" Copyright (c) 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 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. .\" .\" $FreeBSD$ .\" .Dd May 13, 2021 .Dt CC_NEWRENO 4 .Os .Sh NAME .Nm cc_newreno .Nd NewReno Congestion Control Algorithm .Sh SYNOPSIS .In netinet/cc/cc_newreno.h .Sh DESCRIPTION The NewReno congestion control algorithm is the default for TCP. Details about the algorithm can be found in RFC5681. .Sh Socket Options The .Nm module supports a number of socket options under TCP_CCALGOOPT (refer to .Xr tcp 4 and .Xr mod_cc 9 for details) which can be set with .Xr setsockopt 2 and tested with .Xr getsockopt 2 . The .Nm socket options use this structure defined in : .Bd -literal struct cc_newreno_opts { int name; uint32_t val; } .Ed .Bl -tag -width ".Va CC_NEWRENO_BETA_ECN" .It Va CC_NEWRENO_BETA Multiplicative window decrease factor, specified as a percentage, applied to the congestion window in response to a congestion signal per: cwnd = (cwnd * CC_NEWRENO_BETA) / 100. Default is 50. .It Va CC_NEWRENO_BETA_ECN Multiplicative window decrease factor, specified as a percentage, applied to the congestion window in response to an ECN congestion signal when .Va net.inet.tcp.cc.abe=1 per: cwnd = (cwnd * CC_NEWRENO_BETA_ECN) / 100. Default is 80. -.PP +.Pp Note that currently the only way to enable hystart++ is to enable it via socket option. When enabling it a value of 1 will enable precise internet-draft (version 4) behavior (subject to any MIB variable settings), other setting (2 and 3) are experimental. .El -.PP +.Pp Note that hystart++ requires the TCP stack be able to call to the congestion controller with both the .Va newround function as well as the .Va rttsample function. Currently the only TCP stacks that provide this feedback to the congestion controller is rack. -.Pp .Sh MIB Variables The algorithm exposes these variables in the .Va net.inet.tcp.cc.newreno branch of the .Xr sysctl 3 MIB: .Bl -tag -width ".Va beta_ecn" .It Va beta Multiplicative window decrease factor, specified as a percentage, applied to the congestion window in response to a congestion signal per: cwnd = (cwnd * beta) / 100. Default is 50. .It Va beta_ecn Multiplicative window decrease factor, specified as a percentage, applied to the congestion window in response to an ECN congestion signal when .Va net.inet.tcp.cc.abe=1 per: cwnd = (cwnd * beta_ecn) / 100. Default is 80. .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_vegas 4 , .Xr mod_cc 4 , .Xr tcp 4 , .Xr mod_cc 9 .Rs .%A "Mark Allman" .%A "Vern Paxson" .%A "Ethan Blanton" .%T "TCP Congestion Control" .%O "RFC 5681" .Re .Rs .%A "Naeem Khademi" .%A "Michael Welzl" .%A "Grenville Armitage" .%A "Gorry Fairhurst" .%T "TCP Alternative Backoff with ECN (ABE)" .%O "RFC 8511" .Re .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 congestion control algorithm first appeared in its modular form in .Fx 9.0 . .Pp The module 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 congestion control module was written by .An James Healy Aq Mt jimmy@deefa.com , .An Lawrence Stewart Aq Mt lstewart@FreeBSD.org and .An David Hayes Aq Mt david.hayes@ieee.org . .Pp Support for TCP ABE was added by .An Tom Jones Aq Mt tj@enoti.me . .Pp This manual page was written by .An Lawrence Stewart Aq Mt lstewart@FreeBSD.org . diff --git a/share/man/man4/ddb.4 b/share/man/man4/ddb.4 index bc46051c37ed..cfc2d37287e1 100644 --- a/share/man/man4/ddb.4 +++ b/share/man/man4/ddb.4 @@ -1,1630 +1,1628 @@ .\" .\" Mach Operating System .\" Copyright (c) 1991,1990 Carnegie Mellon University .\" Copyright (c) 2007 Robert N. M. Watson .\" All Rights Reserved. .\" .\" Permission to use, copy, modify and distribute this software and its .\" documentation is hereby granted, provided that both the copyright .\" notice and this permission notice appear in all copies of the .\" software, derivative works or modified versions, and any portions .\" thereof, and that both notices appear in supporting documentation. .\" .\" CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS" .\" CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR .\" ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE. .\" .\" Carnegie Mellon requests users of this software to return to .\" .\" Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU .\" School of Computer Science .\" Carnegie Mellon University .\" Pittsburgh PA 15213-3890 .\" .\" any improvements or extensions that they make and grant Carnegie Mellon .\" the rights to redistribute these changes. .\" .\" $FreeBSD$ .\" .Dd March 14, 2021 .Dt DDB 4 .Os .Sh NAME .Nm ddb .Nd interactive kernel debugger .Sh SYNOPSIS In order to enable kernel debugging facilities include: .Bd -ragged -offset indent .Cd options KDB .Cd options DDB .Ed .Pp To prevent activation of the debugger on kernel .Xr panic 9 : .Bd -ragged -offset indent .Cd options KDB_UNATTENDED .Ed .Pp In order to print a stack trace of the current thread on the console for a panic: .Bd -ragged -offset indent .Cd options KDB_TRACE .Ed .Pp To print the numerical value of symbols in addition to the symbolic representation, define: .Bd -ragged -offset indent .Cd options DDB_NUMSYM .Ed .Pp To enable the .Xr gdb 1 backend, so that remote debugging with .Xr kgdb 1 is possible, include: .Bd -ragged -offset indent .Cd options GDB .Ed .Sh DESCRIPTION The .Nm kernel debugger is an interactive debugger with a syntax inspired by .Xr gdb 1 . If linked into the running kernel, it can be invoked locally with the .Ql debug .Xr keymap 5 action, usually mapped to Ctrl+Alt+Esc, or by setting the .Va debug.kdb.enter sysctl to 1. The debugger is also invoked on kernel .Xr panic 9 if the .Va debug.debugger_on_panic .Xr sysctl 8 MIB variable is set non-zero, which is the default unless the .Dv KDB_UNATTENDED option is specified. Similarly, if the .Va debug.debugger_on_recursive_panic variable is set to .Dv 1 , then the debugger will be invoked on a recursive kernel panic. This variable has a default value of .Dv 0 , and has no effect if .Va debug.debugger_on_panic is already set non-zero. .Pp The current location is called .Va dot . The .Va dot is displayed with a hexadecimal format at a prompt. The commands .Ic examine and .Ic write update .Va dot to the address of the last line examined or the last location modified, and set .Va next to the address of the next location to be examined or changed. Other commands do not change .Va dot , and set .Va next to be the same as .Va dot . .Pp The general command syntax is: .Ar command Ns Op Li / Ns Ar modifier .Oo Ar addr Oc Ns Op , Ns Ar count .Pp A blank line repeats the previous command from the address .Va next with count 1 and no modifiers. Specifying .Ar addr sets .Va dot to the address. Omitting .Ar addr uses .Va dot . A missing .Ar count is taken to be 1 for printing commands or infinity for stack traces. A .Ar count of -1 is equivalent to a missing .Ar count . Options that are supplied but not supported by the given .Ar command are usually ignored. .Pp The .Nm debugger has a pager feature (like the .Xr more 1 command) for the output. If an output line exceeds the number set in the .Va lines variable, it displays .Dq Li --More-- and waits for a response. The valid responses for it are: .Pp .Bl -tag -compact -width ".Li SPC" .It Li SPC one more page .It Li RET one more line .It Li q abort the current command, and return to the command input mode .El .Pp Finally, .Nm provides a small (currently 10 items) command history, and offers simple .Nm emacs Ns -style command line editing capabilities. In addition to the .Nm emacs control keys, the usual .Tn ANSI arrow keys may be used to browse through the history buffer, and move the cursor within the current line. .Sh COMMANDS .Ss COMMON DEBUGGER COMMANDS .Bl -tag -width indent -compact .It Ic help Print a short summary of the available commands and command abbreviations. .Pp .It Xo .Ic examine Ns Op Li / Ns Cm AISabcdghilmorsuxz ... .Oo Ar addr Oc Ns Op , Ns Ar count .Xc .It Xo .Ic x Ns Op Li / Ns Cm AISabcdghilmorsuxz ... .Oo Ar addr Oc Ns Op , Ns Ar count .Xc Display the addressed locations according to the formats in the modifier. Multiple modifier formats display multiple locations. If no format is specified, the last format specified for this command is used. .Pp The format characters are: .Bl -tag -compact -width indent .It Cm b look at by bytes (8 bits) .It Cm h look at by half words (16 bits) .It Cm l look at by long words (32 bits) .It Cm g look at by quad words (64 bits) .It Cm a print the location being displayed .It Cm A print the location with a line number if possible .It Cm x display in unsigned hex .It Cm z display in signed hex .It Cm o display in unsigned octal .It Cm d display in signed decimal .It Cm u display in unsigned decimal .It Cm r display in current radix, signed .It Cm c display low 8 bits as a character. Non-printing characters are displayed as an octal escape code (e.g., .Ql \e000 ) . .It Cm s display the null-terminated string at the location. Non-printing characters are displayed as octal escapes. .It Cm m display in unsigned hex with character dump at the end of each line. The location is also displayed in hex at the beginning of each line. .It Cm i display as a disassembled instruction .It Cm I display as an disassembled instruction with possible alternate formats depending on the machine. On i386, this selects the alternate format for the instruction decoding (16 bits in a 32-bit code segment and vice versa). .It Cm S display a symbol name for the pointer stored at the address .El .Pp .It Ic xf Examine forward: execute an .Ic examine command with the last specified parameters to it except that the next address displayed by it is used as the start address. .Pp .It Ic xb Examine backward: execute an .Ic examine command with the last specified parameters to it except that the last start address subtracted by the size displayed by it is used as the start address. .Pp .It Ic print Ns Op Li / Ns Cm acdoruxz .It Ic p Ns Op Li / Ns Cm acdoruxz Print .Ar addr Ns s according to the modifier character (as described above for .Cm examine ) . Valid formats are: .Cm a , x , z , o , d , u , r , and .Cm c . If no modifier is specified, the last one specified to it is used. The argument .Ar addr can be a string, in which case it is printed as it is. For example: .Bd -literal -offset indent print/x "eax = " $eax "\enecx = " $ecx "\en" .Ed .Pp will print like: .Bd -literal -offset indent eax = xxxxxx ecx = yyyyyy .Ed .Pp .It Xo .Ic write Ns Op Li / Ns Cm bhl .Ar addr expr1 Op Ar expr2 ... .Xc .It Xo .Ic w Ns Op Li / Ns Cm bhl .Ar addr expr1 Op Ar expr2 ... .Xc Write the expressions specified after .Ar addr on the command line at succeeding locations starting with .Ar addr . The write unit size can be specified in the modifier with a letter .Cm b (byte), .Cm h (half word) or .Cm l (long word) respectively. If omitted, long word is assumed. .Pp .Sy Warning : since there is no delimiter between expressions, strange things may happen. It is best to enclose each expression in parentheses. .Pp .It Ic set Li $ Ns Ar variable Oo Li = Oc Ar expr Set the named variable or register with the value of .Ar expr . Valid variable names are described below. .Pp .It Ic break Ns Oo Li / Ns Cm u Oc Oo Ar addr Oc Ns Op , Ns Ar count .It Ic b Ns Oo Li / Ns Cm u Oc Oo Ar addr Oc Ns Op , Ns Ar count Set a break point at .Ar addr . If .Ar count is supplied, the .Ic continue command will not stop at this break point on the first .Ar count \- 1 times that it is hit. If the break point is set, a break point number is printed with .Ql # . This number can be used in deleting the break point or adding conditions to it. .Pp If the .Cm u modifier is specified, this command sets a break point in user address space. Without the .Cm u option, the address is considered to be in the kernel space, and a wrong space address is rejected with an error message. This modifier can be used only if it is supported by machine dependent routines. .Pp .Sy Warning : If a user text is shadowed by a normal user space debugger, user space break points may not work correctly. Setting a break point at the low-level code paths may also cause strange behavior. .Pp .It Ic delete Op Ar addr .It Ic d Op Ar addr .It Ic delete Li # Ns Ar number .It Ic d Li # Ns Ar number Delete the specified break point. The break point can be specified by a break point number with .Ql # , or by using the same .Ar addr specified in the original .Ic break command, or by omitting .Ar addr to get the default address of .Va dot . .Pp .It Ic halt Halt the system. .Pp .It Ic watch Oo Ar addr Oc Ns Op , Ns Ar size Set a watchpoint for a region. Execution stops when an attempt to modify the region occurs. The .Ar size argument defaults to 4. If you specify a wrong space address, the request is rejected with an error message. .Pp .Sy Warning : Attempts to watch wired kernel memory may cause unrecoverable error in some systems such as i386. Watchpoints on user addresses work best. .Pp .It Ic hwatch Oo Ar addr Oc Ns Op , Ns Ar size Set a hardware watchpoint for a region if supported by the architecture. Execution stops when an attempt to modify the region occurs. The .Ar size argument defaults to 4. .Pp .Sy Warning : The hardware debug facilities do not have a concept of separate address spaces like the watch command does. Use .Ic hwatch for setting watchpoints on kernel address locations only, and avoid its use on user mode address spaces. .Pp .It Ic dhwatch Oo Ar addr Oc Ns Op , Ns Ar size Delete specified hardware watchpoint. .Pp .It Ic kill Ar sig pid Send signal .Ar sig to process .Ar pid . The signal is acted on upon returning from the debugger. This command can be used to kill a process causing resource contention in the case of a hung system. See .Xr signal 3 for a list of signals. Note that the arguments are reversed relative to .Xr kill 2 . .Pp .It Ic step Ns Oo Li / Ns Cm p Oc Ns Op , Ns Ar count .It Ic s Ns Oo Li / Ns Cm p Oc Ns Op , Ns Ar count Single step .Ar count times. If the .Cm p modifier is specified, print each instruction at each step. Otherwise, only print the last instruction. .Pp .Sy Warning : depending on machine type, it may not be possible to single-step through some low-level code paths or user space code. On machines with software-emulated single-stepping (e.g., pmax), stepping through code executed by interrupt handlers will probably do the wrong thing. .Pp .It Ic continue Ns Op Li / Ns Cm c .It Ic c Ns Op Li / Ns Cm c Continue execution until a breakpoint or watchpoint. If the .Cm c modifier is specified, count instructions while executing. Some machines (e.g., pmax) also count loads and stores. .Pp .Sy Warning : when counting, the debugger is really silently single-stepping. This means that single-stepping on low-level code may cause strange behavior. .Pp .It Ic until Ns Op Li / Ns Cm p Stop at the next call or return instruction. If the .Cm p modifier is specified, print the call nesting depth and the cumulative instruction count at each call or return. Otherwise, only print when the matching return is hit. .Pp .It Ic next Ns Op Li / Ns Cm p .It Ic match Ns Op Li / Ns Cm p Stop at the matching return instruction. If the .Cm p modifier is specified, print the call nesting depth and the cumulative instruction count at each call or return. Otherwise, only print when the matching return is hit. .Pp .It Xo .Ic trace Ns Op Li / Ns Cm u .Op Ar pid | tid Ns .Op , Ns Ar count .Xc .It Xo .Ic t Ns Op Li / Ns Cm u .Op Ar pid | tid Ns .Op , Ns Ar count .Xc .It Xo .Ic where Ns Op Li / Ns Cm u .Op Ar pid | tid Ns .Op , Ns Ar count .Xc .It Xo .Ic bt Ns Op Li / Ns Cm u .Op Ar pid | tid Ns .Op , Ns Ar count .Xc Stack trace. The .Cm u option traces user space; if omitted, .Ic trace only traces kernel space. The optional argument .Ar count is the number of frames to be traced. If .Ar count is omitted, all frames are printed. .Pp .Sy Warning : User space stack trace is valid only if the machine dependent code supports it. .Pp .It Xo .Ic search Ns Op Li / Ns Cm bhl .Ar addr .Ar value .Op Ar mask Ns .Op , Ns Ar count .Xc Search memory for .Ar value . The optional .Ar count argument limits the search. .\" .Pp .It Ic reboot Op Ar seconds .It Ic reset Op Ar seconds Hard reset the system. If the optional argument .Ar seconds is given, the debugger will wait for this long, at most a week, before rebooting. .Pp .It Ic thread Ar addr | tid Switch the debugger to the thread with ID .Ar tid , if the argument is a decimal number, or address .Ar addr , otherwise. .El .Ss SPECIALIZED HELPER COMMANDS .Bl -tag -width indent -compact .It Xo .Ic findstack .Ar addr .Xc Prints the thread address for a thread kernel-mode stack of which contains the specified address. If the thread is not found, search the thread stack cache and prints the cached stack address. Otherwise, prints nothing. .Pp .It Ic show Cm all procs Ns Op Li / Ns Cm a .It Ic ps Ns Op Li / Ns Cm a Display all process information. The process information may not be shown if it is not supported in the machine, or the bottom of the stack of the target process is not in the main memory at that time. The .Cm a modifier will print command line arguments for each process. .\" .Pp .It Ic show Cm all trace .It Ic alltrace Show a stack trace for every thread in the system. .Pp .It Ic show Cm all ttys Show all TTY's within the system. Output is similar to .Xr pstat 8 , but also includes the address of the TTY structure. .\" .Pp .It Ic show Cm all vnets Show the same output as "show vnet" does, but lists all virtualized network stacks within the system. .\" .Pp .It Ic show Cm allchains Show the same information like "show lockchain" does, but for every thread in the system. .\" .Pp .It Ic show Cm alllocks Show all locks that are currently held. This command is only available if .Xr witness 4 is included in the kernel. .\" .Pp .It Ic show Cm allpcpu The same as "show pcpu", but for every CPU present in the system. .\" .Pp .It Ic show Cm allrman Show information related with resource management, including interrupt request lines, DMA request lines, I/O ports, I/O memory addresses, and Resource IDs. .\" .Pp .It Ic show Cm apic Dump data about APIC IDT vector mappings. .\" .Pp .It Ic show Cm breaks Show breakpoints set with the "break" command. .\" .Pp .It Ic show Cm bio Ar addr Show information about the bio structure .Vt struct bio present at .Ar addr . See the .Pa sys/bio.h header file and .Xr g_bio 9 for more details on the exact meaning of the structure fields. .\" .Pp .It Ic show Cm buffer Ar addr Show information about the buf structure .Vt struct buf present at .Ar addr . See the .Pa sys/buf.h header file for more details on the exact meaning of the structure fields. .\" .Pp .It Ic show Cm callout Ar addr Show information about the callout structure .Vt struct callout present at .Ar addr . .\" .Pp .It Ic show Cm cbstat Show brief information about the TTY subsystem. .\" .Pp .It Ic show Cm cdev Without argument, show the list of all created cdev's, consisting of devfs node name and struct cdev address. When address of cdev is supplied, show some internal devfs state of the cdev. .\" .Pp .It Ic show Cm conifhk Lists hooks currently waiting for completion in run_interrupt_driven_config_hooks(). .\" .Pp .It Ic show Cm cpusets Print numbered root and assigned CPU affinity sets. See .Xr cpuset 2 for more details. .\" .Pp .It Ic show Cm cyrixreg Show registers specific to the Cyrix processor. .\" .Pp .It Ic show Cm devmap Prints the contents of the static device mapping table. Currently only available on the ARM architecture. .\" .Pp .It Ic show Cm domain Ar addr Print protocol domain structure .Vt struct domain at address .Ar addr . See the .Pa sys/domain.h header file for more details on the exact meaning of the structure fields. .\" .Pp .It Ic show Cm ffs Op Ar addr Show brief information about ffs mount at the address .Ar addr , if argument is given. Otherwise, provides the summary about each ffs mount. .\" .Pp .It Ic show Cm file Ar addr Show information about the file structure .Vt struct file present at address .Ar addr . .\" .Pp .It Ic show Cm files Show information about every file structure in the system. .\" .Pp .It Ic show Cm freepages Show the number of physical pages in each of the free lists. .\" .Pp .It Ic show Cm geom Op Ar addr If the .Ar addr argument is not given, displays the entire GEOM topology. If .Ar addr is given, displays details about the given GEOM object (class, geom, provider or consumer). .\" .Pp .It Ic show Cm idt Show IDT layout. The first column specifies the IDT vector. The second one is the name of the interrupt/trap handler. Those functions are machine dependent. .\" .Pp .It Ic show Cm igi_list Ar addr Show information about the IGMP structure .Vt struct igmp_ifsoftc present at .Ar addr . .\" .Pp .It Ic show Cm inodedeps Op Ar addr Show brief information about each inodedep structure. If .Ar addr is given, only inodedeps belonging to the fs located at the supplied address are shown. .\" .Pp .It Ic show Cm inpcb Ar addr Show information on IP Control Block .Vt struct in_pcb present at .Ar addr . .\" .Pp .It Ic show Cm intr Dump information about interrupt handlers. .\" .Pp .It Ic show Cm intrcnt Dump the interrupt statistics. .\" .Pp .It Ic show Cm irqs Show interrupt lines and their respective kernel threads. .\" .Pp .It Ic show Cm jails Show the list of .Xr jail 8 instances. In addition to what .Xr jls 8 shows, also list kernel internal details. .\" .Pp .It Ic show Cm lapic Show information from the local APIC registers for this CPU. .\" .Pp .It Ic show Cm lock Ar addr Show lock structure. The output format is as follows: .Bl -tag -width "flags" .It Ic class: Class of the lock. Possible types include .Xr mutex 9 , .Xr rmlock 9 , .Xr rwlock 9 , .Xr sx 9 . .It Ic name: Name of the lock. .It Ic flags: Flags passed to the lock initialization function. .Em flags values are lock class specific. .It Ic state: Current state of a lock. .Em state values are lock class specific. .It Ic owner: Lock owner. .El .\" .Pp .It Ic show Cm lockchain Ar addr Show all threads a particular thread at address .Ar addr is waiting on based on non-spin locks. .\" .Pp .It Ic show Cm lockedbufs Show the same information as "show buf", but for every locked .Vt struct buf object. .\" .Pp .It Ic show Cm lockedvnods List all locked vnodes in the system. .\" .Pp .It Ic show Cm locks Prints all locks that are currently acquired. This command is only available if .Xr witness 4 is included in the kernel. .\" .Pp .It Ic show Cm locktree .\" .Pp .It Ic show Cm malloc Ns Op Li / Ns Cm i Prints .Xr malloc 9 memory allocator statistics. If the .Cm i modifier is specified, format output as machine-parseable comma-separated values ("CSV"). The output columns are as follows: .Pp .Bl -tag -compact -offset indent -width "Requests" .It Ic Type Specifies a type of memory. It is the same as a description string used while defining the given memory type with .Xr MALLOC_DECLARE 9 . .It Ic InUse Number of memory allocations of the given type, for which .Xr free 9 has not been called yet. .It Ic MemUse Total memory consumed by the given allocation type. .It Ic Requests Number of memory allocation requests for the given memory type. .El .Pp The same information can be gathered in userspace with .Dq Nm vmstat Fl m . .\" .Pp .It Ic show Cm map Ns Oo Li / Ns Cm f Oc Ar addr Prints the VM map at .Ar addr . If the .Cm f modifier is specified the complete map is printed. .\" .Pp .It Ic show Cm msgbuf Print the system's message buffer. It is the same output as in the .Dq Nm dmesg case. It is useful if you got a kernel panic, attached a serial cable to the machine and want to get the boot messages from before the system hang. .\" .It Ic show Cm mount Displays short info about all currently mounted file systems. .Pp .It Ic show Cm mount Ar addr Displays details about the given mount point. .\" .Pp .It Ic show Cm object Ns Oo Li / Ns Cm f Oc Ar addr Prints the VM object at .Ar addr . If the .Cm f option is specified the complete object is printed. .\" .Pp .It Ic show Cm panic Print the panic message if set. .\" .Pp .It Ic show Cm page Show statistics on VM pages. .\" .Pp .It Ic show Cm pageq Show statistics on VM page queues. .\" .Pp .It Ic show Cm pciregs Print PCI bus registers. The same information can be gathered in userspace by running .Dq Nm pciconf Fl lv . .\" .Pp .It Ic show Cm pcpu Print current processor state. The output format is as follows: .Pp .Bl -tag -compact -offset indent -width "spin locks held:" .It Ic cpuid Processor identifier. .It Ic curthread Thread pointer, process identifier and the name of the process. .It Ic curpcb Control block pointer. .It Ic fpcurthread FPU thread pointer. .It Ic idlethread Idle thread pointer. .It Ic APIC ID CPU identifier coming from APIC. .It Ic currentldt LDT pointer. .It Ic spin locks held Names of spin locks held. .El .\" .Pp .It Ic show Cm pgrpdump Dump process groups present within the system. .\" .Pp .It Ic show Cm proc Op Ar addr If no .Op Ar addr is specified, print information about the current process. Otherwise, show information about the process at address .Ar addr . .\" .Pp .It Ic show Cm procvm Show process virtual memory layout. .\" .Pp .It Ic show Cm protosw Ar addr Print protocol switch structure .Vt struct protosw at address .Ar addr . .\" .Pp .It Ic show Cm registers Ns Op Li / Ns Cm u Display the register set. If the .Cm u modifier is specified, the register contents of the thread's previous trapframe are displayed instead. Usually, this corresponds to the saved state from userspace. -.Pp .\" .Pp .It Ic show Cm rman Ar addr Show resource manager object .Vt struct rman at address .Ar addr . Addresses of particular pointers can be gathered with "show allrman" command. .\" .Pp .It Ic show Cm route Ar addr Show route table result for destination .Ar addr . At this time, INET and INET6 formatted addresses are supported. .\" .Pp .It Ic show Cm routetable Oo Ar af Oc Show full route table or tables. If .Ar af is specified, show only routes for the given numeric address family. If no argument is specified, dump the route table for all address families. .\" .Pp .It Ic show Cm rtc Show real time clock value. Useful for long debugging sessions. .\" .Pp .It Ic show Cm sleepchain Deprecated. Now an alias for .Ic show Cm lockchain . .\" .Pp .It Ic show Cm sleepq .It Ic show Cm sleepqueue Both commands provide the same functionality. They show sleepqueue .Vt struct sleepqueue structure. Sleepqueues are used within the .Fx kernel to implement sleepable synchronization primitives (thread holding a lock might sleep or be context switched), which at the time of writing are: .Xr condvar 9 , .Xr sx 9 and standard .Xr msleep 9 interface. .\" .Pp .It Ic show Cm sockbuf Ar addr .It Ic show Cm socket Ar addr Those commands print .Vt struct sockbuf and .Vt struct socket objects placed at .Ar addr . Output consists of all values present in structures mentioned. For exact interpretation and more details, visit .Pa sys/socket.h header file. .\" .Pp .It Ic show Cm sysregs Show system registers (e.g., .Li cr0-4 on i386.) Not present on some platforms. .\" .Pp .It Ic show Cm tcpcb Ar addr Print TCP control block .Vt struct tcpcb lying at address .Ar addr . For exact interpretation of output, visit .Pa netinet/tcp.h header file. .\" .Pp .It Ic show Cm thread Op Ar addr | tid If no .Ar addr or .Ar tid is specified, show detailed information about current thread. Otherwise, print information about the thread with ID .Ar tid or kernel address .Ar addr . (If the argument is a decimal number, it is assumed to be a tid.) .\" .Pp .It Ic show Cm threads Show all threads within the system. Output format is as follows: .Pp .Bl -tag -compact -offset indent -width "Second column" .It Ic First column Thread identifier (TID) .It Ic Second column Thread structure address .It Ic Third column Backtrace. .El .\" .Pp .It Ic show Cm tty Ar addr Display the contents of a TTY structure in a readable form. .\" .Pp .It Ic show Cm turnstile Ar addr Show turnstile .Vt struct turnstile structure at address .Ar addr . Turnstiles are structures used within the .Fx kernel to implement synchronization primitives which, while holding a specific type of lock, cannot sleep or context switch to another thread. Currently, those are: .Xr mutex 9 , .Xr rwlock 9 , .Xr rmlock 9 . .\" .Pp .It Ic show Cm uma Ns Op Li / Ns Cm i Show UMA allocator statistics. If the .Cm i modifier is specified, format output as machine-parseable comma-separated values ("CSV"). The output contains the following columns: .Pp .Bl -tag -compact -offset indent -width "Total Mem" .It Cm "Zone" Name of the UMA zone. The same string that was passed to .Xr uma_zcreate 9 as a first argument. .It Cm "Size" Size of a given memory object (slab). .It Cm "Used" Number of slabs being currently used. .It Cm "Free" Number of free slabs within the UMA zone. .It Cm "Requests" Number of allocations requests to the given zone. .It Cm "Total Mem" Total memory in use (either allocated or free) by a zone, in bytes. .It Cm "XFree" Number of free slabs within the UMA zone that were freed on a different NUMA domain than allocated. (The count in the .Cm "Free" column is inclusive of .Cm "XFree" . ) .El .Pp The same information might be gathered in the userspace with the help of .Dq Nm vmstat Fl z . .\" .Pp .It Ic show Cm unpcb Ar addr Shows UNIX domain socket private control block .Vt struct unpcb present at the address .Ar addr . .\" .Pp .It Ic show Cm vmochk Prints, whether the internal VM objects are in a map somewhere and none have zero ref counts. .\" .Pp .It Ic show Cm vmopag This is supposed to show physical addresses consumed by a VM object. Currently, it is not possible to use this command when .Xr witness 4 is compiled in the kernel. .\" .Pp .It Ic show Cm vnet Ar addr Prints virtualized network stack .Vt struct vnet structure present at the address .Ar addr . .\" .Pp .It Ic show Cm vnode Op Ar addr Prints vnode .Vt struct vnode structure lying at .Op Ar addr . For the exact interpretation of the output, look at the .Pa sys/vnode.h header file. .\" .Pp .It Ic show Cm vnodebufs Ar addr Shows clean/dirty buffer lists of the vnode located at .Ar addr . .\" .Pp .It Ic show Cm vpath Ar addr Walk the namecache to lookup the pathname of the vnode located at .Ar addr . .\" .Pp .It Ic show Cm watches Displays all watchpoints. Shows watchpoints set with "watch" command. .\" .Pp .It Ic show Cm witness Shows information about lock acquisition coming from the .Xr witness 4 subsystem. .El -.Pp .Ss OFFLINE DEBUGGING COMMANDS .Bl -tag -width indent -compact .It Ic gdb Switches to remote GDB mode. In remote GDB mode, another machine is required that runs .Xr gdb 1 using the remote debug feature, with a connection to the serial console port on the target machine. .Pp .It Ic netdump Fl s Ar server Oo Fl g Ar gateway Fl c Ar client Fl i Ar iface Oc Configure .Xr netdump 4 with the provided parameters, and immediately perform a netdump. .Pp There are some known limitations. Principally, .Xr netdump 4 only supports IPv4 at this time. The address arguments to the .Ic netdump command must be dotted decimal IPv4 addresses. (Hostnames are not supported.) At present, the command only works if the machine is in a panic state. Finally, the .Nm .Ic netdump command does not provide any way to configure compression or encryption. .Pp .It Ic netgdb Fl s Ar server Oo Fl g Ar gateway Fl c Ar client Fl i Ar iface Oc Initiate a .Xr netgdb 4 session with the provided parameters. .Pp .Ic netgdb has identical limitations to .Ic netdump . .Pp .It Ic capture on .It Ic capture off .It Ic capture reset .It Ic capture status .Nm supports a basic output capture facility, which can be used to retrieve the results of debugging commands from userspace using .Xr sysctl 3 . .Ic capture on enables output capture; .Ic capture off disables capture. .Ic capture reset will clear the capture buffer and disable capture. .Ic capture status will report current buffer use, buffer size, and disposition of output capture. .Pp Userspace processes may inspect and manage .Nm capture state using .Xr sysctl 8 : .Pp .Va debug.ddb.capture.bufsize may be used to query or set the current capture buffer size. .Pp .Va debug.ddb.capture.maxbufsize may be used to query the compile-time limit on the capture buffer size. .Pp .Va debug.ddb.capture.bytes may be used to query the number of bytes of output currently in the capture buffer. .Pp .Va debug.ddb.capture.data returns the contents of the buffer as a string to an appropriately privileged process. .Pp This facility is particularly useful in concert with the scripting and .Xr textdump 4 facilities, allowing scripted debugging output to be captured and committed to disk as part of a textdump for later analysis. The contents of the capture buffer may also be inspected in a kernel core dump using .Xr kgdb 1 . .Pp .It Ic run .It Ic script .It Ic scripts .It Ic unscript Run, define, list, and delete scripts. See the .Sx SCRIPTING section for more information on the scripting facility. .Pp .It Ic textdump dump .It Ic textdump set .It Ic textdump status .It Ic textdump unset Use the .Ic textdump dump command to immediately perform a textdump. More information may be found in .Xr textdump 4 . The .Ic textdump set command may be used to force the next kernel core dump to be a textdump rather than a traditional memory dump or minidump. .Ic textdump status reports whether a textdump has been scheduled. .Ic textdump unset cancels a request to perform a textdump as the next kernel core dump. .El .Sh VARIABLES The debugger accesses registers and variables as .Li $ Ns Ar name . Register names are as in the .Dq Ic show Cm registers command. Some variables are suffixed with numbers, and may have some modifier following a colon immediately after the variable name. For example, register variables can have a .Cm u modifier to indicate user register (e.g., .Dq Li $eax:u ) . .Pp Built-in variables currently supported are: .Pp .Bl -tag -width ".Va tabstops" -compact .It Va radix Input and output radix. .It Va maxoff Addresses are printed as .Dq Ar symbol Ns Li + Ns Ar offset unless .Ar offset is greater than .Va maxoff . .It Va maxwidth The width of the displayed line. .It Va lines The number of lines. It is used by the built-in pager. Setting it to 0 disables paging. .It Va tabstops Tab stop width. .It Va work Ns Ar xx Work variable; .Ar xx can take values from 0 to 31. .El .Sh EXPRESSIONS Most expression operators in C are supported except .Ql ~ , .Ql ^ , and unary .Ql & . Special rules in .Nm are: .Bl -tag -width ".No Identifiers" .It Identifiers The name of a symbol is translated to the value of the symbol, which is the address of the corresponding object. .Ql \&. and .Ql \&: can be used in the identifier. If supported by an object format dependent routine, .Sm off .Oo Ar filename : Oc Ar func : lineno , .Sm on .Oo Ar filename : Oc Ns Ar variable , and .Oo Ar filename : Oc Ns Ar lineno can be accepted as a symbol. .It Numbers Radix is determined by the first two letters: .Ql 0x : hex, .Ql 0o : octal, .Ql 0t : decimal; otherwise, follow current radix. .It Li \&. .Va dot .It Li + .Va next .It Li .. address of the start of the last line examined. Unlike .Va dot or .Va next , this is only changed by .Ic examine or .Ic write command. .It Li ' last address explicitly specified. .It Li $ Ns Ar variable Translated to the value of the specified variable. It may be followed by a .Ql \&: and modifiers as described above. .It Ar a Ns Li # Ns Ar b A binary operator which rounds up the left hand side to the next multiple of right hand side. .It Li * Ns Ar expr Indirection. It may be followed by a .Ql \&: and modifiers as described above. .El .Sh SCRIPTING .Nm supports a basic scripting facility to allow automating tasks or responses to specific events. Each script consists of a list of DDB commands to be executed sequentially, and is assigned a unique name. Certain script names have special meaning, and will be automatically run on various .Nm events if scripts by those names have been defined. .Pp The .Ic script command may be used to define a script by name. Scripts consist of a series of .Nm commands separated with the .Ql \&; character. For example: .Bd -literal -offset indent script kdb.enter.panic=bt; show pcpu script lockinfo=show alllocks; show lockedvnods .Ed .Pp The .Ic scripts command lists currently defined scripts. .Pp The .Ic run command execute a script by name. For example: .Bd -literal -offset indent run lockinfo .Ed .Pp The .Ic unscript command may be used to delete a script by name. For example: .Bd -literal -offset indent unscript kdb.enter.panic .Ed .Pp These functions may also be performed from userspace using the .Xr ddb 8 command. .Pp Certain scripts are run automatically, if defined, for specific .Nm events. The follow scripts are run when various events occur: .Bl -tag -width kdb.enter.powerfail .It Va kdb.enter.acpi The kernel debugger was entered as a result of an .Xr acpi 4 event. .It Va kdb.enter.bootflags The kernel debugger was entered at boot as a result of the debugger boot flag being set. .It Va kdb.enter.break The kernel debugger was entered as a result of a serial or console break. .It Va kdb.enter.cam The kernel debugger was entered as a result of a .Xr CAM 4 event. .It Va kdb.enter.mac The kernel debugger was entered as a result of an assertion failure in the .Xr mac_test 4 module of the TrustedBSD MAC Framework. .It Va kdb.enter.netgraph The kernel debugger was entered as a result of a .Xr netgraph 4 event. .It Va kdb.enter.panic .Xr panic 9 was called. .It Va kdb.enter.powerpc The kernel debugger was entered as a result of an unimplemented interrupt type on the powerpc platform. .It Va kdb.enter.sysctl The kernel debugger was entered as a result of the .Va debug.kdb.enter sysctl being set. .It Va kdb.enter.unionfs The kernel debugger was entered as a result of an assertion failure in the union file system. .It Va kdb.enter.unknown The kernel debugger was entered, but no reason has been set. .It Va kdb.enter.vfslock The kernel debugger was entered as a result of a VFS lock violation. .It Va kdb.enter.watchdog The kernel debugger was entered as a result of a watchdog firing. .It Va kdb.enter.witness The kernel debugger was entered as a result of a .Xr witness 4 violation. .El .Pp In the event that none of these scripts is found, .Nm will attempt to execute a default script: .Bl -tag -width kdb.enter.powerfail .It Va kdb.enter.default The kernel debugger was entered, but a script exactly matching the reason for entering was not defined. This can be used as a catch-all to handle cases not specifically of interest; for example, .Va kdb.enter.witness might be defined to have special handling, and .Va kdb.enter.default might be defined to simply panic and reboot. .El .Sh HINTS On machines with an ISA expansion bus, a simple NMI generation card can be constructed by connecting a push button between the A01 and B01 (CHCHK# and GND) card fingers. Momentarily shorting these two fingers together may cause the bridge chipset to generate an NMI, which causes the kernel to pass control to .Nm . Some bridge chipsets do not generate a NMI on CHCHK#, so your mileage may vary. The NMI allows one to break into the debugger on a wedged machine to diagnose problems. Other bus' bridge chipsets may be able to generate NMI using bus specific methods. There are many PCI and PCIe add-in cards which can generate NMI for debugging. Modern server systems typically use IPMI to generate signals to enter the debugger. The .Va devel/ipmitool port can be used to send the .Cd chassis power diag command which delivers an NMI to the processor. Embedded systems often use JTAG for debugging, but rarely use it in combination with .Nm . .Pp Serial consoles can break to the debugger by sending a BREAK condition on the serial line. This requires a kernel built with .Cd options BREAK_TO_DEBUGGER is specified in the kernel. Most terminal emulation programs can send a break sequence with a special key sequence or menu selection. Sending the break can be difficult or even happen spuriously in some setups. An alternative method is to build a kernel with .Cd options ALT_BREAK_TO_DEBUGGER then the sequence of CR TILDE CTRL-B enters the debugger; CR TILDE CTRL-P causes a panic; and CR TILDE CTRL-R causes an immediate reboot. In all these sequences, CR represents Carriage Return and is usually sent by pressing the Enter or Return key. TILDE is the ASCII tilde character (~). CTRL-x is Control x, send by pressing the Control key, then x, then releasing both. and then releasing both. .Pp The break-to-debugger behavior can be enabled by setting .Xr sysctl 8 .Va debug.kdb.break_to_debugger to 1. The alt-break-to-debugger behavior can be enabled by setting .Xr sysctl 8 .Va debug.kdb.alt_break_to_debugger to 1. The debugger can be entered by setting .Xr sysctl 8 .Va debug.kdb.enter to 1. .Pp Output can be interrupted, paused, and resumed with the control characters CTRL-C, CTRL-S, and CTRL-Q. Because these control characters are received as in-band data from the console, there is an input buffer, and once that buffer fills .Nm must either stop responding to control characters or drop additional input while continuing to search for control characters. This behavior is controlled by the tunable .Xr sysctl 8 .Va debug.ddb.prioritize_control_input , which defaults to 1. The input buffer size is 512 bytes. .Sh FILES Header files mentioned in this manual page can be found below .Pa /usr/include directory. .Pp .Bl -dash -compact .It .Pa sys/buf.h .It .Pa sys/domain.h .It .Pa netinet/in_pcb.h .It .Pa sys/socket.h .It .Pa sys/vnode.h .El .Sh SEE ALSO .Xr gdb 1 , .Xr kgdb 1 , .Xr acpi 4 , .Xr CAM 4 , .Xr mac_test 4 , .Xr netgraph 4 , .Xr textdump 4 , .Xr witness 4 , .Xr ddb 8 , .Xr sysctl 8 , .Xr panic 9 .Sh HISTORY The .Nm debugger was developed for Mach, and ported to .Bx 386 0.1 . This manual page translated from .Xr man 7 macros by .An Garrett Wollman . .Pp .An Robert N. M. Watson added support for .Nm output capture, .Xr textdump 4 and scripting in .Fx 7.1 . diff --git a/share/man/man4/dtrace_audit.4 b/share/man/man4/dtrace_audit.4 index 94f7cdad1f1d..5869eb97f99a 100644 --- a/share/man/man4/dtrace_audit.4 +++ b/share/man/man4/dtrace_audit.4 @@ -1,178 +1,176 @@ .\"- .\" SPDX-License-Identifier: BSD-2-Clause .\" .\" Copyright (c) 2019 Robert N. M. Watson .\" .\" This software was developed by BAE Systems, the University of Cambridge .\" Computer Laboratory, and Memorial University under DARPA/AFRL contract .\" FA8650-15-C-7558 ("CADETS"), as part of the DARPA Transparent Computing .\" (TC) research program. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd April 28, 2019 .Dt DTRACE_AUDIT 4 .Os .Sh NAME .Nm dtrace_audit .Nd A DTrace provider for tracing .Xr audit 4 events .Sh SYNOPSIS -.Pp .Fn audit:event:aue_*:commit "char *eventname" "struct audit_record *ar" .Fn audit:event:aue_*:bsm "char *eventname" "struct audit_record *ar" "const void *" "size_t" .Pp To compile this module into the kernel, place the following in your kernel configuration file: -.Pp .Bd -literal -offset indent .Cd "options DTAUDIT" .Ed .Pp Alternatively, to load the module at boot time, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent dtaudit_load="YES" .Ed .Sh DESCRIPTION The DTrace .Nm dtaudit provider allows users to trace events in the kernel security auditing subsystem, .Xr audit 4 . .Xr audit 4 provides detailed logging of a configurable set of security-relevant system calls, including key arguments (such as file paths) and return values that are copied race-free as the system call proceeds. The .Nm dtaudit provider allows DTrace scripts to selectively enable in-kernel audit-record capture for system calls, and then access those records in either the in-kernel format or BSM format (\c .Xr audit.log 5 ) when the system call completes. While the in-kernel audit record data structure is subject to change as the kernel changes over time, it is a much more friendly interface for use in D scripts than either those available via the DTrace system-call provider or the BSM trail itself. .Ss Configuration The .Nm dtaudit provider relies on .Xr audit 4 being compiled into the kernel. .Nm dtaudit probes become available only once there is an event-to-name mapping installed in the kernel, normally done by .Xr auditd 8 during the boot process, if audit is enabled in .Xr rc.conf 5 : .Bd -literal -offset indent auditd_enable="YES" .Ed .Pp If .Nm dtaudit probes are required earlier in boot -- for example, in single-user mode -- or without enabling .Xr audit 4 , they can be preloaded in the boot loader by adding this line to .Xr loader.conf 5 . .Bd -literal -offset indent audit_event_load="YES" .Ed .Ss Probes The .Fn audit:event:aue_*:commit probes fire synchronously during system-call return, giving access to two arguments: a .Vt char * audit event name, and the .Vt struct audit_record * in-kernel audit record. Because the probe fires in system-call return, the user thread has not yet regained control, and additional information from the thread and process remains available for capture by the script. .Pp The .Fn audit:event:aue_*:bsm probes fire asynchronously from system-call return, following BSM conversion and just prior to being written to disk, giving access to four arguments: a .Vt char * audit event name, the .Vt struct audit_record * in-kernel audit record, a .Vt const void * pointer to the converted BSM record, and a .Vt size_t for the length of the BSM record. .Sh IMPLEMENTATION NOTES When a set of .Nm dtaudit probes are registered, corresponding in-kernel audit records will be captured and their probes will fire regardless of whether the .Xr audit 4 subsystem itself would have captured the record for the purposes of writing it to the audit trail, or for delivery to a .Xr auditpipe 4 . In-kernel audit records allocated only because of enabled .Xr dtaudit 4 probes will not be unnecessarily written to the audit trail or enabled pipes. .Sh SEE ALSO .Xr dtrace 1 , .Xr audit 4 , .Xr audit.log 5 , .Xr loader.conf 5 , .Xr rc.conf 5 , .Xr auditd 8 .Sh HISTORY The .Nm dtaudit provider first appeared in .Fx 12.0 . .Sh AUTHORS This software and this manual page were developed by BAE Systems, the University of Cambridge Computer Laboratory, and Memorial University under DARPA/AFRL contract .Pq FA8650-15-C-7558 .Pq Do CADETS Dc , as part of the DARPA Transparent Computing (TC) research program. The .Nm dtaudit provider and this manual page were written by .An Robert Watson Aq Mt rwatson@FreeBSD.org . .Sh BUGS Because .Xr audit 4 maintains its primary event-to-name mapping database in userspace, that database must be loaded into the kernel before .Nm dtaudit probes become available. .Pp .Nm dtaudit is only able to provide access to system-call audit events, not the full scope of userspace events, such as those relating to login, password change, and so on. diff --git a/share/man/man4/hidraw.4 b/share/man/man4/hidraw.4 index 7012089e354b..c01b961e738d 100644 --- a/share/man/man4/hidraw.4 +++ b/share/man/man4/hidraw.4 @@ -1,308 +1,309 @@ .\" $NetBSD: uhid.4,v 1.13 2001/12/29 14:41:59 augustss Exp $ .\" .\" Copyright (c) 1999, 2001 The NetBSD Foundation, Inc. .\" All rights reserved. .\" .\" This code is derived from software contributed to The NetBSD Foundation .\" by Lennart Augustsson. .\" .\" 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. .\" .\" $FreeBSD$ .\" .Dd July 1, 2018 .Dt HIDRAW 4 .Os .Sh NAME .Nm hidraw .Nd Raw Access to HID devices .Sh SYNOPSIS To compile this driver into the kernel, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "device hidraw" .Cd "device hid" .Cd "device hidbus" .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 hidraw_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides a raw interface to Human Interface Devices (HIDs). The reports are sent to and received from the device unmodified. .Pp The device handles 2 sets of .Xr ioctl 2 calls: .Pp .Fx .Xr uhid 4 \-compatible calls: .Bl -tag -width indent .It Dv HID_GET_REPORT_ID Pq Vt int Get the report identifier used by this HID report. .It Dv HID_GET_REPORT_DESC Pq Vt "struct hidraw_gen_descriptor" Get the HID report descriptor. Copies a maximum of .Va hgd_maxlen bytes of the report descriptor data into the memory specified by .Va hgd_data . Upon return .Va hgd_actlen is set to the number of bytes copied. Using this descriptor the exact layout and meaning of data to/from the device can be found. The report descriptor is delivered without any processing. .Bd -literal struct hidraw_gen_descriptor { void *hgd_data; uint16_t hgd_maxlen; uint16_t hgd_actlen; uint8_t hgd_report_type; ... }; .Ed .It Dv HID_SET_IMMED Pq Vt int Sets the device in a mode where each .Xr read 2 will return the current value of the input report. Normally a .Xr read 2 will only return the data that the device reports on its interrupt pipe. This call may fail if the device does not support this feature. .It Dv HID_GET_REPORT Pq Vt "struct hidraw_gen_descriptor" Get a report from the device without waiting for data on the interrupt pipe. Copies a maximum of .Va hgd_maxlen bytes of the report data into the memory specified by .Va hgd_data . Upon return .Va hgd_actlen is set to the number of bytes copied. The .Va hgd_report_type field indicates which report is requested. It should be .Dv HID_INPUT_REPORT , .Dv HID_OUTPUT_REPORT , or .Dv HID_FEATURE_REPORT . On a device which uses numbered reports, the first byte of the returned data is the report number. The report data begins from the second byte. For devices which do not use numbered reports, the report data begins at the first byte. This call may fail if the device does not support this feature. .It Dv HID_SET_REPORT Pq Vt "struct hidraw_gen_descriptor" Set a report in the device. The .Va hgd_report_type field indicates which report is to be set. It should be .Dv HID_INPUT_REPORT , .Dv HID_OUTPUT_REPORT , or .Dv HID_FEATURE_REPORT . The value of the report is specified by the .Va hgd_data and the .Va hgd_maxlen fields. On a device which uses numbered reports, the first byte of data to be sent is the report number. The report data begins from the second byte. For devices which do not use numbered reports, the report data begins at the first byte. This call may fail if the device does not support this feature. .El .Pp Linux .Nm \-compatible calls: .Bl -tag -width indent .It Dv HIDIOCGRDESCSIZE Pq Vt int Get the HID report descriptor size. Returns the size of the device report descriptor to use with .Dv HIDIOCGRDESC .Xr ioctl 2 . .It Dv HIDIOCGRDESC Pq Vt "struct hidraw_report_descriptor" Get the HID report descriptor. Copies a maximum of .Va size bytes of the report descriptor data into the memory specified by .Va value . .Bd -literal struct hidraw_report_descriptor { uint32_t size; uint8_t value[HID_MAX_DESCRIPTOR_SIZE]; }; .Ed .It Dv HIDIOCGRAWINFO Pq Vt "struct hidraw_devinfo" Get structure containing the bus type, the vendor ID (VID), and product ID -(PID) of the device. The bus type can be one of: +(PID) of the device. +The bus type can be one of: .Dv BUS_USB or .Dv BUS_I2C which are defined in dev/evdev/input.h. .Bd -literal struct hidraw_devinfo { uint32_t bustype; int16_t vendor; int16_t product; }; .Ed .It Dv HIDIOCGRAWNAME(len) Pq Vt "char[] buf" Get device description. Copies a maximum of .Va len bytes of the device description previously set with .Xr device_set_desc 9 procedure into the memory specified by .Va buf . .It Dv HIDIOCGRAWPHYS(len) Pq Vt "char[] buf" Get the newbus path to the device. .\For Bluetooth devices, it returns the hardware (MAC) address of the device. Copies a maximum of .Va len bytes of the newbus device path into the memory specified by .Va buf . .It Dv HIDIOCGFEATURE(len) Pq Vt "void[] buf" Get a feature report from the device. Copies a maximum of .Va len bytes of the feature report data into the memory specified by .Va buf . The first byte of the supplied buffer should be set to the report number of the requested report. For devices which do not use numbered reports, set the first byte to 0. The report will be returned starting at the first byte of the buffer (ie: the report number is not returned). This call may fail if the device does not support this feature. .It Dv HIDIOCSFEATURE(len) Pq Vt "void[] buf" Set a feature Report in the device. The value of the report is specified by the .Va buf and the .Va len parameters. Set the first byte of the supplied buffer to the report number. For devices which do not use numbered reports, set the first byte to 0. The report data begins in the second byte. Make sure to set len accordingly, to one more than the length of the report (to account for the report number). This call may fail if the device does not support this feature. .El .Pp Use .Xr read 2 to get data from the device. Data should be read in chunks of the size prescribed by the report descriptor. On a device which uses numbered reports, the first byte of the returned data is the report number. The report data begins from the second byte. For devices which do not use numbered reports, the report data begins at the first byte. .Pp Use .Xr write 2 to send data to the device. Data should be written in chunks of the size prescribed by the report descriptor. The first byte of the buffer passed to .Xr write 2 should be set to the report number. If the device does not use numbered reports, there are 2 operation modes: .Nm mode and .Xr uhid 4 mode. In the .Nm mode, the first byte should be set to 0 and the report data itself should begin at the second byte. In the .Xr uhid 4 mode, the report data should begin at the first byte. The modes can be switched with issuing one of .Dv HIDIOCGRDESC or .Dv HID_GET_REPORT_DESC .Xr ioctl 2 accordingly. Default mode is .Nm . .Sh SYSCTL VARIABLES The following variables are available as both .Xr sysctl 8 variables and .Xr loader 8 tunables: .Bl -tag -width indent .It Va hw.hid.hidraw.debug Debug output level, where 0 is debugging disabled and larger values increase debug message verbosity. Default is 0. .El .Sh FILES .Bl -tag -width ".Pa /dev/hidraw?" .It Pa /dev/hidraw? .El .Sh SEE ALSO .Xr usbhidctl 1 , .Xr hid 4 , .Xr hidbus 4 , .Xr uhid 4 .Sh HISTORY The .Xr uhid 4 driver appeared in .Nx 1.4 . .Nm protocol support was added in .Fx 13 by .An Vladimir Kondratyev Aq Mt wulf@FreeBSD.org . This manual page was adopted from .Nx by .An Tom Rhodes Aq Mt trhodes@FreeBSD.org in April 2002. diff --git a/share/man/man4/igc.4 b/share/man/man4/igc.4 index db88aa4ca725..9c80b3e1c4d3 100644 --- a/share/man/man4/igc.4 +++ b/share/man/man4/igc.4 @@ -1,167 +1,166 @@ .\"- .\" Copyright 2021 Intel Corp .\" Copyright 2021 Rubicon Communications, LLC (Netgate) .\" SPDX-License-Identifier: BSD-3-Clause .\" .\" $FreeBSD$ .\" .Dd May 10, 2021 .Dt IGC 4 .Os .Sh NAME .Nm igc .Nd "Intel Ethernet Controller I225 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 iflib" .Cd "device igc" .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_igc_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for any PCI Express adapter or LOM (LAN On Motherboard) based on the Intel I225 Multi Gigabit Controller. The driver supports Transmit/Receive checksum offload, Jumbo Frames, MSI/MSI-X, TSO, and RSS. .Pp Support for Jumbo Frames is provided via the interface MTU setting. Selecting an MTU larger than 1500 bytes with the .Xr ifconfig 8 utility configures the adapter to receive and transmit Jumbo Frames. The maximum MTU size for Jumbo Frames is 9216 bytes. .Pp This driver version supports VLAN hardware insertion / extraction, and VLAN checksum offload. For information on enabling VLANs, see .Xr ifconfig 8 . The .Nm driver supports the following media types: .Bl -tag -width ".Cm 10baseT/UTP" .It Cm autoselect Enables auto-negotiation for speed and duplex. .It Cm 10baseT/UTP Sets 10Mbps operation. Use the .Cm mediaopt option to select .Cm half-duplex mode. .It Cm 100baseTX Sets 100Mbps operation. Use the .Cm mediaopt option to select .Cm half-duplex mode. .It Cm 1000baseT Sets 1000Mbps operation. Only .Cm full-duplex mode is supported at this speed. .It Cm 2500baseT Sets 2500Mbps operation. Only .Cm full-duplex mode is supported at this speed. .El -.Pp .Sh HARDWARE The .Nm driver supports the following models: .Pp .Bl -bullet -compact .It I225-LM .It I225-V .It I225-IT .It I225-K .El .Sh LOADER TUNABLES Tunables can be set at the .Xr loader 8 prompt before booting the kernel or stored in .Xr loader.conf 5 . .Bl -tag -width indent .It Va hw.igc.igc_disable_crc_stripping Disable or enable hardware stripping of CRC field. This is mostly useful on BMC/IPMI shared interfaces where stripping the CRC causes remote access over IPMI to fail. Default 0 (enabled). .It Va hw.igc.rx_int_delay This value delays the generation of receive interrupts in units of 1.024 microseconds. The default value is 0, since adapters may hang with this feature being enabled. .It Va hw.igc.rx_abs_int_delay If hw.igc.rx_int_delay is non-zero, this tunable limits the maximum delay in which a receive interrupt is generated. .It Va hw.igc.tx_int_delay This value delays the generation of transmit interrupts in units of 1.024 microseconds. The default value is 64. .It Va hw.igc.tx_abs_int_delay If hw.igc.tx_int_delay is non-zero, this tunable limits the maximum delay in which a transmit interrupt is generated. .It Va hw.igc.sbp Show bad packets when in promiscuous mode. Default is false. .It Va hw.igc.rx_process_limit Maximum number of received packets to process at a time. Default is 100. A value of -1 means unlimited. .It Va hw.igc.eee_setting Disable or enable Energy Efficient Ethernet. Default 1 (disabled). .It Va hw.igc.max_interrupt_rate Maximum device interrupts per second. The default is 8000. .El .Sh DIAGNOSTICS .Bl -diag .It "igc%d: Hardware Initialization Failed" A fatal initialization error has occurred. .It "igc%d: Unable to allocate bus resource: memory" A fatal initialization error has occurred. .It "igc%d: Invalid MAC address" The MAC address programmed into the EEPROM is either empty or a multicast/broadcast address. .El .Sh SEE ALSO .Xr altq 4 , .Xr arp 4 , .Xr iflib 4 , .Xr netintro 4 , .Xr ng_ether 4 , .Xr vlan 4 , .Xr ifconfig 8 .Sh HISTORY The .Nm device driver first appeared in .Fx 14.0 . .Sh AUTHORS .An -nosplit The .Nm was originally written by .An Intel Corporation and converted to the .Xr iflib 4 framework by .An Netgate . diff --git a/share/man/man4/iic_gpiomux.4 b/share/man/man4/iic_gpiomux.4 index 16d15fbcfd3a..a6d59ff2d37c 100644 --- a/share/man/man4/iic_gpiomux.4 +++ b/share/man/man4/iic_gpiomux.4 @@ -1,88 +1,87 @@ .\"- .\" SPDX-License-Identifier: BSD-2-Clause .\" .\" 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 AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd January 1, 2020 .Dt IIC_GPIOMUX 4 .Os .Sh NAME .Nm iic_gpiomux .Nd driver for I2C mux hardware controlled via GPIO .Sh SYNOPSIS To compile this driver into the kernel, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "device iic_gpiomux" .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 iic_gpiomux_load="YES" .Ed .Sh DESCRIPTION The .Nm driver supports any type of I2C bus multiplexer (mux) hardware that is controlled by manipulating the state of one or more GPIO pins. It automatically connects an upstream I2C bus to one of the downstream buses as needed when slave devices on the downstream buses initiate I/O. More information on the automatic switching behavior is available in .Xr iicmux 4 . -.Pp .Sh FDT CONFIGURATION On an .Xr fdt 4 based system, an .Nm device node may be defined as a child node of any arbitrary bus in the FDT data. The .Va i2c-parent property indicates the connection to the upstream I2C bus. The children of the .Nm node are additional i2c buses, which will have their own i2c slave devices described in their child nodes. .Pp The .Nm driver conforms to the standard .Bk -words .Li i2c/i2c-mux-gpio.txt .Ek bindings document. .Sh SEE ALSO .Xr iicbus 4 , .Xr iicmux 4 , .Sh HISTORY The .Nm driver first appeared in .Fx 13.0 . diff --git a/share/man/man4/liquidio.4 b/share/man/man4/liquidio.4 index 2f9416a7026d..075b361605b9 100644 --- a/share/man/man4/liquidio.4 +++ b/share/man/man4/liquidio.4 @@ -1,134 +1,133 @@ .\" BSD LICENSE .\" .\" Copyright(c) 2017 Cavium, Inc.. All rights reserved. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" .\" * Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" * 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. .\" * Neither the name of Cavium, Inc. 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 .\" OWNER(S) OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE .\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" $FreeBSD$ .\" .Dd August 17, 2017 .Dt LIQUIDIO 4 .Os .Sh NAME .Nm liquidio .Nd "Cavium 10Gb/25Gb Ethernet driver for the FreeBSD operating system" .Sh SYNOPSIS To compile this driver into the kernel, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "device lio" .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_lio_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for 23XX 10Gb/25Gb Ethernet adapters. The driver supports Jumbo Frames, Transmit/Receive checksum offload, TCP segmentation offload (TSO), Large Receive Offload (LRO), VLAN tag insertion/extraction, VLAN checksum offload, VLAN TSO, and Receive Side Steering (RSS) .Pp Support for Jumbo Frames is provided via the interface MTU setting. Selecting an MTU larger than 1500 bytes with the .Xr ifconfig 8 utility configures the adapter to receive and transmit Jumbo Frames. The maximum MTU size for Jumbo Frames is 16000. .Pp For more information on configuring this device, see ifconfig(8). .Sh HARDWARE The .Nm driver supports the following cards: .Pp .Bl -bullet -compact .It LiquidIO II CN2350 210SV/225SV .It LiquidIO II CN2360 210SV/225SV .El .Sh LOADER TUNABLES Tunables can be set at the .Xr loader 8 prompt before booting the kernel or stored in .Xr loader.conf 5 . -.Pp .Bl -tag -width indent .It Va hw.lio.fw_type .Pp String that specifies type of firmware to be loaded. Default is "nic". Use "none" to load firmware from flash. .It Va hw.lio.num_queues_per_pf0 .Pp Unsigned integers that specify number of queues per PF0. Valid range is 0 to 64. Use 0 to derive autoconfigures based on the number of cpus with a max of 8 .It Va hw.lio.num_queues_per_pf1 .Pp Unsigned integers that specify number of queues per PF1. Valid range is 0 to 64. Use 0 to derive autoconfigures based on the number of cpus with a max of 8 .It Va hw.lio.console_bitmask .Pp Bitmask indicating which consoles have debug output redirected to syslog. .It Va hw.lio.rss .Pp To enable/disable driver RSS support .It Va hw.lio.hwlro .Pp To enable/disable hardware LRO .El .Sh SUPPORT For general information and support, go to the Cavium support website at: .Pa http://support.cavium.com . .Sh SEE ALSO .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 12.0 . .Sh AUTHORS The .Nm driver was written by .An Derek Chickles Aq Mt derek.chickles@cavium.com . diff --git a/share/man/man4/ltc430x.4 b/share/man/man4/ltc430x.4 index c6d843ed53c1..0eba67e40fad 100644 --- a/share/man/man4/ltc430x.4 +++ b/share/man/man4/ltc430x.4 @@ -1,145 +1,145 @@ .\"- .\" SPDX-License-Identifier: BSD-2-Clause .\" .\" 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 AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd September 2, 2020 .Dt LTC430X 4 .Os .Sh NAME .Nm ltc430x .Nd driver for LTC4305 and LTC4306 I2C mux chips .Sh SYNOPSIS To compile this driver into the kernel, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "device ltc430x" .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 ltc430x_load="YES" .Ed .Sh DESCRIPTION The .Nm driver supports the LTC4305 and LTC4306 I2C bus multiplexer (mux) chips. It automatically connects an upstream I2C bus to one of several downstream buses as needed when slave devices on the downstream buses initiate I/O. More information on the automatic switching behavior is available in .Xr iicmux 4 . .Sh FDT CONFIGURATION On an .Xr fdt 4 based system, an .Nm device node is defined as a child node of its upstream i2c bus. The children of the .Nm node are additional i2c buses, which will have their own i2c slave devices described in their child nodes. .Pp The .Nm driver conforms to the standard .Bk -words .Li i2c/i2c-mux-ltc4306.txt .Ek bindings document, except that the following optional properties are not currently supported and will be ignored if present: .Bl -bullet -compact -inset -offset indent .It enable-gpios .It gpio-controller .It #gpio-cells .It ltc,downstream-accelerators-enable .It ltc,upstream-accelerators-enable .El .Pp In addition, the following additional property is supported: .Bl -tag -offset indent -width indent .It Va freebsd,ctlreg2 A value to store into the chip's control register 2 during initialization. Consult the chip datasheet for the meaning of the various bits in the register. .El .Sh HINTS CONFIGURATION On a .Xr device.hints 5 based system, the following hints are required: .Bl -tag -offset indent -width indent .It Va hint.ltc430x..at The upstream .Xr iicbus 4 the .Nm instance is attached to. .It Va hint.ltc430x..addr The slave address of the .Nm instance on the upstream bus. .It Va hint.ltc430x..chip_type The type of chip the driver is controlling. Valid values are .Dq ltc4305 and .Dq ltc4306 . .El .Pp The following hints are optional: .Bl -tag -offset indent -width indent .It Va hint.ltc430x..ctlreg2 A value to store into the chip's control register 2 during initialization. Consult the chip datasheet for the meaning of the various bits in the register. This hint is optional; when missing, the driver does not update control register 2. .It Va hint.ltc430x..idle_disconnect Whether to disconnect all downstream busses from the upstream bus when idle. If set to zero, the most recently used downstream bus is left connected to the upstream bus after IO completes. Any non-zero value causes all downstream busses to be disconnected when idle. This hint is optional; when missing, the driver behaves as if it were zero. .El .Pp When configured via hints, the driver automatically adds an iicbus instance for every downstream bus supported by the chip. There is currently no way to indicate used versus unused downstream channels. .Sh SEE ALSO .Xr iicbus 4 , -.Xr iicmux 4 , +.Xr iicmux 4 .Sh HISTORY The .Nm driver first appeared in .Fx 13.0 . diff --git a/share/man/man4/mac_bsdextended.4 b/share/man/man4/mac_bsdextended.4 index ca0296226e82..f55e113aabb0 100644 --- a/share/man/man4/mac_bsdextended.4 +++ b/share/man/man4/mac_bsdextended.4 @@ -1,149 +1,148 @@ .\" Copyright (c) 2002 Networks Associates Technology, Inc. .\" All rights reserved. .\" .\" This software was developed for the FreeBSD Project by Chris Costello .\" at Safeport Network Services and Network Associates Laboratories, the .\" Security Research Division of Network Associates, Inc. under .\" DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the .\" DARPA CHATS research program. .\" .\" 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 AUTHORS 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 AUTHORS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd May 21, 2005 .Dt MAC_BSDEXTENDED 4 .Os .Sh NAME .Nm mac_bsdextended .Nd "file system firewall policy" .Sh SYNOPSIS To compile the file system firewall policy into your kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "options MAC" .Cd "options MAC_BSDEXTENDED" .Ed .Pp Alternately, to load the file system firewall policy module at boot time, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "options MAC" .Ed .Pp and in .Xr loader.conf 5 : .Bd -literal -offset indent mac_bsdextended_load="YES" .Ed .Sh DESCRIPTION The .Nm security policy module provides an interface for the system administrator to impose mandatory rules regarding users and some system objects. Rules are uploaded to the module (typically using .Xr ugidfw 8 , or some other tool utilizing .Xr libugidfw 3 ) where they are stored internally and used to determine whether to allow or deny specific accesses (see .Xr ugidfw 8 ) . .Sh IMPLEMENTATION NOTES While the traditional .Xr mac 9 entry points are implemented, policy labels are not used; instead, access control decisions are made by iterating through the internal list of rules until a rule which denies the particular access is found, or the end of the list is reached. The .Nm policy works similar to .Xr ipfw 8 or by using a .Em first match semantic . This means that not all rules are applied, only the first matched rule; thus if Rule A allows access and Rule B blocks access, Rule B will never be applied. -.Pp .Ss Sysctls The following sysctls may be used to tweak the behavior of .Nm : .Bl -tag -width indent .It Va security.mac.bsdextended.enabled Set to zero or one to toggle the policy off or on. .It Va security.mac.bsdextended.rule_count List the number of defined rules, the maximum rule count is current set at 256. .It Va security.mac.bsdextended.rule_slots List the number of rule slots currently being used. .It Va security.mac.bsdextended.firstmatch_enabled Toggle between the old all rules match functionality and the new first rule matches functionality. This is enabled by default. .It Va security.mac.bsdextended.logging Log all access violations via the .Dv AUTHPRIV .Xr syslog 3 facility. .It Va security.mac.bsdextended.rules Currently does nothing interesting. .El .Sh SEE ALSO .Xr libugidfw 3 , .Xr syslog 3 , .Xr mac 4 , .Xr mac_biba 4 , .Xr mac_ifoff 4 , .Xr mac_lomac 4 , .Xr mac_mls 4 , .Xr mac_none 4 , .Xr mac_partition 4 , .Xr mac_portacl 4 , .Xr mac_seeotheruids 4 , .Xr mac_test 4 , .Xr ipfw 8 , .Xr ugidfw 8 , .Xr mac 9 .Sh HISTORY The .Nm policy module first appeared in .Fx 5.0 and was developed by the .Tn TrustedBSD Project. .Pp The "match first case" and logging capabilities were later added by .An Tom Rhodes Aq Mt trhodes@FreeBSD.org . .Sh AUTHORS This software was contributed to the .Fx Project by NAI Labs, the Security Research Division of Network Associates Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035 .Pq Dq CBOSS , as part of the DARPA CHATS research program. diff --git a/share/man/man4/mac_ntpd.4 b/share/man/man4/mac_ntpd.4 index cce0065f8216..85abfd0c97c0 100644 --- a/share/man/man4/mac_ntpd.4 +++ b/share/man/man4/mac_ntpd.4 @@ -1,115 +1,113 @@ .\" Copyright (c) 2018 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 AUTHORS 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 AUTHORS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd July 20, 2018 .Dt MAC_NTPD 4 .Os .Sh NAME .Nm mac_ntpd .Nd "policy allowing ntpd to run as non-root user" .Sh SYNOPSIS To compile the ntpd policy into your kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "options MAC" .Cd "options MAC_NTPD" .Ed .Pp Alternately, to load the ntpd policy module at boot time, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "options MAC" .Ed .Pp and in .Xr loader.conf 5 : .Bd -literal -offset indent mac_ntpd_load="YES" .Ed .Sh DESCRIPTION The .Nm policy grants any process running as user .Sq ntpd (uid 123) the privileges needed to manipulate system time, and to (re-)bind to the privileged NTP port. .Pp When .Xr ntpd 8 is started with .Sq Fl u Ar [:group] on the command line, it performs all initializations requiring root privileges, then drops root privileges by switching to the given user id. From that point on, the only privileges it requires are the ability to manipulate system time, and the ability to re-bind a UDP socket to the NTP port (port 123) after a network interface change. .Pp With the .Nm policy active, it may also be possible to start ntpd as a non-root user, because the default ntpd options don't require any additional root privileges beyond those granted by the policy. -.Pp .Ss Privileges Granted The exact set of kernel privileges granted to any process running with the configured uid is: .Bl -inset -compact -offset indent .It Dv PRIV_ADJTIME .It Dv PRIV_CLOCK_SETTIME .It Dv PRIV_NTP_ADJTIME .It Dv PRIV_NETINET_RESERVEDPORT .It Dv PRIV_NETINET_REUSEPORT .El -.Pp .Ss Runtime Configuration The following .Xr sysctl 8 MIBs are available for fine-tuning this MAC policy. All .Xr sysctl 8 variables can also be set as .Xr loader 8 tunables in .Xr loader.conf 5 . .Bl -tag -width indent .It Va security.mac.ntpd.enabled Enable the .Nm policy. (Default: 1). .It Va security.mac.ntpd.uid The numeric uid of the ntpd user. (Default: 123). .El .Sh SEE ALSO .Xr mac 4 , .Xr ntpd 8 .Sh HISTORY MAC first appeared in .Fx 5.0 and .Nm first appeared in .Fx 12.0 . diff --git a/share/man/man4/mlx5en.4 b/share/man/man4/mlx5en.4 index 31dcdb4657d4..49ad9abb16fd 100644 --- a/share/man/man4/mlx5en.4 +++ b/share/man/man4/mlx5en.4 @@ -1,134 +1,134 @@ .\" Copyright (c) 2015 Mellanox Technologies .\" Copyright (c) 2021 NVIDIA corporation & affiliates .\" 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 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 AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd July 20, 2021 .Dt MLX5EN 4 .Os .Sh NAME .Nm mlx5en .Nd "NVIDIA Mellanox ConnectX-4/5/6 [Dx/Ex/Lx] based 200Gb, 100Gb, 50Gb, 40Gb, 25Gb and 10Gb ethernet 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 "options COMPAT_LINUXKPI" .Cd "options RATELIMIT" .Cd "options KERN_TLS" .Cd "device xz" .Cd "device mlxfw" .Cd "device firmware" .Cd "device mlx5" .Cd "device mlx5en" .Ed .Pp To load the driver as a module at run-time, run the following command as root: .Bd -literal -offset indent kldload mlx5en .Ed .Pp To load the driver as a module at boot time, place the following lines in .Xr loader.conf 5 : .Bd -literal -offset indent mlx5en_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for PCI Express Ethernet adapters based on ConnectX-4/5/6 [Dx, Ex and Lx variants]. The driver supports Jumbo Frames, Transmit and Receive checksum offload, TCP segmentation offload (TSO), Large Receive Offload (LRO), HW Large Receive Offload (HW LRO), VLAN tag insertion and extraction, VLAN checksum offload, VLAN TSO, hardware rate limiting (TXRTLMT), stateless VxLAN hardware offload for receive and transmit, HW TLS offload for transmit, Receive Side Steering (RSS) and .Xr NUMA 4 awareness. .Pp The network interface name is .Dv mce which corresponds to a PCI function, .Dv mlx_core , where .Dv is a number starting at zero. There is at most one network interface per PCI function. .Pp For further information and questions related to hardware requirements, see .Pa https://www.mellanox.com . .Sh HARDWARE The .Nm driver supports 200Gb, 100Gb, 50Gb, 40Gb, 25Gb and 10Gb ethernet adapters. -.Bl -bullet -compact .Pp +.Bl -bullet -compact .It ConnectX-6 supports 10/20/25/40/50/56/100Gb/200Gb/s speeds. .It ConnectX-5 supports 10/20/25/40/50/56/100Gb/s speeds. .It ConnectX-4 supports 10/20/25/40/50/56/100Gb/s speeds. .It ConnectX-4 LX supports 10/25/40/50Gb/s speeds and reduced power consumption. .El .Sh CONFIGURATION The .Nm network interface is configured using .Xr ifconfig 8 and the .Xr sysctl 8 tree at .Dv dev.mce. . All configurable entries are also tunables, and can be put directly into the .Xr loader.conf 5 for persistent configuration. .Sh SUPPORT For general information and support, go to the NVIDIA Mellanox networking support website at: .Pa https://www.mellanox.com . .Pp If an issue is identified with this driver using a supported adapter, e-mail all the specific information related to the issue to .Aq Mt nbu-freebsd-drivers@nvidia.com . .Sh SEE ALSO .Xr ifconfig 8 .Sh HISTORY The .Nm device driver first appeared in .Fx 11.0 . .Sh AUTHORS .An -nosplit The .Nm driver was written by .An NVIDIA Mellanox networking . diff --git a/share/man/man4/mod_cc.4 b/share/man/man4/mod_cc.4 index ddc7440a4ca7..63eb1733df8b 100644 --- a/share/man/man4/mod_cc.4 +++ b/share/man/man4/mod_cc.4 @@ -1,211 +1,210 @@ .\" .\" Copyright (c) 2010-2011 The FreeBSD Foundation .\" All rights reserved. .\" .\" 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. .\" .\" $FreeBSD$ .\" .Dd August 6, 2019 .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 NewReno, 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 -.Pp All of the available congestion control modules may also be loaded via kernel configutation 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 and is included in GENERIC by default. .It Va CC_CUBIC This directive loads the cubic congestion control algorithm. .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 newreno. .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/mpr.4 b/share/man/man4/mpr.4 index 59d9f801f049..3cc516397e33 100644 --- a/share/man/man4/mpr.4 +++ b/share/man/man4/mpr.4 @@ -1,410 +1,409 @@ .\" .\" Copyright (c) 2010 Spectra Logic Corporation .\" Copyright (c) 2014 LSI Corp .\" Copyright (c) 2015-2017 Avago Technologies .\" Copyright (c) 2015-2017 Broadcom Ltd. .\" 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, .\" without modification. .\" 2. Redistributions in binary form must reproduce at minimum a disclaimer .\" substantially similar to the "NO WARRANTY" disclaimer below .\" ("Disclaimer") and any redistribution must be conditioned upon .\" including a substantially similar Disclaimer requirement for further .\" binary redistribution. .\" .\" NO WARRANTY .\" 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 MERCHANTIBILITY AND FITNESS FOR .\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT .\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR 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 DAMAGES. .\" .\" mpr driver man page. .\" .\" Author: Ken Merry .\" Author: Stephen McConnell .\" .\" $Id$ .\" $FreeBSD$ .\" .Dd June 1, 2019 .Dt MPR 4 .Os .Sh NAME .Nm mpr .Nd "LSI Fusion-MPT 3/3.5 IT/IR 12Gb/s Serial Attached SCSI/SATA/PCIe driver" .Sh SYNOPSIS To compile this driver into the kernel, place these lines in the kernel configuration file: .Bd -ragged -offset indent .Cd "device pci" .Cd "device scbus" .Cd "device mpr" .Ed .Pp The driver can be loaded as a module at boot time by placing this line in .Xr loader.conf 5 : .Bd -literal -offset indent mpr_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for Broadcom Ltd./Avago Tech (LSI) Fusion-MPT 3/3.5 IT/IR .Tn SAS/PCIe controllers. .Sh HARDWARE These controllers are supported by the .Nm driver: .Pp .Bl -bullet -compact .It Broadcom Ltd./Avago Tech (LSI) SAS 3004 (4 Port SAS) .It Broadcom Ltd./Avago Tech (LSI) SAS 3008 (8 Port SAS) .It Broadcom Ltd./Avago Tech (LSI) SAS 3108 (8 Port SAS) .It Broadcom Ltd./Avago Tech (LSI) SAS 3216 (16 Port SAS) .It Broadcom Ltd./Avago Tech (LSI) SAS 3224 (24 Port SAS) .It Broadcom Ltd./Avago Tech (LSI) SAS 3316 (16 Port SAS) .It Broadcom Ltd./Avago Tech (LSI) SAS 3324 (24 Port SAS) .It Broadcom Ltd./Avago Tech (LSI) SAS 3408 (8 Port SAS/PCIe) .It Broadcom Ltd./Avago Tech (LSI) SAS 3416 (16 Port SAS/PCIe) .It Broadcom Ltd./Avago Tech (LSI) SAS 3508 (8 Port SAS/PCIe) .It Broadcom Ltd./Avago Tech (LSI) SAS 3516 (16 Port SAS/PCIe) .It Broadcom Ltd./Avago Tech (LSI) SAS 3616 (16 Port SAS/PCIe) .It Broadcom Ltd./Avago Tech (LSI) SAS 3708 (8 Port SAS/PCIe) .It Broadcom Ltd./Avago Tech (LSI) SAS 3716 (16 Port SAS/PCIe) .El .Sh CONFIGURATION In all tunable descriptions below, X represents the adapter number. .Pp To disable MSI interrupts for all .Nm driver instances, set this tunable value in .Xr loader.conf 5 : .Bd -literal -offset indent hw.mpr.disable_msi=1 .Ed .Pp To disable MSI interrupts for a specific .Nm driver instance, set this tunable value in .Xr loader.conf 5 : .Bd -literal -offset indent dev.mpr.X.disable_msi=1 .Ed .Pp To disable MSI-X interrupts for all .Nm driver instances, set this tunable value in .Xr loader.conf 5 : .Bd -literal -offset indent hw.mpr.disable_msix=1 .Ed .Pp To disable MSI-X interrupts for a specific .Nm driver instance, set this tunable value in .Xr loader.conf 5 : .Bd -literal -offset indent dev.mpr.X.disable_msix=1 .Ed .Pp To set the maximum number of DMA chains allocated for all adapters, set this tunable in .Xr loader.conf 5 : .Bd -literal -offset indent hw.mpr.max_chains=NNNN .Ed .Pp To set the maximum number of DMA chains allocated for a specific adapter, set this tunable in .Xr loader.conf 5 : .Bd -literal -offset indent dev.mpr.X.max_chains=NNNN .Ed .Pp The default max_chains value is 16384. .Pp The current number of free chain frames is stored in the dev.mpr.X.chain_free .Xr sysctl 8 variable. .Pp The lowest number of free chain frames seen since boot is stored in the dev.mpr.X.chain_free_lowwater .Xr sysctl 8 variable. .Pp The number of times that chain frame allocations have failed since boot is stored in the dev.mpr.X.chain_alloc_fail .Xr sysctl 8 variable. This can be used to determine whether the max_chains tunable should be increased to help performance. .Pp The current number of active I/O commands is shown in the dev.mpr.X.io_cmds_active .Xr sysctl 8 variable. .Pp The current number of free PRP pages is stored in the dev.mpr.X.prp_pages_free .Xr sysctl 8 variable. PRP pages are used by NVMe devices for I/O transfers, much like Scatter/Gather lists. .Pp The lowest number of free PRP pages seen since boot is stored in the dev.mpr.X.prp_pages_free_lowwater .Xr sysctl 8 variable. .Pp The number of times that PRP page allocations have failed since boot is stored in the dev.mpr.X.prp_page_alloc_fail .Xr sysctl 8 variable. .Pp To set the maximum number of pages that will be used per I/O for all adapters, set this tunable in .Xr loader.conf 5 : .Bd -literal -offset indent hw.mpr.max_io_pages=NNNN .Ed .Pp To set the maximum number of pages that will be used per I/O for a specific adapter, set this tunable in .Xr loader.conf 5 : .Bd -literal -offset indent dev.mpr.X.max_io_pages=NNNN .Ed .Pp The default max_io_pages value is -1, meaning that the maximum I/O size that will be used per I/O will be calculated using the IOCFacts values stored in the controller. The lowest value that the driver will use for max_io_pages is 1, otherwise IOCFacts will be used to calculate the maximum I/O size. The smaller I/O size calculated from either max_io_pages or IOCFacts will be the maximum I/O size used by the driver. .Pp The highest number of active I/O commands seen since boot is stored in the dev.mpr.X.io_cmds_highwater .Xr sysctl 8 variable. .Pp Devices can be excluded from .Nm control for all adapters by setting this tunable in .Xr loader.conf 5 : .Bd -literal -offset indent hw.mpr.exclude_ids=Y .Ed .Pp Y represents the target ID of the device. If more than one device is to be excluded, target IDs are separated by commas. .Pp Devices can be excluded from .Nm control for a specific adapter by setting this tunable in .Xr loader.conf 5 : .Bd -literal -offset indent dev.mpr.X.exclude_ids=Y .Ed .Pp Y represents the target ID of the device. If more than one device is to be excluded, target IDs are separated by commas. .Pp The adapter can issue the .Sy StartStopUnit SCSI command to SATA direct-access devices during shutdown. This allows the device to quiesce powering down. To control this feature for all adapters, set the .Bd -literal -offset indent hw.mpr.enable_ssu .Ed .Pp tunable in .Xr loader.conf 5 to one of these values: .Bl -tag -width 6n -offset indent .It 0 Do not send SSU to either HDDs or SSDs. .It 1 Send SSU to SSDs, but not to HDDs. This is the default value. .It 2 Send SSU to HDDs, but not to SSDs. .It 3 Send SSU to both HDDs and SSDs. .El .Pp To control this feature for a specific adapter, set this tunable value in .Xr loader.conf 5 : .Bd -literal -offset indent dev.mpr.X.enable_ssu .Ed .Pp The same set of values are valid as when setting this tunable for all adapters. .Pp SATA disks that take several seconds to spin up and fail the SATA Identify command might not be discovered by the driver. This problem can sometimes be overcome by increasing the value of the spinup wait time in .Xr loader.conf 5 with the .Bd -literal -offset indent hw.mpr.spinup_wait_time=NNNN .Ed .Pp tunable. NNNN represents the number of seconds to wait for SATA devices to spin up when the device fails the initial SATA Identify command. .Pp Spinup wait times can be set for specific adapters in .Xr loader.conf 5 : with the .Bd -literal -offset indent dev.mpr.X.spinup_wait_time=NNNN .Ed .Pp tunable. NNNN is the number of seconds to wait for SATA devices to spin up when they fail the initial SATA Identify command. .Pp The driver can map devices discovered by the adapter so that target IDs corresponding to a specific device persist across resets and reboots. In some cases it is possible for devices to lose their mapped IDs due to unexpected behavior from certain hardware, such as some types of enclosures. To overcome this problem, a tunable is provided that will force the driver to map devices using the Phy number associated with the device. This feature is not recommended if the topology includes multiple enclosures/expanders. If multiple enclosures/expanders are present in the topology, Phy numbers are repeated, causing all devices at these Phy numbers except the first device to fail enumeration. To control this feature for all adapters, set the .Bd -literal -offset indent hw.mpr.use_phy_num .Ed .Pp tunable in .Xr loader.conf 5 to one of these values: .Bl -tag -width 6n -offset indent .It -1 Only use Phy numbers to map devices and bypass the driver's mapping logic. .It 0 Never use Phy numbers to map devices. .It 1 Use Phy numbers to map devices, but only if the driver's mapping logic fails to map the device that is being enumerated. This is the default value. .El .Pp To control this feature for a specific adapter, set this tunable value in .Xr loader.conf 5 : .Bd -literal -offset indent dev.mpr.X.use_phy_num .Ed .Pp The same set of values are valid as when setting this tunable for all adapters. -.Pp .Sh DEBUGGING Driver diagnostic printing is controlled in .Xr loader.conf 5 by using the global .Va hw.mpr.debug_level and per-device .Va dev.mpr.X.debug_level tunables. One can alter the debug level for any adapter at run-time using the .Xr sysctl 8 variable .Va dev.mpr.X.debug_level . .Pp All .Va debug_level variables can be named by either an integer value or a text string. Multiple values can be specified together by either ORing the integer values or by providing a comma-separated list of names. A text string prefixed by .Qq + adds the specified debug levels to the existing set, while the prefix .Qq - removes them from the existing set. The current .Va debug_level status is reported in both formats for convenience. The following levels are available: .Bl -column "FlagXX" "NameXXXX" "Description" -offset indent .It Em Flag Ta Em Name Ta Em Description .It 0x0001 Ta info Ta Basic information (enabled by default) .It 0x0002 Ta fault Ta Driver faults (enabled by default) .It 0x0004 Ta event Ta Controller events .It 0x0008 Ta log Ta Logging data from controller .It 0x0010 Ta recovery Ta Tracing of recovery operations .It 0x0020 Ta error Ta Parameter errors and programming bugs .It 0x0040 Ta init Ta System initialization operations .It 0x0080 Ta xinfo Ta More detailed information .It 0x0100 Ta user Ta Tracing of user-generated commands (IOCTL) .It 0x0200 Ta mapping Ta Tracing of device mapping .It 0x0400 Ta trace Ta Tracing through driver functions .El .Sh SEE ALSO .Xr cam 4 , .Xr cd 4 , .Xr ch 4 , .Xr da 4 , .Xr mps 4 , .Xr mpt 4 , .Xr pci 4 , .Xr sa 4 , .Xr scsi 4 , .Xr targ 4 , .Xr loader.conf 5 , .Xr sysctl 8 .Sh HISTORY The .Nm driver first appeared in .Fx 9.3 . .Sh AUTHORS The .Nm driver was originally written by .An -nosplit .An Scott Long Aq Mt scottl@FreeBSD.org . It has been improved and tested by LSI Corporation, Avago Technologies (formally LSI), and Broadcom Ltd. (formally Avago). .Pp This man page was written by .An Ken Merry Aq Mt ken@FreeBSD.org with additional input from .An Stephen McConnell Aq Mt slm@FreeBSD.org . diff --git a/share/man/man4/mps.4 b/share/man/man4/mps.4 index c2fb6c245403..fac131429fec 100644 --- a/share/man/man4/mps.4 +++ b/share/man/man4/mps.4 @@ -1,386 +1,385 @@ .\" .\" Copyright (c) 2010 Spectra Logic Corporation .\" Copyright (c) 2014 LSI Corp .\" Copyright (c) 2015-2017 Avago Technologies .\" Copyright (c) 2015-2017 Broadcom Ltd. .\" 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, .\" without modification. .\" 2. Redistributions in binary form must reproduce at minimum a disclaimer .\" substantially similar to the "NO WARRANTY" disclaimer below .\" ("Disclaimer") and any redistribution must be conditioned upon .\" including a substantially similar Disclaimer requirement for further .\" binary redistribution. .\" .\" NO WARRANTY .\" 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 MERCHANTIBILITY AND FITNESS FOR .\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT .\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR 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 DAMAGES. .\" .\" mps driver man page. .\" .\" Author: Ken Merry .\" Author: Stephen McConnell .\" .\" $Id: //depot/SpectraBSD/head/share/man/man4/mps.4#6 $ .\" $FreeBSD$ .\" .Dd June 1, 2019 .Dt MPS 4 .Os .Sh NAME .Nm mps .Nd "LSI Fusion-MPT 2 IT/IR 6Gb/s Serial Attached SCSI/SATA driver" .Sh SYNOPSIS To compile this driver into the kernel, place these lines in the kernel configuration file: .Bd -ragged -offset indent .Cd "device pci" .Cd "device scbus" .Cd "device mps" .Ed .Pp The driver can be loaded as a module at boot time by placing this line in .Xr loader.conf 5 : .Bd -literal -offset indent mps_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for Broadcom Ltd./Avago Tech (LSI) Fusion-MPT 2 IT/IR .Tn SAS controllers and WarpDrive solid state storage cards. .Sh HARDWARE These controllers are supported by the .Nm driver: .Pp .Bl -bullet -compact .It Broadcom Ltd./Avago Tech (LSI) SAS 2004 (4 Port SAS) .It Broadcom Ltd./Avago Tech (LSI) SAS 2008 (8 Port SAS) .It Broadcom Ltd./Avago Tech (LSI) SAS 2108 (8 Port SAS) .It Broadcom Ltd./Avago Tech (LSI) SAS 2116 (16 Port SAS) .It Broadcom Ltd./Avago Tech (LSI) SAS 2208 (8 Port SAS) .It Broadcom Ltd./Avago Tech (LSI) SAS 2308 (8 Port SAS) .It Broadcom Ltd./Avago Tech (LSI) SSS6200 Solid State Storage .It Intel Integrated RAID Module RMS25JB040 .It Intel Integrated RAID Module RMS25JB080 .It Intel Integrated RAID Module RMS25KB040 .It Intel Integrated RAID Module RMS25KB080 .El .Sh CONFIGURATION In all tunable descriptions below, X represents the adapter number. .Pp To disable MSI interrupts for all .Nm driver instances, set this tunable value in .Xr loader.conf 5 : .Bd -literal -offset indent hw.mps.disable_msi=1 .Ed .Pp To disable MSI interrupts for a specific .Nm driver instance, set this tunable value in .Xr loader.conf 5 : .Bd -literal -offset indent dev.mps.X.disable_msi=1 .Ed .Pp To disable MSI-X interrupts for all .Nm driver instances, set this tunable value in .Xr loader.conf 5 : .Bd -literal -offset indent hw.mps.disable_msix=1 .Ed .Pp To disable MSI-X interrupts for a specific .Nm driver instance, set this tunable value in .Xr loader.conf 5 : .Bd -literal -offset indent dev.mps.X.disable_msix=1 .Ed .Pp To set the maximum number of DMA chains allocated for all adapters, set this tunable in .Xr loader.conf 5 : .Bd -literal -offset indent hw.mps.max_chains=NNNN .Ed .Pp To set the maximum number of DMA chains allocated for a specific adapter, set this tunable in .Xr loader.conf 5 : .Bd -literal -offset indent dev.mps.X.max_chains=NNNN .Ed .Pp The default max_chains value is 16384. .Pp The current number of free chain frames is stored in the dev.mps.X.chain_free .Xr sysctl 8 variable. .Pp The lowest number of free chain frames seen since boot is stored in the dev.mps.X.chain_free_lowwater .Xr sysctl 8 variable. .Pp The number of times that chain frame allocations have failed since boot is stored in the dev.mps.X.chain_alloc_fail .Xr sysctl 8 variable. This can be used to determine whether the max_chains tunable should be increased to help performance. .Pp The current number of active I/O commands is shown in the dev.mps.X.io_cmds_active .Xr sysctl 8 variable. .Pp To set the maximum number of pages that will be used per I/O for all adapters, set this tunable in .Xr loader.conf 5 : .Bd -literal -offset indent hw.mps.max_io_pages=NNNN .Ed .Pp To set the maximum number of pages that will be used per I/O for a specific adapter, set this tunable in .Xr loader.conf 5 : .Bd -literal -offset indent dev.mps.X.max_io_pages=NNNN .Ed .Pp The default max_io_pages value is -1, meaning that the maximum I/O size that will be used per I/O will be calculated using the IOCFacts values stored in the controller. The lowest value that the driver will use for max_io_pages is 1, otherwise IOCFacts will be used to calculate the maximum I/O size. The smaller I/O size calculated from either max_io_pages or IOCFacts will be the maximum I/O size used by the driver. .Pp The highest number of active I/O commands seen since boot is stored in the dev.mps.X.io_cmds_highwater .Xr sysctl 8 variable. .Pp Devices can be excluded from .Nm control for all adapters by setting this tunable in .Xr loader.conf 5 : .Bd -literal -offset indent hw.mps.exclude_ids=Y .Ed .Pp Y represents the target ID of the device. If more than one device is to be excluded, target IDs are separated by commas. .Pp Devices can be excluded from .Nm control for a specific adapter by setting this tunable in .Xr loader.conf 5 : .Bd -literal -offset indent dev.mps.X.exclude_ids=Y .Ed .Pp Y represents the target ID of the device. If more than one device is to be excluded, target IDs are separated by commas. .Pp The adapter can issue the .Sy StartStopUnit SCSI command to SATA direct-access devices during shutdown. This allows the device to quiesce powering down. To control this feature for all adapters, set the .Bd -literal -offset indent hw.mps.enable_ssu .Ed .Pp tunable in .Xr loader.conf 5 to one of these values: .Bl -tag -width 6n -offset indent .It 0 Do not send SSU to either HDDs or SSDs. .It 1 Send SSU to SSDs, but not to HDDs. This is the default value. .It 2 Send SSU to HDDs, but not to SSDs. .It 3 Send SSU to both HDDs and SSDs. .El .Pp To control this feature for a specific adapter, set this tunable value in .Xr loader.conf 5 : .Bd -literal -offset indent dev.mps.X.enable_ssu .Ed .Pp The same set of values are valid as when setting this tunable for all adapters. .Pp SATA disks that take several seconds to spin up and fail the SATA Identify command might not be discovered by the driver. This problem can sometimes be overcome by increasing the value of the spinup wait time in .Xr loader.conf 5 with the .Bd -literal -offset indent hw.mps.spinup_wait_time=NNNN .Ed .Pp tunable. NNNN represents the number of seconds to wait for SATA devices to spin up when the device fails the initial SATA Identify command. .Pp Spinup wait times can be set for specific adapters in .Xr loader.conf 5 : with the .Bd -literal -offset indent dev.mps.X.spinup_wait_time=NNNN .Ed .Pp tunable. NNNN is the number of seconds to wait for SATA devices to spin up when they fail the initial SATA Identify command. .Pp The driver can map devices discovered by the adapter so that target IDs corresponding to a specific device persist across resets and reboots. In some cases it is possible for devices to lose their mapped IDs due to unexpected behavior from certain hardware, such as some types of enclosures. To overcome this problem, a tunable is provided that will force the driver to map devices using the Phy number associated with the device. This feature is not recommended if the topology includes multiple enclosures/expanders. If multiple enclosures/expanders are present in the topology, Phy numbers are repeated, causing all devices at these Phy numbers except the first device to fail enumeration. To control this feature for all adapters, set the .Bd -literal -offset indent hw.mps.use_phy_num .Ed .Pp tunable in .Xr loader.conf 5 to one of these values: .Bl -tag -width 6n -offset indent .It -1 Only use Phy numbers to map devices and bypass the driver's mapping logic. .It 0 Never use Phy numbers to map devices. .It 1 Use Phy numbers to map devices, but only if the driver's mapping logic fails to map the device that is being enumerated. This is the default value. .El .Pp To control this feature for a specific adapter, set this tunable value in .Xr loader.conf 5 : .Bd -literal -offset indent dev.mps.X.use_phy_num .Ed .Pp The same set of values are valid as when setting this tunable for all adapters. -.Pp .Sh DEBUGGING Driver diagnostic printing is controlled in .Xr loader.conf 5 by using the global .Va hw.mps.debug_level and per-device .Va dev.mps.X.debug_level tunables. One can alter the debug level for any adapter at run-time using the .Xr sysctl 8 variable .Va dev.mps.X.debug_level . .Pp All .Va debug_level variables can be named by either an integer value or a text string. Multiple values can be specified together by either ORing the integer values or by providing a comma-separated list of names. A text string prefixed by .Qq + adds the specified debug levels to the existing set, while the prefix .Qq - removes them from the existing set. The current .Va debug_level status is reported in both formats for convenience. The following levels are available: .Bl -column "FlagXX" "NameXXXX" "Description" -offset indent .It Em Flag Ta Em Name Ta Em Description .It 0x0001 Ta info Ta Basic information (enabled by default) .It 0x0002 Ta fault Ta Driver faults (enabled by default) .It 0x0004 Ta event Ta Controller events .It 0x0008 Ta log Ta Logging data from controller .It 0x0010 Ta recovery Ta Tracing of recovery operations .It 0x0020 Ta error Ta Parameter errors and programming bugs .It 0x0040 Ta init Ta System initialization operations .It 0x0080 Ta xinfo Ta More detailed information .It 0x0100 Ta user Ta Tracing of user-generated commands (IOCTL) .It 0x0200 Ta mapping Ta Tracing of device mapping .It 0x0400 Ta trace Ta Tracing through driver functions .El .Sh SEE ALSO .Xr cam 4 , .Xr cd 4 , .Xr ch 4 , .Xr da 4 , .Xr mpr 4 , .Xr mpt 4 , .Xr pci 4 , .Xr sa 4 , .Xr scsi 4 , .Xr targ 4 , .Xr loader.conf 5 , .Xr sysctl 8 .Sh HISTORY The .Nm driver first appeared in .Fx 9.0 . .Sh AUTHORS The .Nm driver was originally written by .An -nosplit .An Scott Long Aq Mt scottl@FreeBSD.org . It has been improved and tested by LSI Corporation, Avago Technologies (formally LSI), and Broadcom Ltd. (formally Avago). .Pp This man page was written by .An Ken Merry Aq Mt ken@FreeBSD.org with additional input from .An Stephen McConnell Aq Mt slm@FreeBSD.org . diff --git a/share/man/man4/netmap.4 b/share/man/man4/netmap.4 index 732e3bfaeaab..46a2f53b9b1f 100644 --- a/share/man/man4/netmap.4 +++ b/share/man/man4/netmap.4 @@ -1,1187 +1,1187 @@ .\" Copyright (c) 2011-2014 Matteo Landi, Luigi Rizzo, Universita` di Pisa .\" 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. .\" .\" This document is derived in part from the enet man page (enet.4) .\" distributed with 4.3BSD Unix. .\" .\" $FreeBSD$ .\" .Dd October 3, 2020 .Dt NETMAP 4 .Os .Sh NAME .Nm netmap .Nd a framework for fast packet I/O .Sh SYNOPSIS .Cd device netmap .Sh DESCRIPTION .Nm is a framework for extremely fast and efficient packet I/O for userspace and kernel clients, and for Virtual Machines. It runs on .Fx , Linux and some versions of Windows, and supports a variety of .Nm netmap ports , including .Bl -tag -width XXXX .It Nm physical NIC ports to access individual queues of network interfaces; .It Nm host ports to inject packets into the host stack; .It Nm VALE ports implementing a very fast and modular in-kernel software switch/dataplane; .It Nm netmap pipes a shared memory packet transport channel; .It Nm netmap monitors a mechanism similar to .Xr bpf 4 to capture traffic .El .Pp All these .Nm netmap ports are accessed interchangeably with the same API, and are at least one order of magnitude faster than standard OS mechanisms (sockets, bpf, tun/tap interfaces, native switches, pipes). With suitably fast hardware (NICs, PCIe buses, CPUs), packet I/O using .Nm on supported NICs reaches 14.88 million packets per second (Mpps) with much less than one core on 10 Gbit/s NICs; 35-40 Mpps on 40 Gbit/s NICs (limited by the hardware); about 20 Mpps per core for VALE ports; and over 100 Mpps for .Nm netmap pipes . NICs without native .Nm support can still use the API in emulated mode, which uses unmodified device drivers and is 3-5 times faster than .Xr bpf 4 or raw sockets. .Pp Userspace clients can dynamically switch NICs into .Nm mode and send and receive raw packets through memory mapped buffers. Similarly, .Nm VALE switch instances and ports, .Nm netmap pipes and .Nm netmap monitors can be created dynamically, providing high speed packet I/O between processes, virtual machines, NICs and the host stack. .Pp .Nm supports both non-blocking I/O through .Xr ioctl 2 , synchronization and blocking I/O through a file descriptor and standard OS mechanisms such as .Xr select 2 , .Xr poll 2 , .Xr kqueue 2 and .Xr epoll 7 . All types of .Nm netmap ports and the .Nm VALE switch are implemented by a single kernel module, which also emulates the .Nm API over standard drivers. For best performance, .Nm requires native support in device drivers. A list of such devices is at the end of this document. .Pp In the rest of this (long) manual page we document various aspects of the .Nm and .Nm VALE architecture, features and usage. .Sh ARCHITECTURE .Nm supports raw packet I/O through a .Em port , which can be connected to a physical interface .Em ( NIC ) , to the host stack, or to a .Nm VALE switch. Ports use preallocated circular queues of buffers .Em ( rings ) residing in an mmapped region. There is one ring for each transmit/receive queue of a NIC or virtual port. An additional ring pair connects to the host stack. .Pp After binding a file descriptor to a port, a .Nm client can send or receive packets in batches through the rings, and possibly implement zero-copy forwarding between ports. .Pp All NICs operating in .Nm mode use the same memory region, accessible to all processes who own .Pa /dev/netmap file descriptors bound to NICs. Independent .Nm VALE and .Nm netmap pipe ports by default use separate memory regions, but can be independently configured to share memory. .Sh ENTERING AND EXITING NETMAP MODE The following section describes the system calls to create and control .Nm netmap ports (including .Nm VALE and .Nm netmap pipe ports). Simpler, higher level functions are described in the .Sx LIBRARIES section. .Pp Ports and rings are created and controlled through a file descriptor, created by opening a special device .Dl fd = open("/dev/netmap"); and then bound to a specific port with an .Dl ioctl(fd, NIOCREGIF, (struct nmreq *)arg); .Pp .Nm has multiple modes of operation controlled by the .Vt struct nmreq argument. .Va arg.nr_name specifies the netmap port name, as follows: .Bl -tag -width XXXX .It Dv OS network interface name (e.g., 'em0', 'eth1', ... ) the data path of the NIC is disconnected from the host stack, and the file descriptor is bound to the NIC (one or all queues), or to the host stack; .It Dv valeSSS:PPP the file descriptor is bound to port PPP of VALE switch SSS. Switch instances and ports are dynamically created if necessary. .Pp Both SSS and PPP have the form [0-9a-zA-Z_]+ , the string cannot exceed IFNAMSIZ characters, and PPP cannot be the name of any existing OS network interface. .El .Pp On return, .Va arg indicates the size of the shared memory region, and the number, size and location of all the .Nm data structures, which can be accessed by mmapping the memory .Dl char *mem = mmap(0, arg.nr_memsize, fd); .Pp Non-blocking I/O is done with special .Xr ioctl 2 .Xr select 2 and .Xr poll 2 on the file descriptor permit blocking I/O. .Pp While a NIC is in .Nm mode, the OS will still believe the interface is up and running. OS-generated packets for that NIC end up into a .Nm ring, and another ring is used to send packets into the OS network stack. A .Xr close 2 on the file descriptor removes the binding, and returns the NIC to normal mode (reconnecting the data path to the host stack), or destroys the virtual port. .Sh DATA STRUCTURES The data structures in the mmapped memory region are detailed in .In sys/net/netmap.h , which is the ultimate reference for the .Nm API. The main structures and fields are indicated below: .Bl -tag -width XXX .It Dv struct netmap_if (one per interface ) .Bd -literal struct netmap_if { ... const uint32_t ni_flags; /* properties */ ... const uint32_t ni_tx_rings; /* NIC tx rings */ const uint32_t ni_rx_rings; /* NIC rx rings */ uint32_t ni_bufs_head; /* head of extra bufs list */ ... }; .Ed .Pp Indicates the number of available rings .Pa ( struct netmap_rings ) and their position in the mmapped region. The number of tx and rx rings .Pa ( ni_tx_rings , ni_rx_rings ) normally depends on the hardware. NICs also have an extra tx/rx ring pair connected to the host stack. .Em NIOCREGIF can also request additional unbound buffers in the same memory space, to be used as temporary storage for packets. The number of extra buffers is specified in the .Va arg.nr_arg3 field. On success, the kernel writes back to .Va arg.nr_arg3 the number of extra buffers actually allocated (they may be less than the amount requested if the memory space ran out of buffers). .Pa ni_bufs_head contains the index of the first of these extra buffers, which are connected in a list (the first uint32_t of each buffer being the index of the next buffer in the list). A .Dv 0 indicates the end of the list. The application is free to modify this list and use the buffers (i.e., binding them to the slots of a netmap ring). When closing the netmap file descriptor, the kernel frees the buffers contained in the list pointed by .Pa ni_bufs_head , irrespectively of the buffers originally provided by the kernel on .Em NIOCREGIF . .It Dv struct netmap_ring (one per ring ) .Bd -literal struct netmap_ring { ... const uint32_t num_slots; /* slots in each ring */ const uint32_t nr_buf_size; /* size of each buffer */ ... uint32_t head; /* (u) first buf owned by user */ uint32_t cur; /* (u) wakeup position */ const uint32_t tail; /* (k) first buf owned by kernel */ ... uint32_t flags; struct timeval ts; /* (k) time of last rxsync() */ ... struct netmap_slot slot[0]; /* array of slots */ } .Ed .Pp Implements transmit and receive rings, with read/write pointers, metadata and an array of .Em slots describing the buffers. .It Dv struct netmap_slot (one per buffer ) .Bd -literal struct netmap_slot { uint32_t buf_idx; /* buffer index */ uint16_t len; /* packet length */ uint16_t flags; /* buf changed, etc. */ uint64_t ptr; /* address for indirect buffers */ }; .Ed .Pp Describes a packet buffer, which normally is identified by an index and resides in the mmapped region. .It Dv packet buffers Fixed size (normally 2 KB) packet buffers allocated by the kernel. .El .Pp The offset of the .Pa struct netmap_if in the mmapped region is indicated by the .Pa nr_offset field in the structure returned by .Dv NIOCREGIF . From there, all other objects are reachable through relative references (offsets or indexes). Macros and functions in .In net/netmap_user.h help converting them into actual pointers: .Pp .Dl struct netmap_if *nifp = NETMAP_IF(mem, arg.nr_offset); .Dl struct netmap_ring *txr = NETMAP_TXRING(nifp, ring_index); .Dl struct netmap_ring *rxr = NETMAP_RXRING(nifp, ring_index); .Pp .Dl char *buf = NETMAP_BUF(ring, buffer_index); .Sh RINGS, BUFFERS AND DATA I/O .Va Rings are circular queues of packets with three indexes/pointers .Va ( head , cur , tail ) ; one slot is always kept empty. The ring size .Va ( num_slots ) should not be assumed to be a power of two. .Pp .Va head is the first slot available to userspace; .Pp .Va cur is the wakeup point: select/poll will unblock when .Va tail passes .Va cur ; .Pp .Va tail is the first slot reserved to the kernel. .Pp Slot indexes .Em must only move forward; for convenience, the function .Dl nm_ring_next(ring, index) returns the next index modulo the ring size. .Pp .Va head and .Va cur are only modified by the user program; .Va tail is only modified by the kernel. The kernel only reads/writes the .Vt struct netmap_ring slots and buffers during the execution of a netmap-related system call. The only exception are slots (and buffers) in the range .Va tail\ . . . head-1 , that are explicitly assigned to the kernel. .Ss TRANSMIT RINGS On transmit rings, after a .Nm system call, slots in the range .Va head\ . . . tail-1 are available for transmission. User code should fill the slots sequentially and advance .Va head and .Va cur past slots ready to transmit. .Va cur may be moved further ahead if the user code needs more slots before further transmissions (see .Sx SCATTER GATHER I/O ) . .Pp At the next NIOCTXSYNC/select()/poll(), slots up to .Va head-1 are pushed to the port, and .Va tail may advance if further slots have become available. Below is an example of the evolution of a TX ring: .Bd -literal after the syscall, slots between cur and tail are (a)vailable head=cur tail | | v v TX [.....aaaaaaaaaaa.............] user creates new packets to (T)ransmit head=cur tail | | v v TX [.....TTTTTaaaaaa.............] NIOCTXSYNC/poll()/select() sends packets and reports new slots head=cur tail | | v v TX [..........aaaaaaaaaaa........] .Ed .Pp .Fn select and .Fn poll will block if there is no space in the ring, i.e., .Dl ring->cur == ring->tail and return when new slots have become available. .Pp High speed applications may want to amortize the cost of system calls by preparing as many packets as possible before issuing them. .Pp A transmit ring with pending transmissions has .Dl ring->head != ring->tail + 1 (modulo the ring size). The function .Va int nm_tx_pending(ring) implements this test. .Ss RECEIVE RINGS On receive rings, after a .Nm system call, the slots in the range .Va head\& . . . tail-1 contain received packets. User code should process them and advance .Va head and .Va cur past slots it wants to return to the kernel. .Va cur may be moved further ahead if the user code wants to wait for more packets without returning all the previous slots to the kernel. .Pp At the next NIOCRXSYNC/select()/poll(), slots up to .Va head-1 are returned to the kernel for further receives, and .Va tail may advance to report new incoming packets. .Pp Below is an example of the evolution of an RX ring: .Bd -literal after the syscall, there are some (h)eld and some (R)eceived slots head cur tail | | | v v v RX [..hhhhhhRRRRRRRR..........] user advances head and cur, releasing some slots and holding others head cur tail | | | v v v RX [..*****hhhRRRRRR...........] NICRXSYNC/poll()/select() recovers slots and reports new packets head cur tail | | | v v v RX [.......hhhRRRRRRRRRRRR....] .Ed .Sh SLOTS AND PACKET BUFFERS Normally, packets should be stored in the netmap-allocated buffers assigned to slots when ports are bound to a file descriptor. One packet is fully contained in a single buffer. .Pp The following flags affect slot and buffer processing: .Bl -tag -width XXX .It NS_BUF_CHANGED .Em must be used when the .Va buf_idx in the slot is changed. This can be used to implement zero-copy forwarding, see .Sx ZERO-COPY FORWARDING . .It NS_REPORT reports when this buffer has been transmitted. Normally, .Nm notifies transmit completions in batches, hence signals can be delayed indefinitely. This flag helps detect when packets have been sent and a file descriptor can be closed. .It NS_FORWARD When a ring is in 'transparent' mode, packets marked with this flag by the user application are forwarded to the other endpoint at the next system call, thus restoring (in a selective way) the connection between a NIC and the host stack. .It NS_NO_LEARN tells the forwarding code that the source MAC address for this packet must not be used in the learning bridge code. .It NS_INDIRECT indicates that the packet's payload is in a user-supplied buffer whose user virtual address is in the 'ptr' field of the slot. The size can reach 65535 bytes. .Pp This is only supported on the transmit ring of .Nm VALE ports, and it helps reducing data copies in the interconnection of virtual machines. .It NS_MOREFRAG indicates that the packet continues with subsequent buffers; the last buffer in a packet must have the flag clear. .El .Sh SCATTER GATHER I/O Packets can span multiple slots if the .Va NS_MOREFRAG flag is set in all but the last slot. The maximum length of a chain is 64 buffers. This is normally used with .Nm VALE ports when connecting virtual machines, as they generate large TSO segments that are not split unless they reach a physical device. .Pp NOTE: The length field always refers to the individual fragment; there is no place with the total length of a packet. .Pp On receive rings the macro .Va NS_RFRAGS(slot) indicates the remaining number of slots for this packet, including the current one. Slots with a value greater than 1 also have NS_MOREFRAG set. .Sh IOCTLS .Nm uses two ioctls (NIOCTXSYNC, NIOCRXSYNC) for non-blocking I/O. They take no argument. Two more ioctls (NIOCGINFO, NIOCREGIF) are used to query and configure ports, with the following argument: .Bd -literal struct nmreq { char nr_name[IFNAMSIZ]; /* (i) port name */ uint32_t nr_version; /* (i) API version */ uint32_t nr_offset; /* (o) nifp offset in mmap region */ uint32_t nr_memsize; /* (o) size of the mmap region */ uint32_t nr_tx_slots; /* (i/o) slots in tx rings */ uint32_t nr_rx_slots; /* (i/o) slots in rx rings */ uint16_t nr_tx_rings; /* (i/o) number of tx rings */ uint16_t nr_rx_rings; /* (i/o) number of rx rings */ uint16_t nr_ringid; /* (i/o) ring(s) we care about */ uint16_t nr_cmd; /* (i) special command */ uint16_t nr_arg1; /* (i/o) extra arguments */ uint16_t nr_arg2; /* (i/o) extra arguments */ uint32_t nr_arg3; /* (i/o) extra arguments */ uint32_t nr_flags /* (i/o) open mode */ ... }; .Ed .Pp A file descriptor obtained through .Pa /dev/netmap also supports the ioctl supported by network devices, see .Xr netintro 4 . .Bl -tag -width XXXX .It Dv NIOCGINFO returns EINVAL if the named port does not support netmap. Otherwise, it returns 0 and (advisory) information about the port. Note that all the information below can change before the interface is actually put in netmap mode. .Bl -tag -width XX .It Pa nr_memsize indicates the size of the .Nm memory region. NICs in .Nm mode all share the same memory region, whereas .Nm VALE ports have independent regions for each port. .It Pa nr_tx_slots , nr_rx_slots indicate the size of transmit and receive rings. .It Pa nr_tx_rings , nr_rx_rings indicate the number of transmit and receive rings. Both ring number and sizes may be configured at runtime using interface-specific functions (e.g., .Xr ethtool 8 ). .El .It Dv NIOCREGIF binds the port named in .Va nr_name to the file descriptor. For a physical device this also switches it into .Nm mode, disconnecting it from the host stack. Multiple file descriptors can be bound to the same port, with proper synchronization left to the user. .Pp The recommended way to bind a file descriptor to a port is to use function .Va nm_open(..) (see .Sx LIBRARIES ) which parses names to access specific port types and enable features. In the following we document the main features. .Pp .Dv NIOCREGIF can also bind a file descriptor to one endpoint of a .Em netmap pipe , consisting of two netmap ports with a crossover connection. A netmap pipe share the same memory space of the parent port, and is meant to enable configuration where a master process acts as a dispatcher towards slave processes. .Pp To enable this function, the .Pa nr_arg1 field of the structure can be used as a hint to the kernel to indicate how many pipes we expect to use, and reserve extra space in the memory region. .Pp On return, it gives the same info as NIOCGINFO, with .Pa nr_ringid and .Pa nr_flags indicating the identity of the rings controlled through the file descriptor. .Pp .Va nr_flags .Va nr_ringid selects which rings are controlled through this file descriptor. Possible values of .Pa nr_flags are indicated below, together with the naming schemes that application libraries (such as the .Nm nm_open indicated below) can use to indicate the specific set of rings. In the example below, "netmap:foo" is any valid netmap port name. .Bl -tag -width XXXXX .It NR_REG_ALL_NIC "netmap:foo" (default) all hardware ring pairs .It NR_REG_SW "netmap:foo^" the ``host rings'', connecting to the host stack. .It NR_REG_NIC_SW "netmap:foo*" all hardware rings and the host rings .It NR_REG_ONE_NIC "netmap:foo-i" only the i-th hardware ring pair, where the number is in .Pa nr_ringid ; .It NR_REG_PIPE_MASTER "netmap:foo{i" the master side of the netmap pipe whose identifier (i) is in .Pa nr_ringid ; .It NR_REG_PIPE_SLAVE "netmap:foo}i" the slave side of the netmap pipe whose identifier (i) is in .Pa nr_ringid . .Pp The identifier of a pipe must be thought as part of the pipe name, and does not need to be sequential. On return the pipe will only have a single ring pair with index 0, irrespective of the value of .Va i . .El .Pp By default, a .Xr poll 2 or .Xr select 2 call pushes out any pending packets on the transmit ring, even if no write events are specified. The feature can be disabled by or-ing .Va NETMAP_NO_TX_POLL to the value written to .Va nr_ringid . When this feature is used, packets are transmitted only on .Va ioctl(NIOCTXSYNC) or .Va select() / .Va poll() are called with a write event (POLLOUT/wfdset) or a full ring. .Pp When registering a virtual interface that is dynamically created to a .Nm VALE switch, we can specify the desired number of rings (1 by default, and currently up to 16) on it using nr_tx_rings and nr_rx_rings fields. .It Dv NIOCTXSYNC tells the hardware of new packets to transmit, and updates the number of slots available for transmission. .It Dv NIOCRXSYNC tells the hardware of consumed packets, and asks for newly available packets. .El .Sh SELECT, POLL, EPOLL, KQUEUE .Xr select 2 and .Xr poll 2 on a .Nm file descriptor process rings as indicated in .Sx TRANSMIT RINGS and .Sx RECEIVE RINGS , respectively when write (POLLOUT) and read (POLLIN) events are requested. Both block if no slots are available in the ring .Va ( ring->cur == ring->tail ) . Depending on the platform, .Xr epoll 7 and .Xr kqueue 2 are supported too. .Pp Packets in transmit rings are normally pushed out (and buffers reclaimed) even without requesting write events. Passing the .Dv NETMAP_NO_TX_POLL flag to .Em NIOCREGIF disables this feature. By default, receive rings are processed only if read events are requested. Passing the .Dv NETMAP_DO_RX_POLL flag to .Em NIOCREGIF updates receive rings even without read events. Note that on .Xr epoll 7 and .Xr kqueue 2 , .Dv NETMAP_NO_TX_POLL and .Dv NETMAP_DO_RX_POLL only have an effect when some event is posted for the file descriptor. .Sh LIBRARIES The .Nm API is supposed to be used directly, both because of its simplicity and for efficient integration with applications. .Pp For convenience, the .In net/netmap_user.h header provides a few macros and functions to ease creating a file descriptor and doing I/O with a .Nm port. These are loosely modeled after the .Xr pcap 3 API, to ease porting of libpcap-based applications to .Nm . To use these extra functions, programs should .Dl #define NETMAP_WITH_LIBS before .Dl #include .Pp The following functions are available: .Bl -tag -width XXXXX .It Va struct nm_desc * nm_open(const char *ifname, const struct nmreq *req, uint64_t flags, const struct nm_desc *arg ) similar to .Xr pcap_open_live 3 , binds a file descriptor to a port. .Bl -tag -width XX .It Va ifname is a port name, in the form "netmap:PPP" for a NIC and "valeSSS:PPP" for a .Nm VALE port. .It Va req provides the initial values for the argument to the NIOCREGIF ioctl. The nm_flags and nm_ringid values are overwritten by parsing ifname and flags, and other fields can be overridden through the other two arguments. .It Va arg points to a struct nm_desc containing arguments (e.g., from a previously open file descriptor) that should override the defaults. The fields are used as described below .It Va flags can be set to a combination of the following flags: .Va NETMAP_NO_TX_POLL , .Va NETMAP_DO_RX_POLL (copied into nr_ringid); .Va NM_OPEN_NO_MMAP (if arg points to the same memory region, avoids the mmap and uses the values from it); .Va NM_OPEN_IFNAME (ignores ifname and uses the values in arg); .Va NM_OPEN_ARG1 , .Va NM_OPEN_ARG2 , .Va NM_OPEN_ARG3 (uses the fields from arg); .Va NM_OPEN_RING_CFG (uses the ring number and sizes from arg). .El .It Va int nm_close(struct nm_desc *d ) closes the file descriptor, unmaps memory, frees resources. .It Va int nm_inject(struct nm_desc *d, const void *buf, size_t size ) similar to .Va pcap_inject() , pushes a packet to a ring, returns the size of the packet is successful, or 0 on error; .It Va int nm_dispatch(struct nm_desc *d, int cnt, nm_cb_t cb, u_char *arg ) similar to .Va pcap_dispatch() , applies a callback to incoming packets .It Va u_char * nm_nextpkt(struct nm_desc *d, struct nm_pkthdr *hdr ) similar to .Va pcap_next() , fetches the next packet .El .Sh SUPPORTED DEVICES .Nm natively supports the following devices: .Pp On .Fx : .Xr cxgbe 4 , .Xr em 4 , .Xr iflib 4 .Pq providing Xr igb 4 and Xr em 4 , .Xr ixgbe 4 , .Xr ixl 4 , .Xr re 4 , .Xr vtnet 4 . .Pp On Linux e1000, e1000e, i40e, igb, ixgbe, ixgbevf, r8169, virtio_net, vmxnet3. .Pp NICs without native support can still be used in .Nm mode through emulation. Performance is inferior to native netmap mode but still significantly higher than various raw socket types (bpf, PF_PACKET, etc.). Note that for slow devices (such as 1 Gbit/s and slower NICs, or several 10 Gbit/s NICs whose hardware is unable to sustain line rate), emulated and native mode will likely have similar or same throughput. .Pp When emulation is in use, packet sniffer programs such as tcpdump could see received packets before they are diverted by netmap. This behaviour is not intentional, being just an artifact of the implementation of emulation. Note that in case the netmap application subsequently moves packets received from the emulated adapter onto the host RX ring, the sniffer will intercept those packets again, since the packets are injected to the host stack as they were received by the network interface. .Pp Emulation is also available for devices with native netmap support, which can be used for testing or performance comparison. The sysctl variable .Va dev.netmap.admode globally controls how netmap mode is implemented. .Sh SYSCTL VARIABLES AND MODULE PARAMETERS Some aspects of the operation of .Nm and .Nm VALE are controlled through sysctl variables on .Fx .Em ( dev.netmap.* ) and module parameters on Linux .Em ( /sys/module/netmap/parameters/* ) : .Bl -tag -width indent .It Va dev.netmap.admode: 0 Controls the use of native or emulated adapter mode. .Pp 0 uses the best available option; .Pp 1 forces native mode and fails if not available; .Pp 2 forces emulated hence never fails. .It Va dev.netmap.generic_rings: 1 Number of rings used for emulated netmap mode .It Va dev.netmap.generic_ringsize: 1024 Ring size used for emulated netmap mode .It Va dev.netmap.generic_mit: 100000 Controls interrupt moderation for emulated mode .It Va dev.netmap.fwd: 0 Forces NS_FORWARD mode .It Va dev.netmap.txsync_retry: 2 Number of txsync loops in the .Nm VALE flush function .It Va dev.netmap.no_pendintr: 1 Forces recovery of transmit buffers on system calls .It Va dev.netmap.no_timestamp: 0 Disables the update of the timestamp in the netmap ring .It Va dev.netmap.verbose: 0 Verbose kernel messages .It Va dev.netmap.buf_num: 163840 .It Va dev.netmap.buf_size: 2048 .It Va dev.netmap.ring_num: 200 .It Va dev.netmap.ring_size: 36864 .It Va dev.netmap.if_num: 100 .It Va dev.netmap.if_size: 1024 Sizes and number of objects (netmap_if, netmap_ring, buffers) for the global memory region. The only parameter worth modifying is .Va dev.netmap.buf_num as it impacts the total amount of memory used by netmap. .It Va dev.netmap.buf_curr_num: 0 .It Va dev.netmap.buf_curr_size: 0 .It Va dev.netmap.ring_curr_num: 0 .It Va dev.netmap.ring_curr_size: 0 .It Va dev.netmap.if_curr_num: 0 .It Va dev.netmap.if_curr_size: 0 Actual values in use. .It Va dev.netmap.priv_buf_num: 4098 .It Va dev.netmap.priv_buf_size: 2048 .It Va dev.netmap.priv_ring_num: 4 .It Va dev.netmap.priv_ring_size: 20480 .It Va dev.netmap.priv_if_num: 2 .It Va dev.netmap.priv_if_size: 1024 Sizes and number of objects (netmap_if, netmap_ring, buffers) for private memory regions. A separate memory region is used for each .Nm VALE port and each pair of .Nm netmap pipes . .It Va dev.netmap.bridge_batch: 1024 Batch size used when moving packets across a .Nm VALE switch. Values above 64 generally guarantee good performance. .It Va dev.netmap.ptnet_vnet_hdr: 1 Allow ptnet devices to use virtio-net headers .El .Sh SYSTEM CALLS .Nm uses .Xr select 2 , .Xr poll 2 , .Xr epoll 7 and .Xr kqueue 2 to wake up processes when significant events occur, and .Xr mmap 2 to map memory. .Xr ioctl 2 is used to configure ports and .Nm VALE switches . .Pp Applications may need to create threads and bind them to specific cores to improve performance, using standard OS primitives, see .Xr pthread 3 . In particular, .Xr pthread_setaffinity_np 3 may be of use. .Sh EXAMPLES .Ss TEST PROGRAMS .Nm comes with a few programs that can be used for testing or simple applications. See the .Pa examples/ directory in .Nm distributions, or .Pa tools/tools/netmap/ directory in .Fx distributions. .Pp .Xr pkt-gen 8 is a general purpose traffic source/sink. .Pp As an example .Dl pkt-gen -i ix0 -f tx -l 60 can generate an infinite stream of minimum size packets, and .Dl pkt-gen -i ix0 -f rx is a traffic sink. Both print traffic statistics, to help monitor how the system performs. .Pp .Xr pkt-gen 8 has many options can be uses to set packet sizes, addresses, rates, and use multiple send/receive threads and cores. .Pp .Xr bridge 4 is another test program which interconnects two .Nm ports. It can be used for transparent forwarding between interfaces, as in .Dl bridge -i netmap:ix0 -i netmap:ix1 or even connect the NIC to the host stack using netmap .Dl bridge -i netmap:ix0 .Ss USING THE NATIVE API The following code implements a traffic generator: .Pp .Bd -literal -compact #include \&... void sender(void) { struct netmap_if *nifp; struct netmap_ring *ring; struct nmreq nmr; struct pollfd fds; fd = open("/dev/netmap", O_RDWR); bzero(&nmr, sizeof(nmr)); strcpy(nmr.nr_name, "ix0"); nmr.nm_version = NETMAP_API; ioctl(fd, NIOCREGIF, &nmr); p = mmap(0, nmr.nr_memsize, fd); nifp = NETMAP_IF(p, nmr.nr_offset); ring = NETMAP_TXRING(nifp, 0); fds.fd = fd; fds.events = POLLOUT; for (;;) { poll(&fds, 1, -1); while (!nm_ring_empty(ring)) { i = ring->cur; buf = NETMAP_BUF(ring, ring->slot[i].buf_index); ... prepare packet in buf ... ring->slot[i].len = ... packet length ... ring->head = ring->cur = nm_ring_next(ring, i); } } } .Ed .Ss HELPER FUNCTIONS A simple receiver can be implemented using the helper functions: .Pp .Bd -literal -compact #define NETMAP_WITH_LIBS #include \&... void receiver(void) { struct nm_desc *d; struct pollfd fds; u_char *buf; struct nm_pkthdr h; ... d = nm_open("netmap:ix0", NULL, 0, 0); fds.fd = NETMAP_FD(d); fds.events = POLLIN; for (;;) { poll(&fds, 1, -1); while ( (buf = nm_nextpkt(d, &h)) ) consume_pkt(buf, h.len); } nm_close(d); } .Ed .Ss ZERO-COPY FORWARDING Since physical interfaces share the same memory region, it is possible to do packet forwarding between ports swapping buffers. The buffer from the transmit ring is used to replenish the receive ring: .Pp .Bd -literal -compact uint32_t tmp; struct netmap_slot *src, *dst; ... src = &src_ring->slot[rxr->cur]; dst = &dst_ring->slot[txr->cur]; tmp = dst->buf_idx; dst->buf_idx = src->buf_idx; dst->len = src->len; dst->flags = NS_BUF_CHANGED; src->buf_idx = tmp; src->flags = NS_BUF_CHANGED; rxr->head = rxr->cur = nm_ring_next(rxr, rxr->cur); txr->head = txr->cur = nm_ring_next(txr, txr->cur); ... .Ed .Ss ACCESSING THE HOST STACK The host stack is for all practical purposes just a regular ring pair, which you can access with the netmap API (e.g., with .Dl nm_open("netmap:eth0^", ... ) ; All packets that the host would send to an interface in .Nm mode end up into the RX ring, whereas all packets queued to the TX ring are send up to the host stack. .Ss VALE SWITCH A simple way to test the performance of a .Nm VALE switch is to attach a sender and a receiver to it, e.g., running the following in two different terminals: .Dl pkt-gen -i vale1:a -f rx # receiver .Dl pkt-gen -i vale1:b -f tx # sender The same example can be used to test netmap pipes, by simply changing port names, e.g., .Dl pkt-gen -i vale2:x{3 -f rx # receiver on the master side .Dl pkt-gen -i vale2:x}3 -f tx # sender on the slave side .Pp The following command attaches an interface and the host stack to a switch: .Dl valectl -h vale2:em0 Other .Nm clients attached to the same switch can now communicate with the network card or the host. .Sh SEE ALSO .Xr vale 4 , -.Xr valectl 8 , .Xr bridge 8 , +.Xr valectl 8 , .Xr lb 8 , .Xr nmreplay 8 , .Xr pkt-gen 8 .Pp .Pa http://info.iet.unipi.it/~luigi/netmap/ .Pp Luigi Rizzo, Revisiting network I/O APIs: the netmap framework, Communications of the ACM, 55 (3), pp.45-51, March 2012 .Pp Luigi Rizzo, netmap: a novel framework for fast packet I/O, Usenix ATC'12, June 2012, Boston .Pp Luigi Rizzo, Giuseppe Lettieri, VALE, a switched ethernet for virtual machines, ACM CoNEXT'12, December 2012, Nice .Pp Luigi Rizzo, Giuseppe Lettieri, Vincenzo Maffione, Speeding up packet I/O in virtual machines, ACM/IEEE ANCS'13, October 2013, San Jose .Sh AUTHORS .An -nosplit The .Nm framework has been originally designed and implemented at the Universita` di Pisa in 2011 by .An Luigi Rizzo , and further extended with help from .An Matteo Landi , .An Gaetano Catalli , .An Giuseppe Lettieri , and .An Vincenzo Maffione . .Pp .Nm and .Nm VALE have been funded by the European Commission within FP7 Projects CHANGE (257422) and OPENLAB (287581). .Sh CAVEATS No matter how fast the CPU and OS are, achieving line rate on 10G and faster interfaces requires hardware with sufficient performance. Several NICs are unable to sustain line rate with small packet sizes. Insufficient PCIe or memory bandwidth can also cause reduced performance. .Pp Another frequent reason for low performance is the use of flow control on the link: a slow receiver can limit the transmit speed. Be sure to disable flow control when running high speed experiments. .Ss SPECIAL NIC FEATURES .Nm is orthogonal to some NIC features such as multiqueue, schedulers, packet filters. .Pp Multiple transmit and receive rings are supported natively and can be configured with ordinary OS tools, such as .Xr ethtool 8 or device-specific sysctl variables. The same goes for Receive Packet Steering (RPS) and filtering of incoming traffic. .Pp .Nm .Em does not use features such as .Em checksum offloading , TCP segmentation offloading , .Em encryption , VLAN encapsulation/decapsulation , etc. When using netmap to exchange packets with the host stack, make sure to disable these features. diff --git a/share/man/man4/ntb_hw_intel.4 b/share/man/man4/ntb_hw_intel.4 index 67dc0b838185..cb538b91511d 100644 --- a/share/man/man4/ntb_hw_intel.4 +++ b/share/man/man4/ntb_hw_intel.4 @@ -1,100 +1,100 @@ .\" .\" Copyright (c) 2016-2017 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. .\" .\" $FreeBSD$ .\" .Dd October 11, 2020 .Dt NTB_HW_INTEL 4 .Os .Sh NAME .Nm ntb_hw_intel .Nd Intel(R) Non-Transparent Bridge driver .Sh SYNOPSIS To compile this driver into your kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device ntb" .Cd "device ntb_hw_intel" .Ed .Pp Or, to load the driver as a module at boot, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent ntb_hw_intel_load="YES" .Ed .Sh DESCRIPTION The .Nm ntb_hw_intel driver provides support for the Non-Transparent Bridge (NTB) hardware in Intel Xeon E3/E5 and S1200 processor families, which allow one of their PCIe ports to be switched from transparent to non-transparent bridge mode. In this mode the bridge looks not like a PCI bridge, but like a PCI endpoint device. The driver hides hardware details, exposing memory windows, scratchpads and doorbells of the other side via a hardware independent KPI to the .Xr ntb 4 subsystem. .Pp The hardware provides 2 or 3 memory windows to the other system's memory, 16 scratchpad registers and 14, 31 or 34 doorbells to interrupt the other system, depending on the platform. On Xeon processors one of the memory windows is typically consumed by the driver itself to work around multiple hardware errata. .Sh CONFIGURATION The NTB configuration should be set by BIOS. It includes enabling NTB, choosing between NTB-to-NTB (back-to-back) or NTB-to-Root Port mode, enabling split BAR mode (one of two 64-bit BARs can be split into two 32-bit ones) and configuring BAR sizes in bits (from 12 to 29/39) for both NTB sides. .Pp The recommended configuration is NTB-to-NTB mode, split bar enabled and all BAR sizes set to 20 (1 MiB). This needs to be done on both systems. Note, on Xeon SkyLake and newer platforms, split bar mode is not available. .Sh SEE ALSO .Xr if_ntb 4 , -.Xr ntb_transport 4 , .Xr ntb 4 , +.Xr ntb_transport 4 .Sh AUTHORS .An -nosplit The .Nm driver was developed by Intel and originally written by .An Carl Delsey Aq Mt carl@FreeBSD.org . Later improvements were done by .An Conrad E. Meyer Aq Mt cem@FreeBSD.org and .An Alexander Motin Aq Mt mav@FreeBSD.org . .Sh BUGS NTB-to-Root Port mode is not yet supported, but it doesn't look very useful. .Pp On Xeon v2/v3/v4 processors split BAR mode should be enabled to allow SB01BASE_LOCKUP errata workaround to be applied by the driver. .Pp There is no way to protect your system from malicious behavior on the other system once the link is brought up. Anyone with root or kernel access on the other system can read or write to any location on your system. In other words, only connect two systems that completely trust each other. diff --git a/share/man/man4/numa.4 b/share/man/man4/numa.4 index 069eac68d955..89f1bcb5684d 100644 --- a/share/man/man4/numa.4 +++ b/share/man/man4/numa.4 @@ -1,154 +1,152 @@ .\" Copyright (c) 2015 Adrian Chadd .\" 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 AUTHORS 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 AUTHORS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd October 22, 2018 .Dt NUMA 4 .Os .Sh NAME .Nm NUMA .Nd Non-Uniform Memory Access .Sh SYNOPSIS .Cd options MAXMEMDOM .Cd options NUMA -.Pp .Sh DESCRIPTION Non-Uniform Memory Access is a computer architecture design which involves unequal costs between processors, memory and IO devices in a given system. .Pp In a .Nm architecture, the latency to access specific memory or IO devices depends upon which processor the memory or device is attached to. Accessing memory local to a processor is faster than accessing memory that is connected to one of the other processors. .Fx implements NUMA-aware memory allocation policies. By default it attempts to ensure that allocations are balanced across each domain. Users may override the default domain selection policy using .Xr cpuset 1 . .Pp .Nm support is enabled when the .Cd NUMA option is specified in the kernel configuration file. Each platform defines the .Cd MAXMEMDOM constant, which specifies the maximum number of supported NUMA domains. This constant may be specified in the kernel configuration file. .Nm support can be disabled at boot time by setting the .Va vm.numa.disabled tunable to 1. Other values for this tunable are currently ignored. .Pp Thread and process .Nm policies are controlled with the .Xr cpuset_getdomain 2 and .Xr cpuset_setdomain 2 syscalls. The .Xr cpuset 1 tool is available for starting processes with a non-default policy, or to change the policy of an existing thread or process. See .Xr SMP 4 for information about CPU to domain mapping. .Pp Systems with non-uniform access to I/O devices may mark those devices with the local VM domain identifier. Drivers can find out their local domain information by calling .Xr bus_get_domain 9 . .Ss MIB Variables The operation of .Nm is controlled and exposes information with these .Xr sysctl 8 MIB variables: .Pp .Bl -tag -width indent -compact .It Va vm.ndomains The number of VM domains which have been detected. .Pp .It Va vm.phys_locality A table indicating the relative cost of each VM domain to each other. A value of 10 indicates equal cost. A value of -1 means the locality map is not available or no locality information is available. .Pp .It Va vm.phys_segs The map of physical memory, grouped by VM domain. .El .Sh IMPLEMENTATION NOTES The current .Nm implementation is VM-focused. The hardware .Nm domains are mapped into a contiguous, non-sparse VM domain space, starting from 0. Thus, VM domain information (for example, the domain identifier) is not necessarily the same as is found in the hardware specific information. Policy information is available in both struct thread and struct proc. .Sh SEE ALSO .Xr cpuset 1 , .Xr cpuset_getaffinity 2 , .Xr cpuset_setaffinity 2 , .Xr SMP 4 , .Xr bus_get_domain 9 .Sh HISTORY .Nm first appeared in .Fx 9.0 as a first-touch allocation policy with a fail-over to round-robin allocation and was not configurable. It was then modified in .Fx 10.0 to implement a round-robin allocation policy and was also not configurable. .Pp The .Xr numa_getaffinity 2 and .Xr numa_setaffinity 2 syscalls and the .Xr numactl 1 tool first appeared in .Fx 11.0 and were removed in .Fx 12.0 . The current implementation appeared in .Fx 12.0 . -.Pp .Sh AUTHORS This manual page written by .An Adrian Chadd Aq Mt adrian@FreeBSD.org . .Sh NOTES No statistics are kept to indicate how often .Nm allocation policies succeed or fail. diff --git a/share/man/man4/nvme.4 b/share/man/man4/nvme.4 index eb9f9b222f51..a6e57358bac8 100644 --- a/share/man/man4/nvme.4 +++ b/share/man/man4/nvme.4 @@ -1,267 +1,266 @@ .\" .\" Copyright (c) 2012-2016 Intel 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, .\" without modification. .\" 2. Redistributions in binary form must reproduce at minimum a disclaimer .\" substantially similar to the "NO WARRANTY" disclaimer below .\" ("Disclaimer") and any redistribution must be conditioned upon .\" including a substantially similar Disclaimer requirement for further .\" binary redistribution. .\" .\" NO WARRANTY .\" 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 MERCHANTIBILITY AND FITNESS FOR .\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT .\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR 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 DAMAGES. .\" .\" nvme driver man page. .\" .\" Author: Jim Harris .\" .\" $FreeBSD$ .\" .Dd June 6, 2020 .Dt NVME 4 .Os .Sh NAME .Nm nvme .Nd NVM Express core driver .Sh SYNOPSIS To compile this driver into your kernel, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "device nvme" .Ed .Pp Or, to load the driver as a module at boot, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent nvme_load="YES" .Ed .Pp Most users will also want to enable .Xr nvd 4 or .Xr nda 4 to expose NVM Express namespaces as disk devices which can be partitioned. Note that in NVM Express terms, a namespace is roughly equivalent to a SCSI LUN. .Sh DESCRIPTION The .Nm driver provides support for NVM Express (NVMe) controllers, such as: .Bl -bullet .It Hardware initialization .It Per-CPU IO queue pairs .It API for registering NVMe namespace consumers such as .Xr nvd 4 or .Xr nda 4 .It API for submitting NVM commands to namespaces .It Ioctls for controller and namespace configuration and management .El .Pp The .Nm driver creates controller device nodes in the format .Pa /dev/nvmeX and namespace device nodes in the format .Pa /dev/nvmeXnsY . Note that the NVM Express specification starts numbering namespaces at 1, not 0, and this driver follows that convention. .Sh CONFIGURATION By default, .Nm will create an I/O queue pair for each CPU, provided enough MSI-X vectors and NVMe queue pairs can be allocated. If not enough vectors or queue pairs are available, nvme(4) will use a smaller number of queue pairs and assign multiple CPUs per queue pair. .Pp To force a single I/O queue pair shared by all CPUs, set the following tunable value in .Xr loader.conf 5 : .Bd -literal -offset indent hw.nvme.per_cpu_io_queues=0 .Ed .Pp To assign more than one CPU per I/O queue pair, thereby reducing the number of MSI-X vectors consumed by the device, set the following tunable value in .Xr loader.conf 5 : .Bd -literal -offset indent hw.nvme.min_cpus_per_ioq=X .Ed .Pp To force legacy interrupts for all .Nm driver instances, set the following tunable value in .Xr loader.conf 5 : .Bd -literal -offset indent hw.nvme.force_intx=1 .Ed .Pp Note that use of INTx implies disabling of per-CPU I/O queue pairs. .Pp To control maximum amount of system RAM in bytes to use as Host Memory Buffer for capable devices, set the following tunable: .Bd -literal -offset indent hw.nvme.hmb_max .Ed .Pp The default value is 5% of physical memory size per device. .Pp The .Xr nvd 4 driver is used to provide a disk driver to the system by default. The .Xr nda 4 driver can also be used instead. The .Xr nvd 4 driver performs better with smaller transactions and few TRIM commands. It sends all commands directly to the drive immediately. The .Xr nda 4 driver performs better with larger transactions and also collapses TRIM commands giving better performance. It can queue commands to the drive; combine .Dv BIO_DELETE commands into a single trip; and use the CAM I/O scheduler to bias one type of operation over another. To select the .Xr nda 4 driver, set the following tunable value in .Xr loader.conf 5 : .Bd -literal -offset indent hw.nvme.use_nvd=0 .Ed .Pp This value may also be set in the kernel config file with .Bd -literal -offset indent .Cd options NVME_USE_NVD=0 .Ed .Pp When there is an error, .Nm prints only the most relevant information about the command by default. To enable dumping of all information about the command, set the following tunable value in .Xr loader.conf 5 : .Bd -literal -offset indent hw.nvme.verbose_cmd_dump=1 .Ed .Pp Prior versions of the driver reset the card twice on boot. This proved to be unnecessary and inefficient, so the driver now resets drive controller only once. The old behavior may be restored in the kernel config file with .Bd -literal -offset indent .Cd options NVME_2X_RESET .Ed -.Pp .Sh SYSCTL VARIABLES The following controller-level sysctls are currently implemented: .Bl -tag -width indent .It Va dev.nvme.0.num_cpus_per_ioq (R) Number of CPUs associated with each I/O queue pair. .It Va dev.nvme.0.int_coal_time (R/W) Interrupt coalescing timer period in microseconds. Set to 0 to disable. .It Va dev.nvme.0.int_coal_threshold (R/W) Interrupt coalescing threshold in number of command completions. Set to 0 to disable. .El .Pp The following queue pair-level sysctls are currently implemented. Admin queue sysctls take the format of dev.nvme.0.adminq and I/O queue sysctls take the format of dev.nvme.0.ioq0. .Bl -tag -width indent .It Va dev.nvme.0.ioq0.num_entries (R) Number of entries in this queue pair's command and completion queue. .It Va dev.nvme.0.ioq0.num_tr (R) Number of nvme_tracker structures currently allocated for this queue pair. .It Va dev.nvme.0.ioq0.num_prp_list (R) Number of nvme_prp_list structures currently allocated for this queue pair. .It Va dev.nvme.0.ioq0.sq_head (R) Current location of the submission queue head pointer as observed by the driver. The head pointer is incremented by the controller as it takes commands off of the submission queue. .It Va dev.nvme.0.ioq0.sq_tail (R) Current location of the submission queue tail pointer as observed by the driver. The driver increments the tail pointer after writing a command into the submission queue to signal that a new command is ready to be processed. .It Va dev.nvme.0.ioq0.cq_head (R) Current location of the completion queue head pointer as observed by the driver. The driver increments the head pointer after finishing with a completion entry that was posted by the controller. .It Va dev.nvme.0.ioq0.num_cmds (R) Number of commands that have been submitted on this queue pair. .It Va dev.nvme.0.ioq0.dump_debug (W) Writing 1 to this sysctl will dump the full contents of the submission and completion queues to the console. .El .Pp In addition to the typical pci attachment, the .Nm driver supports attaching to a .Xr ahci 4 device. Intel's Rapid Storage Technology (RST) hides the nvme device behind the AHCI device due to limitations in Windows. However, this effectively hides it from the .Fx kernel. To work around this limitation, .Fx detects that the AHCI device supports RST and when it is enabled. See .Xr ahci 4 for more details. .Sh SEE ALSO .Xr nda 4 , .Xr nvd 4 , .Xr pci 4 , .Xr nvmecontrol 8 , .Xr disk 9 .Sh HISTORY The .Nm driver first appeared in .Fx 9.2 . .Sh AUTHORS .An -nosplit The .Nm driver was developed by Intel and originally written by .An Jim Harris Aq Mt jimharris@FreeBSD.org , with contributions from .An Joe Golio at EMC. .Pp This man page was written by .An Jim Harris Aq Mt jimharris@FreeBSD.org . diff --git a/share/man/man4/pchtherm.4 b/share/man/man4/pchtherm.4 index 96f8e5e129a5..098c1d459867 100644 --- a/share/man/man4/pchtherm.4 +++ b/share/man/man4/pchtherm.4 @@ -1,117 +1,116 @@ .\" .\" Copyright (c) 2020 Takanori Watanabe .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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. .\" .\" $FreeBSD$ .\" .Dd March 15, 2020 .Dt pchtherm 4 .Os .Sh NAME .Nm pchtherm .Nd Intel PCH thermal subsystem .Sh SYNOPSIS .Cd "device pci" .Cd "device pchtherm" .Sh DESCRIPTION The .Nm driver provides access to sensor data and configuration installed in Intel PCH chipset. .Nm configuration register. .Pp The access to .Nm data is made via the .Xr sysctl 8 interface: .Bd -literal dev.pchtherm.0.ctt: 115.0C dev.pchtherm.0.temperature: 28.5C dev.pchtherm.0.t2temp: 91.0C dev.pchtherm.0.t1temp: 86.0C dev.pchtherm.0.t0temp: 81.0C dev.pchtherm.0.tahv: 83.0C dev.pchtherm.0.talv: 30.0C dev.pchtherm.0.pmtime: 32 dev.pchtherm.0.pmtemp: 50.0C dev.pchtherm.0.%parent: pci0 dev.pchtherm.0.%pnpinfo: vendor=0x8086 device=0x9d31 subvendor=0x17aa subdevice=0x2256 class=0x118000 dev.pchtherm.0.%location: slot=20 function=2 dbsf=pci0:0:20:2 dev.pchtherm.0.%driver: pchtherm dev.pchtherm.0.%desc: Skylake PCH Thermal Subsystem dev.pchtherm.%parent: .Ed .Bl -tag -width ".Va dev.pchtherm.%d.pch_hot_level" .It Va dev.pchtherm.%d.temperature Is the read-only value of the current temperature read by the sensor. .It Va dev.pchtherm.%d.ctt When the system reaches this temperature, it will shut down. This will not appear when this feature is disabled and locked down. .It Va dev.pchtherm.%d.t0temp When temperature is under this value, system will be in T0 state. .It Va dev.pchtherm.%d.t1temp When temperature is over .Va t0temp and under this value, system will be in T1 state. .It Va dev.pchtherm.%d.t2temp When temperature is over .Va t1temp and under this value, system will be in T2 state. Over this value, system will be in T3 state. .It Va dev.pchtherm.%d.talv Lower alart value. This will not appear when sensor enable bit is locked down and the value is zero(which will show -50.0C). .It Va dev.pchtherm.%d.tahv High alart value. This will not appear when sensor enable bit is locked down and the value is zero(which will show -50.0C). .It Va dev.pchtherm.%d.pmtemp Sensor Power management temperature. Under this temperature, sensor will idle during .Va pmtime second. .It Va dev.pchtherm.%d.pmtime Sensor idle duration when low temperature. .It Va dev.pchtherm.%d.pch_hot_level When temperature is higher than this value, PCHHOT# pin will assert. This value is not appear when this feature is disabled and locked down. .El .Pp Please check the PCH datasheets for more details. -.Pp .Sh CAVEATS All values are read-only. And it do not support event interrupt for now. .Sh SEE ALSO .Xr sysctl 8 .Sh HISTORY The .Nm driver first appeared in .Fx 13.0 . .Sh AUTHORS .An -nosplit The .Nm driver and this manual page were written by .An Takanori Watanabe Aq Mt takawata@FreeBSD.org . diff --git a/share/man/man4/ppbus.4 b/share/man/man4/ppbus.4 index 030128014c99..41810757735c 100644 --- a/share/man/man4/ppbus.4 +++ b/share/man/man4/ppbus.4 @@ -1,348 +1,348 @@ .\" Copyright (c) 1998, 1999 Nicolas Souchu .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd March 1, 1998 .Dt PPBUS 4 .Os .Sh NAME .Nm ppbus .Nd Parallel Port Bus system .Sh SYNOPSIS .Cd "device ppbus" .Pp .Cd "device lpt" .Cd "device plip" .Cd "device ppi" .Cd "device pps" .Cd "device lpbb" .Sh DESCRIPTION The .Em ppbus system provides a uniform, modular and architecture-independent system for the implementation of drivers to control various parallel devices, and to utilize different parallel port chipsets. .Sh DEVICE DRIVERS In order to write new drivers or port existing drivers, the ppbus system provides the following facilities: .Bl -bullet -offset indent .It architecture-independent macros or functions to access parallel ports .It mechanism to allow various devices to share the same parallel port .It a user interface named .Xr ppi 4 that allows parallel port access from outside the kernel without conflicting with kernel-in drivers. .El .Ss Developing new drivers The ppbus system has been designed to support the development of standard and non-standard software: .Pp .Bl -column "Driver" -compact .It Em Driver Ta Em Description .It Sy ppi Ta "Parallel port interface for general I/O" .It Sy pps Ta "Pulse per second Timing Interface" .It Sy lpbb Ta "Philips official parallel port I2C bit-banging interface" .El .Ss Porting existing drivers Another approach to the ppbus system is to port existing drivers. Various drivers have already been ported: .Pp .Bl -column "Driver" -compact .It Em Driver Ta Em Description .It Sy lpt Ta "lpt printer driver" .It Sy plip Ta "lp parallel network interface driver" .El .Pp ppbus should let you port any other software even from other operating systems that provide similar services. .Sh PARALLEL PORT CHIPSETS Parallel port chipset support is provided by .Xr ppc 4 . .Pp The ppbus system provides functions and macros to allocate a new parallel port bus, then initialize it and upper peripheral device drivers. .Pp ppc makes chipset detection and initialization and then calls ppbus attach functions to initialize the ppbus system. .Sh PARALLEL PORT MODEL The logical parallel port model chosen for the ppbus system is the PC's parallel port model. Consequently, for the i386 implementation of ppbus, most of the services provided by ppc are macros for inb() and outb() calls. But, for another architecture, accesses to one of our logical registers (data, status, control...) may require more than one I/O access. .Ss Description The parallel port may operate in the following modes: .Bl -bullet -offset indent .It compatible mode, also called Centronics mode .It bidirectional 8/4-bits mode, also called NIBBLE mode .It byte mode, also called PS/2 mode .It Extended Capability Port mode, ECP .It Enhanced Parallel Port mode, EPP .It mixed ECP+EPP or ECP+PS/2 modes .El .Ss Compatible mode This mode defines the protocol used by most PCs to transfer data to a printer. In this mode, data is placed on the port's data lines, the printer status is checked for no errors and that it is not busy, and then a data Strobe is generated by the software to clock the data to the printer. .Pp Many I/O controllers have implemented a mode that uses a FIFO buffer to transfer data with the Compatibility mode protocol. This mode is referred to as "Fast Centronics" or "Parallel Port FIFO mode". .Ss Bidirectional mode The NIBBLE mode is the most common way to get reverse channel data from a printer or peripheral. Combined with the standard host to printer mode, it provides a complete bidirectional channel. .Pp In this mode, outputs are 8-bits long. Inputs are accomplished by reading 4 of the 8 bits of the status register. .Ss Byte mode In this mode, the data register is used either for outputs and inputs. Then, any transfer is 8-bits long. .Ss Extended Capability Port mode The ECP protocol was proposed as an advanced mode for communication with printer and scanner type peripherals. Like the EPP protocol, ECP mode provides for a high performance bidirectional communication path between the host adapter and the peripheral. .Pp ECP protocol features include: .Bl -item -offset indent .It Run_Length_Encoding (RLE) data compression for host adapters .It FIFOs for both the forward and reverse channels .It DMA as well as programmed I/O for the host register interface. .El .Ss Enhanced Parallel Port mode The EPP protocol was originally developed as a means to provide a high performance parallel port link that would still be compatible with the standard parallel port. .Pp The EPP mode has two types of cycle: address and data. What makes the difference at hardware level is the strobe of the byte placed on the data lines. Data are strobed with nAutofeed, addresses are strobed with nSelectin signals. .Pp A particularity of the ISA implementation of the EPP protocol is that an EPP cycle fits in an ISA cycle. In this fashion, parallel port peripherals can operate at close to the same performance levels as an equivalent ISA plug-in card. .Pp At software level, you may implement the protocol you wish, using data and address cycles as you want. This is for the IEEE1284 compatible part. Then, peripheral vendors may implement protocol handshake with the following status lines: PError, nFault and Select. Try to know how these lines toggle with your peripheral, allowing the peripheral to request more data, stop the transfer and so on. .Pp At any time, the peripheral may interrupt the host with the nAck signal without disturbing the current transfer. .Ss Mixed modes Some manufacturers, like SMC, have implemented chipsets that support mixed modes. With such chipsets, mode switching is available at any time by accessing the extended control register. .Sh IEEE1284-1994 Standard .Ss Background This standard is also named "IEEE Standard Signaling Method for a Bidirectional Parallel Peripheral Interface for Personal Computers". It defines a signaling method for asynchronous, fully interlocked, bidirectional parallel communications between hosts and printers or other peripherals. It also specifies a format for a peripheral identification string and a method of returning this string to the host outside of the bidirectional data stream. .Pp This standard is architecture independent and only specifies dialog handshake at signal level. One should refer to architecture specific documentation in order to manipulate machine dependent registers, mapped memory or other methods to control these signals. .Pp The IEEE1284 protocol is fully oriented with all supported parallel port modes. The computer acts as master and the peripheral as slave. .Pp Any transfer is defined as a finite state automaton. It allows software to properly manage the fully interlocked scheme of the signaling method. The compatible mode is supported "as is" without any negotiation because it is compatible. Any other mode must be firstly negotiated by the host to check it is supported by the peripheral, then to enter one of the forward idle states. .Pp At any time, the slave may want to send data to the host. This is only possible from forward idle states (nibble, byte, ecp...). So, the host must have previously negotiated to permit the peripheral to request transfer. Interrupt lines may be dedicated to the requesting signals to prevent time consuming polling methods. .Pp But peripheral requests are only a hint to the master host. If the host accepts the transfer, it must firstly negotiate the reverse mode and then starts the transfer. At any time during reverse transfer, the host may terminate the transfer or the slave may drive wires to signal that no more data is available. .Ss Implementation IEEE1284 Standard support has been implemented at the top of the ppbus system as a set of procedures that perform high level functions like negotiation, termination, transfer in any mode without bothering you with low level characteristics of the standard. .Pp IEEE1284 interacts with the ppbus system as little as possible. That means you still have to request the ppbus when you want to access it, the negotiate function does not do it for you. And of course, release it later. .Sh ARCHITECTURE .Ss adapter, ppbus and device layers First, there is the .Em adapter layer, the lowest of the ppbus system. It provides chipset abstraction throw a set of low level functions that maps the logical model to the underlying hardware. .Pp Secondly, there is the .Em ppbus layer that provides functions to: .Bl -enum -offset indent .It share the parallel port bus among the daisy-chain like connected devices .It manage devices linked to ppbus .It propose an arch-independent interface to access the hardware layer. .El .Pp Finally, the .Em device layer gathers the parallel peripheral device drivers. .Ss Parallel modes management We have to differentiate operating modes at various ppbus system layers. Actually, ppbus and adapter operating modes on one hands and for each one, current and available modes are separated. .Pp With this level of abstraction a particular chipset may commute from any native mode to any other mode emulated with extended modes without disturbing upper layers. For example, most chipsets support NIBBLE mode as native and emulated with ECP and/or EPP. .Pp This architecture should support IEEE1284-1994 modes. .Sh FEATURES .Ss The boot process The boot process starts with the probe stage of the .Xr ppc 4 driver during ISA bus (PC architecture) initialization. During attachment of the ppc driver, a new ppbus structure is allocated, then probe and attachment for this new bus node are called. .Pp ppbus attachment tries to detect any PnP parallel peripheral (according to .%T "Plug and Play Parallel Port Devices" draft from (c)1993-4 Microsoft Corporation) then probes and attaches known device drivers. .Pp During probe, device drivers are supposed to request the ppbus and try to set their operating mode. This mode will be saved in the context structure and returned each time the driver requests the ppbus. .Ss Bus allocation and interrupts ppbus allocation is mandatory not to corrupt I/O of other devices. Another usage of ppbus allocation is to reserve the port and receive incoming interrupts. .Pp High level interrupt handlers are connected to the ppbus system thanks to the newbus .Fn BUS_SETUP_INTR and .Fn BUS_TEARDOWN_INTR functions. But, in order to attach a handler, drivers must own the bus. Consequently, a ppbus request is mandatory in order to call the above functions (see existing drivers for more info). Note that the interrupt handler is automatically released when the ppbus is released. .Ss Microsequences .Em Microsequences is a general purpose mechanism to allow fast low-level manipulation of the parallel port. Microsequences may be used to do either standard (in IEEE1284 modes) or non-standard transfers. The philosophy of microsequences is to avoid the overhead of the ppbus layer and do most of the job at adapter level. .Pp A microsequence is an array of opcodes and parameters. Each opcode codes an operation (opcodes are described in .Xr microseq 9 ) . Standard I/O operations are implemented at ppbus level whereas basic I/O operations and microseq language are coded at adapter level for efficiency. .Sh SEE ALSO .Xr lpt 4 , .Xr plip 4 , .Xr ppc 4 , -.Xr ppi 4 , +.Xr ppi 4 .Sh HISTORY The .Nm manual page first appeared in .Fx 3.0 . .Sh AUTHORS This manual page was written by .An Nicolas Souchu . diff --git a/share/man/man4/rtwn_usb.4 b/share/man/man4/rtwn_usb.4 index 0ead332bd591..e6c2a2a89823 100644 --- a/share/man/man4/rtwn_usb.4 +++ b/share/man/man4/rtwn_usb.4 @@ -1,133 +1,133 @@ .\"- .\" Copyright (c) 2011 Adrian Chadd, Xenion Pty Ltd .\" Copyright (c) 2016 Andriy Voskoboinyk .\" 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, .\" without modification. .\" 2. Redistributions in binary form must reproduce at minimum a disclaimer .\" similar to the "NO WARRANTY" disclaimer below ("Disclaimer") and any .\" redistribution must be conditioned upon including a substantially .\" similar Disclaimer requirement for further binary redistribution. .\" .\" NO WARRANTY .\" 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 NONINFRINGEMENT, MERCHANTIBILITY .\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL .\" THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR 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 DAMAGES. .\" .\" $FreeBSD$ .\"/ .Dd November 1, 2021 .Dt RTWN_USB 4 .Os .Sh NAME .Nm rtwn_usb .Nd "Realtek USB device glue" .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device xhci" .Cd "device ehci" .Cd "device uhci" .Cd "device ohci" .Cd "device usb" .Cd "device rtwn" .Cd "device rtwn_usb" .Cd "device wlan" .Ed -.SH DESCRIPTION +.Sh DESCRIPTION This module provides the USB bus glue needed for the devices supported by the .Xr rtwn 4 driver. .Sh HARDWARE The .Nm driver supports Realtek RTL8188CUS/RTL8188RU/RTL8188EU/RTL8192CU/RTL8192EU/RTL8812AU/RTL8821AU based USB wireless network adapters, including: .Pp .Bl -column -compact "Belkin F7D1102 Surf Wireless Micro" "RTL8188CUS" "Bus" .It Em Card Ta Em Chip Ta Em Bus .It "Alfa AWUS036NHR v2" Ta RTL8188RU Ta USB 2.0 .It "ASUS USB-AC56" Ta RTL8812AU Ta USB 3.0 .It "ASUS USB-N10 NANO" Ta RTL8188CUS Ta USB 2.0 .It "ASUS USB-N10 NANO rev B1" Ta RTL8188EUS Ta USB 2.0 .It "Asus USB-N13, rev. B1" Ta RTL8192CU Ta USB 2.0 .It "Belkin F7D1102 Surf Wireless Micro" Ta RTL8188CUS Ta USB 2.0 .It "Buffalo WI-U2-433DHP" Ta RTL8821AU Ta USB 2.0 .It "Buffalo WI-U2-433DM" Ta RTL8821AU Ta USB 2.0 .It "Buffalo WI-U3-866D" Ta RTL8812AU Ta USB 3.0 .It "D-Link DWA-121 rev C1A (N150 Nano)" Ta RTL8188EU Ta USB 2.0 .It "D-Link DWA-123 rev D1" Ta RTL8188EU Ta USB 2.0 .It "D-Link DWA-125 rev D1" Ta RTL8188EU Ta USB 2.0 .It "D-Link DWA-131" Ta RTL8192CU Ta USB 2.0 .It "D-Link DWA-131 rev E1" Ta RTL8192EU Ta USB 2.0 .It "D-Link DWA-171 rev A1" Ta RTL8821AU Ta USB 2.0 .It "D-Link DWA-172 rev A1" Ta RTL8821AU Ta USB 2.0 .It "D-Link DWA-180 rev A1" Ta RTL8812AU Ta USB 2.0 .It "D-Link DWA-182 rev C1" Ta RTL8812AU Ta USB 3.0 .It "Edimax EW-7811Un" Ta RTL8188CUS Ta USB 2.0 .It "Edimax EW-7811UTC" Ta RTL8821AU Ta USB 2.0 .It "Edimax EW-7822UAC" Ta RTL8812AU Ta USB 3.0 .It "EDUP EP-AC1620" Ta RTL8821AU Ta USB 2.0 .It "Elecom WDC-150SU2M" Ta RTL8188EU Ta USB 2.0 .It "EnGenius EUB1200AC" Ta RTL8812AU Ta USB 3.0 .It "Foxconn WFUR6" Ta RTL8812AU Ta USB 2.0 .It "Hawking HD65U" Ta RTL8821AU Ta USB 2.0 .It "Hercules Wireless N USB Pico" Ta RTL8188CUS Ta USB 2.0 .It "I-O Data WN-AC867U" Ta RTL8812AU Ta USB 3.0 .It "Linksys WUSB6300" Ta RTL8812AU Ta USB 3.0 .It "NEC AtermWL900U PA-WL900U" Ta RTL8812AU Ta USB 3.0 .It "Netgear A6100" Ta RTL8821AU Ta USB 2.0 .It "Netgear WNA1000M" Ta RTL8188CUS Ta USB 2.0 .It "Mercusys MW150US" Ta RTL8188EU Ta USB 2.0 .It "Planex GW-900D" Ta RTL8812AU Ta USB 3.0 .It "Realtek RTL8192CU" Ta RTL8192CU Ta USB 2.0 .It "Realtek RTL8188CUS" Ta RTL8188CUS Ta USB 2.0 .It "Sitecom WLA-7100" Ta RTL8812AU Ta USB 3.0 .It "TP-Link Archer T2U Nano" Ta RTL8821AU Ta USB 2.0 .It "TP-Link Archer T2U Plus" Ta RTL8821AU Ta USB 2.0 .It "TP-Link Archer T2U v3" Ta RTL8821AU Ta USB 2.0 .It "TP-Link Archer T4U" Ta RTL8812AU Ta USB 3.0 .It "TP-Link Archer T4U v2" Ta RTL8812AU Ta USB 3.0 .It "TP-Link Archer T4UH v1" Ta RTL8812AU Ta USB 3.0 .It "TP-Link Archer T4UH v2" Ta RTL8812AU Ta USB 3.0 .It "TP-Link TL-WN722N v2" Ta RTL8188EU Ta USB 2.0 .It "TP-LINK TL-WN723N v3" Ta RTL8188EU Ta USB 2.0 .It "TP-LINK TL-WN725N v2" Ta RTL8188EU Ta USB 2.0 .It "TP-LINK TL-WN727N v5" Ta RTL8188EU Ta USB 2.0 .It "TP-LINK TL-WN821N v4" Ta RTL8192CU Ta USB 2.0 .It "TP-LINK TL-WN821N v5" Ta RTL8192EU Ta USB 2.0 .It "TP-LINK TL-WN822N v4" Ta RTL8192EU Ta USB 2.0 .It "TP-LINK TL-WN823N v1" Ta RTL8192CU Ta USB 2.0 .It "TP-LINK TL-WN823N v2" Ta RTL8192EU Ta USB 2.0 .It "TRENDnet TEW-805UB" Ta RTL8812AU Ta USB 3.0 .It "ZyXEL NWD6605" Ta RTL8812AU Ta USB 3.0 .El .Sh SEE ALSO .Xr rtwn 4 , .Xr rtwn_pci 4 , .Xr rtwnfw 4 , .Xr usb 4 .Sh BUGS The .Nm driver does not support any of the 802.11ac capabilities offered by the adapters. Additional work is required in .Xr ieee80211 9 before those features can be supported. diff --git a/share/man/man4/scsi.4 b/share/man/man4/scsi.4 index e4c6d9a53eb4..79e7ab322611 100644 --- a/share/man/man4/scsi.4 +++ b/share/man/man4/scsi.4 @@ -1,529 +1,528 @@ .\" Copyright (c) 1996 .\" Julian Elischer . All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .Dd November 3, 2021 .Dt CAM 4 .Os .Sh NAME .Nm CAM .Nd Common Access Method Storage subsystem .Sh SYNOPSIS .Cd "device scbus" .Cd "device ada" .Cd "device cd" .Cd "device ch" .Cd "device da" .Cd "device pass" .Cd "device pt" .Cd "device sa" .Cd "options CAMDEBUG" .Cd "options CAM_DEBUG_BUS=-1" .Cd "options CAM_DEBUG_TARGET=-1" .Cd "options CAM_DEBUG_LUN=-1" .Cd "options CAM_DEBUG_COMPILE=CAM_DEBUG_INFO|CAM_DEBUG_CDB|CAM_DEBUG_PROBE" .Cd "options CAM_DEBUG_FLAGS=CAM_DEBUG_INFO|CAM_DEBUG_CDB" .Cd "options CAM_MAX_HIGHPOWER=4" .Cd "options SCSI_NO_SENSE_STRINGS" .Cd "options SCSI_NO_OP_STRINGS" .Cd "options SCSI_DELAY=8000" .Sh DESCRIPTION The .Nm subsystem provides a uniform and modular system for the implementation of drivers to control various .Tn SCSI , .Tn ATA , .Tn NVMe , and .Tn MMC / SD devices, and to utilize different .Tn SCSI , .Tn ATA , .Tn NVMe , and .Tn MMC / SD host adapters through host adapter drivers. When the system probes buses, it attaches any devices it finds to the appropriate drivers. The .Xr pass 4 driver, if it is configured in the kernel, will attach to all devices. .Sh KERNEL CONFIGURATION There are a number of generic kernel configuration options for the .Nm subsystem: .Bl -tag -width SCSI_NO_SENSE_STRINGS .It Dv CAM_BOOT_DELAY Additional time to wait after the static parts of the kernel have run to allow for discovery of additional devices which may take time to connect, such as USB attached storage. .It Dv CAM_IOSCHED_DYNAMIC Enable dynamic decisions in the I/O scheduler based on hints and the current performance of the storage devices. .It Dv CAM_IO_STATS Enable collection of statistics for periph devices. .It Dv CAM_TEST_FAILURE Enable ability to simulate I/O failures. .It Dv CAMDEBUG This option compiles in all the .Nm debugging printf code. This will not actually cause any debugging information to be printed out when included by itself. See below for details. .It Dv "CAM_MAX_HIGHPOWER=4" This sets the maximum allowable number of concurrent "high power" commands. A "high power" command is a command that takes more electrical power than most to complete. An example of this is the .Tn SCSI START UNIT command. Starting a disk often takes significantly more electrical power than normal operation. This option allows the user to specify how many concurrent high power commands may be outstanding without overloading the power supply on his computer. .It Dv SCSI_NO_SENSE_STRINGS This eliminates text descriptions of each .Tn SCSI Additional Sense Code and Additional Sense Code Qualifier pair. Since this is a fairly large text database, eliminating it reduces the size of the kernel somewhat. This is primarily necessary for boot floppies and other low disk space or low memory space environments. In most cases, though, this should be enabled, since it speeds the interpretation of .Tn SCSI error messages. Do not let the "kernel bloat" zealots get to you -- leave the sense descriptions in your kernel! .It Dv SCSI_NO_OP_STRINGS This disables text descriptions of each .Tn SCSI opcode. This option, like the sense string option above, is primarily useful for environments like a boot floppy where kernel size is critical. Enabling this option for normal use is not recommended, since it slows debugging of .Tn SCSI problems. .It Dv SCSI_DELAY=8000 This is the .Tn SCSI "bus settle delay." In .Nm , it is specified in .Em milliseconds , not seconds like the old .Tn SCSI layer used to do. When the kernel boots, it sends a bus reset to each .Tn SCSI bus to tell each device to reset itself to a default set of transfer negotiations and other settings. Most .Tn SCSI devices need some amount of time to recover from a bus reset. Newer disks may need as little as 100ms, while old, slow devices may need much longer. If the .Dv SCSI_DELAY is not specified, it defaults to 2 seconds. The minimum allowable value for .Dv SCSI_DELAY is "100", or 100ms. One special case is that if the .Dv SCSI_DELAY is set to 0, that will be taken to mean the "lowest possible value." In that case, the .Dv SCSI_DELAY will be reset to 100ms. .El .Pp All devices and buses support dynamic allocation so that an upper number of devices and controllers does not need to be configured; .Cd "device da" will suffice for any number of disk drivers. .Pp The devices are either .Em wired so they appear as a particular device unit or .Em counted so that they appear as the next available unused unit. .Pp Units are wired down by setting kernel environment hints. This is usually done either interactively from the .Xr loader 8 , or automatically via the .Pa /boot/device.hints file. The basic syntax is: .Bd -literal -offset indent hint.device.unit.property="value" .Ed .Pp Individual .Nm bus numbers can be wired down to specific controllers with a config line similar to the following: .Bd -literal -offset indent hint.scbus.0.at="ahd1" .Ed .Pp This assigns .Nm bus number 0 to the .Em ahd1 driver instance. For controllers supporting more than one bus, a particular bus can be assigned as follows: .Bd -literal -offset indent hint.scbus.0.at="ahc1" hint.scbus.0.bus="1" .Ed .Pp This assigns .Nm bus 0 to the bus 1 instance on .Em ahc1 . Peripheral drivers can be wired to a specific bus, target, and lun as so: .Bd -literal -offset indent hint.da.0.at="scbus0" hint.da.0.target="0" hint.da.0.unit="0" .Ed .Pp This assigns .Em da0 to target 0, unit (lun) 0 of scbus 0. Omitting the target or unit hints will instruct .Nm to treat them as wildcards and use the first respective counted instances. These examples can be combined together to allow a peripheral device to be wired to any particular controller, bus, target, and/or unit instance. .Pp This also works with .Xr nvme 4 drives as well. .Bd -literal -offset indent hint.nvme.4.at="pci7:0:0" hint.scbus.10.at="nvme4" hint.nda.10.at="scbus10" hint.nda.10.target="1" hint.nda.10.unit="12" hint.nda.11.at="scbus10" hint.nda.11.target="1" hint.nda.11.unit="2" .Ed .Pp This assigns the NVMe card living at PCI bus 7 slot 0 function 1 to scbus 10. The target for .Xr nda 4 devices is always 1. The unit is the namespace identifier from the drive. The namespace id 1 is exported as .Em nda10 and namespace id 2 is exported as .Em nda11 . .Pp For devices that provide a serial number, units may be wired to that serial number without regard where the drive is attached: .Bd -literal -offset indent hint.nda.3.sn="CY0AN07101120B12P" hint.da.44.sn="143282400011" hint.ada.2.sn="A065D591" .Ed wires .Em nda3 , .Em da44 , and .Em ada2 to drives with the specified serial numbers. One need not specify an .Em at line when serial numbers are used. .Sh ADAPTERS The system allows common device drivers to work through many different types of adapters. The adapters take requests from the upper layers and do all IO between the .Tn SCSI , .Tn ATA , .Tn NVMe , or .Tn MMC / SD bus and the system. The maximum size of a transfer is governed by the adapter. Most adapters can transfer 64KB in a single operation, however many can transfer larger amounts. .Sh TARGET MODE Some adapters support .Em target mode in which the system is capable of operating as a device, responding to operations initiated by another system. Target mode is supported for some adapters, but is not yet complete for this version of the .Nm .Tn SCSI subsystem. .Sh ARCHITECTURE The .Nm subsystem glues together the upper layers of the system to the storage devices. PERIPH devices accept storage requests from GEOM and other upper layers of the system and translates them into protocol requests. XPT (transport) dispatches these protocol requests to a SIM driver. A SIM driver takes protocol requests and translates them into hardware commands the host adapter understands to transfer the protocol requests, and data (if any) to the storage device. The CCB transports these requests around as messages. .Ss CAM The Common Access Method was a standard defined in the 1990s to talk to disk drives. .Fx is one of the few operating systems to fully implement this model. The interface between different parts of CAM is the CCB (or CAM Control Block). Each CCB has a standard header, which contains the type of request and dispatch information, and a command specific portion. A CAM Periph generates requests. The XPT layer dispatches these requests to the appropriate SIM. Some CCBs are sent directly to the SIM for immediate processing, while others are queued and complete when the I/O has finished. A SIM takes CCBs and translates them into hardware specific commands to push the SCSI CDB or other protocol control block to the peripheral, along with setting up the DMA for the associated data. .Ss Periph Devices A periph driver knows how to translate standard requests into protocol messages that a SIM can deliver to hardware. These requests can come from any upper layer source, but primarily come in via GEOM as a bio request. They can also come in directly from character device requests for tapes and pass through commands. .Pp Disk devices, or direct access (da) in CAM, are one type of peripheral. These devices present themselves to the kernel a device ending in .Dq da . Each protocol has a unique device name: .Bl -tag -width 4 .It Xr da 4 SCSI or SAS device, or devices that accept SCSI CDBs for I/O. .It Xr ada 4 ATA or SATA device .It Xr nda 4 NVME device .It Xr sdda 4 An SD or MMC block storage device. .El .Pp Tape devices are called serial access .Po .Xr sa 4 .Pc in CAM. They interface to the system via a character device and provide .Xr ioctl 2 control for tape drives. .Pp The .Xr pass 4 device will pass through CCB requests from userland to the SIM directly. The device is used to send commands other than read, write, trim or flush to a device. The .Xr camcontrol 8 command uses this device. .Ss XPT drivers The transport driver connects the periph to the SIM. It is not configured separately. It is also responsible for device discovery for those SIM drivers that do not enumerate themselves. .Ss SIM driver SIM used to stand for SCSI Interface Module. Now it is just SIM because it understands protocols other than SCSI. There are two types of SIM drivers: virtual and physical. Physical SIMs are typically called host bus adapters (HBA), but not universally. Virtual SIM drivers are for communicating with virtual machine hosts. .Sh FILES see other .Nm device entries. .Sh DIAGNOSTICS An XPT_DEBUG CCB can be used to enable various amounts of tracing information on any specific bus/device from the list of options compiled into the kernel. There are currently seven debugging flags that may be compiled in and used: .Bl -tag -width CAM_DEBUG_SUBTRACE .It Dv CAM_DEBUG_INFO This flag enables general informational printfs for the device or devices in question. .It Dv CAM_DEBUG_TRACE This flag enables function-level command flow tracing i.e., kernel printfs will happen at the entrance and exit of various functions. .It Dv CAM_DEBUG_SUBTRACE This flag enables debugging output internal to various functions. .It Dv CAM_DEBUG_CDB This flag will cause the kernel to print out all .Tn ATA and .Tn SCSI commands sent to a particular device or devices. .It Dv CAM_DEBUG_XPT This flag will enable command scheduler tracing. .It Dv CAM_DEBUG_PERIPH This flag will enable peripheral drivers messages. .It Dv CAM_DEBUG_PROBE This flag will enable devices probe process tracing. .El .Pp Some of these flags, most notably .Dv CAM_DEBUG_TRACE and .Dv CAM_DEBUG_SUBTRACE , will produce kernel printfs in EXTREME numbers. .Pp Users can enable debugging from their kernel config file, by using the following kernel config options: .Bl -tag -width CAM_DEBUG_COMPILE .It Dv CAMDEBUG This builds into the kernel all possible .Nm debugging. .It Dv CAM_DEBUG_COMPILE This specifies support for which debugging flags described above should be built into the kernel. Flags may be ORed together if the user wishes to see printfs for multiple debugging levels. .It Dv CAM_DEBUG_FLAGS This sets the various debugging flags from a kernel config file. .It Dv CAM_DEBUG_BUS Specify a bus to debug. To debug all buses, set this to -1. .It Dv CAM_DEBUG_TARGET Specify a target to debug. To debug all targets, set this to -1. .It Dv CAM_DEBUG_LUN Specify a lun to debug. To debug all luns, set this to -1. .El .Pp Users may also enable debugging on the fly by using the .Xr camcontrol 8 utility, if wanted options built into the kernel. See .Xr camcontrol 8 for details. .Sh SEE ALSO .Bl -tag -width 20 .It Sy Commands: .Xr camcontrol 8 , .Xr camdd 8 .It Sy Libraries: .Xr cam 3 .It Sy Periph Drivers: .Xr ada 4 , .Xr da 4 , .Xr nda 4 , .\" .Xr sdda 4 , .Xr pass 4 , .Xr sa 4 -.Pp .It Sy SIM Devices: .Xr aac 4 , .Xr aacraid 4 , .Xr ahc 4 , .Xr ahci 4 , .Xr ata 4 , .Xr aw_mmc 4 , .Xr ciss 4 , .Xr hv_storvsc 4 , .Xr isci 4 , .Xr iscsi 4 , .Xr isp 4 , .\" .Xr mmcnull 4 , .Xr mpr 4 , .Xr mps 4 , .Xr mpt 4 , .Xr mrsas 4 , .Xr mvs 4 , .Xr nvme 4 , .Xr pms 4 , .Xr pvscsi 4 , .Xr sdhci 4 , .Xr smartpqi 4 , .Xr sym 4 , .Xr tws 4 , .Xr umass 4 , .Xr virtio_scsi 4 .It Sy Deprecated or Poorly Supported SIM Devices: .Xr ahd 4 , .Xr amr 4 , .Xr arcmsr 4 , .Xr esp 4 , .\" .Xr fslsata 4 , .Xr hpt27xx 4 , .Xr hptiop 4 , .Xr hptmv 4 , .Xr hptnr 4 , .\" .Xr htprr 4 , .Xr iir 4 .Xr mfi 4 , .\" .Xr osc 4 , .\" .Xr ps3cdrom 4 , .Xr sbp 4 , .Xr twa 4 .El .Sh HISTORY The .Nm .Tn SCSI subsystem first appeared in .Fx 3.0 . The .Nm ATA support was added in .Fx 8.0 . .Sh AUTHORS .An -nosplit The .Nm .Tn SCSI subsystem was written by .An Justin Gibbs and .An Kenneth Merry . The .Nm .Tn ATA support was added by .An Alexander Motin Aq Mt mav@FreeBSD.org . The .Nm .Tn NVMe support was added by .An Warner Losh Aq Mt imp@FreeBSD.org . diff --git a/share/man/man4/smartpqi.4 b/share/man/man4/smartpqi.4 index 65b9530f1498..fbe435ca3a7f 100644 --- a/share/man/man4/smartpqi.4 +++ b/share/man/man4/smartpqi.4 @@ -1,103 +1,103 @@ .\" Copyright (c) 2018 Murthy Bhat .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ stable/10/share/man/man4/smartpqi.4 195614 2017-01-11 08:10:18Z jkim $ .Dd April 6, 2018 .Dt SMARTPQI 4 .Os .Sh NAME .Nm smartpqi .Nd Microsemi smartpqi SCSI driver for PQI controllers .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd device pci .Cd device scbus .Cd device smartpqi .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 smartpqi_load="YES" .Ed .Sh DESCRIPTION The .Nm SCSI driver provides support for the new generation of PQI controllers from Microsemi. The .Nm driver is the first SCSI driver to implement the PQI queuing model. .Pp The .Nm driver will replace the aacraid driver for Adaptec Series 9 controllers. .Pp The .Pa /dev/smartpqi? device nodes provide access to the management interface of the controller. One node exists per installed card. .Sh HARDWARE Controllers supported by the .Nm driver include: .Pp .Bl -bullet -compact .It HPE Gen10 Smart Array Controller Family .It OEM Controllers based on the Microsemi Chipset .El .Sh FILES .Bl -tag -width /boot/kernel/aac.ko -compact .It Pa /dev/smartpqi? smartpqi management interface .El .Sh SEE ALSO .Xr kld 4 , .Xr linux 4 , -.Xr scsi 4 , -.Xr kldload 8 , .Xr pass 4 , +.Xr scsi 4 , .Xr xpt 4 , .Xr loader.conf 5 , -.Xr camcontrol 8 +.Xr camcontrol 8 , +.Xr kldload 8 .Rs .%T "Microsemi Website" .%U https://www.microsemi.com/ .Re .Sh HISTORY The .Nm driver first appeared in .Fx 11.1 . .Sh AUTHORS .An Murthy Bhat .Aq murthy.bhat@microsemi.com .Sh BUGS The controller is not actually paused on suspend/resume. diff --git a/share/man/man4/stf.4 b/share/man/man4/stf.4 index 2b794cd2936e..8ffd2481a08b 100644 --- a/share/man/man4/stf.4 +++ b/share/man/man4/stf.4 @@ -1,342 +1,341 @@ .\" $KAME: stf.4,v 1.35 2001/05/02 06:24:49 itojun Exp $ .\" .\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the project 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 PROJECT 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 PROJECT OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd November 16, 2021 .Dt STF 4 .Os .Sh NAME .Nm stf .Nd .Tn 6to4 tunnel interface .Sh SYNOPSIS .Cd "device stf" .Sh DESCRIPTION The .Nm interface supports .Dq 6to4 and .Dq 6rd IPv6 in IPv4 encapsulation. It can tunnel IPv6 traffic over IPv4, as specified in .Li RFC3056 or .Li RFC5969 . .Pp For ordinary nodes in a 6to4 or 6RD site, you do not need .Nm interface. The .Nm interface is necessary for site border routers (called .Dq 6to4 routers or .Dq 6rd Customer Edge (CE) in the specification). .Pp Each .Nm interface is created at runtime using interface cloning. This is most easily done with the .Xr ifconfig 8 .Cm create command or using the .Va cloned_interfaces variable in .Xr rc.conf 5 . .Sh 6to4 -.Pp Due to the way 6to4 protocol is specified, .Nm interface requires certain configuration to work properly. Single (no more than 1) valid 6to4 address needs to be configured to the interface. .Dq A valid 6to4 address is an address which has the following properties. If any of the following properties are not satisfied, .Nm raises runtime error on packet transmission. Read the specification for more details. .Bl -bullet .It matches .Li 2002:xxyy:zzuu::/48 where .Li xxyy:zzuu is a hexadecimal notation of an IPv4 address for the node. IPv4 address can be taken from any of interfaces your node has. Since the specification forbids the use of IPv4 private address, the address needs to be a global IPv4 address. .It Subnet identifier portion (48th to 63rd bit) and interface identifier portion (lower 64 bits) are properly filled to avoid address collisions. .El .Pp If you would like the node to behave as a relay router, the prefix length for the IPv6 interface address needs to be 16 so that the node would consider any 6to4 destination as .Dq on-link . If you would like to restrict 6to4 peers to be inside certain IPv4 prefix, you may want to configure IPv6 prefix length as .Dq 16 + IPv4 prefix length . .Nm interface will check the IPv4 source address on packets, if the IPv6 prefix length is larger than 16. .Pp .Nm can be configured to be ECN friendly. This can be configured by .Dv IFF_LINK1 . See .Xr gif 4 for details. .Pp Please note that 6to4 specification is written as .Dq accept tunnelled packet from everyone tunnelling device. By enabling .Nm device, you are making it much easier for malicious parties to inject fabricated IPv6 packet to your node. Also, malicious party can inject an IPv6 packet with fabricated source address to make your node generate improper tunnelled packet. Administrators must take caution when enabling the interface. To prevent possible attacks, .Nm interface filters out the following packets. Note that the checks are no way complete: .Bl -bullet .It Packets with IPv4 unspecified address as outer IPv4 source/destination .Pq Li 0.0.0.0/8 .It Packets with loopback address as outer IPv4 source/destination .Pq Li 127.0.0.0/8 .It Packets with IPv4 multicast address as outer IPv4 source/destination .Pq Li 224.0.0.0/4 .It Packets with limited broadcast address as outer IPv4 source/destination .Pq Li 255.0.0.0/8 .It Packets with private address as outer IPv4 source/destination .Pq Li 10.0.0.0/8 , 172.16.0.0/12 , 192.168.0.0/16 .It Packets with subnet broadcast address as outer IPv4 source/destination. The check is made against subnet broadcast addresses for all of the directly connected subnets. .It Packets that does not pass ingress filtering. Outer IPv4 source address must meet the IPv4 topology on the routing table. Ingress filter can be turned off by .Dv IFF_LINK2 bit. .It The same set of rules are applied against the IPv4 address embedded into inner IPv6 address, if the IPv6 address matches 6to4 prefix. .El .Pp It is recommended to filter/audit incoming IPv4 packet with IP protocol number 41, as necessary. It is also recommended to filter/audit encapsulated IPv6 packets as well. You may also want to run normal ingress filter against inner IPv6 address to avoid spoofing. .Pp By setting the .Dv IFF_LINK0 flag on the .Nm interface, it is possible to disable the input path, making the direct attacks from the outside impossible. Note, however, there are other security risks exist. If you wish to use the configuration, you must not advertise your 6to4 address to others. .\" .Sh 6rd Like .Dq 6to4 .Dq 6rd also requires configuration before it can be used. The required configuration parameters are: .Bl -bullet .It The IPv6 address and prefix length. .It The border router IPv4 address. .It The IPv4 WAN address. .It The prefix length of the IPv4 WAN address. .El .Pp These can parameters are all configured through .Xr ifconfig 8 . .Pp The IPv6 address and prefix length can be configured like any other IPv6 address. Note that the prefix length is the IPv6 prefix length excluding the embedded IPv4 address bits. The prefix length of the delegated network is the sum of the IPv6 prefix length and the IPv4 prefix length. .Pp The border router IPv4 address is configured with the .Xr ifconfig 8 .Cm stfv4br command. .Pp The IPv4 WAN address and IPv4 prefix length are configured using the .Xr ifconfig 8 .Cm stfv4net command. .Sh SYSCTL VARIABLES The following .Xr sysctl 8 variables can be used to control the behavior of the .Nm stf . The default value is shown next to each variable. .Bl -tag -width indent .It Va net.link.stf.permit_rfc1918 : No 0 The RFC3056 requires the use of globally unique 32-bit IPv4 addresses. This sysctl variable controls the behaviour of this requirement. When it set to not 0, .Nm stf allows the use of private IPv4 addresses described in the RFC1918. This may be useful for an Intranet environment or when some mechanisms of network address translation (NAT) are used. .El .Sh EXAMPLES Note that .Li 8504:0506 is equal to .Li 133.4.5.6 , written in hexadecimals. .Bd -literal # ifconfig ne0 inet 133.4.5.6 netmask 0xffffff00 # ifconfig stf0 inet6 2002:8504:0506:0000:a00:5aff:fe38:6f86 \\ prefixlen 16 alias .Ed .Pp The following configuration accepts packets from IPv4 source .Li 9.1.0.0/16 only. It emits 6to4 packet only for IPv6 destination 2002:0901::/32 (IPv4 destination will match .Li 9.1.0.0/16 ) . .Bd -literal # ifconfig ne0 inet 9.1.2.3 netmask 0xffff0000 # ifconfig stf0 inet6 2002:0901:0203:0000:a00:5aff:fe38:6f86 \\ prefixlen 32 alias .Ed .Pp The following configuration uses the .Nm interface as an output-only device. You need to have alternative IPv6 connectivity (other than 6to4) to use this configuration. For outbound traffic, you can reach other 6to4 networks efficiently via .Nm stf . For inbound traffic, you will not receive any 6to4-tunneled packets (less security drawbacks). Be careful not to advertise your 6to4 prefix to others .Pq Li 2002:8504:0506::/48 , and not to use your 6to4 prefix as a source. .Bd -literal # ifconfig ne0 inet 133.4.5.6 netmask 0xffffff00 # ifconfig stf0 inet6 2002:8504:0506:0000:a00:5aff:fe38:6f86 \\ prefixlen 16 alias deprecated link0 # route add -inet6 2002:: -prefixlen 16 ::1 # route change -inet6 2002:: -prefixlen 16 ::1 -ifp stf0 .Ed .Pp The following example configures a .Dq 6rd tunnel on a .Dq 6rd CE where the ISP's .Dq 6rd IPv6 prefix is 2001:db8::/32. The border router is 192.0.2.1. The .Dq 6rd CE has a WAN address of 192.0.2.2 and the full IPv4 address is embedded in the .Dq 6rd IPv6 address: .Bd -literal # ifconfig stf0 inet6 2001:db8:c000:0202:: prefixlen 32 up # ifconfig stf0 stfv4br 192.0.2.1 # ifconfig stf0 stfv4net 192.0.2.2/32 .Ed .\" .Sh SEE ALSO .Xr gif 4 , .Xr inet 4 , .Xr inet6 4 .Rs .%A Brian Carpenter .%A Keith Moore .%T "Connection of IPv6 Domains via IPv4 Clouds" .%D February 2001 .%R RFC .%N 3056 .Re .Rs .%A Jun-ichiro itojun Hagino .%T "Possible abuse against IPv6 transition technologies" .%D July 2000 .%N draft-itojun-ipv6-transition-abuse-01.txt .%O work in progress .Re .\" .Sh HISTORY The .Nm device first appeared in WIDE/KAME IPv6 stack. .\" .Sh BUGS No more than one .Nm interface is allowed for a node, and no more than one IPv6 interface address is allowed for an .Nm interface. It is to avoid source address selection conflicts between IPv6 layer and IPv4 layer, and to cope with ingress filtering rule on the other side. This is a feature to make .Nm work right for all occasions. diff --git a/share/man/man4/sym.4 b/share/man/man4/sym.4 index 7df2a0ec320e..222f3f54e96e 100644 --- a/share/man/man4/sym.4 +++ b/share/man/man4/sym.4 @@ -1,326 +1,327 @@ .\" .\" Device driver optimized for the Symbios/LSI 53C896/53C895A/53C1010 .\" PCI SCSI controllers. .\" .\" Copyright (C) 1999-2000 Gerard Roudier .\" .\" This driver also supports the following Symbios/LSI PCI SCSI chips: .\" 53C810A, 53C825A, 53C860, 53C875, 53C876, 53C885, 53C895, .\" 53C810, 53C815, 53C825 and the 53C1510D is 53C8XX mode. .\" .\" .\" This driver for FreeBSD-CAM is derived from the Linux sym53c8xx driver. .\" Copyright (C) 1998-1999 Gerard Roudier .\" .\" The sym53c8xx driver is derived from the ncr53c8xx driver that had been .\" a port of the FreeBSD ncr driver to Linux-1.2.13. .\" .\" The original ncr driver has been written for 386bsd and FreeBSD by .\" Wolfgang Stanglmeier .\" Stefan Esser .\" Copyright (C) 1994 Wolfgang Stanglmeier .\" .\" The initialization code, and part of the code that addresses .\" FreeBSD-CAM services is based on the aic7xxx driver for FreeBSD-CAM .\" written by Justin T. Gibbs. .\" .\" Other major contributions: .\" .\" NVRAM detection and reading. .\" Copyright (C) 1997 Richard Waltham .\" .\" ---------------------------------------------------------------------------- .\" .\" 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. 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 AUTHORS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR .\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd December 26, 2020 .Dt SYM 4 .Os .Sh NAME .Nm sym .Nd NCR/Symbios/LSI Logic 53C8XX PCI SCSI host 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 pci" .Cd "device scbus" .Cd "device sym" +.Ed .Pp To disable PCI parity checking (needed for broken bridges): .Cd "options SYM_SETUP_PCI_PARITY=" .Pp To control driver probing against HVD buses: .Cd "options SYM_SETUP_SCSI_DIFF=" .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 sym_load="YES" .Ed .Sh DESCRIPTION This driver provides support for the Symbios/LSI Logic 53C8XX PCI SCSI controllers. .Pp Driver features include support for wide SCSI busses and fast10, fast20, fast40 and fast80-dt synchronous data transfers depending on controller capabilities. It also provides generic SCSI features such as tagged command queueing and auto-request sense. This driver is configured by default for a maximum of 446 outstanding commands per bus, 8 LUNs per target and 64 tagged tasks per LUN. These numbers are not so much limited by design as they are considered reasonable values for current SCSI technology. These values can be increased by changing appropriate constants in driver header files (not recommended). .Pp This driver supports the entire Symbios 53C8XX family of PCI SCSI controllers. It also offers the advantage of architectural improvements available only with newer chips. .Pp .Nm notably handles phase mismatch from SCRIPTS for the 53C896, 53C895A, and 53C1010 cores. As a result, it guarantees that no more than 1 interrupt per IO completion is delivered to the CPU, and that the SCRIPTS processor is never stalled waiting for CPU attention in normal situations. .Pp .Nm also uses LOAD/STORE SCRIPTS instructions for chips that support it. Only the early 810, 815 and 825 NCR chips do not support LOAD/STORE. Use of LOAD/STORE instead of MEMORY MOVE allows SCRIPTS to access IO registers internal to the chip (no external PCI cycles). As a result, the driver guarantees that no PCI self-mastering will occur for chips that support LOAD/STORE. .Pp LOAD/STORE instructions are also faster than MEMORY MOVE because they do not involve the chip DMA FIFO and are coded on 2 DWORDs instead of 3. .Pp For the early NCR 810, 815 and 825 chips, the driver uses a separate SCRIPTS set that uses MEMORY MOVE instructions for data movements. This is because LOAD/STORE are not supported by these chips. .Pp HVD/LVD capable controllers (895, 895A, 896, and 897) report the actual bus mode in the STEST4 chip IO registers. This feature allows the driver to safely probe against bus mode and to set up the chip accordingly. By default the driver only supports HVD for these chips. For other chips that can support HVD but not LVD, the driver has to probe implementation dependent registers (GPIO) in order to detect HVD bus mode. Only HVD implementations that conform with Symbios Logic recommendations can be detected by the driver. When the .Ar SYM_SETUP_SCSI_DIFF kernel option is assigned a value of 1, the driver will also probe against HVD for 825a, 875, 876 and 885 chips, assuming Symbios Logic compatible implementation of HVD. .Pp When the .Ar SYM_SETUP_PCI_PARITY is assigned a value of 0, the driver will not enable PCI parity checking for 53C8XX devices. PCI parity checking should not be an option for PCI SCSI controllers, but some systems have been reported to fail using 53C8XX chips, due to spurious or permanent PCI parity errors detected. This option is supplied for convenience but it is neither recommended nor supported. .Pp This driver offers other options that are not currently exported to the user. They are defined and documented in the .Pa sym_conf.h driver file. Changing these options is not recommended unless absolutely necessary. Some of these options are planned to be exported through .Xr sysctl 3 or an equivalent mechanism in a future driver releases and therefore, no compatibility is guaranteed. .Pp At initialization, the driver tries to detect and read user settings from controller NVRAM. The Symbios/Logic NVRAM layout and the Tekram NVRAM layout are currently supported. If the reading of the NVRAM succeeds, the following settings are taken into account and reported to CAM: .Bl -column "SCSI parity checking" "Symbios" .It Em "Host settings Symbios Tekram" .It "SCSI parity checking Y N" .It "Host SCSI ident Y Y" .It "Verbose messages Y N" .It "Scan targets hi-lo Y N" .It "Avoid SCSI bus reset Y N" .El .Bl -column "Synchronous period" "Symbios" .It Em "Device settings Symbios Tekram" .It "Synchronous period Y Y" .It "SCSI bus width Y Y" .It "Queue tag enable Y Y" .It "Number of tags NA Y" .It "Disconnect enable Y Y" .It "Scan at boot time Y N" .It "Scan LUN Y N" .El .Pp Devices that are configured as disabled for 'scan' in the NVRAM are not reported to CAM at system start-up. They can be discovered later using the .Ql camcontrol rescan command. .Pp The table below summarizes the main features and capabilities of the NCR/Symbios/LSI Logic 53C8XX family of PCI SCSI controllers. .Bl -column sym53c1510d "80MHz" "Width" "SRAM" "PCI64" .It Em "Chip Sync Width SRAM PCI64 Supported" .It "sym53c810 10MHz 8Bit N N Y" .It "sym53c810a 10MHz 8Bit N N Y" .It "sym53c815 10MHz 8Bit N N Y" .It "sym53c825 10MHz 16Bit N N Y" .It "sym53c825a 10MHz 16Bit 4KB N Y" .It "sym53c860 20MHz 8Bit N N Y" .It "sym53c875 20MHz 16Bit 4KB N Y" .It "sym53c876 20MHz 16Bit 4KB N Y" .It "sym53c885 20MHz 16Bit 4KB N Y" .It "sym53c895 40MHz 16Bit 4KB N Y" .It "sym53c895A 40MHz 16Bit 8KB N Y" .It "sym53c896 40MHz 16Bit 8KB Y Y" .It "sym53c897 40MHz 16Bit 8KB Y Y" .It "sym53c1510D 40MHz 16Bit 4KB Y Y" .It "sym53c1010 80MHz 16Bit 8KB Y Y" .El .Sh HARDWARE The .Nm driver provides support for the following Symbios/LSI Logic PCI SCSI controllers: .Pp .Bl -bullet -compact .It .Tn 53C810 .It .Tn 53C810A .It .Tn 53C815 .It .Tn 53C825 .It .Tn 53C825A .It .Tn 53C860 .It .Tn 53C875 .It .Tn 53C876 .It .Tn 53C895 .It .Tn 53C895A .It .Tn 53C896 .It .Tn 53C897 .It .Tn 53C1000 .It .Tn 53C1000R .It .Tn 53C1010-33 .It .Tn 53C1010-66 .It .Tn 53C1510D .El .Pp The SCSI controllers supported by .Nm can be either embedded on a motherboard, or on one of the following add-on boards: .Pp .Bl -bullet -compact .It ASUS SC-200, SC-896 .It Data Technology DTC3130 (all variants) .It DawiControl DC2976UW .It Diamond FirePort (all) .It NCR cards (all) .It Symbios cards (all) .It Tekram DC390W, 390U, 390F, 390U2B, 390U2W, 390U3D, and 390U3W .It Tyan S1365 .El .Sh MISC The DEC KZPCA-AA is a rebadged SYM8952U. .Sh SEE ALSO .Xr cd 4 , .Xr da 4 , .Xr sa 4 , .Xr scsi 4 , .Xr camcontrol 8 .Sh HISTORY The .Nm driver appeared in .Fx 4.0 . .Sh AUTHORS .An -nosplit The .Nm driver was written by .An Gerard Roudier and is derived from the Linux sym53c8xx driver from the same author. The sym53c8xx driver is derived from the ncr53c8xx driver, which was ported from the .Fx .Xr ncr 4 driver to Linux-1.2.13. The original .Xr ncr 4 driver was written for .Bx 386 and .Fx by .An Wolfgang Stanglmeier and .An Stefan Esser . .Sh BUGS No known bugs. diff --git a/share/man/man4/termios.4 b/share/man/man4/termios.4 index 555e944367e0..c9993a6dc14c 100644 --- a/share/man/man4/termios.4 +++ b/share/man/man4/termios.4 @@ -1,1598 +1,1598 @@ .\" Copyright (c) 1991, 1992, 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. .\" .\" @(#)termios.4 8.4 (Berkeley) 4/19/94 .\" $FreeBSD$ .\" .Dd June 28, 2020 .Dt TERMIOS 4 .Os .Sh NAME .Nm termios .Nd general terminal line discipline .Sh SYNOPSIS .In termios.h .Sh DESCRIPTION This describes a general terminal line discipline that is supported on tty asynchronous communication ports. .Ss Opening a Terminal Device File When a terminal file is opened, it normally causes the process to wait until a connection is established. For most hardware, the presence of a connection is indicated by the assertion of the hardware .Dv CARRIER line. If the termios structure associated with the terminal file has the .Dv CLOCAL flag set in the cflag, or if the .Dv O_NONBLOCK flag is set in the .Xr open 2 call, then the open will succeed even without a connection being present. In practice, applications seldom open these files; they are opened by special programs, such as .Xr getty 8 , and become an application's standard input, output, and error files. .Ss Job Control in a Nutshell Every process is associated with a particular process group and session. The grouping is hierarchical: every member of a particular process group is a member of the same session. This structuring is used in managing groups of related processes for purposes of .\" .Gw "job control" ; .Em "job control" ; that is, the ability from the keyboard (or from program control) to simultaneously stop or restart a complex command (a command composed of one or more related processes). The grouping into process groups allows delivering of signals that stop or start the group as a whole, along with arbitrating which process group has access to the single controlling terminal. The grouping at a higher layer into sessions is to restrict the job control related signals and system calls to within processes resulting from a particular instance of a .Dq login . Typically, a session is created when a user logs in, and the login terminal is setup to be the controlling terminal; all processes spawned from that login shell are in the same session, and inherit the controlling terminal. .Pp A job control shell operating interactively (that is, reading commands from a terminal) normally groups related processes together by placing them into the same process group. A set of processes in the same process group is collectively referred to as a .Dq job . When the foreground process group of the terminal is the same as the process group of a particular job, that job is said to be in the .Dq foreground . When the process group of the terminal is different from the process group of a job (but is still the controlling terminal), that job is said to be in the .Dq background . Normally the shell reads a command and starts the job that implements that command. If the command is to be started in the foreground (typical), it sets the process group of the terminal to the process group of the started job, waits for the job to complete, and then sets the process group of the terminal back to its own process group (it puts itself into the foreground). If the job is to be started in the background (as denoted by the shell operator "&"), it never changes the process group of the terminal and does not wait for the job to complete (that is, it immediately attempts to read the next command). If the job is started in the foreground, the user may type a key (usually .Ql \&^Z ) which generates the terminal stop signal .Pq Dv SIGTSTP and has the effect of stopping the entire job. The shell will notice that the job stopped, and will resume running after placing itself in the foreground. The shell also has commands for placing stopped jobs in the background, and for placing stopped or background jobs into the foreground. .Ss Orphaned Process Groups An orphaned process group is a process group that has no process whose parent is in a different process group, yet is in the same session. Conceptually it means a process group that does not have a parent that could do anything if it were to be stopped. For example, the initial login shell is typically in an orphaned process group. Orphaned process groups are immune to keyboard generated stop signals and job control signals resulting from reads or writes to the controlling terminal. .Ss The Controlling Terminal A terminal may belong to a process as its controlling terminal. Each process of a session that has a controlling terminal has the same controlling terminal. A terminal may be the controlling terminal for at most one session. The controlling terminal for a session is allocated by the session leader by issuing the .Dv TIOCSCTTY ioctl. A controlling terminal is never acquired by merely opening a terminal device file. When a controlling terminal becomes associated with a session, its foreground process group is set to the process group of the session leader. .Pp The controlling terminal is inherited by a child process during a .Xr fork 2 function call. A process relinquishes its controlling terminal when it creates a new session with the .Xr setsid 2 function; other processes remaining in the old session that had this terminal as their controlling terminal continue to have it. A process does not relinquish its controlling terminal simply by closing all of its file descriptors associated with the controlling terminal if other processes continue to have it open. .Pp When a controlling process terminates, the controlling terminal is disassociated from the current session, allowing it to be acquired by a new session leader. Subsequent access to the terminal by other processes in the earlier session will be denied, with attempts to access the terminal treated as if modem disconnect had been sensed. .Ss Terminal Access Control If a process is in the foreground process group of its controlling terminal, read operations are allowed. Any attempts by a process in a background process group to read from its controlling terminal causes a .Dv SIGTTIN signal to be sent to the process's group unless one of the following special cases apply: if the reading process is ignoring or blocking the .Dv SIGTTIN signal, or if the process group of the reading process is orphaned, the .Xr read 2 returns -1 with .Va errno set to .Er EIO and no signal is sent. The default action of the .Dv SIGTTIN signal is to stop the process to which it is sent. .Pp If a process is in the foreground process group of its controlling terminal, write operations are allowed. Attempts by a process in a background process group to write to its controlling terminal will cause the process group to be sent a .Dv SIGTTOU signal unless one of the following special cases apply: if .Dv TOSTOP is not set, or if .Dv TOSTOP is set and the process is ignoring or blocking the .Dv SIGTTOU signal, the process is allowed to write to the terminal and the .Dv SIGTTOU signal is not sent. If .Dv TOSTOP is set, and the process group of the writing process is orphaned, and the writing process is not ignoring or blocking .Dv SIGTTOU , the .Xr write 2 returns -1 with errno set to .Er EIO and no signal is sent. .Pp Certain calls that set terminal parameters are treated in the same fashion as write, except that .Dv TOSTOP is ignored; that is, the effect is identical to that of terminal writes when .Dv TOSTOP is set. .Ss Input Processing and Reading Data A terminal device associated with a terminal device file may operate in full-duplex mode, so that data may arrive even while output is occurring. Each terminal device file has associated with it an input queue, into which incoming data is stored by the system before being read by a process. The system imposes a limit, .Pf \&{ Dv MAX_INPUT Ns \&} , on the number of bytes that may be stored in the input queue. The behavior of the system when this limit is exceeded depends on the setting of the .Dv IMAXBEL flag in the termios .Fa c_iflag . If this flag is set, the terminal is sent an .Tn ASCII .Dv BEL character each time a character is received while the input queue is full. Otherwise, the input queue is flushed upon receiving the character. .Pp Two general kinds of input processing are available, determined by whether the terminal device file is in canonical mode or noncanonical mode. Additionally, input characters are processed according to the .Fa c_iflag and .Fa c_lflag fields. Such processing can include echoing, which in general means transmitting input characters immediately back to the terminal when they are received from the terminal. This is useful for terminals that can operate in full-duplex mode. .Pp The manner in which data is provided to a process reading from a terminal device file is dependent on whether the terminal device file is in canonical or noncanonical mode. .Pp Another dependency is whether the .Dv O_NONBLOCK flag is set by .Xr open 2 or .Xr fcntl 2 . If the .Dv O_NONBLOCK flag is clear, then the read request is blocked until data is available or a signal has been received. If the .Dv O_NONBLOCK flag is set, then the read request is completed, without blocking, in one of three ways: .Bl -enum -offset indent .It If there is enough data available to satisfy the entire request, and the read completes successfully the number of bytes read is returned. .It If there is not enough data available to satisfy the entire request, and the read completes successfully, having read as much data as possible, the number of bytes read is returned. .It If there is no data available, the read returns -1, with errno set to .Er EAGAIN . .El .Pp When data is available depends on whether the input processing mode is canonical or noncanonical. .Ss Canonical Mode Input Processing In canonical mode input processing, terminal input is processed in units of lines. A line is delimited by a newline .Ql \&\en character, an end-of-file .Pq Dv EOF character, or an end-of-line .Pq Dv EOL character. See the .Sx "Special Characters" section for more information on .Dv EOF and .Dv EOL . This means that a read request will not return until an entire line has been typed, or a signal has been received. Also, no matter how many bytes are requested in the read call, at most one line is returned. It is not, however, necessary to read a whole line at once; any number of bytes, even one, may be requested in a read without losing information. .Pp .Pf \&{ Dv MAX_CANON Ns \&} is a limit on the number of bytes in a line. The behavior of the system when this limit is exceeded is the same as when the input queue limit .Pf \&{ Dv MAX_INPUT Ns \&} , is exceeded. .Pp Erase and kill processing occur when either of two special characters, the .Dv ERASE and .Dv KILL characters (see the .Sx "Special Characters" section), is received. This processing affects data in the input queue that has not yet been delimited by a newline .Dv NL , .Dv EOF , or .Dv EOL character. This un-delimited data makes up the current line. The .Dv ERASE character deletes the last character in the current line, if there is any. The .Dv KILL character deletes all data in the current line, if there is any. The .Dv ERASE and .Dv KILL characters have no effect if there is no data in the current line. The .Dv ERASE and .Dv KILL characters themselves are not placed in the input queue. .Ss Noncanonical Mode Input Processing In noncanonical mode input processing, input bytes are not assembled into lines, and erase and kill processing does not occur. The values of the .Dv VMIN and .Dv VTIME members of the .Fa c_cc array are used to determine how to process the bytes received. .Pp .Dv MIN represents the minimum number of bytes that should be received when the .Xr read 2 function successfully returns. .Dv TIME is a timer of 0.1 second granularity that is used to time out bursty and short term data transmissions. If .Dv MIN is greater than .Dv \&{ Dv MAX_INPUT Ns \&} , the response to the request is undefined. The four possible values for .Dv MIN and .Dv TIME and their interactions are described below. .Ss "Case A: MIN > 0, TIME > 0" In this case .Dv TIME serves as an inter-byte timer and is activated after the first byte is received. Since it is an inter-byte timer, it is reset after a byte is received. The interaction between .Dv MIN and .Dv TIME is as follows: as soon as one byte is received, the inter-byte timer is started. If .Dv MIN bytes are received before the inter-byte timer expires (remember that the timer is reset upon receipt of each byte), the read is satisfied. If the timer expires before .Dv MIN bytes are received, the characters received to that point are returned to the user. Note that if .Dv TIME expires at least one byte is returned because the timer would not have been enabled unless a byte was received. In this case .Pf \&( Dv MIN > 0, .Dv TIME > 0) the read blocks until the .Dv MIN and .Dv TIME mechanisms are activated by the receipt of the first byte, or a signal is received. If data is in the buffer at the time of the .Fn read , the result is as if data had been received immediately after the .Fn read . .Ss "Case B: MIN > 0, TIME = 0" In this case, since the value of .Dv TIME is zero, the timer plays no role and only .Dv MIN is significant. A pending read is not satisfied until .Dv MIN bytes are received (i.e., the pending read blocks until .Dv MIN bytes are received), or a signal is received. A program that uses this case to read record-based terminal .Dv I/O may block indefinitely in the read operation. .Ss "Case C: MIN = 0, TIME > 0" In this case, since .Dv MIN = 0, .Dv TIME no longer represents an inter-byte timer. It now serves as a read timer that is activated as soon as the read function is processed. A read is satisfied as soon as a single byte is received or the read timer expires. Note that in this case if the timer expires, no bytes are returned. If the timer does not expire, the only way the read can be satisfied is if a byte is received. In this case the read will not block indefinitely waiting for a byte; if no byte is received within .Dv TIME Ns *0.1 seconds after the read is initiated, the read returns a value of zero, having read no data. If data is in the buffer at the time of the read, the timer is started as if data had been received immediately after the read. .Ss Case D: MIN = 0, TIME = 0 The minimum of either the number of bytes requested or the number of bytes currently available is returned without waiting for more bytes to be input. If no characters are available, read returns a value of zero, having read no data. .Ss Writing Data and Output Processing When a process writes one or more bytes to a terminal device file, they are processed according to the .Fa c_oflag field (see the .Sx "Output Modes" section). The implementation may provide a buffering mechanism; as such, when a call to .Fn write completes, all of the bytes written have been scheduled for transmission to the device, but the transmission will not necessarily have been completed. .\" See also .Sx "6.4.2" for the effects of .\" .Dv O_NONBLOCK .\" on write. .Ss Special Characters Certain characters have special functions on input or output or both. These functions are summarized as follows: .Bl -tag -width indent .It Dv INTR Special character on input and is recognized if the .Dv ISIG flag (see the .Sx "Local Modes" section) is enabled. Generates a .Dv SIGINT signal which is sent to all processes in the foreground process group for which the terminal is the controlling terminal. If .Dv ISIG is set, the .Dv INTR character is discarded when processed. .It Dv QUIT Special character on input and is recognized if the .Dv ISIG flag is enabled. Generates a .Dv SIGQUIT signal which is sent to all processes in the foreground process group for which the terminal is the controlling terminal. If .Dv ISIG is set, the .Dv QUIT character is discarded when processed. .It Dv ERASE Special character on input and is recognized if the .Dv ICANON flag is set. Erases the last character in the current line; see .Sx "Canonical Mode Input Processing" . It does not erase beyond the start of a line, as delimited by an .Dv NL , .Dv EOF , or .Dv EOL character. If .Dv ICANON is set, the .Dv ERASE character is discarded when processed. .It Dv KILL Special character on input and is recognized if the .Dv ICANON flag is set. Deletes the entire line, as delimited by a .Dv NL , .Dv EOF , or .Dv EOL character. If .Dv ICANON is set, the .Dv KILL character is discarded when processed. .It Dv EOF Special character on input and is recognized if the .Dv ICANON flag is set. When received, all the bytes waiting to be read are immediately passed to the process, without waiting for a newline, and the .Dv EOF is discarded. Thus, if there are no bytes waiting (that is, the .Dv EOF occurred at the beginning of a line), a byte count of zero is returned from the .Fn read , representing an end-of-file indication. If .Dv ICANON is set, the .Dv EOF character is discarded when processed. .It Dv NL Special character on input and is recognized if the .Dv ICANON flag is set. It is the line delimiter .Ql \&\en . .It Dv EOL Special character on input and is recognized if the .Dv ICANON flag is set. Is an additional line delimiter, like .Dv NL . .It Dv SUSP If the .Dv ISIG flag is enabled, receipt of the .Dv SUSP character causes a .Dv SIGTSTP signal to be sent to all processes in the foreground process group for which the terminal is the controlling terminal, and the .Dv SUSP character is discarded when processed. .It Dv STOP Special character on both input and output and is recognized if the .Dv IXON (output control) or .Dv IXOFF (input control) flag is set. Can be used to temporarily suspend output. It is useful with fast terminals to prevent output from disappearing before it can be read. If .Dv IXON is set, the .Dv STOP character is discarded when processed. .It Dv START Special character on both input and output and is recognized if the .Dv IXON (output control) or .Dv IXOFF (input control) flag is set. Can be used to resume output that has been suspended by a .Dv STOP character. If .Dv IXON is set, the .Dv START character is discarded when processed. .It Dv CR Special character on input and is recognized if the .Dv ICANON flag is set; it is the .Ql \&\er , as denoted in the .Tn \&C Standard {2}. When .Dv ICANON and .Dv ICRNL are set and .Dv IGNCR is not set, this character is translated into a .Dv NL , and has the same effect as a .Dv NL character. .El .Pp The following special characters are extensions defined by this system and are not a part of .St -p1003.1 termios. .Bl -tag -width indent .It Dv EOL2 Secondary .Dv EOL character. Same function as .Dv EOL . .It Dv WERASE Special character on input and is recognized if the .Dv ICANON flag is set. Erases the last word in the current line according to one of two algorithms. If the .Dv ALTWERASE flag is not set, first any preceding whitespace is erased, and then the maximal sequence of non-whitespace characters. If .Dv ALTWERASE is set, first any preceding whitespace is erased, and then the maximal sequence of alphabetic/underscores or non alphabetic/underscores. As a special case in this second algorithm, the first previous non-whitespace character is skipped in determining whether the preceding word is a sequence of alphabetic/underscores. This sounds confusing but turns out to be quite practical. .It Dv REPRINT Special character on input and is recognized if the .Dv ICANON flag is set. Causes the current input edit line to be retyped. .It Dv DSUSP Has similar actions to the .Dv SUSP character, except that the .Dv SIGTSTP signal is delivered when one of the processes in the foreground process group issues a .Fn read to the controlling terminal. .It Dv LNEXT Special character on input and is recognized if the .Dv IEXTEN flag is set. Receipt of this character causes the next character to be taken literally. .It Dv DISCARD Special character on input and is recognized if the .Dv IEXTEN flag is set. Receipt of this character toggles the flushing of terminal output. .It Dv STATUS Special character on input and is recognized if the .Dv ICANON flag is set. Receipt of this character causes a .Dv SIGINFO signal to be sent to the foreground process group of the terminal. Also, if the .Dv NOKERNINFO flag is not set, it causes the kernel to write a status message to the terminal that displays the current load average, the name of the command in the foreground, its process ID, the symbolic wait channel, the number of user and system seconds used, the percentage of cpu the process is getting, and the resident set size of the process. .Pp In case the .Xr sysctl 8 variable .Va kern.tty_info_kstacks is set to a non-zero value, the running thread's kernel stack is written to the terminal (e.g., for debugging purposes). .El .Pp The .Dv NL and .Dv CR characters cannot be changed. The values for all the remaining characters can be set and are described later in the document under Special Control Characters. .Pp Special character functions associated with changeable special control characters can be disabled individually by setting their value to .Dv {_POSIX_VDISABLE} ; see .Sx "Special Control Characters" . .Pp If two or more special characters have the same value, the function performed when that character is received is undefined. .Ss Modem Disconnect If a modem disconnect is detected by the terminal interface for a controlling terminal, and if .Dv CLOCAL is not set in the .Fa c_cflag field for the terminal, the .Dv SIGHUP signal is sent to the controlling process associated with the terminal. Unless other arrangements have been made, this causes the controlling process to terminate. Any subsequent call to the .Fn read function returns the value zero, indicating end of file. Thus, processes that read a terminal file and test for end-of-file can terminate appropriately after a disconnect. .\" If the .\" .Er EIO .\" condition specified in 6.1.1.4 that applies .\" when the implementation supports job control also exists, it is .\" unspecified whether the .\" .Dv EOF .\" condition or the .\" .Pf [ Dv EIO .\" ] is returned. Any subsequent .Fn write to the terminal device returns -1, with .Va errno set to .Er EIO , until the device is closed. .Sh General Terminal Interface .Ss Closing a Terminal Device File The last process to close a terminal device file causes any output to be sent to the device and any input to be discarded. Then, if .Dv HUPCL is set in the control modes, and the communications port supports a disconnect function, the terminal device performs a disconnect. .Ss Parameters That Can Be Set Routines that need to control certain terminal .Tn I/O characteristics do so by using the termios structure as defined in the header .In termios.h . This structure contains minimally four scalar elements of bit flags and one array of special characters. The scalar flag elements are named: .Fa c_iflag , .Fa c_oflag , .Fa c_cflag , and .Fa c_lflag . The character array is named .Fa c_cc , and its maximum index is .Dv NCCS . .Ss Input Modes Values of the .Fa c_iflag field describe the basic terminal input control, and are composed of following masks: .Pp .Bl -tag -width IMAXBEL -offset indent -compact .It Dv IGNBRK /* ignore BREAK condition */ .It Dv BRKINT /* map BREAK to SIGINTR */ .It Dv IGNPAR /* ignore (discard) parity errors */ .It Dv PARMRK /* mark parity and framing errors */ .It Dv INPCK /* enable checking of parity errors */ .It Dv ISTRIP /* strip 8th bit off chars */ .It Dv INLCR /* map NL into CR */ .It Dv IGNCR /* ignore CR */ .It Dv ICRNL /* map CR to NL (ala CRMOD) */ .It Dv IXON /* enable output flow control */ .It Dv IXOFF /* enable input flow control */ .It Dv IXANY /* any char will restart after stop */ .It Dv IMAXBEL /* ring bell on input queue full */ .El .Pp In the context of asynchronous serial data transmission, a break condition is defined as a sequence of zero-valued bits that continues for more than the time to send one byte. The entire sequence of zero-valued bits is interpreted as a single break condition, even if it continues for a time equivalent to more than one byte. In contexts other than asynchronous serial data transmission the definition of a break condition is implementation defined. .Pp If .Dv IGNBRK is set, a break condition detected on input is ignored, that is, not put on the input queue and therefore not read by any process. If .Dv IGNBRK is not set and .Dv BRKINT is set, the break condition flushes the input and output queues and if the terminal is the controlling terminal of a foreground process group, the break condition generates a single .Dv SIGINT signal to that foreground process group. If neither .Dv IGNBRK nor .Dv BRKINT is set, a break condition is read as a single .Ql \&\e0 , or if .Dv PARMRK is set, as .Ql \&\e377 , .Ql \&\e0 , .Ql \&\e0 . .Pp If .Dv IGNPAR is set, a byte with a framing or parity error (other than break) is ignored. .Pp If .Dv PARMRK is set, and .Dv IGNPAR is not set, a byte with a framing or parity error (other than break) is given to the application as the three-character sequence .Ql \&\e377 , .Ql \&\e0 , X, where .Ql \&\e377 , .Ql \&\e0 is a two-character flag preceding each sequence and X is the data of the character received in error. To avoid ambiguity in this case, if .Dv ISTRIP is not set, a valid character of .Ql \&\e377 is given to the application as .Ql \&\e377 , .Ql \&\e377 . If neither .Dv PARMRK nor .Dv IGNPAR is set, a framing or parity error (other than break) is given to the application as a single character .Ql \&\e0 . .Pp If .Dv INPCK is set, input parity checking is enabled. If .Dv INPCK is not set, input parity checking is disabled, allowing output parity generation without input parity errors. Note that whether input parity checking is enabled or disabled is independent of whether parity detection is enabled or disabled (see .Sx "Control Modes" ) . If parity detection is enabled but input parity checking is disabled, the hardware to which the terminal is connected recognizes the parity bit, but the terminal special file does not check whether this bit is set correctly or not. .Pp If .Dv ISTRIP is set, valid input bytes are first stripped to seven bits, otherwise all eight bits are processed. .Pp If .Dv INLCR is set, a received .Dv NL character is translated into a .Dv CR character. If .Dv IGNCR is set, a received .Dv CR character is ignored (not read). If .Dv IGNCR is not set and .Dv ICRNL is set, a received .Dv CR character is translated into a .Dv NL character. .Pp If .Dv IXON is set, start/stop output control is enabled. A received .Dv STOP character suspends output and a received .Dv START character restarts output. If .Dv IXANY is also set, then any character may restart output. When .Dv IXON is set, .Dv START and .Dv STOP characters are not read, but merely perform flow control functions. When .Dv IXON is not set, the .Dv START and .Dv STOP characters are read. .Pp If .Dv IXOFF is set, start/stop input control is enabled. The system shall transmit one or more .Dv STOP characters, which are intended to cause the terminal device to stop transmitting data, as needed to prevent the input queue from overflowing and causing the undefined behavior described in .Sx "Input Processing and Reading Data" , and shall transmit one or more .Dv START characters, which are intended to cause the terminal device to resume transmitting data, as soon as the device can continue transmitting data without risk of overflowing the input queue. The precise conditions under which .Dv STOP and .Dv START characters are transmitted are implementation defined. .Pp If .Dv IMAXBEL is set and the input queue is full, subsequent input shall cause an .Tn ASCII .Dv BEL character to be transmitted to the output queue. .Pp The initial input control value after .Fn open is implementation defined. .Ss Output Modes Values of the .Fa c_oflag field describe the basic terminal output control, and are composed of the following masks: .Pp .Bl -tag -width ONOEOT -offset indent -compact .It Dv OPOST /* enable following output processing */ .It Dv ONLCR /* map NL to CR-NL (ala .Dv CRMOD ) */ .It Dv OCRNL /* map CR to NL */ .It Dv TABDLY /* tab delay mask */ .It Dv TAB0 /* no tab delay and expansion */ .It Dv TAB3 /* expand tabs to spaces */ .It Dv ONOEOT /* discard .Dv EOT Ns 's .Ql \&^D on output) */ .It Dv ONOCR /* do not transmit CRs on column 0 */ .It Dv ONLRET /* on the terminal NL performs the CR function */ .El .Pp If .Dv OPOST is set, the remaining flag masks are interpreted as follows; otherwise characters are transmitted without change. .Pp If .Dv ONLCR is set, newlines are translated to carriage return, linefeeds. .Pp If .Dv OCRNL is set, carriage returns are translated to newlines. .Pp The .Dv TABDLY bits specify the tab delay. The .Fa c_oflag is masked with .Dv TABDLY and compared with the values .Dv TAB0 or .Dv TAB3 . If .Dv TAB3 is set, tabs are expanded to the appropriate number of spaces (assuming 8 column tab stops). .Pp If .Dv ONOEOT is set, .Tn ASCII .Dv EOT Ns 's are discarded on output. .Pp If .Dv ONOCR is set, no CR character is transmitted when at column 0 (first position). .Pp If .Dv ONLRET is set, the NL character is assumed to do the carriage-return function; the column pointer will be set to 0. .Ss Control Modes Values of the .Fa c_cflag field describe the basic terminal hardware control, and are composed of the following masks. Not all values specified are supported by all hardware. .Pp .Bl -tag -width CRTSXIFLOW -offset indent -compact .It Dv CSIZE /* character size mask */ .It Dv CS5 /* 5 bits (pseudo) */ .It Dv CS6 /* 6 bits */ .It Dv CS7 /* 7 bits */ .It Dv CS8 /* 8 bits */ .It Dv CSTOPB /* send 2 stop bits */ .It Dv CREAD /* enable receiver */ .It Dv PARENB /* parity enable */ .It Dv PARODD /* odd parity, else even */ .It Dv HUPCL /* hang up on last close */ .It Dv CLOCAL /* ignore modem status lines */ .It Dv CCTS_OFLOW /* .Dv CTS flow control of output */ .It Dv CRTSCTS /* same as .Dv CCTS_OFLOW */ .It Dv CRTS_IFLOW /* RTS flow control of input */ .It Dv MDMBUF /* flow control output via Carrier */ .It Dv CNO_RTSDTR /* Do not assert RTS or DTR automatically */ .El .Pp The .Dv CSIZE bits specify the byte size in bits for both transmission and reception. The .Fa c_cflag is masked with .Dv CSIZE and compared with the values .Dv CS5 , .Dv CS6 , .Dv CS7 , or .Dv CS8 . This size does not include the parity bit, if any. If .Dv CSTOPB is set, two stop bits are used, otherwise one stop bit. For example, at 110 baud, two stop bits are normally used. .Pp If .Dv CREAD is set, the receiver is enabled. Otherwise, no character is received. Not all hardware supports this bit. In fact, this flag is pretty silly and if it were not part of the .Nm specification it would be omitted. .Pp If .Dv PARENB is set, parity generation and detection are enabled and a parity bit is added to each character. If parity is enabled, .Dv PARODD specifies odd parity if set, otherwise even parity is used. .Pp If .Dv HUPCL is set, the modem control lines for the port are lowered when the last process with the port open closes the port or the process terminates. The modem connection is broken. .Pp If .Dv CLOCAL is set, a connection does not depend on the state of the modem status lines. If .Dv CLOCAL is clear, the modem status lines are monitored. .Pp Under normal circumstances, a call to the .Fn open function waits for the modem connection to complete. However, if the .Dv O_NONBLOCK flag is set or if .Dv CLOCAL has been set, the .Fn open function returns immediately without waiting for the connection. .Pp The .Dv CCTS_OFLOW .Pf ( Dv CRTSCTS ) flag is currently unused. .Pp If .Dv MDMBUF is set then output flow control is controlled by the state of Carrier Detect. .Pp If .Dv CNO_RTSDTR is set then the RTS and DTR lines will not be asserted when the device is opened. As a result, this flag is only useful on initial-state devices. .Pp If the object for which the control modes are set is not an asynchronous serial connection, some of the modes may be ignored; for example, if an attempt is made to set the baud rate on a network connection to a terminal on another host, the baud rate may or may not be set on the connection between that terminal and the machine it is directly connected to. .Ss Local Modes Values of the .Fa c_lflag field describe the control of various functions, and are composed of the following masks. .Pp .Bl -tag -width NOKERNINFO -offset indent -compact .It Dv ECHOKE /* visual erase for line kill */ .It Dv ECHOE /* visually erase chars */ .It Dv ECHO /* enable echoing */ .It Dv ECHONL /* echo .Dv NL even if .Dv ECHO is off */ .It Dv ECHOPRT /* visual erase mode for hardcopy */ .It Dv ECHOCTL /* echo control chars as ^(Char) */ .It Dv ISIG /* enable signals .Dv INTR , .Dv QUIT , .Dv [D]SUSP */ .It Dv ICANON /* canonicalize input lines */ .It Dv ALTWERASE /* use alternate .Dv WERASE algorithm */ .It Dv IEXTEN /* enable .Dv DISCARD and .Dv LNEXT */ .It Dv EXTPROC /* external processing */ .It Dv TOSTOP /* stop background jobs from output */ .It Dv FLUSHO /* output being flushed (state) */ .It Dv NOKERNINFO /* no kernel output from .Dv VSTATUS */ .It Dv PENDIN /* XXX retype pending input (state) */ .It Dv NOFLSH /* don't flush after interrupt */ .El .Pp If .Dv ECHO is set, input characters are echoed back to the terminal. If .Dv ECHO is not set, input characters are not echoed. .Pp If .Dv ECHOE and .Dv ICANON are set, the .Dv ERASE character causes the terminal to erase the last character in the current line from the display, if possible. If there is no character to erase, an implementation may echo an indication that this was the case or do nothing. .Pp If .Dv ECHOK and .Dv ICANON are set, the .Dv KILL character causes the current line to be discarded and the system echoes the .Ql \&\en character after the .Dv KILL character. .Pp If .Dv ECHOKE and .Dv ICANON are set, the .Dv KILL character causes the current line to be discarded and the system causes the terminal to erase the line from the display. .Pp If .Dv ECHOPRT and .Dv ICANON are set, the system assumes that the display is a printing device and prints a backslash and the erased characters when processing .Dv ERASE characters, followed by a forward slash. .Pp If .Dv ECHOCTL is set, the system echoes control characters in a visible fashion using a caret followed by the control character. .Pp If .Dv ALTWERASE is set, the system uses an alternative algorithm for determining what constitutes a word when processing .Dv WERASE characters (see .Dv WERASE ) . .Pp If .Dv ECHONL and .Dv ICANON are set, the .Ql \&\en character echoes even if .Dv ECHO is not set. .Pp If .Dv ICANON is set, canonical processing is enabled. This enables the erase and kill edit functions, and the assembly of input characters into lines delimited by .Dv NL , .Dv EOF , and .Dv EOL , as described in .Sx "Canonical Mode Input Processing" . .Pp If .Dv ICANON is not set, read requests are satisfied directly from the input queue. A read is not satisfied until at least .Dv MIN bytes have been received or the timeout value .Dv TIME expired between bytes. The time value represents tenths of seconds. See .Sx "Noncanonical Mode Input Processing" for more details. .Pp If .Dv ISIG is set, each input character is checked against the special control characters .Dv INTR , .Dv QUIT , and .Dv SUSP (job control only). If an input character matches one of these control characters, the function associated with that character is performed. If .Dv ISIG is not set, no checking is done. Thus these special input functions are possible only if .Dv ISIG is set. .Pp If .Dv IEXTEN is set, implementation-defined functions are recognized from the input data. How .Dv IEXTEN being set interacts with .Dv ICANON , .Dv ISIG , .Dv IXON , or .Dv IXOFF is implementation defined. If .Dv IEXTEN is not set, then implementation-defined functions are not recognized, and the corresponding input characters are not processed as described for .Dv ICANON , .Dv ISIG , .Dv IXON , and .Dv IXOFF . .Pp If .Dv NOFLSH is set, the normal flush of the input and output queues associated with the .Dv INTR , .Dv QUIT , and .Dv SUSP characters are not be done. .Pp If .Dv TOSTOP is set, the signal .Dv SIGTTOU is sent to the process group of a process that tries to write to its controlling terminal if it is not in the foreground process group for that terminal. This signal, by default, stops the members of the process group. Otherwise, the output generated by that process is output to the current output stream. Processes that are blocking or ignoring .Dv SIGTTOU signals are excepted and allowed to produce output and the .Dv SIGTTOU signal is not sent. .Pp If .Dv NOKERNINFO is set, the kernel does not produce a status message when processing .Dv STATUS characters (see .Dv STATUS ) . .Ss Special Control Characters The special control characters values are defined by the array .Fa c_cc . This table lists the array index, the corresponding special character, and the system default value. For an accurate list of the system defaults, consult the header file .In sys/ttydefaults.h . .Pp .Bl -column "Index Name" "Special Character" -offset indent -compact .It Em "Index Name Special Character Default Value" .It Dv VEOF Ta EOF Ta \&^D .It Dv VEOL Ta EOL Ta _POSIX_VDISABLE .It Dv VEOL2 Ta EOL2 Ta _POSIX_VDISABLE .It Dv VERASE Ta ERASE Ta \&^? Ql \&\e177 .It Dv VWERASE Ta WERASE Ta \&^W .It Dv VKILL Ta KILL Ta \&^U .It Dv VREPRINT Ta REPRINT Ta \&^R .It Dv VINTR Ta INTR Ta \&^C .It Dv VQUIT Ta QUIT Ta \&^\e\e Ql \&\e34 .It Dv VSUSP Ta SUSP Ta \&^Z .It Dv VDSUSP Ta DSUSP Ta \&^Y .It Dv VSTART Ta START Ta \&^Q .It Dv VSTOP Ta STOP Ta \&^S .It Dv VLNEXT Ta LNEXT Ta \&^V .It Dv VDISCARD Ta DISCARD Ta \&^O .It Dv VMIN Ta --- Ta \&1 .It Dv VTIME Ta --- Ta \&0 .It Dv VSTATUS Ta STATUS Ta \&^T .El .Pp If the value of one of the changeable special control characters (see .Sx "Special Characters" ) is .Dv {_POSIX_VDISABLE} , that function is disabled; that is, no input data is recognized as the disabled special character. If .Dv ICANON is not set, the value of .Dv {_POSIX_VDISABLE} has no special meaning for the .Dv VMIN and .Dv VTIME entries of the .Fa c_cc array. .Pp The initial values of the flags and control characters after .Fn open is set according to the values in the header .In sys/ttydefaults.h . .Sh SEE ALSO .Xr stty 1 , .Xr tcgetsid 3 , -.Xr tcgetwinsize 3, +.Xr tcgetwinsize 3 , .Xr tcsendbreak 3 , .Xr tcsetattr 3 , .Xr tcsetsid 3 , .Xr tty 4 , .Xr stack 9 diff --git a/share/man/man4/vmx.4 b/share/man/man4/vmx.4 index 7d8ef9e1518f..b42eda327ef0 100644 --- a/share/man/man4/vmx.4 +++ b/share/man/man4/vmx.4 @@ -1,157 +1,157 @@ .\" .\" Copyright (c) 2006,2013 Reyk Floeter .\" .\" 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. .\" .\" $OpenBSD: src/share/man/man4/vmx.4,v 1.1 2013/05/31 20:18:44 reyk Exp $ .\" .\" $FreeBSD$ .\" .Dd December 26, 2020 .Dt VMX 4 .Os .Sh NAME .Nm vmx .Nd VMware VMXNET3 Virtual Interface Controller 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 iflib" .Cd "device vmx" .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_vmx_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for the VMXNET3 virtual NIC available in virtual machines by VMware. It appears as a simple Ethernet device but is actually a virtual network interface to the underlying host operating system. .Pp This driver supports the .Ic VMXNET3 driver protocol, as an alternative to the emulated .Xr le 4 , .Xr em 4 interfaces also available in the VMware environment. The .Nm driver is optimized for the virtual machine, it can provide advanced capabilities depending on the underlying host operating system and the physical network interface controller of the host. The .Nm driver supports features like multiqueue support, IPv6 checksum offloading, MSI/MSI-X support and hardware VLAN tagging in VMware's VLAN Guest Tagging (VGT) mode. .Pp The .Nm driver supports VMXNET3 VMware virtual NICs provided by the virtual machine hardware version 7 or newer, as provided by the following products: .Pp .Bl -bullet -compact -offset indent .It VMware ESX/ESXi 4.0 and newer .It VMware Server 2.0 and newer .It VMware Workstation 6.5 and newer .It VMware Fusion 2.0 and newer .El .Pp For more information on configuring this device, see .Xr ifconfig 8 . .Sh MULTIPLE QUEUES The .Nm driver supports multiple transmit and receive queues. Multiple queues are only supported by certain VMware products, such as ESXi. The number of queues allocated depends on the presence of MSI-X, the number of configured CPUs, and the tunables listed below. .Fx does not enable MSI-X support on VMware by default. The .Va hw.pci.honor_msi_blacklist tunable must be disabled to enable MSI-X support. .Sh LOADER TUNABLES Tunables can be set at the .Xr loader 8 prompt before booting the kernel or stored in .Xr loader.conf 5 . .Bl -tag -width indent .It Va hw.vmx.txnqueue .It Va hw.vmx. Ns Ar X Ns Va .txnqueue Maximum number of transmit queues allocated by default by the driver. The default value is 8. The maximum supported by the VMXNET3 virtual NIC is 8. .It Va hw.vmx.rxnqueue .It Va hw.vmx. Ns Ar X Ns Va .rxnqueue Maximum number of receive queues allocated by default by the driver. The default value is 8. The maximum supported by the VMXNET3 virtual NIC is 16. .It Va hw.vmx.txndesc .It Va hw.vmx. Ns Ar X Ns Va .txndesc .Pp Number of transmit descriptors allocated by the driver. The default value is 512. The value must be a multiple of 32, and the maximum is 4096. .It Va hw.vmx.rxndesc .It Va hw.vmx. Ns Ar X Ns Va .rxndesc .Pp Number of receive descriptors per ring allocated by the driver. The default value is 256. The value must be a multiple of 32, and the maximum is 2048. There are two rings so the actual usage is doubled. .El .Sh EXAMPLES The following entry must be added to the VMware configuration file to provide the .Nm device: .Bd -literal -offset indent ethernet0.virtualDev = "vmxnet3" .Ed .Sh SEE ALSO .Xr altq 4 , .Xr arp 4 , .Xr em 4 , .Xr iflib 4 , +.Xr le 4 , .Xr netintro 4 , .Xr ng_ether 4 , -.Xr le 4 , .Xr vlan 4 , .Xr ifconfig 8 .Sh AUTHORS .An -nosplit The .Nm driver was ported from .Ox and significantly rewritten by .An Bryan Venteicher Aq Mt bryanv@freebsd.org . The .Ox driver was written by .An Tsubai Masanari . diff --git a/share/man/man4/vt.4 b/share/man/man4/vt.4 index bee7ef4e6f45..0c18b605ee37 100644 --- a/share/man/man4/vt.4 +++ b/share/man/man4/vt.4 @@ -1,397 +1,396 @@ .\" Copyright (c) 2014 Warren Block .\" 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 AUTHORS 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 AUTHORS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd February 14, 2022 .Dt "VT" 4 .Os .Sh NAME .Nm vt .Nd virtual terminal console driver .Sh SYNOPSIS .Cd "options TERMINAL_KERN_ATTR=_attribute_" .Cd "options TERMINAL_NORM_ATTR=_attribute_" .Cd "options VT_MAXWINDOWS=N" .Cd "options VT_ALT_TO_ESC_HACK=1" .Cd "options VT_TWOBUTTON_MOUSE" .Cd "options VT_FB_MAX_WIDTH=X" .Cd "options VT_FB_MAX_HEIGHT=Y" .Cd "options SC_NO_CUTPASTE" .Cd "device vt" .Pp In .Xr loader.conf 5 : .Cd hw.vga.textmode=1 .Cd hw.vga.acpi_ignore_no_vga=1 .Cd kern.vty=vt .Cd kern.vt.color..rgb="" .Cd kern.vt.fb.default_mode="x" .Cd kern.vt.fb.modes.="x" .Pp In .Xr loader.conf 5 or .Xr sysctl.conf 5 : .Cd kern.vt.kbd_halt=1 .Cd kern.vt.kbd_poweroff=1 .Cd kern.vt.kbd_reboot=1 .Cd kern.vt.kbd_debug=1 .Cd kern.vt.kbd_panic=0 .Cd kern.vt.enable_bell=1 .Sh DESCRIPTION The .Nm device provides multiple virtual terminals with an extensive feature set: .Bl -item -offset indent .It Unicode UTF-8 text with double-width characters. .It Large font maps in graphics mode, including support for Asian character sets. .It Graphics-mode consoles. .It Integration with KMS .Pq Kernel Mode Setting video drivers for switching between the .Em X Window System and virtual terminals. .El .Ss Virtual Terminals Multiple virtual terminals are provided on a single computer. Up to sixteen virtual terminals can be defined. A single virtual terminal is connected to the screen and keyboard at a time. Key combinations are used to select a virtual terminal. Alt-F1 through Alt-F12 correspond to the first twelve virtual terminals. If more than twelve virtual terminals are created, Shift-Alt-F1 through Shift-Alt-F4 are used to switch to the additional terminals. .Ss Copying and Pasting Text with a Mouse Copying and pasting text from the screen with a mouse is supported. Press and hold down mouse button 1, usually the left button, while moving the mouse to select text. Selected text is highlighted with reversed foreground and background colors. To select more text after releasing mouse button 1, press mouse button 3, usually the right button. To paste text that has been selected, press mouse button 2, usually the middle button. The text is entered as if it were typed at the keyboard. The .Dv VT_TWOBUTTON_MOUSE kernel option can be used with mice that only have two buttons. Setting this option makes the second mouse button into the paste button. See .Xr moused 8 for more information. .Ss Scrolling Back Output that has scrolled off the screen can be reviewed by pressing the Scroll Lock key, then scrolling up and down with the arrow keys. The Page Up and Page Down keys scroll up or down a full screen at a time. The Home and End keys jump to the beginning or end of the scrollback buffer. When finished reviewing, press the Scroll Lock key again to return to normal use. .Sh DRIVER CONFIGURATION .Ss Kernel Configuration Options These kernel options control the .Nm driver. .Bl -tag -width MAXCONS .It Dv TERMINAL_NORM_ATTR= Ns Pa attribute .It Dv TERMINAL_KERN_ATTR= Ns Pa attribute These options change the default colors used for normal and kernel text. Available colors are defined in .In sys/terminal.h . See .Sx EXAMPLES below. .It Dv VT_MAXWINDOWS=N Set the number of virtual terminals to be created to .Fa N . The value defaults to 12. .It Dv VT_ALT_TO_ESC_HACK=1 When the Alt key is held down while pressing another key, send an ESC sequence instead of the Alt key. .It Dv VT_TWOBUTTON_MOUSE If defined, swap the functions of mouse buttons 2 and 3. In effect, this makes the right-hand mouse button perform a paste. These options are checked in the order shown. .It Dv SC_NO_CUTPASTE Disable mouse support. .It VT_FB_MAX_WIDTH=X Set the maximum width to .Fa X . .It VT_FB_MAX_HEIGHT=Y Set the maximum height to .Fa Y . .El .Sh BACKWARDS COMPATIBILITY Several options are provided for compatibility with the previous console device, .Xr sc 4 . These options will be removed in a future .Fx version. .Bl -column -offset indent ".Sy vt VT_TWOBUTTON_MOUSE" ".Sy SC_TWOBUTTON_MOUSE" .It Sy vt Option Name Ta Sy sc Option Name .It Dv TERMINAL_KERN_ATTR Ta Dv SC_KERNEL_CONS_ATTR .It Dv TERMINAL_NORM_ATTR Ta Dv SC_NORM_ATTR .It Dv VT_TWOBUTTON_MOUSE Ta Dv SC_TWOBUTTON_MOUSE .It Dv VT_MAXWINDOWS Ta Dv MAXCONS .It none Ta Dv SC_NO_CUTPASTE .El .Sh START-UP OPERATION WITH X86 BIOS SYSTEMS The computer BIOS starts in text mode, and the .Fx .Xr loader 8 runs, loading the kernel. If .Va hw.vga.textmode is set, the system remains in text mode. Otherwise, .Nm switches to 640x480x16 VGA mode using .Cm vt_vga . If a KMS .Pq Kernel Mode Setting video driver is available, the display is switched to high resolution and the KMS driver takes over. When a KMS driver is not available, .Cm vt_vga remains active. .Sh LOADER TUNABLES These settings can be entered at the .Xr loader 8 prompt or in .Xr loader.conf 5 . .Bl -tag -width indent .It Va hw.vga.textmode Set to 1 to use virtual terminals in text mode instead of graphics mode. Features that require graphics mode, like loadable fonts, will be disabled. .Pp If a KMS driver is loaded the console will switch to (and remain in) graphics mode. .It Va hw.vga.acpi_ignore_no_vga Set to 1 to force the usage of the VGA driver regardless of whether ACPI IAPC_BOOT_ARCH signals no VGA support. Can be used to workaround firmware bugs in the ACPI tables. .It Va kern.vty Set this value to .Ql vt or .Ql sc to choose a specific system console, overriding the default. The .Pa GENERIC kernel uses .Nm when this value is not set. .It Va kern.vt.color. Ns Ar colornum Ns Va .rgb Set this value to override default palette entry for color .Pa colornum which should be in a range from 0 to 15 inclusive. The value should be either a comma-separated triplet of red, green, and blue values in a range from 0 to 255 or HTML-like hex triplet. See .Sx EXAMPLES below. .It Va kern.vt.fb.default_mode Set this value to a graphic mode to override the default mode picked by the .Nm backend. The mode is applied to all output connectors. This is currently only supported by the .Cm vt_fb backend when it is paired with a KMS video driver. .It Va kern.vt.fb.modes. Ns Pa connector_name Set this value to a graphic mode to override the default mode picked by the .Nm backend. This mode is applied to the output connector .Pa connector_name only. It has precedence over .Va kern.vt.fb.default_mode . The names of available connector names can be found in .Xr dmesg 8 after loading the KMS driver. It will contain a list of connectors and their associated tunables. This is currently only supported by the .Cm vt_fb backend when it is paired with a KMS video driver. .El .Sh KEYBOARD SYSCTL TUNABLES These settings control whether certain special key combinations are enabled or ignored. The specific key combinations can be configured by using a .Xr keymap 5 file. .Pp These settings can be entered at the .Xr loader 8 prompt or in .Xr loader.conf 5 and can also be changed at runtime with the .Xr sysctl 8 command. .Bl -tag -width indent .It Va kern.vt.kbd_halt Enable halt keyboard combination. .It Va kern.vt.kbd_poweroff Enable power off key combination. .It Va kern.vt.kbd_reboot Enable reboot key combination, usually Ctrl+Alt+Del. .It Va kern.vt.kbd_debug Enable debug request key combination, usually Ctrl+Alt+Esc. .It Va kern.vt.kbd_panic Enable panic key combination. .El .Sh OTHER SYSCTL TUNABLES These settings can be entered at the .Xr loader 8 prompt, set in .Xr loader.conf 5 , or changed at runtime with .Xr sysctl 8 . .Bl -tag -width indent .It Va kern.vt.enable_bell Enable the terminal bell. .El .Sh FILES .Bl -tag -width /usr/share/vt/keymaps/* -compact .It Pa /dev/console .It Pa /dev/consolectl .It Pa /dev/ttyv* virtual terminals .It Pa /etc/ttys terminal initialization information .It Pa /usr/share/vt/fonts/*.fnt console fonts .It Pa /usr/share/vt/keymaps/*.kbd keyboard layouts .El .Sh DEVCTL MESSAGES .Bl -column "System" "Subsystem" "1234567" -compact .Sy "System" Ta Sy "Subsystem" Ta Sy "Type" Ta Sy "Description" .It Li VT Ta BELL Ta RING Ta Notification that the console bell has rung. .El .Pp .Bl -column "Variable" "Meaning" -compact .Sy "Variable" Ta Sy "Meaning" .It Li duration_ms Ta Length of time the bell was requested to ring in milliseconds. .It Li enabled Ta true or false indicating whether or not the bell was administratively enabled when rung. .It Li hushed Ta true or false indicating whether or not the bell was quieted by the user when rung. .It Li hz Ta Tone that was requested in Hz. .El -.Pp .Sh EXAMPLES This example changes the default color of normal text to green on a black background, or black on a green background when reversed. Note that white space cannot be used inside the attribute string because of the current implementation of .Xr config 8 . .Pp .Dl "options TERMINAL_NORM_ATTR=(FG_GREEN|BG_BLACK)" .Pp This line changes the default color of kernel messages to be bright red on a black background, or black on a bright red background when reversed. .Pp .Dl "options TERMINAL_KERN_ATTR=(FG_LIGHTRED|BG_BLACK)" .Pp To set a 1024x768 mode on all output connectors, put the following line in .Pa /boot/loader.conf : .Pp .Dl kern.vt.fb.default_mode="1024x768" .Pp To set a 800x600 only on a laptop builtin screen, use the following line instead: .Pp .Dl kern.vt.fb.modes.LVDS-1="800x600" .Pp The connector name was found in .Xr dmesg 8 : .Pp .Dl info: [drm] Connector LVDS-1: get mode from tunables: .Dl info: [drm] - kern.vt.fb.modes.LVDS-1 .Dl info: [drm] - kern.vt.fb.default_mode .Pp To set black and white colors of console palette .Pp .Dl kern.vt.color.0.rgb="10,10,10" .Dl kern.vt.color.15.rgb="#f0f0f0" .Sh SEE ALSO .Xr kbdcontrol 1 , .Xr login 1 , .Xr vidcontrol 1 , .Xr atkbd 4 , .Xr atkbdc 4 , .Xr kbdmux 4 , .Xr keyboard 4 , .Xr screen 4 , .Xr splash 4 , .Xr syscons 4 , .Xr ukbd 4 , .Xr kbdmap 5 , .Xr rc.conf 5 , .Xr ttys 5 , .Xr config 8 , .Xr getty 8 , .Xr kldload 8 , .Xr moused 8 , .Xr vtfontcvt 8 .Sh HISTORY The .Nm driver first appeared in .Fx 9.3 . .Sh AUTHORS .An -nosplit The .Nm device driver was developed by .An \&Ed Schouten Aq Mt ed@FreeBSD.org , .An \&Ed Maste Aq Mt emaste@FreeBSD.org , and .An Aleksandr Rybalko Aq Mt ray@FreeBSD.org , with sponsorship provided by the .Fx Foundation. This manual page was written by .An Warren Block Aq Mt wblock@FreeBSD.org . .Sh CAVEATS Paste buffer size is limited by the system value .Brq Dv MAX_INPUT , the number of bytes that can be stored in the terminal input queue, usually 1024 bytes (see .Xr termios 4 ) .