Index: head/share/man/man4/altera_atse.4 =================================================================== --- head/share/man/man4/altera_atse.4 (revision 275990) +++ head/share/man/man4/altera_atse.4 (revision 275991) @@ -1,119 +1,119 @@ .\"- .\" Copyright (c) 2013-2014 SRI International .\" All rights reserved. .\" .\" This software was developed by SRI International and the University of .\" Cambridge Computer Laboratory under DARPA/AFRL contract (FA8750-10-C-0237) .\" ("CTSRD"), as part of the DARPA CRASH research programme. .\" .\" 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 21, 2014 .Dt ALTERA_ATSE 4 .Os .Sh NAME .Nm atse .Nd driver for the Altera Triple-Speed Ethernet MegaCore .Sh SYNOPSIS .Cd "device atse" .Cd "options ATSE_CFI_HACK" .Pp In .Pa /boot/device.hints : .Cd hint.atse.0.at="nexus0" .Cd hint.atse.0.maddr=0x7f007000 .Cd hint.atse.0.msize=0x540 .Cd hint.atse.0.rc_irq=1 .Cd hint.atse.0.rx_maddr=0x7f007500 .Cd hint.atse.0.rx_msize=0x8 .Cd hint.atse.0.rxc_maddr=0x7f007520 .Cd hint.atse.0.rxc_msize=0x20 .Cd hint.atse.0.tx_irq=2 .Cd hint.atse.0.tx_maddr=0x7f007400 .Cd hint.atse.0.tx_msize=0x8 .Cd hint.atse.0.txc_maddr=0x7f007420 .Cd hint.atse.0.txc_msize=0x20 .Cd hint.e1000phy.0.at="miibus0" .Cd hint.e1000phy.0.phyno=0 .Sh DESCRIPTION The .Nm device driver provides support for the Altera Triple-Speed Ethernet MegaCore. .Sh HARDWARE The current version of the .Nm driver supports the Ethernet MegaCore as described in version 11.1 of Altera's documentation when the device is configured with internal FIFOs. .Sh MAC SELECTION The default MAC address for each .Nm interface is derived from a value stored in .Xr cfi 4 flash. The value is managed by the .Xr atsectl 8 utility. .Pp Only a single MAC address may be stored in flash. If the address begins with the Altera prefix 00:07:ed and ends in 00 then up to 16 addresses will be derived from it by adding the unit number of the interface to the stored address. -For other prefixes, the address will be assigned to atse0 and random +For other prefixes, the address will be assigned to atse0 and random addresses will be used for other interfaces. If the stored address is invalid, for example all zero's, multicast, or the default address shipped on all DE4 boards (00:07:ed:ff:ed:15) then a random address is generated when the device is attached. .Sh SEE ALSO .Xr miibus 4 , .Xr netintro 4 , .Xr ifconfig 8 .Rs .%T Triple-Speed Ethernet MegaCore Function User Guide .%D November 2011 .%I Altera Corporation .Re .Sh HISTORY The .Nm device driver first appeared in .Fx 10.0 . .Sh AUTHORS The .Nm device driver and this manual page were developed by SRI International and the University of Cambridge Computer Laboratory under DARPA/AFRL contract .Pq FA8750-10-C-0237 .Pq Do CTSRD Dc , as part of the DARPA CRASH research programme. This device driver was written by .An Bjoern A. Zeeb . .Sh BUGS The .Nm driver only supports a single configuration of the MegaCore as installed on the Terasic Technologies Altera DE4 Development and Education Board. .Pp Only gigabit Ethernet speeds are currently supported. Index: head/share/man/man4/gpioled.4 =================================================================== --- head/share/man/man4/gpioled.4 (revision 275990) +++ head/share/man/man4/gpioled.4 (revision 275991) @@ -1,156 +1,156 @@ .\" Copyright (c) 2013, Luiz Otavio O Souza .\" 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 May 14, 2014 .Dt GPIOLED 4 .Os .Sh NAME .Nm gpioled .Nd GPIO LED generic device 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 gpio" .Cd "device gpioled" .Ed .Sh DESCRIPTION The .Nm driver provides glue to attach a .Xr led 4 compatible device to a GPIO pin. Each LED in the system has a .Pa name which is used to export a device as .Pa /dev/led/ . The GPIO pin can then be controlled by writing to this device as described in .Xr led 4 . .Pp -On a -.Xr device.hints 5 +On a +.Xr device.hints 5 based system, like .Li MIPS , these values are configurable for .Nm : .Bl -tag -width ".Va hint.gpioiic.%d.atXXX" .It Va hint.gpioled.%d.at The gpiobus you are attaching to. Normally assigned to gpiobus0. .It Va hint.gpioled.%d.name Arbitrary name of device in .Pa /dev/led/ to create for .Xr led 4 . .It Va hint.gpioled.%d.pins Which pin on the GPIO interface to map to this instance. Please note that this mask should only ever have one bit set (any other bits - i.e., pins - will be ignored). .El .Pp On a .Xr FDT 4 based system, like .Li ARM , the DTS part for a .Nm gpioled device usually looks like: .Bd -literal gpio: gpio { gpio-controller; ... led0 { compatible = "gpioled"; gpios = <&gpio 16 2 0>; /* GPIO pin 16. */ name = "ok"; }; led1 { compatible = "gpioled"; gpios = <&gpio 17 2 0>; /* GPIO pin 17. */ name = "user-led1"; }; }; .Ed .Pp Optionally, you can choose to combine all the LEDs under a single .Dq gpio-leds compatible node: .Bd -literal simplebus0 { ... leds { compatible = "gpio-leds"; led0 { gpios = <&gpio 16 2 0>; name = "ok" }; led1 { gpios = <&gpio 17 2 0>; name = "user-led1" }; }; }; .Ed .Pp Both methods are equally supported and it is possible to have the LEDs defined with any sort of mix between the methods. The only restriction is that a GPIO pin cannot be mapped by two different (gpio)leds. .Pp For more details about the .Va gpios property, please consult .Pa /usr/src/sys/boot/fdt/dts/bindings-gpio.txt . .Pp The property .Va name is the arbitrary name of the device in .Pa /dev/led/ to create for .Xr led 4 . .Sh SEE ALSO .Xr fdt 4 , .Xr gpio 4 , .Xr gpioiic 4 , .Xr led 4 .Sh HISTORY The .Nm manual page first appeared in .Fx 10.1 . .Sh AUTHORS This manual page was written by .An Luiz Otavio O Souza . Index: head/share/man/man4/iicbus.4 =================================================================== --- head/share/man/man4/iicbus.4 (revision 275990) +++ head/share/man/man4/iicbus.4 (revision 275991) @@ -1,167 +1,167 @@ .\" Copyright (c) 1998, 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 November 17, 2014 .Dt IICBUS 4 .Os .Sh NAME .Nm iicbus .Nd I2C bus system .Sh SYNOPSIS .Cd "device iicbus" .Cd "device iicbb" .Pp .Cd "device iic" .Cd "device ic" .Cd "device iicsmb" .Sh DESCRIPTION The .Em iicbus system provides a uniform, modular and architecture-independent system for the implementation of drivers to control various I2C devices and to utilize different I2C controllers. .Sh I2C I2C is an acronym for Inter Integrated Circuit bus. The I2C bus was developed in the early 1980's by Philips semiconductors. Its purpose was to provide an easy way to connect a CPU to peripheral chips in a TV-set. .Pp The BUS physically consists of 2 active wires and a ground connection. The active wires, SDA and SCL, are both bidirectional. Where SDA is the Serial DAta line and SCL is the Serial CLock line. .Pp Every component hooked up to the bus has its own unique address whether it is a CPU, LCD driver, memory, or complex function chip. Each of these chips can act as a receiver and/or transmitter depending on its functionality. Obviously an LCD driver is only a receiver, while a memory or I/O chip can both be transmitter and receiver. Furthermore there may be one or more BUS MASTERs. .Pp The BUS MASTER is the chip issuing the commands on the BUS. In the I2C protocol specification it is stated that the IC that initiates a data transfer on the bus is considered the BUS MASTER. At that time all the others are regarded to as the BUS SLAVEs. As mentioned before, the IC bus is a Multi-MASTER BUS. This means that more than one IC capable of initiating data transfer can be connected to it. .Sh DEVICES Some I2C device drivers are available: .Pp .Bl -column "Device drivers" -compact .It Em Devices Ta Em Description .It Sy iic Ta "general i/o operation" .It Sy ic Ta "network IP interface" .It Sy iicsmb Ta "I2C to SMB software bridge" .El .Sh INTERFACES The I2C protocol may be implemented by hardware or software. Software interfaces rely on very simple hardware, usually two lines twiddled by 2 registers. Hardware interfaces are more intelligent and receive 8-bit characters they write to the bus according to the I2C protocol. .Pp I2C interfaces may act on the bus as slave devices, allowing spontaneous bidirectional communications, thanks to the multi-master capabilities of the I2C protocol. .Pp Some I2C interfaces are available: .Pp .Bl -column "Interface drivers" -compact .It Em Interface Ta Em Description .It Sy pcf Ta "Philips PCF8584 master/slave interface" .It Sy iicbb Ta "generic bit-banging master-only driver" .It Sy lpbb Ta "parallel port specific bit-banging interface" .It Sy bktr Ta "Brooktree848 video chipset, hardware and software master-only interface" .El .Sh BUS FREQUENCY CONFIGURATION The operating frequency of an I2C bus may be fixed or configurable. The bus may be used as part of some larger standard interface, and that -interface specification may require a fixed frequency. -The driver for that hardware would not honor an attempt to configure a +interface specification may require a fixed frequency. +The driver for that hardware would not honor an attempt to configure a different speed. A general purpose I2C bus, such as those found in many embedded systems, -will often support multiple bus frequencies. +will often support multiple bus frequencies. .Pp When a system supports multiple I2C busses, a different frequency can be configured for each bus by number, represented by the .Va %d in the variable names below. Busses can be configured using any combination of device hints, Flattened Device Tree (FDT) data, tunables set via .Xr loader 8 , or at runtime using .Xr sysctl 8 . When configuration is supplied using more than one method, FDT and hint data will be overridden by a tunable, which can be overriden by .Xr sysctl 8 . .Ss Device Hints Set .Va hint.iicbus.%d.frequency to the frequency in Hz, on systems that use device hints to configure I2C devices. The hint is also honored by systems that use FDT data if no frequency is configured using FDT. .Ss Flattened Device Tree Data Configure the I2C bus speed using the FDT standard .Va clock-frequency property of the node describing the I2C controller hardware. .Ss Sysctl and Tunable Set .Va dev.iicbus.%d.frequency in .Xr loader.conf 5 . The same variable can be changed at any time with .Xr sysctl 8 . Reset the bus using .Xr i2c 8 or the -.Xr iic 4 +.Xr iic 4 .Va I2CRSTCARD ioctl to make the change take effect. .Sh SEE ALSO .Xr bktr 4 , .Xr fdt 4 , .Xr iic 4 , .Xr iicbb 4 , .Xr lpbb 4 , .Xr pcf 4 , .Xr i2c 8 .Sh HISTORY The .Nm manual page first appeared in .Fx 3.0 . .Sh AUTHORS This manual page was written by .An Nicolas Souchu . Index: head/share/man/man4/iscsi_initiator.4 =================================================================== --- head/share/man/man4/iscsi_initiator.4 (revision 275990) +++ head/share/man/man4/iscsi_initiator.4 (revision 275991) @@ -1,118 +1,118 @@ .\" Copyright (c) 2007-2010 Daniel Braniss .\" 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 9, 2014 .Dt ISCSI_INITIATOR 4 .Os .Sh NAME .Nm iscsi_initiator .Nd kernel driver for the iSCSI protocol .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device iscsi_initiator" .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 iscsi_initiator_load="YES" .Ed .Sh DESCRIPTION .Bf -symbolic This driver, along with its userspace counterpart -.Xr iscontrol 8 , +.Xr iscontrol 8 , is obsolete. Users are advised to use .Xr iscsi 4 instead. .Ef .Pp The .Nm implements the kernel side of the Internet SCSI (iSCSI) network protocol standard, the user land companion is .Xr iscontrol 8 , and permits access to remote .Em virtual SCSI devices via .Xr cam 4 . .Sh SYSCTL VARIABLES .Bl -tag -width ".Va net.iscsi.n.targeaddress" .It Va debug.iscsi_initiator set the debug-level, 0 means no debugging, 9 for maximum. .It Va net.iscsi.isid the initiator part of the Session Identifier. .It Va "kern.cam.cam_srch_hi=1" allow search above LUN 7 for SCSI3 and greater devices. .It "the following are informative only:" .It Va net.iscsi.driver_version the current version of the driver. .It Va net.iscsi.sessions the number of current active sessions. .It Va net.iscsi.n.targetname is the targe name of session .Em n . .It Va net.iscsi.n.targeaddress is the IP address of the target of session .Em n . .It Va net.iscsi.n.stats are some statistics for session .Em n .It Va net.iscsi.n.pid is the .Em "process id" of the userland side of session .Em n , see .Xr iscontrol 8 . .El .Sh FILES The .Nm driver creates the following: .Pp .Bl -tag -width ".Pa /dev/iscsi%dxx" -compact .It Pa /dev/iscsi used to create new sessions. .It Pa /dev/iscsi%d for each new session. .El .Sh SEE ALSO .Xr cam 4 , .Xr camcontrol 8 , .Xr iscontrol 8 .Sh STANDARDS iSCSI RFC 3720 .\" .Sh HISTORY .Sh AUTHORS This software was written by .An Daniel Braniss Aq Mt danny@cs.huji.ac.il .Sh BUGS The lun discovery method is old-fashioned. Index: head/share/man/man4/mpr.4 =================================================================== --- head/share/man/man4/mpr.4 (revision 275990) +++ head/share/man/man4/mpr.4 (revision 275991) @@ -1,229 +1,229 @@ .\" .\" Copyright (c) 2010 Spectra Logic Corporation .\" Copyright (c) 2014 LSI Corp .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions, and the following disclaimer, .\" 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 May 2, 2014 .Dt MPR 4 .Os .Sh NAME .Nm mpr .Nd "LSI Fusion-MPT 3 IT/IR 12Gb/s Serial Attached SCSI/SATA 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 mpr" .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 mpr_load="YES" .Ed .Sh DESCRIPTION The -.Nm +.Nm driver provides support for LSI Fusion-MPT 3 IT/IR .Tn SAS controllers. .Sh HARDWARE The following controllers are supported by the .Nm driver: .Pp .Bl -bullet -compact .It LSI SAS 3004 (4 Port SAS) .It LSI SAS 3008 (8 Port SAS) .It LSI SAS 3108 (8 Port SAS) .El .Sh CONFIGURATION To disable MSI interrupts for all .Nm driver instances, set the following 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 the following tunable value in .Xr loader.conf 5 : .Bd -literal -offset indent dev.mpr.X.disable_msi=1 .Ed .Pp where X is the adapter number. .Pp To disable MSI-X interrupts for all .Nm driver instances, set the following 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 the following 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 the following variable 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 the following variable in .Xr loader.conf 5 : .Bd -literal -offset indent dev.mpr.X.max_chains=NNNN .Ed .Pp This variable may also be viewed via .Xr sysctl 8 to see the maximum set for a given adapter. .Pp The current number of free chain frames may be seen via the dev.mpr.X.chain_free .Xr sysctl 8 variable. .Pp The lowest number of free chain frames may be seen via the dev.mpr.X.chain_free_lowwater .Xr sysctl 8 variable. .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 maximum number of active I/O commands seen since boot is shown 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 the following variable in .Xr loader.conf 5 : .Bd -literal -offset indent hw.mpr.exclude_ids=Y .Ed .Pp where Y is the target ID of the device. If more than one device is to be excluded, target ID's are separated by commas. .Pp Devices can be excluded from .Nm control for a specific adapter by setting the following variable in .Xr loader.conf 5 : .Bd -literal -offset indent dev.mpr.X.exclude_ids=Y .Ed .Pp where X is the adapter number and Y is the target ID of the device. If more than one device is to be excluded, target ID's are separated by commas. .Sh DEBUGGING To enable debugging prints from the .Nm driver, set the .Bd -literal -offset indent hw.mpr.X.debug_level .Ed .Pp variable, where X is the adapter number, either in .Xr loader.conf 5 or via .Xr sysctl 8 . The following bits have the described effects: .Bd -literal -offset indent 0x0001 Enable informational prints. 0x0002 Enable prints for driver faults. 0x0004 Enable prints for controller events. 0x0008 Enable prints for controller logging. 0x0010 Enable prints for tracing recovery operations. 0x0020 Enable prints for parameter errors and programming bugs. 0x0040 Enable prints for system initialization operations. 0x0080 Enable prints for more detailed information. 0x0100 Enable prints for user-generated commands. 0x0200 Enable prints for device mapping. 0x0400 Enable prints for tracing through driver functions. .Ed .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 FreeBSD 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. .Pp This man page was written by .An Ken Merry Aq Mt ken@FreeBSD.org with additional input from .An Stephen McConnell Aq Mt stephen.mcconnell@lsi.com . Index: head/share/man/man4/mrsas.4 =================================================================== --- head/share/man/man4/mrsas.4 (revision 275990) +++ head/share/man/man4/mrsas.4 (revision 275991) @@ -1,403 +1,403 @@ .\" Copyright (c) 2014 LSI Corp .\" All rights reserved. .\" Author: Kashyap Desai .\" Support: freebsdraid@lsi.com .\" .\" 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 nor the names of its .\" contributors may be used to endorse or promote products derived .\" from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS .\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE .\" COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER .\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN .\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. -.\" +.\" .\" The views and conclusions contained in the software and documentation .\" are those of the authors and should not be interpreted as representing .\" official policies, either expressed or implied, of the FreeBSD Project. .\" .\" $FreeBSD$ .\" .Dd May 8, 2014 .Dt MRSAS 4 .Os .Sh NAME .Nm mrsas .Nd "LSI MegaRAID 6Gb/s and 12Gb/s SAS+SATA RAID controller 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 mrsas" .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 mrsas_load="YES" .Ed .Sh DESCRIPTION The -.Nm +.Nm driver will detect LSI's next generation (6Gb/s and 12Gb/s) PCI Express SAS/SATA RAID controllers. See the .Nm HARDWARE section for the supported devices list. -A disk (virtual disk/physical disk) attached to the +A disk (virtual disk/physical disk) attached to the .Nm -driver will be visible to the user through +driver will be visible to the user through .Xr camcontrol 8 as .Pa /dev/da? device nodes. A simple management interface is also provided on a per-controller basis via the .Pa /dev/mrsas? device node. .Pp The .Nm name is derived from the phrase "MegaRAID SAS HBA", which is substantially different than the old "MegaRAID" Driver .Xr mfi 4 -which does not connect targets -to the +which does not connect targets +to the .Xr cam 4 -layer and thus requires a new driver which attaches targets to the -.Xr cam 4 +layer and thus requires a new driver which attaches targets to the +.Xr cam 4 layer. Older MegaRAID controllers are supported by .Xr mfi 4 and will not work with .Nm , but both the .Xr mfi 4 -and +and .Nm drivers can detect and manage the LSI MegaRAID SAS 2208/2308/3008/3108 series of controllers. .Pp The .Xr device.hints 5 option is provided to tune the .Nm driver's behavior for LSI MegaRAID SAS 2208/2308/3008/3108 controllers. By default, the .Xr mfi 4 driver will detect these controllers. -See the -.Nm PRIORITY +See the +.Nm PRIORITY section to know more about driver priority for MR-Fusion devices. .Pp .Nm will provide a priority of (-30) (between .Dv BUS_PROBE_DEFAULT and .Dv BUS_PROBE_LOW_PRIORITY ) at probe call for device id's 0x005B, 0x005D, and 0x005F so that .Nm does not take control of these devices without user intervention. .Sh HARDWARE The .Nm driver supports the following hardware: .Pp [ Thunderbolt 6Gb/s MR controller ] .Bl -bullet -compact .It LSI MegaRAID SAS 9265 .It LSI MegaRAID SAS 9266 .It LSI MegaRAID SAS 9267 .It LSI MegaRAID SAS 9270 .It LSI MegaRAID SAS 9271 .It LSI MegaRAID SAS 9272 .It LSI MegaRAID SAS 9285 .It LSI MegaRAID SAS 9286 .It DELL PERC H810 .It DELL PERC H710/P .El .Pp [ Invader/Fury 12Gb/s MR controller ] .Bl -bullet -compact .It LSI MegaRAID SAS 9380 .It LSI MegaRAID SAS 9361 .It LSI MegaRAID SAS 9341 .It DELL PERC H830 .It DELL PERC H730/P .It DELL PERC H330 .El .Sh CONFIGURATION To disable Online Controller Reset(OCR) for a specific .Nm -driver instance, set the +driver instance, set the following tunable value in .Xr loader.conf 5 : .Bd -literal -offset indent -dev.mrsas.X.disable_ocr=1 +dev.mrsas.X.disable_ocr=1 .Ed .Pp where X is the adapter number. .Pp -To change the I/O timeout value for a specific +To change the I/O timeout value for a specific .Nm driver instance, set the following tunable value in .Xr loader.conf 5 : .Bd -literal -offset indent dev.mrsas.X.mrsas_io_timeout=NNNNNN .Ed .Pp where NNNNNN is the timeout value in milli-seconds. .Pp To change the firmware fault check timer value for a specific .Nm driver instance, set the following tunable value in .Xr loader.conf 5 : .Bd -literal -offset indent dev.mrsas.X.mrsas_fw_fault_check_delay=NN .Ed .Pp where NN is the fault check delay value in seconds. .Pp The current number of active I/O commands is shown in the .Va dev.mrsas.X.fw_outstanding .Xr sysctl 8 variable. .Sh DEBUGGING To enable debugging prints from the .Nm driver, set the .Va hw.mrsas.X.debug_level variable, where X is the adapter number, either in .Xr loader.conf 5 or via .Xr sysctl 8 . The following bits have the described effects: .Bl -tag -width indent -offset indent .It 0x01 Enable informational prints. .It 0x02 Enable tracing prints. .It 0x04 Enable prints for driver faults. .It 0x08 Enable prints for OCR and I/O timeout. .It 0x10 Enable prints for AEN events. .El .Sh PRIORITY The .Nm driver will always set a default (-30) priority in the PCI subsystem for selection of MR-Fusion cards. (It is between .Dv BUS_PROBE_DEFAULT and .Dv BUS_PROBE_LOW_PRIORITY ) . MR-Fusion Controllers include all cards with the Device IDs - -0x005B, +0x005B, 0x005D, 0x005F. .Pp The -.Xr mfi 4 +.Xr mfi 4 driver will set a priority of either .Dv BUS_PROBE_DEFAULT or .Dv BUS_PROBE_LOW_PRIORITY (depending on the device.hints setting) in the PCI subsystem for selection of MR-Fusion cards. With the above design in place, the .Xr mfi 4 driver will attach to a MR-Fusion card given that it has a higher priority than .Nm . .Pp Using .Pa /boot/device.hints (as mentioned below), the user can provide a preference for the .Nm driver to detect a MR-Fusion card instead of the .Xr mfi 4 -driver. +driver. .Bd -ragged -offset indent .Cd hw.mfi.mrsas_enable="1" .Ed .Pp At boot time, the -.Xr mfi 4 +.Xr mfi 4 driver will get priority to detect MR-Fusion controllers by default. Before changing this default driver selection policy, LSI advises users to understand how the driver selection policy works. LSI's policy is to provide priority to the .Xr mfi 4 driver to detect MR-Fusion cards, but allow for the ability to choose the .Nm driver to detect MR-Fusion cards. .Pp LSI recommends setting hw.mfi.mrsas_enable="0" for customers who are using the -older -.Xr mfi 4 -driver and do not want to switch to +older +.Xr mfi 4 +driver and do not want to switch to .Nm . For those customers who are using a MR-Fusion controller for the first time, LSI recommends using the .Nm driver and setting hw.mfi.mrsas_enable="1". .Pp Changing the default behavior is well tested under most conditions, but unexpected behavior may pop up if more complex and unrealistic operations are executed by switching between the .Xr mfi 4 -and -.Nm +and +.Nm drivers for MR-Fusion. Switching drivers is designed to happen only one time. Although multiple switching is possible, it is not recommended. The user should decide from .Nm Start of Day which driver they want to use for the MR-Fusion card. .Pp -The user may see different device names when switching from -.Xr mfi 4 -to +The user may see different device names when switching from +.Xr mfi 4 +to .Nm . This behavior is .Nm Functions As Designed and the user needs to change the .Xr fstab 5 -entry manually if they are doing any experiments with -.Xr mfi 4 +entry manually if they are doing any experiments with +.Xr mfi 4 and .Nm interoperability. .Sh FILES .Bl -tag -width ".Pa /dev/mrsas?" -compact .It Pa /dev/da? array/logical disk interface .It Pa /dev/mrsas? management interface .El .Sh SEE ALSO .Xr cam 4 , .Xr mfi 4 , .Xr pci 4 , .Xr device.hints 5 , .Xr camcontrol 8 .Sh HISTORY The .Nm driver first appeared in .Fx 10.1 . .Bd -ragged .Cd "mfi Driver:" .Xr mfi 4 is the old .Fx driver which started with support for Gen-1 Controllers and was extended to support up to MR-Fusion (Device ID = 0x005B, 0x005D, 0x005F). .Ed .Bd -ragged .Cd "mrsas Driver:" .Nm is the new driver reworked by LSI which supports Thunderbolt and onward products. The SAS+SATA RAID controller with device id 0x005b is referred to as the Thunderbolt controller throughout this man page. -.Ed +.Ed .Bd -ragged .Nm cam aware HBA drivers: .Fx has a .Xr cam 4 layer which attaches storage devices and provides a common access mechanism to storage controllers and attached devices. The -.Nm +.Nm driver is .Xr cam 4 -aware and devices associated with -.Nm -can be seen using +aware and devices associated with +.Nm +can be seen using .Xr camcontrol 8 . The .Xr mfi 4 driver does not understand the .Xr cam 4 layer and it directly associates storage disks to the block layer. .Pp -.Nm Thunderbolt Controller: +.Nm Thunderbolt Controller: This is the 6Gb/s MegaRAID HBA card which has device id 0x005B. .Pp -.Nm Invader Controller: +.Nm Invader Controller: This is 12Gb/s MegaRAID HBA card which has device id 0x005D. .Pp -.Nm Fury Controller: +.Nm Fury Controller: This is the 12Gb/s MegaRAID HBA card which has device id 0x005F. .Ed .Sh AUTHORS The .Nm driver and this manual page were written by .An Kashyap Desai Aq Mt Kashyap.Desai@lsi.com . .Sh TODO The driver does not support big-endian architectures at this time. .Pp The driver does not support alias for device name (it is required when the user switches between two drivers and does not want to edit .Pa /etc/fstab manually). .Pp The -.Nm +.Nm driver exposes devices as .Pa /dev/da? , -whereas -.Xr mfi 4 +whereas +.Xr mfi 4 exposes devices as .Pa /dev/mfid? . .Pp .Nm does not support the Linux Emulator interface. .Pp .Nm will not work with .Xr mfiutil 8 . Index: head/share/man/man4/netmap.4 =================================================================== --- head/share/man/man4/netmap.4 (revision 275990) +++ head/share/man/man4/netmap.4 (revision 275991) @@ -1,1067 +1,1067 @@ .\" 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 February 13, 2014 .Dt NETMAP 4 .Os .Sh NAME .Nm netmap .Nd a framework for fast packet I/O .br .Nm VALE .Nd a fast VirtuAl Local Ethernet using the netmap API .br .Nm netmap pipes .Nd a shared memory packet transport channel .Sh SYNOPSIS .Cd device netmap .Sh DESCRIPTION .Nm is a framework for extremely fast and efficient packet I/O for both userspace and kernel clients. It runs on FreeBSD and Linux, and includes .Nm VALE , a very fast and modular in-kernel software switch/dataplane, and .Nm netmap pipes , a shared memory packet transport channel. All these are accessed interchangeably with the same API. .Pp .Nm , VALE and .Nm netmap pipes are at least one order of magnitude faster than standard OS mechanisms (sockets, bpf, tun/tap interfaces, native switches, pipes), reaching 14.88 million packets per second (Mpps) with much less than one core on a 10 Gbit NIC, about 20 Mpps per core for VALE ports, and over 100 Mpps for netmap pipes. .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, and .Nm netmap pipes can be created dynamically, providing high speed packet I/O between processes, virtual machines, NICs and the host stack. .Pp .Nm suports both non-blocking I/O through .Xr ioctls() , synchronization and blocking I/O through a file descriptor and standard OS mechanisms such as .Xr select 2 , .Xr poll 2 , .Xr epoll 2 , .Xr kqueue 2 . .Nm VALE and .Nm netmap pipes are implemented by a single kernel module, which also emulates the .Nm API over standard drivers for devices without native .Nm support. For best performance, .Nm requires explicit support in device drivers. .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 .Nm /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 +.Nm netmap ports (including .Nm VALE and .Nm netmap pipe ports). Simpler, higher level functions are described in section .Xr LIBRARIES . .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 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 valeXXX:YYY (arbitrary XXX and YYY) the file descriptor is bound to port YYY of a VALE switch called XXX, both dynamically created if necessary. The string cannot exceed IFNAMSIZ characters, and YYY 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. .Xr epoll 2 and .Xr kqueue 2 are not supported on .Nm file descriptors. .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 .Xr 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. .Pa ni_bufs_head contains the index of the first of these free rings, which are connected in a list (the first uint32_t of each buffer being the index of the next buffer in the list). A 0 indicates the end of the list. .Pp .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 and an array of .Pa slots describing the buffers. .Pp .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 .Pa NIOCREGIF . From there, all other objects are reachable through relative references (offsets or indexes). Macros and functions in 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. .br (NOTE: older versions of netmap used head/count format to indicate the content of a ring). .Pp .Va head is the first slot available to userspace; .br .Va cur is the wakeup point: select/poll will unblock when .Va tail passes .Va cur ; .br .Va tail is the first slot reserved to the kernel. .Pp Slot indexes 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. .Pp .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: .Pp .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 select() and poll() wlll 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. .br 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 it MUST be used when the buf_idx in the slot is changed. This can be used to implement zero-copy forwarding, see .Sx ZERO-COPY FORWARDING . .Pp .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 detecting when packets have been send and a file descriptor can be closed. .It NS_FORWARD When a ring is in 'transparent' mode (see .Sx TRANSPARENT MODE ) , packets marked with this flags 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 SRC 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. .br 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 tx 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 . .Pp .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. .Pp .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 ). .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 .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. .Pp .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 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 select()/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 .Xr vale 4 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 2 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 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 NETMAP_DO_RX_POLL flag to .Em NIOCREGIF updates receive rings even without read events. Note that on epoll and kqueue, NETMAP_NO_TX_POLL and 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 conveniency, the .Va 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 , binds a file descriptor to a port. .Bl -tag -width XX .It Va ifname is a port name, in the form "netmap:XXX" for a NIC and "valeXXX:YYY" 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 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 pcap_dispatch(), applies a callback to incoming packets .It Va u_char * nm_nextpkt(struct nm_desc *d, struct nm_pkthdr *hdr) similar to pcap_next(), fetches the next packet .El .Sh SUPPORTED DEVICES .Nm natively supports the following devices: .Pp On FreeBSD: .Xr em 4 , .Xr igb 4 , .Xr ixgbe 4 , .Xr lem 4 , .Xr re 4 . .Pp On Linux .Xr e1000 4 , .Xr e1000e 4 , .Xr igb 4 , .Xr ixgbe 4 , .Xr mlx4 4 , .Xr forcedeth 4 , .Xr r8169 4 . .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 sockets, and approaching that of in-kernel solutions such as Linux's .Xr pktgen . .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 aspect of the operation of .Nm are controlled through sysctl variables on FreeBSD .Em ( dev.netmap.* ) and module parameters on Linux .Em ( /sys/module/netmap_lin/parameters/* ) : .Pp .Bl -tag -width indent .It Va dev.netmap.admode: 0 Controls the use of native or emulated adapter mode. 0 uses the best available option, 1 forces native and fails if not available, 2 forces emulated hence never fails. .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.mmap_unreg: 0 .It Va dev.netmap.fwd: 0 Forces NS_FORWARD mode .It Va dev.netmap.flags: 0 .It Va dev.netmap.txsync_retry: 2 .It Va dev.netmap.no_pendintr: 1 Forces recovery of transmit buffers on system calls .It Va dev.netmap.mitigate: 1 Propagates interrupt mitigation to user processes .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.bridge_batch: 1024 Batch size used when moving packets across a .Nm VALE switch. Values above 64 generally guarantee good performance. .El .Sh SYSTEM CALLS .Nm uses .Xr select 2 , .Xr poll 2 , .Xr epoll and .Xr kqueue 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 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. .Pp .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 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. .Sh EXAMPLES .Ss TEST PROGRAMS .Nm comes with a few programs that can be used for testing or simple applications. See the .Va examples/ directory in .Nm distributions, or .Va tools/tools/netmap/ directory in FreeBSD distributions. .Pp .Xr pkt-gen 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 has many options can be uses to set packet sizes, addresses, rates, and use multiple send/receive threads and cores. .Pp .Xr bridge is another test program which interconnects two .Nm ports. It can be used for transparent forwarding between interfaces, as in .Dl bridge -i ix0 -i ix1 or even connect the NIC to the host stack using netmap .Dl bridge -i ix0 -i 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 .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: .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 vale:x{3 -f rx # receiver on the master side .Dl pkt-gen -i vale:x}3 -f tx # sender on the slave side .Pp The following command attaches an interface and the host stack to a switch: .Dl vale-ctl -h vale2:em0 Other .Nm clients attached to the same switch can now communicate with the network card or the host. .Sh SEE ALSO .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 , .An Vincenzo Maffione . .Pp .Nm and .Nm VALE have been funded by the European Commission within FP7 Projects CHANGE (257422) and OPENLAB (287581). Index: head/share/man/man4/tap.4 =================================================================== --- head/share/man/man4/tap.4 (revision 275990) +++ head/share/man/man4/tap.4 (revision 275991) @@ -1,329 +1,329 @@ .\" $FreeBSD$ .\" Based on PR#2411 .\" .Dd November 30, 2014 .Dt TAP 4 .Os .Sh NAME .Nm tap .Nd Ethernet tunnel software network interface .Sh SYNOPSIS .Cd device tap .Sh DESCRIPTION The .Nm interface is a software loopback mechanism that can be loosely described as the network interface analog of the .Xr pty 4 , that is, .Nm does for network interfaces what the .Xr pty 4 driver does for terminals. .Pp The .Nm driver, like the .Xr pty 4 driver, provides two interfaces: an interface like the usual facility it is simulating (an Ethernet network interface in the case of .Nm , or a terminal for .Xr pty 4 ) , and a character-special device .Dq control interface. -A client program transfers Ethernet frames to or from the +A client program transfers Ethernet frames to or from the .Nm .Dq control interface. The .Xr tun 4 interface provides similar functionality at the network layer: a client will transfer IP (by default) packets to or from a .Xr tun 4 .Dq control interface. .Pp The network interfaces are named .Dq Li tap0 , .Dq Li tap1 , etc., one for each control device that has been opened. These Ethernet network interfaces persist until .Pa if_tap.ko module is unloaded, or until removed with "ifconfig destroy" (see below). .Pp .Nm devices are created using interface cloning. This is done using the .Dq ifconfig tap Ns Sy N No create command. This is the preferred method of creating .Nm devices. The same method allows removal of interfaces. For this, use the .Dq ifconfig tap Ns Sy N No destroy command. .Pp If the .Xr sysctl 8 variable .Va net.link.tap.devfs_cloning is non-zero, the .Nm interface permits opens on the special control device .Pa /dev/tap . When this device is opened, .Nm will return a handle for the lowest unused .Nm device (use .Xr devname 3 to determine which). .Pp .Bf Em Disabling the legacy devfs cloning functionality may break existing applications which use .Nm , such as .Tn VMware and .Xr ssh 1 . It therefore defaults to being enabled until further notice. .Ef .Pp Control devices (once successfully opened) persist until .Pa if_tap.ko is unloaded or the interface is destroyed. .Pp Each interface supports the usual Ethernet network interface .Xr ioctl 2 Ns s and thus can be used with .Xr ifconfig 8 like any other Ethernet interface. When the system chooses to transmit an Ethernet frame on the network interface, the frame can be read from the control device (it appears as .Dq input there); writing an Ethernet frame to the control device generates an input frame on the network interface, as if the (non-existent) hardware had just received it. .Pp The Ethernet tunnel device, normally .Pa /dev/tap Ns Sy N , is exclusive-open (it cannot be opened if it is already open) and is restricted to the super-user, unless the .Xr sysctl 8 variable .Va net.link.tap.user_open is non-zero. If the .Xr sysctl 8 variable .Va net.link.tap.up_on_open is non-zero, the tunnel device will be marked .Dq up when the control device is opened. A .Fn read call will return an error .Pq Er EHOSTDOWN if the interface is not .Dq ready . Once the interface is ready, .Fn read will return an Ethernet frame if one is available; if not, it will either block until one is or return .Er EWOULDBLOCK , depending on whether non-blocking I/O has been enabled. If the frame is longer than is allowed for in the buffer passed to .Fn read , the extra data will be silently dropped. .Pp A .Xr write 2 call passes an Ethernet frame in to be .Dq received on the pseudo-interface. Each .Fn write call supplies exactly one frame; the frame length is taken from the amount of data provided to .Fn write . Writes will not block; if the frame cannot be accepted for a transient reason (e.g., no buffer space available), it is silently dropped; if the reason is not transient (e.g., frame too large), an error is returned. The following .Xr ioctl 2 calls are supported (defined in .In net/if_tap.h ) : .Bl -tag -width VMIO_SIOCSETMACADDR .It Dv TAPSIFINFO Set network interface information (line speed, MTU and type). The argument should be a pointer to a .Va struct tapinfo . .It Dv TAPGIFINFO Retrieve network interface information (line speed, MTU and type). The argument should be a pointer to a .Va struct tapinfo . .It Dv TAPSDEBUG The argument should be a pointer to an .Va int ; this sets the internal debugging variable to that value. What, if anything, this variable controls is not documented here; see the source code. .It Dv TAPGDEBUG The argument should be a pointer to an .Va int ; this stores the internal debugging variable's value into it. .It Dv TAPGIFNAME Retrieve network interface name. The argument should be a pointer to a .Va struct ifreq . The interface name will be returned in the .Va ifr_name field. .It Dv FIONBIO Turn non-blocking I/O for reads off or on, according as the argument .Va int Ns 's value is or is not zero (Writes are always nonblocking). .It Dv FIOASYNC Turn asynchronous I/O for reads (i.e., generation of .Dv SIGIO when data is available to be read) off or on, according as the argument .Va int Ns 's value is or is not zero. .It Dv FIONREAD If any frames are queued to be read, store the size of the first one into the argument .Va int ; otherwise, store zero. .It Dv TIOCSPGRP Set the process group to receive .Dv SIGIO signals, when asynchronous I/O is enabled, to the argument .Va int value. .It Dv TIOCGPGRP Retrieve the process group value for .Dv SIGIO signals into the argument .Va int value. .It Dv SIOCGIFADDR Retrieve the Media Access Control .Pq Dv MAC address of the .Dq remote side. This command is used by the VMware port and expected to be executed on descriptor, associated with control device (usually .Pa /dev/vmnet Ns Sy N or .Pa /dev/tap Ns Sy N ) . The .Va buffer , which is passed as the argument, is expected to have enough space to store the .Dv MAC address. At the open time both .Dq local and .Dq remote .Dv MAC addresses are the same, so this command could be used to retrieve the .Dq local .Dv MAC address. .It Dv SIOCSIFADDR Set the Media Access Control .Pq Dv MAC address of the .Dq remote side. This command is used by VMware port and expected to be executed on a descriptor, associated with control device (usually .Pa /dev/vmnet Ns Sy N ) . .El .Pp The control device also supports .Xr select 2 for read; selecting for write is pointless, and always succeeds, since writes are always non-blocking. .Pp On the last close of the data device, the interface is brought down (as if with .Dq ifconfig tap Ns Sy N No down ) unless the device is a .Em VMnet device. All queued frames are thrown away. If the interface is up when the data device is not open, output frames are thrown away rather than letting them pile up. .Pp The .Nm device can also be used with the VMware port as a replacement for the old .Em VMnet device driver. The driver uses the minor number to select between .Nm and .Nm vmnet devices. .Em VMnet minor numbers begin at .Va 0x800000 + .Va N ; where .Va N is a .Em VMnet unit number. In this case the control device is expected to be .Pa /dev/vmnet Ns Sy N , and the network interface will be .Sy vmnet Ns Ar N . Additionally, .Em VMnet devices do not .Xr ifconfig 8 themselves down when the control device is closed. Everything else is the same. .Pp In addition to the above mentioned .Xr ioctl 2 calls, there is an additional one for the VMware port. .Bl -tag -width VMIO_SIOCSETMACADDR .It Dv VMIO_SIOCSIFFLAGS VMware .Dv SIOCSIFFLAGS . .El .Sh SEE ALSO .Xr inet 4 , .Xr intro 4 , .Xr tun 4 Index: head/share/man/man4/tun.4 =================================================================== --- head/share/man/man4/tun.4 (revision 275990) +++ head/share/man/man4/tun.4 (revision 275991) @@ -1,325 +1,325 @@ .\" $NetBSD: tun.4,v 1.1 1996/06/25 22:17:37 pk Exp $ .\" $FreeBSD$ .\" Based on PR#2411 .\" .Dd November 30, 2014 .Dt TUN 4 .Os .Sh NAME .Nm tun .Nd tunnel software network interface .Sh SYNOPSIS .Cd device tun .Sh DESCRIPTION The .Nm interface is a software loopback mechanism that can be loosely described as the network interface analog of the .Xr pty 4 , that is, .Nm does for network interfaces what the .Xr pty 4 driver does for terminals. .Pp The .Nm driver, like the .Xr pty 4 driver, provides two interfaces: an interface like the usual facility it is simulating (a network interface in the case of .Nm , or a terminal for .Xr pty 4 ) , and a character-special device .Dq control interface. -A client program transfers IP (by default) packets to or from the +A client program transfers IP (by default) packets to or from the .Nm .Dq control interface. The .Xr tap 4 interface provides similar functionality at the Ethernet layer: a client will transfer Ethernet frames to or from a .Xr tap 4 .Dq control interface. .Pp The network interfaces are named .Dq Li tun0 , .Dq Li tun1 , etc., one for each control device that has been opened. These network interfaces persist until the .Pa if_tun.ko module is unloaded, or until removed with the .Xr ifconfig 8 command. .Pp .Nm devices are created using interface cloning. This is done using the .Dq ifconfig tun Ns Sy N No create command. This is the preferred method of creating .Nm devices. The same method allows removal of interfaces. For this, use the .Dq ifconfig tun Ns Sy N No destroy command. .Pp If the .Xr sysctl 8 variable .Va net.link.tun.devfs_cloning is non-zero, the .Nm interface permits opens on the special control device .Pa /dev/tun . When this device is opened, .Nm will return a handle for the lowest unused .Nm device (use .Xr devname 3 to determine which). .Pp .Bf Em Disabling the legacy devfs cloning functionality may break existing applications which use .Nm , such as .Xr ppp 8 and .Xr ssh 1 . It therefore defaults to being enabled until further notice. .Ef .Pp Control devices (once successfully opened) persist until .Pa if_tun.ko is unloaded in the same way that network interfaces persist (see above). .Pp Each interface supports the usual network-interface .Xr ioctl 2 Ns s , such as .Dv SIOCAIFADDR and thus can be used with .Xr ifconfig 8 like any other interface. At boot time, they are .Dv POINTOPOINT interfaces, but this can be changed; see the description of the control device, below. When the system chooses to transmit a packet on the network interface, the packet can be read from the control device (it appears as .Dq input there); writing a packet to the control device generates an input packet on the network interface, as if the (non-existent) hardware had just received it. .Pp The tunnel device .Pq Pa /dev/tun Ns Ar N is exclusive-open (it cannot be opened if it is already open). A .Xr read 2 call will return an error .Pq Er EHOSTDOWN if the interface is not .Dq ready (which means that the control device is open and the interface's address has been set). .Pp Once the interface is ready, .Xr read 2 will return a packet if one is available; if not, it will either block until one is or return .Er EWOULDBLOCK , depending on whether non-blocking I/O has been enabled. If the packet is longer than is allowed for in the buffer passed to .Xr read 2 , the extra data will be silently dropped. .Pp If the .Dv TUNSLMODE ioctl has been set, packets read from the control device will be prepended with the destination address as presented to the network interface output routine, .Fn tunoutput . The destination address is in .Vt struct sockaddr format. The actual length of the prepended address is in the member .Va sa_len . If the .Dv TUNSIFHEAD ioctl has been set, packets will be prepended with a four byte address family in network byte order. .Dv TUNSLMODE and .Dv TUNSIFHEAD are mutually exclusive. In any case, the packet data follows immediately. .Pp A .Xr write 2 call passes a packet in to be .Dq received on the pseudo-interface. If the .Dv TUNSIFHEAD ioctl has been set, the address family must be prepended, otherwise the packet is assumed to be of type .Dv AF_INET . Each .Xr write 2 call supplies exactly one packet; the packet length is taken from the amount of data provided to .Xr write 2 (minus any supplied address family). Writes will not block; if the packet cannot be accepted for a transient reason (e.g., no buffer space available), it is silently dropped; if the reason is not transient (e.g., packet too large), an error is returned. .Pp The following .Xr ioctl 2 calls are supported (defined in .In net/if_tun.h ) : .Bl -tag -width ".Dv TUNSIFMODE" .It Dv TUNSDEBUG The argument should be a pointer to an .Vt int ; this sets the internal debugging variable to that value. What, if anything, this variable controls is not documented here; see the source code. .It Dv TUNGDEBUG The argument should be a pointer to an .Vt int ; this stores the internal debugging variable's value into it. .It Dv TUNSIFINFO The argument should be a pointer to an .Vt struct tuninfo and allows setting the MTU, the type, and the baudrate of the tunnel device. The .Vt struct tuninfo is declared in .In net/if_tun.h . .Pp The use of this ioctl is restricted to the super-user. .It Dv TUNGIFINFO The argument should be a pointer to an .Vt struct tuninfo , where the current MTU, type, and baudrate will be stored. .It Dv TUNSIFMODE The argument should be a pointer to an .Vt int ; its value must be either .Dv IFF_POINTOPOINT or .Dv IFF_BROADCAST and should have .Dv IFF_MULTICAST OR'd into the value if multicast support is required. The type of the corresponding .Dq Li tun Ns Ar N interface is set to the supplied type. If the value is outside the above range, an .Er EINVAL error is returned. The interface must be down at the time; if it is up, an .Er EBUSY error is returned. .It Dv TUNSLMODE The argument should be a pointer to an .Vt int ; a non-zero value turns off .Dq multi-af mode and turns on .Dq link-layer mode, causing packets read from the tunnel device to be prepended with the network destination address (see above). .It Dv TUNSIFPID Will set the pid owning the tunnel device to the current process's pid. .It Dv TUNSIFHEAD The argument should be a pointer to an .Vt int ; a non-zero value turns off .Dq link-layer mode, and enables .Dq multi-af mode, where every packet is preceded with a four byte address family. .It Dv TUNGIFHEAD The argument should be a pointer to an .Vt int ; the ioctl sets the value to one if the device is in .Dq multi-af mode, and zero otherwise. .It Dv FIONBIO Turn non-blocking I/O for reads off or on, according as the argument .Vt int Ns 's value is or is not zero. (Writes are always non-blocking.) .It Dv FIOASYNC Turn asynchronous I/O for reads (i.e., generation of .Dv SIGIO when data is available to be read) off or on, according as the argument .Vt int Ns 's value is or is not zero. .It Dv FIONREAD If any packets are queued to be read, store the size of the first one into the argument .Vt int ; otherwise, store zero. .It Dv TIOCSPGRP Set the process group to receive .Dv SIGIO signals, when asynchronous I/O is enabled, to the argument .Vt int value. .It Dv TIOCGPGRP Retrieve the process group value for .Dv SIGIO signals into the argument .Vt int value. .El .Pp The control device also supports .Xr select 2 for read; selecting for write is pointless, and always succeeds, since writes are always non-blocking. .Pp On the last close of the data device, by default, the interface is brought down (as if with .Nm ifconfig Ar tunN Cm down ) . All queued packets are thrown away. If the interface is up when the data device is not open output packets are always thrown away rather than letting them pile up. .Sh SEE ALSO .Xr ioctl 2 , .Xr read 2 , .Xr select 2 , .Xr write 2 , .Xr devname 3 , .Xr inet 4 , .Xr intro 4 , .Xr pty 4 , .Xr tap 4 , .Xr ifconfig 8 .Sh AUTHORS This manual page was originally obtained from .Nx . Index: head/share/man/man4/umass.4 =================================================================== --- head/share/man/man4/umass.4 (revision 275990) +++ head/share/man/man4/umass.4 (revision 275991) @@ -1,262 +1,262 @@ .\" Copyright (c) 1999 .\" Nick Hibma . 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 April 19, 2014 .Dt UMASS 4 .Os .Sh NAME .Nm umass .Nd USB Mass Storage Devices driver .Sh SYNOPSIS To compile this driver into the kernel, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "device scbus" .Cd "device usb" .Cd "device umass" .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 umass_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for Mass Storage devices that attach to the USB port. .Pp To use the .Nm driver, .Xr usb 4 and one of .Xr uhci 4 or .Xr ohci 4 or .Xr ehci 4 -or +or .Xr xhci 4 must be configured in the kernel. Additionally, since .Nm uses the SCSI subsystem and sometimes acts as a SCSI device, it requires .Xr da 4 and .Xr scbus 4 to be included in the kernel. .Sh HARDWARE The .Nm driver supports USB Mass Storage devices, including: .Pp .Bl -bullet -compact .It ADTEC Stick Drive AD-UST32M, 64M, 128M, 256M .It Denno FireWire/USB2 Removable 2.5-inch HDD Case MIFU-25CB20 .It FujiFilm Zip USB Drive ZDR100 USB A .It GREEN HOUSE USB Flash Memory "PicoDrive" GH-UFD32M, 64M, 128M .It Huawei Mobile (SD slot) .It IBM 32MB USB Memory Key (P/N 22P5296) .It IBM 256MB USB Drive (MSYSTEM DiskOnKey2) .It IBM ThinkPad USB Portable CD-ROM Drive (P/N 33L5151) .It I-O DATA USB CD/CD-R/CD-RW/DVD-R/DVD-RW/DVD-RAM/DVD-ROM Drive DVR-iUH2 (CDROM, DVD-RAM only) .It I-O DATA USB x6 CD-RW Drive CDRW-i64/USB (CDROM only) .It I-O DATA USB/IEEE1394 Portable HD Drive HDP-i30P/CI, HDP-i40P/CI .It Iomega USB Zip 100/250 drive .It Iomega Zip750 USB2.0 drive .It Keian USB1.1/2.0 3.5-inch HDD Case KU350A .It Kurouto Shikou USB 2.5-inch HDD Case GAWAP2.5PS-USB2.0 .It LaCie P3 HardDrive USB 200GB .It Logitec LDR-H443U2 DVD-RAM/-R/+R/-RW/+RW drive .It Logitec Mobile USB Memory LMC-256UD .It Logitec USB1.1/2.0 HDD Unit SHD-E60U2 .It Logitec USB Double-Speed Floppy Drive LFD-31U2 .It Logitec USB/IEEE1394 DVD-RAM/R/RW Unit LDR-N21FU2 (CDROM only) .It MELCO USB Flash Disk "ClipDrive", RUF-C32M, -C64M, -C128M, -C256M, -C512M .It MELCO USB Flash Disk "PetitDrive", RUF-32M, -64M, -128M, -256Mm .It MELCO USB2.0 Flash Disk "PetitDrive2", RUF-256M/U2, -512M/U2 .It MELCO USB2.0 MO Drive MO-CH640U2 .It Matshita CF-VFDU03 floppy drive .It Merlin SM300 MP3/WMA Player (256Mb) .It Microtech International, Inc.\& USB-SCSI-HD 50 USB to SCSI cable .It Motorola E398 Mobile Phone (TransFlash memory card) .It NOVAC USB2.0 2.5/3.5-inch HDD Case NV-HD351U .It PNY Attache Flash Drive .It Panasonic ("Matshita FDD CF-VFDU03") .It Panasonic KXL-CB20AN Portable DVD-ROM/CD-R/RW .It Panasonic KXL-CB35AN (DVD-ROM & CD-R/RW) .It Panasonic USB2.0 Portable CD-RW Drive KXL-RW40AN (CDROM only) .It Panasonic floppy drive .It Qware BeatZkey!\& Pro .It RATOC Systems USB2.0 Removable HDD Case U2-MDK1, U2-MDK1B .It SanDisk SDDR-31 (Compact Flash) .It SanDisk SDDR-75 (only Compact Flash port works) .It Sitecom CN-300 MultiFlash (MMC/SD, SmartMedia, CF, MemoryStick) .It Sony Portable CD-R/RW Drive CRX10U (CDROM only) .It TEAC Portable USB CD-ROM Unit CD-110PU/210PU .It Time DPA20B MP3 Player (1Gb) .It Trek Thumbdrive 8MB .It VAIO floppy drive (includes Y-E Data Flashbuster-U) .It Y-E Data floppy drive (720/1.44/2.88Mb) .El .Pp Among the supported digital cameras are: .Pp .Bl -bullet -compact .It Asahi Optical (PENTAX) Optio 230 & 330 .El .Sh EXAMPLES .Bd -literal -offset indent device umass device scbus device da device pass .Ed .Pp Add the .Nm driver to the kernel. .Pp .Dl "camcontrol rescan 0" .Pp Rescan a Zip drive that was added after boot. The command above assumes that the Zip drive is on the first SCSI bus in the system. .Bd -literal -offset indent camcontrol rescan 0:0:0 camcontrol rescan 0:0:1 camcontrol rescan 0:0:2 camcontrol rescan 0:0:3 .Ed .Pp Rescan all slots on a multi-slot flash reader, where the slots map to separate LUNs on a single SCSI ID. Typically only the first slot will be enabled at boot time. Again, this assumes that the flash reader is the first SCSI bus in the system. .Bd -literal -offset indent bsdlabel -w da0 zip100 newfs da0c mount -t ufs /dev/da0c /mnt .Ed .Pp Write a disklabel to the Zip drive (see .Xr vpo 4 for the .Xr disktab 5 entry), creates the file system and mounts the new file system on /mnt. .Pp .Dl "newfs_msdos /dev/da0" .Pp Create a new FAT type file system. Care should be taken not to run .Xr newfs 8 on devices that already contain data, as this will result in the information being lost. .Pp Many consumer devices such as digital cameras automatically create .Tn MS-DOS based file systems when storing information such as images and videos. These file systems can be accessed by specifying the file system type as .Cm msdosfs when using .Xr mount 8 . .Sh SEE ALSO .Xr ehci 4 , .Xr xhci 4 , .Xr ohci 4 , .Xr uhci 4 , .Xr usb 4 , .Xr vpo 4 , .Xr disktab 5 , .Xr bsdlabel 8 , .Xr camcontrol 8 .\".Sh HISTORY .Sh AUTHORS .An -nosplit The .Nm driver was written by .An MAEKAWA Masahide Aq Mt bishop@rr.iij4u.or.jp and .An Nick Hibma Aq Mt n_hibma@FreeBSD.org . .Pp This manual page was written by .An Nick Hibma Aq Mt n_hibma@FreeBSD.org . Index: head/share/man/man4/wsp.4 =================================================================== --- head/share/man/man4/wsp.4 (revision 275990) +++ head/share/man/man4/wsp.4 (revision 275991) @@ -1,90 +1,90 @@ .\" Copyright (c) 2014 Hans Petter Selasky . .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" 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 February 7, 2014 .Dt WSP 4 .Os .Sh NAME .Nm wsp .Nd Wellspring touchpad driver .Sh SYNOPSIS To compile this driver into the kernel, place the following lines into your kernel configuration file: .Bd -ragged -offset indent .Cd "device wsp" .Cd "device usb" .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 wsp_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for the Apple Internal Trackpad device found in many Apple laptops. .Pp The driver simulates a three-button mouse using multi-finger tap detection. -A single-finger press generates a left button click. +A single-finger press generates a left button click. A two-finger tap maps to the right button; whereas a three-finger tap gets treated as a middle button click. .Pp .Nm supports dynamic reconfiguration using .Xr sysctl 8 through nodes under .Nm hw.usb.wsp . Pointer sensitivity can be controlled using the sysctl tunable .Nm hw.usb.wsp.scale_factor . .Sh FILES .Nm creates a blocking pseudo-device file, .Pa /dev/wsp0 , which presents the mouse as a .Em sysmouse or .Em mousesystems type device--see .Xr moused 8 for an explanation of these mouse types. .Sh SEE ALSO .Xr sysmouse 4 , .Xr usb 4 , .Xr loader.conf 5 , .Xr xorg.conf 5 Pq Pa ports/x11/xorg , .Xr moused 8 , .Xr sysctl 8 .Sh AUTHORS .An -nosplit The .Nm driver was written by .An Huang Wen Hui Aq Mt huanghwh@gmail.com .