Index: stable/9/share/man/man4/acpi_hp.4 =================================================================== --- stable/9/share/man/man4/acpi_hp.4 (revision 290885) +++ stable/9/share/man/man4/acpi_hp.4 (revision 290886) @@ -1,288 +1,287 @@ .\" Copyright (c) 2009 Michael Gmelin .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd February 8, 2010 .Dt ACPI_HP 4 .Os .Sh NAME .Nm acpi_hp .Nd "ACPI extras driver for HP laptops" .Sh SYNOPSIS To compile this driver into the kernel, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "device acpi_hp" .Ed .Pp Alternatively, to load the driver as a module at boot time, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent acpi_hp_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for ACPI-controlled features found on HP laptops that use a WMI enabled BIOS (e.g. HP Compaq 8510p and 6510p). .Pp The main purpose of this driver is to provide an interface, accessible via .Xr sysctl 8 , .Xr devd 8 and .Xr devfs 8 , through which applications can determine and change the status of various laptop components and BIOS settings. .Pp .Ss Xr devd 8 Ss Events Devd events received by .Xr devd 8 provide the following information: .Pp .Bl -tag -width "subsystem" -offset indent -compact .It system .Qq Li ACPI .It subsystem .Qq Li HP .It type The source of the event in the ACPI namespace. The value depends on the model. .It notify Event code (see below). .El .Pp Event codes: .Pp .Bl -tag -width "0xc0" -offset indent -compact .It Li 0xc0 WLAN on air status changed to 0 (not on air) .It Li 0xc1 WLAN on air status changed to 1 (on air) .It Li 0xd0 Bluetooth on air status changed to 0 (not on air) .It Li 0xd1 Bluetooth on air status changed to 1 (on air) .It Li 0xe0 WWAN on air status changed to 0 (not on air) .It Li 0xe1 WWAN on air status changed to 1 (on air) .El .Ss Xr devfs 8 Ss Device You can read /dev/hpcmi to see your current BIOS settings. The detail level can be adjusted by setting the sysctl .Va cmi_detail as described below. .Sh SYSCTL VARIABLES The following sysctls are currently implemented: .Ss WLAN: .Bl -tag -width indent .It Va dev.acpi_hp.0.wlan_enabled Toggle WLAN chip activity. .It Va dev.acpi_hp.0.wlan_radio (read-only) WLAN radio status (controlled by hardware switch) .It Va dev.acpi_hp.0.wlan_on_air (read-only) WLAN on air (chip enabled, hardware switch enabled + enabled in BIOS) .It Va dev.acpi_hp.0.wlan_enabled_if_radio_on If set to 1, the WLAN chip will be enabled if the radio is turned on .It Va dev.acpi_hp.0.wlan_disable_if_radio_off If set to 1, the WLAN chip will be disabled if the radio is turned off .El .Ss Bluetooth: .Bl -tag -width indent .It Va dev.acpi_hp.0.bt_enabled Toggle Bluetooth chip activity. .It Va dev.acpi_hp.0.bt_radio (read-only) Bluetooth radio status (controlled by hardware switch) .It Va dev.acpi_hp.0.bt_on_air (read-only) Bluetooth on air (chip enabled, hardware switch enabled + enabled in BIOS) .It Va dev.acpi_hp.0.bt_enabled_if_radio_on If set to 1, the Bluetooth chip will be enabled if the radio is turned on .It Va dev.acpi_hp.0.bt_disable_if_radio_off If set to 1, the Bluetooth chip will be disabled if the radio is turned off .El .Ss WWAN: .Bl -tag -width indent .It Va dev.acpi_hp.0.wwan_enabled Toggle WWAN chip activity. .It Va dev.acpi_hp.0.wwan_radio (read-only) WWAN radio status (controlled by hardware switch) .It Va dev.acpi_hp.0.wwan_on_air (read-only) WWAN on air (chip enabled, hardware switch enabled + enabled in BIOS) .It Va dev.acpi_hp.0.wwan_enabled_if_radio_on If set to 1, the WWAN chip will be enabled if the radio is turned on .It Va dev.acpi_hp.0.wwan_disable_if_radio_off If set to 1, the WWAN chip will be disabled if the radio is turned off .El .Ss Misc: .Bl -tag -width indent .It Va dev.acpi_hp.0.als_enabled Toggle ambient light sensor (ALS) .It Va dev.acpi_hp.0.display (read-only) Display status (bitmask) .It Va dev.acpi_hp.0.hdd_temperature (read-only) HDD temperature .It Va dev.acpi_hp.0.is_docked (read-only) Docking station status (1 if docked) .It Va dev.acpi_hp.0.cmi_detail Bitmask to control detail level in /dev/hpcmi output (values can be ORed). .Bl -tag -width "0x01" -offset indent -compact .It Li 0x01 Show path component of BIOS setting .It Li 0x02 Show a list of valid options for the BIOS setting .It Li 0x04 Show additional flags of BIOS setting (ReadOnly etc.) .It Li 0x08 Query highest BIOS entry instance. This is broken on many HP models and therefore disabled by default. .El .It Va dev.acpi_hp.0.verbose (read-only) Set verbosity level .El .Pp Defaults for these sysctls can be set in .Xr sysctl.conf 5 . .Sh HARDWARE The .Nm driver has been reported to support the following hardware: .Pp .Bl -bullet -compact .It HP Compaq 8510p .It HP Compaq nx7300 .El .Pp It should work on most HP laptops that feature a WMI enabled BIOS. .Sh FILES .Bl -tag -width ".Pa /dev/hpcmi" .It Pa /dev/hpcmi Interface to read BIOS settings .El .Sh EXAMPLES The following can be added to .Xr devd.conf 5 in order disable the LAN interface when WLAN on air and reenable if it's not: .Bd -literal -offset indent notify 0 { match "system" "ACPI"; match "subsystem" "HP"; match "notify" "0xc0"; action "ifconfig em0 up"; }; notify 0 { match "system" "ACPI"; match "subsystem" "HP"; match "notify" "0xc1"; action "ifconfig em0 down"; }; .Ed .Pp Enable the ambient light sensor: .Bd -literal -offset indent sysctl dev.acpi_hp.0.als_enabled=1 .Ed .Pp Enable Bluetooth: .Bd -literal -offset indent sysctl dev.acpi_hp.0.bt_enabled=1 .Ed .Pp Get BIOS settings: .Bd -literal -offset indent cat /dev/hpcmi Serial Port Disable Infrared Port Enable Parallel Port Disable Flash Media Reader Disable USB Ports including Express Card slot Enable 1394 Port Enable Cardbus Slot Disable Express Card Slot Disable (...) .Ed .Pp Set maximum detail level for /dev/hpcmi output: .Bd -literal -offset indent sysctl dev.acpi_hp.0.cmi_detail=7 .Ed -.Pp .Sh SEE ALSO .Xr acpi 4 , .Xr acpi_wmi 4 , .Xr sysctl.conf 5 , .Xr devd 8 , .Xr devfs 8 , .Xr sysctl 8 .Sh HISTORY The .Nm device driver first appeared in .Fx 8.0 . .Sh AUTHORS .An -nosplit The .Nm driver was written by .An Michael Gmelin Aq freebsd@grem.de . .Pp It has been inspired by hp-wmi driver, which implements a subset of these features (hotkeys) on Linux. .Bl -tag -width indent .It HP CMI whitepaper: http://h20331.www2.hp.com/Hpsub/downloads/cmi_whitepaper.pdf .It wmi-hp for Linux: http://www.kernel.org .It WMI and ACPI: http://www.microsoft.com/whdc/system/pnppwr/wmi/wmi-acpi.mspx .El .Pp This manual page was written by .An Michael Gmelin Aq freebsd@grem.de . .Sh BUGS This driver is experimental and has only been tested on i386 on an HP Compaq 8510p which featured all supported wireless devices (WWAN/BT/WLAN). Expect undefined results when operating on different hardware. .Pp Loading the driver is slow. Reading from /dev/hpcmi is even slower. .Pp Additional features like HP specific sensor readings or writing BIOS settings are not supported. Index: stable/9/share/man/man4/adv.4 =================================================================== --- stable/9/share/man/man4/adv.4 (revision 290885) +++ stable/9/share/man/man4/adv.4 (revision 290886) @@ -1,246 +1,243 @@ .\" .\" Copyright (c) 1998, 2000 .\" Justin T. Gibbs. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd August 8, 2004 .Dt ADV 4 .Os .Sh NAME .Nm adv .Nd Advansys ISA/VL/EISA/PCI 8bit SCSI Host adapter driver .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device scbus" .Cd "device adv" .Pp For one or more EISA cards: .Cd "device eisa" .Pp For one or more VL/ISA cards: .Cd "device isa" .Pp In .Pa /boot/device.hints : .Cd hint.adv.0.at="isa" .Pp For one or more PCI cards: .Cd "device pci" .Ed .Sh DESCRIPTION This driver provides access to the 8bit .Tn SCSI bus connected to the Advanced Systems Products, Inc. .Tn ASC900 , .Tn ASC1000 , .Tn ASC1090 , .Tn ASC1200 , .Tn ASC3030 , .Tn ASC3050 , and .Tn ASC3150 host adapter chips. The following tables list the AdvanSys products using these chips, their bus attachment type, maximum sync rate, and the maximum number of commands that can be handled by the adapter concurrently. -.Pp .Bd -ragged -offset indent .Bl -column "ABP510/5150 " "ISA PnP " "Yes " "10MHz " "Commands " Footnotes Connectivity Products: .Pp .Em "Adapter Bus Floppy MaxSync Commands Footnotes" ABP510/5150 ISA No 10MHz 240 1 ABP5140 ISA PnP No 10MHz 16 1, 3 ABP5142 ISA PnP Yes 10MHz 16 4 ABP[3]902 PCI No 10MHz 16 ABP3905 PCI No 10MHz 16 ABP915 PCI No 10MHz 16 ABP920 PCI No 10MHz 16 ABP3922 PCI No 10MHz 16 ABP3925 PCI No 10MHz 16 ABP930 PCI No 10MHz 16 5 ABP930U PCI No 20MHz 16 ABP930UA PCI No 20MHz 16 ABP960 PCI No 10MHz 16 ABP960U PCI No 20MHz 16 .El .Pp Footnotes: .Bl -enum -compact .It This board has been shipped by HP with the 4020i CD-R drive. The board has no BIOS so it cannot control a boot device, but it can control any secondary SCSI device. .It This board has been sold by Iomega as a Jaz Jet PCI adapter. .It This board has been sold by SIIG as the i540 SpeedMaster. .It This board has been sold by SIIG as the i542 SpeedMaster. .It This board has been sold by SIIG as the Fast SCSI Pro PCI. .El .Ed -.Pp .Bd -ragged -offset indent .Bl -column "ABP510/5150 " "ISA PnP " "Yes " "10MHz " Commands Single Channel Products: .Pp .Em "Adapter Bus Floppy MaxSync Commands" ABP542 ISA Yes 10MHz 240 ABP742 EISA Yes 10MHz 240 ABP842 VL Yes 10MHz 240 ABP940 PCI No 10MHz 240 ABP[3]940UA PCI No 20MHz 240 ABP940U PCI No 20MHz 240 ABP3960UA PCI No 20MHz 240 ABP970 PCI No 10MHz 240 ABP970U PCI No 20MHz 240 .El .Ed -.Pp .Bd -ragged -offset indent .Bl -column "ABP510/5150 " "ISA PnP " "Yes " "10MHz " "Commands " "Channels " Multi Channel Products (Commands are per-channel): .Pp .Em "Adapter Bus Floppy MaxSync Commands Channels" ABP752 EISA Yes 10MHz 240 2 ABP852 VL Yes 10MHz 240 2 ABP950 PCI No 10MHz 240 2 ABP980 PCI No 10MHz 240 4 ABP980U PCI No 20MHz 240 4 ABP[3]980UA PCI No 20MHz 16 4 .El .Ed .Pp .\" For ISA or Vesa Local Bus adapters, one kernel config entry is required .\" for every card to be attached by the system. Specific values for the port .\" address, irq, and drq may be specified. If wildcard values are used, the .\" driver will query the device for its current settings and use those. If .\" the port address is a wildcard, the driver consults an internal table of .\" possible port address locations and attaches to the first unattached card .\" it finds. The possible port addresses for these card are 0x110, 0x130, .\" 0x150, 0x190, 0x210, 0x230, 0x250, and 0x330. .\" .Pp Per target configuration performed in the .Tn AdvanceWare menu, which is accessible at boot, is honored by this driver. This includes synchronous/asynchronous transfers, maximum synchronous negotiation rate, disconnection, tagged queueing, and the host adapter's SCSI ID. The global setting for the maximum number of tagged transactions allowed per target is not honored as the CAM SCSI system will automatically determine the maximum number of tags a device can receive as well as guarantee fair resource allocation among devices. .Sh HARDWARE The .Nm driver supports the following SCSI controllers: .Pp .Bl -bullet -compact .It AdvanSys ABP510/5150 .It AdvanSys ABP5140 .It AdvanSys ABP5142 .It AdvanSys ABP902/3902 .It AdvanSys ABP3905 .It AdvanSys ABP915 .It AdvanSys ABP920 .It AdvanSys ABP3922 .It AdvanSys ABP3925 .It AdvanSys ABP930, ABP930U, ABP930UA .It AdvanSys ABP960, ABP960U .It AdvanSys ABP542 .It AdvanSys ABP742 .It AdvanSys ABP842 .It AdvanSys ABP940 .It AdvanSys ABP940UA/3940UA .It AdvanSys ABP940U .It AdvanSys ABP3960UA .It AdvanSys ABP970, ABP970U .It AdvanSys ABP752 .It AdvanSys ABP852 .It AdvanSys ABP950 .It AdvanSys ABP980, ABP980U .It AdvanSys ABP980UA/3980UA .It MELCO IFC-USP (PC-98) .It RATOC REX-PCI30 (PC-98) .It @Nifty FNECHARD IFC-USUP-TX (PC-98) .El .Sh SEE ALSO .Xr adw 4 , .Xr aha 4 , .Xr ahb 4 , .Xr ahc 4 , .Xr cd 4 , .Xr da 4 , .Xr sa 4 , .Xr scsi 4 .Sh HISTORY The .Nm driver appeared in .Fx 3.0 . .Sh AUTHORS .An -nosplit The .Nm driver was ported by .An Justin T. Gibbs from the Linux driver written by .An Bob Frey of Advanced System Products, Inc. Many thanks to AdvanSys for providing the original driver under a suitable license for use in .Fx . Index: stable/9/share/man/man4/ahc.4 =================================================================== --- stable/9/share/man/man4/ahc.4 (revision 290885) +++ stable/9/share/man/man4/ahc.4 (revision 290886) @@ -1,447 +1,446 @@ .\" .\" Copyright (c) 1995, 1996, 1997, 1998, 2000 .\" Justin T. Gibbs. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd July 13, 2008 .Dt AHC 4 .Os .Sh NAME .Nm ahc .Nd Adaptec VL/EISA/PCI SCSI host adapter driver .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device scbus" .Cd "device ahc" .Pp For one or more VL/EISA cards: .Cd "device eisa" .Pp For one or more PCI cards: .Cd "device pci" .Pp To allow PCI adapters to use memory mapped I/O if enabled: .Cd options AHC_ALLOW_MEMIO .Pp To configure one or more controllers to assume the target role: .Cd options AHC_TMODE_ENABLE .Ed .Pp Alternatively, to load the driver as a module at boot time, place the following lines in .Xr loader.conf 5 : .Bd -literal -offset indent ahc_load="YES" ahc_eisa_load="YES" ahc_isa_load="YES" ahc_pci_load="YES" .Ed .Sh DESCRIPTION This driver provides access to the .Tn SCSI bus(es) connected to the Adaptec AIC77xx and AIC78xx host adapter chips. .Pp Driver features include support for twin and wide busses, fast, ultra or ultra2 synchronous transfers depending on controller type, tagged queueing, SCB paging, and target mode. .Pp Memory mapped I/O can be enabled for PCI devices with the .Dq Dv AHC_ALLOW_MEMIO configuration option. Memory mapped I/O is more efficient than the alternative, programmed I/O. Most PCI BIOSes will map devices so that either technique for communicating with the card is available. In some cases, usually when the PCI device is sitting behind a PCI->PCI bridge, the BIOS may fail to properly initialize the chip for memory mapped I/O. The typical symptom of this problem is a system hang if memory mapped I/O is attempted. Most modern motherboards perform the initialization correctly and work fine with this option enabled. .Pp Individual controllers may be configured to operate in the target role through the .Dq Dv AHC_TMODE_ENABLE configuration option. The value assigned to this option should be a bitmap of all units where target mode is desired. For example, a value of 0x25, would enable target mode on units 0, 2, and 5. A value of 0x8a enables it for units 1, 3, and 7. .Pp Per target configuration performed in the .Tn SCSI-Select menu, accessible at boot in .No non- Ns Tn EISA models, or through an .Tn EISA configuration utility for .Tn EISA models, is honored by this driver. This includes synchronous/asynchronous transfers, maximum synchronous negotiation rate, wide transfers, disconnection, the host adapter's SCSI ID, and, in the case of .Tn EISA Twin Channel controllers, the primary channel selection. For systems that store non-volatile settings in a system specific manner rather than a serial eeprom directly connected to the aic7xxx controller, the .Tn BIOS must be enabled for the driver to access this information. This restriction applies to all .Tn EISA and many motherboard configurations. .Pp Note that I/O addresses are determined automatically by the probe routines, but care should be taken when using a 284x .Pq Tn VESA No local bus controller in an .Tn EISA system. The jumpers setting the I/O area for the 284x should match the .Tn EISA slot into which the card is inserted to prevent conflicts with other .Tn EISA cards. .Pp Performance and feature sets vary throughout the aic7xxx product line. The following table provides a comparison of the different chips supported by the .Nm driver. Note that wide and twin channel features, although always supported by a particular chip, may be disabled in a particular motherboard or card design. -.Pp .Bd -ragged -offset indent .Bl -column "aic7770 " "10 " "EISA/VL " "10MHz " "16bit " "SCBs " Features .Em "Chip MIPS Bus MaxSync MaxWidth SCBs Features" aic7770 10 EISA/VL 10MHz 16Bit 4 1 aic7850 10 PCI/32 10MHz 8Bit 3 aic7860 10 PCI/32 20MHz 8Bit 3 aic7870 10 PCI/32 10MHz 16Bit 16 aic7880 10 PCI/32 20MHz 16Bit 16 aic7890 20 PCI/32 40MHz 16Bit 16 3 4 5 6 7 8 aic7891 20 PCI/64 40MHz 16Bit 16 3 4 5 6 7 8 aic7892 20 PCI/64 80MHz 16Bit 16 3 4 5 6 7 8 aic7895 15 PCI/32 20MHz 16Bit 16 2 3 4 5 aic7895C 15 PCI/32 20MHz 16Bit 16 2 3 4 5 8 aic7896 20 PCI/32 40MHz 16Bit 16 2 3 4 5 6 7 8 aic7897 20 PCI/64 40MHz 16Bit 16 2 3 4 5 6 7 8 aic7899 20 PCI/64 80MHz 16Bit 16 2 3 4 5 6 7 8 .El .Pp .Bl -enum -compact .It Multiplexed Twin Channel Device - One controller servicing two busses. .It Multi-function Twin Channel Device - Two controllers on one chip. .It Command Channel Secondary DMA Engine - Allows scatter gather list and SCB prefetch. .It 64 Byte SCB Support - SCSI CDB is embedded in the SCB to eliminate an extra DMA. .It Block Move Instruction Support - Doubles the speed of certain sequencer operations. .It .Sq Bayonet style Scatter Gather Engine - Improves S/G prefetch performance. .It Queuing Registers - Allows queueing of new transactions without pausing the sequencer. .It Multiple Target IDs - Allows the controller to respond to selection as a target on multiple SCSI IDs. .El .Ed .Sh HARDWARE The .Nm driver supports the following .Tn SCSI host adapter chips and .Tn SCSI controller cards: .Pp .Bl -bullet -compact .It Adaptec .Tn AIC7770 host adapter chip .It Adaptec .Tn AIC7850 host adapter chip .It Adaptec .Tn AIC7860 host adapter chip .It Adaptec .Tn AIC7870 host adapter chip .It Adaptec .Tn AIC7880 host adapter chip .It Adaptec .Tn AIC7890 host adapter chip .It Adaptec .Tn AIC7891 host adapter chip .It Adaptec .Tn AIC7892 host adapter chip .It Adaptec .Tn AIC7895 host adapter chip .It Adaptec .Tn AIC7896 host adapter chip .It Adaptec .Tn AIC7897 host adapter chip .It Adaptec .Tn AIC7899 host adapter chip .It Adaptec .Tn 274X(W) .It Adaptec .Tn 274X(T) .It Adaptec .Tn 284X .It Adaptec .Tn 2910 .It Adaptec .Tn 2915 .It Adaptec .Tn 2920C .It Adaptec .Tn 2930C .It Adaptec .Tn 2930U2 .It Adaptec .Tn 2940 .It Adaptec .Tn 2940J .It Adaptec .Tn 2940N .It Adaptec .Tn 2940U .It Adaptec .Tn 2940AU .It Adaptec .Tn 2940UW .It Adaptec .Tn 2940UW Dual .It Adaptec .Tn 2940UW Pro .It Adaptec .Tn 2940U2W .It Adaptec .Tn 2940U2B .It Adaptec .Tn 2950U2W .It Adaptec .Tn 2950U2B .It Adaptec .Tn 19160B .It Adaptec .Tn 29160B .It Adaptec .Tn 29160N .It Adaptec .Tn 3940 .It Adaptec .Tn 3940U .It Adaptec .Tn 3940AU .It Adaptec .Tn 3940UW .It Adaptec .Tn 3940AUW .It Adaptec .Tn 3940U2W .It Adaptec .Tn 3950U2 .It Adaptec .Tn 3960 .It Adaptec .Tn 39160 .It Adaptec .Tn 3985 .It Adaptec .Tn 4944UW .It NEC PC-9821Xt13 (PC-98) .It NEC RvII26 (PC-98) .It NEC PC-9821X-B02L/B09 (PC-98) .It NEC SV-98/2-B03 (PC-98) .It Many motherboards with on-board .Tn SCSI support .El .Sh SCSI CONTROL BLOCKS (SCBs) Every transaction sent to a device on the SCSI bus is assigned a .Sq SCSI Control Block (SCB). The SCB contains all of the information required by the controller to process a transaction. The chip feature table lists the number of SCBs that can be stored in on-chip memory. All chips with model numbers greater than or equal to 7870 allow for the on chip SCB space to be augmented with external SRAM up to a maximum of 255 SCBs. Very few Adaptec controller configurations have external SRAM. .Pp If external SRAM is not available, SCBs are a limited resource. Using the SCBs in a straight forward manner would only allow the driver to handle as many concurrent transactions as there are physical SCBs. To fully utilize the SCSI bus and the devices on it, requires much more concurrency. The solution to this problem is .Em SCB Paging , a concept similar to memory paging. SCB paging takes advantage of the fact that devices usually disconnect from the SCSI bus for long periods of time without talking to the controller. The SCBs for disconnected transactions are only of use to the controller when the transfer is resumed. When the host queues another transaction for the controller to execute, the controller firmware will use a free SCB if one is available. Otherwise, the state of the most recently disconnected (and therefore most likely to stay disconnected) SCB is saved, via dma, to host memory, and the local SCB reused to start the new transaction. This allows the controller to queue up to 255 transactions regardless of the amount of SCB space. Since the local SCB space serves as a cache for disconnected transactions, the more SCB space available, the less host bus traffic consumed saving and restoring SCB data. .Sh SEE ALSO .Xr aha 4 , .Xr ahb 4 , .Xr cd 4 , .Xr da 4 , .Xr sa 4 , .Xr scsi 4 .Sh HISTORY The .Nm driver appeared in .Fx 2.0 . .Sh AUTHORS The .Nm driver, the .Tn AIC7xxx sequencer-code assembler, and the firmware running on the aic7xxx chips was written by .An Justin T. Gibbs . .Sh BUGS Some Quantum drives (at least the Empire 2100 and 1080s) will not run on an .Tn AIC7870 Rev B in synchronous mode at 10MHz. Controllers with this problem have a 42 MHz clock crystal on them and run slightly above 10MHz. This confuses the drive and hangs the bus. Setting a maximum synchronous negotiation rate of 8MHz in the .Tn SCSI-Select utility will allow normal operation. .Pp Although the Ultra2 and Ultra160 products have sufficient instruction ram space to support both the initiator and target roles concurrently, this configuration is disabled in favor of allowing the target role to respond on multiple target ids. A method for configuring dual role mode should be provided. .Pp Tagged Queuing is not supported in target mode. .Pp Reselection in target mode fails to function correctly on all high voltage differential boards as shipped by Adaptec. Information on how to modify HVD board to work correctly in target mode is available from Adaptec. Index: stable/9/share/man/man4/atkbd.4 =================================================================== --- stable/9/share/man/man4/atkbd.4 (revision 290885) +++ stable/9/share/man/man4/atkbd.4 (revision 290886) @@ -1,231 +1,230 @@ .\" .\" Copyright (c) 1999 .\" Kazutaka YOKOTA .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer as .\" the first lines of this file unmodified. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd January 29, 2008 .Dt ATKBD 4 .Os .Sh NAME .Nm atkbd .Nd the AT keyboard interface .Sh SYNOPSIS .Cd "options ATKBD_DFLT_KEYMAP" .Cd "makeoptions ATKBD_DFLT_KEYMAP=_keymap_name_" .Cd "options KBD_DISABLE_KEYMAP_LOAD" .Cd "device atkbd" .Pp In .Pa /boot/device.hints : .Cd hint.atkbd.0.at="atkbdc" .Cd hint.atkbd.0.irq="1" .Sh DESCRIPTION The .Nm driver, together with the .Nm atkbdc driver, provides access to the AT 84 keyboard or the AT enhanced keyboard which is connected to the AT keyboard controller. .Pp This driver is required for the console driver .Xr syscons 4 . .Pp There can be only one .Nm device defined in the kernel configuration file. This device also requires the .Nm atkbdc keyboard controller to be present. The .Em irq number must always be 1; there is no provision of changing the number. .Ss Function Keys The AT keyboard has a number of function keys. They are numbered as follows and can be associated with strings by the .Xr kbdcontrol 1 command. You can use a keyboard map file (see .Xr kbdmap 5 ) to map them to arbitrary keys, particularly the functions in the range from 65 to 96 which are not used by default. .Pp .Bl -tag -width "Function Key Number" -compact .It "Function Key number" Function Key .It "1, 2,...12" F1, F2,...\& F12 .It "13, 14,...24" Shift+F1, Shift+F2,...\& Shift+F12 .It "25, 26,...36" Ctl+F1, Ctl+F2,...\& Ctl+F12 .It "37, 38,...48" Shift+Ctl+F1, Shift+Ctl+F2,...\& Shift+Ctl+F12 .It 49 Home and Numpad 7 (without NumLock) .It 50 Up Arrow and Numpad 8 (without NumLock) .It 51 Page Up and Numpad 9 (without NumLock) .It 52 Numpad - .It 53 Left Arrow and Numpad 4 (without NumLock) .It 54 Numpad 5 (without NumLock) .It 55 Right Arrow and Numpad 6 (without NumLock) .It 56 Numpad + .It 57 End and Numpad 1 (without NumLock) .It 58 Down Arrow and Numpad 2 (without NumLock) .It 59 Page Down and Numpad 3 (without NumLock) .It 60 Ins and Numpad 0 (without NumLock) .It 61 Del .It 62 Left GUI Key .It 63 Right GUI Key .It 64 Menu .It "65, 66,...96" free (not used by default) .El .Pp See the man page for the .Xr kbdcontrol 1 command for how to assign a string to the function key. .Sh DRIVER CONFIGURATION .Ss Kernel Configuration Options The following kernel configuration options control the .Nm driver. .Bl -tag -width ATKBD_DFLT .It Em ATKBD_DFLT_KEYMAP This option sets the default, built-in keymap of the .Nm driver to the named keymap. See .Sx EXAMPLES below. .It Em KBD_DISABLE_KEYMAP_LOAD The keymap can be modified by the .Xr kbdcontrol 1 command. This option will disable this feature and prevent the user from changing key assignment. .El -.Pp .Ss Driver Flags The .Nm driver accepts the following driver flags. They can be set either in .Pa /boot/device.hints , or else from within the boot loader (see .Xr loader 8 ) . .Bl -tag -width FAIL .It bit 0 (FAIL_IF_NO_KBD) By default the .Nm driver will install even if a keyboard is not actually connected to the system. This option prevents the driver from being installed in this situation. .It bit 1 (NO_RESET) When this option is given, the .Nm driver will not reset the keyboard when initializing it. It may be useful for laptop computers whose function keys have special functions and these functions are forgotten when the keyboard is reset. .It bit 2 (ALT_SCANCODESET) Certain keyboards, such as those on some ThinkPad models, behave like the old XT keyboard and require this option. .It bit 3 (NO_PROBE_TEST) When this option is given, the .Nm driver will not test the keyboard port during the probe routine. Some machines hang during boot when this test is performed. .El .\".Sh FILES .Sh EXAMPLES The .Nm driver requires the keyboard controller .Nm atkbdc . Thus, the kernel configuration file should contain the following lines. .Pp .Dl "device atkbdc" .Dl "device atkbd" .Pp The following example shows how to set the default, built-in keymap to .Pa jp.106.kbd . .Pp .Dl "device atkbdc" .Dl "options ATKBD_DFLT_KEYMAP" .Dl "makeoptions ATKBD_DFLT_KEYMAP=jp.106" .Dl "device atkbd" .Pp In both cases, you also need to have following lines in .Pa /boot/device.hints . .Pp .Dl hint.atkbdc.0.at="isa" .Dl hint.atkbdc.0.port="0x060" .Dl hint.atkbd.0.at="atkbdc" .Dl hint.atkbd.0.irq="1" .\".Sh DIAGNOSTICS .\".Sh CAVEATS .\".Sh BUGS .Sh SEE ALSO .Xr kbdcontrol 1 , .Xr atkbdc 4 , .Xr psm 4 , .Xr syscons 4 , .Xr kbdmap 5 , .Xr loader 8 .Sh HISTORY The .Nm driver first appeared in .Fx 3.1 . .Sh AUTHORS .An -nosplit The .Nm driver was written by .An S\(/oren Schmidt Aq sos@FreeBSD.org and .An Kazutaka Yokota Aq yokota@FreeBSD.org . This manual page was written by .An Kazutaka Yokota . Index: stable/9/share/man/man4/bridge.4 =================================================================== --- stable/9/share/man/man4/bridge.4 (revision 290885) +++ stable/9/share/man/man4/bridge.4 (revision 290886) @@ -1,522 +1,521 @@ .\" $NetBSD: bridge.4,v 1.5 2004/01/31 20:14:11 jdc Exp $ .\" .\" Copyright 2001 Wasabi Systems, Inc. .\" All rights reserved. .\" .\" Written by Jason R. Thorpe for Wasabi Systems, Inc. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed for the NetBSD Project by .\" Wasabi Systems, Inc. .\" 4. The name of Wasabi Systems, Inc. may not be used to endorse .\" or promote products derived from this software without specific prior .\" written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY WASABI SYSTEMS, INC. ``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 WASABI SYSTEMS, INC .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd July 27, 2013 .Dt IF_BRIDGE 4 .Os .Sh NAME .Nm if_bridge .Nd network bridge device .Sh SYNOPSIS To compile this driver into the kernel, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "device if_bridge" .Ed .Pp Alternatively, to load the driver as a module at boot time, place the following lines in .Xr loader.conf 5 : .Bd -literal -offset indent if_bridge_load="YES" bridgestp_load="YES" .Ed .Sh DESCRIPTION The .Nm driver creates a logical link between two or more IEEE 802 networks that use the same (or .Dq "similar enough" ) framing format. For example, it is possible to bridge Ethernet and 802.11 networks together, but it is not possible to bridge Ethernet and Token Ring together. .Pp Each .Nm interface is created at runtime using interface cloning. This is most easily done with the .Xr ifconfig 8 .Cm create command or using the .Va cloned_interfaces variable in .Xr rc.conf 5 . .Pp The .Nm interface randomly chooses a link (MAC) address in the range reserved for locally administered addresses when it is created. This address is guaranteed to be unique .Em only across all .Nm interfaces on the local machine. Thus you can theoretically have two bridges on the different machines with the same link addresses. The address can be changed by assigning the desired link address using .Xr ifconfig 8 . .Pp If .Xr sysctl 8 node .Va net.link.bridge.inherit_mac has non-zero value, newly created bridge will inherit MAC address from its first member instead of choosing random link-level address. This will provide more predictable bridge MAC without any additional configuration, but currently this feature is known to break some L2 protocols, for example PPPoE that is provided by .Xr ng_pppoe 4 and .Xr ppp 8 . Now this feature is considered as experimental and is turned off by-default. .Pp A bridge can be used to provide several services, such as a simple 802.11-to-Ethernet bridge for wireless hosts, and traffic isolation. .Pp A bridge works like a switch, forwarding traffic from one interface to another. Multicast and broadcast packets are always forwarded to all interfaces that are part of the bridge. For unicast traffic, the bridge learns which MAC addresses are associated with which interfaces and will forward the traffic selectively. .Pp All the bridged member interfaces need to be up in order to pass network traffic. These can be enabled using .Xr ifconfig 8 or .Va ifconfig_ Ns Ao Ar interface Ac Ns Li ="up" in .Xr rc.conf 5 . .Pp The MTU of the first member interface to be added is used as the bridge MTU. All additional members are required to have exactly the same value. .Pp The TXCSUM capability is disabled for any interface added to the bridge, and it is restored when the interface is removed again. .Pp The bridge supports .Dq monitor mode , where the packets are discarded after .Xr bpf 4 processing, and are not processed or forwarded further. This can be used to multiplex the input of two or more interfaces into a single .Xr bpf 4 stream. This is useful for reconstructing the traffic for network taps that transmit the RX/TX signals out through two separate interfaces. .Sh IPV6 SUPPORT .Nm supports the .Li AF_INET6 address family on bridge interfaces. The following .Xr rc.conf 5 variable configures an IPv6 link-local address on .Li bridge0 interface: .Bd -literal -offset indent ifconfig_bridge0_ipv6="up" .Ed .Pp or in a more explicit manner: .Bd -literal -offset indent ifconfig_bridge0_ipv6="inet6 auto_linklocal" .Ed .Pp However, the .Li AF_INET6 address family has a concept of scope zone. Bridging multiple interfaces change the zone configuration because multiple links are merged to each other and form a new single link while the member interfaces still work individually. This means each member interface still has a separate link-local scope zone and the .Nm interface has another single, aggregated link-local scope zone at the same time. This situation is clearly against the description .Qq zones of the same scope cannot overlap in Section 5, RFC 4007. Although it works in most cases, it can cause some conterintuitive or undesirable behavior in some edge cases when both of the .Nm interface and one of the member interface have an IPv6 address and applications use both of them. .Pp To prevent this situation, .Nm checks whether a link-local scoped IPv6 address is configured on a member interface to be added and the .Nm interface. When the .Nm interface has IPv6 addresses, IPv6 addresses on the member interface will be automatically removed before the interface is added. .Pp This behavior can be disabled by setting .Xr sysctl 8 variable .Va net.link.bridge.allow_llz_overlap to .Li 1 . .Pp Note that .Li ACCEPT_RTADV and .Li AUTO_LINKLOCAL interface flag are not enabled by default on .Nm interface even when .Va net.inet6.ip6.accept_rtadv and/or .Va net.inet6.ip6.auto_linklocal is set to .Li 1 . .Sh SPANNING TREE The .Nm driver implements the Rapid Spanning Tree Protocol (RSTP or 802.1w) with backwards compatibility with the legacy Spanning Tree Protocol (STP). Spanning Tree is used to detect and remove loops in a network topology. .Pp RSTP provides faster spanning tree convergence than legacy STP, the protocol will exchange information with neighbouring switches to quickly transition to forwarding without creating loops. .Pp The code will default to RSTP mode but will downgrade any port connected to a legacy STP network so is fully backward compatible. A bridge can be forced to operate in STP mode without rapid state transitions via the .Va proto command in .Xr ifconfig 8 . .Pp The bridge can log STP port changes to .Xr syslog 3 by enabling the .Va net.link.bridge.log_stp variable using .Xr sysctl 8 . -.Pp .Sh PACKET FILTERING Packet filtering can be used with any firewall package that hooks in via the .Xr pfil 9 framework. When filtering is enabled, bridged packets will pass through the filter inbound on the originating interface, on the bridge interface and outbound on the appropriate interfaces. Either stage can be disabled. The filtering behaviour can be controlled using .Xr sysctl 8 : .Bl -tag -width ".Va net.link.bridge.pfil_onlyip" .It Va net.link.bridge.pfil_onlyip Controls the handling of non-IP packets which are not passed to .Xr pfil 9 . Set to .Li 1 to only allow IP packets to pass (subject to firewall rules), set to .Li 0 to unconditionally pass all non-IP Ethernet frames. .It Va net.link.bridge.pfil_member Set to .Li 1 to enable filtering on the incoming and outgoing member interfaces, set to .Li 0 to disable it. .It Va net.link.bridge.pfil_bridge Set to .Li 1 to enable filtering on the bridge interface, set to .Li 0 to disable it. .It Va net.link.bridge.pfil_local_phys Set to .Li 1 to additionally filter on the physical interface for locally destined packets. Set to .Li 0 to disable this feature. .It Va net.link.bridge.ipfw Set to .Li 1 to enable layer2 filtering with .Xr ipfirewall 4 , set to .Li 0 to disable it. This needs to be enabled for .Xr dummynet 4 support. When .Va ipfw is enabled, .Va pfil_bridge and .Va pfil_member will be disabled so that IPFW is not run twice; these can be re-enabled if desired. .It Va net.link.bridge.ipfw_arp Set to .Li 1 to enable layer2 ARP filtering with .Xr ipfirewall 4 , set to .Li 0 to disable it. Requires .Va ipfw to be enabled. .El .Pp ARP and REVARP packets are forwarded without being filtered and others that are not IP nor IPv6 packets are not forwarded when .Va pfil_onlyip is enabled. IPFW can filter Ethernet types using .Cm mac-type so all packets are passed to the filter for processing. .Pp The packets originating from the bridging host will be seen by the filter on the interface that is looked up in the routing table. .Pp The packets destined to the bridging host will be seen by the filter on the interface with the MAC address equal to the packet's destination MAC. There are situations when some of the bridge members are sharing the same MAC address (for example the .Xr vlan 4 interfaces: they are currently sharing the MAC address of the parent physical interface). It is not possible to distinguish between these interfaces using their MAC address, excluding the case when the packet's destination MAC address is equal to the MAC address of the interface on which the packet was entered to the system. In this case the filter will see the incoming packet on this interface. In all other cases the interface seen by the packet filter is chosen from the list of bridge members with the same MAC address and the result strongly depends on the member addition sequence and the actual implementation of .Nm . It is not recommended to rely on the order chosen by the current .Nm implementation: it can be changed in the future. .Pp The previous paragraph is best illustrated with the following pictures. Let .Bl -bullet .It the MAC address of the incoming packet's destination is .Nm nn:nn:nn:nn:nn:nn , .It the interface on which packet entered the system is .Nm ifX , .It .Nm ifX MAC address is .Nm xx:xx:xx:xx:xx:xx , .It there are possibly other bridge members with the same MAC address .Nm xx:xx:xx:xx:xx:xx , .It the bridge has more than one interface that are sharing the same MAC address .Nm yy:yy:yy:yy:yy:yy ; we will call them .Nm vlanY1 , .Nm vlanY2 , etc. .El .Pp Then if the MAC address .Nm nn:nn:nn:nn:nn:nn is equal to the .Nm xx:xx:xx:xx:xx:xx then the filter will see the packet on the interface .Nm ifX no matter if there are any other bridge members carrying the same MAC address. But if the MAC address .Nm nn:nn:nn:nn:nn:nn is equal to the .Nm yy:yy:yy:yy:yy:yy then the interface that will be seen by the filter is one of the .Nm vlanYn . It is not possible to predict the name of the actual interface without the knowledge of the system state and the .Nm implementation details. .Pp This problem arises for any bridge members that are sharing the same MAC address, not only to the .Xr vlan 4 ones: they we taken just as the example of such situation. So if one wants the filter the locally destined packets based on their interface name, one should be aware of this implication. The described situation will appear at least on the filtering bridges that are doing IP-forwarding; in some of such cases it is better to assign the IP address only to the .Nm interface and not to the bridge members. Enabling .Va net.link.bridge.pfil_local_phys will let you do the additional filtering on the physical interface. .Sh EXAMPLES The following when placed in the file .Pa /etc/rc.conf will cause a bridge called .Dq Li bridge0 to be created, and will add the interfaces .Dq Li wlan0 and .Dq Li fxp0 to the bridge, and then enable packet forwarding. Such a configuration could be used to implement a simple 802.11-to-Ethernet bridge (assuming the 802.11 interface is in ad-hoc mode). .Bd -literal -offset indent cloned_interfaces="bridge0" ifconfig_bridge0="addm wlan0 addm fxp0 up" .Ed .Pp For the bridge to forward packets all member interfaces and the bridge need to be up. The above example would also require: .Bd -literal -offset indent create_args_wlan0="wlanmode hostap" ifconfig_wlan0="up ssid my_ap mode 11g" ifconfig_fxp0="up" .Ed .Pp Consider a system with two 4-port Ethernet boards. The following will cause a bridge consisting of all 8 ports with Rapid Spanning Tree enabled to be created: .Bd -literal -offset indent ifconfig bridge0 create ifconfig bridge0 \e addm fxp0 stp fxp0 \e addm fxp1 stp fxp1 \e addm fxp2 stp fxp2 \e addm fxp3 stp fxp3 \e addm fxp4 stp fxp4 \e addm fxp5 stp fxp5 \e addm fxp6 stp fxp6 \e addm fxp7 stp fxp7 \e up .Ed .Pp The bridge can be used as a regular host interface at the same time as bridging between its member ports. In this example, the bridge connects em0 and em1, and will receive its IP address through DHCP: .Bd -literal -offset indent cloned_interfaces="bridge0" ifconfig_bridge0="addm em0 addm em1 DHCP" ifconfig_em0="up" ifconfig_em1="up" .Ed .Pp The bridge can tunnel Ethernet across an IP internet using the EtherIP protocol. This can be combined with .Xr ipsec 4 to provide an encrypted connection. Create a .Xr gif 4 interface and set the local and remote IP addresses for the tunnel, these are reversed on the remote bridge. .Bd -literal -offset indent ifconfig gif0 create ifconfig gif0 tunnel 1.2.3.4 5.6.7.8 up ifconfig bridge0 create ifconfig bridge0 addm fxp0 addm gif0 up .Ed .Pp Note that .Fx 6.1, 6.2, 6.3, 7.0, 7.1, and 7.2 have a bug in the EtherIP protocol. For more details and workaround, see .Xr gif 4 manual page. .Sh SEE ALSO .Xr gif 4 , .Xr ipf 4 , .Xr ipfw 4 , .Xr pf 4 , .Xr ifconfig 8 .Sh HISTORY The .Nm driver first appeared in .Fx 6.0 . .Sh AUTHORS .An -nosplit The .Nm bridge driver was originally written by .An Jason L. Wright .Aq jason@thought.net as part of an undergraduate independent study at the University of North Carolina at Greensboro. .Pp This version of the .Nm driver has been heavily modified from the original version by .An Jason R. Thorpe .Aq thorpej@wasabisystems.com . .Pp Rapid Spanning Tree Protocol (RSTP) support was added by .An Andrew Thompson .Aq thompsa@FreeBSD.org . .Sh BUGS The .Nm driver currently supports only Ethernet and Ethernet-like (e.g., 802.11) network devices, with exactly the same interface MTU size as the bridge device. Index: stable/9/share/man/man4/cas.4 =================================================================== --- stable/9/share/man/man4/cas.4 (revision 290885) +++ stable/9/share/man/man4/cas.4 (revision 290886) @@ -1,160 +1,159 @@ .\" .\" Copyright (c) 2009 Marius Strobl .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd March 24, 2012 .Dt CAS 4 .Os .Sh NAME .Nm cas .Nd Sun Cassini/Cassini+ and National Semiconductor DP83065 Saturn Gigabit Ethernet driver .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device miibus" .Cd "device cas" .Ed .Pp Alternatively, to load the driver as a module at boot time, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent if_cas_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for the Sun Cassini/Cassini+ and National Semiconductor DP83065 Saturn Gigabit Ethernet controllers found on-board in Sun UltraSPARC machines and as add-on cards. .Pp All controllers supported by the .Nm driver have TCP/UDP checksum offload capability for both receive and transmit, support for the reception and transmission of extended frames for .Xr vlan 4 and an interrupt coalescing/moderation mechanism as well as a 512-bit multicast hash filter. .Pp The .Nm driver also supports Jumbo Frames (up to 9022 bytes), which can be configured via the interface MTU setting. Selecting an MTU larger than 1500 bytes with the .Xr ifconfig 8 utility configures the adapter to receive and transmit Jumbo Frames. .Sh HARDWARE -.Pp The chips supported by the .Nm driver are: .Pp .Bl -bullet -compact .It National Semiconductor DP83065 Saturn Gigabit Ethernet .It Sun Cassini Gigabit Ethernet .It Sun Cassini+ Gigabit Ethernet .El .Pp The following add-on cards are known to work with the .Nm driver at this time: .Pp .Bl -bullet -compact .It Sun GigaSwift Ethernet 1.0 MMF (Cassini Kuheen) (part no.\& 501-5524) .It Sun GigaSwift Ethernet 1.0 UTP (Cassini) (part no.\& 501-5902) .It Sun GigaSwift Ethernet UTP (GCS) (part no.\& 501-6719) .It Sun Quad GigaSwift Ethernet UTP (QGE) (part no.\& 501-6522) .It Sun Quad GigaSwift Ethernet PCI-X (QGE-X) (part no.\& 501-6738) .El .Sh NOTES On sparc64 the .Nm driver respects the .Va local-mac-address? system configuration variable which can be set in the Open Firmware boot monitor using the .Ic setenv command or by .Xr eeprom 8 . If set to .Dq Li false (the default), the .Nm driver will use the system's default MAC address for all of its devices. If set to .Dq Li true , the unique MAC address of each interface is used if present rather than the system's default MAC address. .Pp Supported interfaces having their own MAC address include on-board versions on boards equipped with more than one Ethernet interface and all add-on cards. .Sh SEE ALSO .Xr altq 4 , .Xr miibus 4 , .Xr netintro 4 , .Xr vlan 4 , .Xr eeprom 8 , .Xr ifconfig 8 .Sh HISTORY The .Nm device driver appeared in .Fx 8.0 and .Fx 7.3 . It is named after the .Nm driver which first appeared in .Ox 4.1 and supports the same set of controllers but is otherwise unrelated. .Sh AUTHORS .An -nosplit The .Nm driver was written by .An Marius Strobl .Aq marius@FreeBSD.org based on the .Xr gem 4 driver. Index: stable/9/share/man/man4/cc_vegas.4 =================================================================== --- stable/9/share/man/man4/cc_vegas.4 (revision 290885) +++ stable/9/share/man/man4/cc_vegas.4 (revision 290886) @@ -1,138 +1,136 @@ .\" .\" Copyright (c) 2010-2011 The FreeBSD Foundation .\" All rights reserved. .\" .\" This documentation was written at the Centre for Advanced Internet .\" Architectures, Swinburne University of Technology, Melbourne, Australia by .\" David Hayes under sponsorship from the FreeBSD Foundation. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR .\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd September 15, 2011 .Dt CC_VEGAS 4 .Os .Sh NAME .Nm cc_vegas .Nd Vegas Congestion Control Algorithm .Sh DESCRIPTION The Vegas congestion control algorithm uses what the authors term the actual and expected transmission rates to determine whether there is congestion along the network path i.e. -.Pp .Bl -item -offset indent .It actual rate = (total data sent in a RTT) / RTT .It expected rate = cwnd / RTTmin .It diff = expected - actual .El .Pp where RTT is the measured instantaneous round trip time and RTTmin is the smallest round trip time observed during the connection. .Pp The algorithm aims to keep diff between two parameters alpha and beta, such that: -.Pp .Bl -item -offset indent .It alpha < diff < beta .El .Pp If diff > beta, congestion is inferred and cwnd is decremented by one packet (or the maximum TCP segment size). If diff < alpha, then cwnd is incremented by one packet. Alpha and beta govern the amount of buffering along the path. .Pp The implementation was done in a clean-room fashion, and is based on the paper referenced in the .Sx SEE ALSO section below. .Sh IMPLEMENTATION NOTES The time from the transmission of a marked packet until the receipt of an acknowledgement for that packet is measured once per RTT. This implementation does not implement Brakmo's and Peterson's original duplicate ACK policy since clock ticks in today's machines are not as coarse as they were (i.e. 500ms) when Vegas was originally designed. Note that modern TCP recovery processes such as fast retransmit and SACK are enabled by default in the TCP stack. .Sh MIB Variables The algorithm exposes the following tunable variables in the .Va net.inet.tcp.cc.vegas branch of the .Xr sysctl 3 MIB: .Bl -tag -width ".Va alpha" .It Va alpha Query or set the Vegas alpha parameter as a number of buffers on the path. When setting alpha, the value must satisfy: 0 < alpha < beta. Default is 1. .It Va beta Query or set the Vegas beta parameter as a number of buffers on the path. When setting beta, the value must satisfy: 0 < alpha < beta. Default is 3. .El .Sh SEE ALSO .Xr cc_chd 4 , .Xr cc_cubic 4 , .Xr cc_hd 4 , .Xr cc_htcp 4 , .Xr cc_newreno 4 , .Xr h_ertt 4 , .Xr mod_cc 4 , .Xr tcp 4 , .Xr khelp 9 , .Xr mod_cc 9 .Rs .%A "L. S. Brakmo" .%A "L. L. Peterson" .%T "TCP Vegas: end to end congestion avoidance on a global internet" .%J "IEEE J. Sel. Areas Commun." .%D "October 1995" .%V "13" .%N "8" .%P "1465-1480" .Re .Sh ACKNOWLEDGEMENTS Development and testing of this software were made possible in part by grants from the FreeBSD Foundation and Cisco University Research Program Fund at Community Foundation Silicon Valley. .Sh HISTORY The .Nm congestion control module first appeared in .Fx 9.0 . .Pp The module was first released in 2010 by David Hayes whilst working on the NewTCP research project at Swinburne University of Technology's Centre for Advanced Internet Architectures, Melbourne, Australia. More details are available at: .Pp http://caia.swin.edu.au/urp/newtcp/ .Sh AUTHORS .An -nosplit The .Nm congestion control module and this manual page were written by .An David Hayes Aq david.hayes@ieee.org . Index: stable/9/share/man/man4/cy.4 =================================================================== --- stable/9/share/man/man4/cy.4 (revision 290885) +++ stable/9/share/man/man4/cy.4 (revision 290886) @@ -1,262 +1,261 @@ .\" Copyright (c) 1990, 1991 The Regents of the University of California. .\" All rights reserved. .\" .\" This code is derived from software contributed to Berkeley by .\" the Systems Programming Group of the University of Utah Computer .\" Science Department. .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" from: @(#)dca.4 5.2 (Berkeley) 3/27/91 .\" from: com.4,v 1.1 1993/08/06 11:19:07 cgd Exp .\" from: sio.4,v 1.16 1995/06/26 06:05:30 bde Exp $ .\" $FreeBSD$ .\" .Dd May 24, 2004 .Dt CY 4 .Os .Sh NAME .Nm cy .Nd Cyclades Cyclom-Y serial driver .Sh SYNOPSIS -.Pp For one ISA card: .Bd -ragged -offset indent -compact .Cd "device cy" .Pp In .Pa /boot/device.hints : .Cd hint.cy.0.at="isa" .Cd hint.cy.0.irq="10" .Cd hint.cy.0.maddr="0xd4000" .Cd hint.cy.0.msize="0x2000" .Ed .Pp For two ISA cards: .Bd -ragged -offset indent -compact .Cd "device cy" .Pp In .Pa /boot/device.hints : .Cd hint.cy.0.at="isa" .Cd hint.cy.0.irq="10" .Cd hint.cy.0.maddr="0xd4000" .Cd hint.cy.0.msize="0x2000" .Cd hint.cy.1.at="isa" .Cd hint.cy.1.irq="11" .Cd hint.cy.1.maddr="0xd6000" .Cd hint.cy.1.msize="0x2000" .Ed .Pp For PCI cards: .Bd -ragged -offset indent -compact .Cd "device cy" .Cd "options CY_PCI_FASTINTR" .Pp No lines are required in .Pa /boot/device.hints for PCI cards. .Ed .Pp Minor numbering: .Bd -literal -offset indent -compact 0b\fIMMMMMMMMMMMMMMMMxxxxxxxxOLIMMMMM\fR call\fBO\fRut \fBL\fRock \fBI\fRnitial \fBMMMMMMMMMMMMMMMM MMMMMM\fRinor .Ed .Sh DESCRIPTION The .Nm driver provides support for Cirrus Logic CD1400-based .Tn EIA .Tn RS-232C .Pf ( Tn CCITT .Tn V.24 ) communications interfaces (ports) on Cyclades Cyclom-Y boards. Each CD1400 provides 4 ports. Cyclom-Y boards with various numbers of CD1400's are available. This driver supports up to 8 CD1400's (32 ports) per board. .Pp Input and output for each line may set independently to the following speeds: 50, 75, 110, 134.5, 150, 300, 600, 1200, 1800, 2400, 4800, 9600, 19200, 38400, 57600, or 115200 bps. Other speeds of up to 150000 are supported by the termios interface but not by the sgttyb compatibility interface. The CD1400 is not fast enough to handle speeds above 115200 bps effectively. It can transmit on a single line at slightly more than 115200 bps, but when 4 lines are active in both directions its limit is about 90000 bps on each line. .\" XXX the following should be true for all serial drivers and .\" should not be repeated in the man pages for all serial drivers. .\" It was copied from sio.4. The only change was s/sio/cy/g. .Pp Serial ports controlled by the .Nm driver can be used for both `callin' and `callout'. For each port there is a callin device and a callout device. The minor number of the callout device is 128 higher than that of the corresponding callin port. The callin device is general purpose. Processes opening it normally wait for carrier and for the callout device to become inactive. The callout device is used to steal the port from processes waiting for carrier on the callin device. Processes opening it do not wait for carrier and put any processes waiting for carrier on the callin device into a deeper sleep so that they do not conflict with the callout session. The callout device is abused for handling programs that are supposed to work on general ports and need to open the port without waiting but are too stupid to do so. .Pp The .Nm driver also supports an initial-state and a lock-state control device for each of the callin and the callout "data" devices. The minor number of the initial-state device is 32 higher than that of the corresponding data device. The minor number of the lock-state device is 64 higher than that of the corresponding data device. The termios settings of a data device are copied from those of the corresponding initial-state device on first opens and are not inherited from previous opens. Use .Xr stty 1 in the normal way on the initial-state devices to program initial termios states suitable for your setup. .Pp The lock termios state acts as flags to disable changing the termios state. E.g., to lock a flag variable such as CRTSCTS, use .Em "stty crtscts" on the lock-state device. Speeds and special characters may be locked by setting the corresponding value in the lock-state device to any nonzero value. .Pp Correct programs talking to correctly wired external devices work with almost arbitrary initial states and almost no locking, but other setups may benefit from changing some of the default initial state and locking the state. In particular, the initial states for non (POSIX) standard flags should be set to suit the devices attached and may need to be locked to prevent buggy programs from changing them. E.g., CRTSCTS should be locked on for devices that support RTS/CTS handshaking at all times and off for devices that do not support it at all. CLOCAL should be locked on for devices that do not support carrier. HUPCL may be locked off if you do not want to hang up for some reason. In general, very bad things happen if something is locked to the wrong state, and things should not be locked for devices that support more than one setting. The CLOCAL flag on callin ports should be locked off for logins to avoid certain security holes, but this needs to be done by getty if the callin port is used for anything else. .Ss Kernel Configuration Options The .Em CY_PCI_FASTINTR option should be used to avoid suboptimal interrupt handling for PCI Cyclades boards. The PCI BIOS must be configured with the .Nm interrupt not shared with any other active device for this option to work. This option is not the default because it is currently harmful in certain cases where it does not work. .Sh FILES .\" XXX more cloning: s/d/c/g and add a ? for the card number. .Bl -tag -width /dev/ttyic?? -compact .It Pa /dev/ttyc?? for callin ports .It Pa /dev/ttyic?? .It Pa /dev/ttylc?? corresponding callin initial-state and lock-state devices .Pp .\" XXX more cloning: s/a/c/g. No consistency :-(. .It Pa /dev/cuac?? for callout ports .It Pa /dev/cuaic?? .It Pa /dev/cualc?? corresponding callout initial-state and lock-state devices .El .Pp .Bl -tag -width /etc/rc.serial -compact .It Pa /etc/rc.serial examples of setting the initial-state and lock-state devices .El .Pp The first question mark in these device names is short for the card number (a decimal number between 0 and 65535 inclusive). The second question mark is short for the port number (a letter in the range [0-9a-v]). .Sh DIAGNOSTICS .Bl -diag .\" XXX back to s/sio/cy/g. .It cy%d: silo overflow. Problem in the interrupt handler. .El .Bl -diag .It cy%d: interrupt-level buffer overflow. Problem in the bottom half of the driver. .El .Bl -diag .It cy%d: tty-level buffer overflow. Problem in the application. Input has arrived faster than the given module could process it and some has been lost. .El .\" .Bl -diag .\" .It sio%d: reduced fifo trigger level to %d. .\" Attempting to avoid further silo overflows. .\" .El .Sh SEE ALSO .Xr stty 1 , .Xr termios 4 , .Xr tty 4 , .Xr comcontrol 8 , .Xr pstat 8 .Sh HISTORY The .Nm driver is derived from the .Nm sio driver and the .Nx .Nm driver and is .Ud .Sh BUGS Serial consoles are not implemented. Index: stable/9/share/man/man4/dpms.4 =================================================================== --- stable/9/share/man/man4/dpms.4 (revision 290885) +++ stable/9/share/man/man4/dpms.4 (revision 290886) @@ -1,58 +1,57 @@ .\" Copyright (c) 2008 Yahoo!, Inc. .\" All rights reserved. .\" Written by: John Baldwin .\" .\" 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 author nor the names of any co-contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd August 23, 2008 .Dt DPMS 4 .Os .Sh NAME .Nm dpms .Nd VESA BIOS DPMS driver .Sh SYNOPSIS .Cd "device dpms" .Sh DESCRIPTION The .Nm driver uses the VESA BIOS to manage an external display during suspend and resume. When the machine suspends, the .Nm driver turns the external display off. When the machine resumes, it restores the display to its state when the driver was first loaded. .Sh SEE ALSO .Xr acpi_video 4 .Sh BUGS -.Pp The VESA BIOS DPMS calls do not provide any way to identify a particular display or adapter to manipulate. As a result, this driver may have unexpected results on systems with multiple displays and/or adapters. Index: stable/9/share/man/man4/ed.4 =================================================================== --- stable/9/share/man/man4/ed.4 (revision 290885) +++ stable/9/share/man/man4/ed.4 (revision 290886) @@ -1,445 +1,444 @@ .\" .\" Copyright (c) 1994, David Greenman .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by David Greenman. .\" 4. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 25, 2012 .Dt ED 4 .Os .Sh NAME .Nm ed .Nd "NE-2000 and WD-80x3 Ethernet driver" .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device miibus" .Cd "device ed" .Ed .Pp Alternatively, to load the driver as a module at boot time, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent if_ed_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for 8 and 16bit Ethernet cards that are based on the National Semiconductor DS8390 and similar NICs manufactured by other companies. The .Nm driver also supports many PC Card chips which interface via MII to a PHY. Axiom's AX88790, AX88190 and AX88190A; DLink's DL10019 and DL10022; and Tamarack's TC5299J chips all support internal or external MII/PHY combinations. Realtek's PCI and ISA RTL80x9-based cards are also supported. For these chipsets, autonegotiation and status reporting are supported. .Pp In addition to the standard port and IRQ specifications, the .Nm driver also supports a number of .Cd flags which can force 8/16bit mode, enable/disable multi-buffering, and select the default interface type (AUI/BNC, and for cards with twisted pair, AUI/10BaseT). .Pp The .Cd flags are a bit field, and are summarized as follows: .Bl -tag -width indent .It Li 0x01 Disable transceiver. On those cards which support it, this flag causes the transceiver to be disabled and the AUI connection to be used by default. .It Li 0x02 Force 8bit mode. This flag forces the card to 8bit mode regardless of how the card identifies itself. This may be needed for some clones which incorrectly identify themselves as 16bit, even though they only have an 8bit interface. This flag takes precedence over force 16bit mode. .It Li 0x04 Force 16bit mode. This flag forces the card to 16bit mode regardless of how the card identifies itself. This may be needed for some clones which incorrectly identify themselves as 8bit, even though they have a 16bit ISA interface. .It Li 0x08 Disable transmitter multi-buffering. This flag disables the use of multiple transmit buffers and may be necessary in rare cases where packets are sent out faster than a machine on the other end can handle (as evidenced by severe packet lossage). Some .No ( non- Ns Fx :-)) machines have terrible Ethernet performance and simply cannot cope with 1100K+ data rates. Use of this flag also provides one more packet worth of receiver buffering, and on 8bit cards, this may help reduce receiver lossage. .El .Pp When using a 3c503 card, the AUI connection may be selected by specifying the .Cm link2 option to .Xr ifconfig 8 (BNC is the default). .Sh HARDWARE The .Nm driver supports the following Ethernet NICs: .Pp .Bl -bullet -compact .It 3Com 3c503 Etherlink II .Pq Cd "options ED_3C503" .It AR-P500 Ethernet .It Accton EN1644 (old model), EN1646 (old model), EN2203 (old model) (110pin) (flags 0xd00000) .It Accton EN2212/EN2216/UE2216 .It Allied Telesis CentreCOM LA100-PCM_V2 .It Allied Telesis LA-98 (flags 0x000000) (PC-98) .It Allied Telesis SIC-98, SIC-98NOTE (110pin), SIU-98 (flags 0x600000) (PC-98) .It Allied Telesis SIU-98-D (flags 0x610000) (PC-98) .It AmbiCom 10BaseT card .It Bay Networks NETGEAR FA410TXC Fast Ethernet .It Belkin F5D5020 PC Card Fast Ethernet .It Billionton LM5LT-10B Ethernet/Modem PC Card .It Bromax iPort 10/100 Ethernet PC Card .It Bromax iPort 10 Ethernet PC Card .It Buffalo LPC2-CLT, LPC3-CLT, LPC3-CLX, LPC4-TX PC Card .It CNet BC40 adapter .It Compex Net-A adapter .It Compex RL2000 .It Contec C-NET(98), RT-1007(98), C-NET(9N) (110pin) (flags 0xa00000) (PC-98) .It Contec C-NET(98)E-A, C-NET(98)L-A, C-NET(98)P (flags 0x300000) (PC-98) .It Corega Ether98-T (flags 0x000000) (PC-98) .It Corega Ether PCC-T/EtherII PCC-T/FEther PCC-TXF/PCC-TXD PCC-T/Fether II TXD .It Corega LAPCCTXD (TC5299J) .It CyQ've ELA-010 .It DEC EtherWorks DE305 .It Danpex EN-6200P2 .It D-Link DE-298, DE-298P (flags 0x500000) (PC-98) .It D-Link DE-660, DE-660+ .It D-Link IC-CARD/IC-CARD+ Ethernet .It ELECOM LD-98P (flags 0x500000) (PC-98) .It ELECOM LD-BDN, LD-NW801G (flags 0x200000) (PC-98) .It ELECOM Laneed LD-CDL/TX, LD-CDF, LD-CDS, LD-10/100CD, LD-CDWA (DP83902A) .It Hawking PN652TX PC Card (AX88790) .It HP PC Lan+ 27247B and 27252A .Pq Cd "options ED_HPP" .It IBM Creditcard Ethernet I/II .It ICM AD-ET2-T, DT-ET-25, DT-ET-T5, IF-2766ET, IF-2771ET, NB-ET-T (110pin) (flags 0x500000) (PC-98) .It I-O DATA LA/T-98, LA/T-98SB, LA2/T-98, ET/T-98 (flags 0x900000) (PC-98) .It I-O DATA ET2/T-PCI .It I-O DATA PCLATE .It Kansai KLA-98C/T (flags 0x900000) (PC-98) .It Kingston KNE-PC2, CIO10T, KNE-PCM/x Ethernet .It KTI ET32P2 PCI .It Linksys EC2T/PCMPC100/PCM100, PCMLM56 .It Linksys EtherFast 10/100 PC Card, Combo PCMCIA Ethernet Card (PCMPC100 V2) .It Logitec LAN-98T (flags 0xb00000) (PC-98) .It MACNICA Ethernet ME1 for JEIDA .It MACNICA ME98 (flags 0x900000) (PC-98) .It MACNICA NE2098 (flags 0x400000) (PC-98) .It MELCO EGY-98 (flags 0x300000) (PC-98) .It MELCO LGH-98, LGY-98, LGY-98-N (110pin), IND-SP, IND-SS (flags 0x400000) (PC-98) .It MELCO LGY-PCI-TR .It MELCO LPC-T/LPC2-T/LPC2-CLT/LPC2-TX/LPC3-TX/LPC3-CLX .It NDC Ethernet Instant-Link .It NEC PC-9801-77, PC-9801-78 (flags 0x910000) (PC-98) .It NEC PC-9801-107, PC-9801-108 (flags 0x800000) (PC-98) .It National Semiconductor InfoMover NE4100 .It NetGear FA-410TX .It NetVin NV5000SC .It Network Everywhere Ethernet 10BaseT PC Card .It Networld 98X3 (flags 0xd00000) (PC-98) .It Networld EC-98X, EP-98X (flags 0xd10000) (PC-98) .It New Media LANSurfer 10+56 Ethernet/Modem .It New Media LANSurfer .It Novell NE1000/NE2000/NE2100 .It PLANEX ENW-8300-T .It PLANEX EN-2298-C (flags 0x200000) (PC-98) .It PLANEX EN-2298P-T, EN-2298-T (flags 0x500000) (PC-98) .It PLANEX FNW-3600-T .It Psion 10/100 LANGLOBAL Combine iT .It RealTek 8019 .It RealTek 8029 .It Relia Combo-L/M-56k PC Card .It SMC Elite 16 WD8013 .It SMC Elite Ultra .It SMC EtherEZ98 (flags 0x000000) (PC-98) .It SMC WD8003E/WD8003EBT/WD8003S/WD8003SBT/WD8003W/WD8013EBT/WD8013W and clones .It SMC EZCard PC Card, 8040-TX, 8041-TX (AX88x90), 8041-TX V.2 (TC5299J) .It Socket LP-E, ES-1000 Ethernet/Serial, LP-E CF, LP-FE CF .It Surecom EtherPerfect EP-427 .It Surecom NE-34 .It TDK 3000/3400/5670 Fast Ethernet/Modem .It TDK LAK-CD031, Grey Cell GCS2000 Ethernet Card .It TDK DFL5610WS Ethernet/Modem PC Card .It Telecom Device SuperSocket RE450T .It Toshiba LANCT00A PC Card .It VIA VT86C926 .It Winbond W89C940 .It Winbond W89C940F .El .Pp C-Bus, ISA, PCI and PC Card devices are supported. .Pp The .Nm driver does not support the following Ethernet NICs: .Pp .Bl -bullet -compact .It Mitsubishi LAN Adapter B8895 .El .Sh DIAGNOSTICS .Bl -diag .It "ed%d: failed to clear shared memory at %x - check configuration." When the card was probed at system boot time, the .Nm driver found that it could not clear the card's shared memory. This is most commonly caused by a BIOS extension ROM being configured in the same address space as the Ethernet card's shared memory. Either find the offending card and change its BIOS ROM to be at an address that does not conflict, or change the settings in .Xr device.hints 5 that the card's shared memory is mapped at a non-conflicting address. .It "ed%d: Invalid irq configuration (%d) must be 2-5 for 3c503." The IRQ number that was specified in the .Xr device.hints 5 file is not valid for the 3Com 3c503 card. The 3c503 can only be assigned to IRQs 2 through 5. .It "ed%d: Cannot find start of RAM." .It "ed%d: Cannot find any RAM, start : %d, x = %d." The probe of a Gateway card was unsuccessful in configuring the card's packet memory. This likely indicates that the card was improperly recognized as a Gateway or that the card is defective. .It "ed: packets buffered, but transmitter idle." Indicates a logic problem in the driver. Should never happen. .It "ed%d: device timeout" Indicates that an expected transmitter interrupt did not occur. Usually caused by an interrupt conflict with another card on the ISA bus. This condition could also be caused if the kernel is configured for a different IRQ channel than the one the card is actually using. If that is the case, you will have to either reconfigure the card using a DOS utility or set the jumpers on the card appropriately. .It "ed%d: NIC memory corrupt - invalid packet length %d." Indicates that a packet was received with a packet length that was either larger than the maximum size or smaller than the minimum size allowed by the IEEE 802.3 standard. Usually caused by a conflict with another card on the ISA bus, but in some cases may also indicate faulty cabling. .It "ed%d: remote transmit DMA failed to complete." This indicates that a programmed I/O transfer to an NE1000 or NE2000 style card has failed to properly complete. Usually caused by the ISA bus speed being set too fast. .It "ed%d: Invalid irq configuration (%ld) must be %s for %s" Indicates the device has a different IRQ than supported or expected. .It "ed%d: Cannot locate my ports!" The device is using a different I/O port than the driver knows about. .It "ed%d: Cannot extract MAC address" Attempts to get the MAC address failed. .It "ed%d: Missing mii!" Probing for an MII bus has failed. This indicates a coding error in the PC Card attachment, because a PHY is required for the chips that generate this error message. .El .Sh SEE ALSO .Xr altq 4 , .Xr arp 4 , .Xr miibus 4 , .Xr netintro 4 , .Xr ng_ether 4 , .Xr device.hints 5 , .Xr ifconfig 8 .Sh HISTORY The .Nm device driver first appeared in .Fx 1.0 . .Sh AUTHORS The .Nm device driver and this manual page were written by .An David Greenman . .Sh CAVEATS Early revision DS8390 chips have problems. They lock up whenever the receive ring-buffer overflows. They occasionally switch the byte order of the length field in the packet ring header (several different causes of this related to an off-by-one byte alignment) - resulting in .Qq Li "NIC memory corrupt - invalid packet length" messages. The card is reset whenever these problems occur, but otherwise there is no problem with recovering from these conditions. .Pp The NIC memory access to 3Com and Novell cards is much slower than it is on WD/SMC cards; it is less than 1MB/second on 8bit boards and less than 2MB/second on the 16bit cards. This can lead to ring-buffer overruns resulting in dropped packets during heavy network traffic. .Pp The Mitsubishi B8895 PC Card uses a DP83902, but its ASIC part is undocumented. Neither the NE2000 nor the WD83x0 drivers work with this card. -.Pp .Sh BUGS The .Nm driver is a bit too aggressive about resetting the card whenever any bad packets are received. As a result, it may throw out some good packets which have been received but not yet transferred from the card to main memory. .Pp The .Nm driver is slow by today's standards. .Pp PC Card attachment supports the D-Link DMF650TX LAN/Modem card's Ethernet port only at this time. .Pp Some devices supported by .Nm do not generate the link state change events used by .Xr devd 8 to start .Xr dhclient 8 . If you have problems with .Xr dhclient 8 not starting and the device is always attached to the network it may be possible to work around this by changing .Dq Li DHCP to .Dq Li SYNCDHCP in the .Va ifconfig_ed0 entry in .Pa /etc/rc.conf . Index: stable/9/share/man/man4/em.4 =================================================================== --- stable/9/share/man/man4/em.4 (revision 290885) +++ stable/9/share/man/man4/em.4 (revision 290886) @@ -1,288 +1,287 @@ .\" Copyright (c) 2001-2003, Intel Corporation .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions are met: .\" .\" 1. Redistributions of source code must retain the above copyright notice, .\" this list of conditions and the following disclaimer. .\" .\" 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 Intel Corporation nor the names of its .\" contributors may be used to endorse or promote products derived from .\" this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" .\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER 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. .\" .\" * Other names and brands may be claimed as the property of others. .\" .\" $FreeBSD$ .\" .Dd May 14, 2010 .Dt EM 4 .Os .Sh NAME .Nm em .Nd "Intel(R) PRO/1000 Gigabit Ethernet adapter 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 em" .Ed .Pp Alternatively, to load the driver as a module at boot time, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent if_em_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for PCI Gigabit Ethernet adapters based on the Intel 82540, 82541ER, 82541PI, 82542, 82543, 82544, 82545, 82546, 82546EB, 82546GB, 82547, 82571, 81572, 82573, and 82574 Ethernet controller chips. The driver supports Transmit/Receive checksum offload and Jumbo Frames on all but 82542-based adapters. Furthermore it supports TCP segmentation offload (TSO) on all adapters but those based on the 82543, 82544 and 82547 controller chips. The identification LEDs of the adapters supported by the .Nm driver can be controlled via the .Xr led 4 API for localization purposes. For further hardware information, see the .Pa README included with the driver. .Pp For questions related to hardware requirements, refer to the documentation supplied with your Intel PRO/1000 adapter. All hardware requirements listed apply to use with .Fx . .Pp Support for Jumbo Frames is provided via the interface MTU setting. Selecting an MTU larger than 1500 bytes with the .Xr ifconfig 8 utility configures the adapter to receive and transmit Jumbo Frames. The maximum MTU size for Jumbo Frames is 16114. .Pp This driver version supports VLANs. The .Nm driver supports the following media types: .Bl -tag -width ".Cm 10baseT/UTP" .It Cm autoselect Enables auto-negotiation for speed and duplex. .It Cm 10baseT/UTP Sets 10Mbps operation. Use the .Cm mediaopt option to select .Cm full-duplex mode. .It Cm 100baseTX Sets 100Mbps operation. Use the .Cm mediaopt option to select .Cm full-duplex mode. .It Cm 1000baseSX Sets 1000Mbps operation. Only .Cm full-duplex mode is supported at this speed. .It Cm 1000baseTX Sets 1000Mbps operation. Only .Cm full-duplex mode is supported at this speed. .El .Pp The .Nm driver supports the following media options: .Bl -tag -width ".Cm full-duplex" .It Cm full-duplex Forces full-duplex operation .It Cm half-duplex Forces half-duplex operation. .El .Pp Only use .Cm mediaopt to set the driver to .Cm full-duplex . If .Cm mediaopt is not specified, the driver defaults to .Cm half-duplex . .Pp For more information on configuring this device, see .Xr ifconfig 8 . .Sh HARDWARE The .Nm driver supports Gigabit Ethernet adapters based on the Intel 82540, 82541ER, 82541PI, 82542, 82543, 82544, 82545, 82546, 82546EB, 82546GB, 82547, 82571, 82572, 82573, and 82574 controller chips: .Pp .Bl -bullet -compact .It Intel PRO/1000 CT Network Connection (82547) .It Intel PRO/1000 F Server Adapter (82543) .It Intel PRO/1000 Gigabit Server Adapter (82542) .It Intel PRO/1000 GT Desktop Adapter (82541PI) .It Intel PRO/1000 MF Dual Port Server Adapter (82546) .It Intel PRO/1000 MF Server Adapter (82545) .It Intel PRO/1000 MF Server Adapter (LX) (82545) .It Intel PRO/1000 MT Desktop Adapter (82540) .It Intel PRO/1000 MT Desktop Adapter (82541) .It Intel PRO/1000 MT Dual Port Server Adapter (82546) .It Intel PRO/1000 MT Quad Port Server Adapter (82546EB) .It Intel PRO/1000 MT Server Adapter (82545) .It Intel PRO/1000 PF Dual Port Server Adapter (82571) .It Intel PRO/1000 PF Quad Port Server Adapter (82571) .It Intel PRO/1000 PF Server Adapter (82572) .It Intel PRO/1000 PT Desktop Adapter (82572) .It Intel PRO/1000 PT Dual Port Server Adapter (82571) .It Intel PRO/1000 PT Quad Port Server Adapter (82571) .It Intel PRO/1000 PT Server Adapter (82572) .It Intel PRO/1000 T Desktop Adapter (82544) .It Intel PRO/1000 T Server Adapter (82543) .It Intel PRO/1000 XF Server Adapter (82544) .It Intel PRO/1000 XT Server Adapter (82544) .El .Sh LOADER TUNABLES Tunables can be set at the .Xr loader 8 prompt before booting the kernel or stored in .Xr loader.conf 5 . .Bl -tag -width indent .It Va hw.em.rxd Number of receive descriptors allocated by the driver. The default value is 256. The 82542 and 82543-based adapters can handle up to 256 descriptors, while others can have up to 4096. .It Va hw.em.txd Number of transmit descriptors allocated by the driver. The default value is 256. The 82542 and 82543-based adapters can handle up to 256 descriptors, while others can have up to 4096. .It Va hw.em.rx_int_delay This value delays the generation of receive interrupts in units of 1.024 microseconds. The default value is 0, since adapters may hang with this feature being enabled. .It Va hw.em.rx_abs_int_delay If .Va hw.em.rx_int_delay is non-zero, this tunable limits the maximum delay in which a receive interrupt is generated. .It Va hw.em.tx_int_delay This value delays the generation of transmit interrupts in units of 1.024 microseconds. The default value is 64. .It Va hw.em.tx_abs_int_delay If .Va hw.em.tx_int_delay is non-zero, this tunable limits the maximum delay in which a transmit interrupt is generated. .El .Sh FILES .Bl -tag -width /dev/led/em* .It Pa /dev/led/em* identification LED device nodes .El .Sh EXAMPLES Make the identification LED of em0 blink: .Pp .Dl "echo f2 > /dev/led/em0" .Pp Turn the identification LED of em0 off again: .Pp .Dl "echo 0 > /dev/led/em0" -.Pp .Sh DIAGNOSTICS .Bl -diag .It "em%d: Unable to allocate bus resource: memory" A fatal initialization error has occurred. .It "em%d: Unable to allocate bus resource: interrupt" A fatal initialization error has occurred. .It "em%d: watchdog timeout -- resetting" The device has stopped responding to the network, or there is a problem with the network connection (cable). .El .Sh SUPPORT For general information and support, go to the Intel support website at: .Pa http://support.intel.com . .Pp If an issue is identified with the released source code on the supported kernel with a supported adapter, email the specific information related to the issue to .Aq freebsdnic@mailbox.intel.com . .Sh SEE ALSO .Xr altq 4 , .Xr arp 4 , .Xr igb 4 , .Xr led 4 , .Xr netintro 4 , .Xr ng_ether 4 , .Xr polling 4 , .Xr vlan 4 , .Xr ifconfig 8 .Sh HISTORY The .Nm device driver first appeared in .Fx 4.4 . .Sh AUTHORS The .Nm driver was written by .An Intel Corporation Aq freebsdnic@mailbox.intel.com . .Sh BUGS Hardware-assisted VLAN processing is disabled by default. You can enable it on an .Nm interface using .Xr ifconfig 8 . Index: stable/9/share/man/man4/epair.4 =================================================================== --- stable/9/share/man/man4/epair.4 (revision 290885) +++ stable/9/share/man/man4/epair.4 (revision 290886) @@ -1,120 +1,119 @@ .\"- .\" Copyright (c) 2008 The FreeBSD Foundation .\" All rights reserved. .\" .\" This software was developed by CK Software GmbH under sponsorship .\" from the FreeBSD Foundation. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd July 26, 2009 .Dt EPAIR 4 .Os .Sh NAME .Nm epair .Nd A pair of virtual back-to-back connected Ethernet interfaces .Sh SYNOPSIS To compile this driver into the kernel, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "device epair" .Ed .Pp Alternatively, to load the driver as a module at boot time, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent if_epair_load="YES" .Ed .Sh DESCRIPTION The .Nm is a pair of Ethernet-like software interfaces, which are connected back-to-back with a virtual cross-over cable. .Pp Each .Nm interface pair is created at runtime using interface cloning. This is most easily done with the .Xr ifconfig 8 .Cm create command or using the .Va cloned_interfaces variable in .Xr rc.conf 5 . While for cloning you only give either .Pa epair or .Pa epair the .Nm pair will be named like .Pa epair[ab] . This means the names of the first .Nm interfaces will be .Pa epair0a and .Pa epair0b . .Pp Like any other Ethernet interface, an .Nm needs to have a network address. Each .Nm will be assigned a locally administered address by default, that is only guaranteed to be unique within one network stack. To change the default addresses one may use the SIOCSIFADDR ioctl(2) or ifconfig(8) utility. .Pp The basic intend is to provide connectivity between two virtual network stack instances. When connected to a .Xr if_bridge 4 one end of the interface pair can also be part of another (virtual) LAN. As with any other Ethernet interface one can configure .Xr vlan 4 support on top of it. -.Pp .Sh SEE ALSO .Xr ioctl 2 , .Xr altq 4 , .Xr bpf 4 , .Xr if_bridge 4 , .Xr vlan 4 , .Xr loader.conf 5 , .Xr rc.conf 5 , .Xr ifconfig 8 .Sh HISTORY The .Nm interface first appeared in .Fx 8.0 . .Sh AUTHORS The .Nm interface was written by .An Bjoern A. Zeeb, CK Software GmbH, under sponsorship from the FreeBSD Foundation. Index: stable/9/share/man/man4/fdc.4 =================================================================== --- stable/9/share/man/man4/fdc.4 (revision 290885) +++ stable/9/share/man/man4/fdc.4 (revision 290886) @@ -1,344 +1,343 @@ .\" .\" Copyright (c) 1994 Wilko Bulte .\" Copyright (c) 2001 Joerg Wunsch .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd May 11, 2006 .Dt FDC 4 .Os .Sh NAME .Nm fdc .Nd "PC architecture floppy disk controller driver" .Sh SYNOPSIS .Cd device fdc .Pp In .Pa /boot/device.hints : .Cd hint.fdc.0.at="isa" .Cd hint.fdc.0.port="0x3F0" .Cd hint.fdc.0.irq="6" .Cd hint.fdc.0.drq="2" .Cd hint.fdc.0.flags="0x0" .Cd hint.fd.0.at="fdc0" .Cd hint.fd.0.drive="0" .Cd hint.fd.0.flags="0x0" .Cd hint.fd.1.at="fdc0" .Cd hint.fd.1.drive="1" .Cd hint.fd.1.flags="0x0" .Sh DESCRIPTION .Ss Device Usage This driver provides access to floppy disk drives. Floppy disks using either FM (single-density) or MFM (double or high-density) recording can be handled. .Pp Floppy disk controllers can connect up to four drives each. The .Nm driver can currently handle up to two drives per controller (or four drives on ACPI). Upon driver initialization, an attempt is made to find out the type of the floppy controller in use. The known controller types are either the original NE765 or i8272 chips, or alternatively .Em enhanced controllers that are compatible with the NE72065 or i82077 chips. These enhanced controllers (among other enhancements) implement a FIFO for floppy data transfers that will automatically be enabled once an enhanced chip has been detected. This FIFO activation can be disabled using the per-controller flags value of .Ar 0x1 . .Pp By default, this driver creates a single device node .Pa /dev/fd Ns Ar N for each attached drive with number .Ar N . For historical reasons, device nodes that use a trailing UFS-style partition letter (ranging from .Sq a through .Sq h ) can also be accessed, which will be implemented as symbolic links to the main device node. .Pp Accessing the main device node will attempt to autodetect the density of the available medium for multi-density devices. Thus it is possible to use either a 720 KB medium or a 1440 KB medium in a high-density 3.5 inch standard floppy drive. Normally, this autodetection will only happen once at the first call to .Xr open 2 for the device after inserting the medium. This assumes the drive offers proper changeline support so media changes can be detected by the driver. To indicate a drive that does not have the changeline support, this can be overridden using the per-drive device flags value of .Ar 0x10 (causing each call to .Xr open 2 to perform the autodetection). .Pp When trying to use a floppy device with special-density media, other device nodes can be created, of the form .Pa /dev/fd Ns Ar N . Ns Ar MMMM , where .Ar N is the drive number, and .Ar MMMM is a number between one and four digits describing the device density. Up to 15 additional subdevices per drive can be created that way. The administrator is free to decide on a policy how to assign these numbers. The two common policies are to either implement subdevices numbered 1 through 15, or to use a number that describes the medium density in kilobytes. Initially, each of those devices will be configured to the maximal density that is possible for the drive type (like 1200 KB for 5.25 inch HD drives or 1440 KB for 3.5 inch HD drives). The desired density to be used on that subdevice needs to be configured using .Xr fdcontrol 8 . .Pp Drive types are configured using the lower four bits of the per-drive device flags. The following values can be specified: .Bl -tag -width 2n -offset indent .It Ar 1 5.25 inch double-density device with 40 cylinders (360 KB native capacity) .It Ar 2 5.25 inch high-density device with 80 cylinders (1200 KB native capacity) .It Ar 3 3.5 inch double-density device with 80 cylinders (720 KB native capacity) .It Ar 4 3.5 inch high-density device with 80 cylinders (1440 KB native capacity) .It Ar 5 3.5 inch extra-density device with 80 cylinders (2880 KB native capacity, usage currently restricted to at most 1440 KB media) .It Ar 6 Same as type 5, available for compatibility with some BIOSes .El .Pp On IA32 architectures, the drive type can be specified as 0 for the drives. In that case, the CMOS configuration memory will be consulted to obtain the value for that drive. The ACPI probe automatically determines these values via the _FDE and _FDI methods, but this can be overridden by specifying a drive type hint. .Pp Normally, each configured drive will be probed at initialization time, using a short seek sequence. This is intended to find out about drives that have been configured but are actually missing or otherwise not responding. (The ACPI probe method does not perform this seek.) In some environments (like laptops with detachable drives), it might be desirable to bypass this drive probe, and pretend a drive to be there so the driver autoconfiguration will work even if the drive is currently not present. For that purpose, a per-drive device flags value of .Ar 0x20 needs to be specified. -.Pp .Ss Programming Interface In addition to the normal read and write functionality, the .Nm driver offers a number of configurable options using .Xr ioctl 2 . In order to access any of this functionality, programmers need to include the header file .In sys/fdcio.h into their programs. The call to .Xr open 2 can be performed in two possible ways. When opening the device without the .Dv O_NONBLOCK flag set, the device is opened in a normal way, which would cause the main device nodes to perform automatic media density selection, and which will yield a file descriptor that is fully available for any I/O operation or any of the following .Xr ioctl 2 commands. .Pp When opening the device with .Dv O_NONBLOCK set, automatic media density selection will be bypassed, and the device remains in a half-opened state. No actual I/O operations are possible, but many of the .Xr ioctl 2 commands described below can be performed. This mode is intended for access to the device without the requirement to have an accessible media present, like for status inquiries to the drive, or in order to format a medium. .Dv O_NONBLOCK needs to be cleared before I/O operations are possible on the descriptor, which requires a prior specification of the density using the .Dv FD_STYPE command (see below). Operations that are not allowed on the half-opened descriptor will cause an error value of .Er EAGAIN . .Pp The following .Xr ioctl 2 commands are currently available: .Bl -tag -width ".Dv FD_READID" .It Dv FD_FORM Used to format a floppy disk medium. Third argument is a pointer to a .Vt "struct fd_formb" specifying which track to format, and which parameters to fill into the ID fields of the floppy disk medium. .It Dv FD_GTYPE Returns the current density definition record for the selected device. Third argument is a pointer to .Vt "struct fd_type" . .It Dv FD_STYPE Adjusts the density definition of the selected device. Third argument is a pointer to .Vt "struct fd_type" . For the fixed-density subdevices (1 through 15 per drive), this operation is restricted to a process with superuser privileges. For the auto-selecting subdevice 0, the operation is temporarily allowed to any process, but this setting will be lost again upon the next autoselection. This can be used when formatting a new medium (which will require to open the device using .Dv O_NONBLOCK , and thus to later adjust the density using .Dv FD_STYPE ) . .It Dv FD_GOPTS Obtain the current drive options. Third argument is a pointer to .Vt int , containing a bitwise union of the following possible flag values: .Bl -tag -width ".Dv FDOPT_NOERRLOG" .It Dv FDOPT_NORETRY Do not automatically retry operations upon failure. .It Dv FDOPT_NOERRLOG Do not cause .Dq "hard error" kernel logs for failed I/O operations. .It Dv FDOPT_NOERROR Do not indicate I/O errors when returning from .Xr read 2 or .Xr write 2 system calls. The caller is assumed to use .Dv FD_GSTAT calls in order to inquire about the success of each operation. This is intended to allow even erroneous data from bad blocks to be retrieved using normal I/O operations. .It Dv FDOPT_AUTOSEL Device performs automatic density selection. Unlike the above flags, this one is read-only. .El .It Dv FD_SOPTS Set device options, see above for their meaning. Third argument is a pointer to .Vt int . Drive options will always be cleared when closing the descriptor. .It Dv FD_DEBUG Set the driver debug level. Third argument is a pointer to .Vt int , level 0 turns off all debugging. Only applicable if the driver has been configured with .Cd "options FDC_DEBUG" . .It Dv FD_CLRERR Clear the internal low-level error counter. Normally, controller-level I/O errors are only logged up to .Dv FDC_ERRMAX errors (currently defined to 100). This command resets the counter. Requires superuser privileges. .It Dv FD_READID Read one sector ID field from the floppy disk medium. Third argument is a pointer to .Vt "struct fdc_readid" , where the read data will be returned. Can be used to analyze a floppy disk medium. .It Dv FD_GSTAT Return the recent floppy disk controller status, if available. Third argument is a pointer to .Vt "struct fdc_status" , where the status registers (ST0, ST1, ST2, C, H, R, and N) are being returned. .Er EINVAL will be caused if no recent status is available. .It Dv FD_GDTYPE Returns the floppy disk drive type. Third argument is a pointer to .Vt "enum fd_drivetype" . This type is the same as being used in the per-drive configuration flags, or in the CMOS configuration data or ACPI namespace on IA32 systems. .El .Sh FILES .Bl -tag -width ".Pa /dev/fd*" -compact .It Pa /dev/fd* floppy disk device nodes .El .Sh SEE ALSO .Xr fdformat 1 , .Xr fdread 1 , .Xr fdwrite 1 , .Xr ioctl 2 , .Xr open 2 , .Xr read 2 , .Xr write 2 , .Xr fdcontrol 8 .Sh AUTHORS .An -nosplit This man page was initially written by .An Wilko Bulte , and later vastly rewritten by .An J\(:org Wunsch . Index: stable/9/share/man/man4/fwohci.4 =================================================================== --- stable/9/share/man/man4/fwohci.4 (revision 290885) +++ stable/9/share/man/man4/fwohci.4 (revision 290886) @@ -1,159 +1,158 @@ .\" Copyright (c) 1998,1999,2000 Katsushi Kobayashi and Hidetoshi Shimokawa .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the acknowledgement as bellow: .\" .\" This product includes software developed by K. Kobayashi and H. Shimokawa .\" .\" 4. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE .\" DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN .\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .\" .Dd March 3, 2008 .Dt FWOHCI 4 .Os .Sh NAME .Nm fwohci .Nd OHCI FireWire chipset device driver .Sh SYNOPSIS To compile this driver into the kernel, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "device firewire" .Ed .Pp Alternatively, to load the driver as a module at boot time, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent firewire_load="YES" .Ed .Pp To disable physical access (see .Sx BUGS section for detail), put the following line in .Xr loader.conf 5 : .Bd -literal -offset indent hw.firewire.phydma_enable=0 .Ed -.Pp .Sh HARDWARE The .Nm driver provides support for PCI/CardBus FireWire interface cards. The driver supports the following IEEE 1394 OHCI chipsets: .Pp .Bl -bullet -compact .It Adaptec AHA-894x/AIC-5800 .It Apple Pangea .It Apple UniNorth .It Intel 82372FB .It IOGEAR GUF320 .It Lucent / Agere FW322/323 .It NEC uPD72861 .It NEC uPD72870 .It NEC uPD72871/2 .It NEC uPD72873 .It NEC uPD72874 .It National Semiconductor CS4210 .It Ricoh R5C551 .It Ricoh R5C552 .It Sony CX3022 .It Sony i.LINK (CXD3222) .It Sun PCIO-2 (RIO 1394) .It Texas Instruments PCI4410A .It Texas Instruments PCI4450 .It Texas Instruments PCI4451 .It Texas Instruments TSB12LV22 .It Texas Instruments TSB12LV23 .It Texas Instruments TSB12LV26 .It Texas Instruments TSB43AA22 .It Texas Instruments TSB43AB21/A/AI/A-EP .It Texas Instruments TSB43AB22/A .It Texas Instruments TSB43AB23 .It Texas Instruments TSB82AA2 .It VIA Fire II (VT6306) .El .Sh SEE ALSO .Xr firewire 4 , .Xr fwe 4 , .Xr fwip 4 , .Xr sbp 4 , .Xr fwcontrol 8 , .Xr kldload 8 .Sh HISTORY The .Nm device driver first appeared in .Fx 5.0 . .Sh AUTHORS .An -nosplit The .Nm device driver was written by .An Katsushi Kobayashi and .An Hidetoshi Shimokawa . .Sh BUGS The driver allows physical access from any nodes on the bus by default. This means that any devices on the bus can read and modify any memory space which can be accessed by an IEEE 1394 OHCI chip. It is allowed mostly for .Xr sbp 4 devices. This should be changed to allow it only for specific devices. Anyway, FireWire is a bus and not expected to be connected with un-trustable devices because a node can monitor all the traffic. Index: stable/9/share/man/man4/gem.4 =================================================================== --- stable/9/share/man/man4/gem.4 (revision 290885) +++ stable/9/share/man/man4/gem.4 (revision 290886) @@ -1,149 +1,148 @@ .\" $NetBSD: gem.4,v 1.2 2003/02/14 15:20:18 grant Exp $ .\" .\" Copyright (c) 2002 The NetBSD Foundation, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd December 25, 2009 .Dt GEM 4 .Os .Sh NAME .Nm gem .Nd ERI/GEM/GMAC Ethernet 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 miibus" .Cd "device gem" .Ed .Pp Alternatively, to load the driver as a module at boot time, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent if_gem_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for the GMAC Ethernet hardware found mostly in the last Apple PowerBooks G3s and most G4-based Apple hardware, as well as Sun UltraSPARC machines. .Pp All controllers supported by the .Nm driver have TCP checksum offload capability for both receive and transmit, support for the reception and transmission of extended frames for .Xr vlan 4 and a 512-bit multicast hash filter. .Sh HARDWARE -.Pp Chips supported by the .Nm driver include: .Pp .Bl -bullet -compact .It Apple GMAC .It Sun ERI 10/100 Mbps Ethernet .It Sun GEM Gigabit Ethernet .El .Pp The following add-on cards are known to work with the .Nm driver at this time: .Pp .Bl -bullet -compact .It Sun Gigabit Ethernet PCI 2.0/3.0 (GBE/P) (part no.\& 501-4373) .It Sun Gigabit Ethernet SBus 2.0/3.0 (GBE/S) (part no.\& 501-4375) .El .Sh NOTES On sparc64 the .Nm driver respects the .Va local-mac-address? system configuration variable which can be set in the Open Firmware boot monitor using the .Ic setenv command or by .Xr eeprom 8 . If set to .Dq Li false (the default), the .Nm driver will use the system's default MAC address for all of its devices. If set to .Dq Li true , the unique MAC address of each interface is used if present rather than the system's default MAC address. .Pp Supported interfaces having their own MAC address include the on-board Sun ERI 10/100 Mbps on boards equipped with more than one Ethernet interface and the Sun Gigabit Ethernet 2.0/3.0 GBE add-on cards. .Sh SEE ALSO .Xr altq 4 , .Xr miibus 4 , .Xr netintro 4 , .Xr vlan 4 , .Xr eeprom 8 , .Xr ifconfig 8 .Sh HISTORY The .Nm device driver appeared in .Nx 1.6 . The first .Fx version to include it was .Fx 5.0 . .Sh AUTHORS .An -nosplit The .Nm driver was written for .Nx by .An Eduardo Horvath .Aq eeh@NetBSD.org . It was ported to .Fx by .An Thomas Moestl .Aq tmm@FreeBSD.org and later on improved by .An Marius Strobl .Aq marius@FreeBSD.org . The man page was written by .An Thomas Klausner .Aq wiz@NetBSD.org . Index: stable/9/share/man/man4/geom_fox.4 =================================================================== --- stable/9/share/man/man4/geom_fox.4 (revision 290885) +++ stable/9/share/man/man4/geom_fox.4 (revision 290886) @@ -1,215 +1,214 @@ .\" .\" Copyright (c) 2006 Wilko Bulte .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd January 2, 2005 .Dt GEOM_FOX 4 .Os .Sh NAME .Nm geom_fox .Nd "GEOM based basic disk multipathing" .Sh SYNOPSIS To compile this driver into the kernel, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "options GEOM_FOX" .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 geom_fox_load="YES" .Ed .Sh DESCRIPTION The intent of the .Nm framework is to provide basic multipathing support to access direct access devices. Basic in the above sentence should be read as: .Nm only provides path failover functionality, not load balancing over the available paths etc. Using suitable hardware like SCSI or FibreChannel disks it is possible to have multiple (typically 2) host bus adapters access the same physical disk drive. .Pp Without a multipathing driver the .Fx kernel would probe the disks multiple times, resulting in the creation of multiple .Pa /dev entries for the same underlying physical device. A unique label written in the GEOM label area allows .Nm to detect multiple paths. Using this information it creates a unique .Pa da#.fox device. .Pp The .Nm device is subsequently used by the .Fx kernel to access the disks. Multiple physical access paths ensure that even in case of a path failure the .Fx kernel can continue to access the data. .Pp The .Nm driver will disallow write operations to the underlying devices once the fox device has been opened for writing. .Sh EXAMPLES -.Pp .Bl -bullet -compact .It .Nm needs a label on the disk as follows in order to work properly: .Bd -literal "0123456789abcdef0123456789abcdef" "GEOM::FOX <--unique--id-->" .Ed .Pp For the unique ID 16 bytes are available. The .Dq Li GEOM::FOX is the magic to mark a .Nm device. .Pp The actual labelling is accomplished by .Bd -literal echo "GEOM::FOX someid" | dd of=/dev/da2 conv=sync .Ed .Pp For FibreChannel devices it is suggested to use the Node World Wide Name (Node WWN) as this is guaranteed by the FibreChannel standard to be worldwide unique. The use of the Port WWN not recommended as each port of a given device has a different WWN, thereby confusing things. .Pp The Node WWN can be obtained from a verbose boot as in for example .Bd -literal isp1: Target 1 (Loop 0x1) Port ID 0xe8 (role Target) Arrived Port WWN 0x21000004cfc8aca2 Node WWN 0x20000004cfc8aca2 .Ed .Pp This Node WWN would then be used like so: .Bd -literal echo "GEOM::FOX 20000004cfc8aca2" | dd of=/dev/da2 conv=sync .Ed .Pp For non-FibreChannel devices you could for example use the serial number of the device. Regardless of what you use, make sure the label is unique. .Pp Once the labelling has been performed and assuming the .Nm module is loaded the kernel will inform you that it has found a new .Nm device with a message similar to .Bd -literal Creating new fox (da2) fox da2.fox lock 0xfffffc0000fdba20 .Ed .Pp .It To check which physical devices match a given .Nm device: .Bd -literal -offset indent # geom fox list Geom name: da2.fox Providers: 1. Name: da2.fox Mediasize: 73407865344 (68G) Sectorsize: 512 Mode: r0w0e0 Consumers: 1. Name: da2 Mediasize: 73407865856 (68G) Sectorsize: 512 Mode: r0w0e0 2. Name: da6 Mediasize: 73407865856 (68G) Sectorsize: 512 Mode: r0w0e0 .Ed .Pp .It To check the status of the .Nm components: .Bd -literal # geom fox status Name Status Components da2.fox N/A da2 da6 .Ed .El .Sh SEE ALSO .Xr GEOM 4 , .Xr geom 8 , .Xr gmultipath 8 .Sh AUTHORS .An -nosplit The .Nm driver was written by .An "Poul-Henning Kamp" Aq phk@FreeBSD.org . This manual page was written by .An "Wilko Bulte" Aq wilko@FreeBSD.org . .Sh CAVEATS The .Nm driver depends on the underlying hardware drivers to do the right thing in case of a path failure. If for example a hardware driver continues to retry forever, .Nm is not able to re-initiate the I/O to an alternative physical path. .Pp You have to be very sure to provide a unique label for each of the .Nm devices. Safety belts are not provided. For FibreChannel devices it is suggested to use the Port WWN of the device. The World Wide Name is guaranteed to be worldwide unique per the FibreChannel standard. .Sh BUGS The .Nm framework has only seen light testing. There definitely might be dragons here. .Pp The name .Nm is completely obscure. Just remember that any sly fox has multiple exits from its hole. .Pp The examples provided are too FibreChannel-centric. Index: stable/9/share/man/man4/geom_uzip.4 =================================================================== --- stable/9/share/man/man4/geom_uzip.4 (revision 290885) +++ stable/9/share/man/man4/geom_uzip.4 (revision 290886) @@ -1,106 +1,105 @@ .\" .\" Copyright (c) 2006 Ceri Davies .\" 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, 2006 .Dt GEOM_UZIP 4 .Os .Sh NAME .Nm geom_uzip .Nd "GEOM based compressed disk images" .Sh SYNOPSIS To compile this driver into the kernel, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "options GEOM_UZIP" .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 geom_uzip_load="YES" .Ed .Sh DESCRIPTION The .Nm framework provides support for compressed read only disk images. This allows significant storage savings at the expense of a little CPU time on each read. Data written in the GEOM label area allows .Nm to detect compressed images which have been created with .Xr mkuzip 8 and presented to the kernel as a logical disk device via .Xr md 4 . .Nm creates a unique .Pa md#.uzip device for each image. .Pp The .Nm device is subsequently used by the .Fx kernel to access the disk images. The .Nm driver does not allow write operations to the underlying disk image. To check which .Xr md 4 devices match a given .Nm device: .Bd -literal -offset indent # geom uzip list Geom name: md1.uzip Providers: 1. Name: md1.uzip Mediasize: 22003712 (21M) Sectorsize: 512 Mode: r1w0e1 Consumers: 1. Name: md1 Mediasize: 9563648 (9.1M) Sectorsize: 512 Mode: r1w0e1 .Ed -.Pp .Sh SEE ALSO .Xr GEOM 4 , .Xr md 4 , .Xr geom 8 , .Xr mkuzip 8 .Sh AUTHORS .An -nosplit The .Nm driver was written by .An "Max Khon" Aq fjoe@FreeBSD.org . This manual page was written by .An "Ceri Davies" Aq ceri@FreeBSD.org . Index: stable/9/share/man/man4/hptiop.4 =================================================================== --- stable/9/share/man/man4/hptiop.4 (revision 290885) +++ stable/9/share/man/man4/hptiop.4 (revision 290886) @@ -1,139 +1,138 @@ .\" Copyright (c) 2007 Christian Brueffer .\" 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 July 5, 2013 .Dt HPTIOP 4 .Os .Sh NAME .Nm hptiop .Nd "HighPoint RocketRAID 3xxx/4xxx device driver" .Sh SYNOPSIS To compile this driver into the kernel, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "device hptiop" .Cd "device scbus" .Cd "device da" .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 hptiop_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for the HighPoint RocketRAID 3xxx/4xxx series of SAS and SATA RAID controllers. .Sh HARDWARE The .Nm driver supports the following SAS and SATA RAID controllers: .Pp .Bl -bullet -compact .It HighPoint RocketRAID 4522 .It HighPoint RocketRAID 4521 .It HighPoint RocketRAID 4520 .It HighPoint RocketRAID 4322 .It HighPoint RocketRAID 4321 .It HighPoint RocketRAID 4320 .It HighPoint RocketRAID 4311 .It HighPoint RocketRAID 4310 .It HighPoint RocketRAID 3640 .It HighPoint RocketRAID 3622 .It HighPoint RocketRAID 3620 .El .Pp The .Nm driver also supports the following SAS and SATA RAID controllers that are already End-of-Life: .Pp .Bl -bullet -compact .It HighPoint RocketRAID 4211 .It HighPoint RocketRAID 4210 .It HighPoint RocketRAID 3560 .It HighPoint RocketRAID 3540 .It HighPoint RocketRAID 3530 .It HighPoint RocketRAID 3522 .It HighPoint RocketRAID 3521 .It HighPoint RocketRAID 3520 .It HighPoint RocketRAID 3511 .It HighPoint RocketRAID 3510 .It HighPoint RocketRAID 3410 .It HighPoint RocketRAID 3320 .It HighPoint RocketRAID 3220 .It HighPoint RocketRAID 3122 .It HighPoint RocketRAID 3120 .It HighPoint RocketRAID 3020 .El .Sh NOTES The .Nm driver has only been tested on the i386 and amd64 platforms. .Sh SEE ALSO .Xr cam 4 , .Xr hptmv 4 .Sh HISTORY The .Nm device driver first appeared in .Fx 7.0 . -.Pp .Sh AUTHORS The .Nm driver was written by HighPoint Technologies, Inc. Index: stable/9/share/man/man4/igb.4 =================================================================== --- stable/9/share/man/man4/igb.4 (revision 290885) +++ stable/9/share/man/man4/igb.4 (revision 290886) @@ -1,229 +1,228 @@ .\" Copyright (c) 2001-2003, Intel Corporation .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions are met: .\" .\" 1. Redistributions of source code must retain the above copyright notice, .\" this list of conditions and the following disclaimer. .\" .\" 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 Intel Corporation nor the names of its .\" contributors may be used to endorse or promote products derived from .\" this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" .\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER 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. .\" .\" * Other names and brands may be claimed as the property of others. .\" .\" $FreeBSD$ .\" .Dd March 25, 2013 .Dt IGB 4 .Os .Sh NAME .Nm igb .Nd "Intel(R) PRO/1000 PCI Express Gigabit Ethernet adapter 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 igb" .Ed .Pp Alternatively, to load the driver as a module at boot time, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent if_igb_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for PCI Express Gigabit Ethernet adapters based on the Intel 82575 and 82576 Ethernet controller chips. The driver supports Transmit/Receive checksum offload and Jumbo Frames. Furthermore it supports TCP segmentation offload (TSO) on all adapters. The identification LEDs of the adapters supported by the .Nm driver can be controlled via the .Xr led 4 API for localization purposes. .Pp For questions related to hardware requirements, refer to the documentation supplied with your Intel PRO/1000 adapter. All hardware requirements listed apply to use with .Fx . .Pp Support for Jumbo Frames is provided via the interface MTU setting. Selecting an MTU larger than 1500 bytes with the .Xr ifconfig 8 utility configures the adapter to receive and transmit Jumbo Frames. The maximum MTU size for Jumbo Frames is 9216. .Pp This driver supports hardware assisted VLANs. The .Nm driver supports the following media types: .Bl -tag -width ".Cm 10baseT/UTP" .It Cm autoselect Enables auto-negotiation for speed and duplex. .It Cm 10baseT/UTP Sets 10Mbps operation. Use the .Cm mediaopt option to select .Cm full-duplex mode. .It Cm 100baseTX Sets 100Mbps operation. Use the .Cm mediaopt option to select .Cm full-duplex mode. .It Cm 1000baseSX Sets 1000Mbps operation. Only .Cm full-duplex mode is supported at this speed. .It Cm 1000baseTX Sets 1000Mbps operation. Only .Cm full-duplex mode is supported at this speed. .El .Pp The .Nm driver supports the following media options: .Bl -tag -width ".Cm full-duplex" .It Cm full-duplex Forces full-duplex operation .It Cm half-duplex Forces half-duplex operation. .El .Pp Only use .Cm mediaopt to set the driver to .Cm full-duplex . If .Cm mediaopt is not specified, the driver defaults to .Cm half-duplex . .Pp For more information on configuring this device, see .Xr ifconfig 8 . .Sh HARDWARE The .Nm driver supports Gigabit Ethernet adapters based on the Intel 82575 and 82576 controller chips: .Pp .Bl -bullet -compact .It Intel Gigabit ET Dual Port Server Adapter (82576) .It Intel Gigabit VT Quad Port Server Adapter (82575) .El .Sh LOADER TUNABLES Tunables can be set at the .Xr loader 8 prompt before booting the kernel or stored in .Xr loader.conf 5 . .Bl -tag -width indent .It Va hw.igb.rxd Number of receive descriptors allocated by the driver. The default value is 256. The minimum is 80, and the maximum is 4096. .It Va hw.igb.txd Number of transmit descriptors allocated by the driver. The default value is 256. The minimum is 80, and the maximum is 4096. .It Va hw.igb.enable_aim If set to 1, enable Adaptive Interrupt Moderation. The default is to enable Adaptive Interrupt Moderation. .It Va hw.igb.num_queues Number of queues used for data transfer. If set to 0, number of queues will be configured automatically based on number of CPUs and max supported MSI-X messages on the device. .It Va kern.ipc.nmbclusters The maximum number of mbuf clusters allowed. If the system has more than one igb card or jumbo frames are enabled, this value will need to be increased. .It Va kern.ipc.nmbjumbo9k The maximum number of mbuf 9k jumbo clusters allowed. Increasing this to allow for at least 8192 extra clusters per interface can allow for an mtu of 8192. .El .Sh FILES .Bl -tag -width /dev/led/igb* .It Pa /dev/led/igb* identification LED device nodes .El .Sh EXAMPLES Make the identification LED of igb0 blink: .Pp .Dl "echo f2 > /dev/led/igb0" .Pp Turn the identification LED of igb0 off again: .Pp .Dl "echo 0 > /dev/led/igb0" -.Pp .Sh DIAGNOSTICS .Bl -diag .It "igb%d: Unable to allocate bus resource: memory" A fatal initialization error has occurred. .It "igb%d: Unable to allocate bus resource: interrupt" A fatal initialization error has occurred. .It "igb%d: watchdog timeout -- resetting" The device has stopped responding to the network, or there is a problem with the network connection (cable). .El .Sh SUPPORT For general information and support, go to the Intel support website at: .Pa http://support.intel.com . .Pp If an issue is identified with the released source code on the supported kernel with a supported adapter, email the specific information related to the issue to .Aq freebsdnic@mailbox.intel.com . .Sh SEE ALSO .Xr altq 4 , .Xr arp 4 , .Xr em 4 , .Xr led 4 , .Xr netintro 4 , .Xr ng_ether 4 , .Xr polling 4 , .Xr vlan 4 , .Xr ifconfig 8 .Sh HISTORY The .Nm device driver first appeared in .Fx 7.1 . .Sh AUTHORS The .Nm driver was written by .An Intel Corporation Aq freebsdnic@mailbox.intel.com . Index: stable/9/share/man/man4/ip.4 =================================================================== --- stable/9/share/man/man4/ip.4 (revision 290885) +++ stable/9/share/man/man4/ip.4 (revision 290886) @@ -1,891 +1,889 @@ .\" Copyright (c) 1983, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)ip.4 8.2 (Berkeley) 11/30/93 .\" $FreeBSD$ .\" .Dd October 12, 2012 .Dt IP 4 .Os .Sh NAME .Nm ip .Nd Internet Protocol .Sh SYNOPSIS .In sys/types.h .In sys/socket.h .In netinet/in.h .Ft int .Fn socket AF_INET SOCK_RAW proto .Sh DESCRIPTION .Tn IP is the transport layer protocol used by the Internet protocol family. Options may be set at the .Tn IP level when using higher-level protocols that are based on .Tn IP (such as .Tn TCP and .Tn UDP ) . It may also be accessed through a .Dq raw socket when developing new protocols, or special-purpose applications. .Pp There are several .Tn IP-level .Xr setsockopt 2 and .Xr getsockopt 2 options. .Dv IP_OPTIONS may be used to provide .Tn IP options to be transmitted in the .Tn IP header of each outgoing packet or to examine the header options on incoming packets. .Tn IP options may be used with any socket type in the Internet family. The format of .Tn IP options to be sent is that specified by the .Tn IP protocol specification (RFC-791), with one exception: the list of addresses for Source Route options must include the first-hop gateway at the beginning of the list of gateways. The first-hop gateway address will be extracted from the option list and the size adjusted accordingly before use. To disable previously specified options, use a zero-length buffer: .Bd -literal setsockopt(s, IPPROTO_IP, IP_OPTIONS, NULL, 0); .Ed .Pp .Dv IP_TOS and .Dv IP_TTL may be used to set the type-of-service and time-to-live fields in the .Tn IP header for .Dv SOCK_STREAM , SOCK_DGRAM , and certain types of .Dv SOCK_RAW sockets. For example, .Bd -literal int tos = IPTOS_LOWDELAY; /* see */ setsockopt(s, IPPROTO_IP, IP_TOS, &tos, sizeof(tos)); int ttl = 60; /* max = 255 */ setsockopt(s, IPPROTO_IP, IP_TTL, &ttl, sizeof(ttl)); .Ed .Pp .Dv IP_MINTTL may be used to set the minimum acceptable TTL a packet must have when received on a socket. All packets with a lower TTL are silently dropped. This option is only really useful when set to 255, preventing packets from outside the directly connected networks reaching local listeners on sockets. .Pp .Dv IP_DONTFRAG may be used to set the Don't Fragment flag on IP packets. Currently this option is respected only on .Xr udp 4 and raw .Xr ip 4 sockets, unless the .Dv IP_HDRINCL option has been set. On .Xr tcp 4 sockets, the Don't Fragment flag is controlled by the Path MTU Discovery option. Sending a packet larger than the MTU size of the egress interface, determined by the destination address, returns an .Er EMSGSIZE error. .Pp If the .Dv IP_RECVDSTADDR option is enabled on a .Dv SOCK_DGRAM socket, the .Xr recvmsg 2 call will return the destination .Tn IP address for a .Tn UDP datagram. The .Vt msg_control field in the .Vt msghdr structure points to a buffer that contains a .Vt cmsghdr structure followed by the .Tn IP address. The .Vt cmsghdr fields have the following values: .Bd -literal cmsg_len = CMSG_LEN(sizeof(struct in_addr)) cmsg_level = IPPROTO_IP cmsg_type = IP_RECVDSTADDR .Ed .Pp The source address to be used for outgoing .Tn UDP datagrams on a socket can be specified as ancillary data with a type code of .Dv IP_SENDSRCADDR . The msg_control field in the msghdr structure should point to a buffer that contains a .Vt cmsghdr structure followed by the .Tn IP address. The cmsghdr fields should have the following values: .Bd -literal cmsg_len = CMSG_LEN(sizeof(struct in_addr)) cmsg_level = IPPROTO_IP cmsg_type = IP_SENDSRCADDR .Ed .Pp The socket should be either bound to .Dv INADDR_ANY and a local port, and the address supplied with .Dv IP_SENDSRCADDR should't be .Dv INADDR_ANY , or the socket should be bound to a local address and the address supplied with .Dv IP_SENDSRCADDR should be .Dv INADDR_ANY . In the latter case bound address is overriden via generic source address selection logic, which would choose IP address of interface closest to destination. .Pp For convenience, .Dv IP_SENDSRCADDR is defined to have the same value as .Dv IP_RECVDSTADDR , so the .Dv IP_RECVDSTADDR control message from .Xr recvmsg 2 can be used directly as a control message for .Xr sendmsg 2 . .\" .Pp If the .Dv IP_ONESBCAST option is enabled on a .Dv SOCK_DGRAM or a .Dv SOCK_RAW socket, the destination address of outgoing broadcast datagrams on that socket will be forced to the undirected broadcast address, .Dv INADDR_BROADCAST , before transmission. This is in contrast to the default behavior of the system, which is to transmit undirected broadcasts via the first network interface with the .Dv IFF_BROADCAST flag set. .Pp This option allows applications to choose which interface is used to transmit an undirected broadcast datagram. For example, the following code would force an undirected broadcast to be transmitted via the interface configured with the broadcast address 192.168.2.255: .Bd -literal char msg[512]; struct sockaddr_in sin; u_char onesbcast = 1; /* 0 = disable (default), 1 = enable */ setsockopt(s, IPPROTO_IP, IP_ONESBCAST, &onesbcast, sizeof(onesbcast)); sin.sin_addr.s_addr = inet_addr("192.168.2.255"); sin.sin_port = htons(1234); sendto(s, msg, sizeof(msg), 0, &sin, sizeof(sin)); .Ed .Pp It is the application's responsibility to set the .Dv IP_TTL option to an appropriate value in order to prevent broadcast storms. The application must have sufficient credentials to set the .Dv SO_BROADCAST socket level option, otherwise the .Dv IP_ONESBCAST option has no effect. .Pp If the .Dv IP_BINDANY option is enabled on a .Dv SOCK_STREAM , .Dv SOCK_DGRAM or a .Dv SOCK_RAW socket, one can .Xr bind 2 to any address, even one not bound to any available network interface in the system. This functionality (in conjunction with special firewall rules) can be used for implementing a transparent proxy. The .Dv PRIV_NETINET_BINDANY privilege is needed to set this option. .Pp If the .Dv IP_RECVTTL option is enabled on a .Dv SOCK_DGRAM socket, the .Xr recvmsg 2 call will return the .Tn IP .Tn TTL (time to live) field for a .Tn UDP datagram. The msg_control field in the msghdr structure points to a buffer that contains a cmsghdr structure followed by the .Tn TTL . The cmsghdr fields have the following values: .Bd -literal cmsg_len = CMSG_LEN(sizeof(u_char)) cmsg_level = IPPROTO_IP cmsg_type = IP_RECVTTL .Ed .\" .Pp If the .Dv IP_RECVTOS option is enabled on a .Dv SOCK_DGRAM socket, the .Xr recvmsg 2 call will return the .Tn IP .Tn TOS (type of service) field for a .Tn UDP datagram. The msg_control field in the msghdr structure points to a buffer that contains a cmsghdr structure followed by the .Tn TOS . The cmsghdr fields have the following values: .Bd -literal cmsg_len = CMSG_LEN(sizeof(u_char)) cmsg_level = IPPROTO_IP cmsg_type = IP_RECVTOS .Ed .\" .Pp If the .Dv IP_RECVIF option is enabled on a .Dv SOCK_DGRAM socket, the .Xr recvmsg 2 call returns a .Vt "struct sockaddr_dl" corresponding to the interface on which the packet was received. The .Va msg_control field in the .Vt msghdr structure points to a buffer that contains a .Vt cmsghdr structure followed by the .Vt "struct sockaddr_dl" . The .Vt cmsghdr fields have the following values: .Bd -literal cmsg_len = CMSG_LEN(sizeof(struct sockaddr_dl)) cmsg_level = IPPROTO_IP cmsg_type = IP_RECVIF .Ed .Pp .Dv IP_PORTRANGE may be used to set the port range used for selecting a local port number on a socket with an unspecified (zero) port number. It has the following possible values: .Bl -tag -width IP_PORTRANGE_DEFAULT .It Dv IP_PORTRANGE_DEFAULT use the default range of values, normally .Dv IPPORT_HIFIRSTAUTO through .Dv IPPORT_HILASTAUTO . This is adjustable through the sysctl setting: .Va net.inet.ip.portrange.first and .Va net.inet.ip.portrange.last . .It Dv IP_PORTRANGE_HIGH use a high range of values, normally .Dv IPPORT_HIFIRSTAUTO and .Dv IPPORT_HILASTAUTO . This is adjustable through the sysctl setting: .Va net.inet.ip.portrange.hifirst and .Va net.inet.ip.portrange.hilast . .It Dv IP_PORTRANGE_LOW use a low range of ports, which are normally restricted to privileged processes on .Ux systems. The range is normally from .Dv IPPORT_RESERVED \- 1 down to .Li IPPORT_RESERVEDSTART in descending order. This is adjustable through the sysctl setting: .Va net.inet.ip.portrange.lowfirst and .Va net.inet.ip.portrange.lowlast . .El .Pp The range of privileged ports which only may be opened by root-owned processes may be modified by the .Va net.inet.ip.portrange.reservedlow and .Va net.inet.ip.portrange.reservedhigh sysctl settings. The values default to the traditional range, 0 through .Dv IPPORT_RESERVED \- 1 (0 through 1023), respectively. Note that these settings do not affect and are not accounted for in the use or calculation of the other .Va net.inet.ip.portrange values above. Changing these values departs from .Ux tradition and has security consequences that the administrator should carefully evaluate before modifying these settings. .Pp Ports are allocated at random within the specified port range in order to increase the difficulty of random spoofing attacks. In scenarios such as benchmarking, this behavior may be undesirable. In these cases, .Va net.inet.ip.portrange.randomized can be used to toggle randomization off. If more than .Va net.inet.ip.portrange.randomcps ports have been allocated in the last second, then return to sequential port allocation. Return to random allocation only once the current port allocation rate drops below .Va net.inet.ip.portrange.randomcps for at least .Va net.inet.ip.portrange.randomtime seconds. The default values for .Va net.inet.ip.portrange.randomcps and .Va net.inet.ip.portrange.randomtime are 10 port allocations per second and 45 seconds correspondingly. .Ss "Multicast Options" -.Pp .Tn IP multicasting is supported only on .Dv AF_INET sockets of type .Dv SOCK_DGRAM and .Dv SOCK_RAW , and only on networks where the interface driver supports multicasting. .Pp The .Dv IP_MULTICAST_TTL option changes the time-to-live (TTL) for outgoing multicast datagrams in order to control the scope of the multicasts: .Bd -literal u_char ttl; /* range: 0 to 255, default = 1 */ setsockopt(s, IPPROTO_IP, IP_MULTICAST_TTL, &ttl, sizeof(ttl)); .Ed .Pp Datagrams with a TTL of 1 are not forwarded beyond the local network. Multicast datagrams with a TTL of 0 will not be transmitted on any network, but may be delivered locally if the sending host belongs to the destination group and if multicast loopback has not been disabled on the sending socket (see below). Multicast datagrams with TTL greater than 1 may be forwarded to other networks if a multicast router is attached to the local network. .Pp For hosts with multiple interfaces, where an interface has not been specified for a multicast group membership, each multicast transmission is sent from the primary network interface. The .Dv IP_MULTICAST_IF option overrides the default for subsequent transmissions from a given socket: .Bd -literal struct in_addr addr; setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, &addr, sizeof(addr)); .Ed .Pp where "addr" is the local .Tn IP address of the desired interface or .Dv INADDR_ANY to specify the default interface. .Pp To specify an interface by index, an instance of .Vt ip_mreqn may be passed instead. The .Vt imr_ifindex member should be set to the index of the desired interface, or 0 to specify the default interface. The kernel differentiates between these two structures by their size. .Pp The use of .Vt IP_MULTICAST_IF is .Em not recommended , as multicast memberships are scoped to each individual interface. It is supported for legacy use only by applications, such as routing daemons, which expect to be able to transmit link-local IPv4 multicast datagrams (224.0.0.0/24) on multiple interfaces, without requesting an individual membership for each interface. .Pp .\" An interface's local IP address and multicast capability can be obtained via the .Dv SIOCGIFCONF and .Dv SIOCGIFFLAGS ioctls. Normal applications should not need to use this option. .Pp If a multicast datagram is sent to a group to which the sending host itself belongs (on the outgoing interface), a copy of the datagram is, by default, looped back by the IP layer for local delivery. The .Dv IP_MULTICAST_LOOP option gives the sender explicit control over whether or not subsequent datagrams are looped back: .Bd -literal u_char loop; /* 0 = disable, 1 = enable (default) */ setsockopt(s, IPPROTO_IP, IP_MULTICAST_LOOP, &loop, sizeof(loop)); .Ed .Pp This option improves performance for applications that may have no more than one instance on a single host (such as a routing daemon), by eliminating the overhead of receiving their own transmissions. It should generally not be used by applications for which there may be more than one instance on a single host (such as a conferencing program) or for which the sender does not belong to the destination group (such as a time querying program). .Pp The sysctl setting .Va net.inet.ip.mcast.loop controls the default setting of the .Dv IP_MULTICAST_LOOP socket option for new sockets. .Pp A multicast datagram sent with an initial TTL greater than 1 may be delivered to the sending host on a different interface from that on which it was sent, if the host belongs to the destination group on that other interface. The loopback control option has no effect on such delivery. .Pp A host must become a member of a multicast group before it can receive datagrams sent to the group. To join a multicast group, use the .Dv IP_ADD_MEMBERSHIP option: .Bd -literal struct ip_mreq mreq; setsockopt(s, IPPROTO_IP, IP_ADD_MEMBERSHIP, &mreq, sizeof(mreq)); .Ed .Pp where .Fa mreq is the following structure: .Bd -literal struct ip_mreq { struct in_addr imr_multiaddr; /* IP multicast address of group */ struct in_addr imr_interface; /* local IP address of interface */ } .Ed .Pp .Va imr_interface should be set to the .Tn IP address of a particular multicast-capable interface if the host is multihomed. It may be set to .Dv INADDR_ANY to choose the default interface, although this is not recommended; this is considered to be the first interface corresponding to the default route. Otherwise, the first multicast-capable interface configured in the system will be used. .Pp Prior to .Fx 7.0 , if the .Va imr_interface member is within the network range .Li 0.0.0.0/8 , it is treated as an interface index in the system interface MIB, as per the RIP Version 2 MIB Extension (RFC-1724). In versions of .Fx since 7.0, this behavior is no longer supported. Developers should instead use the RFC 3678 multicast source filter APIs; in particular, .Dv MCAST_JOIN_GROUP . .Pp Up to .Dv IP_MAX_MEMBERSHIPS memberships may be added on a single socket. Membership is associated with a single interface; programs running on multihomed hosts may need to join the same group on more than one interface. .Pp To drop a membership, use: .Bd -literal struct ip_mreq mreq; setsockopt(s, IPPROTO_IP, IP_DROP_MEMBERSHIP, &mreq, sizeof(mreq)); .Ed .Pp where .Fa mreq contains the same values as used to add the membership. Memberships are dropped when the socket is closed or the process exits. .\" TODO: Update this piece when IPv4 source-address selection is implemented. .Pp The IGMP protocol uses the primary IP address of the interface as its identifier for group membership. This is the first IP address configured on the interface. If this address is removed or changed, the results are undefined, as the IGMP membership state will then be inconsistent. If multiple IP aliases are configured on the same interface, they will be ignored. .Pp This shortcoming was addressed in IPv6; MLDv2 requires that the unique link-local address for an interface is used to identify an MLDv2 listener. .Ss "Source-Specific Multicast Options" Since .Fx 8.0 , the use of Source-Specific Multicast (SSM) is supported. These extensions require an IGMPv3 multicast router in order to make best use of them. If a legacy multicast router is present on the link, .Fx will simply downgrade to the version of IGMP spoken by the router, and the benefits of source filtering on the upstream link will not be present, although the kernel will continue to squelch transmissions from blocked sources. .Pp Each group membership on a socket now has a filter mode: .Bl -tag -width MCAST_EXCLUDE .It Dv MCAST_EXCLUDE Datagrams sent to this group are accepted, unless the source is in a list of blocked source addresses. .It Dv MCAST_INCLUDE Datagrams sent to this group are accepted only if the source is in a list of accepted source addresses. .El .Pp Groups joined using the legacy .Dv IP_ADD_MEMBERSHIP option are placed in exclusive-mode, and are able to request that certain sources are blocked or allowed. This is known as the .Em delta-based API . .Pp To block a multicast source on an existing group membership: .Bd -literal struct ip_mreq_source mreqs; setsockopt(s, IPPROTO_IP, IP_BLOCK_SOURCE, &mreqs, sizeof(mreqs)); .Ed .Pp where .Fa mreqs is the following structure: .Bd -literal struct ip_mreq_source { struct in_addr imr_multiaddr; /* IP multicast address of group */ struct in_addr imr_sourceaddr; /* IP address of source */ struct in_addr imr_interface; /* local IP address of interface */ } .Ed .Va imr_sourceaddr should be set to the address of the source to be blocked. .Pp To unblock a multicast source on an existing group: .Bd -literal struct ip_mreq_source mreqs; setsockopt(s, IPPROTO_IP, IP_UNBLOCK_SOURCE, &mreqs, sizeof(mreqs)); .Ed .Pp The .Dv IP_BLOCK_SOURCE and .Dv IP_UNBLOCK_SOURCE options are .Em not permitted for inclusive-mode group memberships. .Pp To join a multicast group in .Dv MCAST_INCLUDE mode with a single source, or add another source to an existing inclusive-mode membership: .Bd -literal struct ip_mreq_source mreqs; setsockopt(s, IPPROTO_IP, IP_ADD_SOURCE_MEMBERSHIP, &mreqs, sizeof(mreqs)); .Ed .Pp To leave a single source from an existing group in inclusive mode: .Bd -literal struct ip_mreq_source mreqs; setsockopt(s, IPPROTO_IP, IP_DROP_SOURCE_MEMBERSHIP, &mreqs, sizeof(mreqs)); .Ed If this is the last accepted source for the group, the membership will be dropped. .Pp The .Dv IP_ADD_SOURCE_MEMBERSHIP and .Dv IP_DROP_SOURCE_MEMBERSHIP options are .Em not accepted for exclusive-mode group memberships. However, both exclusive and inclusive mode memberships support the use of the .Em full-state API documented in RFC 3678. For management of source filter lists using this API, please refer to .Xr sourcefilter 3 . .Pp The sysctl settings .Va net.inet.ip.mcast.maxsocksrc and .Va net.inet.ip.mcast.maxgrpsrc are used to specify an upper limit on the number of per-socket and per-group source filter entries which the kernel may allocate. .\"----------------------- .Ss "Raw IP Sockets" -.Pp Raw .Tn IP sockets are connectionless, and are normally used with the .Xr sendto 2 and .Xr recvfrom 2 calls, though the .Xr connect 2 call may also be used to fix the destination for future packets (in which case the .Xr read 2 or .Xr recv 2 and .Xr write 2 or .Xr send 2 system calls may be used). .Pp If .Fa proto is 0, the default protocol .Dv IPPROTO_RAW is used for outgoing packets, and only incoming packets destined for that protocol are received. If .Fa proto is non-zero, that protocol number will be used on outgoing packets and to filter incoming packets. .Pp Outgoing packets automatically have an .Tn IP header prepended to them (based on the destination address and the protocol number the socket is created with), unless the .Dv IP_HDRINCL option has been set. Incoming packets are received with .Tn IP header and options intact, except for .Va ip_len and .Va ip_off fields converted to host byte order. .Pp .Dv IP_HDRINCL indicates the complete IP header is included with the data and may be used only with the .Dv SOCK_RAW type. .Bd -literal #include #include int hincl = 1; /* 1 = on, 0 = off */ setsockopt(s, IPPROTO_IP, IP_HDRINCL, &hincl, sizeof(hincl)); .Ed .Pp Unlike previous .Bx releases, the program must set all the fields of the IP header, including the following: .Bd -literal ip->ip_v = IPVERSION; ip->ip_hl = hlen >> 2; ip->ip_id = 0; /* 0 means kernel set appropriate value */ ip->ip_off = offset; .Ed .Pp The .Va ip_len and .Va ip_off fields .Em must be provided in host byte order. All other fields must be provided in network byte order. See .Xr byteorder 3 for more information on network byte order. If the .Va ip_id field is set to 0 then the kernel will choose an appropriate value. If the header source address is set to .Dv INADDR_ANY , the kernel will choose an appropriate address. .Sh ERRORS A socket operation may fail with one of the following errors returned: .Bl -tag -width Er .It Bq Er EISCONN when trying to establish a connection on a socket which already has one, or when trying to send a datagram with the destination address specified and the socket is already connected; .It Bq Er ENOTCONN when trying to send a datagram, but no destination address is specified, and the socket has not been connected; .It Bq Er ENOBUFS when the system runs out of memory for an internal data structure; .It Bq Er EADDRNOTAVAIL when an attempt is made to create a socket with a network address for which no network interface exists. .It Bq Er EACCES when an attempt is made to create a raw IP socket by a non-privileged process. .El .Pp The following errors specific to .Tn IP may occur when setting or getting .Tn IP options: .Bl -tag -width Er .It Bq Er EINVAL An unknown socket option name was given. .It Bq Er EINVAL The IP option field was improperly formed; an option field was shorter than the minimum value or longer than the option buffer provided. .El .Pp The following errors may occur when attempting to send .Tn IP datagrams via a .Dq raw socket with the .Dv IP_HDRINCL option set: .Bl -tag -width Er .It Bq Er EINVAL The user-supplied .Va ip_len field was not equal to the length of the datagram written to the socket. .El .Sh SEE ALSO .Xr getsockopt 2 , .Xr recv 2 , .Xr send 2 , .Xr byteorder 3 , .Xr icmp 4 , .Xr igmp 4 , .Xr inet 4 , .Xr intro 4 , .Xr multicast 4 , .Xr sourcefilter 3 .Rs .%A D. Thaler .%A B. Fenner .%A B. Quinn .%T "Socket Interface Extensions for Multicast Source Filters" .%N RFC 3678 .%D Jan 2004 .Re .Sh HISTORY The .Nm protocol appeared in .Bx 4.2 . The .Vt ip_mreqn structure appeared in .Tn Linux 2.4 . Index: stable/9/share/man/man4/isp.4 =================================================================== --- stable/9/share/man/man4/isp.4 (revision 290885) +++ stable/9/share/man/man4/isp.4 (revision 290886) @@ -1,239 +1,238 @@ .\" $NetBSD: isp.4,v 1.5 1999/12/18 18:33:05 mjacob Exp $ .\" .\" Copyright (c) 1998, 1999, 2001 .\" Matthew Jacob, for NASA/Ames Research Center .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" Additional Copyright (c) 2006 by Marcus Alves Grando .\" .\" $FreeBSD$ .\" .Dd February 28, 2007 .Dt ISP 4 .Os .Sh NAME .Nm isp .Nd Qlogic based SCSI and FibreChannel SCSI Host Adapters .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device scbus" .Cd "device isp" .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 isp_load="YES" .Ed .Sh DESCRIPTION This driver provides access to .Tn SCSI or .Tn FibreChannel devices. .Pp SCSI features include support for Ultra SCSI and wide mode transactions for .Tn SCSI , Ultra2 LVD (for the ISP1080 and ISP1280), and Ultra3 LVD (for the ISP12160). .Pp Fibre Channel support uses FCP SCSI profile for .Tn FibreChannel , and utilizes Class 3 and Class 2 connections (Qlogic 2100 is Class 3 only, minor patches to the Qlogic 2200 to force Class 2 mode). Support is available for Public and Private loops, and for point-to-point connections (Qlogic 2200 only). The newer 2-Gigabit cards (2300, 2312, 2322) and 4-Gigabit (2422, 2432) are also supported. Command tagging is supported for all (in fact, .Tn FibreChannel requires tagging). Fabric support is enabled by default for other than 2100 cards. Fabric support for 2100 cards has been so problematic and these cards are so old now that it is just not worth your time to try it. .Sh FIRMWARE Firmware is available if the .Xr ispfw 4 module is loaded during bootstrap (q.v.). .Pp It is .Ar strongly recommended that you use the firmware available from .Xr ispfw 4 as it is the most likely to have been tested with this driver. .Sh HARDWARE Cards supported by the .Nm driver include: .Bl -tag -width xxxxxx -offset indent .It ISP1000 SBus Fast Wide, Ultra Fast Wide cards, Single Ended or Differential cards. .It ISP1020 Qlogic 1020 Fast Wide and Differential Fast Wide PCI cards. .It ISP1040 Qlogic 1040 Ultra Wide and Differential Ultra Wide PCI cards. Also known as the DEC KZPBA-CA (single ended) and KZPBA-CB (HVD differential). .It Qlogic 1240 Qlogic 1240 Dual Bus Ultra Wide and Differential Ultra Wide PCI cards. .It Qlogic 1020 Qlogic 1020 SCSI cards. .It Qlogic 1040 Qlogic 1040 Ultra SCSI cards. .It Qlogic 1080 Qlogic 1280 LVD Ultra2 Wide PCI cards. .It Qlogic 1280 Qlogic 1280 Dual Bus LVD Ultra2 Wide PCI cards. .It Qlogic 12160 Qlogic 12160 Dual Bus LVD Ultra3 Wide PCI cards. .It Qlogic 210X Qlogic 2100 and 2100A Copper and Optical Fibre Channel Arbitrated Loop (single, dual). .It Qlogic 220X Qlogic 2200 Copper and Optical Fibre Channel Arbitrated Loop PCI cards (single, dual, quad). .It Qlogic 2300 Qlogic 2300 Optical Fibre Channel PCI cards. .It Qlogic 2312 Qlogic 2312 Optical Fibre Channel PCI cards. .It Qlogic 234X Qlogic 234X Optical Fibre Channel PCI cards (2312 chipset, single and dual attach). .It Qlogic 2322 Qlogic 2322 Optical Fibre Channel PCIe cards. .It Qlogic 200 Dell Branded version of the QLogic 2312 Fibre Channel PCI cards. .It Qlogic 2422 Qlogic 2422 Optical Fibre Channel PCI cards (4 Gigabit) .It Qlogic 2432 Qlogic 2432 Optical Fibre Channel PCIe cards (4 Gigabit) .El .Sh CONFIGURATION OPTIONS -.Pp Target mode support may be enabled with the .Pp .Cd options ISP_TARGET_MODE .Pp option. .Sh BOOT OPTIONS The following options are switchable by setting values in .Pa /boot/device.hints . .Pp They are: .Bl -tag -width indent .It Va hint.isp.0.disable A hint value to disable driver in kernel. .It Va hint.isp.0.fwload_disable A hint value to disable loading of firmware .Xr ispfw 4 . .It Va hint.isp.0.prefer_memmap A hint value to use PCI memory space instead of I/O space access for. .It Va hint.isp.0.prefer_iomap A hint value to use PCI I/O space instead of Memory space access for. .It Va hint.isp.0.ignore_nvram A hint value to ignore board NVRAM settings for. Otherwise use NVRAM settings. .It Va hint.isp.0.fullduplex A hint value to set full duplex mode. .It Va hint.isp.0.topology A hint value to select topology of connection. Supported values are: .Pp .Bl -tag -width ".Li lport-only" -compact .It Li lport Prefer loopback and fallback to point to point. .It Li nport Prefer point to point and fallback to loopback. .It Li lport-only Loopback only. .It Li nport-only Point to point only. .El .It Va hint.isp.0.portwwn This should be the full 64 bit World Wide Port Name you would like to use, overriding the value in NVRAM for the card. .It Va hint.isp.0.nodewwn This should be the full 64 bit World Wide Node Name you would like to use, overriding the value in NVRAM for the card. .It Va hint.isp.0.iid A hint to override or set the Initiator ID or Loop ID. For Fibre Channel cards in Local Loop topologies it is .Ar strongly recommended that you set this value to non-zero. .It Va hint.isp.0.role A hint to define default role for isp instance (target, initiator, both). .It Va hint.isp.0.debug A hint value for a driver debug level (see the file .Pa /usr/src/sys/dev/isp/ispvar.h for the values. .El .Sh SYSCTL OPTIONS .Bl -tag -width indent .It Va dev.isp.N.loop_down_limit This value says how long to wait in seconds after loop has gone down before giving up and expiring all of the devices that were visible. The default is 300 seconds (5 minutes). A separate (nonadjustable) timeout is used when booting to not stop booting on lack of FC connectivity. .It Va dev.isp.N.gone_device_time This value says how long to wait for devices to reappear if they (temporarily) disappear due to loop or fabric events. While this timeout is running, I/O to those devices will simply be held. .It Va dev.isp.N.wwnn This is the readonly World Wide Node Name value for this port. .It Va dev.isp.N.wwpn This is the readonly World Wide Port Name value for this port. .El .Sh SEE ALSO .Xr da 4 , .Xr intro 4 , .Xr ispfw 4 , .Xr sa 4 , .Xr scsi 4 , .Xr gmultipath 8 .Sh AUTHORS The .Nm driver was written by Matthew Jacob originally for NetBSD at NASA/Ames Research Center. .Sh BUGS The driver currently ignores some NVRAM settings. .Pp Target mode support is not completely reliable yet. It works reasonably well for Fibre Channel, somewhat well for Qlogic 1040 cards, but does not yet work for the other cards (due to last minute unannounced changes in firmware interfaces). Index: stable/9/share/man/man4/man4.powerpc/bm.4 =================================================================== --- stable/9/share/man/man4/man4.powerpc/bm.4 (revision 290885) +++ stable/9/share/man/man4/man4.powerpc/bm.4 (revision 290886) @@ -1,89 +1,87 @@ .\"- .\" Copyright (c) 2008 Nathan Whitehorn .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE .\" DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN .\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd July 3, 2008 .Dt BM 4 .Os .Sh NAME .Nm bm .Nd BMAC Ethernet 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 miibus" .Cd "device bm" .Ed .Pp Alternatively, to load the driver as a module at boot time, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent if_bm_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for the BMac ethernet hardware found mostly in G3-based Apple hardware. It is a close relative of the Sun HME controller found in contemporary Sun workstations. .Sh HARDWARE -.Pp Chips supported by the .Nm driver include: .Pp .Bl -bullet -compact .It Apple BMAC Onboard Ethernet .It Apple BMAC+ Onboard Ethernet .El -.Pp .Sh SEE ALSO .Xr altq 4 , .Xr hme 4 , .Xr miibus 4 , .Xr netintro 4 , .Xr ifconfig 8 .Sh HISTORY The .Nm device driver appeared in .Fx 7.1 . .Sh AUTHORS .An -nosplit The .Nm driver was written by .An Nathan Whitehorn .Aq nwhitehorn@FreeBSD.org based on work by .An Peter Grehan .Aq grehan@FreeBSD.org . Index: stable/9/share/man/man4/man4.powerpc/snd_ai2s.4 =================================================================== --- stable/9/share/man/man4/man4.powerpc/snd_ai2s.4 (revision 290885) +++ stable/9/share/man/man4/man4.powerpc/snd_ai2s.4 (revision 290886) @@ -1,90 +1,88 @@ .\"- .\" Copyright (c) 2009 Nathan Whitehorn .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE .\" DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN .\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd January 20, 2009 .Dt SND_AI2S 4 .Os .Sh NAME .Nm snd_ai2s .Nd "Apple I2S audio 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 sound" .Cd "device snd_ai2s" .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 snd_ai2s_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for the Apple I2S audio controllers found predominantly in G4 and G5 machines, along with the snapper and tumbler codecs. Some machines (e.g. the Mac Mini) do not have configurable codecs and so lack hardware volume control. .Sh HARDWARE -.Pp Chips supported by the .Nm driver include: .Pp .Bl -bullet -compact .It Apple Tumbler Audio .It Apple Snapper Audio .El -.Pp .Sh SEE ALSO .Xr sound 4 , .Xr snd_davbus 4 .Sh HISTORY The .Nm device driver appeared in .Nx 2.0 and then in .Fx 8.0 . .Sh AUTHORS .An -nosplit The .Nm driver was written by .An Tsubai Masanari .Aq tsubai@netbsd.org , and ported to FreeBSD by .An Marco Trillo .Aq marcotrillo@gmail.com . .Sh BUGS Recording and operation with non-44.1 Khz audio are not currently supported. Index: stable/9/share/man/man4/man4.powerpc/snd_davbus.4 =================================================================== --- stable/9/share/man/man4/man4.powerpc/snd_davbus.4 (revision 290885) +++ stable/9/share/man/man4/man4.powerpc/snd_davbus.4 (revision 290886) @@ -1,83 +1,81 @@ .\"- .\" Copyright (c) 2009 Nathan Whitehorn .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE .\" DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN .\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd January 20, 2009 .Dt SND_DAVBUS 4 .Os .Sh NAME .Nm snd_davbus .Nd "Apple Davbus audio 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 sound" .Cd "device snd_davbus" .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 snd_davbus_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for the Apple Davbus audio controllers found in many G3-era Apple machines. .Sh HARDWARE -.Pp Chips supported by the .Nm driver include: .Pp .Bl -bullet -compact .It Apple Burgundy Audio .It Apple Screamer Audio .El -.Pp .Sh SEE ALSO .Xr sound 4 , .Xr snd_ai2s 4 .Sh HISTORY The .Nm device driver appeared in .Fx 8.0 . .Sh AUTHORS .An -nosplit The .Nm driver was written by .An Marco Trillo .Aq marcotrillo@gmail.com . .Sh BUGS Recording is not currently supported. Index: stable/9/share/man/man4/netmap.4 =================================================================== --- stable/9/share/man/man4/netmap.4 (revision 290885) +++ stable/9/share/man/man4/netmap.4 (revision 290886) @@ -1,1075 +1,1073 @@ .\" 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. .Pp .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. .Pp .Sh ENTERING AND EXITING NETMAP MODE The following section describes the system calls to create and control .Nm netmap ports (including .Nm VALE and .Nm netmap pipe ports). Simpler, higher level functions are described in 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. -.Pp .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. .Pp .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 .Pp .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_NIC "netmap:foo^" the ``host rings'', connecting to the host stack. .It NR_RING_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_SYNC 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_SYNC flag to .Em NIOCREGIF disables this feature. By default, receive rings are processed only if read events are requested. Passing the NETMAP_DO_RX_SYNC flag to .Em NIOCREGIF updates receive rings even without read events. Note that on epoll and kqueue, NETMAP_NO_TX_SYNC and NETMAP_DO_RX_SYNC 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 .Pp .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. .Pp .Sh SEE ALSO .Pp 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: stable/9/share/man/man4/ng_netflow.4 =================================================================== --- stable/9/share/man/man4/ng_netflow.4 (revision 290885) +++ stable/9/share/man/man4/ng_netflow.4 (revision 290886) @@ -1,332 +1,331 @@ .\" Copyright (c) 2004-2005 Gleb Smirnoff .\" 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 Nov 2, 2012 .Dt NG_NETFLOW 4 .Os .Sh NAME .Nm ng_netflow .Nd Cisco's NetFlow implementation .Sh SYNOPSIS .In sys/types.h .In netinet/in.h .In netgraph/netflow/ng_netflow.h .Sh DESCRIPTION The .Nm node implements Cisco's NetFlow export protocol on a router running .Fx . The .Nm node listens for incoming traffic and identifies unique flows in it. Flows are distinguished by endpoint IP addresses, TCP/UDP port numbers, ToS and input interface. Expired flows are exported out of the node in NetFlow version 5/9 UDP datagrams. Expiration reason can be one of the following: .Bl -dash .It RST or FIN TCP segment. .It Active timeout. Flows cannot live more than the specified period of time. The default is 1800 seconds (30 minutes). .It Inactive timeout. A flow was inactive for the specified period of time. The default is 15 seconds. .El .Pp Node supports IPv6 accounting (NetFlow v9 only) and is aware of multiple fibs. Different fibs are mapped to different domain_id in NetFlow V9 and different engine_id in NetFlow V5. -.Pp .Sh HOOKS This node type supports up to .Dv NG_NETFLOW_MAXIFACES (default 65536) hooks named .Va iface0 , iface1 , etc., and the same number of hooks named .Va out0 , out1 , etc., plus two export hooks: .Va export (for NetFlow version 5) and .Va export9 (for NetFlow version 9). Export can be done simultaneously for all supported export hooks. By default (ingress NetFlow enabled) node does NetFlow accounting of data received on .Va iface* hooks. If corresponding .Va out hook is connected, unmodified data is bypassed to it, otherwise data is freed. If data is received on .Va out hook, it is bypassed to corresponding .Va iface hook without any processing (egress NetFlow disabled by default). When full export datagram for an export protocol is built it is sent to the .Va export or .Va export9 hook. In normal operation, one (or more) export hook is connected to the .Va inet/dgram/udp hook of the .Xr ng_ksocket 4 node. .Sh CONTROL MESSAGES This node type supports the generic control messages, plus the following: .Bl -tag -width indent .It Dv NGM_NETFLOW_INFO Pq Ic info Returns some node statistics and the current timeout values in a .Vt "struct ng_netflow_info" . .It Dv NGM_NETFLOW_IFINFO Pq Ic ifinfo Returns information about the .Va iface Ns Ar N hook. The hook number is passed as an argument. .It Dv NGM_NETFLOW_SETDLT Pq Ic setdlt Sets data link type on the .Va iface Ns Ar N hook. Currently, supported types are raw IP datagrams and Ethernet. This message type uses .Vt "struct ng_netflow_setdlt" as an argument: .Bd -literal -offset 4n struct ng_netflow_setdlt { uint16_t iface; /* which iface dlt change */ uint8_t dlt; /* DLT_XXX from bpf.h */ }; .Ed .Pp The requested .Va iface Ns Ar N hook must already be connected, otherwise message send operation will return an error. .It Dv NGM_NETFLOW_SETIFINDEX Pq Ic setifindex In some cases, .Nm may be unable to determine the input interface index of a packet. This can happen if traffic enters the .Nm node before it comes to the system interface's input queue. An example of such a setup is capturing a traffic .Em between synchronous data line and .Xr ng_iface 4 . In this case, the input index should be associated with a given hook. The interface's index can be determined via .Xr if_nametoindex 3 from userland. This message requires .Vt "struct ng_netflow_setifindex" as an argument: .Bd -literal -offset 4n struct ng_netflow_setifindex { uint16_t iface; /* which iface index change */ uint16_t index; /* new index */ }; .Ed .Pp The requested .Va iface Ns Ar N hook must already be connected, otherwise the message send operation will return an error. .It Dv NGM_NETFLOW_SETTIMEOUTS Pq Ic settimeouts Sets values in seconds for NetFlow active/inactive timeouts. This message requires .Vt "struct ng_netflow_settimeouts" as an argument: .Bd -literal -offset 4n struct ng_netflow_settimeouts { uint32_t inactive_timeout; /* flow inactive timeout */ uint32_t active_timeout; /* flow active timeout */ }; .Ed .It Dv NGM_NETFLOW_SETCONFIG Pq Ic setconfig Sets configuration for the specified interface. This message requires .Vt "struct ng_netflow_setconfig" as an argument: .Bd -literal -offset 4n struct ng_netflow_setconfig { uint16_t iface; /* which iface config change */ uint32_t conf; /* new config */ #define NG_NETFLOW_CONF_INGRESS 1 #define NG_NETFLOW_CONF_EGRESS 2 #define NG_NETFLOW_CONF_ONCE 4 #define NG_NETFLOW_CONF_THISONCE 8 }; .Ed .Pp Configuration is a bitmask of several options. Option NG_NETFLOW_CONF_INGRESS enabled by default enables ingress NetFlow generation (for data coming from ifaceX hook). Option NG_NETFLOW_CONF_EGRESS enables egress NetFlow (for data coming from outX hook). Option NG_NETFLOW_CONF_ONCE defines that packet should be accounted only once if it several times passes via netflow node. Option NG_NETFLOW_CONF_THISONCE defines that packet should be accounted only once if it several times passes via exactly this netflow node. Last two options are important to avoid duplicate accounting when both ingress and egress NetFlow are enabled. .It Dv NGM_NETFLOW_SETTEMPLATE Pq Ic settemplate Sets various timeouts to announce data flow templates (NetFlow v9-specific). This message requires .Vt "struct ng_netflow_settemplate" as an argument: .Bd -literal -offset 4n struct ng_netflow_settemplate { uint16_t time; /* max time between announce */ uint16_t packets; /* max packets between announce */ }; .Ed .Pp Value of time field represents time in seconds to re-announce data templates. Value of packets field represents maximum packets count between re-announcing data templates. .It Dv NGM_NETFLOW_SETMTU Pq Ic setmtu Sets export interface MTU to build packets of specified size (NetFlow v9-specific). This message requires .Vt "struct ng_netflow_setmtu" as an argument: .Bd -literal -offset 4n struct ng_netflow_setemtu { uint16_t mtu; /* MTU for packet */ }; .Ed .Pp Default is 1500 bytes. .It Dv NGM_NETFLOW_SHOW This control message asks a node to dump the entire contents of the flow cache. It is called from .Xr flowctl 8 , not directly from .Xr ngctl 8 . See also .Sx BUGS section. .It Dv NGM_NETFLOW_V9INFO Pq Ic v9info Returns some NetFlow v9 related values in a .Bd -literal -offset 4n struct ng_netflow_v9info { uint16_t templ_packets; /* v9 template packets */ uint16_t templ_time; /* v9 template time */ uint16_t mtu; /* v9 MTU */ }; .Ed .El .Sh SHUTDOWN This node shuts down upon receipt of a .Dv NGM_SHUTDOWN control message, or when all hooks have been disconnected. .Sh EXAMPLES The simplest possible configuration is one Ethernet interface, where flow collecting is enabled. .Bd -literal -offset indent /usr/sbin/ngctl -f- <<-SEQ mkpeer fxp0: netflow lower iface0 name fxp0:lower netflow connect fxp0: netflow: upper out0 mkpeer netflow: ksocket export inet/dgram/udp msg netflow:export connect inet/10.0.0.1:4444 SEQ .Ed .Pp This is a more complicated example of a router with 2 NetFlow-enabled interfaces .Li fxp0 and .Li ng0 . Note that the .Va ng0: node in this example is connected to .Xr ng_tee 4 . The latter sends us a copy of IP packets, which we analyze and free. On .Va fxp0: we do not use tee, but send packets back to either node. .Bd -literal -offset indent /usr/sbin/ngctl -f- <<-SEQ # connect ng0's tee to iface0 hook mkpeer ng0:inet netflow right2left iface0 name ng0:inet.right2left netflow # set DLT to raw mode msg netflow: setdlt { iface=0 dlt=12 } # set interface index (5 in this example) msg netflow: setifindex { iface=0 index=5 } # Connect fxp0: to iface1 and out1 hook connect fxp0: netflow: lower iface1 connect fxp0: netflow: upper out1 # Create ksocket node on export hook, and configure it # to send exports to proper destination mkpeer netflow: ksocket export inet/dgram/udp msg netflow:export connect inet/10.0.0.1:4444 SEQ .Ed .Sh SEE ALSO .Xr netgraph 4 , .Xr setfib 2 , .Xr ng_ether 4 , .Xr ng_iface 4 , .Xr ng_ksocket 4 , .Xr ng_tee 4 , .Xr flowctl 8 , .Xr ngctl 8 .Rs .%A B. Claise, Ed .%T "Cisco Systems NetFlow Services Export Version 9" .%O RFC 3954 .Re .Pp .Pa http://www.cisco.com/en/US/docs/ios/solutions_docs/netflow/nfwhite.html .Sh AUTHORS .An -nosplit The .Nm node type was written by .An Gleb Smirnoff Aq glebius@FreeBSD.org , .An Alexander Motin Aq mav@FreeBSD.org , .An Alexander Chernikov Aq melifaro@ipfw.ru . The initial code was based on .Nm ng_ipacct written by .An Roman V. Palagin Aq romanp@unshadow.net . .Sh BUGS Cache snapshot obtained via .Dv NGM_NETFLOW_SHOW command may lack some percentage of entries under severe load. IPv6 flows are not shown. .Pp The .Nm node type does not fill in AS numbers. This is due to the lack of necessary information in the kernel routing table. However, this information can be injected into the kernel from a routing daemon such as GNU Zebra. This functionality may become available in future releases. Index: stable/9/share/man/man4/nvram2env.4 =================================================================== --- stable/9/share/man/man4/nvram2env.4 (revision 290885) +++ stable/9/share/man/man4/nvram2env.4 (revision 290886) @@ -1,119 +1,118 @@ .\" Copyright (c) 2011 Aleksandr Rybalko .\" 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 3, 2011 .Dt NVRAM2ENV 4 .Os .Sh NAME .Nm nvram2env .Nd "copy nvram-like data into kernel environment" .Sh SYNOPSIS .Cd "device nvram2env" .Sh DESCRIPTION .Nm implements a simple method of reading the NVRAM-like data and information stored in flash and storing it in the kernel environment. It can then be used by various device drivers at boot-time. .Pp The NVRAM-like data is an array of zero terminated strings. Each string contains the string name, "=" delimiter and the string value. .Pp .Nm copies the environment values into kernel environment using the kernel setenv call. .Pp Configuration of .Nm is done in .Xr device.hints 5 defining the NVRAM base address, fallback base address, maxsize and flags. .Pp .Nm is currently MIPS-specific. .Ss base base - physical address where data block is stored. .Ss fallbackbase fallbackbase - physical address where data block is stored, but only if not found at base. .Ss maxsize maxsize - maximum size of data block. .Ss flags flags - control flags, used to select nvram type and enable/disable CRC check. .Bl -tag -width indent .It Fa 0x0001 Avoid CRC checking. Currently CRC checking is not implemented, so to be future compatible, please set it to "1". .It Fa 0x0002 Use format "Generic", skip uint32_t field, then zero terminating array of strings. .It Fa 0x0004 Use Broadcom CFE format. uint32_t signature "FLSH", uint32_t size, three unused fields uint32_t, then data. .It Fa 0x0008 Use U-Boot format, uint32_t crc, then zero terminating array of strings. .El .Sh EXAMPLES Usage in U-Boot case: .Bd -literal -offset indent hint.nvram.0.base=0x1f030000 hint.nvram.0.maxsize=0x2000 hint.nvram.0.flags=3 # 1 = No check, 2 = Format Generic hint.nvram.1.base=0x1f032000 hint.nvram.1.maxsize=0x4000 hint.nvram.1.flags=3 # 1 = No check, 2 = Format Generic .Ed .Pp CFE nvram with fallback: .Bd -literal -offset indent hint.nvram.0.base=0x1fff8000 hint.nvram.0.fallbackbase=0x1fc00400 hint.nvram.0.flags=4 # 4 = Format Broadcom .Ed .Pp but seems for CFE nvram preferred to read both blocks: .Pp NVRAM partition: Static, CFE internal .Bd -literal -offset indent hint.nvram.0.flags=0x05 # Broadcom + nocheck hint.nvram.0.base=0x1fc00400 .Ed .Pp Dynamic, editable form CFE, override values from first -.Pp .Bd -literal -offset indent hint.nvram.1.flags=0x05 # Broadcom + nocheck hint.nvram.1.base=0x1cff8000 .Ed .Sh SEE ALSO .Xr kenv 1 , .Xr kenv 2 . .Sh HISTORY .Nm first appeared in .Fx 9.0 . .Sh AUTHORS .An -nosplit .Nm .An Aleksandr Rybalko Aq ray@ddteam.net . Index: stable/9/share/man/man4/oce.4 =================================================================== --- stable/9/share/man/man4/oce.4 (revision 290885) +++ stable/9/share/man/man4/oce.4 (revision 290886) @@ -1,136 +1,135 @@ .\" Copyright (C) 2013 Emulex .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions are met: .\" .\" 1. Redistributions of source code must retain the above copyright notice, .\" this list of conditions and the following disclaimer. .\" .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" 3. Neither the name of the Emulex Corporation nor the names of its .\" contributors may be used to endorse or promote products derived from .\" this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" .\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER 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. .\" .\" Contact Information: .\" freebsd-drivers@emulex.com .\" .\" Emulex .\" 3333 Susan Street .\" Costa Mesa, CA 92626 .\" .\" $FreeBSD$ .\" .Dd February 19, 2012 .Dt OCE 4 .Os .Sh NAME .Nm oce .Nd "Device driver for Emulex OneConnect 10Gb network adapters" .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 oce" .Ed .Pp Alternatively, to load the driver as a module at boot time, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent if_oce_load="YES" .Ed .Sh DESCRIPTION Emulex OneConnect adapters come in various skews and with different combinations of NIC, FCoE and iSCSI functions. The .Nm driver claims the NIC functions in all these adapters. .Pp The .Nm driver supports VLAN Hardware offload, TCP checksum offload, TCP segmentation offload (TSO), Large receive offload (LRO), Bonding, Jumbo frames (from 1500 - 9000), Multiple TX queues, Receive-Side Scaling (RSS) and MSI-X interrupts. .Sh HARDWARE The .Nm driver supports the following network adapters: .Pp .Bl -bullet -compact .It Emulex BladeEngine 2 .It Emulex BladeEngine 3 .It Emulex Lancer .El .Sh UPDATING FIRMWARE Adapter firmware updates are persistent. .Pp Firmware can be updated by following the steps below: .Bl -enum .It Copy the below code to a Makefile: -.Pp .Bd -literal -offset indent \&.KMOD=elxflash FIRMWS=imagename.ufi:elxflash \&.include .Ed .It Replace imagename in above with UFI file name .It Copy Makefile and UFI file to a directory .It Execute make & copy generated elxflash.ko to .Pa /lib/modules .It sysctl dev.oce..fw_upgrade=elxflash .It Reboot the machine .El .Pp In case of issues with supplied UFI, flashing fails with one of the following errors. .Pp .Bl -enum -compact .It .Qq Invalid BE3 firmware image .It .Qq "Invalid Cookie. Firmware image corrupted ?" .It .Qq cmd to write to flash rom failed. .El .Sh SUPPORT For general information and support, go to the Emulex website at: .Pa http://www.Emulex.com/ or E-Mail at .Pa freebsd-drivers@emulex.com . .Sh SEE ALSO .Xr ifconfig 8 .Sh AUTHORS .An -nosplit The .Nm driver was written by .An freebsd-drivers@emulex.com . Index: stable/9/share/man/man4/ppbus.4 =================================================================== --- stable/9/share/man/man4/ppbus.4 (revision 290885) +++ stable/9/share/man/man4/ppbus.4 (revision 290886) @@ -1,366 +1,363 @@ .\" Copyright (c) 1998, 1999 Nicolas Souchu .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd March 1, 1998 .Dt PPBUS 4 .Os .Sh NAME .Nm ppbus .Nd Parallel Port Bus system .Sh SYNOPSIS .Cd "device ppbus" .Pp .Cd "device vpo" .Pp .Cd "device lpt" .Cd "device plip" .Cd "device ppi" .Cd "device pps" .Cd "device lpbb" .Sh DESCRIPTION The .Em ppbus system provides a uniform, modular and architecture-independent system for the implementation of drivers to control various parallel devices, and to utilize different parallel port chipsets. .Sh DEVICE DRIVERS In order to write new drivers or port existing drivers, the ppbus system provides the following facilities: .Bl -bullet -offset indent .It architecture-independent macros or functions to access parallel ports .It mechanism to allow various devices to share the same parallel port .It a user interface named .Xr ppi 4 that allows parallel port access from outside the kernel without conflicting with kernel-in drivers. .El .Ss Developing new drivers -.Pp The ppbus system has been designed to support the development of standard and non-standard software: .Pp .Bl -column "Driver" -compact .It Em Driver Ta Em Description .It Sy vpo Ta "VPI0 parallel to Adaptec AIC-7110 SCSI controller driver" . It uses standard and non-standard parallel port accesses. .It Sy ppi Ta "Parallel port interface for general I/O" .It Sy pps Ta "Pulse per second Timing Interface" .It Sy lpbb Ta "Philips official parallel port I2C bit-banging interface" .El .Ss Porting existing drivers -.Pp Another approach to the ppbus system is to port existing drivers. Various drivers have already been ported: .Pp .Bl -column "Driver" -compact .It Em Driver Ta Em Description .It Sy lpt Ta "lpt printer driver" .It Sy plip Ta "lp parallel network interface driver" .El .Pp ppbus should let you port any other software even from other operating systems that provide similar services. .Sh PARALLEL PORT CHIPSETS Parallel port chipset support is provided by .Xr ppc 4 . .Pp The ppbus system provides functions and macros to allocate a new parallel port bus, then initialize it and upper peripheral device drivers. .Pp ppc makes chipset detection and initialization and then calls ppbus attach functions to initialize the ppbus system. .Sh PARALLEL PORT MODEL The logical parallel port model chosen for the ppbus system is the PC's parallel port model. Consequently, for the i386 implementation of ppbus, most of the services provided by ppc are macros for inb() and outb() calls. But, for an other architecture, accesses to one of our logical registers (data, status, control...) may require more than one I/O access. .Ss Description The parallel port may operate in the following modes: .Bl -bullet -offset indent .It compatible mode, also called Centronics mode .It bidirectional 8/4-bits mode, also called NIBBLE mode .It byte mode, also called PS/2 mode .It Extended Capability Port mode, ECP .It Enhanced Parallel Port mode, EPP .It mixed ECP+EPP or ECP+PS/2 modes .El .Ss Compatible mode This mode defines the protocol used by most PCs to transfer data to a printer. In this mode, data is placed on the port's data lines, the printer status is checked for no errors and that it is not busy, and then a data Strobe is generated by the software to clock the data to the printer. .Pp Many I/O controllers have implemented a mode that uses a FIFO buffer to transfer data with the Compatibility mode protocol. This mode is referred to as "Fast Centronics" or "Parallel Port FIFO mode". .Ss Bidirectional mode The NIBBLE mode is the most common way to get reverse channel data from a printer or peripheral. Combined with the standard host to printer mode, it provides a complete bidirectional channel. .Pp In this mode, outputs are 8-bits long. Inputs are accomplished by reading 4 of the 8 bits of the status register. .Ss Byte mode In this mode, the data register is used either for outputs and inputs. Then, any transfer is 8-bits long. .Ss Extended Capability Port mode The ECP protocol was proposed as an advanced mode for communication with printer and scanner type peripherals. Like the EPP protocol, ECP mode provides for a high performance bidirectional communication path between the host adapter and the peripheral. .Pp ECP protocol features include: .Bl -item -offset indent .It Run_Length_Encoding (RLE) data compression for host adapters .It FIFOs for both the forward and reverse channels .It DMA as well as programmed I/O for the host register interface. .El .Ss Enhanced Parallel Port mode The EPP protocol was originally developed as a means to provide a high performance parallel port link that would still be compatible with the standard parallel port. .Pp The EPP mode has two types of cycle: address and data. What makes the difference at hardware level is the strobe of the byte placed on the data lines. Data are strobed with nAutofeed, addresses are strobed with nSelectin signals. .Pp A particularity of the ISA implementation of the EPP protocol is that an EPP cycle fits in an ISA cycle. In this fashion, parallel port peripherals can operate at close to the same performance levels as an equivalent ISA plug-in card. .Pp At software level, you may implement the protocol you wish, using data and address cycles as you want. This is for the IEEE1284 compatible part. Then, peripheral vendors may implement protocol handshake with the following status lines: PError, nFault and Select. Try to know how these lines toggle with your peripheral, allowing the peripheral to request more data, stop the transfer and so on. .Pp At any time, the peripheral may interrupt the host with the nAck signal without disturbing the current transfer. .Ss Mixed modes Some manufacturers, like SMC, have implemented chipsets that support mixed modes. With such chipsets, mode switching is available at any time by accessing the extended control register. .Sh IEEE1284-1994 Standard .Ss Background This standard is also named "IEEE Standard Signaling Method for a Bidirectional Parallel Peripheral Interface for Personal Computers". It defines a signaling method for asynchronous, fully interlocked, bidirectional parallel communications between hosts and printers or other peripherals. It also specifies a format for a peripheral identification string and a method of returning this string to the host outside of the bidirectional data stream. .Pp This standard is architecture independent and only specifies dialog handshake at signal level. One should refer to architecture specific documentation in order to manipulate machine dependent registers, mapped memory or other methods to control these signals. .Pp The IEEE1284 protocol is fully oriented with all supported parallel port modes. The computer acts as master and the peripheral as slave. .Pp Any transfer is defined as a finite state automaton. It allows software to properly manage the fully interlocked scheme of the signaling method. The compatible mode is supported "as is" without any negotiation because it is compatible. Any other mode must be firstly negotiated by the host to check it is supported by the peripheral, then to enter one of the forward idle states. .Pp At any time, the slave may want to send data to the host. This is only possible from forward idle states (nibble, byte, ecp...). So, the host must have previously negotiated to permit the peripheral to request transfer. Interrupt lines may be dedicated to the requesting signals to prevent time consuming polling methods. .Pp But peripheral requests are only a hint to the master host. If the host accepts the transfer, it must firstly negotiate the reverse mode and then starts the transfer. At any time during reverse transfer, the host may terminate the transfer or the slave may drive wires to signal that no more data is available. .Ss Implementation IEEE1284 Standard support has been implemented at the top of the ppbus system as a set of procedures that perform high level functions like negotiation, termination, transfer in any mode without bothering you with low level characteristics of the standard. .Pp IEEE1284 interacts with the ppbus system as little as possible. That means you still have to request the ppbus when you want to access it, the negotiate function does not do it for you. And of course, release it later. .Sh ARCHITECTURE .Ss adapter, ppbus and device layers First, there is the .Em adapter layer, the lowest of the ppbus system. It provides chipset abstraction throw a set of low level functions that maps the logical model to the underlying hardware. .Pp Secondly, there is the .Em ppbus layer that provides functions to: .Bl -enum -offset indent .It share the parallel port bus among the daisy-chain like connected devices .It manage devices linked to ppbus .It propose an arch-independent interface to access the hardware layer. .El .Pp Finally, the .Em device layer gathers the parallel peripheral device drivers. -.Pp .Ss Parallel modes management We have to differentiate operating modes at various ppbus system layers. Actually, ppbus and adapter operating modes on one hands and for each one, current and available modes are separated. .Pp With this level of abstraction a particular chipset may commute from any native mode to any other mode emulated with extended modes without disturbing upper layers. For example, most chipsets support NIBBLE mode as native and emulated with ECP and/or EPP. .Pp This architecture should support IEEE1284-1994 modes. .Sh FEATURES .Ss The boot process The boot process starts with the probe stage of the .Xr ppc 4 driver during ISA bus (PC architecture) initialization. During attachment of the ppc driver, a new ppbus structure is allocated, then probe and attachment for this new bus node are called. .Pp ppbus attachment tries to detect any PnP parallel peripheral (according to .%T "Plug and Play Parallel Port Devices" draft from (c)1993-4 Microsoft Corporation) then probes and attaches known device drivers. .Pp During probe, device drivers are supposed to request the ppbus and try to set their operating mode. This mode will be saved in the context structure and returned each time the driver requests the ppbus. .Ss Bus allocation and interrupts ppbus allocation is mandatory not to corrupt I/O of other devices. Another usage of ppbus allocation is to reserve the port and receive incoming interrupts. .Pp High level interrupt handlers are connected to the ppbus system thanks to the newbus .Fn BUS_SETUP_INTR and .Fn BUS_TEARDOWN_INTR functions. But, in order to attach a handler, drivers must own the bus. Consequently, a ppbus request is mandatory in order to call the above functions (see existing drivers for more info). Note that the interrupt handler is automatically released when the ppbus is released. .Ss Microsequences .Em Microsequences is a general purpose mechanism to allow fast low-level manipulation of the parallel port. Microsequences may be used to do either standard (in IEEE1284 modes) or non-standard transfers. The philosophy of microsequences is to avoid the overhead of the ppbus layer and do most of the job at adapter level. .Pp A microsequence is an array of opcodes and parameters. Each opcode codes an operation (opcodes are described in .Xr microseq 9 ) . Standard I/O operations are implemented at ppbus level whereas basic I/O operations and microseq language are coded at adapter level for efficiency. .Pp As an example, the .Xr vpo 4 driver uses microsequences to implement: .Bl -bullet -offset indent .It a modified version of the NIBBLE transfer mode .It various I/O sequences to initialize, select and allocate the peripheral .El .Sh SEE ALSO .Xr lpt 4 , .Xr plip 4 , .Xr ppc 4 , .Xr ppi 4 , .Xr vpo 4 .Sh HISTORY The .Nm manual page first appeared in .Fx 3.0 . .Sh AUTHORS This manual page was written by .An Nicolas Souchu . Index: stable/9/share/man/man4/snd_emu10kx.4 =================================================================== --- stable/9/share/man/man4/snd_emu10kx.4 (revision 290885) +++ stable/9/share/man/man4/snd_emu10kx.4 (revision 290886) @@ -1,298 +1,296 @@ .\" .\" Copyright (c) 2003-2007 Yuriy Tsibizov .\" 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 28, 2008 .Dt SND_EMU10KX 4 .Os .Sh NAME .Nm snd_emu10kx .Nd Creative SoundBlaster Live! and Audigy sound cards 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 sound" .Cd "device snd_emu10kx" .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 snd_emu10kx_load="YES" .Ed .Sh DESCRIPTION The .Nm bridge driver allows the generic audio driver .Xr sound 4 to attach to Creative sound cards based on the EMU10K1, CA0100, CA0101, CA0102 and CA0108 DSPs. .Pp The .Nm sound cards have a PCM part, which is accessible through one to five .Xr pcm 4 devices (see .Sx MULTICHANNEL PLAYBACK for details), and MPU401-compatible MIDI I/O controller, which is accessible through the midi device. Wave table synthesizer support is not available. .Sh HARDWARE The .Nm driver supports the following sound cards: .Pp .Bl -bullet -compact .It Creative Sound Blaster Live!\& (EMU10K1 Chipset). Both PCM and MIDI interfaces are available. .It Creative Sound Blaster Audigy (CA0100 and CA0101 Chipset). PCM and two MIDI interfaces available. .It Creative Sound Blaster Audigy 2 and Creative Sound Blaster Audigy 4 (CA0102 Chipset). PCM support is limited to 48kHz/16 bit stereo (192kHz/24 bit part of this chipset is not supported). .It Creative Sound Blaster Audigy 2 Value (CA0108 Chipset). PCM support is limited to 48kHz/16 bit stereo (192kHz/24 bit part of this chipset is not supported). There is no MIDI support for this card. .El .Pp The .Nm driver does .Em not support the following sound cards (although they have names similar to some supported ones): .Pp .Bl -bullet -compact .It Creative Sound Blaster Live!\& 24-Bit, identified by .Fx as .Qq Li "emu10k1x Soundblaster Live! 5.1" . .It Creative Sound Blaster Audigy LS / ES, identified by .Fx as .Qq Li "CA0106-DAT Audigy LS" . .It All other Creative sound cards with -DAT chipsets. .It All Creative X-Fi series sound cards. .El .Sh MULTICHANNEL PLAYBACK By default the .Nm driver is loaded with multichannel playback capabilities enabled. If you do not set the .Dv hint.emu10kx.0.multichannel_disabled option in your .Xr loader.conf 5 configuration file you will get up to five DSP devices, one for each sound card output. You can use additional software (like .Em audio/pulseaudio from .Em The Ports Collection ) to do sound stream demultiplexing. Only .Dq FRONT output can play and record sound from external sources (like line or S/PDIF inputs). .Sh MULTICHANNEL RECORDING By default multichannel recording capabilities are not enabled when you load the .Nm driver. If you enable the .Dv hint.emu10kx.0.multichannel_recording option in .Xr loader.conf 5 you will get one more DSP device that is rate-locked to 48kHz/16bit/mono. This is actually 48kHz/16bit/32 channels on SB Live! cards and 48kHz/16bit/64channels on Audigy cards, but the current implementation of the sound subsystem does not support such an amount of PCM channels. This device can not be opened for read, thus confusing many applications. .Pp Within a multichannel stream, the first half (0-15 or 0-31) is a copy of all DSP outputs, the second half (15-30 or 32-63) is a copy of some DSP inputs. On Live! cards the last substream (31) is used as a sync stream and is always set to 0xc0de. Audigy cards do not need such sync data, because a stream always starts with substream 0. .Ss SB Live! substream map (in byte offsets, each substream is 2 bytes LE) .Bl -tag -width ".Dv +0x00..+0x1E" .It Dv Offset Substream .It +0x00..+0x1E PCM streams 0..15 .It +0x20, +0x22 Empty .It +0x24..+0x2A PCM inputs: front left, front right, rear left, rear right, center, sub .It +0x2C..+0x3C DSP inputs 0..8: .It +0x3E sync substream (0xc0de) .El -.Pp .Ss Audigy substream map (in byte offsets, each substream is 2 bytes LE) .Bl -tag -width ".Dv +0x00..+0x3E" .It Dv Offset Substream .It +0x00..+0x3E PCM streams 0..31 .It +0x40..+0x5E PCM inputs: front LR, rear LR, center, sub, ... .It +0x60..+0x7E DSP inputs 0..16 .El .Sh OSS MIXER CONTROLS These are the controls available through the standard OSS programming interface. You can use .Xr mixer 8 to change them. .Pp On EMU10K1-based cards the OSS mixer directly controls the AC97 codec. On newer cards the OSS mixer controls some parameters of the AC97 codec and some DSP-based mixer controls. .Bl -inset .It Qq vol mixer control for the overall sound volume. .It Qq pcm mixer control for the PCM playback volume. It controls only front output volume in multichannel mode and all output volume in single channel mode. .It Qq rec mixer control acts very differently on EMU10K1 and other cards. On EMU10K1 cards it controls the AC97 codec recording level. On non-EMU10K1 cards it controls the amount of AC97 .Dq stereo mix entering the DSP. AC97 recording level and AC97 recording source are fixed on CA0100, CA0101, CA0102 and CA0108 cards. The AC97 recording levels are always set to maximum and recording source is always .Dq Li "stereo mix" . .It Qq dig1 is a CD S/PDIF (on-card) volume control .It Qq dig2 is an AudigyDrive S/PDIF (Audigy series) or TOSLink (SB Live! series) volume control .It Qq dig3 is an on-card S/PDIF volume control .It Qq line2 is AudigyDrive "Line In 2" volume control .It Qq line3 is AudigyDrive "AUX In 2" volume control .El .Pp Other OSS mixer controls control the inputs of the AC97 codec. .Sh PRIVATE DEVICE CONTROLS You can control some of EMU10Kx's operation and configuration parameters through .Va dev.emu10kx. Ns Aq Ar X sysctls. These .Xr sysctl 8 values are temporary and should not be relied upon. .Sh DRIVER CONFIGURATION Loader tunables are used to set driver configuration. Tunables can be set at the .Xr loader 8 prompt before booting the kernel or they can be stored in .Pa /boot/loader.conf . These tunables cannot be changed from a machine .Xr sysctl 8 entry after boot, but you can change them using .Xr kenv 1 before loading the .Nm driver. .Bl -tag -width indent .It Va hint.emu10kx. Ns Ao Ar X Ac Ns Va .disabled Disables loading a driver instance. .It Va hint.emu10kx. Ns Ao Ar X Ac Ns Va .multichannel_disabled Disables multichannel playback support, when one card is represented as several PCM devices. .It Va hint.emu10kx. Ns Ao Ar X Ac Ns Va .multichannel_recording Enables experimental multichannel recording support. .It Va hint.emu10kx. Ns Ao Ar X Ac Ns Va .debug Set debug output level. .Bl -tag -width 2n .It 0 No additional debug options enabled .It 1 Enables all DSP outputs to be connected, even those that are known to be unused on a particular card. .It 2 Additional debug messages about in-driver events will be printed. .It 2 Additional debug messages will be printed when memory allocation fails. .El .El .Sh FILES .Bl -tag -width ".Pa /dev/emu10kx?" -compact .It Pa /dev/emu10kx? .Nm management interface .El .Sh SEE ALSO .Xr sound 4 .Sh HISTORY The .Nm device driver first appeared in .Fx 7.0 . .Sh AUTHORS .An -nosplit The PCM part of the driver is based on the .Xr snd_emu10k1 4 SB Live!\& driver by .An Cameron Grant Aq cg@FreeBSD.org . The MIDI interface is based on the .Xr snd_emu10k1 4 MIDI interface code by .An Mathew Kanner Aq matk@FreeBSD.org . The .Nm device driver and this manual page were written by .An Yuriy Tsibizov . .Sh BUGS -.Pp The driver does not detect lost S/PDIF signals and produces noise when S/PDIF is not connected and S/PDIF volume is not zero. .Pp The PCM driver cannot detect the presence of Live!Drive or AudigyDrive breakout boxes and tries to use them (and list their connectors in the mixer). .Pp The MIDI driver cannot detect the presence of Live!Drive or AudigyDrive breakout boxes and tries to enable the IR receiver on them anyway. Index: stable/9/share/man/man4/snd_hda.4 =================================================================== --- stable/9/share/man/man4/snd_hda.4 (revision 290885) +++ stable/9/share/man/man4/snd_hda.4 (revision 290886) @@ -1,638 +1,635 @@ .\" Copyright (c) 2006-2008 Joel Dahl .\" Copyright (c) 2008 Alexander Motin .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd January 25, 2012 .Dt SND_HDA 4 .Os .Sh NAME .Nm snd_hda .Nd "Intel High Definition Audio bridge 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 sound" .Cd "device snd_hda" .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 snd_hda_load="YES" .Ed .Sh DESCRIPTION The High Definition (HD) Audio specification was developed by Intel as the logical successor of the old AC'97 specification and has several advantages, such as higher bandwidth which allows more channels and more detailed formats, support for several logical audio devices, and general purpose DMA channels. .Pp The .Nm driver includes HDA bus controller driver (hdac), HDA codec driver (hdacc) and HDA codecs audio functions bridge driver (hdaa) that allows the generic audio driver, .Xr sound 4 , to be used with this hardware. Only audio functions are supported by .Nm . Modem and other possible functions are not implemented. .Pp The .Nm driver supports hardware that conforms with revision 1.0 of the Intel High Definition Audio specification and tries to behave much like the Microsoft Universal Audio Architecture (UAA) draft (revision 0.7b) for handling audio devices. .Pp According to HDA and UAA specifications, depending on the number of HDA buses and codecs present in system, their audio capabilities and BIOS provided configuration, the .Nm driver often provides several PCM audio devices. For example, one device for main rear 7.1 output and inputs, one device for independent headset connectors at front and one device for SPDIF or HDMI audio input/output. The assignment of audio inputs and outputs may be tuned with .Xr device.hints 5 or .Xr sysctl 8 . The driver's verbose boot messages provide a lot of information about the operation of the driver and present audio setup. .Pp The default audio device may be tuned by setting the .Ar hw.snd.default_unit sysctl, as described in .Xr sound 4 , or explicitly specified in application settings. .Ss Boot-time Configuration The following variables are available at boot-time through the .Xr device.hints 5 file: .Bl -tag -width ".Va hint.hdac.%d.config"-offset indent .It Va hint.hdac.%d.config Configures a range of possible controller options. Possible values are: .Dq Li 64bit , .Dq Li dmapos , .Dq Li msi . An option prefixed with .Dq Li no , such as .Dq Li nomsi , will do the opposite and takes precedence. Options can be separated by whitespace and commas. .It Va hint.hdac.%d.msi Controls MSI (Message Signaled Interrupts) support. .It Va hint.hdac.%d.cad%d.nid%d.config Same as .Va hint.hdaa.%d.nid%d.config .It Va hint.hdaa.%d.config Configures a range of possible audio function options. Possible values are: .Dq Li eapdinv , .Dq Li ivref , .Dq Li ivref50 , .Dq Li ivref80 , .Dq Li ivref100 , .Dq Li fixedrate , .Dq Li forcestereo , .Dq Li ovref , .Dq Li ovref50 , .Dq Li ovref80 , .Dq Li ovref100 , .Dq Li senseinv , .Dq Li softpcmvol , and .Dq Li vref . An option prefixed with .Dq Li no , such as .Dq Li nofixedrate , will do the opposite and takes precedence. Options can be separated by whitespace and commas. .Pp The .Dq Li eapdinv option inverts External Amplifier Power Down signal. The .Dq Li fixedrate denies all sampling rates except 48KHz. The .Dq Li forcestereo denies mono playback/recording. The .Dq Li senseinv option inverts jack sensing logic. The .Dq Li ivref Ns Ar X and .Dq Li ovref Ns Ar X options control the voltage used to power external microphones. .It Va hint.hdaa.%d.gpio_config Overrides audio function GPIO pins configuration set by BIOS. May be specified as a set of space-separated .Dq Ar num Ns = Ns Ar value pairs, where .Ar num is GPIO line number, and .Ar value is one of: .Dq Li keep , .Dq Li set , .Dq Li clear , .Dq Li disable and .Dq Li input . .Pp .Dq Li GPIO Ns s are a codec's General Purpose I/O pins which system integrators sometimes use to control external muters, amplifiers and so on. If you have no sound, or sound volume is not adequate, you may have to experiment a bit with the GPIO setup to find the optimal setup for your system. .It Va hint.hdaa.%d.nid%d.config Overrides audio function pin configuration set by BIOS. May be specified as a 32-bit hexadecimal value with a leading .Dq 0x , or as a set of space-separated .Dq Ar option Ns = Ns Ar value pairs. .It Va hint.pcm.%d.rec.autosrc Controls automatic recording source feature: .Bl -tag -compact .It 0 disabled, .It 1 once on attach, .It 2 enabled. .El When enabled, driver will automatically set recording source of the mixer to connected input using jack presence detection statuses. .El .Pp Pin configuration is the UAA driver's main source of information about codec usage. This information is usually provided by the codec manufacturer and tuned by system integrators for specific system requirements. The .Nm driver allows users to override it to fix integrator mistakes or to use the available codec in alternative ways (for example to get stereo output and 2 inputs instead of a single 5.1 output). .Pp The following options are supported: .Bl -tag -width ".Va device=" -offset indent .It Va as Association number. Associations are used to group individual pins to form a complex multi-pin device. For example, to group 4 connectors for 7.1 input/output, or to treat several input connectors as sources for the same input device. Association numbers can be specified as numeric values from 0 to 15. A value of 0 means disabled pin. A value of 15 is a set of independent unassociated pins. Each association includes only pins of the same direction (in/out) and is detected atomically (all pins or none). A separate PCM audio device is created for every pair of input and output associations. .It Va seq Sequence number. A unique, per-association number used to order pins inside the particular association. Sequence numbers can be specified as numeric values from 0 to 15. .Pp The sequence number 15 has a special meaning for output associations. Output pins with this number and device type .Dq Ar Headphones will duplicate (with automatic mute if jack detection is supported) the first pin in that association. .Pp The sequence numbers 14 and 15 has a special meaning for input associations. Their presence in association defines it as multiplexed or mixed respectively. If none of them are present and there are more than one pin in association, the association will provide multichannel input. .Pp For multichannel input/output associations sequence numbers encode channel pairs positions: 0 - Front, 1 - Center/LFE, 2 - Back, 3 - Front Wide Center, 4 - Side. Standard combinations are: (0) - Stereo; (0, 2), (0, 4) - Quadro; (0, 1, 2), (0, 1, 4) - 5.1; (0, 1, 2, 4) - 7.1. .It Va device Device type. Can be specified as a number from 0 to 15 or as a name: .Dq Li Line-out , .Dq Li Speaker , .Dq Li Headphones, .Dq Li CD , .Dq Li SPDIF-out , .Dq Li Digital-out , .Dq Li Modem-line , .Dq Li Modem-handset , .Dq Li Line-in , .Dq Li AUX , .Dq Li Mic , .Dq Li Telephony , .Dq Li SPDIF-in , .Dq Li Digital-in , .Dq Li Res.E , or .Dq Li Other . The device type also describes the pin direction (in/out). For example, .Dq Li CD always means an input pin, while .Dq Li Headphones always means an output. .It Va conn Connection type. Can be specified as a number from 0 to 3. The connection type can also be specified as one of the special names .Dq Li Jack , .Dq Li None , .Dq Li Fixed , or .Dq Li Both . Pins with a connection type of .Dq Li None are disabled. .It Va ctype Connector physical type. Can be specified as a number from 0 to 15. This is a reference only value. It is ignored by the .Nm driver. .It Va color Connector color. Can be specified as a number from 0 to 15 or as one of the names .Dq Li Unknown , .Dq Li Black , .Dq Li Grey , .Dq Li Blue , .Dq Li Green , .Dq Li Red , .Dq Li Orange , .Dq Li Yellow , .Dq Li Purple , .Dq Li Pink , .Dq Li Res.A , .Dq Li Res.B , .Dq Li Res.C , .Dq Li Res.D , .Dq Li White , or .Dq Li Other . This is a reference only value. It is ignored by the .Nm driver. .It Va loc Connector physical location. Can be specified as a number from 0 to 63. This is a reference only value. It is ignored by the .Nm driver. .It Va misc Misc bits. Can be specified as a number from 0 to 15. Bit 0 has a special meaning. When set it means that jack detection is not implemented in hardware. .El .Ss Runtime Configuration The following .Xr sysctl 8 variables are available in addition to those available to all .Xr sound 4 devices: .Bl -tag -width ".Va dev.hdaa.%d.nid%d_original" -offset indent .It Va dev.hdac.%d.pindump Setting this to a non-zero value dumps the current pin configuration, main capabilities and jack sense status of all audio functions on the controller to console and syslog. .It Va dev.hdac.%d.polling Enables polling mode. In this mode the driver operates by querying the device state on timer ticks using .Xr callout 9 instead of interrupts. Polling is disabled by default. Do not enable it unless you are facing weird interrupt problems or if the device cannot generate interrupts at all. .It Va dev.hdaa.%d.config Run-time equivalent of the .Va hint.hdaa.%d.config tunable. .It Va dev.hdaa.%d.gpi_state Current state of GPI lines. .It Va dev.hdaa.%d.gpio_state Current state of GPIO lines. .It Va dev.hdaa.%d.gpio_config Run-time equivalent of the .Va hint.hdaa.%d.gpio.config tunable. .It Va dev.hdaa.%d.gpo_state Current state of GPO lines. .It Va dev.hdaa.%d.nid%d_config Run-time equivalent of the .Va hint.hdaa.%d.nid%d.config tunable. .It Va dev.hdaa.%d.nid%d_original Original pin configuration written by BIOS. .It Va dev.hdaa.%d.reconfig Setting this to a non-zero value makes driver to destroy existing pcm devices and process new pins configuration set via .Va dev.hdaa.%d.nid%d_config . .It Va dev.pcm.%d.play.32bit , dev.pcm.%d.rec.32bit HDA controller uses 32bit representation for all samples of more then 16 bits. These variables allow to specify how many bits of these 32 should be used by CODEC. Depending on codec capabilities, possible values are 20, 24 and 32 bit. The default value is 24. .It Va dev.pcm.%d.rec.autosrc Run-time equivalent of the .Va hint.pcm.%d.rec.autosrc tunable. .El .Sh EXAMPLES Taking HP Compaq DX2300 with Realtek ALC888 HDA codec for example. This system has two audio connectors on a front side, three audio connectors on a rear side and one internal speaker. According to verbose driver output and the codec datasheet, this codec has five stereo DACs and two stereo ADCs, all of them are routable to any codec pin (external connector). All codec pins are reversible (could be configured either as input or output). .Pp So high codec uniformity and flexibility allow driver to configure it in many different ways, depending on requested pins usage described by pins configuration. The driver reports such default pin configuration when verbose messages enabled: .Bd -literal hdaa0: nid 0x as seq device conn jack loc color misc hdaa0: 20 01014020 2 0 Line-out Jack 1/8 Rear Green 0 hdaa0: 21 99130110 1 0 Speaker Fixed ATAPI Onboard Unknown 1 hdaa0: 22 411111f0 15 0 Speaker None 1/8 Rear Black 1 DISA hdaa0: 23 411111f0 15 0 Speaker None 1/8 Rear Black 1 DISA hdaa0: 24 01a19830 3 0 Mic Jack 1/8 Rear Pink 8 hdaa0: 25 02a1983f 3 15 Mic Jack 1/8 Front Pink 8 hdaa0: 26 01813031 3 1 Line-in Jack 1/8 Rear Blue 0 hdaa0: 27 0221401f 1 15 Headphones Jack 1/8 Front Green 0 hdaa0: 28 411111f0 15 0 Speaker None 1/8 Rear Black 1 DISA hdaa0: 30 411111f0 15 0 Speaker None 1/8 Rear Black 1 DISA hdaa0: 31 411111f0 15 0 Speaker None 1/8 Rear Black 1 DISA .Ed .Pp Here we can see, that the nodes with ID (nid) 25 and 27 are front panel connectors (Jack, Front), nids 20, 24 and 26 are rear panel connectors (Jack, Rear) and nid 21 is a built-in speaker (Fixed, Onboard). Pins with nids 22, 23, 28, 30 and 31 will be disabled by driver due to "None" connectivity. So the pin count and description matches to connectors that we have. .Pp Using association (as) and sequence (seq) fields values pins are grouped into 3 associations: .Bd -literal hdaa0: Association 0 (1) out: hdaa0: Pin nid=21 seq=0 hdaa0: Pin nid=27 seq=15 hdaa0: Association 1 (2) out: hdaa0: Pin nid=20 seq=0 hdaa0: Association 2 (3) in: hdaa0: Pin nid=24 seq=0 hdaa0: Pin nid=26 seq=1 hdaa0: Pin nid=25 seq=15 .Ed .Pp Each .Xr pcm 4 device uses two associations: one for playback and one for recording. Associations processed and assigned to .Xr pcm 4 devices in increasing numerical order. In this case association #0 (1) will become .Li pcm0 device playback, using the internal speakers and .Ar Headphones jack with speaker automute on the headphones jack connection. Association #1 (2) will become .Li pcm1 playback, using the .Ar Line-out jack. Association #2 (3) will become .Li pcm0 recording, using the external microphones and the .Ar Line-in jack. .Pp The .Nm driver provides extensive verbose messages to diagnose its operation logic and describe its current codec configuration. .Pp Using .Xr device.hints 5 it is possible to modify the configuration of the existing pins, allowing a broad range of different audio setups. Here are a few examples of some setups possible for this particular hardware: .Ss Example 1 Setting the .Xr device.hints 5 options .Bd -literal hint.hdac.0.cad0.nid20.config="as=1" hint.hdac.0.cad0.nid21.config="as=2" .Ed .Pp will swap line-out and speaker functions. So the .Li pcm0 device will play to the line-out and headphones jacks. Line-out will be muted on the headphones jack connection. Recording on .Li pcm0 will go from two external microphones and line-in jacks. .Li pcm1 playback will go to the internal speaker. -.Pp .Ss Example 2 Setting the .Xr device.hints 5 options .Bd -literal hint.hdac.0.cad0.nid20.config="as=1 seq=15 device=Headphones" hint.hdac.0.cad0.nid27.config="as=2 seq=0" hint.hdac.0.cad0.nid25.config="as=4 seq=0" .Ed .Pp will split the headphones and one of the microphones to a separate device. The .Li pcm0 device will play to the internal speaker and to the line-out jack, with speaker automute on the line-out jack connection. Recording on .Li pcm0 will use input from one external microphone and the line-in jacks. The .Li pcm1 device will be completely dedicated to a headset (headphones and mic) connected to the front connectors. -.Pp .Ss Example 3 Setting the .Xr device.hints 5 options .Bd -literal hint.hdac.0.cad0.nid20.config="as=1 seq=0" hint.hdac.0.cad0.nid26.config="as=2 seq=0" hint.hdac.0.cad0.nid27.config="as=3 seq=0" hint.hdac.0.cad0.nid25.config="as=4 seq=0" hint.hdac.0.cad0.nid24.config="as=5 seq=0 device=Line-out" hint.hdac.0.cad0.nid21.config="as=6 seq=0" .Ed .Pp will give 4 independent devices: .Li pcm0 .Pq line-out and line-in , .Li pcm1 .Pq headphones and mic , .Li pcm2 .Pq additional line-out via retasked rear mic jack , and .Li pcm3 .Pq internal speaker . -.Pp .Ss Example 4 Setting the .Xr device.hints 5 options .Bd -literal hint.hdac.0.cad0.nid20.config="as=1 seq=0" hint.hdac.0.cad0.nid24.config="as=1 seq=1 device=Line-out" hint.hdac.0.cad0.nid26.config="as=1 seq=2 device=Line-out" hint.hdac.0.cad0.nid21.config="as=2 seq=0" .Ed .Pp will give 2 devices: .Li pcm0 for 5.1 playback via 3 rear connectors (line-out and retasked mic and line-in) and headset (headphones and mic) at front connectors. .Li pcm1 for internal speaker playback. On headphones connection rear connectors will be muted. .Sh MIXER CONTROLS Depending on codec configuration, these controls and signal sources could be reported to .Xr sound 4 : .Bl -tag -width ".Va speaker" -offset indent .It Va vol overall output level (volume) .It Va rec overall recording level .It Va igain input-to-output monitoring loopback level .It Va ogain external amplifier control .It Va pcm PCM playback .It Va mix input mix .It Va mic first external or second internal microphone input .It Va monitor first internal or second external microphone input .It Va line , Va line1 , Va line2, Va line3 analog (line) inputs .It Va dig1 , Va dig2 , Va dig3 digital (S/PDIF, HDMI or DisplayPort) inputs .It Va cd CD input .It Va speaker PC speaker input .It Va phin , Va phout , Va radio . Va video other random inputs .El .Pp Controls have different precision. Some could be just an on/off triggers. Most of controls use logarithmic scale. .Sh HARDWARE The .Nm driver supports controllers having PCI class 4 (multimedia) and subclass 3 (HDA), compatible with Intel HDA specification. .Pp The .Nm driver supports more than two hundred different controllers and CODECs. There is no sense to list all of them here, as in most cases specific CODEC configuration and wiring are more important then type of the CODEC itself. .Sh SEE ALSO .Xr sound 4 , .Xr snd_ich 4 , .Xr device.hints 5 , .Xr loader.conf 5 , .Xr sysctl 8 .Sh HISTORY The .Nm device driver first appeared in .Fx 6.3 . .Sh AUTHORS .An -nosplit The .Nm driver was written by .An Stephane E. Potvin Aq sepotvin@videotron.ca , .An Ariff Abdullah Aq ariff@FreeBSD.org and .An Alexander Motin Aq mav@FreeBSD.org . This manual page was written by .An Joel Dahl Aq joel@FreeBSD.org , .An Alexander Motin Aq mav@FreeBSD.org and .An Giorgos Keramidas Aq keramida@FreeBSD.org . .Sh BUGS Some Hardware/OEM vendors tend to screw up BIOS settings or use custom unusual CODEC wiring that create problems to the driver. This may result in missing pcm devices, or a state where the .Nm driver seems to attach and work, but no sound is played. Some cases can be solved by tuning .Pa loader.conf variables. But before trying to fix problem that way, make sure that there really is a problem and that the PCM audio device in use really corresponds to the expected audio connector. .Pp Some vendors use non-standardized General Purpose I/O (GPIO) pins of the codec to control external amplifiers. In some cases setting a combination of GPIO bits may be needed to make sound work on a specific device. .Pp HDMI and DisplayPort audio may also require support from video driver. Index: stable/9/share/man/man4/u3g.4 =================================================================== --- stable/9/share/man/man4/u3g.4 (revision 290885) +++ stable/9/share/man/man4/u3g.4 (revision 290886) @@ -1,124 +1,123 @@ .\" .\" Copyright (c) 2008 AnyWi Technologies .\" All rights reserved. .\" .\" This code is derived from uark.c .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" .\" $FreeBSD$ .\" .Dd November 26, 2013 .Dt U3G 4 .Os .Sh NAME .Nm u3g .Nd USB support for 3G datacards .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device u3g" .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 u3g_load="YES" .Ed .Pp If neither of the above is done, the driver will automatically be loaded by devd(8) when the device is connected. .Sh DESCRIPTION The .Nm driver provides support for the multiple USB-to-serial interfaces exposed by many 3G USB/PCCard modems. .Pp The device is accessed through the .Xr ucom 4 driver which makes it behave like a .Xr tty 4 . .Sh HARDWARE The .Nm driver supports the following adapters: .Pp .Bl -bullet -compact .It Option GT 3G Fusion, GT Fusion Quad, etc. (only 3G part, not WLAN) .It Option GT 3G, GT 3G Quad, etc. .It Vodafone Mobile Connect Card 3G .It Qualcomm Inc. CDMA MSM .It Huawei B190, E180v, E220 ('') .It Novatel U740, MC950D, X950D, etc. .It Sierra MC875U, MC8775U, etc. .El .Pp (See .Pa /sys/dev/usb/serial/u3g.c for the complete list of supported cards for each vendor mentioned above.) .Pp The supported 3G cards provide the necessary modem port for ppp, or mpd connections as well as extra ports (depending on the specific device) to provide other functions (additional command port, diagnostic port, SIM toolkit port). .Pp In some of these devices a mass storage device supported by the .Xr umass 4 driver is present which contains Windows and Mac OS X drivers. The device starts up in disk mode (TruInstall, ZeroCD, etc.) and requires additional commands to switch it to modem mode. If your device is not switching automatically, please try to add quirks. See .Xr usbconfig 8 and .Xr usb_quirk 4 . -.Pp .Sh SEE ALSO .Xr tty 4 , .Xr ucom 4 , .Xr usb 4 , .Xr usb_quirk 4 , .Xr devd 8 , .Xr usbconfig 8 .Sh HISTORY The .Nm driver appeared in .Fx 7.2 , is based on the .Xr uark 4 driver, and written by .An Andrea Guzzo Aq aguzzo@anywi.com in September 2008. .Sh AUTHORS The .Nm driver was written by .An Andrea Guzzo Aq aguzzo@anywi.com and .An Nick Hibma Aq n_hibma@FreeBSD.org . Hardware for testing was provided by AnyWi Technologies, Leiden, NL. .Sh BUGS The automatic mode switch from disk mode to modem mode does not work unless the driver is either built into the kernel or loaded before the device is connected. Index: stable/9/share/man/man4 =================================================================== --- stable/9/share/man/man4 (revision 290885) +++ stable/9/share/man/man4 (revision 290886) Property changes on: stable/9/share/man/man4 ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/share/man/man4:r233422 Index: stable/9/share/man/man7/mailaddr.7 =================================================================== --- stable/9/share/man/man7/mailaddr.7 (revision 290885) +++ stable/9/share/man/man7/mailaddr.7 (revision 290886) @@ -1,168 +1,162 @@ .\" Copyright (c) 1983, 1987, 1990, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)mailaddr.7 8.1 (Berkeley) 6/16/93 .\" $FreeBSD$ .\" .Dd June 16, 1993 .Dt MAILADDR 7 .Os .Sh NAME .Nm mailaddr .Nd mail addressing description .Sh DESCRIPTION Mail addresses are based on the Internet protocol listed at the end of this manual page. These addresses are in the general format .Pp .Dl user@domain .Pp where a domain is a hierarchical dot separated list of subdomains. For example, a valid address is: .Pp .Dl eric@CS.Berkeley.EDU .Pp Unlike some other forms of addressing, domains do not imply any routing. Thus, although this address is specified as an Internet address, it might travel by an alternate route if that were more convenient or efficient. For example, at Berkeley, the associated message would probably go directly to CS over the Ethernet rather than going via the Berkeley Internet gateway. .Ss Abbreviation. Under certain circumstances it may not be necessary to type the entire domain name. In general, anything following the first dot may be omitted if it is the same as the domain from which you are sending the message. For example, a user on ``calder.berkeley.edu'' could send to ``eric@CS'' without adding the ``berkeley.edu'' since it is the same on both sending and receiving hosts. .Ss Compatibility. -.Pp Certain old address formats are converted to the new format to provide compatibility with the previous mail system. In particular, .Pp .Dl user@host .Pp and .Dl user@host.domain .Pp are allowed; .Pp .Dl host.domain!user .Pp is converted to .Pp .Dl user@host.domain .Pp and .Pp .Dl host!user .Pp is converted to .Pp .Dl user@host.UUCP .Pp This is normally converted back to the ``host!user'' form before being sent on for compatibility with older UUCP hosts. -.Pp .Ss Case Distinctions. -.Pp Domain names (i.e., anything after the ``@'' sign) may be given in any mixture of upper and lower case with the exception of UUCP hostnames. Most hosts accept any combination of case in user names, with the notable exception of MULTICS sites. .Ss Route-addrs. -.Pp Under some circumstances it may be necessary to route a message through several hosts to get it to the final destination. Normally this routing is done automatically, but sometimes it is desirable to route the message manually. Addresses which show these relays are termed ``route-addrs.'' These use the syntax: .Pp .Dl <@hosta,@hostb:user@hostc> .Pp This specifies that the message should be sent to hosta, from there to hostb, and finally to hostc. This path is forced even if there is a more efficient path to hostc. .Pp Route-addrs occur frequently on return addresses, since these are generally augmented by the software at each host. It is generally possible to ignore all but the ``user@hostc'' part of the address to determine the actual sender. .Pp [Note: the route-addr syntax is officially deprecated in RFC 1123 and should not be used.] .Pp Many sites also support the ``percent hack'' for simplistic routing: .Pp .Dl user%hostc%hostb@hosta .Pp is routed as indicated in the previous example. .Ss Postmaster. -.Pp Every site is required to have a user or user alias designated ``postmaster'' to which problems with the mail system may be addressed. .Ss Other Networks. -.Pp Some other networks can be reached by giving the name of the network as the last component of the domain. .Em This is not a standard feature and may not be supported at all sites. For example, messages to CSNET or BITNET sites can often be sent to ``user@host.CSNET'' or ``user@host.BITNET'' respectively. .Sh SEE ALSO .Xr mail 1 , .Xr sendmail 8 .Rs .%A Crocker, D. H. .%T Standard for the Format of Arpa Internet Text Messages .%O RFC822 .Re .Sh HISTORY .Nm Mailaddr appeared in .Bx 4.2 . .Sh BUGS The RFC822 group syntax (``group:user1,user2,user3;'') is not supported except in the special case of ``group:;'' because of a conflict with old berknet-style addresses. .Pp Route-Address syntax is grotty. .Pp UUCP- and Internet-style addresses do not coexist politely. Index: stable/9/share/man/man7 =================================================================== --- stable/9/share/man/man7 (revision 290885) +++ stable/9/share/man/man7 (revision 290886) Property changes on: stable/9/share/man/man7 ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/share/man/man7:r233422 Index: stable/9/share/man/man9/DB_COMMAND.9 =================================================================== --- stable/9/share/man/man9/DB_COMMAND.9 (revision 290885) +++ stable/9/share/man/man9/DB_COMMAND.9 (revision 290886) @@ -1,111 +1,110 @@ .\"- .\" Copyright (c) 2008 Guillaume Ballet .\" 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 August 27, 2008 .Dt DB_COMMAND 9 .Os .Sh NAME .Nm DB_COMMAND , .Nm DB_SHOW_COMMAND , .Nm DB_SHOW_ALL_COMMAND .Nd Extends the ddb command set .Sh SYNOPSIS .In ddb/ddb.h .Fo DB_COMMAND .Fa command_name .Fa command_function .Fc .Fn DB_SHOW_COMMAND "command_name" "command_function" .Fn DB_SHOW_ALL_COMMAND "command_name" "command_function" .Sh DESCRIPTION -.Pp The .Fn DB_COMMAND macro adds .Fa command_name to the list of top-level commands. Invoking .Fa command_name from ddb will call .Fa command_function . .Pp The .Fn DB_SHOW_COMMAND and .Fn DB_SHOW_ALL_COMMAND are roughly equivalent to .Fn DB_COMMAND but in these cases, .Fa command_name is a sub-command of the ddb .Sy show command and .Sy show all command, respectively. .Pp The general command syntax: .Cm command Ns Op Li \&/ Ns Ar modifier .Ar address Ns Op Li , Ns Ar count , translates into the following parameters for .Fa command_function : .Bl -tag -width Fa -offset indent .It Fa addr The address passed to the command as an argument. .It Fa have_addr A boolean value that is true if the addr field is valid. .It Fa count The number of quad words starting at offset .Fa addr that the command must process. .It Fa modif A pointer to the string of modifiers. That is, a series of symbols used to pass some options to the command. For example, the .Sy examine command will display words in decimal form if it is passed the modifier "d". .El .Sh EXAMPLE In your module, the command is declared as: .Bd -literal DB_COMMAND(mycmd, my_cmd_func) { if (have_addr) db_printf("Calling my command with address %p\\n", addr); } .Ed .Pp Then, when in ddb: .Bd -literal .Bf Sy db> mycmd 0x1000 Calling my command with address 0x1000 db> .Ef .Ed .Sh "SEE ALSO" .Xr ddb 4 .Sh AUTHOR This manual page was written by .An Guillaume Ballet Aq gballet@gmail.com . Index: stable/9/share/man/man9/fail.9 =================================================================== --- stable/9/share/man/man9/fail.9 (revision 290885) +++ stable/9/share/man/man9/fail.9 (revision 290886) @@ -1,209 +1,208 @@ .\" .\" Copyright (c) 2009 Isilon Inc http://www.isilon.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(s), this list of conditions and the following disclaimer as .\" the first lines of this file unmodified other than the possible .\" addition of one or more copyright notices. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice(s), this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``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(S) 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 10, 2009 .Dt FAIL 9 .Os .Sh NAME .Nm KFAIL_POINT_CODE , .Nm KFAIL_POINT_RETURN , .Nm KFAIL_POINT_RETURN_VOID , .Nm KFAIL_POINT_ERROR , .Nm KFAIL_POINT_GOTO , .Nm fail_point , .Nm DEBUG_FP .Nd fail points .Sh SYNOPSIS .In sys/fail.h .Fn KFAIL_POINT_CODE "parent" "name" "code" .Fn KFAIL_POINT_RETURN "parent" "name" .Fn KFAIL_POINT_RETURN_VOID "parent" "name" .Fn KFAIL_POINT_ERROR "parent" "name" "error_var" .Fn KFAIL_POINT_GOTO "parent" "name" "error_var" "label" .Sh DESCRIPTION Fail points are used to add code points where errors may be injected in a user controlled fashion. Fail points provide a convenient wrapper around user-provided error injection code, providing a .Xr sysctl 9 MIB, and a parser for that MIB that describes how the error injection code should fire. .Pp The base fail point macro is .Fn KFAIL_POINT_CODE where .Fa parent is a sysctl tree (frequently .Sy DEBUG_FP for kernel fail points, but various subsystems may wish to provide their own fail point trees), and .Fa name is the name of the MIB in that tree, and .Fa code is the error injection code. The .Fa code argument does not require braces, but it is considered good style to use braces for any multi-line code arguments. Inside the .Fa code argument, the evaluation of .Sy RETURN_VALUE is derived from the .Fn return value set in the sysctl MIB. See .Sx SYSCTL VARIABLES below. .Pp The remaining .Fn KFAIL_POINT_* macros are wrappers around common error injection paths: .Bl -inset .It Fn KFAIL_POINT_RETURN parent name is the equivalent of .Sy KFAIL_POINT_CODE(..., return RETURN_VALUE) .It Fn KFAIL_POINT_RETURN_VOID parent name is the equivalent of .Sy KFAIL_POINT_CODE(..., return) .It Fn KFAIL_POINT_ERROR parent name error_var is the equivalent of .Sy KFAIL_POINT_CODE(..., error_var = RETURN_VALUE) .It Fn KFAIL_POINT_GOTO parent name error_var label is the equivalent of .Sy KFAIL_POINT_CODE(..., { error_var = RETURN_VALUE; goto label;}) .El .Sh SYSCTL VARIABLES The .Fn KFAIL_POINT_* macros add sysctl MIBs where specified. Many base kernel MIBs can be found in the .Sy debug.fail_point tree (referenced in code by .Sy DEBUG_FP ) . .Pp The sysctl variable may be set using the following grammar: .Bd -literal :: ( "->" )* :: ( ( "%") | ( "*" ) )* [ "(" ")" ] [ "[pid " "]" ] :: [ "." ] | "." :: "off" | "return" | "sleep" | "panic" | "break" | "print" .Ed .Pp The argument specifies which action to take: .Bl -tag -width ".Dv return" .It Sy off Take no action (does not trigger fail point code) .It Sy return Trigger fail point code with specified argument .It Sy sleep Sleep the specified number of milliseconds .It Sy panic Panic .It Sy break Break into the debugger, or trap if there is no debugger support .It Sy print Print that the fail point executed .El .Pp The % and * modifiers prior to control when is executed. The % form (e.g. "1.2%") can be used to specify a probability that will execute. The * form (e.g. "5*") can be used to specify the number of times should be executed before this is disabled. Only the last probability and the last count are used if multiple are specified, i.e. "1.2%2%" is the same as "2%". When both a probability and a count are specified, the probability is evaluated before the count, i.e. "2%5*" means "2% of the time, but only 5 times total". .Pp The operator -> can be used to express cascading terms. If you specify ->, it means that if does not .Ql execute , is evaluated. For the purpose of this operator, the return() and print() operators are the only types that cascade. A return() term only cascades if the code executes, and a print() term only cascades when passed a non-zero argument. A pid can optionally be specified. The fail point term is only executed when invoked by a process with a matching p_pid. -.Pp .Sh EXAMPLES .Bl -tag -width Sy .It Sy sysctl debug.fail_point.foobar="2.1%return(5)" 21/1000ths of the time, execute .Fa code with RETURN_VALUE set to 5. .It Sy sysctl debug.fail_point.foobar="2%return(5)->5%return(22)" 2/100ths of the time, execute .Fa code with RETURN_VALUE set to 5. If that does not happen, 5% of the time execute .Fa code with RETURN_VALUE set to 22. .It Sy sysctl debug.fail_point.foobar="5*return(5)->0.1%return(22)" For 5 times, return 5. After that, 1/1000th of the time, return 22. .It Sy sysctl debug.fail_point.foobar="0.1%5*return(5)" Return 5 for 1 in 1000 executions, but only 5 times total. .It Sy sysctl debug.fail_point.foobar="1%*sleep(50)" 1/100th of the time, sleep 50ms. .It Sy sysctl debug.fail_point.foobar="1*return(5)[pid 1234]" Return 5 once, when pid 1234 executes the fail point. .El .Sh AUTHORS .An -nosplit This manual page was written by .An Zach Loafman Aq zml@FreeBSD.org . .Sh CAVEATS It is easy to shoot yourself in the foot by setting fail points too aggressively or setting too many in combination. For example, forcing .Fn malloc to fail consistently is potentially harmful to uptime. .Pp The .Fn sleep sysctl setting may not be appropriate in all situations. Currently, .Fn fail_point_eval does not verify whether the context is appropriate for calling .Fn msleep . Index: stable/9/share/man/man9/lock.9 =================================================================== --- stable/9/share/man/man9/lock.9 (revision 290885) +++ stable/9/share/man/man9/lock.9 (revision 290886) @@ -1,401 +1,400 @@ .\" .\" Copyright (C) 2002 Chad David . 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(s), this list of conditions and the following disclaimer as .\" the first lines of this file unmodified other than the possible .\" addition of one or more copyright notices. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice(s), this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``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(S) 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 6, 2013 .Dt LOCK 9 .Os .Sh NAME .Nm lockinit , .Nm lockdestroy , .Nm lockmgr , .Nm lockmgr_args , .Nm lockmgr_args_rw , .Nm lockmgr_disown , .Nm lockmgr_printinfo , .Nm lockmgr_recursed , .Nm lockmgr_rw , .Nm lockmgr_waiters , .Nm lockstatus , .Nm lockmgr_assert .Nd "lockmgr family of functions" .Sh SYNOPSIS .In sys/types.h .In sys/lock.h .In sys/lockmgr.h .Ft void .Fn lockinit "struct lock *lkp" "int prio" "const char *wmesg" "int timo" "int flags" .Ft void .Fn lockdestroy "struct lock *lkp" .Ft int .Fn lockmgr "struct lock *lkp" "u_int flags" "struct mtx *ilk" .Ft int .Fn lockmgr_args "struct lock *lkp" "u_int flags" "struct mtx *ilk" "const char *wmesg" "int prio" "int timo" .Ft int .Fn lockmgr_args_rw "struct lock *lkp" "u_int flags" "struct rwlock *ilk" "const char *wmesg" "int prio" "int timo" .Ft void .Fn lockmgr_disown "struct lock *lkp" .Ft void .Fn lockmgr_printinfo "struct lock *lkp" .Ft int .Fn lockmgr_recursed "struct lock *lkp" .Ft int .Fn lockmgr_rw "struct lock *lkp" "u_int flags" "struct rwlock *ilk" .Ft int .Fn lockmgr_waiters "struct lock *lkp" .Ft int .Fn lockstatus "struct lock *lkp" .Pp .Cd "options INVARIANTS" .Cd "options INVARIANT_SUPPORT" .Ft void .Fn lockmgr_assert "struct lock *lkp" "int what" .Sh DESCRIPTION The .Fn lockinit function is used to initialize a lock. It must be called before any operation can be performed on a lock. Its arguments are: .Bl -tag -width ".Fa wmesg" .It Fa lkp A pointer to the lock to initialize. .It Fa prio The priority passed to .Xr sleep 9 . .It Fa wmesg The lock message. This is used for both debugging output and .Xr sleep 9 . .It Fa timo The timeout value passed to .Xr sleep 9 . .It Fa flags The flags the lock is to be initialized with: .Bl -tag -width ".Dv LK_CANRECURSE" .It Dv LK_ADAPTIVE Enable adaptive spinning for this lock if the kernel is compiled with the ADAPTIVE_LOCKMGRS option. .It Dv LK_CANRECURSE Allow recursive exclusive locks. .It Dv LK_NOPROFILE Disable lock profiling for this lock. .It Dv LK_NOSHARE Allow exclusive locks only. .It Dv LK_NOWITNESS Instruct .Xr witness 4 to ignore this lock. .It Dv LK_NODUP .Xr witness 4 should log messages about duplicate locks being acquired. .It Dv LK_QUIET Disable .Xr ktr 4 logging for this lock. .It Dv LK_TIMELOCK Use .Fa timo during a sleep; otherwise, 0 is used. .El .El .Pp The .Fn lockdestroy function is used to destroy a lock, and while it is called in a number of places in the kernel, it currently does nothing. .Pp The .Fn lockmgr and .Fn lockmgr_rw functions handle general locking functionality within the kernel, including support for shared and exclusive locks, and recursion. .Fn lockmgr and .Fn lockmgr_rw are also able to upgrade and downgrade locks. .Pp Their arguments are: .Bl -tag -width ".Fa flags" .It Fa lkp A pointer to the lock to manipulate. .It Fa flags Flags indicating what action is to be taken. .Bl -tag -width ".Dv LK_CANRECURSE" .It Dv LK_SHARED Acquire a shared lock. If an exclusive lock is currently held, .Dv EDEADLK will be returned. .It Dv LK_EXCLUSIVE Acquire an exclusive lock. If an exclusive lock is already held, and .Dv LK_CANRECURSE is not set, the system will .Xr panic 9 . .It Dv LK_DOWNGRADE Downgrade exclusive lock to a shared lock. Downgrading a shared lock is not permitted. If an exclusive lock has been recursed, the system will .Xr panic 9 . .It Dv LK_UPGRADE Upgrade a shared lock to an exclusive lock. If this call fails, the shared lock is lost, even if the .Dv LK_NOWAIT flag is specified. During the upgrade, the shared lock could be temporarily dropped. Attempts to upgrade an exclusive lock will cause a .Xr panic 9 . .It Dv LK_TRYUPGRADE Try to upgrade a shared lock to an exclusive lock. The failure to upgrade does not result in the dropping of the shared lock ownership. .It Dv LK_RELEASE Release the lock. Releasing a lock that is not held can cause a .Xr panic 9 . .It Dv LK_DRAIN Wait for all activity on the lock to end, then mark it decommissioned. This is used before freeing a lock that is part of a piece of memory that is about to be freed. (As documented in .In sys/lockmgr.h . ) .It Dv LK_SLEEPFAIL Fail if operation has slept. .It Dv LK_NOWAIT Do not allow the call to sleep. This can be used to test the lock. .It Dv LK_NOWITNESS Skip the .Xr witness 4 checks for this instance. .It Dv LK_CANRECURSE Allow recursion on an exclusive lock. For every lock there must be a release. .It Dv LK_INTERLOCK Unlock the interlock (which should be locked already). .El .It Fa ilk An interlock mutex for controlling group access to the lock. If .Dv LK_INTERLOCK is specified, .Fn lockmgr and .Fn lockmgr_rw assume .Fa ilk is currently owned and not recursed, and will return it unlocked. See .Xr mtx_assert 9 . .El .Pp The .Fn lockmgr_args and .Fn lockmgr_args_rw function work like .Fn lockmgr and .Fn lockmgr_rw but accepting a .Fa wmesg , .Fa timo and .Fa prio on a per-instance basis. The specified values will override the default ones, but this can still be used passing, respectively, .Dv LK_WMESG_DEFAULT , .Dv LK_PRIO_DEFAULT and .Dv LK_TIMO_DEFAULT . .Pp The .Fn lockmgr_disown function switches the owner from the current thread to be .Dv LK_KERNPROC , if the lock is already held. .Pp The .Fn lockmgr_printinfo function prints debugging information about the lock. It is used primarily by .Xr VOP_PRINT 9 functions. .Pp The .Fn lockmgr_recursed function returns true if the lock is recursed, 0 otherwise. .Pp The .Fn lockmgr_waiters function returns true if the lock has waiters, 0 otherwise. .Pp The .Fn lockstatus function returns the status of the lock in relation to the current thread. .Pp When compiled with .Cd "options INVARIANTS" and .Cd "options INVARIANT_SUPPORT" , the .Fn lockmgr_assert function tests .Fa lkp for the assertions specified in .Fa what , and panics if they are not met. One of the following assertions must be specified: .Bl -tag -width ".Dv KA_UNLOCKED" .It Dv KA_LOCKED Assert that the current thread has either a shared or an exclusive lock on the .Vt lkp lock pointed to by the first argument. .It Dv KA_SLOCKED Assert that the current thread has a shared lock on the .Vt lkp lock pointed to by the first argument. .It Dv KA_XLOCKED Assert that the current thread has an exclusive lock on the .Vt lkp lock pointed to by the first argument. .It Dv KA_UNLOCKED Assert that the current thread has no lock on the .Vt lkp lock pointed to by the first argument. .El .Pp In addition, one of the following optional assertions can be used with either an .Dv KA_LOCKED , .Dv KA_SLOCKED , or .Dv KA_XLOCKED assertion: .Bl -tag -width ".Dv KA_NOTRECURSED" .It Dv KA_RECURSED Assert that the current thread has a recursed lock on .Fa lkp . .It Dv KA_NOTRECURSED Assert that the current thread does not have a recursed lock on .Fa lkp . .El -.Pp .Sh RETURN VALUES The .Fn lockmgr and .Fn lockmgr_rw functions return 0 on success and non-zero on failure. .Pp The .Fn lockstatus function returns: .Bl -tag -width ".Dv LK_EXCLUSIVE" .It Dv LK_EXCLUSIVE An exclusive lock is held by the current thread. .It Dv LK_EXCLOTHER An exclusive lock is held by someone other than the current thread. .It Dv LK_SHARED A shared lock is held. .It Li 0 The lock is not held by anyone. .El .Sh ERRORS .Fn lockmgr and .Fn lockmgr_rw fail if: .Bl -tag -width Er .It Bq Er EBUSY .Dv LK_FORCEUPGRADE was requested and another thread had already requested a lock upgrade. .It Bq Er EBUSY .Dv LK_NOWAIT was set, and a sleep would have been required, or .Dv LK_TRYUPGRADE operation was not able to upgrade the lock. .It Bq Er ENOLCK .Dv LK_SLEEPFAIL was set and .Fn lockmgr or .Fn lockmgr_rw did sleep. .It Bq Er EINTR .Dv PCATCH was set in the lock priority, and a signal was delivered during a sleep. Note the .Er ERESTART error below. .It Bq Er ERESTART .Dv PCATCH was set in the lock priority, a signal was delivered during a sleep, and the system call is to be restarted. .It Bq Er EWOULDBLOCK a non-zero timeout was given, and the timeout expired. .El .Sh LOCKS If .Dv LK_INTERLOCK is passed in the .Fa flags argument to .Fn lockmgr or .Fn lockmgr_rw , the .Fa ilk must be held prior to calling .Fn lockmgr or .Fn lockmgr_rw , and will be returned unlocked. .Pp Upgrade attempts that fail result in the loss of the lock that is currently held. Also, it is invalid to upgrade an exclusive lock, and a .Xr panic 9 will be the result of trying. .Sh SEE ALSO .Xr condvar 9 , .Xr locking 9 , .Xr mutex 9 , .Xr rwlock 9 , .Xr sleep 9 , .Xr sx 9 , .Xr mtx_assert 9 , .Xr panic 9 , .Xr VOP_PRINT 9 .Sh AUTHORS This manual page was written by .An Chad David Aq davidc@acns.ab.ca . Index: stable/9/share/man/man9/make_dev.9 =================================================================== --- stable/9/share/man/man9/make_dev.9 (revision 290885) +++ stable/9/share/man/man9/make_dev.9 (revision 290886) @@ -1,402 +1,401 @@ .\" Copyright (c) 1999 Chris Costello .\" 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 3, 2011 .Dt MAKE_DEV 9 .Os .Sh NAME .Nm make_dev , .Nm make_dev_cred , .Nm make_dev_credf , .Nm make_dev_p , .Nm make_dev_alias , .Nm make_dev_alias_p , .Nm destroy_dev , .Nm destroy_dev_sched , .Nm destroy_dev_sched_cb , .Nm destroy_dev_drain , .Nm dev_depends .Nd manage .Vt cdev Ns 's and DEVFS registration for devices .Sh SYNOPSIS .In sys/param.h .In sys/conf.h .Ft struct cdev * .Fn make_dev "struct cdevsw *cdevsw" "int unit" "uid_t uid" "gid_t gid" "int perms" "const char *fmt" ... .Ft struct cdev * .Fn make_dev_cred "struct cdevsw *cdevsw" "int unit" "struct ucred *cr" "uid_t uid" "gid_t gid" "int perms" "const char *fmt" ... .Ft struct cdev * .Fn make_dev_credf "int flags" "struct cdevsw *cdevsw" "int unit" "struct ucred *cr" "uid_t uid" "gid_t gid" "int perms" "const char *fmt" ... .Ft int .Fn make_dev_p "int flags" "struct cdev **cdev" "struct cdevsw *devsw" "struct ucred *cr" "uid_t uid" "gid_t gid" "int mode" "const char *fmt" ... .Ft struct cdev * .Fn make_dev_alias "struct cdev *pdev" "const char *fmt" ... .Ft int .Fn make_dev_alias_p "int flags" "struct cdev **cdev" "struct cdev *pdev" "const char *fmt" ... .Ft void .Fn destroy_dev "struct cdev *dev" .Ft void .Fn destroy_dev_sched "struct cdev *dev" .Ft void .Fn destroy_dev_sched_cb "struct cdev *dev" "void (*cb)(void *)" "void *arg" .Ft void .Fn destroy_dev_drain "struct cdevsw *csw" .Ft void .Fn dev_depends "struct cdev *pdev" "struct cdev *cdev" .Sh DESCRIPTION The .Fn make_dev_credf function creates a .Fa cdev structure for a new device. It also notifies .Xr devfs 5 of the presence of the new device, that causes corresponding nodes to be created. Besides this, a .Xr devctl 4 notification is sent. The device will be owned by .Va uid , with the group ownership as .Va gid . The name is the expansion of .Va fmt and following arguments as .Xr printf 9 would print it. The name determines its path under .Pa /dev or other .Xr devfs 5 mount point and may contain slash .Ql / characters to denote subdirectories. The permissions of the file specified in .Va perms are defined in .In sys/stat.h : .Pp .Bd -literal -offset indent -compact #define S_IRWXU 0000700 /* RWX mask for owner */ #define S_IRUSR 0000400 /* R for owner */ #define S_IWUSR 0000200 /* W for owner */ #define S_IXUSR 0000100 /* X for owner */ #define S_IRWXG 0000070 /* RWX mask for group */ #define S_IRGRP 0000040 /* R for group */ #define S_IWGRP 0000020 /* W for group */ #define S_IXGRP 0000010 /* X for group */ #define S_IRWXO 0000007 /* RWX mask for other */ #define S_IROTH 0000004 /* R for other */ #define S_IWOTH 0000002 /* W for other */ #define S_IXOTH 0000001 /* X for other */ #define S_ISUID 0004000 /* set user id on execution */ #define S_ISGID 0002000 /* set group id on execution */ #define S_ISVTX 0001000 /* sticky bit */ #ifndef _POSIX_SOURCE #define S_ISTXT 0001000 #endif .Ed .Pp The .Va cr argument specifies credentials that will be stored in the .Fa si_cred member of the initialized .Fa struct cdev . The .Va flags argument alters the operation of .Fn make_dev_credf or .Fn make_dev_p . The following values are currently accepted: .Pp .Bl -tag -width "MAKEDEV_CHECKNAME" -compact -offset indent .It MAKEDEV_REF reference the created device .It MAKEDEV_NOWAIT do not sleep, the call may fail .It MAKEDEV_WAITOK allow the function to sleep to satisfy malloc .It MAKEDEV_ETERNAL created device will be never destroyed .It MAKEDEV_CHECKNAME return an error if the device name is invalid or already exists .El .Pp Only .Dv MAKEDEV_NOWAIT , .Dv MAKEDEV_WAITOK and .Dv MAKEDEV_CHECKNAME values are accepted for the .Fn make_dev_alias_p function. .Pp The .Dv MAKEDEV_WAITOK flag is assumed if none of .Dv MAKEDEV_WAITOK , .Dv MAKEDEV_NOWAIT is specified. .Pp The .Xr dev_clone 9 event handler shall specify .Dv MAKEDEV_REF flag when creating a device in response to lookup, to avoid race where the device created is destroyed immediately after .Xr devfs_lookup 9 drops his reference to cdev. .Pp The .Dv MAKEDEV_ETERNAL flag allows the kernel to not acquire some locks when translating system calls into the cdevsw methods calls. It is responsibility of the driver author to make sure that .Fn destroy_dev is never called on the returned cdev. For the convenience, use the .Dv MAKEDEV_ETERNAL_KLD flag for the code that can be compiled into kernel or loaded (and unloaded) as loadable module. .Pp A panic will occur if the MAKEDEV_CHECKNAME flag is not specified and the device name is invalid or already exists. .Pp The .Fn make_dev_cred function is equivalent to the call .Bd -literal -offset indent make_dev_credf(0, cdevsw, unit, cr, uid, gid, perms, fmt, ...); .Ed .Pp The .Fn make_dev function call is the same as .Bd -literal -offset indent make_dev_credf(0, cdevsw, unit, NULL, uid, gid, perms, fmt, ...); .Ed .Pp The .Fn make_dev_p function is similar to .Fn make_dev_credf but it may return an error number and takes a pointer to the resulting .Ft *cdev as an argument. .Pp The .Fn make_dev_alias function takes the returned .Ft cdev from .Fn make_dev and makes another (aliased) name for this device. It is an error to call .Fn make_dev_alias prior to calling .Fn make_dev . .Pp .Fn make_dev_alias_p function is similar to .Fn make_dev_alias but it takes a pointer to the resulting .Ft *cdev as an argument and may return an error. .Pp The .Fa cdev returned by .Fn make_dev and .Fn make_dev_alias has two fields, .Fa si_drv1 and .Fa si_drv2 , that are available to store state. Both fields are of type .Ft void * . These are designed to replace the .Fa unit argument to .Fn make_dev , which can be obtained with .Fn dev2unit . .Pp The .Fn destroy_dev function takes the returned .Fa cdev from .Fn make_dev and destroys the registration for that device. The notification is sent to .Xr devctl 4 about the destruction event. Do not call .Fn destroy_dev on devices that were created with .Fn make_dev_alias . .Pp The .Fn dev_depends function establishes a parent-child relationship between two devices. The net effect is that a .Fn destroy_dev of the parent device will also result in the destruction of the child device(s), if any exist. A device may simultaneously be a parent and a child, so it is possible to build a complete hierarchy. .Pp The .Fn destroy_dev_sched_cb function schedules execution of the .Fn destroy_dev for the specified .Fa cdev in the safe context. After .Fn destroy_dev is finished, and if the supplied .Fa cb is not .Dv NULL , the callback .Fa cb is called, with argument .Fa arg . The .Fn destroy_dev_sched function is the same as .Bd -literal -offset indent destroy_dev_sched_cb(cdev, NULL, NULL); .Ed .Pp The .Fn d_close driver method cannot call .Fn destroy_dev directly. Doing so causes deadlock when .Fn destroy_dev waits for all threads to leave the driver methods. Also, because .Fn destroy_dev sleeps, no non-sleepable locks may be held over the call. The .Fn destroy_dev_sched family of functions overcome these issues. .Pp The device driver may call the .Fn destroy_dev_drain function to wait until all devices that have supplied .Fa csw as cdevsw, are destroyed. This is useful when driver knows that .Fn destroy_dev_sched is called for all instantiated devices, but need to postpone module unload until .Fn destroy_dev is actually finished for all of them. .Sh RETURN VALUES If successful, .Fn make_dev_p will return 0, otherwise it will return an error. If successful, .Fn make_dev_credf will return a valid .Fa cdev pointer, otherwise it will return .Dv NULL . .Sh ERRORS The .Fn make_dev_p and .Fn make_dev_alias_p call will fail and the device will be not registered if: .Bl -tag -width Er .It Bq Er ENOMEM The .Dv MAKEDEV_NOWAIT flag was specified and a memory allocation request could not be satisfied. .It Bq Er ENAMETOOLONG The .Dv MAKEDEV_CHECKNAME flag was specified and the provided device name is longer than .Dv SPECNAMELEN . .It Bq Er EINVAL The .Dv MAKEDEV_CHECKNAME flag was specified and the provided device name is empty, contains a .Qq \&. or .Qq .. path component or ends with .Ql / . .It Bq Er EEXIST The .Dv MAKEDEV_CHECKNAME flag was specified and the provided device name already exists. .El -.Pp .Sh SEE ALSO .Xr devctl 4 , .Xr devfs 5 , .Xr destroy_dev_drain 9 , .Xr dev_clone 9 .Sh HISTORY The .Fn make_dev and .Fn destroy_dev functions first appeared in .Fx 4.0 . The function .Fn make_dev_alias first appeared in .Fx 4.1 . The function .Fn dev_depends first appeared in .Fx 5.0 . The functions .Fn make_dev_credf , .Fn destroy_dev_sched , .Fn destroy_dev_sched_cb first appeared in .Fx 7.0 . The function .Fn make_dev_p first appeared in .Fx 8.2 . Index: stable/9/share/man/man9 =================================================================== --- stable/9/share/man/man9 (revision 290885) +++ stable/9/share/man/man9 (revision 290886) Property changes on: stable/9/share/man/man9 ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/share/man/man9:r233422 Index: stable/9/share/man =================================================================== --- stable/9/share/man (revision 290885) +++ stable/9/share/man (revision 290886) Property changes on: stable/9/share/man ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/share/man:r233422 Index: stable/9/share =================================================================== --- stable/9/share (revision 290885) +++ stable/9/share (revision 290886) Property changes on: stable/9/share ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/share:r233422 Index: stable/9 =================================================================== --- stable/9 (revision 290885) +++ stable/9 (revision 290886) Property changes on: stable/9 ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head:r233422