Index: head/share/man/man4/aac.4 =================================================================== --- head/share/man/man4/aac.4 (revision 117010) +++ head/share/man/man4/aac.4 (revision 117011) @@ -1,163 +1,164 @@ .\" Copyright (c) 2000 Scott Long .\" 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 22, 2001 .Dt AAC 4 .Os .Sh NAME .Nm aac .Nd Adaptec AdvancedRAID Controller driver .Sh SYNOPSIS .Cd options AAC_DEBUG=N .Cd device pci .Cd device aac .Cd device aacp .Sh DESCRIPTION The .Nm driver provides support for the Adaptec AAC family of SCSI Ultra2, Ultra160, and Ultra320 RAID controllers. Supported controllers include: .Bl -bullet .It AAC-364 .It Adaptec SCSI RAID 2120S .It Adaptec SCSI RAID 2200S .It Adaptec SCSI RAID 5400S .It HP NetRAID 4M .It Dell PERC 2/Si .It Dell PERC 2/QC .It Dell PERC 3/Si .It Dell PERC 3/Di .Pp .El Access to RAID containers is available via the .Pa /dev/aacd? device nodes. Individual drives cannot be accessed unless they are part of a container or volume set, and non-fixed disks cannot be accessed. Containers can be configured by using either the on-board BIOS utility of the card, or a command-line interface management application. .Pp The .Pa /dev/aac? device nodes provide access to the management interface of the controller. One node exists per installed card. The aliases .Pa /dev/afa? and .Pa /dev/hpn? exist for the Dell and HP flavors, respectively, and are required for the CLI management utility available from these vendors to work. If the kernel is compiled with the .Dv COMPAT_LINUX option, or the .Pa aac_linux.ko and .Pa linux.ko modules are loaded, the Linux-compatible .Xr ioctl 2 interface for the management device will be enabled and will allow Linux-based management applications to control the card. .Pp The .Nm aacp device enables the SCSI pass-thru interface and allows devices connected to the card such as cdroms to be available via the CAM .Xr scsi 4 -subsystem. Note that not all cards allow this interface to be enabled. +subsystem. +Note that not all cards allow this interface to be enabled. .Ss Tuning The read-only sysctl .Va hw.aac.iosize_max defaults to 65536 and may be set at boot time to another value via .Xr loader 8 . This value determines the maximum data transfer size allowed to/from an array. Setting it higher will result in better performance, especially for large sequential access patterns. .Em Beware : internal limitations of the card limit this value to 64K for arrays with many members. While it may be safe to raise this value, this is done .Em at the operator's own risk . Note also that performance peaks at a value of 96K, and drops off dramatically at 128K, due to other limitations of the card. .Sh FILES .Bl -tag -width /boot/kernel/aac.ko -compact .It Pa /dev/aac? aac management interface .It Pa /dev/aacd? disk/container interface .It Pa /boot/kernel/aac.ko aac loadable module .El .Sh DIAGNOSTICS Compiling with .Dv AAC_DEBUG set to a number between 0 and 3 will enable increasingly verbose debug messages. .Pp The adapter can send status and alert messages asynchronously to the driver. These messages are printed on the system console, and are also queued for retrieval by a management application. .Sh SEE ALSO .Xr kld 4 , .Xr linux 4 , .Xr scsi 4 , .Xr kldload 8 , .Xr loader 8 , .Xr sysctl 8 .Sh HISTORY The .Nm driver first appeared in .Fx 4.3 . .Sh AUTHORS .An Mike Smith .Aq msmith@FreeBSD.org .An Scott Long .Aq scottl@FreeBSD.org .Sh BUGS This driver is not compatible with Dell controllers that have version 1.x firmware. The firmware version is the same as the kernel version printed in the BIOS POST and driver attach messages. .Pp The controller is not actually paused on suspend/resume. .Pp Index: head/share/man/man4/aha.4 =================================================================== --- head/share/man/man4/aha.4 (revision 117010) +++ head/share/man/man4/aha.4 (revision 117011) @@ -1,81 +1,87 @@ .\" .\" Copyright (c) 1994 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. .\" 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 October 15, 1998 .Dt AHA 4 .Os .Sh NAME .Nm aha .Nd Adaptec SCSI host adapter driver .Sh SYNOPSIS .Cd device aha .Cd device scbus .Pp In .Pa /boot/device.hints : .Cd hint.aha.0.at="isa" .Sh DESCRIPTION This driver provides access to the .Tn SCSI bus connected to an Adaptec 154xA, 154xB, 154xC, 154xCF, or 154xCP -host adapter. Host adapters supporting a 154X compatible interface, +host adapter. +Host adapters supporting a 154X compatible interface, such as some Tekram controllers and the Adaptec 174x in 154x -emulation mode can, also be attached with this driver. For optimum +emulation mode can, also be attached with this driver. +For optimum performance, Adaptec 174x controllers should be configured in enhanced mode and attached via the .Xr ahb 4 driver. .Pp One kernel config entry for every card to be attached by the system is -required. 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 +required. +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 +locations and attaches to the first unattached card it finds. +The possible port addresses for this card are 0x330, 0x334, 0x230, 0x234, 0x130, and 0x134. .Sh SEE ALSO .Xr ahb 4 , .Xr ahc 4 , .Xr cd 4 , .Xr da 4 , .Xr sa 4 , .Xr scsi 4 .\" .\" .Sh DIAGNOSTICS .\" .Sh AUTHORS .An -nosplit The .Nm driver was ported by .An M. Warner Losh from the .Nm bt driver written by .An Justin T. Gibbs . Index: head/share/man/man4/ahb.4 =================================================================== --- head/share/man/man4/ahb.4 (revision 117010) +++ head/share/man/man4/ahb.4 (revision 117011) @@ -1,63 +1,64 @@ .\" .\" Copyright (c) 1994 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. .\" 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 October 15, 1998 .Dt AHB 4 .Os .Sh NAME .Nm ahb .Nd Adaptec EISA SCSI host adapter driver .Sh SYNOPSIS .Cd device ahb .Cd device scbus .Sh DESCRIPTION This driver provides access to the .Tn SCSI bus connected to an Adaptec 174x hostadapter in .Dq Em enhanced mode. Tagged queueing and synchronous SCSI transfers are supported. .Sh CAVEATS The Adaptec 174X is very sensitive to SCSI bus termination and cable -length. It may also have difficulties operating with some modern devices -that, due to their speed, expose timing problems in the controller. There -are no known mechanisms for working around device incompatibilities of +length. +It may also have difficulties operating with some modern devices +that, due to their speed, expose timing problems in the controller. +There are no known mechanisms for working around device incompatibilities of this nature. .Sh SEE ALSO .Xr aha 4 , .Xr ahc 4 , .Xr cd 4 , .Xr da 4 , .Xr sa 4 , .Xr scsi 4 .Sh AUTHORS The .Nm driver was written by .An Justin T. Gibbs . Index: head/share/man/man4/ahc.4 =================================================================== --- head/share/man/man4/ahc.4 (revision 117010) +++ head/share/man/man4/ahc.4 (revision 117011) @@ -1,296 +1,309 @@ .\" .\" 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 February 13, 2000 .Dt AHC 4 .Os .Sh NAME .Nm ahc .Nd Adaptec VL/EISA/PCI SCSI host adapter driver .Sh SYNOPSIS For one or more VL/EISA cards: .Cd device eisa .Cd device ahc .Pp For one or more PCI cards: .Cd device pci .Cd device ahc .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 .Pp For one or more SCSI busses: .Cd device scbus .Sh DESCRIPTION This driver provides access to the .Tn SCSI bus(es) connected to Adaptec .Tn AIC7770 , .Tn AIC7850 , .Tn AIC7860 , .Tn AIC7870 , .Tn AIC7880 , .Tn AIC7890 , .Tn AIC7891 , .Tn AIC7892 , .Tn AIC7895 , .Tn AIC7896 , .Tn AIC7897 and .Tn AIC7899 host adapter chips. These chips are found on many motherboards as well as the following Adaptec SCSI controller cards: .Tn 274X(W) , .Tn 274X(T) , .Tn 284X , .Tn 2910 , .Tn 2915 , .Tn 2920 , .Tn 2930C , .Tn 2930U2 , .Tn 2940 , .Tn 2940U , .Tn 2940AU , .Tn 2940UW , .Tn 2940UW Dual , .Tn 2940UW Pro , .Tn 2940U2W , .Tn 2940U2B , .Tn 2950U2W , .Tn 2950U2B , .Tn 19160B , .Tn 29160B , .Tn 29160N , .Tn 3940 , .Tn 3940U , .Tn 3940AU , .Tn 3940UW , .Tn 3940AUW , .Tn 3940U2W , .Tn 3950U2 , .Tn 3960 , .Tn 39160 , .Tn 3985 , and .Tn 4944UW . .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 +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 +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 +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 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 +(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 +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 +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 +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 +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 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 +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. +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 +voltage differential boards as shipped by Adaptec. +Information on how to modify HVD board to work correctly in target mode is available from Adaptec. .Sh SEE ALSO .Xr aha 4 , .Xr ahb 4 , .Xr cd 4 , .Xr da 4 , .Xr sa 4 , .Xr scsi 4 .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 HISTORY The .Nm driver appeared in .Fx 2.0 . Index: head/share/man/man4/atkbd.4 =================================================================== --- head/share/man/man4/atkbd.4 (revision 117010) +++ head/share/man/man4/atkbd.4 (revision 117011) @@ -1,222 +1,222 @@ .\" .\" 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 May 21, 1999 .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 drivers .Xr syscons 4 and .Xr pcvt 4 . .Pp There can be only one .Nm -device defined in the kernel configuration file. This device also -requires the +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. .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 .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. .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" .Pp .\".Sh DIAGNOSTICS .\".Sh CAVEATS .\".Sh BUGS .Sh SEE ALSO .Xr kbdcontrol 1 , .Xr atkbdc 4 , .Xr pcvt 4 , .Xr psm 4 , .Xr syscons 4 , .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: head/share/man/man4/awi.4 =================================================================== --- head/share/man/man4/awi.4 (revision 117010) +++ head/share/man/man4/awi.4 (revision 117011) @@ -1,158 +1,162 @@ .\" $NetBSD: awi.4,v 1.6 2000/03/22 11:24:33 onoe Exp $ .\" $FreeBSD$ .\" .Dd October 31, 1999 .Dt AWI 4 .Os .Sh NAME .Nm awi .Nd "AMD PCnetMobile IEEE 802.11 PCMCIA wireless network driver" .Sh SYNOPSIS .Cd "device awi" .Sh DESCRIPTION The .Nm driver supports various IEEE 802.11 wireless cards which run AMD PCnetMobile firmware based on AMD 79c930 controller with Intersil (formerly Harris) PRISM radio chipset. It provides access to 32kb of memory shared between the controller and the host. All host/device interaction is via this shared memory, which can be accessed either via PCMCIA memory space or I/O space. The .Nm driver encapsulates all IP and ARP traffic as 802.11 frames. .Pp The driver works both in infrastructure mode and in adhoc (independent BSS) mode. .Pp In infrastructure mode, it communicates with an Access Point which serves as a link-layer bridge between an Ethernet and -the wireless network. An access point also provides roaming capability +the wireless network. +An access point also provides roaming capability which allows wireless node to move between access points. .Pp In adhoc mode, it communicates peer to peer. Though it is more efficient to communicate between wireless nodes, the coverage is limited spatially due to lack of roaming capability. .Pp In addition to these two mode in IEEE 802.11 specification, the .Nm driver also supports a variant of adhoc mode out of spec for DS radio cards, which makes possible to communicate with adhoc mode of .Xr wi 8 -driver. The NWID doesn't affect in this mode. +driver. +The NWID doesn't affect in this mode. .Pp For more information on configuring this device, see .Xr ifconfig 8 and .Xr ifmedia 4 . .Sh HARDWARE Cards supported by the .Nm driver include: .Pp .Bl -tag -width BayStack_650x -offset indent .It BayStack 650 1Mbps Frequency Hopping PCCARD adapter .It BayStack 660 2Mbps Direct Sequence PCCARD adapter .It Icom SL-200 2Mbps Direct Sequence PCCARD adapter .It Melco WLI-PCM 2Mbps Direct Sequence PCCARD adapter .It NEL SSMagic 2Mbps Direct Sequence PCCARD adapter .It Netwave AirSurfer Plus 1Mbps Frequency Hopping PCCARD adapter .It Netwave AirSurfer Pro 2Mbps Direct Sequence PCCARD adapter .El .Pp The original Xircom Netwave AirSurfer is supported by the .Xr cnw 4 driver. .Sh MEDIA SELECTION The DS cards support .Em DS1 and .Em DS2 media types, while the FH cards support .Em FH1 -media type. For each media type, +media type. +For each media type, .Em adhoc mediaopt can be used to indicate the driver to operate in adhoc mode. For DS radio cards, .Em adhoc , Ns Em flag0 mediaopt can be used for .Xr wi 4 compatible adhoc mode. .Sh DIAGNOSTICS .Bl -diag .It "awi0: unable to allocate memory space; using i/o only" Indicates that the driver was not able to allocate 32kb of PCMCIA bus address space into which to map the device; the driver will use the (slightly slower) i/o-space only access methods to read and write to -the shared memory. Since by default, +the shared memory. +Since by default, .Nx , only allocates 16kb of address space per PCMCIA controller, this message is in some sense to be expected and should not be a cause for alarm. See .Xr pcmcia 4 for information on how to increase the memory available to the PCMCIA controller. .It "awi0: failed to complete selftest (%s)" The device failed to complete its self test. .It "awi0: synced with no-bssid at channel %d" The device is ready to relay traffic at specified channel. .It "awi0: synced with %s ssid %s at channel %d" The device has successfully synchronized with at least one of the identified stations and is ready to relay traffic. .It "awi0: associated with %s ssid %s channel %d signal %d" The device has successfully synchronized with the identified Access Point and is ready to relay traffic. .It "awi0: authentication failed (reason %d)" .It "awi0: association failed (reason %d)" The access point refuses the association request from the device. .It "awi0: no recent beacons from %s; rescanning" The device has not heard a beacon from its currently associated Access Point recently, and is looking for a new access point. .It "awi0: transmit timeout" The device failed to generate an interrupt to acknowledge a transmitted packet. .It "awi0: failed to lock interrupt" The system was unable to obtain the lock to access shared memory. .It "awi0: command %d failed %x" The device failed to complete the request from the system. .El .Sh BUGS Doesn't create IBSS itself. .Sh SEE ALSO .Xr arp 4 , .Xr cnw 4 , .Xr ifmedia 4 , .Xr miibus 4 , .Xr netintro 4 , .Xr pcmcia 4 , .Xr wi 4 , .Xr ifconfig 8 .Rs .%T Am79C930 PCnet Mobile Single-Chip Wireless LAN Media Access Controller .%O http://www.amd.com .Re .Sh HISTORY The .Nm device driver first appeared in .Nx 1.5 . .Sh AUTHORS .An -nosplit The initial version of the .Nm driver was written by .An Bill Sommerfeld Aq sommerfeld@netbsd.org . Then the .Nm driver module completely rewritten to support cards with DS phy and to support adhoc mode by .An Atsushi Onoe Aq onoe@netbsd.org . Index: head/share/man/man4/bktr.4 =================================================================== --- head/share/man/man4/bktr.4 (revision 117010) +++ head/share/man/man4/bktr.4 (revision 117011) @@ -1,187 +1,189 @@ .\" .\" $FreeBSD$ .\" .Dd January 28, 1998 .Dt BKTR 4 .Os .Sh NAME .Nm brooktree .Nd video capture driver .Sh SYNOPSIS .Cd device bktr .Pp .Cd device iicbus .Cd device iicbb .Cd device smbus .Sh DESCRIPTION The .Nm bktr driver provides support for PCI .Em video capture and .Em VBI -capture on low cost, high performance boards. The driver is based on -the Matrox Meteor driver and uses the same API. The bktr driver should support most video cards +capture on low cost, high performance boards. +The driver is based on the Matrox Meteor driver and uses the same API. +The bktr driver should support most video cards based on the .Em "Brooktree Bt848/849/878/879 Video Capture Chip" . The driver also supports .Em FM Radio if the tuner supports it. .Pp Specifically, the following cards are known to work: .Bd -unfilled -offset indent .Em Hauppauge Wincast TV and WinTV/PCI .Em STB TV PCI Television Tuner .Em Miro PC TV .Em Intel Smart Video Recorder III .Em AverMedia cards .Em Video Highway XTreme .Em VideoLogic Captivator PCI .Ed .Pp The driver currently supports the following features: .Bd -unfilled -offset indent PCI to PCI dma transfer clipping yuv rgb16 rgb24 rgb32 .Ed .Pp On these cards, tuners and other components are interconnected with an I2C bus. The Brooktree848 chips act as a master device on the bus to control them. Therefore, .Xr iicbus 4 , .Xr iicbb 4 and .Xr smbus 4 controller declarations are mandatory to activate bktr support. .Pp The following kernel parameters may be used to further configure the driver: .Pp .Em options "BROOKTREE_ALLOC_PAGES=xxx" specifies the number of contiguous pages to allocate when successfully -probed. The default number of pages allocated by the kernel is 216. +probed. +The default number of pages allocated by the kernel is 216. This means that there are (216*4096) bytes available for use. .Bd -unfilled .Em options BROOKTREE_SYSTEM_DEFAULT=BROOKTREE_PAL .Em options BROOKTREE_SYSTEM_DEFAULT=BROOKTREE_NTSC .Ed One of these options can be used to set the default video format for the driver. This fixed random hangs and lockups with the VideoLogic Captivator PCI card. .Pp The following sysctls may be used to further configure the driver: .Pp .Em sysctl hw.bt848.card=nnnn This can be used to override the card make which was detected at boot time. .Ql nnnn is set to an integer from 1 to 13 taken from the following table: .Pp .Bl -tag -compact -width 22n .It MIRO 1 .It HAUPPAUGE 2 .It STB 3 .It INTEL 4 .It IMS_TURBO 5 .It AVER_MEDIA 6 .It OSPREY 7 .It NEC_PK 8 .It IO_GV 9 .It FLYVIDEO 10 .It ZOLTRIX 11 .It KISS 12 .It VIDEO_HIGHWAY_XTREME 13 .El .Pp .Em sysctl hw.bt848.tuner=nnnn This can be used to override the tuner make which was detected at boot time. .Ql nnnn is set to an integer from 1 to 13 taken from the following table: .Pp .Bl -tag -compact -width 22n .It NO_TUNER 0 .It TEMIC_NTSC 1 .It TEMIC_PAL 2 .It TEMIC_SECAM 3 .It PHILIPS_NTSC 4 .It PHILIPS_PAL 5 .It PHILIPS_SECAM 6 .It TEMIC_PALI 7 .It PHILIPS_PALI 8 .It PHILIPS_FR1236_NTSC 9 /* These have FM Radio support */ .It PHILIPS_FR1216_PAL 10 /* These have FM Radio support */ .It PHILIPS_FR1236_SECAM 11 /* These have FM Radio support */ .It ALPS_TSCH5 12 .It ALPS_TSBH1 13 .El .Sh AUTHORS .An -nosplit This driver is based on the work of .An Jim Lowe Aq james@miller.cs.uwm.edu , .An Mark Tinguely Aq tinguely@plains.nodak.edu , .An Amancio Hasty Aq hasty@star\-gate.com , .An Roger Hardiman Aq roger@FreeBSD.org and a bunch of other people. .Sh FILES .Bl -tag -width /usr/share/examples/meteor -compact .It Pa /usr/share/examples/meteor Examples of what you can do with the (similarly designed) Meteor driver. .It Pa /usr/ports/graphics/fxtv A TV and Camera display program utilizing the bktr driver - requires that .Em The X Window System and .Em The Ports Collection also be installed. .It Pa /usr/ports/misc/alevt A program to capture and display Teletext (VideoText) pages - requires that .Em The X Window System and .Em The Ports Collection also be installed. .It Pa /usr/ports/audio/xmradio An FM Radio Tuner for cards which have an FM Radio tuner fitted. - requires that .Em The X Window System and .Em The Ports Collection also be installed. It also requires .Em Motif or the .Em lesstif port. .El .Sh SEE ALSO .Xr meteor 4 .Sh HISTORY The .Nm driver first appeared in .Fx 2.2 . Index: head/share/man/man4/blackhole.4 =================================================================== --- head/share/man/man4/blackhole.4 (revision 117010) +++ head/share/man/man4/blackhole.4 (revision 117011) @@ -1,79 +1,83 @@ .\" .\" blackhole - drop refused TCP or UDP connects .\" .\" 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. .\" .\" .\" $FreeBSD$ .Dd August 17, 1999 .Dt BLACKHOLE 4 .Os .Sh NAME .Nm blackhole .Nd a .Xr sysctl 8 MIB for manipulating behaviour in respect of refused TCP or UDP connection attempts .Sh SYNOPSIS .Cd sysctl net.inet.tcp.blackhole[=[0 | 1 | 2]] .Cd sysctl net.inet.udp.blackhole[=[0 | 1]] .Sh DESCRIPTION The .Nm .Xr sysctl 8 MIB is used to control system behaviour when connection requests are received on TCP or UDP ports where there is no socket listening. .Pp Normal behaviour, when a TCP SYN segment is received on a port where there is no socket accepting connections, is for the system to return -a RST segment, and drop the connection. The connecting system will -see this as a "Connection refused". By setting the TCP blackhole +a RST segment, and drop the connection. +The connecting system will +see this as a +.Dq Connection refused . +By setting the TCP blackhole MIB to a numeric value of one, the incoming SYN segment is merely dropped, and no RST is sent, making the system appear -as a blackhole. By setting the MIB value to two, any segment arriving -on a closed port is dropped without returning a RST. This provides -some degree of protection against stealth port scans. +as a blackhole. +By setting the MIB value to two, any segment arriving +on a closed port is dropped without returning a RST. +This provides some degree of protection against stealth port scans. .Pp In the UDP instance, enabling blackhole behaviour turns off the sending of an ICMP port unreachable message in response to a UDP datagram which -arrives on a port where there is no socket listening. It must be noted -that this behaviour will prevent remote systems from running +arrives on a port where there is no socket listening. +It must be noted that this behaviour will prevent remote systems from running .Xr traceroute 8 to a system. .Pp The blackhole behaviour is useful to slow down anyone who is port scanning a system, attempting to detect vulnerable services on a system. It could potentially also slow down someone who is attempting a denial of service attack. .Sh WARNING The TCP and UDP blackhole features should not be regarded as a replacement for .Xr ipfw 8 -as a tool for firewalling a system. In order to create a highly -secure system, +as a tool for firewalling a system. +In order to create a highly secure system, .Xr ipfw 8 should be used for protection, not the blackhole feature. .Pp This mechanism is not a substitute for securing a system. It should be used together with other security mechanisms. .Sh SEE ALSO .Xr ip 4 , .Xr tcp 4 , .Xr udp 4 , .Xr ipfw 8 , .Xr sysctl 8 .Sh AUTHORS .An Geoffrey M. Rehmet .Sh HISTORY The TCP and UDP .Nm MIBs first appeared in .Fx 4.0 . Index: head/share/man/man4/bpf.4 =================================================================== --- head/share/man/man4/bpf.4 (revision 117010) +++ head/share/man/man4/bpf.4 (revision 117011) @@ -1,749 +1,768 @@ .\" Copyright (c) 1990 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: (1) source code distributions .\" retain the above copyright notice and this paragraph in its entirety, (2) .\" distributions including binary code include the above copyright notice and .\" this paragraph in its entirety in the documentation or other materials .\" provided with the distribution, and (3) all advertising materials mentioning .\" features or use of this software display the following acknowledgement: .\" ``This product includes software developed by the University of California, .\" Lawrence Berkeley Laboratory and its contributors.'' 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 ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. .\" .\" This document is derived in part from the enet man page (enet.4) .\" distributed with 4.3BSD Unix. .\" .\" $FreeBSD$ .\" .Dd January 16, 1996 .Dt BPF 4 .Os .Sh NAME .Nm bpf .Nd Berkeley Packet Filter .Sh SYNOPSIS .Cd device bpf .Sh DESCRIPTION The Berkeley Packet Filter provides a raw interface to data link layers in a protocol independent fashion. All packets on the network, even those destined for other hosts, are accessible through this mechanism. .Pp The packet filter appears as a character special device, .Pa /dev/bpf0 , .Pa /dev/bpf1 , etc. After opening the device, the file descriptor must be bound to a specific network interface with the .Dv BIOCSETIF ioctl. A given interface can be shared by multiple listeners, and the filter underlying each descriptor will see an identical packet stream. .Pp A separate device file is required for each minor device. If a file is in use, the open will fail and .Va errno will be set to .Er EBUSY . .Pp Associated with each open instance of a .Nm file is a user-settable packet filter. Whenever a packet is received by an interface, all file descriptors listening on that interface apply their filter. Each descriptor that accepts the packet receives its own copy. .Pp Reads from these files return the next group of packets that have matched the filter. To improve performance, the buffer passed to read must be the same size as the buffers used internally by .Nm . This size is returned by the .Dv BIOCGBLEN ioctl (see below), and can be set with .Dv BIOCSBLEN . Note that an individual packet larger than this size is necessarily truncated. .Pp The packet filter will support any link level protocol that has fixed length -headers. Currently, only Ethernet, +headers. +Currently, only Ethernet, .Tn SLIP , and .Tn PPP drivers have been modified to interact with .Nm . .Pp Since packet data is in network byte order, applications should use the .Xr byteorder 3 macros to extract multi-byte values. .Pp A packet can be sent out on the network by writing to a .Nm -file descriptor. The writes are unbuffered, meaning only one -packet can be processed per write. +file descriptor. +The writes are unbuffered, meaning only one packet can be processed per write. Currently, only writes to Ethernets and .Tn SLIP links are supported. .Sh IOCTLS The .Xr ioctl 2 command codes below are defined in .Aq Pa net/bpf.h . All commands require these includes: .Bd -literal #include #include #include #include .Ed .Pp Additionally, .Dv BIOCGETIF and .Dv BIOCSETIF require .Aq Pa sys/socket.h and .Aq Pa net/if.h . .Pp In addition to .Dv FIONREAD and .Dv SIOCGIFADDR , the following commands may be applied to any open .Nm file. The (third) argument to .Xr ioctl 2 should be a pointer to the type indicated. .Bl -tag -width BIOCGRTIMEOUT .It Dv BIOCGBLEN .Pq Li u_int Returns the required buffer length for reads on .Nm files. .It Dv BIOCSBLEN .Pq Li u_int Sets the buffer length for reads on .Nm -files. The buffer must be set before the file is attached to an interface +files. +The buffer must be set before the file is attached to an interface with .Dv BIOCSETIF . If the requested buffer size cannot be accommodated, the closest allowable size will be set and returned in the argument. A read call will result in .Er EIO if it is passed a buffer that is not this size. .It Dv BIOCGDLT .Pq Li u_int Returns the type of the data link layer underlying the attached interface. .Er EINVAL is returned if no interface has been specified. The device types, prefixed with .Dq Li DLT_ , are defined in .Aq Pa net/bpf.h . .It Dv BIOCPROMISC Forces the interface into promiscuous mode. All packets, not just those destined for the local host, are processed. Since more than one file can be listening on a given interface, a listener that opened its interface non-promiscuously may receive -packets promiscuously. This problem can be remedied with an -appropriate filter. +packets promiscuously. +This problem can be remedied with an appropriate filter. .It Dv BIOCFLUSH Flushes the buffer of incoming packets, and resets the statistics that are returned by BIOCGSTATS. .It Dv BIOCGETIF .Pq Li "struct ifreq" Returns the name of the hardware interface that the file is listening on. The name is returned in the ifr_name field of the .Li ifreq structure. All other fields are undefined. .It Dv BIOCSETIF .Pq Li "struct ifreq" Sets the hardware interface associate with the file. This command must be performed before any packets can be read. The device is indicated by name using the .Li ifr_name field of the .Li ifreq structure. Additionally, performs the actions of .Dv BIOCFLUSH . .It Dv BIOCSRTIMEOUT .It Dv BIOCGRTIMEOUT .Pq Li "struct timeval" Set or get the read timeout parameter. The argument specifies the length of time to wait before timing out on a read request. This parameter is initialized to zero by .Xr open 2 , indicating no timeout. .It Dv BIOCGSTATS .Pq Li "struct bpf_stat" Returns the following structure of packet statistics: .Bd -literal struct bpf_stat { u_int bs_recv; /* number of packets received */ u_int bs_drop; /* number of packets dropped */ }; .Ed .Pp The fields are: .Bl -hang -offset indent .It Li bs_recv the number of packets received by the descriptor since opened or reset (including any buffered since the last read call); and .It Li bs_drop the number of packets which were accepted by the filter but dropped by the kernel because of buffer overflows (i.e., the application's reads aren't keeping up with the packet traffic). .El .It Dv BIOCIMMEDIATE .Pq Li u_int Enable or disable .Dq immediate mode , based on the truth value of the argument. When immediate mode is enabled, reads return immediately upon packet -reception. Otherwise, a read will block until either the kernel buffer +reception. +Otherwise, a read will block until either the kernel buffer becomes full or a timeout occurs. This is useful for programs like .Xr rarpd 8 which must respond to messages in real time. The default for a new file is off. .It Dv BIOCSETF .Pq Li "struct bpf_program" Sets the filter program used by the kernel to discard uninteresting -packets. An array of instructions and its length is passed in using +packets. +An array of instructions and its length is passed in using the following structure: .Bd -literal struct bpf_program { int bf_len; struct bpf_insn *bf_insns; }; .Ed .Pp The filter program is pointed to by the .Li bf_insns field while its length in units of .Sq Li struct bpf_insn is given by the .Li bf_len field. Also, the actions of .Dv BIOCFLUSH are performed. See section .Sx "FILTER MACHINE" for an explanation of the filter language. .It Dv BIOCVERSION .Pq Li "struct bpf_version" Returns the major and minor version numbers of the filter language currently -recognized by the kernel. Before installing a filter, applications must check -that the current version is compatible with the running kernel. Version -numbers are compatible if the major numbers match and the application minor -is less than or equal to the kernel minor. The kernel version number is -returned in the following structure: +recognized by the kernel. +Before installing a filter, applications must check +that the current version is compatible with the running kernel. +Version numbers are compatible if the major numbers match and the application minor +is less than or equal to the kernel minor. +The kernel version number is returned in the following structure: .Bd -literal struct bpf_version { u_short bv_major; u_short bv_minor; }; .Ed .Pp The current version numbers are given by .Dv BPF_MAJOR_VERSION and .Dv BPF_MINOR_VERSION from .Aq Pa net/bpf.h . An incompatible filter may result in undefined behavior (most likely, an error returned by .Fn ioctl or haphazard packet matching). .It Dv BIOCSHDRCMPLT .It Dv BIOCGHDRCMPLT .Pq Li u_int Set or get the status of the .Dq header complete flag. Set to zero if the link level source address should be filled in automatically -by the interface output routine. Set to one if the link level source -address will be written, as provided, to the wire. This flag is initialized -to zero by default. +by the interface output routine. +Set to one if the link level source +address will be written, as provided, to the wire. +This flag is initialized to zero by default. .It Dv BIOCSSEESENT .It Dv BIOCGSEESENT .Pq Li u_int Set or get the flag determining whether locally generated packets on the -interface should be returned by BPF. Set to zero to see only incoming -packets on the interface. Set to one to see packets originating -locally and remotely on the interface. This flag is initialized to one by +interface should be returned by BPF. +Set to zero to see only incoming packets on the interface. +Set to one to see packets originating locally and remotely on the interface. +This flag is initialized to one by default. .El .Sh BPF HEADER The following structure is prepended to each packet returned by .Xr read 2 : .Bd -literal struct bpf_hdr { struct timeval bh_tstamp; /* time stamp */ u_long bh_caplen; /* length of captured portion */ u_long bh_datalen; /* original length of packet */ u_short bh_hdrlen; /* length of bpf header (this struct plus alignment padding */ }; .Ed .Pp The fields, whose values are stored in host order, and are: .Pp .Bl -tag -compact -width bh_datalen .It Li bh_tstamp The time at which the packet was processed by the packet filter. .It Li bh_caplen -The length of the captured portion of the packet. This is the minimum of +The length of the captured portion of the packet. +This is the minimum of the truncation amount specified by the filter and the length of the packet. .It Li bh_datalen The length of the packet off the wire. This value is independent of the truncation amount specified by the filter. .It Li bh_hdrlen The length of the .Nm header, which may not be equal to .\" XXX - not really a function call .Fn sizeof "struct bpf_hdr" . .El .Pp The .Li bh_hdrlen field exists to account for padding between the header and the link level protocol. The purpose here is to guarantee proper alignment of the packet data structures, which is required on alignment sensitive architectures and improves performance on many other architectures. The packet filter insures that the .Li bpf_hdr and the network layer -header will be word aligned. Suitable precautions +header will be word aligned. +Suitable precautions must be taken when accessing the link layer protocol fields on alignment -restricted machines. (This isn't a problem on an Ethernet, since +restricted machines. +(This isn't a problem on an Ethernet, since the type field is a short falling on an even offset, and the addresses are probably accessed in a bytewise fashion). .Pp Additionally, individual packets are padded so that each starts -on a word boundary. This requires that an application +on a word boundary. +This requires that an application has some knowledge of how to get from packet to packet. The macro .Dv BPF_WORDALIGN is defined in .Aq Pa net/bpf.h to facilitate -this process. It rounds up its argument -to the nearest word aligned value (where a word is +this process. +It rounds up its argument to the nearest word aligned value (where a word is .Dv BPF_ALIGNMENT bytes wide). .Pp For example, if .Sq Li p points to the start of a packet, this expression will advance it to the next packet: .Dl p = (char *)p + BPF_WORDALIGN(p->bh_hdrlen + p->bh_caplen) .Pp For the alignment mechanisms to work properly, the buffer passed to .Xr read 2 must itself be word aligned. The .Xr malloc 3 function will always return an aligned buffer. .Sh FILTER MACHINE A filter program is an array of instructions, with all branches forwardly directed, terminated by a .Em return instruction. Each instruction performs some action on the pseudo-machine state, which consists of an accumulator, index register, scratch memory store, and implicit program counter. .Pp The following structure defines the instruction format: .Bd -literal struct bpf_insn { u_short code; u_char jt; u_char jf; u_long k; }; .Ed .Pp The .Li k field is used in different ways by different instructions, and the .Li jt and .Li jf fields are used as offsets by the branch instructions. The opcodes are encoded in a semi-hierarchical fashion. There are eight classes of instructions: .Dv BPF_LD , .Dv BPF_LDX , .Dv BPF_ST , .Dv BPF_STX , .Dv BPF_ALU , .Dv BPF_JMP , .Dv BPF_RET , and .Dv BPF_MISC . Various other mode and operator bits are or'd into the class to give the actual instructions. The classes and modes are defined in .Aq Pa net/bpf.h . .Pp Below are the semantics for each defined .Nm instruction. We use the convention that A is the accumulator, X is the index register, P[] packet data, and M[] scratch memory store. P[i:n] gives the data at byte offset .Dq i in the packet, interpreted as a word (n=4), unsigned halfword (n=2), or unsigned byte (n=1). M[i] gives the i'th word in the scratch memory store, which is only -addressed in word units. The memory store is indexed from 0 to +addressed in word units. +The memory store is indexed from 0 to .Dv BPF_MEMWORDS - 1. .Li k , .Li jt , and .Li jf are the corresponding fields in the instruction definition. .Dq len refers to the length of the packet. .Pp .Bl -tag -width BPF_STXx .It Dv BPF_LD -These instructions copy a value into the accumulator. The type of the -source operand is specified by an +These instructions copy a value into the accumulator. +The type of the source operand is specified by an .Dq addressing mode and can be a constant .Pq Dv BPF_IMM , packet data at a fixed offset .Pq Dv BPF_ABS , packet data at a variable offset .Pq Dv BPF_IND , the packet length .Pq Dv BPF_LEN , or a word in the scratch memory store .Pq Dv BPF_MEM . For .Dv BPF_IND and .Dv BPF_ABS , the data size must be specified as a word .Pq Dv BPF_W , halfword .Pq Dv BPF_H , or byte .Pq Dv BPF_B . The semantics of all the recognized .Dv BPF_LD instructions follow. .Pp .Bl -tag -width "BPF_LD+BPF_W+BPF_IND" -compact .It Li BPF_LD+BPF_W+BPF_ABS A <- P[k:4] .It Li BPF_LD+BPF_H+BPF_ABS A <- P[k:2] .It Li BPF_LD+BPF_B+BPF_ABS A <- P[k:1] .It Li BPF_LD+BPF_W+BPF_IND A <- P[X+k:4] .It Li BPF_LD+BPF_H+BPF_IND A <- P[X+k:2] .It Li BPF_LD+BPF_B+BPF_IND A <- P[X+k:1] .It Li BPF_LD+BPF_W+BPF_LEN A <- len .It Li BPF_LD+BPF_IMM A <- k .It Li BPF_LD+BPF_MEM A <- M[k] .El .It Dv BPF_LDX -These instructions load a value into the index register. Note that +These instructions load a value into the index register. +Note that the addressing modes are more restrictive than those of the accumulator loads, but they include .Dv BPF_MSH , a hack for efficiently loading the IP header length. .Pp .Bl -tag -width "BPF_LDX+BPF_W+BPF_MEM" -compact .It Li BPF_LDX+BPF_W+BPF_IMM X <- k .It Li BPF_LDX+BPF_W+BPF_MEM X <- M[k] .It Li BPF_LDX+BPF_W+BPF_LEN X <- len .It Li BPF_LDX+BPF_B+BPF_MSH X <- 4*(P[k:1]&0xf) .El .It Dv BPF_ST This instruction stores the accumulator into the scratch memory. We do not need an addressing mode since there is only one possibility for the destination. .Pp .Bl -tag -width "BPF_ST" -compact .It Li BPF_ST M[k] <- A .El .It Dv BPF_STX This instruction stores the index register in the scratch memory store. .Pp .Bl -tag -width "BPF_STX" -compact .It Li BPF_STX M[k] <- X .El .It Dv BPF_ALU The alu instructions perform operations between the accumulator and index register or constant, and store the result back in the accumulator. For binary operations, a source mode is required .Dv ( BPF_K or .Dv BPF_X ) . .Pp .Bl -tag -width "BPF_ALU+BPF_MUL+BPF_K" -compact .It Li BPF_ALU+BPF_ADD+BPF_K A <- A + k .It Li BPF_ALU+BPF_SUB+BPF_K A <- A - k .It Li BPF_ALU+BPF_MUL+BPF_K A <- A * k .It Li BPF_ALU+BPF_DIV+BPF_K A <- A / k .It Li BPF_ALU+BPF_AND+BPF_K A <- A & k .It Li BPF_ALU+BPF_OR+BPF_K A <- A | k .It Li BPF_ALU+BPF_LSH+BPF_K A <- A << k .It Li BPF_ALU+BPF_RSH+BPF_K A <- A >> k .It Li BPF_ALU+BPF_ADD+BPF_X A <- A + X .It Li BPF_ALU+BPF_SUB+BPF_X A <- A - X .It Li BPF_ALU+BPF_MUL+BPF_X A <- A * X .It Li BPF_ALU+BPF_DIV+BPF_X A <- A / X .It Li BPF_ALU+BPF_AND+BPF_X A <- A & X .It Li BPF_ALU+BPF_OR+BPF_X A <- A | X .It Li BPF_ALU+BPF_LSH+BPF_X A <- A << X .It Li BPF_ALU+BPF_RSH+BPF_X A <- A >> X .It Li BPF_ALU+BPF_NEG A <- -A .El .It Dv BPF_JMP -The jump instructions alter flow of control. Conditional jumps +The jump instructions alter flow of control. +Conditional jumps compare the accumulator against a constant .Pq Dv BPF_K or the index register .Pq Dv BPF_X . If the result is true (or non-zero), the true branch is taken, otherwise the false branch is taken. Jump offsets are encoded in 8 bits so the longest jump is 256 instructions. However, the jump always .Pq Dv BPF_JA opcode uses the 32 bit .Li k field as the offset, allowing arbitrarily distant destinations. All conditionals use unsigned comparison conventions. .Pp .Bl -tag -width "BPF_JMP+BPF_KSET+BPF_X" -compact .It Li BPF_JMP+BPF_JA pc += k .It Li BPF_JMP+BPF_JGT+BPF_K pc += (A > k) ? jt : jf .It Li BPF_JMP+BPF_JGE+BPF_K pc += (A >= k) ? jt : jf .It Li BPF_JMP+BPF_JEQ+BPF_K pc += (A == k) ? jt : jf .It Li BPF_JMP+BPF_JSET+BPF_K pc += (A & k) ? jt : jf .It Li BPF_JMP+BPF_JGT+BPF_X pc += (A > X) ? jt : jf .It Li BPF_JMP+BPF_JGE+BPF_X pc += (A >= X) ? jt : jf .It Li BPF_JMP+BPF_JEQ+BPF_X pc += (A == X) ? jt : jf .It Li BPF_JMP+BPF_JSET+BPF_X pc += (A & X) ? jt : jf .El .It Dv BPF_RET The return instructions terminate the filter program and specify the amount -of packet to accept (i.e., they return the truncation amount). A return -value of zero indicates that the packet should be ignored. +of packet to accept (i.e., they return the truncation amount). +A return value of zero indicates that the packet should be ignored. The return value is either a constant .Pq Dv BPF_K or the accumulator .Pq Dv BPF_A . .Pp .Bl -tag -width "BPF_RET+BPF_K" -compact .It Li BPF_RET+BPF_A accept A bytes .It Li BPF_RET+BPF_K accept k bytes .El .It Dv BPF_MISC The miscellaneous category was created for anything that doesn't fit into the above classes, and for any new instructions that might need to -be added. Currently, these are the register transfer instructions +be added. +Currently, these are the register transfer instructions that copy the index register to the accumulator or vice versa. .Pp .Bl -tag -width "BPF_MISC+BPF_TAX" -compact .It Li BPF_MISC+BPF_TAX X <- A .It Li BPF_MISC+BPF_TXA A <- X .El .El .Pp The .Nm interface provides the following macros to facilitate array initializers: .Fn BPF_STMT opcode operand and .Fn BPF_JUMP opcode operand true_offset false_offset . .Sh EXAMPLES -The following filter is taken from the Reverse ARP Daemon. It accepts -only Reverse ARP requests. +The following filter is taken from the Reverse ARP Daemon. +It accepts only Reverse ARP requests. .Bd -literal struct bpf_insn insns[] = { BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_REVARP, 0, 3), BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 20), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, REVARP_REQUEST, 0, 1), BPF_STMT(BPF_RET+BPF_K, sizeof(struct ether_arp) + sizeof(struct ether_header)), BPF_STMT(BPF_RET+BPF_K, 0), }; .Ed .Pp This filter accepts only IP packets between host 128.3.112.15 and 128.3.112.35. .Bd -literal struct bpf_insn insns[] = { BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_IP, 0, 8), BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 26), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x8003700f, 0, 2), BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 30), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x80037023, 3, 4), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x80037023, 0, 3), BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 30), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x8003700f, 0, 1), BPF_STMT(BPF_RET+BPF_K, (u_int)-1), BPF_STMT(BPF_RET+BPF_K, 0), }; .Ed .Pp -Finally, this filter returns only TCP finger packets. We must parse -the IP header to reach the TCP header. The +Finally, this filter returns only TCP finger packets. +We must parse the IP header to reach the TCP header. +The .Dv BPF_JSET instruction checks that the IP fragment offset is 0 so we are sure that we have a TCP header. .Bd -literal struct bpf_insn insns[] = { BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_IP, 0, 10), BPF_STMT(BPF_LD+BPF_B+BPF_ABS, 23), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, IPPROTO_TCP, 0, 8), BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 20), BPF_JUMP(BPF_JMP+BPF_JSET+BPF_K, 0x1fff, 6, 0), BPF_STMT(BPF_LDX+BPF_B+BPF_MSH, 14), BPF_STMT(BPF_LD+BPF_H+BPF_IND, 14), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 79, 2, 0), BPF_STMT(BPF_LD+BPF_H+BPF_IND, 16), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 79, 0, 1), BPF_STMT(BPF_RET+BPF_K, (u_int)-1), BPF_STMT(BPF_RET+BPF_K, 0), }; .Ed .Sh SEE ALSO .Xr tcpdump 1 , .Xr ioctl 2 , .Xr byteorder 3 , .Xr ng_bpf 4 .Rs .%A McCanne, S. .%A Jacobson V. .%T "An efficient, extensible, and portable network monitor" .Re .Sh FILES .Bl -tag -compact -width /dev/bpfXXX .It Pa /dev/bpf Ns Sy n the packet filter device .El .Sh BUGS The read buffer must be of a fixed size (returned by the .Dv BIOCGBLEN ioctl). .Pp A file that does not request promiscuous mode may receive promiscuously received packets as a side effect of another file requesting this -mode on the same hardware interface. This could be fixed in the kernel -with additional processing overhead. However, we favor the model where +mode on the same hardware interface. +This could be fixed in the kernel with additional processing overhead. +However, we favor the model where all files must assume that the interface is promiscuous, and if so desired, must utilize a filter to reject foreign packets. .Pp Data link protocols with variable length headers are not currently supported. .Pp The .Dv SEESENT flag has been observed to work incorrectly on some interface types, including those with hardware loopback rather than software loopback, -and point-to-point interfaces. It appears to function correctly on a +and point-to-point interfaces. +It appears to function correctly on a broad range of ethernet-style interfaces. .Sh HISTORY The Enet packet filter was created in 1980 by Mike Accetta and -Rick Rashid at Carnegie-Mellon University. Jeffrey Mogul, at +Rick Rashid at Carnegie-Mellon University. +Jeffrey Mogul, at Stanford, ported the code to .Bx and continued its development from -1983 on. Since then, it has evolved into the Ultrix Packet Filter -at +1983 on. +Since then, it has evolved into the Ultrix Packet Filter at .Tn DEC , a .Tn STREAMS .Tn NIT module under .Tn SunOS 4.1 , and .Tn BPF . .Sh AUTHORS .An -nosplit .An Steven McCanne , of Lawrence Berkeley Laboratory, implemented BPF in Summer 1990. Much of the design is due to .An Van Jacobson . Index: head/share/man/man4/bt.4 =================================================================== --- head/share/man/man4/bt.4 (revision 117010) +++ head/share/man/man4/bt.4 (revision 117011) @@ -1,144 +1,147 @@ .\" .\" Copyright (c) 1994 Jordan Hubbard .\" 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 October 16, 1998 .Dt BT 4 .Os .Sh NAME .Nm bt .Nd Buslogic/Mylex MultiMaster SCSI host adapter driver .Sh SYNOPSIS .Cd device bt .Cd device scbus .Pp In .Pa /boot/device.hints : .Cd hint.bt.0.at="isa" .Cd hint.bt.0.port="0x330" .Sh DESCRIPTION This driver provides access to the .Tn SCSI bus connected to a Buslogic/Mylex MultiMaster or compatible controller: .Pp .Bd -ragged -offset indent .Bl -column "BT-956CD " "ISA " "Commands " Description MultiMaster "W" Series Host Adapters: .Pp .Em "Adapter Bus Commands Description" BT-948 PCI 192 ULtra SCSI-3 BT-958 PCI 192 Wide ULtra SCSI-3 BT-958D PCI 192 Wide Differential ULtra SCSI-3 .El .Bl -column "BT-956CD " "ISA " "Commands " Description MultiMaster "C" Series Host Adapters: .Pp .Em "Adapter Bus Commands Description" BT-946C PCI 100 Fast SCSI-2 BT-956C PCI 100 Wide Fast SCSI-2 BT-956CD PCI 100 Wide Differential Fast SCSI-2 BT-445C VLB 100 Fast SCSI-2 BT-747C EISA 100 Fast SCSI-2 BT-757C EISA 100 Wide Fast SCSI-2 BT-757CD EISA 100 Wide Differential Fast SCSI-2 BT-545C ISA 50 Fast SCSI-2 BT-540CF ISA 50 Fast SCSI-2 .El .Bl -column "BT-956CD " "ISA " "Commands " Description MultiMaster "S" Series Host Adapters: .Pp .Em "Adapter Bus Commands Description" BT-445S VLB 30 Fast SCSI-2 BT-747S EISA 30 Fast SCSI-2 BT-747D EISA 30 Differential Fast SCSI-2 BT-757S EISA 30 Wide Fast SCSI-2 BT-757D EISA 30 Wide Differential Fast SCSI-2 BT-545S ISA 30 Fast SCSI-2 BT-542D ISA 30 Differential Fast SCSI-2 BT-742A EISA 30 SCSI-2 (742A revision H) BT-542B ISA 30 SCSI-2 (542B revision H) .El .Bl -column "BT-956CD " "ISA " "Commands " Description MultiMaster "A" Series Host Adapters: .Pp .Em "Adapter Bus Commands Description" BT-742A EISA 30 SCSI-2 (742A revisions A - G) BT-542B ISA 30 SCSI-2 (542B revisions A - G) .El .Ed .Pp AMI FastDisk Host Adapters that are true BusLogic MultiMaster clones are also supported by this driver. .Pp Tagged queueing is supported on 'W' series adapters, 'C' series adapters with firmware of rev 4.42 and higher, and 'S' series adapters with firmware of rev 3.35 and higher. .Pp Boards with certain firmware revisions may lock up under heavy load to -certain devices, especially if tagged queueing is used. Should you encounter +certain devices, especially if tagged queueing is used. +Should you encounter a problem with your adapter, contact Mylex technical support and ensure you have the latest firmware for your controller. .Sh SEE ALSO .Xr cd 4 , .Xr da 4 , .Xr sa 4 , .Xr scsi 4 .Sh AUTHORS .An -nosplit .An Julian Elischer wrote a driver for the Multimaster cards that appeared in the .Bx 386 -patch kit. The driver was rewritten by +patch kit. +The driver was rewritten by .An Justin T. Gibbs to take advantage of new board features and work with the CAM SCSI framework in .Fx 3.0 . .Pp Special thanks to .An Leonard N. Zubkoff for writing such a complete and well documented Mylex/BusLogic MultiMaster -driver for Linux. Support in this driver for the wide range of MultiMaster +driver for Linux. +Support in this driver for the wide range of MultiMaster controllers and firmware revisions, with their otherwise undocumented quirks, would not have been possible without his efforts. .Sh FILES .Bl -tag -width /usr/share/man0/template.doc -compact .It Pa sys/dev/buslogic/bt.c Core Driver Implementation .It Pa sys/dev/buslogic/btreg.h MultiMaster Register Set and Core Driver Data Structures .It Pa sys/pci/bt_pci.c PCI Bus Driver Attachment .It Pa sys/i386/eisa/bt_eisa.c EISA Bus Driver Attachment .It Pa sys/i386/isa/bt_isa.c ISA/VL Bus Driver Attachment .El .Sh HISTORY The .Nm driver first appeared in the .Bx 386 patch kit. Index: head/share/man/man4/cd.4 =================================================================== --- head/share/man/man4/cd.4 (revision 117010) +++ head/share/man/man4/cd.4 (revision 117011) @@ -1,481 +1,483 @@ .\" Copyright (c) 1996 .\" Julian Elischer . All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd October 10, 1998 .Dt CD 4 .Os .Sh NAME .Nm cd .Nd SCSI CD-ROM driver .Sh SYNOPSIS .Cd device cd .Cd "options ""CHANGER_MIN_BUSY_SECONDS=3""" .Cd "options ""CHANGER_MAX_BUSY_SECONDS=11"" .Sh DESCRIPTION The .Nm driver provides support for a .Tn SCSI .Tn CD-ROM (Compact Disc-Read Only Memory) drive. In an attempt to look like a regular disk, the .Nm driver synthesizes a partition table, with one partition covering the entire .Tn CD-ROM . It is possible to modify this partition table using .Xr disklabel 8 , but it will only last until the .Tn CD-ROM is unmounted. In general the interfaces are similar to those described by .Xr ad 4 and .Xr da 4 . .Pp As the .Tn SCSI adapter is probed during boot, the .Tn SCSI bus is scanned for devices. Any devices found which answer as CDROM (type 5) or WORM (type 4) type devices will be `attached' to the .Nm driver. Prior to .Fx 2.1 , the first device found will be attached as .Li cd0 the next, .Li cd1 , etc. Beginning in .Fx 2.1 it is possible to specify what cd unit a device should come on line as; refer to .Xr scsi 4 for details on kernel configuration. .Pp The system utility .Xr disklabel 8 may be used to read the synthesized disk label structure, which will contain correct figures for the size of the .Tn CD-ROM should that information be required. .Sh KERNEL CONFIGURATION Any number of .Tn CD-ROM devices may be attached to the system regardless of system configuration as all resources are dynamically allocated. .Sh IOCTLS The following .Xr ioctl 2 calls which apply to .Tn SCSI .Tn CD-ROM drives are defined in the header files .Aq Pa sys/cdio.h and .Aq Pa sys/disklabel.h . .Pp .Bl -tag -width CDIOCREADSUBCHANNEL .It Dv DIOCGDINFO .It Dv DIOCSDINFO .Pq Li "struct disklabel" Read or write the in-core copy of the disklabel for the drive. The disklabel is initialized with information read from the scsi inquiry commands, and should be the same as the information printed at boot. This structure is defined in .Xr disklabel 5 . .It Dv CDIOCCAPABILITY .Pq Li "struct ioc_capability" Retrieve information from the drive on what features it supports. The information is returned in the following structure: .Bd -literal -offset indent struct ioc_capability { u_long play_function; #define CDDOPLAYTRK 0x00000001 /* Can play tracks/index */ #define CDDOPLAYMSF 0x00000002 /* Can play msf to msf */ #define CDDOPLAYBLOCKS 0x00000004 /* Can play range of blocks */ #define CDDOPAUSE 0x00000100 /* Output can be paused */ #define CDDORESUME 0x00000200 /* Output can be resumed */ #define CDDORESET 0x00000400 /* Drive can be completely reset */ #define CDDOSTART 0x00000800 /* Audio can be started */ #define CDDOSTOP 0x00001000 /* Audio can be stopped */ #define CDDOPITCH 0x00002000 /* Audio pitch can be changed */ u_long routing_function; #define CDREADVOLUME 0x00000001 /* Volume settings can be read */ #define CDSETVOLUME 0x00000002 /* Volume settings can be set */ #define CDSETMONO 0x00000100 /* Output can be set to mono */ #define CDSETSTEREO 0x00000200 /* Output can be set to stereo (def) */ #define CDSETLEFT 0x00000400 /* Output can be set to left only */ #define CDSETRIGHT 0x00000800 /* Output can be set to right only */ #define CDSETMUTE 0x00001000 /* Output can be muted */ #define CDSETPATCH 0x00008000 /* Direct routing control allowed */ u_long special_function; #define CDDOEJECT 0x00000001 /* The tray can be opened */ #define CDDOCLOSE 0x00000002 /* The tray can be closed */ #define CDDOLOCK 0x00000004 /* The tray can be locked */ #define CDREADHEADER 0x00000100 /* Can read Table of Contents */ #define CDREADENTRIES 0x00000200 /* Can read TOC Entries */ #define CDREADSUBQ 0x00000200 /* Can read Subchannel info */ #define CDREADRW 0x00000400 /* Can read subcodes R-W */ #define CDHASDEBUG 0x00004000 /* The tray has dynamic debugging */ }; .Ed .It Dv CDIOCPLAYTRACKS .Pq Li "struct ioc_play_track" Start audio playback given a track address and length. The structure is defined as follows: .Bd -literal -offset indent struct ioc_play_track { u_char start_track; u_char start_index; u_char end_track; u_char end_index; }; .Ed .It Dv CDIOCPLAYBLOCKS .Pq Li "struct ioc_play_blocks" Start audio playback given a block address and length. The structure is defined as follows: .Bd -literal -offset indent struct ioc_play_blocks { int blk; int len; }; .Ed .It Dv CDIOCPLAYMSF .Pq Li "struct ioc_play_msf" Start audio playback given a `minutes-seconds-frames' address and length. The structure is defined as follows: .Bd -literal -offset indent struct ioc_play_msf { u_char start_m; u_char start_s; u_char start_f; u_char end_m; u_char end_s; u_char end_f; }; .Ed .It Dv CDIOCREADSUBCHANNEL .Pq Li "struct ioc_read_subchannel" Read information from the subchannel at the location specified by this structure: .Bd -literal -offset indent struct ioc_read_subchannel { u_char address_format; #define CD_LBA_FORMAT 1 #define CD_MSF_FORMAT 2 u_char data_format; #define CD_SUBQ_DATA 0 #define CD_CURRENT_POSITION 1 #define CD_MEDIA_CATALOG 2 #define CD_TRACK_INFO 3 u_char track; int data_len; struct cd_sub_channel_info *data; }; .Ed .It Dv CDIOREADTOCHEADER .Pq Li "struct ioc_toc_header" Return summary information about the table of contents for the mounted .Tn CD-ROM . The information is returned into the following structure: .Bd -literal -offset indent struct ioc_toc_header { u_short len; u_char starting_track; u_char ending_track; }; .Ed .It Dv CDIOREADTOCENTRYS .Pq Li "struct ioc_read_toc_entry" Return information from the table of contents entries mentioned. .Pq Yes, this command name is misspelled. The argument structure is defined as follows: .Bd -literal -offset indent struct ioc_read_toc_entry { u_char address_format; u_char starting_track; u_short data_len; struct cd_toc_entry *data; }; .Ed The requested data is written into an area of size .Li data_len and pointed to by .Li data . .It Dv CDIOCSETPATCH .Pq Li "struct ioc_patch" Attach various audio channels to various output channels. The argument structure is defined thusly: .Bd -literal -offset indent struct ioc_patch { u_char patch[4]; /* one for each channel */ }; .Ed .It Dv CDIOCGETVOL .It Dv CDIOCSETVOL .Pq Li "struct ioc_vol" Get (set) information about the volume settings of the output channels. The argument structure is as follows: .Bd -literal -offset indent struct ioc_vol { u_char vol[4]; /* one for each channel */ }; .Ed .It Dv CDIOCSETMONO Patch all output channels to all source channels. .It Dv CDIOCSETSTEREO Patch left source channel to the left output channel and the right source channel to the right output channel. .It Dv CDIOCSETMUTE Mute output without changing the volume settings. .It Dv CDIOCSETLEFT .It Dv CDIOCSETRIGHT Attach both output channels to the left (right) source channel. .It Dv CDIOCSETDEBUG .It Dv CDIOCCLRDEBUG Turn on (off) debugging for the appropriate device. .It Dv CDIOCPAUSE .It Dv CDIOCRESUME Pause (resume) audio play, without resetting the location of the read-head. .It Dv CDIOCRESET Reset the drive. .It Dv CDIOCSTART .It Dv CDIOCSTOP Tell the drive to spin-up (-down) the .Tn CD-ROM . .It Dv CDIOCALLOW .It Dv CDIOCPREVENT Tell the drive to allow (prevent) manual ejection of the .Tn CD-ROM -disc. Not all drives support this feature. +disc. +Not all drives support this feature. .It Dv CDIOCEJECT Eject the .Tn CD-ROM . .It Dv CDIOCCLOSE Tell the drive to close its door and load the media. Not all drives support this feature. .It Dv CDIOCPITCH .Pq Li "struct ioc_pitch" For drives that support it, this command instructs the drive to play the audio at a faster or slower rate than normal. Values of .Li speed between -32767 and -1 result in slower playback; a zero value indicates normal speed; and values from 1 to 32767 give faster playback. Drives with less than 16 bits of resolution will silently ignore less-significant bits. The structure is defined thusly: .Bd -literal -offset indent struct ioc_pitch { short speed; }; .Ed .El .Sh NOTES When a .Tn CD-ROM is changed in a drive controlled by the .Nm driver, then the act of changing the media will invalidate the disklabel and information held within the kernel. To stop corruption, all accesses to the device will be discarded until there are no more open file descriptors referencing the device. During this period, all new open attempts will be rejected. When no more open file descriptors reference the device, the first next open will load a new set of parameters (including disklabel) for the drive. .Pp The audio code in the .Nm driver only support .Tn SCSI-2 standard audio commands. -Because many +As many .Tn CD-ROM manufacturers have not followed the standard, there are many .Tn CD-ROM drives for which audio will not work. Some work is planned to support some of the more common `broken' .Tn CD-ROM drives; however, this is not yet under way. .Sh CHANGER OPERATION This driver has built-in support for LUN-based CD changers. A LUN-based CD changer is a drive that can hold two or more CDs, but only has one CD player mechanism. Each CD in the drive shows up as a separate logical unit on the .Tn SCSI -bus. The +bus. +The .Nm driver automatically recognizes LUN-based changers, and routes commands for changers through an internal scheduler. The scheduler prevents changer "thrashing", which is caused by sending commands to different LUNs in the changer at the same time. .Pp The scheduler honors minimum and maximum time quanta that the driver will spend on a particular LUN. The minimum time is the guaranteed minimum amount of time that the driver will spend on a given LUN, even if there is no outstanding I/O for that LUN. The maximum time is the maximum amount of time the changer will spend on a LUN if there is outstanding I/O for another LUN. If there is no outstanding I/O for another LUN, the driver will allow indefinite access to a given LUN. .Pp The minimum and maximum time quanta are configurable via kernel options and also via sysctl variables. The kernel options are: .Pp .Bl -item -compact .It .Cd "options ""CHANGER_MIN_BUSY_SECONDS=3""" .It .Cd "options ""CHANGER_MAX_BUSY_SECONDS=11""" .El .Pp The sysctl variables are: .Pp .Bl -item -compact .It .Va kern.cam.cd.changer.min_busy_seconds .It .Va kern.cam.cd.changer.max_busy_seconds .El .Pp It is suggested that the user try experimenting with the minimum and maximum timeouts via the sysctl variables to arrive at the proper values for your changer. Once you have settled on the proper timeouts for your changer, you can then put them in your kernel config file. .Pp If your system does have a LUN-based changer, you may notice that the probe messages for the various LUNs of the changer will continue to appear while the boot process is going on. This is normal, and is caused by the changer scheduling code. .Sh FILES .Bl -tag -width /dev/cd[0-9][a-h] -compact .It Pa /dev/cd[0-9][a-h] raw mode .Tn CD-ROM devices .El .Sh DIAGNOSTICS None. .Sh SEE ALSO .Xr da 4 , .Xr scsi 4 , .Xr disklabel 5 , .Xr disklabel 8 , .Xr cd 9 .Sh BUGS The names of the structures used for the third argument to .Fn ioctl were poorly chosen, and a number of spelling errors have survived in the names of the .Fn ioctl commands. .Pp There is no mechanism currently to set different minimum and maximum timeouts for different CD changers; the timeout values set by the kernel options or the sysctl variables apply to all LUN-based CD changers in the system. It is possible to implement such support, but the sysctl implementation at least would be rather inelegant, because of the current inability of the sysctl code to handle the addition of nodes after compile time. Thus, it would take one dynamically sized sysctl variable and a userland utility to get/set the timeout values. Implementation of separate timeouts for different CD devices in the kernel config file would likely require modification of .Xr config 8 to support the two timeouts when hardwiring .Nm devices. .Sh HISTORY This .Nm driver is based upon the .Nm driver written by Julian Elischer, which appeared in .Bx 386 0.1 . The CAM version of the .Nm driver was written by Kenneth Merry and first appeared in .Fx 3.0 . Index: head/share/man/man4/ch.4 =================================================================== --- head/share/man/man4/ch.4 (revision 117010) +++ head/share/man/man4/ch.4 (revision 117011) @@ -1,308 +1,353 @@ .\" $FreeBSD$ .\" Copyright (c) 1996 .\" Julian Elischer . All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd May 14, 1998 .Dt CH 4 .Os .Sh NAME .Nm ch .Nd SCSI media-changer (juke box) driver .Sh SYNOPSIS .Cd device ch .Cd device ch1 target 4 unit 0 .Sh DESCRIPTION The .Xr ch driver provides support for a .Em SCSI media changer. It allows many slots of media to be multiplexed between -a number of drives. The changer device may optionally be equipped +a number of drives. +The changer device may optionally be equipped with a bar code reader, which reads label information attached to the media. .Pp A SCSI adapter must also be separately configured into the system before a SCSI changer can be configured. .Pp As the SCSI adapter is probed during boot, the .Em SCSI bus is scanned for devices. Any devices found which answer as 'Changer' type devices will be 'attached' to the .Nm driver. In .Fx releases prior to 2.1, the first found will be attached as .Em ch0 and the next, .Em ch1 etc. Beginning in 2.1 it is possible to specify what ch unit a device should come on line as; refer to .Xr scsi 4 for details on kernel configuration. .Sh KERNEL CONFIGURATION In configuring, if an optional .Ar count is given in the specification, that number of SCSI media changers are configured; Most storage for them is allocated only when found so a large number of configured devices is cheap. (once the first has included the driver). .Sh IOCTLS User mode programs communicate with the changer driver through a -number of ioctls which are described below. Changer element addresses +number of ioctls which are described below. +Changer element addresses used in the communication between the kernel and the changer device are -mapped to zero-based logical addresses. Element types are specified -as follows: +mapped to zero-based logical addresses. +Element types are specified as follows: .Bl -tag -width CHET_MT .It Dv CHET_MT Medium transport element (picker). .It Dv CHET_ST Storage element (slot). .It Dv CHET_IE Import/export element (portal). .It Dv CHET_DT Data transfer element (drive). .El .Pp The following .Xr ioctl 2 calls apply to the changer. They are defined in the header file .Aq Pa sys/chio.h . .Pp .Bl -tag -width CHIOEXCHANGE .It Dv CHIOMOVE -.Pq Li "struct changer_move" -Move a medium from one element to another (\fBMOVE MEDIUM\fR) using -the current picker. The source and destination elements are specified +.Pq Vt "struct changer_move" +Move a medium from one element to another +.Pq Sy "MOVE MEDIUM" +using the current picker. +The source and destination elements are specified in a changer_move structure, which includes at least the following fields: .Bd -literal -offset indent u_int cm_fromtype; /* element type to move from */ u_int cm_fromunit; /* logical unit of from element */ u_int cm_totype; /* element type to move to */ u_int cm_tounit; /* logical unit of to element */ u_int cm_flags; /* misc. flags */ .Ed -If the \fBCM_INVERT\fR in the \fBcm_flags\fR field is set, the medium +If the +.Dv CM_INVERT +in the +.Va cm_flags +field is set, the medium changer is instructed to flip the medium while moving it. .It Dv CHIOEXCHANGE -.Pq Li "struct changer_exchange" +.Pq Vt "struct changer_exchange" Move the medium located in the source element to the first destination element, and move the medium that had been in the first destination -element to the second destination element. In case of a simple +element to the second destination element. +In case of a simple exchange, the source and second destination elements should be the -same. The current picker is used to perform the operation. The -addresses of the affected elements is specified to the ioctl in a -changer_exchange structure which includes at least the following +same. +The current picker is used to perform the operation. +The addresses of the affected elements is specified to the ioctl in a +.Vt changer_exchange +structure which includes at least the following fields: .Bd -literal -offset indent u_int ce_srctype; /* element type of source */ u_int ce_srcunit; /* logical unit of source */ u_int ce_fdsttype; /* element type of first destination */ u_int ce_fdstunit; /* logical unit of first destination */ u_int ce_sdsttype; /* element type of second destination */ u_int ce_sdstunit; /* logical unit of second destination */ u_int ce_flags; /* misc. flags */ .Ed -In \fBce_flags\fR, \fBCM_INVERT1\fR and/or \fBCM_INVERT2\fR may be set +In +.Va ce_flags , +.Dv CM_INVERT1 +and/or +.Dv CM_INVERT2 +may be set to flip the first or second medium during the exchange operation, respectively. .Pp -\fIThis operation is untested.\fR +.Em This operation is untested . .It Dv CHIOPOSITION -.Pq Li "struct changer_position" -Position the current picker in front of the specified element. The -element is specified with a changer_position structure, which includes +.Pq Vt "struct changer_position" +Position the current picker in front of the specified element. +The element is specified with a changer_position structure, which includes at least the following elements: .Bd -literal -offset indent u_int cp_type; /* element type */ u_int cp_unit; /* logical unit of element */ u_int cp_flags; /* misc. flags */ .Ed -The \fBcp_flags\fR field may be set to \fBCP_INVERT\fR to invert the -picker during the operation. +The +.Va cp_flags +field may be set to +.Dv CP_INVERT +to invert the picker during the operation. .It Dv CHIOGPICKER -.Pq Li "int" +.Pq Vt int Return the logical address of the current picker. .It Dv CHIOSPICKER -.Pq Li "int" +.Pq Vt int Select the picker specified by the given logical address. .It Dv CHIOGPARAMS -.Pq Li "struct changer_params" -Return the configuration parameters for the media changer. This ioctl +.Pq Vt "struct changer_params" +Return the configuration parameters for the media changer. +This ioctl fills the changer_params structure passed by the user with at least the following fields: .Bd -literal -offset indent u_int cp_npickers; /* number of pickers */ u_int cp_nslots; /* number of slots */ u_int cp_nportals; /* number of import/export portals */ u_int cp_ndrives; /* number of drives */ .Ed .Pp This call can be used by applications to query the dimensions of -the jukebox before using the \fBCHIGSTATUS\fR +the jukebox before using the +.Dv CHIGSTATUS ioctl to query the jukebox' status. .It Dv CHIOIELEM -Perform the \fBINITIALIZE ELEMENT STATUS\fR call on the media changer -device. This forces the media changer to update its internal status -information with respect to loaded media. It also scans any barcode -labels provided that it has a label reader. The +Perform the +.Sy INITIALIZE ELEMENT STATUS +call on the media changer device. +This forces the media changer to update its internal status +information with respect to loaded media. +It also scans any barcode labels provided that it has a label reader. +The .Nm driver's status is not affected by this call. .It Dv CHIOGSTATUS -.Pq Li "struct changer_element_status_request" -Perform the \fBREAD ELEMENT STATUS\fR call on the media changer -device. This call reads the element status information of the media -changer and converts it to an array of \fBchanger_element_status\fR +.Pq Vt "struct changer_element_status_request" +Perform the +.Sy READ ELEMENT STATUS +call on the media changer device. +This call reads the element status information of the media +changer and converts it to an array of +.Vt changer_element_status structures. .Pp With each call to .Dv CHIOGSTATUS , the status of one or more elements of one type may be queried. .Pp -The application passes a changer_element_status_request structure to the +The application passes a +.Vt changer_element_status_request +structure to the .Nm driver which contains the following fields: .Bd -literal -offset indent u_int cesr_element_type; u_int cesr_element_base; u_int cesr_element_count; u_int cesr_flags; struct changer_element_status *cesr_element_status; .Ed .Pp This structure is read by the driver to determine the type, logical base address and number of elements for which information is to be -returned in the array of changer_element_status structures pointed to -by the cesr_element_status field. The application must allocate enough -memory for cesr_element_count status structures (see below). -The cesr_flags can optionally be set to +returned in the array of +.Vt changer_element_status +structures pointed to by the +.Va cesr_element_status field . +The application must allocate enough +memory for +.Va cesr_element_count +status structures (see below). +The +.Va cesr_flags +can optionally be set to .Dv CESR_VOLTAGS to indicate that volume tag (bar code) information is to be read from the jukebox and returned. .Pp -The cesr_element_base and cesr_element_count fields must be valid with -respect to the physical configuration of the changer. If they are -not, the +The +.Va cesr_element_base +and +.Va cesr_element_count +fields must be valid with respect to the physical configuration of the changer. +If they are not, the .Dv CHIOGSTATUS ioctl returns the .Er EINVAL error code. .Pp The information about the elements is returned in an array of -changer_element_status structures. This structure include at least -the following fields: +.Vt changer_element_status +structures. +This structure include at least the following fields: .Bd -literal -offset indent u_int ces_addr; /* element address in media changer */ u_char ces_flags; /* see CESTATUS definitions below */ u_char ces_sensecode; /* additional sense code for element */ u_char ces_sensequal; /* additional sense code qualifier */ u_char ces_invert; /* invert bit */ u_char ces_svalid; /* source address (ces_source) valid */ u_short ces_source; /* source address of medium */ changer_voltag_t ces_pvoltag; /* primary volume tag */ changer_voltag_t ces_avoltag; /* alternate volume tag */ u_char ces_idvalid; /* ces_scsi_id is valid */ u_char ces_scsi_id; /* SCSI id of element (if ces_idvalid is nonzero) */ u_char ces_lunvalid; /* ces_scsi_lun is valid */ u_char ces_scsi_lun; /* SCSI lun of element (if ces_lunvalid is nonzero) */ .Ed .Pp -The ces_addr field contains the address of the element in the -coordinate system of the media changer. It is not used by the driver, +The +.Va ces_addr +field contains the address of the element in the +coordinate system of the media changer. +It is not used by the driver, and should be used for diagnostic purposes only. .Pp -The following flags are defined for the \fBces_flags\fR field: +The following flags are defined for the +.Va ces_flags +field: .Bl -tag -width CESTATUS_IMPEXP .It Dv CESTATUS_FULL A medium is present. .It Dv CESTATUS_IMPEXP The medium has been deposited by the operator (and not by a picker). .It Dv CESTATUS_EXCEPT The element is in an exceptional state (e.g. invalid barcode label, barcode not yet scanned). .It Dv CESTATUS_ACCESS The element is accessible by the picker. .It Dv CESTATUS_EXENAB The element supports medium export. .It Dv CESTATUS_INENAB The element supports medium import. .El .Pp Note that not all flags are valid for all element types. .El .Sh NOTES This version of the .Nm driver has been tested with a DEC TZ875 (5 slot, one DLT drive) and a and a Breece Hill Q47 (60 slot, four DLT drives, barcode reader). .Pp Many of the features the .Nm driver supports are not throughly tested due to the fact that the devices available for testing do not support the necessary commands. This is true for alternate volume tags, media flipping, import/export element handling, multiple picker operation and other things. .Sh AUTHORS .An -nosplit The .Nm driver was written by .An Jason R. Thorpe Aq thorpej@and.com for And Communications, .Pa http://www.and.com/ . It was added to the system by .An Stefan Grefen Aq grefen@goofy.zdv.uni-mainz.de who apparently had such a device. It was ported to CAM by .An Kenneth Merry Aq ken@FreeBSD.org . It was updated to support volume tags by .An Hans Huebner Aq hans@artcom.de . .Sh FILES .Bl -tag -width /dev/ch[0-9] -compact .It Pa /dev/ch[0-9] device entries .El .Sh DIAGNOSTICS If the media changer does not support features requested by the .Nm driver, it will produce both console error messages and failure return codes to the ioctls described here. .Sh SEE ALSO .Xr chio 1 , .Xr cd 4 , .Xr da 4 , .Xr sa 4 .Sh HISTORY The .Nm driver appeared in .Bx 386 0.1 . Index: head/share/man/man4/da.4 =================================================================== --- head/share/man/man4/da.4 (revision 117010) +++ head/share/man/man4/da.4 (revision 117011) @@ -1,296 +1,309 @@ .\" Copyright (c) 1996 .\" Julian Elischer . All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd October 15, 1998 .Dt DA 4 .Os .Sh NAME .Nm da .Nd SCSI Direct Access device driver .Sh SYNOPSIS .Cd device da .Sh DESCRIPTION The .Nm driver provides support for all .Tn SCSI devices of the direct access class that are attached to the system through a supported .Tn SCSI Host Adapter. The direct access class includes disk, magneto-optical, and solid-state devices. .Pp A .Tn SCSI Host adapter must also be separately configured into the system before a .Tn SCSI direct access device can be configured. .Sh PARTITIONING The .Nm driver allows the disk to have two levels of partitioning. One layer, called the .Dq slice layer , is used to separate the .Fx areas of the disk from areas used by other operating systems. The second layer is the native .Bx 4.4 partitioning scheme, .Xr disklabel 5 , which is used to subdivide the .Fx slices into areas for individual file systems and swap spaces. For more information, see .Xr fdisk 8 and .Xr disklabel 8 , respectively. .Pp If an uninitialized disk is opened, the slice table will be initialized with a fictitious .Fx -slice spanning the entire disk. Similarly, if an uninitialized +slice spanning the entire disk. +Similarly, if an uninitialized (or .No non- Ns Fx ) slice is opened, its disklabel will be initialized with parameters returned by the drive and a single .Sq Li c partition encompassing the entire slice. .Sh CACHE EFFECTS Many direct access devices are equipped with read and/or write caches. Parameters affecting the device's cache are stored in mode page 8, -the caching control page. Mode pages can be examined and modified -via the +the caching control page. +Mode pages can be examined and modified via the .Xr camcontrol 8 utility. .Pp The read cache is used to store data from device-initiated read ahead -operations as well as frequently used data. The read cache is transparent +operations as well as frequently used data. +The read cache is transparent to the user and can be enabled without any adverse effect. Most devices -with a read cache come from the factory with it enabled. The read cache -can be disabled by setting the +with a read cache come from the factory with it enabled. +The read cache can be disabled by setting the .Tn RCD (Read Cache Disable) bit in the caching control mode page. .Pp The write cache can greatly decrease the latency of write operations and allows the device to reorganize writes to increase efficiency and -performance. This performance gain comes at a price. Should the device +performance. +This performance gain comes at a price. +Should the device lose power while its cache contains uncommitted write operations, these -writes will be lost. The effect of a loss of write transactions on -a file system is non-deterministic and can cause corruption. Most +writes will be lost. +The effect of a loss of write transactions on +a file system is non-deterministic and can cause corruption. +Most devices age write transactions to limit vulnerability to a few transactions recently reported as complete, but it is none-the-less recommended that systems with write cache enabled devices reside on an Uninterruptible -Power Supply (UPS). The +Power Supply (UPS). +The .Nm device driver ensures that the cache and media are synchronized upon -final close of the device or an unexpected shutdown (panic) event. This -ensures that it is safe to disconnect power once the operating system -has reported that it has halted. The write cache can be enabled by -setting the +final close of the device or an unexpected shutdown (panic) event. +This ensures that it is safe to disconnect power once the operating system +has reported that it has halted. +The write cache can be enabled by setting the .Tn WCE (Write Cache Enable) bit in the caching control mode page. .Sh TAGGED QUEUING The .Nm device driver will take full advantage of the SCSI feature known as tagged -queueing. Tagged queueing allows the device to process multiple transactions +queueing. +Tagged queueing allows the device to process multiple transactions concurrently, often re-ordering them to reduce the number and length of -seeks. To ensure that transactions to distant portions of the media, +seeks. +To ensure that transactions to distant portions of the media, which may be deferred indefinitely by servicing requests nearer the current head position, are completed in a timely fashion, an ordered tagged transaction is sent every 15 seconds during continuous device operation. .Sh BAD BLOCK RECOVERY Direct Access devices have the capability of mapping out portions of -defective media. Media recovery parameters are located in mode page 1, -the Read-Write Error Recovery mode page. The most important media +defective media. +Media recovery parameters are located in mode page 1, +the Read-Write Error Recovery mode page. +The most important media remapping features are 'Auto Write Reallocation' and 'Auto Read Reallocation' which can be enabled via the AWRE and ARRE bits, respectively, of the Read-Write Error Recovery page. Many devices do not ship from the factory with these feature enabled. Mode pages can be examined and modified via the .Xr camcontrol 8 utility. .Sh KERNEL CONFIGURATION It is only necessary to explicitly configure one .Nm device; data structures are dynamically allocated as disks are found on the .Tn SCSI bus. .Sh IOCTLS The following .Xr ioctl 2 calls apply to .Tn SCSI -disks as well as to other disks. They are defined in the header file +disks as well as to other disks. +They are defined in the header file .Aq Pa sys/disklabel.h . .Pp .Bl -tag -width DIOCSDINFO .It Dv DIOCSBAD Usually used to set up a bad-block mapping system on the disk. .Tn SCSI drives incorporate their own bad-block mapping so this command is not implemented. .It Dv DIOCGDINFO Read, from the kernel, the in-core copy of the disklabel for the drive. This may be a fictitious disklabel if the drive has never been initialized, in which case it will contain information read from the .Tn SCSI inquiry commands. .It Dv DIOCSDINFO Give the driver a new disklabel to use. The driver .Em will not write the new disklabel to the disk. .It Dv DIOCWLABEL Enable or disable the driver's software write protect of the disklabel on the disk. .It Dv DIOCWDINFO Give the driver a new disklabel to use. The driver .Em will write the new disklabel to the disk. .El .Sh NOTES If a device becomes invalidated (media is removed, device becomes unresponsive) the disklabel and information held within the kernel about the device will -be invalidated. To avoid corruption of a newly inserted piece of media or +be invalidated. +To avoid corruption of a newly inserted piece of media or a replacement device, all accesses to the device will be discarded until -the last file descriptor referencing the old device is closed. During this -period, all new open attempts will be rejected. +the last file descriptor referencing the old device is closed. +During this period, all new open attempts will be rejected. .Sh FILES .Bl -tag -width /dev/rsdXXXXX -compact .It Pa /dev/rda Ns Ar u raw mode .Tn SCSI disk unit .Ar u , accessed as an unpartitioned device .Sm off .It Pa /dev/da Ar u Pa s Ar n .Sm on block mode .Tn SCSI disk unit .Ar u , slice .Ar n , accessed as an unpartitioned device .Sm off .It Pa /dev/rda Ar u Pa s Ar n .Sm on raw mode .Tn SCSI disk unit .Ar u , slice .Ar n , accessed as an unpartitioned device .It Pa /dev/da Ns Ar u Ns Ar p block mode .Tn SCSI disk unit .Ar u , first .Fx slice, partition .Ar p .It Pa /dev/rda Ns Ar u Ns Ar p raw mode .Tn SCSI disk unit .Ar u , first .Fx slice, partition .Ar p .Sm off .It Xo .Pa /dev/da .Ar u .Pa s .Ar n .Ar p .Xc .Sm on block mode .Tn SCSI disk unit .Ar u , .Ar n Ns th slice, partition .Ar p .Sm off .It Xo .Pa /dev/rda .Ar u .Pa s .Ar n .Ar p .Xc .Sm on raw mode .Tn SCSI disk unit .Ar u , .Ar n Ns th slice, partition .Ar p .El .Sh DIAGNOSTICS None. .Sh SEE ALSO .Xr ad 4 , .Xr disklabel 5 , .Xr disklabel 8 , .Xr fdisk 8 .Sh HISTORY The .Nm driver was written for the .Tn CAM .Tn SCSI subsystem by .An Justin T. Gibbs . Many ideas were gleaned from the .Nm sd device driver written and ported from .Tn Mach 2.5 by .An Julian Elischer . Support for slices was written by .An Bruce Evans . Index: head/share/man/man4/ddb.4 =================================================================== --- head/share/man/man4/ddb.4 (revision 117010) +++ head/share/man/man4/ddb.4 (revision 117011) @@ -1,588 +1,605 @@ .\" .\" Mach Operating System .\" Copyright (c) 1991,1990 Carnegie Mellon University .\" All Rights Reserved. .\" .\" Permission to use, copy, modify and distribute this software and its .\" documentation is hereby granted, provided that both the copyright .\" notice and this permission notice appear in all copies of the .\" software, derivative works or modified versions, and any portions .\" thereof, and that both notices appear in supporting documentation. .\" .\" CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS" .\" CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR .\" ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE. .\" .\" Carnegie Mellon requests users of this software to return to .\" .\" Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU .\" School of Computer Science .\" Carnegie Mellon University .\" Pittsburgh PA 15213-3890 .\" .\" any improvements or extensions that they make and grant Carnegie Mellon .\" the rights to redistribute these changes. .\" .\" changed a \# to #, since groff choked on it. .\" .\" HISTORY .\" ddb.4,v .\" Revision 1.1 1993/07/15 18:41:02 brezak .\" Man page for DDB .\" .\" Revision 2.6 92/04/08 08:52:57 rpd .\" Changes from OSF. .\" [92/01/17 14:19:22 jsb] .\" Changes for OSF debugger modifications. .\" [91/12/12 tak] .\" .\" Revision 2.5 91/06/25 13:50:22 rpd .\" Added some watchpoint explanation. .\" [91/06/25 rpd] .\" .\" Revision 2.4 91/06/17 15:47:31 jsb .\" Added documentation for continue/c, match, search, and watchpoints. .\" I've not actually explained what a watchpoint is; maybe Rich can .\" do that (hint, hint). .\" [91/06/17 10:58:08 jsb] .\" .\" Revision 2.3 91/05/14 17:04:23 mrt .\" Correcting copyright .\" .\" Revision 2.2 91/02/14 14:10:06 mrt .\" Changed to new Mach copyright .\" [91/02/12 18:10:12 mrt] .\" .\" Revision 2.2 90/08/30 14:23:15 dbg .\" Created. .\" [90/08/30 dbg] .\" .\" $FreeBSD$ .Dd January 16, 1996 .Dt DDB 4 .Os .Sh NAME .Nm ddb .Nd interactive kernel debugger .Sh SYNOPSIS .Cd options DDB .Pp To prevent activation of the debugger on kernel .Xr panic 9 : .Cd options DDB_UNATTENDED .Sh DESCRIPTION The .Nm kernel debugger has most of the features of the old kdb, but with a more rational syntax inspired by .Xr gdb 1 . If linked into the running kernel, it can be invoked locally with the .Ql debug .Xr keymap 5 action. The debugger is also invoked on kernel .Xr panic 9 if the .Va debug.debugger_on_panic .Xr sysctl 8 MIB variable is set non-zero, which is the default unless the .Dv DDB_UNATTENDED option is specified. .Pp -The current location is called `dot'. The `dot' is displayed with +The current location is called `dot'. +The `dot' is displayed with a hexadecimal format at a prompt. Examine and write commands update `dot' to the address of the last line examined or the last location modified, and set `next' to the address of the next location to be examined or changed. Other commands don't change `dot', and set `next' to be the same as `dot'. .Pp The general command syntax is: .Cm command Ns Op Li \&/ Ns Ar modifier .Ar address Ns Op Li , Ns Ar count .Pp A blank line repeats the previous command from the address `next' with -count 1 and no modifiers. Specifying +count 1 and no modifiers. +Specifying .Ar address sets `dot' to the -address. Omitting +address. +Omitting .Ar address -uses `dot'. A missing +uses `dot'. +A missing .Ar count is taken to be 1 for printing commands or infinity for stack traces. .Pp The .Nm debugger has a feature like the .Xr more 1 command -for the output. If an output line exceeds the number set in the +for the output. +If an output line exceeds the number set in the .Li \&$lines variable, it displays .Dq Em --db_more-- and waits for a response. The valid responses for it are: .Pp .Bl -tag -compact -width SPC .It Li SPC one more page .It Li RET one more line .It Li q abort the current command, and return to the command input mode .El .Pp Finally, .Nm provides a small (currently 10 items) command history, and offers -simple emacs-style command line editing capabilities. In addition to +simple emacs-style command line editing capabilities. +In addition to the emacs control keys, the usual ANSI arrow keys might be used to browse through the history buffer, and move the cursor within the current line. .Sh COMMANDS .Bl -ohang .It Cm examine .It Cm x Display the addressed locations according to the formats in the modifier. Multiple modifier formats display multiple locations. If no format is specified, the last formats specified for this command is used. .Pp The format characters are: .Bl -tag -compact -width indent .It Li b look at by bytes (8 bits) .It Li h look at by half words (16 bits) .It Li l look at by long words (32 bits) .It Li a print the location being displayed .It Li A print the location with a line number if possible .It Li x display in unsigned hex .It Li z display in signed hex .It Li o display in unsigned octal .It Li d display in signed decimal .It Li u display in unsigned decimal .It Li r display in current radix, signed .It Li c display low 8 bits as a character. Non-printing characters are displayed as an octal escape code (e.g., `\e000'). .It Li s display the null-terminated string at the location. Non-printing characters are displayed as octal escapes. .It Li m display in unsigned hex with character dump at the end of each line. The location is also displayed in hex at the beginning of each line. .It Li i display as an instruction .It Li I display as an instruction with possible alternate formats depending on the machine: .Bl -tag -width MIPS -compact .It Tn VAX don't assume that each external label is a procedure entry mask .It Tn i386 don't round to the next long word boundary .It Tn MIPS print register contents .El .El .It Cm xf Examine forward: Execute an examine command with the last specified parameters to it except that the next address displayed by it is used as the start address. .It Cm xb Examine backward: Execute an examine command with the last specified parameters to it except that the last start address subtracted by the size displayed by it is used as the start address. .It Cm print Ns Op Cm /acdoruxz Print .Ar addr Ns s according to the modifier character (as described above for .Li examine ) . Valid formats are: .Li a , .Li x , .Li z , .Li o , .Li d , .Li u , .Li r , and .Li c . If no modifier is specified, the last one specified to it is used. .Ar addr -can be a string, in which case it is printed as it is. For example: +can be a string, in which case it is printed as it is. +For example: .Bd -literal -offset indent print/x \&"eax = \&" $eax \&"\enecx = \&" $ecx \&"\en\&" .Ed .Pp will print like: .Bd -literal -offset indent eax = xxxxxx ecx = yyyyyy .Ed .It Xo .Cm write Ns Op Cm /bhl .Ar addr Ar expr1 Op Ar "expr2 ..." .Xc Write the expressions specified after .Ar addr on the command line at succeeding locations starting with .Ar addr The write unit size can be specified in the modifier with a letter .Li b (byte), .Li h (half word) or .Li l -(long word) respectively. If omitted, +(long word) respectively. +If omitted, long word is assumed. .Pp .Sy Warning : since there is no delimiter between expressions, strange things may happen. It's best to enclose each expression in parentheses. .It Xo .Cm set .Li \&$ Ns Ar variable .Op Li = .Ar expr .Xc Set the named variable or register with the value of .Ar expr . Valid variable names are described below. .It Cm break Ns Op Cm /u Set a break point at .Ar addr . If .Ar count is supplied, continues .Ar count - 1 times before stopping at the -break point. If the break point is set, a break point number is +break point. +If the break point is set, a break point number is printed with .Sq Li \&# . This number can be used in deleting the break point or adding conditions to it. .Pp If the .Li u modifier is specified, this command sets a break point in user space -address. Without the +address. +Without the .Li u option, the address is considered in the kernel space, and wrong space address is rejected with an error message. This modifier can be used only if it is supported by machine dependent routines. .Pp .Sy Warning : If a user text is shadowed by a normal user space debugger, -user space break points may not work correctly. Setting a break +user space break points may not work correctly. +Setting a break point at the low-level code paths may also cause strange behavior. .It Cm delete Ar addr .It Cm delete Li \&# Ns Ar number Delete the break point. The target break point can be specified by a break point number with .Li # , or by using the same .Ar addr specified in the original .Cm break command. .It Cm step Ns Op Cm /p Single step .Ar count times (the comma is a mandatory part of the syntax). If the .Li p modifier is specified, print each instruction at each step. Otherwise, only print the last instruction. .Pp .Sy Warning : depending on machine type, it may not be possible to single-step through some low-level code paths or user space code. On machines with software-emulated single-stepping (e.g., pmax), stepping through code executed by interrupt handlers will probably do the wrong thing. .It Cm continue Ns Op Cm /c Continue execution until a breakpoint or watchpoint. If the .Li c modifier is specified, count instructions while executing. Some machines (e.g., pmax) also count loads and stores. .Pp .Sy Warning : when counting, the debugger is really silently single-stepping. This means that single-stepping on low-level code may cause strange behavior. .It Cm until Ns Op Cm /p Stop at the next call or return instruction. If the .Li p modifier is specified, print the call nesting depth and the -cumulative instruction count at each call or return. Otherwise, +cumulative instruction count at each call or return. +Otherwise, only print when the matching return is hit. .It Cm next Ns Op Cm /p .It Cm match Ns Op Cm /p Stop at the matching return instruction. If the .Li p modifier is specified, print the call nesting depth and the -cumulative instruction count at each call or return. Otherwise, -only print when the matching return is hit. +cumulative instruction count at each call or return. +Otherwise, only print when the matching return is hit. .It Xo .Cm trace Ns Op Cm /u .Op Ar frame .Op , Ns Ar count .Xc -Stack trace. The +Stack trace. +The .Li u option traces user space; if omitted, .Cm trace only traces kernel space. .Ar count is the number of frames to be traced. If .Ar count is omitted, all frames are printed. .Pp .Sy Warning : User space stack trace is valid only if the machine dependent code supports it. .It Xo .Cm search Ns Op Cm /bhl .Ar addr .Ar value .Op Ar mask .Op , Ns Ar count .Xc Search memory for .Ar value . This command might fail in interesting -ways if it doesn't find the searched-for value. This is because -ddb doesn't always recover from touching bad memory. The optional +ways if it doesn't find the searched-for value. +This is because ddb doesn't always recover from touching bad memory. +The optional .Ar count argument limits the search. .It Cm show all procs Ns Op Cm /m .It Cm ps Ns Op Cm /m Display all process information. The process information may not be shown if it is not supported in the machine, or the bottom of the stack of the target process is not in the main memory at that time. The .Li m modifier will alter the display to show VM map addresses for the process and not show other info. .It Cm show registers Ns Op Cm /u Display the register set. If the .Li u option is specified, it displays user registers instead of kernel or currently saved one. .Pp .Sy Warning : The support of the .Li u -modifier depends on the machine. If -not supported, incorrect information will be displayed. +modifier depends on the machine. +If not supported, incorrect information will be displayed. .It Xo .Cm show map Ns Op Cm /f .Ar addr .Xc Prints the VM map at .Ar addr . If the .Li f modifier is specified the complete map is printed. .It Xo .Cm show object Ns Op Cm /f .Ar addr .Xc Prints the VM object at .Ar addr . If the .Li f option is specified the complete object is printed. .It Cm "show watches" Displays all watchpoints. .It Cm reset Hard reset the system. .It Xo .Cm watch .Ar addr Ns Li \&, Ns Ar size .Xc -Set a watchpoint for a region. Execution stops -when an attempt to modify the region occurs. +Set a watchpoint for a region. +Execution stops when an attempt to modify the region occurs. The .Ar size argument defaults to 4. If you specify a wrong space address, the request is rejected with an error message. .Pp .Sy Warning : Attempts to watch wired kernel memory may cause unrecoverable error in some systems such as i386. Watchpoints on user addresses work best. .It Xo .Cm hwatch .Ar addr Ns Li \&, Ns Ar size .Xc Set a hardware watchpoint for a region if supported by the -architecture. Execution stops when an attempt to modify the region -occurs. The +architecture. +Execution stops when an attempt to modify the region occurs. +The .Ar size argument defaults to 4. .Pp .Sy Warning : The hardware debug facilities do not have a concept of separate -address spaces like the watch command does. Use +address spaces like the watch command does. +Use .Cm hwatch for setting watchpoints on kernel address locations only, and avoid its use on user mode address spaces. .It Xo .Cm dhwatch .Ar addr Ns Li \&, Ns Ar size .Xc Delete specified hardware watchpoint. .It Cm gdb -Toggles between remote GDB and DDB mode. In remote GDB mode, another -machine is required that runs +Toggles between remote GDB and DDB mode. +In remote GDB mode, another machine is required that runs .Xr gdb 1 using the remote debug feature, with a connection to the serial -console port on the target machine. Currently only available on the +console port on the target machine. +Currently only available on the .Em i386 and .Em Alpha architectures. .It Cm help Print a short summary of the available commands and command abbreviations. .El .Sh VARIABLES The debugger accesses registers and variables as .Li \&$ Ns Em name . Register names are as in the .Dq Cm show registers command. Some variables are suffixed with numbers, and may have some modifier following a colon immediately after the variable name. For example, register variables can have a .Li u modifier to indicate user register (e.g., .Li $eax:u ) . .Pp Built-in variables currently supported are: .Bl -tag -width tabstops -compact .It Li radix Input and output radix .It Li maxoff Addresses are printed as 'symbol'+offset unless offset is greater than maxoff. .It Li maxwidth The width of the displayed line. .It Li lines The number of lines. It is used by "more" feature. .It Li tabstops Tab stop width. .It Li work Ns Ar xx Work variable. .Ar xx can be 0 to 31. .El .Sh EXPRESSIONS Almost all expression operators in C are supported except .Sq Li \&~ , .Sq Li \&^ , and unary .Sq Li \&& . Special rules in .Nm are: .Bl -tag -width Identifiers .It Em Identifiers The name of a symbol is translated to the value of the symbol, which is the address of the corresponding object. .Sq Li \&. and .Sq Li \&: can be used in the identifier. If supported by an object format dependent routine, .Sm off .Oo Em filename : Oc Em func : lineno , .Sm on .Oo Em filename : Oc Ns Em variable , and .Oo Em filename : Oc Ns Em lineno can be accepted as a symbol. .It Em Numbers Radix is determined by the first two letters: .Li 0x : hex, .Li 0o : octal, .Li 0t : decimal; otherwise, follow current radix. .It Li \&. `dot' .It Li \&+ `next' .It Li \&.. address of the start of the last line examined. Unlike `dot' or `next', this is only changed by .Dq Li examine or .Dq Li write command. .It Li \&' last address explicitly specified. .It Li \&$ Ns Em variable Translated to the value of the specified variable. It may be followed by a .Li : and modifiers as described above. .It Em a Ns Li \&# Ns Em b a binary operator which rounds up the left hand side to the next multiple of right hand side. .It Li \&* Ns Em expr indirection. It may be followed by a .Sq Li : and modifiers as described above. .El .Sh HINTS On machines with an ISA expansion bus, a simple NMI generation card can be constructed by connecting a push button between the A01 and B01 (CHCHK# and GND) card fingers. Momentarily shorting these two fingers together may cause the bridge chipset to generate an NMI, which causes the kernel to pass control to .Nm . Some bridge chipsets do not generate a NMI on CHCHK#, so your mileage may vary. The NMI allows one to break into the debugger on a wedged machine to diagnose problems. Other bus' bridge chipsets may be able to generate NMI using bus specific methods. .Sh SEE ALSO .Xr gdb 1 .Sh HISTORY The .Nm debugger was developed for Mach, and ported to .Bx 386 0.1 . This manual page translated from .Fl man macros by Garrett Wollman. Index: head/share/man/man4/divert.4 =================================================================== --- head/share/man/man4/divert.4 (revision 117010) +++ head/share/man/man4/divert.4 (revision 117011) @@ -1,168 +1,171 @@ .\" $FreeBSD$ .\" .Dd June 18, 1996 .Dt DIVERT 4 .Os .Sh NAME .Nm divert .Nd kernel packet diversion mechanism .Sh SYNOPSIS .In sys/types.h .In sys/socket.h .In netinet/in.h .Ft int .Fn socket PF_INET SOCK_RAW IPPROTO_DIVERT .Sh DESCRIPTION Divert sockets are similar to raw IP sockets, except that they can be bound to a specific .Nm port via the .Xr bind 2 system call. The IP address in the bind is ignored; only the port number is significant. A divert socket bound to a divert port will receive all packets diverted to that port by some (here unspecified) kernel mechanism(s). Packets may also be written to a divert port, in which case they re-enter kernel IP packet processing. .Pp Divert sockets are normally used in conjunction with .Fx Ns 's packet filtering implementation and the .Xr ipfw 8 program. By reading from and writing to a divert socket, matching packets can be passed through an arbitrary ``filter'' as they travel through the host machine, special routing tricks can be done, etc. .Sh READING PACKETS Packets are diverted either as they are ``incoming'' or ``outgoing.'' Incoming packets are diverted after reception on an IP interface, whereas outgoing packets are diverted before next hop forwarding. .Pp Diverted packets may be read unaltered via .Xr read 2 , .Xr recv 2 , or .Xr recvfrom 2 . In the latter case, the address returned will have its port set to some tag supplied by the packet diverter, (usually the ipfw rule number) and the IP address set to the (first) address of the interface on which the packet was received (if the packet was incoming) or .Dv INADDR_ANY (if the packet was outgoing). In the case of an incoming packet the interface name will also be placed in the 8 bytes following the address, (assuming it fits). .Sh WRITING PACKETS Writing to a divert socket is similar to writing to a raw IP socket; the packet is injected ``as is'' into the normal kernel IP packet processing and minimal error checking is done. Packets are written as either incoming or outgoing: if .Xr write 2 or .Xr send 2 is used to deliver the packet, or if .Xr sendto 2 is used with a destination IP address of .Dv INADDR_ANY , then the packet is treated as if it were outgoing, i.e., destined -for a non-local address. Otherwise, the packet is assumed to be +for a non-local address. +Otherwise, the packet is assumed to be incoming and full packet routing is done. .Pp In the latter case, the IP address specified must match the address of some local interface, or an interface name must be found after the IP address. If an interface name is found, that interface will be used and the value of the IP address will be ignored (other than the fact that it is not .Dv INADDR_ANY ) . -This is to indicate on which interface the packet ``arrived.'' +This is to indicate on which interface the packet +.Dq arrived . .Pp Normally, packets read as incoming should be written as incoming; -similarly for outgoing packets. When reading and then writing back +similarly for outgoing packets. +When reading and then writing back packets, passing the same socket address supplied by .Xr recvfrom 2 unmodified to .Xr sendto 2 simplifies things (see below). .Pp The port part of the socket address passed to the .Xr sendto 2 contains a tag that should be meaningful to the diversion module. In the case of .Xr ipfw 8 the tag is interpreted as the rule number .Em after which rule processing should restart. .Sh LOOP AVOIDANCE Packets written into a divert socket (using .Xr sendto 2 ) re-enter the packet filter at the rule number following the tag given in the port part of the socket address, which is usually already set at the rule number that caused the diversion (not the next rule if there are several at the same number). If the 'tag' is altered to indicate an alternative re-entry point, care should be taken to avoid loops, where the same packet is diverted more than once at the same rule. .Sh DETAILS To enable divert sockets, your kernel must be compiled with the option .Dv IPDIVERT . .Pp If a packet is diverted but no socket is bound to the port, or if .Dv IPDIVERT is not enabled in the kernel, the packet is dropped. .Pp Incoming packet fragments which get diverted are fully reassembled before delivery; the diversion of any one fragment causes the entire packet to get diverted. If different fragments divert to different ports, then which port ultimately gets chosen is unpredictable. .Pp Packets are received and sent unchanged, except that packets read as outgoing have invalid IP header checksums, and packets written as outgoing have their IP header checksums overwritten with the correct value. Packets written as incoming and having incorrect checksums will be dropped. Otherwise, all header fields are unchanged (and therefore in network order). .Pp Binding to port numbers less than 1024 requires super-user access, as does creating a socket of type SOCK_RAW. .Sh ERRORS Writing to a divert socket can return these errors, along with the usual errors possible when writing raw packets: .Bl -tag -width Er .It Bq Er EINVAL The packet had an invalid header, or the IP options in the packet and the socket options set were incompatible. .It Bq Er EADDRNOTAVAIL The destination address contained an IP address not equal to .Dv INADDR_ANY that was not associated with any interface. .El .Sh SEE ALSO .Xr bind 2 , .Xr recvfrom 2 , .Xr sendto 2 , .Xr socket 2 , .Xr ipfw 8 .Sh BUGS This is an attempt to provide a clean way for user mode processes to implement various IP tricks like address translation, but it could be cleaner, and it's too dependent on .Xr ipfw 8 . .Pp It's questionable whether incoming fragments should be reassembled before being diverted. For example, if only some fragments of a packet destined for another machine don't get routed through the local machine, the packet is lost. This should probably be a settable socket option in any case. .Sh AUTHORS .An Archie Cobbs Aq archie@FreeBSD.org , Whistle Communications Corp. Index: head/share/man/man4/fpa.4 =================================================================== --- head/share/man/man4/fpa.4 (revision 117010) +++ head/share/man/man4/fpa.4 (revision 117011) @@ -1,55 +1,58 @@ .\" .\" Copyright (c) 1995, Matt Thomas .\" All rights reserved. .\" .\" $FreeBSD$ .\" .Dd March 13, 1995 .Dt FPA 4 .Os .Sh NAME .Nm fpa , .Nm fea .Nd device drivers for DEC FDDI controllers .Sh SYNOPSIS .Cd "device fpa" .Cd "device fea" .Pp .Fx only: .Cd "device fddi" .Sh DESCRIPTION The .Nm and .Nm fea device driver provides support for the DEC DEFPA PCI FDDI Controller and -the DEC DEFEA EISA FDDI Controller, respectively. All variants of either +the DEC DEFEA EISA FDDI Controller, respectively. +All variants of either controller are supported including the DAS and SAS configurations. .Sh DIAGNOSTICS .Bl -diag .It "fea%d: error: desired IRQ of %d does not match device's actual IRQ (%d)" The device probe detected that the DEFEA board is configured for a different interrupt than the one specified in the kernel configuration file. .It "fea%d: error: memory not enabled! ECU reconfiguration required" The device probe found that no device memory had been configured on the -DEFEA. Also the DEFEA can be configured with no device memory, this driver -requires a minimum of 1K device memory be setup. The ECU (EISA Configuration +DEFEA. +Also the DEFEA can be configured with no device memory, this driver +requires a minimum of 1K device memory be setup. +The ECU (EISA Configuration Utility) will need to be run to change the settings. .El .Sh CAVEATS Normally, the device driver will not enable the reception of SMT frames. However if the IFF_LINK1 flag is set, the device driver will enable the reception of SMT frames and pass them up to the Berkeley Packet Filter for processing. .Sh SEE ALSO .Xr arp 4 , .Xr netintro 4 , .Xr ifconfig 8 .Sh AUTHORS The .Nm and .Nm fea device driver and manual page was written by .An Matt Thomas . Index: head/share/man/man4/icmp.4 =================================================================== --- head/share/man/man4/icmp.4 (revision 117010) +++ head/share/man/man4/icmp.4 (revision 117011) @@ -1,164 +1,165 @@ .\" Copyright (c) 1986, 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. .\" .\" @(#)icmp.4 8.1 (Berkeley) 6/5/93 .\" $FreeBSD$ .\" .Dd March 21, 2003 .Dt ICMP 4 .Os .Sh NAME .Nm icmp .Nd Internet Control Message 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 ICMP is the error and control message protocol used by .Tn IP -and the Internet protocol family. It may be accessed +and the Internet protocol family. +It may be accessed through a .Dq raw socket for network monitoring and diagnostic functions. The .Fa proto parameter to the socket call to create an .Tn ICMP socket is obtained from .Xr getprotobyname 3 . .Tn ICMP 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 Outgoing packets automatically have an .Tn IP header prepended to them (based on the destination address). Incoming packets are received with the .Tn IP header and options intact. .Ss MIB Variables The .Tn ICMP protocol implements a number of variables in the .Va net.inet.icmp branch of the .Xr sysctl 3 MIB. .Bl -tag -width ".Va icmplim_output" .It Va maskrepl .Pq Vt boolean Enable/disable replies to ICMP Address Mask Request packets. Defaults to false. .It Va maskfake .Pq Vt "unsigned integer" When .Va maskrepl is set and this value is non-zero, it will be used instead of the real address mask when the system replies to an ICMP Address Mask Request packet. Defaults to 0. .It Va icmplim .Pq Vt integer Bandwidth limit for ICMP replies in packets/second. Used when .Va icmplim_output is non-zero. Defaults to 200. .It Va icmplim_output .Pq Vt boolean Enable/disable bandwidth limiting of ICMP replies. Defaults to true. .It Va drop_redirect .Pq Vt boolean Enable/disable dropping of ICMP Redirect packets. Defaults to false. .It Va log_redirect .Pq Vt boolean Enable/disable logging of ICMP Redirect packets. Defaults to false. .It Va bmcastecho .Pq Vt boolean Enable/disable ICMP replies received via broadcast or multicast. Defaults to false. .El .Sh ERRORS A socket operation may fail with one of the following errors returned: .Bl -tag -width Er .It Bq Er EISCONN when trying to establish a connection on a socket which already has one, 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 hasn't 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. .El .Sh SEE ALSO .Xr recv 2 , .Xr send 2 , .Xr inet 4 , .Xr intro 4 , .Xr ip 4 .Sh HISTORY The .Nm protocol appeared in .Bx 4.3 . Index: head/share/man/man4/ifmib.4 =================================================================== --- head/share/man/man4/ifmib.4 (revision 117010) +++ head/share/man/man4/ifmib.4 (revision 117011) @@ -1,191 +1,196 @@ .\" Copyright 1996 Massachusetts Institute of Technology .\" .\" Permission to use, copy, modify, and distribute this software and .\" its documentation for any purpose and without fee is hereby .\" granted, provided that both the above copyright notice and this .\" permission notice appear in all copies, that both the above .\" copyright notice and this permission notice appear in all .\" supporting documentation, and that the name of M.I.T. not be used .\" in advertising or publicity pertaining to distribution of the .\" software without specific, written prior permission. M.I.T. makes .\" no representations about the suitability of this software for any .\" purpose. It is provided "as is" without express or implied .\" warranty. .\" .\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''. M.I.T. DISCLAIMS .\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE, .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT .\" SHALL M.I.T. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF .\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd November 15, 1996 .Dt IFMIB 4 .Os .Sh NAME .Nm ifmib .Nd Management Information Base for network interfaces .Sh SYNOPSIS .In sys/types.h .In sys/socket.h .In sys/sysctl.h .In sys/time.h .In net/if.h .In net/if_mib.h .Sh DESCRIPTION The .Nm facility is an application of the .Xr sysctl 3 interface to provide management information about network interfaces to client applications such as .Xr netstat 1 , .Xr slstat 8 , and .Tn SNMP -management agents. This information is structured as a table, where +management agents. +This information is structured as a table, where each row in the table represents a logical network interface (either a hardware device or a software pseudo-device like .Xr lo 4 ) . There are two columns in the table, each containing a single structure: one column contains generic information relevant to all interfaces, and the other contains information specific to the -particular class of interface. (Generally the latter will implement +particular class of interface. +(Generally the latter will implement the .Tn SNMP .Tn MIB defined for that particular interface class, if one exists and can be implemented in the kernel.) .Pp The .Nm facility is accessed via the .Dq Li net.link.generic branch of the .Xr sysctl 3 -MIB. The manifest constants for each level in the +MIB. +The manifest constants for each level in the .Xr sysctl 3 .Ar name are defined in .Aq Pa net/if_mib.h . The index of the last row in the table is given by .Dq Li net.link.generic.system.ifcount (or, using the manifest constants, .Dv CTL_NET , .Dv PF_LINK , .Dv NETLINK_GENERIC , .Dv IFMIB_SYSTEM , .Dv IFMIB_IFCOUNT ) . A management application searching for a particular interface should start with row 1 and continue through the table row-by-row until the desired interface is found, or the interface count is reached. Note that the table may be sparse, i.e. a given row may not exist, indicated by an .Va errno of .Er ENOENT . Such an error should be ignored, and the next row should be checked. .Pp The generic interface information, common to all interfaces, can be accessed via the following procedure: .Bd -literal -offset indent int get_ifmib_general(int row, struct ifmibdata *ifmd) { int name[6]; size_t len; name[0] = CTL_NET; name[1] = PF_LINK; name[2] = NETLINK_GENERIC; name[3] = IFMIB_IFDATA; name[4] = row; name[5] = IFDATA_GENERAL; len = sizeof(*ifmd); return sysctl(name, 6, ifmd, &len, (void *)0, 0); } .Ed .Pp The fields in .Li struct ifmibdata are as follows: .Bl -tag -width "ifmd_snd_drops" .It Li ifmd_name .Pq Li "char []" the name of the interface, including the unit number .It Li ifmd_pcount .Pq Li int the number of promiscuous listeners .It Li ifmd_flags .Pq Li int the interface's flags (defined in .Aq Pa net/if.h ) .It Li ifmd_snd_len .Pq Li int the current instantaneous length of the send queue .It Li ifmd_snd_drops .Pq Li int the number of packets dropped at this interface because the send queue was full .It Li ifmd_data .Pq Li struct if_data more information from a structure defined in .Aq Pa net/if.h (see .Xr if_data 9 ) .El .Pp Class-specific information can be retrieved by examining the .Dv IFDATA_LINKSPECIFIC -column instead. Note that the form and length of the structure will -depend on the class of interface. For +column instead. +Note that the form and length of the structure will +depend on the class of interface. +For .Dv IFT_ETHER , .Dv IFT_ISO88023 , and .Dv IFT_STARLAN interfaces, the structure is called .Dq Li struct ifmib_iso_8802_3 (defined in .Aq Pa net/if_mib.h ) , and implements a superset of the .Tn "RFC 1650" MIB for Ethernet-like networks. .\" This will eventually be defined in an ethermib(4) page. For .Dv IFT_SLIP , the structure is a .Dq Li struct sl_softc .Pq Aq Pa net/if_slvar.h . .Sh SEE ALSO .Xr sysctl 3 , .Xr intro 4 , .Xr ifnet 9 .\" .Xr ethermib 4 , .Rs .%T "Definitions of Managed Objects for the Ethernet-like Interface Types Using SMIv2" .%A F. Kastenholz .%D August 1994 .%O RFC 1650 .Re .Sh BUGS Many Ethernet-like interfaces do not yet support the Ethernet MIB; the interfaces known to support it include .Xr ed 4 and .Xr de 4 . Regardless, all interfaces automatically support the generic MIB. .Sh HISTORY The .Nm interface first appeared in .Fx 2.2 . Index: head/share/man/man4/inet.4 =================================================================== --- head/share/man/man4/inet.4 (revision 117010) +++ head/share/man/man4/inet.4 (revision 117011) @@ -1,299 +1,308 @@ .\" 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. .\" .\" From: @(#)inet.4 8.1 (Berkeley) 6/5/93 .\" $FreeBSD$ .\" .Dd February 14, 1995 .Dt INET 4 .Os .Sh NAME .Nm inet .Nd Internet protocol family .Sh SYNOPSIS .In sys/types.h .In netinet/in.h .Sh DESCRIPTION The Internet protocol family is a collection of protocols layered atop the .Em Internet Protocol .Pq Tn IP transport layer, and utilizing the Internet address format. The Internet family provides protocol support for the .Dv SOCK_STREAM , SOCK_DGRAM , and .Dv SOCK_RAW socket types; the .Dv SOCK_RAW interface provides access to the .Tn IP protocol. .Sh ADDRESSING Internet addresses are four byte quantities, stored in network standard format (on the .Tn VAX these are word and byte -reversed). The include file +reversed). +The include file .Aq Pa netinet/in.h defines this address as a discriminated union. .Pp Sockets bound to the Internet protocol family utilize the following addressing structure, .Bd -literal -offset indent struct sockaddr_in { uint8_t sin_len; sa_family_t sin_family; in_port_t sin_port; struct in_addr sin_addr; char sin_zero[8]; }; .Ed .Pp Sockets may be created with the local address .Dv INADDR_ANY to affect .Dq wildcard matching on incoming messages. The address in a .Xr connect 2 or .Xr sendto 2 call may be given as .Dv INADDR_ANY to mean .Dq this host . The distinguished address .Dv INADDR_BROADCAST is allowed as a shorthand for the broadcast address on the primary network if the first network configured supports broadcast. .Sh PROTOCOLS The Internet protocol family is comprised of the .Tn IP network protocol, Internet Control Message Protocol .Pq Tn ICMP , Internet Group Management Protocol .Pq Tn IGMP , Transmission Control Protocol .Pq Tn TCP , and User Datagram Protocol .Pq Tn UDP . .Tn TCP is used to support the .Dv SOCK_STREAM abstraction while .Tn UDP is used to support the .Dv SOCK_DGRAM -abstraction. A raw interface to +abstraction. +A raw interface to .Tn IP is available by creating an Internet socket of type .Dv SOCK_RAW . The .Tn ICMP message protocol is accessible from a raw socket. .Pp The 32-bit Internet address contains both network and host parts. -However, direct examination of addresses is discouraged. For those +However, direct examination of addresses is discouraged. +For those programs which absolutely need to break addresses into their component parts, the following .Xr ioctl 2 commands are provided for a datagram socket in the Internet domain; they have the same form as the .Dv SIOCIFADDR command (see .Xr intro 4 ) . .Pp .Bl -tag -width SIOCSIFNETMASK .It Dv SIOCSIFNETMASK Set interface network mask. The network mask defines the network part of the address; if it contains more of the address than the address type would indicate, then subnets are in use. .It Dv SIOCGIFNETMASK Get interface network mask. .El .Sh ROUTING The current implementation of Internet protocols includes some routing-table adaptations to provide enhanced caching of certain end-to-end -information necessary for Transaction TCP and Path MTU Discovery. The +information necessary for Transaction TCP and Path MTU Discovery. +The following changes are the most significant: .Bl -enum .It All IP routes, except those with the .Dv RTF_CLONING flag and those to multicast destinations, have the .Dv RTF_PRCLONING flag forcibly enabled (they are thus said to be .Dq "protocol cloning" ) . .It When the last reference to an IP route is dropped, the route is -examined to determine if it was created by cloning such a route. If -this is the case, the +examined to determine if it was created by cloning such a route. +If this is the case, the .Dv RTF_PROTO3 flag is turned on, and the expiration timer is initialized to go off -in net.inet.ip.rtexpire seconds. If such a route is re-referenced, +in net.inet.ip.rtexpire seconds. +If such a route is re-referenced, the flag and expiration timer are reset. .It A kernel timeout runs once every ten minutes, or sooner if there are soon-to-expire routes in the kernel routing table, and deletes the expired routes. .El .Pp A dynamic process is in place to modify the value of net.inet.ip.rtexpire if the number of cached routes grows too large. If after an expiration run there are still more than net.inet.ip.rtmaxcache unreferenced routes remaining, the rtexpire value is multiplied by 3/4, and any routes which have longer -expiration times have those times adjusted. This process is damped -somewhat by specification of a minimum rtexpire value +expiration times have those times adjusted. +This process is damped somewhat by specification of a minimum rtexpire value (net.inet.ip.rtminexpire), and by restricting the reduction to once in a ten-minute period. .Pp If some external process deletes the original route from which a -protocol-cloned route was generated, the ``child route'' is deleted. +protocol-cloned route was generated, the +.Dq child route +is deleted. (This is actually a generic mechanism in the routing code support for protocol-requested cloning.) .Pp No attempt is made to manage routes which were not created by protocol cloning; these are assumed to be static, under the management of an external routing process, or under the management of a link layer (e.g., .Tn ARP for Ethernets). .Pp Only certain types of network activity will result in the cloning of a -route using this mechanism. Specifically, those protocols (such as +route using this mechanism. +Specifically, those protocols (such as .Tn TCP and .Tn UDP ) which themselves cache a long-lasting reference to route for a destination will trigger the mechanism; whereas raw .Tn IP packets, whether locally-generated or forwarded, will not. .Ss MIB Variables A number of variables are implemented in the net.inet branch of the .Xr sysctl 3 MIB. In addition to the variables supported by the transport protocols (for which the respective manual pages may be consulted), the following general variables are defined: .Bl -tag -width IPCTL_FASTFORWARDING .It Dv IPCTL_FORWARDING .Pq ip.forwarding Boolean: enable/disable forwarding of IP packets. Defaults to off. .It Dv IPCTL_FASTFORWARDING .Pq ip.fastforwarding Boolean: enable/disable the use of fast IP forwarding code. Defaults to off. When fast forwarding is enabled, IP packets are forwarded directly to the appropriate network interface with a minimal validity checking, which -greatly improves the throughput. On the other hand, they bypass the +greatly improves the throughput. +On the other hand, they bypass the standard procedures, such as IP option processing and .Xr ipfirewall 4 checking. It is not guaranteed that every packet will be fast-forwarded. .It Dv IPCTL_SENDREDIRECTS .Pq ip.redirect Boolean: enable/disable sending of ICMP redirects in response to unforwardable .Tn IP packets. Defaults to on. .It Dv IPCTL_DEFTTL .Pq ip.ttl Integer: default time-to-live .Pq Dq TTL to use for outgoing .Tn IP packets. .It Dv IPCTL_ACCEPTSOURCEROUTE .Pq ip.accept_sourceroute Boolean: enable/disable accepting of source-routed IP packets (default false). .It Dv IPCTL_SOURCEROUTE .Pq ip.sourceroute Boolean: enable/disable forwarding of source-routed IP packets (default false). .It Dv IPCTL_RTEXPIRE .Pq ip.rtexpire Integer: lifetime in seconds of protocol-cloned .Tn IP -routes after the last reference drops (default one hour). This value -varies dynamically as described above. +routes after the last reference drops (default one hour). +This value varies dynamically as described above. .It Dv IPCTL_RTMINEXPIRE .Pq ip.rtminexpire -Integer: minimum value of ip.rtexpire (default ten seconds). This -value has no effect on user modifications, but restricts the dynamic +Integer: minimum value of ip.rtexpire (default ten seconds). +This value has no effect on user modifications, but restricts the dynamic adaptation described above. .It Dv IPCTL_RTMAXCACHE .Pq ip.rtmaxcache Integer: trigger level of cached, unreferenced, protocol-cloned routes which initiates dynamic adaptation (default 128). .El .Sh SEE ALSO .Xr ioctl 2 , .Xr socket 2 , .Xr sysctl 3 , .Xr icmp 4 , .Xr intro 4 , .Xr ip 4 , .Xr ipfirewall 4 , .Xr tcp 4 , .Xr ttcp 4 , .Xr udp 4 .Rs .%T "An Introductory 4.3 BSD Interprocess Communication Tutorial" .%B PS1 .%N 7 .Re .Rs .%T "An Advanced 4.3 BSD Interprocess Communication Tutorial" .%B PS1 .%N 8 .Re .Sh CAVEAT The Internet protocol support is subject to change as the Internet protocols develop. Users should not depend on details of the current implementation, but rather the services exported. .Sh HISTORY The .Nm protocol interface appeared in .Bx 4.2 . The .Dq protocol cloning code appeared in .Fx 2.1 . Index: head/share/man/man4/intro.4 =================================================================== --- head/share/man/man4/intro.4 (revision 117010) +++ head/share/man/man4/intro.4 (revision 117011) @@ -1,169 +1,178 @@ .\" .\" Copyright (c) 1996 David E. O'Brien, 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. .\" .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``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 DEVELOPERS 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, 1996 .Dt INTRO 4 .Os .Sh NAME .Nm intro .Nd introduction to devices and device drivers .Sh DESCRIPTION This section contains information related to devices, device drivers and miscellaneous hardware. .Ss The device abstraction Device is a term used mostly for hardware-related stuff that belongs to the system, like disks, printers, or a graphics display with its -keyboard. There are also so-called +keyboard. +There are also so-called .Em pseudo-devices where a device driver emulates the behaviour of a device in software -without any particular underlying hardware. A typical example for +without any particular underlying hardware. +A typical example for the latter class is .Pa /dev/mem , a loophole where the physical memory can be accessed using the regular file access semantics. .Pp The device abstraction generally provides a common set of system calls layered on top of them, which are dispatched to the corresponding -device driver by the upper layers of the kernel. The set of system +device driver by the upper layers of the kernel. +The set of system calls available for devices is chosen from .Xr open 2 , .Xr close 2 , .Xr read 2 , .Xr write 2 , .Xr ioctl 2 , .Xr select 2 , and .Xr mmap 2 . Not all drivers implement all system calls, for example, calling .Xr mmap 2 on terminal devices is likely to be not useful at all. .Ss Accessing Devices Most of the devices in a .Ux Ns -like operating system are accessed through so-called .Em device nodes , sometimes also called .Em special files . They are usually located under the directory .Pa /dev in the file system hierarchy (see also .Xr hier 7 ) . .Pp Note that this could lead to an inconsistent state, where either there are device nodes that do not have a configured driver associated with them, or there may be drivers that have successfully probed for their devices, but cannot be accessed since the corresponding device node is -still missing. In the first case, any attempt to reference the device +still missing. +In the first case, any attempt to reference the device through the device node will result in an error, returned by the upper layers of the kernel, usually .Er ENXIO . In the second case, the device node needs to be created before the driver and its device will be usable. .Pp Some devices come in two flavors: .Em block and .Em character devices, or to use better terms, buffered and unbuffered (raw) -devices. The traditional names are reflected by the letters +devices. +The traditional names are reflected by the letters .Ql b and .Ql c as the file type identification in the output of .Ql ls -l . Buffered devices are being accessed through the buffer cache of the operating system, and they are solely intended to layer a file system -on top of them. They are normally implemented for disks and disk-like +on top of them. +They are normally implemented for disks and disk-like devices only and, for historical reasons, for tape devices. .Pp Raw devices are available for all drivers, including those that also -implement a buffered device. For the latter group of devices, the +implement a buffered device. +For the latter group of devices, the differentiation is conventionally done by prepending the letter .Ql r to the path name of the device node, for example .Pa /dev/rda0 denotes the raw device for the first SCSI disk, while .Pa /dev/da0 is the corresponding device node for the buffered device. .Pp Unbuffered devices should be used for all actions that are not related to file system operations, even if the device in question is a disk -device. This includes making backups of entire disk partitions, or +device. +This includes making backups of entire disk partitions, or to .Em raw floppy disks (i.e. those used like tapes). .Pp Access restrictions to device nodes are usually subject to the regular file permissions of the device node entry, instead of being enforced directly by the drivers in the kernel. .Ss Drivers without device nodes Drivers for network devices do not use device nodes in order to be -accessed. Their selection is based on other decisions inside the +accessed. +Their selection is based on other decisions inside the kernel, and instead of calling .Xr open 2 , use of a network device is generally introduced by using the system call .Xr socket 2 . .Ss Configuring a driver into the kernel For each kernel, there is a configuration file that is used as a base to select the facilities and drivers for that kernel, and to tune -several options. See +several options. +See .Xr config 8 -for a detailed description of the files involved. The individual -manual pages in this section provide a sample line for the +for a detailed description of the files involved. +The individual manual pages in this section provide a sample line for the configuration file in their synopsis portion. See also the sample config file .Pa /sys/i386/conf/LINT (for the .Em i386 architecture). .Sh SEE ALSO .Xr close 2 , .Xr ioctl 2 , .Xr mmap 2 , .Xr open 2 , .Xr read 2 , .Xr select 2 , .Xr socket 2 , .Xr write 2 , .Xr devfs 5 , .Xr hier 7 , .Xr config 8 +.Sh HISTORY +This manual page first appeared in +.Fx 2.1 . .Sh AUTHORS .An -nosplit This man page has been written by .An J\(:org Wunsch with initial input by .An David E. O'Brien . -.Sh HISTORY -.Nm Intro -appeared in -.Fx 2.1 . Index: head/share/man/man4/ip6.4 =================================================================== --- head/share/man/man4/ip6.4 (revision 117010) +++ head/share/man/man4/ip6.4 (revision 117011) @@ -1,707 +1,710 @@ .\" $KAME: ip6.4,v 1.14 2001/02/26 09:31:39 itojun Exp $ .\" .\" Copyright (C) 1999 WIDE Project. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the project nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" 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. .\" .\" $FreeBSD$ .\" .Dd March 13, 2000 .Dt IP6 4 .Os .\" .Sh NAME .Nm ip6 .Nd Internet Protocol version 6 (IPv6) .\" .Sh SYNOPSIS .In sys/types.h .In sys/socket.h .In netinet/in.h .Ft int .Fn socket AF_INET6 SOCK_RAW proto .\" .Sh DESCRIPTION .Tn IPv6 is the network layer protocol used by the Internet protocol version 6 family .Pq Dv AF_INET6 . Options may be set at the .Tn IPv6 level when using higher-level protocols that are based on .Tn IPv6 (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 IPv6-level .Xr setsockopt 2 Ns / Ns Xr getsockopt 2 options. They are separated into the basic IPv6 sockets API (defined in RFC2553), and the advanced API (defined in RFC2292). The basic API looks very similar to the API presented in .Xr ip 4 . Advanced API uses ancillary data and can handle more complex cases. .Pp To specify some of socket options, certain privilege (i.e. root privilege) is required. .\" .Ss Basic IPv6 sockets API .Dv IPV6_UNICAST_HOPS may be used to set the hoplimit field in the .Tn IPv6 header. As symbol name suggests, the option controls hoplimit field on unicast packets. If -1 is specified, the kernel will use a default value. If a value of 0 to 255 is specified, the packet will have the specified value as hoplimit. Other values are considered invalid, and .Er EINVAL will be returned. For example: .Bd -literal -offset indent int hlim = 60; /* max = 255 */ setsockopt(s, IPPROTO_IPV6, IPV6_UNICAST_HOPS, &hlim, sizeof(hlim)); .Ed .Pp .Tn IPv6 multicasting is supported only on .Dv AF_INET6 sockets of type .Dv SOCK_DGRAM and .Dv SOCK_RAW, and only on networks where the interface driver supports multicasting. .Pp The .Dv IPV6_MULTICAST_HOPS option changes the hoplimit for outgoing multicast datagrams in order to control the scope of the multicasts: .Bd -literal -offset indent unsigned int hlim; /* range: 0 to 255, default = 1 */ setsockopt(s, IPPROTO_IPV6, IPV6_MULTICAST_HOPS, &hlim, sizeof(hlim)); .Ed .Pp Datagrams with a hoplimit of 1 are not forwarded beyond the local network. Multicast datagrams with a hoplimit 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 hoplimit 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, each multicast transmission is sent from the primary network interface. The .Dv IPV6_MULTICAST_IF option overrides the default for subsequent transmissions from a given socket: .Bd -literal -offset indent unsigned int outif; outif = if_nametoindex("ne0"); setsockopt(s, IPPROTO_IPV6, IPV6_MULTICAST_IF, &outif, sizeof(outif)); .Ed .Pp where "outif" is an interface index of the desired interface, or 0 to specify the default interface. .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 IPv6 layer for local delivery. The .Dv IPV6_MULTICAST_LOOP option gives the sender explicit control over whether or not subsequent datagrams are looped back: .Bd -literal -offset indent u_char loop; /* 0 = disable, 1 = enable (default) */ setsockopt(s, IPPROTO_IPV6, IPV6_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 router 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 A multicast datagram sent with an initial hoplimit 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 IPV6_JOIN_GROUP option: .Bd -literal -offset indent struct ipv6_mreq mreq6; setsockopt(s, IPPROTO_IPV6, IPV6_JOIN_GROUP, &mreq6, sizeof(mreq6)); .Ed .Pp where .Fa mreq6 is the following structure: .Bd -literal -offset indent struct ipv6_mreq { struct in6_addr ipv6mr_multiaddr; u_int ipv6mr_interface; }; .Ed .Pp .Dv ipv6mr_interface should be 0 to choose the default multicast interface, or the interface index of a particular multicast-capable interface if the host is multihomed. 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 -offset indent struct ipv6_mreq mreq6; setsockopt(s, IPPROTO_IPV6, IPV6_LEAVE_GROUP, &mreq6, sizeof(mreq6)); .Ed .Pp where .Fa mreq6 contains the same values as used to add the membership. Memberships are dropped when the socket is closed or the process exits. .Pp .Dv IPV6_PORTRANGE controls how ephemeral ports are allocated for .Dv SOCK_STREAM and .Dv SOCK_DGRAM sockets. For example, .Bd -literal -offset indent int range = IPV6_PORTRANGE_LOW; /* see */ setsockopt(s, IPPROTO_IPV6, IPV6_PORTRANGE, &range, sizeof(range)); .Ed .Pp .Dv IPV6_V6ONLY controls behavior of .Dv AF_INET6 wildcard listening socket. The following example sets the option to 1: .Bd -literal -offset indent int on = 1; setsockopt(s, IPPROTO_IPV6, IPV6_V6ONLY, &on, sizeof(on)); .Ed .Pp If set to 1, .Dv AF_INET6 wildcard listening socket will accept IPv6 traffic only. If set to 0, it will accept IPv4 traffic as well, as if it was from IPv4 mapped address like .Li ::ffff:10.1.1.1 . .\" RFC2553 defines the behavior when the variable is set to 0. Note that if you set it this to 0, IPv4 access control gets much more complicated. For example, even if you have no listening .Dv AF_INET listening socket on port .Li X , you will end up accepting IPv4 traffic by .Dv AF_INET6 listening socket on the same port. The default value for this flag is copied at socket instantiation time, from .Li net.inet6.ip6.v6only .Xr sysctl 3 variable. The option affects .Tn TCP and .Tn UDP sockets only. .\" .Ss Advanced IPv6 sockets API The advanced IPv6 sockets API lets userland programs specify or obtain details about the IPv6 header and the IPv6 extension headers on packets. The advanced API uses ancillary data for passing data from/to the kernel. .Pp There are .Xr setsockopt 2 Ns / Ns Xr getsockopt 2 options to get optional information on incoming packets. They are .Dv IPV6_PKTINFO , .Dv IPV6_HOPLIMIT , .Dv IPV6_HOPOPTS , .Dv IPV6_DSTOPTS , and .Dv IPV6_RTHDR . .Bd -literal -offset indent int on = 1; setsockopt(fd, IPPROTO_IPV6, IPV6_PKTINFO, &on, sizeof(on)); setsockopt(fd, IPPROTO_IPV6, IPV6_HOPLIMIT, &on, sizeof(on)); setsockopt(fd, IPPROTO_IPV6, IPV6_HOPOPTS, &on, sizeof(on)); setsockopt(fd, IPPROTO_IPV6, IPV6_DSTOPTS, &on, sizeof(on)); setsockopt(fd, IPPROTO_IPV6, IPV6_RTHDR, &on, sizeof(on)); .Ed .Pp When any of these options are enabled, the corresponding data is returned as control information by .Xr recvmsg 2 , as one or more ancillary data objects. .Pp If .Dv IPV6_PKTINFO is enabled, the destination IPv6 address and the arriving interface index will be available via .Li struct in6_pktinfo on ancillary data stream. You can pick the structure by checking for an ancillary data item with .Li cmsg_level equals to .Dv IPPROTO_IPV6 , and .Li cmsg_type equals to .Dv IPV6_PKTINFO . .Pp If .Dv IPV6_HOPLIMIT is enabled, hoplimit value on the packet will be made available to the userland program. Ancillary data stream will contain an integer data item with .Li cmsg_level equals to .Dv IPPROTO_IPV6 , and .Li cmsg_type equals to .Dv IPV6_HOPLIMIT . .Pp .Xr inet6_option_space 3 and friends will help you parse ancillary data items for .Dv IPV6_HOPOPTS and .Dv IPV6_DSTOPTS . Similarly, .Xr inet6_rthdr_space 3 and friends will help you parse ancillary data items for .Dv IPV6_RTHDR . .Pp .Dv IPV6_HOPOPTS and .Dv IPV6_DSTOPTS may appear multiple times on an ancillary data stream (note that the behavior is slightly different than the specification). Other ancillary data item will appear no more than once. .Pp For outgoing direction, you can pass ancillary data items with normal payload data, using .Xr sendmsg 2 . Ancillary data items will be parsed by the kernel, and used to construct the IPv6 header and extension headers. For the 5 .Li cmsg_level values listed above, ancillary data format is the same as inbound case. Additionally, you can specify .Dv IPV6_NEXTHOP data object. The .Dv IPV6_NEXTHOP ancillary data object specifies the next hop for the datagram as a socket address structure. In the .Li cmsghdr structure containing this ancillary data, the .Li cmsg_level member will be .Dv IPPROTO_IPV6 , the .Li cmsg_type member will be .Dv IPV6_NEXTHOP , and the first byte of .Li cmsg_data[] will be the first byte of the socket address structure. .Pp If the socket address structure contains an IPv6 address (e.g., the sin6_family member is .Dv AF_INET6 ) , then the node identified by that address must be a neighbor of the sending host. If that address equals the destination IPv6 address of the datagram, then this is equivalent to the existing .Dv SO_DONTROUTE socket option. .Pp For applications that do not, or unable to use .Xr sendmsg 2 or .Xr recvmsg 2 , .Dv IPV6_PKTOPTIONS socket option is defined. Setting the socket option specifies any of the optional output fields: .Bd -literal -offset indent setsockopt(fd, IPPROTO_IPV6, IPV6_PKTOPTIONS, &buf, len); .Ed .Pp The fourth argument points to a buffer containing one or more ancillary data objects, and the fifth argument is the total length of all these objects. The application fills in this buffer exactly as if the buffer were being passed to .Xr sendmsg 2 as control information. .Pp The options set by calling .Xr setsockopt 2 for .Dv IPV6_PKTOPTIONS are called "sticky" options because once set they apply to all packets sent on that socket. The application can call .Xr setsockopt 2 again to change all the sticky options, or it can call .Xr setsockopt 2 with a length of 0 to remove all the sticky options for the socket. .Pp The corresponding receive option .Bd -literal -offset indent getsockopt(fd, IPPROTO_IPV6, IPV6_PKTOPTIONS, &buf, &len); .Ed .Pp returns a buffer with one or more ancillary data objects for all the optional receive information that the application has previously specified that it wants to receive. The fourth argument points to the buffer that is filled in by the call. The fifth argument is a pointer to a value-result integer: when the function is called the integer specifies the size of the buffer pointed to by the fourth argument, and on return this integer contains the actual number of bytes that were returned. The application processes this buffer exactly as if the buffer were returned by .Xr recvmsg 2 as control information. .\" .Ss Advanced API and TCP sockets When using .Xr getsockopt 2 with the .Dv IPV6_PKTOPTIONS option and a .Tn TCP socket, only the options from the most recently received segment are retained and returned to the caller, and only after the socket option has been set. .\" That is, .\" .Tn TCP .\" need not start saving a copy of the options until the application says .\" to do so. The application is not allowed to specify ancillary data in a call to .Xr sendmsg 2 on a .Tn TCP socket, and none of the ancillary data that we described above is ever returned as control information by .Xr recvmsg 2 on a .Tn TCP socket. .\" .Ss Conflict resolution In some cases, there are multiple APIs defined for manipulating a IPv6 header field. A good example is the outgoing interface for multicast datagrams: it can be manipulated by .Dv IPV6_MULTICAST_IF in basic API, .Dv IPV6_PKTINFO in advanced API, and .Li sin6_scope_id field of the socket address passed to .Xr sendto 2 . .Pp When conflicting options are given to the kernel, the kernel will get the value in the following preference: (1) options specified by using ancillary data, (2) options specified by a sticky option of the advanced API, (3) options specified by using the basic API, and lastly (4) options specified by a socket address. Note that the conflict resolution is undefined in the API specification and implementation dependent. .\" .Ss "Raw IPv6 Sockets" Raw .Tn IPv6 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 IPv6 header prepended to them (based on the destination address and the protocol number the socket is created with). Incoming packets are received without .Tn IPv6 header nor extension headers. .Pp All data sent via raw sockets MUST be in network byte order and all data received via raw sockets will be in network byte order. This differs from the IPv4 raw sockets, which did not specify a byte ordering and typically used the host's byte order. .Pp Another difference from IPv4 raw sockets is that complete packets (that is, IPv6 packets with extension headers) cannot be read or written using the IPv6 raw sockets API. Instead, ancillary data objects are used to transfer the extension headers, as described above. Should an application need access to the complete IPv6 packet, some other technique, such as the datalink interfaces, such as .Xr bpf 4 , must be used. .Pp All fields in the IPv6 header that an application might want to change (i.e., everything other than the version number) can be modified using ancillary data and/or socket options by the application for output. All fields in a received IPv6 header (other than the version number and Next Header fields) and all extension headers are also made available to the application as ancillary data on input. Hence there is no need for a socket option similar to the IPv4 .Dv IP_HDRINCL socket option. .Pp When writing to a raw socket the kernel will automatically fragment the packet if its size exceeds the path MTU, inserting the required -fragmentation headers. On input the kernel reassembles received +fragmentation headers. +On input the kernel reassembles received fragments, so the reader of a raw socket never sees any fragment headers. .Pp Most IPv4 implementations give special treatment to a raw socket created with a third argument to .Xr socket 2 of .Dv IPPROTO_RAW , whose value is normally 255. We note that this value has no special meaning to an IPv6 raw socket (and the IANA currently reserves the value of 255 when used as a next-header field). .\" Note: This feature was added to .\" IPv4 in 1988 by Van Jacobson to support traceroute, allowing a .\" complete IP header to be passed by the application, before the .\" .Dv IP_HDRINCL .\" socket option was added. .Pp For ICMPv6 raw sockets, the kernel will calculate and insert the ICMPv6 checksum for since this checksum is mandatory. .Pp For other raw IPv6 sockets (that is, for raw IPv6 sockets created with a third argument other than IPPROTO_ICMPV6), the application must set the new IPV6_CHECKSUM socket option to have the kernel (1) compute and store a pseudo header checksum for output, and (2) verify the received pseudo header checksum on input, discarding the packet if the checksum is in error. This option prevents applications from having to perform source address selection on the packets they send. The checksum will incorporate the IPv6 pseudo-header, defined in Section 8.1 of RFC2460. This new socket option also specifies an integer offset into the user data of where the checksum is located. .Bd -literal -offset indent int offset = 2; setsockopt(fd, IPPROTO_IPV6, IPV6_CHECKSUM, &offset, sizeof(offset)); .Ed .Pp -By default, this socket option is disabled. Setting the offset to -1 -also disables the option. By disabled we mean (1) the kernel will +By default, this socket option is disabled. +Setting the offset to -1 +also disables the option. +By disabled we mean (1) the kernel will not calculate and store a checksum for outgoing packets, and (2) the kernel will not verify a checksum for received packets. .Pp Note: Since the checksum is always calculated by the kernel for an ICMPv6 socket, applications are not able to generate ICMPv6 packets with incorrect checksums (presumably for testing purposes) using this API. .\" .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 hasn't 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 IPv6 socket by a non-privileged process. .El .Pp The following errors specific to .Tn IPv6 may occur: .Bl -tag -width EADDRNOTAVAILxx .It Bq Er EINVAL An unknown socket option name was given. .It Bq Er EINVAL The ancillary data items were improperly formed, or option name was unknown. .El .\" .Sh SEE ALSO .Xr getsockopt 2 , .Xr recv 2 , .Xr send 2 , .Xr setsockopt 2 , .Xr inet6_option_space 3 , .Xr inet6_rthdr_space 3 , .Xr icmp6 4 , .Xr inet6 4 , .Xr intro 4 .Rs .%A W. Stevens .%A M. Thomas .%R RFC .%N 2292 .%D February 1998 .%T "Advanced Sockets API for IPv6" .Re .Rs .%A S. Deering .%A R. Hinden .%R RFC .%N 2460 .%D December 1998 .%T "Internet Protocol, Version 6 (IPv6) Specification" .Re .Rs .%A R. Gilligan .%A S. Thomson .%A J. Bound .%A W. Stevens .%R RFC .%N 2553 .%D March 1999 .%T "Basic Socket Interface Extensions for IPv6" .Re .\" .Sh STANDARDS Most of the socket options are defined in RFC2292 and/or RFC2553. .Pp .Dv IPV6_V6ONLY socket option is defined in draft-ietf-ipngwg-rfc2553bis-03. .Dv IPV6_PORTRANGE socket option and conflict resolution rule are not defined in the RFCs and should be considered implementation dependent. .\" .Sh HISTORY The implementation is based on KAME stack (which is descendant of WIDE hydrangea IPv6 stack kit). .Pp Part of the document was shamelessly copied from RFC2553 and RFC2292. .\" .Sh BUGS The .Dv IPV6_NEXTHOP object/option is not fully implemented as of writing this. Index: head/share/man/man4/kld.4 =================================================================== --- head/share/man/man4/kld.4 (revision 117010) +++ head/share/man/man4/kld.4 (revision 117011) @@ -1,168 +1,170 @@ .\" Copyright (c) 1993 Christopher G. Demetriou .\" 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 November 8, 1998 .Dt KLD 4 .Os .Sh NAME .Nm kld .Nd dynamic kernel linker facility .Sh DESCRIPTION The LKM (Loadable Kernel Modules) facility has been deprecated in .Fx 3.0 and above in favor of the .Nm interface. This interface, like its predecessor, allows the system administrator to dynamically add and remove -functionality from a running system. This ability also helps software +functionality from a running system. +This ability also helps software developers to develop new parts of the kernel without constantly rebooting to test their changes. .Pp Various types of modules can be loaded into the system. There are several defined module types, listed below, which can -be added to the system in a predefined way. In addition, there +be added to the system in a predefined way. +In addition, there is a generic type, for which the module itself handles loading and unloading. .Pp The .Fx system makes extensive use of loadable kernel modules, and provides loadable versions of most file systems, the .Tn NFS client and server, all the screen-savers, and the .Tn iBCS2 and .Tn Linux emulators. .Nm modules are placed by default in the .Pa /boot/kernel directory along with their matching kernel. .Pp The .Nm interface is used through the .Xr kldload 8 , .Xr kldunload 8 and .Xr kldstat 8 programs. .Pp The .Xr kldload 8 program can load either .Xr a.out 5 or ELF formatted loadable modules. The .Xr kldunload 8 program unloads any given loaded module, if no other module is dependent upon the given module. The .Xr kldstat 8 program is used to check the status of the modules currently loaded into the system. .Sh "MODULE TYPES" .Bl -ohang .It Em "Device Driver modules" New block and character device drivers may be loaded into the system with .Nm . Device nodes for the loaded drivers are automatically created when a module is loaded and destroyed when it is unloaded by .Xr devfs 5 . You can specify userland programs that will run when new devices become available as a result of loading modules, or existing devices go away when modules are unloaded, by configuring .Xr devd 8 . .El .Sh FILES .Bl -tag -width /usr/include/sys/module.h -compact .It Pa /boot/kernel directory containing module binaries built for the kernel also residing in the directory. .It Pa /usr/include/sys/module.h file containing definitions required to compile a .Nm module .It Pa /usr/share/examples/kld example source code implementing a sample kld module .El .Sh SEE ALSO .Xr kldfind 2 , .Xr kldfirstmod 2 , .Xr kldload 2 , .Xr kldnext 2 , .Xr kldstat 2 , .Xr kldunload 2 , .Xr devfs 5 , .Xr devd 8 , .Xr kldload 8 , .Xr kldstat 8 , .Xr kldunload 8 .Sh BUGS If a module B, is dependent on another module A, but is not compiled with module A as a dependency, then .Xr kldload 8 fails to load module B, even if module A is already present in the system. .Pp If multiple modules are dependent on module A, and are compiled with module A as a dependency, then .Xr kldload 8 loads an instance of module A when any of the modules are loaded. .Pp If a custom entry point is used for a module, and the module is compiled as an .Sq ELF binary, then .Xr kldload 8 fails to execute the entry point. .Pp .Xr kldload 8 returns the cryptic message .Sq Li "ENOEXEC (Exec format error)" for any error encountered while loading a module. .Pp When system internal interfaces change, old modules often cannot detect this, and such modules when loaded will often cause crashes or mysterious failures. -.Sh AUTHORS -The -.Nm -facility was originally implemented by -.An Doug Rabson Aq dfr@FreeBSD.org . .Sh HISTORY The .Nm facility appeared in .Fx 3.0 and was designed as a replacement for the .Xr lkm 4 facility, which was similar in functionality to the loadable kernel modules facility provided by .Tn SunOS 4.1.3. +.Sh AUTHORS +The +.Nm +facility was originally implemented by +.An Doug Rabson Aq dfr@FreeBSD.org . Index: head/share/man/man4/lp.4 =================================================================== --- head/share/man/man4/lp.4 (revision 117010) +++ head/share/man/man4/lp.4 (revision 117011) @@ -1,233 +1,245 @@ .\" -*- nroff -*- .\" .\" Copyright (c) 1996 A.R.Gordon, andrew.gordon@net-tel.co.uk .\" 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 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. .\" .\" Id: man4.i386/lp.4,v 1.9 1999/02/14 12:06:16 nsouch Exp .\" $FreeBSD$ .\" .Dd March 4, 1996 .Os .Dt LP 4 .Sh NAME .Nm lp .Nd printer port Internet Protocol driver .Sh SYNOPSIS .Nm ifconfig .Ar lp0 .Ar myaddress hisaddress .Op Fl link0 .Pp .Cd "device ppbus" .Cd "device plip" .Cd "device ppc" .Sh DESCRIPTION The .Nm driver allows a PC parallel printer port to be used as a point-to-point network interface between two similarly configured systems. Data is transferred 4 bits at a time, using the printer status lines for input: hence there is no requirement for special bidirectional hardware and any standard AT-compatible printer port with working interrupts may be used. .Pp During the boot process, for each .Nm plip device which is probed and has an interrupt assigned, a corresponding .Nm network device is created. .Pp Configuring an .Nm device with .Xr ifconfig 8 causes the corresponding .Nm parallel port bus to be reserved for PLIP until the network interface is configured 'down'. .Pp The communication protocol is selected by the .Cm link0 flag: .Bl -tag -width Fl .It Fl link0 (default) Use .Fx -mode (LPIP). This is the simpler of the two modes +mode (LPIP). +This is the simpler of the two modes and therefore slightly more efficient. .It Cm link0 -Use Crynwr/Linux compatible mode (CLPIP). This mode has a simulated ethernet +Use Crynwr/Linux compatible mode (CLPIP). +This mode has a simulated ethernet packet header, and is easier to interface to other types of equipment. .El .Pp -The interface MTU defaults to 1500, but may be set to any value. Both ends +The interface MTU defaults to 1500, but may be set to any value. +Both ends of the link must be configured with the same MTU. .Ss Cable Connections The cable connecting the two parallel ports should be wired as follows: .Bd -literal Pin Pin Description 2 15 Data0 -> ERROR* 3 13 Data1 -> SLCT 4 12 Data2 -> PE 5 10 Data3 -> ACK* 6 11 Data4 -> BUSY 15 2 ERROR* -> Data0 13 3 SLCT -> Data1 12 4 PE -> Data2 10 5 ACK* -> Data3 11 6 BUSY -> Data4 18-25 18-25 Ground .Ed .Pp Cables with this wiring are widely available as 'Laplink' cables, and are often coloured yellow. .Pp The connections are symmetric, and provide 5 lines in each direction (four -data plus one handshake). The two modes use the same wiring, but make a +data plus one handshake). +The two modes use the same wiring, but make a different choice of which line to use as handshake. .Ss FreeBSD LPIP mode The signal lines are used as follows: .Bl -tag -width dataxxxx(Pinxx) .It Em Data0 (Pin 2) Data out, bit 0. .It Em Data1 (Pin 3) Data out, bit 1. .It Em Data2 (Pin 4) Data out, bit 2. .It Em Data3 (Pin 5) Handshake out. .It Em Data4 (Pin 6) Data out, bit 3. .It Em ERROR* (pin 15) Data in, bit 0. .It Em SLCT (pin 13) Data in, bit 1. .It Em PE (pin 12) Data in, bit 2. .It Em BUSY (pin 11) Data in, bit 3. .It Em ACK* (pin 10) Handshake in. .El .Pp -When idle, all data lines are at zero. Each byte is signalled in four steps: +When idle, all data lines are at zero. +Each byte is signalled in four steps: sender writes the 4 most significant bits and raises the handshake line; receiver reads the 4 bits and raises its handshake to acknowledge; sender places the 4 least significant bits on the data lines and lowers the handshake; receiver reads the data and lowers its handshake. .Pp The packet format has a two-byte header, comprising the fixed values 0x08, 0x00, immediately followed by the IP header and data. .Pp The start of a packet is indicated by simply signalling the first byte -of the header. The end of the packet is indicated by inverting +of the header. +The end of the packet is indicated by inverting the data lines (ie. writing the ones-complement of the previous nibble to be transmitted) without changing the state of the handshake. .Pp Note that the end-of-packet marker assumes that the handshake signal and the data-out bits can be written in a single instruction - otherwise certain byte values in the packet data would falsely be interpreted -as end-of-packet. This is not a problem for the PC printer port, +as end-of-packet. +This is not a problem for the PC printer port, but requires care when implementing this protocol on other equipment. .Ss Crynwr/Linux CLPIP mode The signal lines are used as follows: .Bl -tag -width dataxxxx(Pinxx) .It Em Data0 (Pin 2) Data out, bit 0. .It Em Data1 (Pin 3) Data out, bit 1. .It Em Data2 (Pin 4) Data out, bit 2. .It Em Data3 (Pin 5) Data out, bit 3. .It Em Data4 (Pin 6) Handshake out. .It Em ERROR* (pin 15) Data in, bit 0. .It Em SLCT (pin 13) Data in, bit 1. .It Em PE (pin 12) Data in, bit 2. .It Em ACK* (pin 10) Data in, bit 3. .It Em BUSY (pin 11) Handshake in. .El .Pp -When idle, all data lines are at zero. Each byte is signalled in four steps: +When idle, all data lines are at zero. +Each byte is signalled in four steps: sender writes the 4 least significant bits and raises the handshake line; receiver reads the 4 bits and raises its handshake to acknowledge; sender places the 4 most significant bits on the data lines and lowers the handshake; receiver reads the data and lowers its handshake. [Note that this is the opposite nibble order to LPIP mode]. .Pp Packet format is: .Bd -literal Length (least significant byte) Length (most significant byte) 12 bytes of supposed MAC addresses (ignored by FreeBSD). Fixed byte 0x08 Fixed byte 0x00 Checksum byte. .Ed .Pp The length includes the 14 header bytes, but not the length bytes themselves nor the checksum byte. .Pp The checksum is a simple arithmetic sum of all the bytes (again, including the header but not checksum or length bytes). .Fx calculates outgoing checksums, but does not validate incoming ones. .Pp The start of packet has to be signalled specially, since the line chosen -for handshake-in cannot be used to generate an interrupt. The sender -writes the value 0x08 to the data lines, and waits for the receiver -to respond by writing 0x01 to its data lines. The sender then starts +for handshake-in cannot be used to generate an interrupt. +The sender writes the value 0x08 to the data lines, and waits for the receiver +to respond by writing 0x01 to its data lines. +The sender then starts signalling the first byte of the packet (the length byte). .Pp End of packet is deduced from the packet length and is not signalled specially (although the data lines are restored to the zero, idle state to avoid spuriously indicating the start of the next packet). .Sh SEE ALSO .Xr ppbus 4 , .Xr ppc 4 , .Xr ifconfig 8 .Sh BUGS Busy-waiting loops are used while handshaking bytes, (and worse still when waiting for the receiving system to respond to an interrupt for the start -of a packet). Hence a fast system talking to a slow one will consume -excessive amounts of CPU. This is unavoidable in the case of CLPIP mode +of a packet). +Hence a fast system talking to a slow one will consume +excessive amounts of CPU. +This is unavoidable in the case of CLPIP mode due to the choice of handshake lines; it could theoretically be improved in the case of LPIP mode. .Pp Polling timeouts are controlled by counting loop iterations rather than -timers, and so are dependent on CPU speed. This is somewhat stabilised +timers, and so are dependent on CPU speed. +This is somewhat stabilised by the need to perform (slow) ISA bus cycles to actually read the port. Index: head/share/man/man4/lpt.4 =================================================================== --- head/share/man/man4/lpt.4 (revision 117010) +++ head/share/man/man4/lpt.4 (revision 117011) @@ -1,97 +1,98 @@ .\" .\" Copyright (c) 1993 Christopher G. Demetriou .\" Copyright (c) 1994 Geoffrey M. Rehmet .\" Copyright (c) 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 February 14, 1999 .Dt LPT 4 .Os .Sh NAME .Nm lpt .Nd generic printer device driver .Sh SYNOPSIS .Cd "device ppc" .Cd "device ppbus" .Cd "device lpt" .Sh DESCRIPTION The current .Em lpt driver is the port of the original lpt driver to the .Xr ppbus 4 system. .Pp One purpose of this port was to allow parallel port sharing with other parallel devices. Secondly, inb()/outb() calls have been replaced by ppbus function calls. lpt is now arch-independent thanks to the ppbus interface. See .Xr ppbus 4 for more info about the ppbus system. .Pp The parallel port bus is allocated by lpt when the printer device is opened and released only when the transfer is completed: either when the device is closed or when the entire buffer is sent in interrupt driven mode. .Pp The driver can be configured to be either interrupt-driven, or -to poll the printer. Ports that are configured to be +to poll the printer. +Ports that are configured to be interrupt-driven can be switched to polled mode by using the .Xr lptcontrol 8 command. .Pp Depending on your hardware, extended capabilities may be configured with the .Xr lptcontrol 8 command. With an ECP/ISA port, you can take advantage of FIFO and DMA. .Pp In order to retrieve printer info from /dev/lpt0, just apply the .Nm cat command to the device. If the printer supports IEEE1284 nibble mode and has data to send to the host, you'll get it. .Sh SEE ALSO .Xr ppbus 4 , .Xr ppc 4 , .Xr lptcontrol 8 .Sh HISTORY This driver replaces the functionality of the lpa driver, which is now defunct. .Sh FILES .Bl -tag -width Pa -compact .It Pa /dev/lpt0 first parallel port driver .El .Sh BUGS There are lots of them, especially in cheap parallel port implementations. .Pp It is only possible to open a lpt port when a printer is connected and on-line, making it impossible to run .Xr lptcontrol 8 when there is no printer connected. .Pp This driver could still stand a rewrite. Index: head/share/man/man4/man4.i386/pae.4 =================================================================== --- head/share/man/man4/man4.i386/pae.4 (revision 117010) +++ head/share/man/man4/man4.i386/pae.4 (revision 117011) @@ -1,123 +1,124 @@ .\" .\" Copyright (c) 2003 Networks Associates Technology, Inc. .\" All rights reserved. .\" .\" This software was developed for the FreeBSD Project by Jake Burkholder, .\" Safeport Network Services, and Network Associates Laboratories, the .\" Security Research Division of Network Associates, Inc. under .\" DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the DARPA .\" CHATS research program. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE 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 8, 2003 .Dt PAE 4 i386 .Os .Sh NAME .Nm PAE .Sh SYNOPSIS .Cd "options PAE" .Sh DESCRIPTION The .Dv PAE option provides support for the physical address extensions capability of the .Tn Intel .Tn Pentium Pro and above CPUs, and allows for up to 64 gigabytes of memory to be used in systems capable of supporting it. With the .Dv PAE option, memory above 4 gigabytes is simply added to the general page pool. The system makes no distinction between memory above or below 4 gigabytes, and no specific facility is provided for a process or the kernel to access more memory than they would otherwise be able to access, through a sliding window or otherwise. .Sh SEE ALSO .Xr smp 4 , .Xr tuning 7 , -.Xr config 8 +.Xr config 8 , +.Xr bus_dma 9 .Sh HISTORY The .Dv PAE option first appeared in .Fx 5.1 . .Sh AUTHORS .An Jake Burkholder Aq jake@FreeBSD.org .Sh BUGS Since KLD modules are not compiled with the same options headers that the kernel is compiled with, they must not be loaded into a kernel compiled with the .Dv PAE option. .Pp Many devices or their device drivers are not capable of direct memory access to physical addresses above 4 gigabytes. In order to make use of direct memory access IO in a system with more than 4 gigabytes of memory when the .Dv PAE option is used, these drivers must use a facility for remapping or substituting physical memory which is not accessible to the device. One such facility is provided by the .Nm busdma interface. Device drivers which do not account for such devices will not work reliably in a system with more than 4 gigabytes of memory when the .Dv PAE option is used, and may cause data corruption. The .Pa PAE kernel configuration file includes the .Dv PAE option, and explicitly excludes all device drivers which are known to not work or have not been tested in a system with the .Dv PAE option and more than 4 gigabytes of memory. .Pp Many parameters which determine how memory is used in the kernel are based on the amount of physical memory. The formulas used to determine the values of these paramters for specific memory configurations may not take into account the fact there may be more than 4 gigabytes of memory, and may not scale well to these memory configurations. In particular, it may be necessary to increase the amount of virtual address space available to the kernel, or to reduce the amount of a specific resource that is heavily used, in order to avoid running out of virtual address space. The .Dv KVA_PAGES option may be used to increase the kernel virtual address space, and the .Va kern.maxvnodes .Xr sysctl 8 may be used to decrease the number of vnodes allowed, an example of a resource that the kernel is likely to overallocate in large memory configurations. For optimal performance and stability it may be necessary to consult the .Xr tuning 7 manual page, and make adjustments to the parameters documented there. Index: head/share/man/man4/matcd.4 =================================================================== --- head/share/man/man4/matcd.4 (revision 117010) +++ head/share/man/man4/matcd.4 (revision 117011) @@ -1,454 +1,454 @@ .\"Matsushita(Panasonic) / Creative Compact Disc Drive Driver (matcd) .\"Authored by Frank Durda IV .\" .\"Program and Documentation are Copyright 1994, 1995, 2003, 2003 Frank Durda IV. .\"All rights reserved. .\" "FDIV" is a trademark of Frank Durda IV. .\" .\" .\"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 their 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. .\" .\"-------------------------------------------------------------------------- .\"Dedicated to: My family, my grandfather, .\" and Max, my Golden Retriever .\" .\" Please note any documentation updates here including your name .\" and the date. .\"<2> Text brought in sync with changes made in versions 1(17) - 1(21) .\" Frank Durda IV 4-Jul-1995 .\"<3> Text brought in sync with changes made in versions 1(22) - 1(25) .\" Frank Durda IV 24-Sep-1995 .\"<4> Overhaul of man page to match version 3(41) (FreeBSD 5.0 support) .\" and style changes noted in other 5.x era man pages. .\" Frank Durda IV 17-Apr-2003 .\"<5> Aligned with version 3(42) (FreeBSD pre5.1 support) .\" Frank Durda IV 10-May-2003 .\" .\" $FreeBSD$ .\" .Dd May 10, 2003 .Dt MATCD 4 i386 .\"Synchronized to Version 3(42) of matcd.c .Os .Sh NAME .Nm matcd .Nd Matsushita (Panasonic) Compact Disc drive driver .Sh SYNOPSIS .Cd "device matcd" .Pp In .Pa /boot/device.hints : .Cd hint.matcd.\fI[0-3]\fP.at="isa" .Cd hint.matcd.\fI[0-3]\fP.port="\fIaddress\fP" .Sh DESCRIPTION The .Nm driver controls the CR-562 and CR-563 Compact Disc drives made by Matsushita-Kotobuki Electronics Industries, or Matsushita for short. These drives were sold under the Panasonic (which is a trade name for Matsushita), Creative Labs (omniCD) and Reveal names, and were also included in computers that were made by Tandy, GRiD, Victor, AST, Packard Bell and many other brands. .Pp The drives are compatible with the major the Compact Disc standards, including CD-DA (Red Book - Digital Audio on pressed media), CD-WO (Orange Book Part II - Write-Once media), CD-ROM (Yellow Book - Data Storage), and the Kodak Photo-CD system. The drives have some support related to CD-ROM XA and CD-I (Green Book) audio and data requirements. .Pp These drives connect to the PC ISA bus through a simple (but proprietary) host interface. The host interface has been manufactured as a stand-alone adapter card, or included on a sound card or other multi-function adapter card. The .Nm driver supports up to four host interfaces with up to four drives on each interface. CD-DA (digital audio) activity may occur on all drives simultaneously. .Pp The drive hardware supports a "bus disconnect" system similar to that found in SCSI, and this allows simultaneous data read operations to be in progress on multiple drives on the same host interface, but the driver currently limits read operations to one active drive per host interface at a time. Despite this, all four drives on a given host interface are able deliver data at their full rated transfer rate for sequential blocks simultaneously, thanks to a modest read-ahead buffer in each drive. .Sh DRIVER INSTALLATION The .Nm driver can be directly linked into the .Fx kernel, or exist as a loadable .Fx kernel module. The kernel module can be loaded or unloaded at any time using the \fBkldload\fR(8)/\fBkldunload\fR(8) commands. .Pp For most configurations, the .Nm driver should be used as a loadable kernel module and need not be linked into the kernel. However, if you are attempting to do an install from a CD-ROM/CD-WO disc that is initiated from a non-FreeBSD operating system or you have a BIOS boot capability for this type of Compact Disc drive, having the driver already in the kernel can simplify the installation process. .Pp if you determine that you need to have the .Nm driver linked into the kernel, it is necessary to add an entry to the kernel configuration file and generate a new kernel. The .Fx kernel source tree comes with the file \fI/usr/src/sys/i386/conf/GENERIC\fR. You should make a copy of this file and give the copy the name of your system, such as "MYSYSTEM". You can then edit the new file to include devices you want the system to include in the basic kernel and delete the device entries for drivers that you don't want included. Eliminating drivers for hardware that you don't have can reduce the size of the finished kernel. .Pp To include the .Nm driver to the configuration file, you will need to add this entry: .Bd -literal -offset indent device matcd .Ed .Pp and after making any other adjustments, save the file. .Pp Then generate a new kernel by using the \fBconfig\fR(8) command and follow all of the instructions that are displayed. If the kernel completely builds, use the "make install" command and then reboot the system for that new kernel to become operational. .Sh DRIVER CONFIGURATION Regardless of whether the .Nm driver is linked into the kernel or is used as a loadable kernel module, the number of host interfaces that the driver will expect (or search for) is dictated by the number of entries present in the file \fI/boot/device\.hints\fR. For example, in order to support two host interfaces, you would include entries like: .Bd -literal -offset indent hint.matcd.0.at="isa" hint.matcd.0.port="0x230" hint.matcd.1.at="isa" hint.matcd.1.port="0x260" .Ed Each set of entries designates a different .Nm host interface, and where the I/O ports on that host interface adapter are located. .Pp (If you only want a single entry, include only the \fBhint.matcd.0\fR items, while add \fBhint.matcd.2\fR and \fBhint.matcd.3\fR as needed to support three or four host interfaces.) .Pp Note that the two \fBhint.matcd.0\fR entries in the \fI/boot/device\.hints\fR file are all that you need to support up to four drives on a single host interface. .Pp If the \fIaddress\fR parameter of a \fBhint.matcd.\fIn\fR.port="\fIaddress\fP"\fR entry in \fI/boot/device\.hints\fR file is set to "\fB-1\fR", the .Nm driver searches for the host interface adapters by using a table of known I/O ports on Creative host adapters contained in the driver itself (see \fI/usr/src/sys/dev/matcd/options.h\fR). .Pp Although the multiple port scan allows the .Nm driver to work with many different types of host adapters without adjustments, using this mechanism has the potential to cause problems when your system has other devices that are located at the I/O ports that the driver will check for potential .Nm host interfaces. The automatic search also significantly increases the amount of time it takes to boot or to load the kernel module. .Pp If you are having problems with the .Nm driver interfering with other adapters while it is probing for hardware, or you don't like the additional amount of time it takes for the entire search of I/O ports to complete, you can solve this by explicitly specifying where all the .Nm host interfaces are located. .Pp Traditionally, Creative Labs SoundBlaster cards have the Matsushita Compact Disc drive host interface located at I/O port 0x230, which is always 0x10 above where the first I/O port for the audio section of the card (0x220). .Pp If you have determined exactly where the Matsushita I/O ports start on your system, specify the port by setting the \fBhint.matcd.\fIn\fR.port="\fIaddress\fP"\fR entry at the kernel boot prompt, or by editing the entry in the \fI/boot/device\.hints\fR file. .Pp If you make a change to the \fI/boot/device\.hints\fR configuration file while the system is running, it is currently necessary to reboot the system before the updated values take effect. .Sh SUPPORTED HARDWARE At this time, there are only two known drive models that work with the .Nm driver: .Bl -item -width CR-123-X -compact -offset indent .It Matsushita CR-562-x .It Matsushita CR-563-x .El Most resellers leave these original markings on the drives since the label also has the FCC, VDE, CSA and RU certification marks. .Pp Both of these drive models have motorized trays. There is also a custom version of these drives that does not have the volume control or headphone jack (seen on some Tandy computers), but this drive also works with .Nm . On drives that lack a front headphone jack, audio from discs can still be obtained at line level via a connector on the rear of the drive. .Pp The Matsushita CR-522-x and CR-523-x Compact Disc drives are not usable with .Nm . The CR-522 and CR-523 models can also be identified from the front as they both require a CD-caddy. .Pp Later versions of Matsushita and "Creative" Compact Disc drives use a basic IDE interface, so these other drives must use an IDE driver, such as \fBata\fR(4). .Pp The TEAC CD-55 4X Compact Disc drive also uses the same Creative/Panasonic electrical interface, but the TEAC drive is not command set compatible with the Matsushita CR-56x drives. The TEAC drive cannot be used with .Nm . .Pp The most common source of host interface adapters for the Panasonic drives was found in products from Creative Labs, including SoundBlaster sound cards. There are numerous models of SoundBlaster sound cards, and most of the newer cards provide the appropriate interface, sometimes labeled as the "Creative/Panasonic" interface. .Pp The following host interface adapters are known to work with the .Nm driver: .Bl -tag -width LONGNAME -compact -offset indent .It Creative Sound Blaster Pro (SBPRO) (CT1330A) .It Creative Sound Blaster 16 (CT1730) .It Creative Sound Blaster 16 - cost-reduced (CT1740) .It Creative OmniCD upgrade kit adapter card - stand-alone CD (CT1810) .It Creative Sound Blaster 16 - 2-layer, cost-reduced (CT2230) .It Creative Sound Blaster 16 (Vibra16) - 2-layer, single-chip (CT2260) .It Creative Sound Blaster 16 Value (SB16) - 2-layer, cost-reduced (CT2770) .It Creative PhoneBlaster SB16 + Sierra 14.4K Voice/FAX/Data/Speakerphone modem combo (CT3100) .It Reveal (SC400) .El .Pp Caution: Some of these sound boards can be optionally manufactured to not include the Panasonic/Creative interface connector and electronics, so check the board visually to verify that the "Creative" or "Panasonic" drive connector is actually there before buying the card solely based on model number. .Pp This is by no means a complete list as Creative Labs and other vendors that produce sound cards with an identical Creative/Panasonic drive interface released many versions of compatible adapters. .Pp In addition to Creative Labs adapters, adapters that are compatible with Media Vision, IBM and Lasermate adapters are also supported. However, these adapters use a wide range of I/O port addresses, so the driver must be reconfigured to locate these adapters, at least initially. .Pp .Sh SUPPORTED OPERATIONS The .Nm driver supports block and character access. Partition "a" returns 2048-byte User Data blocks from data CDs. Partition "c" returns the full 2352-byte Frames from any type of CD, including audio CDs. (Partition -"c" cannot be "mounted" with cd9660 or other standard filesystem emulators.) +"c" cannot be "mounted" with cd9660 or other standard file system emulators.) No other partitions are supported. .Pp The .Nm matcdl devices work the same as the normal .Nm devices except that the drive trays are locked and remain locked until all of the devs on that drive are closed. .Pp .Nm Matcd accepts numerous .Fn ioctl commands, including functions related to Compact Disc audio and drive tray control features. The commands are: .Pp .Bl -tag -width CDIOCREADSUBCHANNELXXX -compact -offset indent .It DIOCGDINFO get disklabel. .It CDIOCREADSUBCHANNEL report the current optical pick-up position and sub channel data. .It CDIOCREADTOCHEADER reads table of contents summary from the disc. .It CDIOCREADTOCENTRYS reads length/size and other control information for an individual track. .It CDIOCPLAYTRACKS plays audio starting at a track/index and stopping at a track/index. .It CDIOCPLAYBLOCKS plays audio starting at a block and stopping at a block. .It CDIOCPLAYMSF plays audio starting at a particular time offset. .It CDIOCPAUSE pauses a playing disc. .It CDIOCRESUME resumes playing a previously paused disc. Ignored if the drive is already playing. .It CDIOCSTOP stops playing a disc. .It CDIOCEJECT opens the disc tray. .It CDIOCCLOSE closes the disc tray. .It CDIOCPREVENT blocks further attempts to open the drive door until all devices close or a CDIOCALLOW ioctl is issued. .It CDIOCALLOW unlocks the drive door if it was locked. This ioctl is rejected if any locking devices are open, so it must be issued via a non-locking device. .It CDIOCGETVOL returns the current volume settings of the drive. .It CDIOCSETVOL sets the volume settings of the drive. .It CDIOCSETSTEREO the left channel audio is sent to the left channel output and the right channel audio is sent to the right channel output. This is the default state. (Note that the drive does not have a documented "Mono" mode, where L combined with R audio from the disc is sent to both the left and right output channels.) .It CDIOCSETMUTE the audio output is to be turned off. The drive continues to read the audio on the disc and that audio is discarded until the audio routing is turned back on. .It CDIOCSETLEFT the left channel audio is to be sent to the left and right channel outputs. The right channel audio signal is discarded. .It CDIOCSETRIGHT the right channel audio is to be sent to the left and right channel outputs. The left channel audio signal is discarded. .It CDIOCSETPATCH the audio is to be routed as specified in the provided bit maps. .It CDIOCSETPITCH the playback speed of the audio is increased or decreased (for Karaoke "off-key" applications). Speed can be adjusted +/-13%. .It CDIOCCAPABILITY report the capabilities of the drive and driver. Results are returned as shown in \fI/usr/include/sys/cdio.h\fR. .El .Pp The .Fn ioctl commands defined above are the only ones that the .Nm driver supports. .Sh FILES .Bl -tag -width /usr/src/sys/dev/matcd/options.h -compact .It Pa /dev/matcd[0-15]a Used to access 2048-byte blocks of data on a Compact Disc that is recorded in the Mode 1 Form 1 format. .It Pa /dev/matcd[0-15]la Used to access 2048-byte blocks of data on a Compact Disc that is recorded in the Mode 1 Form 1 format and disables the disc eject controls. .It Pa /dev/matcd[0-15]c Used to access 2352-byte frames on a Compact Disc recorded in any format. .It Pa /dev/matcd[0-15]lc Used to access 2352-byte frames on a Compact Disc recorded in any format and disables the disc eject controls. .It Pa /boot/devices.hints Specify the number of host interfaces and host adapter I/O port locations that .Nm should examine. .It Pa /usr/src/sys/dev/matcd/* Source code for .Nm . .It Pa /usr/src/sys/dev/matcd/options.h Contains all of the compilation options for .Nm . .El .Sh NOTES The various Creative/Panasonic host interface adapters do not use interrupts or DMA although the drives themselves are equipped to allow both to be used. .Pp If the disc tray is opened while one or more partitions are open, further I/O to all partitions on the drive will be rejected until all partitions are closed. This prevents a disc change from going undetected by higher levels of the operating system. .Pp There must be a drive on each host interface that is addressed as physical drive 0. (Jumpers on the back of the drive control this setting.) If there is no physical drive 0, the .Nm driver will be unable to detect that host interface or any of the drives connected to that host interface. .Pp It is not necessary to have four drives attached to the first host interface before being able to activate a second host interface, but each interface must have at least one drive jumpered to be drive 0. .Pp Drives on a second host interface are considered logical drive numbers 4 through 7, drives 8 through 11 are on the third interface and 12 through 15 are on the fourth. The first drive on the second host interface is always logical drive 4 regardless of how many drives are present on the first host interface. .Pp Host interfaces are numbered as specified in the \fI/boot/devices.hints\fR file. .Sh SEE ALSO .Xr /usr/include/sys/cdio.h , .Xr kldload 8 , .Xr kldunload 8 .Sh AUTHORS The driver and documentation was written by .An Frank Durda IV . .Pp Program and Documentation are Copyright 1994, 1995, 2002, 2003, All rights reserved. .Sh HISTORY The .Nm driver originally appeared in .Fx 2.0.5 . The .Fx 5.1.x compatible implementation described here appeared in .Fx 5.2.0. Index: head/share/man/man4/mem.4 =================================================================== --- head/share/man/man4/mem.4 (revision 117010) +++ head/share/man/man4/mem.4 (revision 117011) @@ -1,193 +1,203 @@ .\" Copyright (c) 1991 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. .\" .\" @(#)mem.4 5.3 (Berkeley) 5/2/91 .\" $FreeBSD$ .\" .Dd May 2, 1991 .Dt MEM 4 .Os .Sh NAME .Nm mem , .Nm kmem .Nd memory files .Sh DESCRIPTION The special file -.Nm /dev/mem +.Pa /dev/mem is an interface to the physical memory of the computer. Byte offsets in this file are interpreted as physical memory addresses. Reading and writing this file is equivalent to reading and writing memory itself. Only offsets within the bounds of -.Nm /dev/mem +.Pa /dev/mem are allowed. .Pp Kernel virtual memory is accessed through the interface -.Nm /dev/kmem +.Pa /dev/kmem in the same manner as -.Nm /dev/mem . +.Pa /dev/mem . Only kernel virtual addresses that are currently mapped to memory are allowed. .Pp On .Tn ISA the .Tn I/O memory space begins at physical address 0x000a0000 and runs to 0x00100000. The per-process data size for the current process is .Dv UPAGES long, and ends at virtual address 0xf0000000. .Sh IOCTL INTERFACE Several architectures allow attributes to be associated with ranges of physical -memory. These attributes can be manipulated via +memory. +These attributes can be manipulated via .Fn ioctl calls performed on -.Nm /dev/mem . +.Pa /dev/mem . Declarations and data types are to be found in -.Pa +.Aq Pa sys/memrange.h . .Pp The specific attributes, and number of programmable ranges may vary between -architectures. The full set of supported attributes is: +architectures. +The full set of supported attributes is: .Bl -tag -width indent -.It MDF_UNCACHEABLE +.It Dv MDF_UNCACHEABLE The region is not cached. -.It MDF_WRITECOMBINE +.It Dv MDF_WRITECOMBINE Writes to the region may be combined or performed out of order. -.It MDF_WRITETHROUGH +.It Dv MDF_WRITETHROUGH Writes to the region are committed synchronously. -.It MDF_WRITEBACK +.It Dv MDF_WRITEBACK Writes to the region are committed asynchronously. -.It MDF_WRITEPROTECT +.It Dv MDF_WRITEPROTECT The region cannot be written to. .El .Pp Memory ranges are described by -.Fa struct mem_range_desc : +.Vt struct mem_range_desc : .Bd -literal -offset indent u_int64_t mr_base; /\(** physical base address \(**/ u_int64_t mr_len; /\(** physical length of region \(**/ int mr_flags; /\(** attributes of region \(**/ char mr_owner[8]; .Ed .Pp In addition to the region attributes listed above, the following flags may also be set in the .Fa mr_flags field: .Bl -tag -width indent .It MDF_FIXBASE The region's base address cannot be changed. .It MDF_FIXLEN The region's length cannot be changed. .It MDF_FIRMWARE The region is believed to have been established by the system firmware. .It MDF_ACTIVE The region is currently active. .It MDF_BOGUS We believe the region to be invalid or otherwise erroneous. .It MDF_FIXACTIVE The region cannot be disabled. .It MDF_BUSY The region is currently owned by another process and may not be altered. .El .Pp Operations are performed using .Fa struct mem_range_op : .Bd -literal -offset indent struct mem_range_desc *mo_desc; int mo_arg[2]; .Ed .Pp The -.Fa MEMRANGE_GET +.Dv MEMRANGE_GET ioctl is used to retrieve current memory range attributes. If -.Fa mo_arg[0] +.Va mo_arg[0] is set to 0, it will be updated with the total number of memory range -descriptors. If greater than 0, the array at -.Fa mo_desc +descriptors. +If greater than 0, the array at +.Va mo_desc will be filled with a corresponding number of descriptor structures, or the maximum, whichever is less. .Pp The -.Fa MEMRANGE_SET +.Dv MEMRANGE_SET ioctl is used to add, alter and remove memory range attributes. A range -with the MDF_FIXACTIVE flag may not be removed; a range with the MDF_BUSY +with the +.Dv MDF_FIXACTIVE +flag may not be removed; a range with the +.Dv MDF_BUSY flag may not be removed or updated. .Pp -.Fa mo_arg[0] -should be set to MEMRANGE_SET_UPDATE to update an existing -or establish a new range, or to MEMRANGE_SET_REMOVE to remove a range. +.Va mo_arg[0] +should be set to +.Dv MEMRANGE_SET_UPDATE +to update an existing or establish a new range, or to +.Dv MEMRANGE_SET_REMOVE +to remove a range. .Sh RETURN VALUES .Bl -tag -width Er .It Bq Er EOPNOTSUPP Memory range operations are not supported on this architecture. .It Bq Er ENXIO No memory range descriptors are available (eg. firmware has not enabled any). .It Bq Er EINVAL The memory range supplied as an argument is invalid or overlaps another range in a fashion not supported by this architecture. .It Bq Er EBUSY An attempt to remove or update a range failed because the range is busy. .It Bq Er ENOSPC An attempt to create a new range failed due to a shortage of hardware resources (eg. descriptor slots). .It Bq Er ENOENT An attempt to remove a range failed because no range matches the descriptor base/length supplied. .It Bq Er EPERM An attempt to remove a range failed because the range is permanently enabled. .El .Sh BUGS Busy range attributes are not yet managed correctly. .Sh FILES .Bl -tag -width /dev/kmem -compact .It Pa /dev/mem .It Pa /dev/kmem .El .Sh SEE ALSO .Xr memcontrol 8 .Sh HISTORY The -.Nm , +.Nm mem +and .Nm kmem files appeared in .At v6 . The ioctl interface for memory range attributes was added in .Fx 3.2 . Index: head/share/man/man4/mtio.4 =================================================================== --- head/share/man/man4/mtio.4 (revision 117010) +++ head/share/man/man4/mtio.4 (revision 117011) @@ -1,314 +1,315 @@ .\" Copyright (c) 1996 .\" Mike Pritchard . All rights reserved. .\" .\" 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. .\" .\" @(#)mtio.4 8.1 (Berkeley) 6/5/93 .\" $FreeBSD$ .\" .Dd February 11, 1996 .Dt MTIO 4 .Os .Sh NAME .Nm mtio .Nd FreeBSD magtape interface .Sh DESCRIPTION The special files named .Pa /dev/[nr]sa* refer to SCSI tape drives, which may be attached to the system. .Pa /dev/[nr]sa*.ctl are control devices that can be used to issue ioctls to the SCSI tape driver to set parameters that are required to last beyond the unmounting of a tape. .Pp .Pp The rewind devices automatically rewind when the last requested read, write or seek has finished, or the end of the tape has been reached. The letter .Ql n is usually prepended to the name of the no-rewind devices. .Pp Tapes can be written with either fixed length records or variable length records. See .Xr sa 4 -for more information. Two end-of-file markers mark the end of a tape, and +for more information. +Two end-of-file markers mark the end of a tape, and one end-of-file marker marks the end of a tape file. If the tape is not to be rewound it is positioned with the head in between the two tape marks, where the next write will over write the second end-of-file marker. .Pp All of the magtape devices may be manipulated with the .Xr mt 1 command. .Pp A number of .Xr ioctl 2 operations are available on raw magnetic tape. The following definitions are from .Aq Pa sys/mtio.h : .Bd -literal #ifndef _SYS_MTIO_H_ #define _SYS_MTIO_H_ #ifndef _KERNEL #include #endif #include /* * Structures and definitions for mag tape io control commands */ /* structure for MTIOCTOP - mag tape op command */ struct mtop { short mt_op; /* operations defined below */ daddr_t mt_count; /* how many of them */ }; /* operations */ #define MTWEOF 0 /* write an end-of-file record */ #define MTFSF 1 /* forward space file */ #define MTBSF 2 /* backward space file */ #define MTFSR 3 /* forward space record */ #define MTBSR 4 /* backward space record */ #define MTREW 5 /* rewind */ #define MTOFFL 6 /* rewind and put the drive offline */ #define MTNOP 7 /* no operation, sets status only */ #define MTCACHE 8 /* enable controller cache */ #define MTNOCACHE 9 /* disable controller cache */ #if defined(__FreeBSD__) /* Set block size for device. If device is a variable size dev */ /* a non zero parameter will change the device to a fixed block size */ /* device with block size set to that of the parameter passed in. */ /* Resetting the block size to 0 will restore the device to a variable */ /* block size device. */ #define MTSETBSIZ 10 /* Set density values for device. Sets the value for the opened mode only. */ #define MTSETDNSTY 11 #define MTERASE 12 /* erase to EOM */ #define MTEOD 13 /* Space to EOM */ #define MTCOMP 14 /* select compression mode 0=off, 1=def */ #define MTRETENS 15 /* re-tension tape */ #define MTWSS 16 /* write setmark(s) */ #define MTFSS 17 /* forward space setmark */ #define MTBSS 18 /* backward space setmark */ #define MT_COMP_ENABLE 0xffffffff #define MT_COMP_DISABLED 0xfffffffe #define MT_COMP_UNSUPP 0xfffffffd /* * Values in mt_dsreg that say what the device is doing */ #define MTIO_DSREG_NIL 0 /* Unknown */ #define MTIO_DSREG_REST 1 /* Doing Nothing */ #define MTIO_DSREG_RBSY 2 /* Communicating with tape (but no motion) */ #define MTIO_DSREG_WR 20 /* Writing */ #define MTIO_DSREG_FMK 21 /* Writing Filemarks */ #define MTIO_DSREG_ZER 22 /* Erasing */ #define MTIO_DSREG_RD 30 /* Reading */ #define MTIO_DSREG_FWD 40 /* Spacing Forward */ #define MTIO_DSREG_REV 41 /* Spacing Reverse */ #define MTIO_DSREG_POS 42 /* Hardware Positioning (direction unknown) */ #define MTIO_DSREG_REW 43 /* Rewinding */ #define MTIO_DSREG_TEN 44 /* Retensioning */ #define MTIO_DSREG_UNL 45 /* Unloading */ #define MTIO_DSREG_LD 46 /* Loading */ #endif /* __FreeBSD__ */ /* structure for MTIOCGET - mag tape get status command */ struct mtget { short mt_type; /* type of magtape device */ /* the following two registers are grossly device dependent */ short mt_dsreg; /* ``drive status'' register */ short mt_erreg; /* ``error'' register */ /* end device-dependent registers */ short mt_resid; /* residual count */ #if defined (__FreeBSD__) daddr_t mt_blksiz; /* presently operating blocksize */ daddr_t mt_density; /* presently operating density */ u_int32_t mt_comp; /* presently operating compression */ daddr_t mt_blksiz0; /* blocksize for mode 0 */ daddr_t mt_blksiz1; /* blocksize for mode 1 */ daddr_t mt_blksiz2; /* blocksize for mode 2 */ daddr_t mt_blksiz3; /* blocksize for mode 3 */ daddr_t mt_density0; /* density for mode 0 */ daddr_t mt_density1; /* density for mode 1 */ daddr_t mt_density2; /* density for mode 2 */ daddr_t mt_density3; /* density for mode 3 */ /* the following are not yet implemented */ u_int32_t mt_comp0; /* compression type for mode 0 */ u_int32_t mt_comp1; /* compression type for mode 1 */ u_int32_t mt_comp2; /* compression type for mode 2 */ u_int32_t mt_comp3; /* compression type for mode 3 */ /* end not yet implemented */ #endif daddr_t mt_fileno; /* relative file number of current position */ daddr_t mt_blkno; /* relative block number of current position */ }; /* structure for MTIOCERRSTAT - tape get error status command */ /* really only supported for SCSI tapes right now */ struct scsi_tape_errors { /* * These are latched from the last command that had a SCSI * Check Condition noted for these operations. The act * of issuing an MTIOCERRSTAT unlatches and clears them. */ u_int8_t io_sense[32]; /* Last Sense Data For Data I/O */ u_int32_t io_resid; /* residual count from last Data I/O */ u_int8_t io_cdb[16]; /* Command that Caused the Last Data Sense */ u_int8_t ctl_sense[32]; /* Last Sense Data For Control I/O */ u_int32_t ctl_resid; /* residual count from last Control I/O */ u_int8_t ctl_cdb[16]; /* Command that Caused the Last Control Sense */ /* * These are the read and write cumulative error counters. * (how to reset cumulative error counters is not yet defined). * (not implemented as yet but space is being reserved for them) */ struct { u_int32_t retries; /* total # retries performed */ u_int32_t corrected; /* total # corrections performed */ u_int32_t processed; /* total # corrections successful */ u_int32_t failures; /* total # corrections/retries failed */ u_int64_t nbytes; /* total # bytes processed */ } wterr, rderr; }; union mterrstat { struct scsi_tape_errors scsi_errstat; char _reserved_padding[256]; }; /* * Constants for mt_type byte. These are the same * for controllers compatible with the types listed. */ #define MT_ISTS 0x01 /* TS-11 */ #define MT_ISHT 0x02 /* TM03 Massbus: TE16, TU45, TU77 */ #define MT_ISTM 0x03 /* TM11/TE10 Unibus */ #define MT_ISMT 0x04 /* TM78/TU78 Massbus */ #define MT_ISUT 0x05 /* SI TU-45 emulation on Unibus */ #define MT_ISCPC 0x06 /* SUN */ #define MT_ISAR 0x07 /* SUN */ #define MT_ISTMSCP 0x08 /* DEC TMSCP protocol (TU81, TK50) */ #define MT_ISCY 0x09 /* CCI Cipher */ #define MT_ISCT 0x0a /* HP 1/4 tape */ #define MT_ISFHP 0x0b /* HP 7980 1/2 tape */ #define MT_ISEXABYTE 0x0c /* Exabyte */ #define MT_ISEXA8200 0x0c /* Exabyte EXB-8200 */ #define MT_ISEXA8500 0x0d /* Exabyte EXB-8500 */ #define MT_ISVIPER1 0x0e /* Archive Viper-150 */ #define MT_ISPYTHON 0x0f /* Archive Python (DAT) */ #define MT_ISHPDAT 0x10 /* HP 35450A DAT drive */ #define MT_ISMFOUR 0x11 /* M4 Data 1/2 9track drive */ #define MT_ISTK50 0x12 /* DEC SCSI TK50 */ #define MT_ISMT02 0x13 /* Emulex MT02 SCSI tape controller */ /* mag tape io control commands */ #define MTIOCTOP _IOW('m', 1, struct mtop) /* do a mag tape op */ #define MTIOCGET _IOR('m', 2, struct mtget) /* get tape status */ /* these two do not appear to be used anywhere */ #define MTIOCIEOT _IO('m', 3) /* ignore EOT error */ #define MTIOCEEOT _IO('m', 4) /* enable EOT error */ /* * When more SCSI-3 SSC (streaming device) devices are out there * that support the full 32 byte type 2 structure, we'll have to * rethink these ioctls to support all the entities they haul into * the picture (64 bit blocks, logical file record numbers, etc..). */ #define MTIOCRDSPOS _IOR('m', 5, u_int32_t) /* get logical blk addr */ #define MTIOCRDHPOS _IOR('m', 6, u_int32_t) /* get hardware blk addr */ #define MTIOCSLOCATE _IOW('m', 5, u_int32_t) /* seek to logical blk addr */ #define MTIOCHLOCATE _IOW('m', 6, u_int32_t) /* seek to hardware blk addr */ #define MTIOCERRSTAT _IOR('m', 7, union mterrstat) /* get tape errors */ /* * Set EOT model- argument is number of filemarks to end a tape with. * Note that not all possible values will be accepted. */ #define MTIOCSETEOTMODEL _IOW('m', 8, u_int32_t) /* Get current EOT model */ #define MTIOCGETEOTMODEL _IOR('m', 8, u_int32_t) #ifndef _KERNEL #define DEFTAPE "/dev/nrsa0" #endif #ifdef _KERNEL /* * minor device number */ #define T_UNIT 003 /* unit selection */ #define T_NOREWIND 004 /* no rewind on close */ #define T_DENSEL 030 /* density select */ #define T_800BPI 000 /* select 800 bpi */ #define T_1600BPI 010 /* select 1600 bpi */ #define T_6250BPI 020 /* select 6250 bpi */ #define T_BADBPI 030 /* undefined selection */ #endif #endif /* !_SYS_MTIO_H_ */ .Ed .Sh FILES .Bl -tag -width /dev/[nr]sa* -compact .It Pa /dev/[nr]sa* .El .Sh SEE ALSO .Xr mt 1 , .Xr tar 1 , .Xr ast 4 , .Xr sa 4 .Sh HISTORY The .Nm manual appeared in .Bx 4.2 . An i386 version first appeared in .Fx 2.2 . .Sh BUGS The status should be returned in a device independent format. .Pp The special file naming should be redone in a more consistent and understandable manner. Index: head/share/man/man4/natm.4 =================================================================== --- head/share/man/man4/natm.4 (revision 117010) +++ head/share/man/man4/natm.4 (revision 117011) @@ -1,96 +1,100 @@ .\" $FreeBSD$ .\" .Dd December 29, 1997 .Dt NATM 4 .Os .Sh NAME .Nm natm .Nd Native Mode ATM protocol layer .Sh DESCRIPTION The .Bx ATM software comes with a .Em native mode ATM protocol layer which provides socket level access to AAL0 and AAL5 virtual circuits. To enable this protocol layer, add .Dl options NATM to your kernel configuration file and re-make the kernel (don't forget to do .Dq make clean ) . .Sh NATM API The NATM layer uses a -.Dv struct sockaddr_natm +.Vt struct sockaddr_natm to specify a virtual circuit: .Bd -literal -offset indent struct sockaddr_natm { u_int8_t snatm_len; /* length */ u_int8_t snatm_family; /* AF_NATM */ char snatm_if[IFNAMSIZ]; /* interface name */ u_int16_t snatm_vci; /* vci */ u_int8_t snatm_vpi; /* vpi */ }; .Ed .Pp To create an AAL5 connection to a virtual circuit with VPI 0, VCI 201 one would use the following: .Bd -literal -offset indent struct sockaddr_natm snatm; int s, r; s = socket(AF_NATM, SOCK_STREAM, PROTO_NATMAAL5); /* note: PROTO_NATMAAL0 is AAL0 */ if (s < 0) { perror("socket"); exit(1); } bzero(&snatm, sizeof(snatm)); snatm.snatm_len = sizeof(snatm); snatm.snatm_family = AF_NATM; sprintf(snatm.snatm_if, "en0"); snatm.snatm_vci = 201; snatm.snatm_vpi = 0; r = connect(s, (struct sockaddr *)&snatm, sizeof(snatm)); if (r < 0) { perror("connect"); exit(1); } /* s now connected to ATM! */ .Ed .Pp The .Fn socket -call simply creates an unconnected NATM socket. The +call simply creates an unconnected NATM socket. +The .Fn connect call associates an unconnected NATM socket with a virtual circuit and tells the driver to enable that virtual circuit -for receiving data. After the +for receiving data. +After the .Fn connect call one can .Fn read or .Fn write to the socket to perform ATM I/O. .Sh Internal NATM operation Internally, the NATM protocol layer keeps a list of all active virtual circuits on the system in .Dv natm_pcbs . This includes circuits currently being used for IP to prevent NATM and IP from clashing over virtual circuit usage. .Pp When a virtual circuit is enabled for receiving data, the NATM protocol layer passes the address of the protocol control block down to the driver as a receive .Dq handle . When inbound data arrives, the driver passes the data back with the -appropriate receive handle. The NATM layer uses this to avoid the -overhead of a protocol control block lookup. This allows us to take +appropriate receive handle. +The NATM layer uses this to avoid the +overhead of a protocol control block lookup. +This allows us to take advantage of the fact that ATM has already demultiplexed the data for us. .Sh CAVEAT The NATM protocol support is subject to change as -the ATM protocols develop. Users should not depend -on details of the current implementation, but rather +the ATM protocols develop. +Users should not depend on details of the current implementation, but rather the services exported. .Sh SEE ALSO .Xr en 4 , -.Xr hatm 4 , .Xr fatm 4 , +.Xr hatm 4 , .Xr natmip 4 .Sh AUTHORS .An Chuck Cranor of Washington University implemented the NATM protocol layer along with the EN ATM driver in 1996 for .Nx . Index: head/share/man/man4/netgraph.4 =================================================================== --- head/share/man/man4/netgraph.4 (revision 117010) +++ head/share/man/man4/netgraph.4 (revision 117011) @@ -1,1371 +1,1399 @@ .\" Copyright (c) 1996-1999 Whistle Communications, Inc. .\" All rights reserved. .\" .\" Subject to the following obligations and disclaimer of warranty, use and .\" redistribution of this software, in source or object code forms, with or .\" without modifications are expressly permitted by Whistle Communications; .\" provided, however, that: .\" 1. Any and all reproductions of the source or object code must include the .\" copyright notice above and the following disclaimer of warranties; and .\" 2. No rights are granted, in any manner or form, to use Whistle .\" Communications, Inc. trademarks, including the mark "WHISTLE .\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as .\" such appears in the above copyright notice or in the software. .\" .\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, .\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. .\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY .\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS .\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. .\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES .\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING .\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, .\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY .\" OF SUCH DAMAGE. .\" .\" Authors: Julian Elischer .\" Archie Cobbs .\" .\" $FreeBSD$ .\" $Whistle: netgraph.4,v 1.7 1999/01/28 23:54:52 julian Exp $ .\" .Dd January 19, 1999 .Dt NETGRAPH 4 .Os .Sh NAME .Nm netgraph .Nd graph based kernel networking subsystem .Sh DESCRIPTION The .Nm system provides a uniform and modular system for the implementation of kernel objects which perform various networking functions. The objects, known as .Em nodes , can be arranged into arbitrarily complicated graphs. Nodes have .Em hooks which are used to connect two nodes together, forming the edges in the graph. Nodes communicate along the edges to process data, implement protocols, etc. .Pp The aim of .Nm is to supplement rather than replace the existing kernel networking -infrastructure. It provides: +infrastructure. +It provides: .Pp .Bl -bullet -compact -offset 2n .It A flexible way of combining protocol and link level drivers .It A modular way to implement new protocols .It A common framework for kernel entities to inter-communicate .It A reasonably fast, kernel-based implementation .El -.Sh Nodes and Types +.Ss Nodes and Types The most fundamental concept in .Nm is that of a .Em node . All nodes implement a number of predefined methods which allow them to interact with other nodes in a well defined manner. .Pp Each node has a .Em type , which is a static property of the node determined at node creation time. A node's type is described by a unique .Tn ASCII type name. The type implies what the node does and how it may be connected to other nodes. .Pp In object-oriented language, types are classes and nodes are instances of their respective class. All node types are subclasses of the generic node type, and hence inherit certain common functionality and capabilities (e.g., the ability to have an .Tn ASCII name). .Pp Nodes may be assigned a globally unique .Tn ASCII name which can be used to refer to the node. The name must not contain the characters .Dq .\& or .Dq \&: and is limited to .Dv "NG_NODELEN + 1" characters (including NUL byte). .Pp Each node instance has a unique .Em ID number -which is expressed as a 32-bit hex value. This value may be used to -refer to a node when there is no +which is expressed as a 32-bit hex value. +This value may be used to refer to a node when there is no .Tn ASCII name assigned to it. -.Sh Hooks +.Ss Hooks Nodes are connected to other nodes by connecting a pair of .Em hooks , one from each node. Data flows bidirectionally between nodes along -connected pairs of hooks. A node may have as many hooks as it +connected pairs of hooks. +A node may have as many hooks as it needs, and may assign whatever meaning it wants to a hook. .Pp Hooks have these properties: .Pp .Bl -bullet -compact -offset 2n .It A hook has an .Tn ASCII name which is unique among all hooks on that node (other hooks on other nodes may have the same name). The name must not contain a .Dq .\& or a .Dq \&: and is limited to .Dv "NG_HOOKLEN + 1" characters (including NUL byte). .It -A hook is always connected to another hook. That is, hooks are +A hook is always connected to another hook. +That is, hooks are created at the time they are connected, and breaking an edge by removing either hook destroys both hooks. .It A hook can be set into a state where incoming packets are always queued -by the input queueing system, rather than being delivered directly. This -is used when the two joined nodes need to be decoupled, e.g. if they are -running at different processor priority levels. (spl) +by the input queueing system, rather than being delivered directly. +This is used when the two joined nodes need to be decoupled, e.g. if they are +running at different processor priority levels. (spl) .It A hook may supply over-riding receive data and receive message functions which should be used for data and messages received through that hook in preference to the general node-wide methods. .El .Pp A node may decide to assign special meaning to some hooks. For example, connecting to the hook named .Dq debug might trigger the node to start sending debugging information to that hook. -.Sh Data Flow +.Ss Data Flow Two types of information flow between nodes: data messages and -control messages. Data messages are passed in mbuf chains along the edges -in the graph, one edge at a time. The first mbuf in a chain must have the +control messages. +Data messages are passed in mbuf chains along the edges +in the graph, one edge at a time. +The first mbuf in a chain must have the .Dv M_PKTHDR flag set. Each node decides how to handle data coming in on its hooks. .Pp Control messages are type-specific C structures sent from one node -directly to some arbitrary other node. Control messages have a common +directly to some arbitrary other node. +Control messages have a common header format, followed by type-specific data, and are binary structures -for efficiency. However, node types also may support conversion of the +for efficiency. +However, node types also may support conversion of the type specific data between binary and .Tn ASCII for debugging and human interface purposes (see the .Dv NGM_ASCII2BINARY and .Dv NGM_BINARY2ASCII -generic control messages below). Nodes are not required to support -these conversions. +generic control messages below). +Nodes are not required to support these conversions. .Pp -There are three ways to address a control message. If -there is a sequence of edges connecting the two nodes, the message +There are three ways to address a control message. +If there is a sequence of edges connecting the two nodes, the message may be .Dq source routed by specifying the corresponding sequence of .Tn ASCII hook names as the destination address for the message (relative -addressing). If the destination is adjacent to the source, then the source +addressing). +If the destination is adjacent to the source, then the source node may simply specify (as a pointer in the code) the hook across which the -message should be sent. Otherwise, the recipient node global +message should be sent. +Otherwise, the recipient node global .Tn ASCII name (or equivalent ID based name) is used as the destination address -for the message (absolute addressing). The two types of +for the message (absolute addressing). +The two types of .Tn ASCII addressing may be combined, by specifying an absolute start node and a sequence of hooks. Only the .Tn ASCII addressing modes are available to control programs outside the kernel, as use of direct pointers is limited of course to kernel modules. .Pp Messages often represent commands that are followed by a reply message -in the reverse direction. To facilitate this, the recipient of a +in the reverse direction. +To facilitate this, the recipient of a control message is supplied with a .Dq return address that is suitable for addressing a reply. .Pp Each control message contains a 32 bit value called a .Em typecookie indicating the type of the message, i.e., how to interpret it. Typically each type defines a unique typecookie for the messages -that it understands. However, a node may choose to recognize and +that it understands. +However, a node may choose to recognize and implement more than one type of message. .Pp If a message is delivered to an address that implies that it arrived at that node through a particular hook, (as opposed to having been directly addressed using its ID or global name), then that hook is identified to the -receiving node. This allows a message to be rerouted or passed on, should +receiving node. +This allows a message to be rerouted or passed on, should a node decide that this is required, in much the same way that data packets are passed around between nodes. A set of standard messages for flow control and link management purposes are defined by the base system that are usually -passed around in this manner. Flow control message would usually travel +passed around in this manner. +Flow control message would usually travel in the opposite direction to the data to which they pertain. -.Sh Netgraph is (usually) Functional +.Ss Netgraph is (usually) Functional In order to minimize latency, most .Nm operations are functional. That is, data and control messages are delivered by making function -calls rather than by using queues and mailboxes. For example, if node +calls rather than by using queues and mailboxes. +For example, if node A wishes to send a data mbuf to neighboring node B, it calls the generic .Nm -data delivery function. This function in turn locates +data delivery function. +This function in turn locates node B and calls B's .Dq receive data -method. There are exceptions to this. +method. +There are exceptions to this. .Pp Each node has an input queue, and some operations can be considered to -be 'writers' in that they alter the state of the node. Obviously in an SMP +be 'writers' in that they alter the state of the node. +Obviously in an SMP world it would be bad if the state of a node were changed while another -data packet were transiting the node. For this purpose, the input queue -implements a +data packet were transiting the node. +For this purpose, the input queue implements a .Em reader/writer semantic so that when there is a writer in the node, all other requests are queued, and while there are readers, a writer, and any following -packets are queued. In the case where there is no reason to queue the +packets are queued. +In the case where there is no reason to queue the data, the input method is called directly, as mentioned above. .Pp A node may declare that all requests should be considered as writers, or that requests coming in over a particular hook should be considered to be a writer, or even that packets leaving or entering across a particular hook should always be queued, rather than delivered directly (often useful for interrupt routines who want to get back to the hardware quickly). By default, all control message packets are considered to be writers unless specifically declared to be a reader in their definition. (see -NGM_READONLY in ng_message.h) +NGM_READONLY in +.Pa ng_message.h ) .Pp While this mode of operation results in good performance, it has a few implications for node developers: .Pp .Bl -bullet -compact -offset 2n .It Whenever a node delivers a data or control message, the node may need to allow for the possibility of receiving a returning message before the original delivery function call returns. .It Netgraph nodes and support routines generally run at .Fn splnet . However, some nodes may want to send data and control messages -from a different priority level. Netgraph supplies a mechanism which +from a different priority level. +Netgraph supplies a mechanism which utilizes the NETISR system to move message and data delivery to .Fn splnet . Nodes that run at other priorities (e.g. interfaces) can be directly linked to other nodes so that the combination runs at the other priority, however any interaction with nodes running at splnet MUST be achieved via the queueing functions, (which use the .Fn netisr feature of the kernel). Note that messages are always received at .Fn splnet . .It It's possible for an infinite loop to occur if the graph contains cycles. .El .Pp So far, these issues have not proven problematical in practice. -.Sh Interaction With Other Parts of the Kernel +.Ss Interaction With Other Parts of the Kernel A node may have a hidden interaction with other components of the kernel outside of the .Nm subsystem, such as device hardware, kernel protocol stacks, etc. In fact, one of the benefits of .Nm is the ability to join disparate kernel networking entities together in a consistent communication framework. .Pp An example is the node type .Em socket which is both a netgraph node and a .Xr socket 2 .Bx socket in the protocol family .Dv PF_NETGRAPH . Socket nodes allow user processes to participate in .Nm . Other nodes communicate with socket nodes using the usual methods, and the node hides the fact that it is also passing information to and from a cooperating user process. .Pp Another example is a device driver that presents a node interface to the hardware. -.Sh Node Methods +.Ss Node Methods Nodes are notified of the following actions via function calls to the following node methods (all at .Fn splnet ) and may accept or reject that action (by returning the appropriate error code): .Bl -tag -width xxx .It Creation of a new node The constructor for the type is called. If creation of a new node is allowed, the constructor must call the generic node creation function (in object-oriented terms, the superclass constructor) and then allocate any special resources it needs. For nodes that correspond to hardware, this is typically done during the device attach routine. Often a global .Tn ASCII name corresponding to the device name is assigned here as well. .It Creation of a new hook The hook is created and tentatively linked to the node, and the node is told about the name that will be used to describe this hook. The node sets up any special data structures it needs, or may reject the connection, based on the name of the hook. .It Successful connection of two hooks After both ends have accepted their hooks, and the links have been made, the nodes get a chance to find out who their peer is across the link and can then decide to reject the connection. Tear-down is automatic. This is also the time at which a node may decide whether to set a particular hook (or its peer) into .Em queueing mode. .It Destruction of a hook The node is notified of a broken connection. The node may consider some hooks to be critical to operation and others to be expendable: the disconnection of one hook may be an acceptable event while for another it may affect a total shutdown for the node. .It Shutdown of a node This method allows a node to clean up and to ensure that any actions that need to be performed at this time are taken. The method is called by the generic (i.e., superclass) node destructor which will get rid of the generic components of the node. Some nodes (usually associated with a piece of hardware) may be .Em persistent in that a shutdown breaks all edges and resets the node, but doesn't remove it. In this case the shutdown method should not free its resources, but rather, clean up and then clear the .Em NG_INVALID flag to signal the generic code that the shutdown is aborted. In the case where the shutdown is started by the node itself due to hardware removal or unloading, (via ng_rmnode_self()) it should set the .Em NG_REALLY_DIE flag to signal to its own shutdown method that it is not to persist. .El -.Sh Sending and Receiving Data +.Ss Sending and Receiving Data Two other methods are also supported by all nodes: .Bl -tag -width xxx .It Receive data message A .Em Netgraph queueable request item , usually referred to as an .Em item , is received by the function. The item contains a pointer to an mbuf and metadata about the packet. .Pp The node is notified on which hook the item arrived, and can use this information in its processing decision. The receiving node must always .Fn NG_FREE_M the mbuf chain on completion or error, or pass it on to another node (or kernel module) which will then be responsible for freeing it. Similarly the .Em item must be freed if it is not to be passed on to another node, by using the .Fn NG_FREE_ITEM macro. If the item still holds references to mbufs or metadata at the time of freeing then they will also be appropriately freed. Therefore, if there is any chance that the mbuf or metadata will be changed or freed separately from the item, it is very important that these fields be retrieved using the .Fn NGI_GET_M and .Fn NGI_GET_META macros that also remove the reference within the item. (or multiple frees of the same object will occur). .Pp If it is only required to examine the contents of the mbufs or the metadata, then it is possible to use the .Fn NGI_M and .Fn NGI_META macros to both read and rewrite these fields. .Pp In addition to the mbuf chain itself there may also be a pointer to a structure describing meta-data about the message (e.g. priority information). This pointer may be .Dv NULL if there is no additional information. The format for this information is described in .Pa sys/netgraph/netgraph.h . The memory for meta-data must allocated via .Fn malloc with type .Dv M_NETGRAPH_META . As with the data itself, it is the receiver's responsibility to .Fn free the meta-data. If the mbuf chain is freed the meta-data must be freed at the same time. If the meta-data is freed but the real data on is passed on, then a .Dv NULL pointer must be substituted. It is also the duty of the receiver to free the request item itself, or to use it to pass the message on further. .Pp The receiving node may decide to defer the data by queueing it in the .Nm NETISR system (see below). It achieves this by setting the .Dv HK_QUEUE flag in the flags word of the hook on which that data will arrive. The infrastructure will respect that bit and queue the data for delivery at a later time, rather than deliver it directly. A node may decide to set the bit on the .Em peer node, so that its own output packets are queued. This is used by device drivers running at different processor priorities to transfer packet delivery to the splnet() level at which the bulk of .Nm runs. .Pp The structure and use of meta-data is still experimental, but is presently used in frame-relay to indicate that management packets should be queued for transmission at a higher priority than data packets. This is required for conformance with Frame Relay standards. .Pp The node may elect to nominate a different receive data function for data received on a particular hook, to simplify coding. It uses the .Fn NG_HOOK_SET_RCVDATA hook fn macro to do this. The function receives the same arguments in every way other than it will receive all (and only) packets from that hook. .It Receive control message This method is called when a control message is addressed to the node. As with the received data, an .Em item is received, with a pointer to the control message. The message can be examined using the .Fn NGI_MSG macro, or completely extracted from the item using the .Fn NGI_GET_MSG which also removes the reference within the item. If the Item still holds a reference to the message when it is freed (using the .Fn NG_FREE_ITEM macro), then the message will also be freed appropriately. If the reference has been removed the node must free the message itself using the .Fn NG_FREE_MSG macro. A return address is always supplied, giving the address of the node that originated the message so a reply message can be sent anytime later. The return address is retrieved from the .Em item using the .Fn NGI_RETADDR macro and is of type .Em ng_ID_t . All control messages and replies are allocated with .Fn malloc type .Dv M_NETGRAPH_MSG , however it is more usual to use the .Fn NG_MKMESSAGE and .Fn NG_MKRESPONSE macros to allocate and fill out a message. Messages must be freed using the .Fn NG_FREE_MSG macro. .Pp If the message was delivered via a specific hook, that hook will also be made known, which allows the use of such things as flow-control messages, and status change messages, where the node may want to forward the message out another hook to that on which it arrived. .Pp The node may elect to nominate a different receive message function for messages received on a particular hook, to simplify coding. It uses the .Fn NG_HOOK_SET_RCVMSG hook fn macro to do this. The function receives the same arguments in every way other than it will receive all (and only) messages from that hook. .El .Pp Much use has been made of reference counts, so that nodes being free'd of all references are automatically freed, and this behaviour has been tested and debugged to present a consistent and trustworthy framework for the .Dq type module writer to use. -.Sh Addressing +.Ss Addressing The .Nm framework provides an unambiguous and simple to use method of specifically addressing any single node in the graph. The naming of a node is independent of its type, in that another node, or external component need not know anything about the node's type in order to address it so as to send it a generic message type. Node and hook names should be chosen so as to make addresses meaningful. .Pp Addresses are either absolute or relative. An absolute address begins with a node name, (or ID), followed by a colon, followed by a sequence of hook names separated by periods. This addresses the node reached by starting at the named node and following the specified sequence of hooks. A relative address includes only the sequence of hook names, implicitly starting hook traversal at the local node. .Pp There are a couple of special possibilities for the node name. The name .Dq .\& (referred to as .Dq \&.: ) always refers to the local node. Also, nodes that have no global name may be addressed by their ID numbers, by enclosing the hex representation of the ID number within square brackets. Here are some examples of valid netgraph addresses: .Bd -literal -offset 4n -compact .: [3f]: foo: .:hook1 foo:hook1.hook2 [d80]:hook1 .Ed .Pp Consider the following set of nodes might be created for a site with a single physical frame relay line having two active logical DLCI channels, with RFC-1490 frames on DLCI 16 and PPP frames over DLCI 20: .Pp .Bd -literal [type SYNC ] [type FRAME] [type RFC1490] [ "Frame1" ](uplink)<-->(data)[](dlci16)<-->(mux)[ ] [ A ] [ B ](dlci20)<---+ [ C ] | | [ type PPP ] +>(mux)[] [ D ] .Ed .Pp One could always send a control message to node C from anywhere by using the name .Em "Frame1:uplink.dlci16" . In this case, node C would also be notified that the message reached it via its hook .Dq mux . Similarly, .Em "Frame1:uplink.dlci20" could reliably be used to reach node D, and node A could refer to node B as .Em ".:uplink" , or simply .Em "uplink" . Conversely, B can refer to A as .Em "data" . The address .Em "mux.data" could be used by both nodes C and D to address a message to node A. .Pp Note that this is only for .Em control messages . In each of these cases, where a relative addressing mode is used, the recipient is notified of the hook on which the message arrived, as well as the originating node. This allows the option of hop-by-hop distribution of messages and state information. Data messages are .Em only routed one hop at a time, by specifying the departing hook, with each node making the next routing decision. So when B receives a frame on hook .Dq data it decodes the frame relay header to determine the DLCI, and then forwards the unwrapped frame to either C or D. .Pp In a similar way, flow control messages may be routed in the reverse direction to outgoing data. For example a "buffer nearly full" message from .Em "Frame1: would be passed to node .Em B which might decide to send similar messages to both nodes .Em C and .Em D . The nodes would use .Em "Direct hook pointer" addressing to route the messages. The message may have travelled from .Em "Frame1: to .Em B as a synchronous reply, saving time and cycles. .Pp A similar graph might be used to represent multi-link PPP running over an ISDN line: .Pp .Bd -literal [ type BRI ](B1)<--->(link1)[ type MPP ] [ "ISDN1" ](B2)<--->(link2)[ (no name) ] [ ](D) <-+ | +----------------+ | +->(switch)[ type Q.921 ](term1)<---->(datalink)[ type Q.931 ] [ (no name) ] [ (no name) ] .Ed -.Sh Netgraph Structures +.Ss Netgraph Structures Structures are defined in .Pa sys/netgraph/netgraph.h (for kernel structures only of interest to nodes) and .Pa sys/netgraph/ng_message.h (for message definitions also of interest to user programs). .Pp The two basic object types that are of interest to node authors are .Em nodes and .Em hooks . These two objects have the following properties that are also of interest to the node writers. .Bl -tag -width xxx .It struct ng_node Node authors should always use the following typedef to declare their pointers, and should never actually declare the structure. .Pp typedef struct ng_node *node_p; .Pp The following properties are associated with a node, and can be accessed in the following manner: .Bl -bullet -compact -offset 2n .Pp .It Validity .Pp A driver or interrupt routine may want to check whether the node is still valid. It is assumed that the caller holds a reference on the node so it will not have been freed, however it may have been disabled or otherwise shut down. Using the .Fn NG_NODE_IS_VALID "node" macro will return this state. Eventually it should be almost impossible for code to run in an invalid node but at this time that work has not been completed. .Pp .It node ID .Pp Of type .Em ng_ID_t , This property can be retrieved using the macro .Fn NG_NODE_ID "node" . .Pp .It node name .Pp Optional globally unique name, null terminated string. If there is a value in here, it is the name of the node. .Pp if .Fn ( NG_NODE_NAME "node" [0]) .... .Pp if (strncmp( .Fn NG_NODE_NAME "node" , "fred", NG_NODELEN)) ... .Pp .It A node dependent opaque cookie .Pp You may place anything of type .Em pointer here. Use the macros .Fn NG_NODE_SET_PRIVATE node value and .Fn NG_NODE_PRIVATE "node" to set and retrieve this property. .Pp .It number of hooks .Pp Use .Fn NG_NODE_NUMHOOKS "node" to retrieve this value. .Pp .It hooks .Pp The node may have a number of hooks. A traversal method is provided to allow all the hooks to be tested for some condition. .Fn NG_NODE_FOREACH_HOOK node fn arg rethook where fn is a function that will be called for each hook with the form .Fn fn hook arg and returning 0 to terminate the search. If the search is terminated, then .Em rethook will be set to the hook at which the search was terminated. .El .It struct ng_hook Node authors should always use the following typedef to declare their hook pointers. .Pp typedef struct ng_hook *hook_p; .Pp The following properties are associated with a hook, and can be accessed in the following manner: .Bl -bullet -compact -offset 2n .Pp .It A node dependent opaque cookie. .Pp You may place anything of type .Em pointer here. Use the macros .Fn NG_HOOK_SET_PRIVATE hook value and .Fn NG_HOOK_PRIVATE "hook" to set and retrieve this property. .Pp .It An associate node. .Pp You may use the macro .Fn NG_HOOK_NODE "hook" to find the associated node. .Pp .It A peer hook .Pp The other hook in this connected pair. Of type hook_p. You can use .Fn NG_HOOK_PEER "hook" to find the peer. .Pp .It references .Pp .Fn NG_HOOK_REF "hook" and .Fn NG_HOOK_UNREF "hook" increment and decrement the hook reference count accordingly. After decrement you should always assume the hook has been freed unless you have another reference still valid. .Pp .It Over-ride receive functions. .Pp The .Fn NG_HOOK_SET_RCVDATA hook fn and .Fn NG_HOOK_SET_RCVMSG hook fn macros can be used to set over-ride methods that will be used in preference to the generic receive data and receive message functions. To unset these use the macros to set them to NULL. They will only be used for data and messages received on the hook on which they are set. .El .Pp The maintenance of the names, reference counts, and linked list of hooks for each node is handled automatically by the .Nm subsystem. Typically a node's private info contains a back-pointer to the node or hook structure, which counts as a new reference that must be included in the reference count for the node. When the node constructor is called there is already a reference for this calculated in, so that when the node is destroyed, it should remember to do a .Fn NG_NODE_UNREF on the node. .Pp From a hook you can obtain the corresponding node, and from a node, it is possible to traverse all the active hooks. .Pp A current example of how to define a node can always be seen in .Em sys/netgraph/ng_sample.c and should be used as a starting point for new node writers. .El -.Sh Netgraph Message Structure +.Ss Netgraph Message Structure Control messages have the following structure: .Bd -literal #define NG_CMDSTRLEN 15 /* Max command string (16 with null) */ struct ng_mesg { struct ng_msghdr { u_char version; /* Must equal NG_VERSION */ u_char spare; /* Pad to 2 bytes */ u_short arglen; /* Length of cmd/resp data */ u_long flags; /* Message status flags */ u_long token; /* Reply should have the same token */ u_long typecookie; /* Node type understanding this message */ u_long cmd; /* Command identifier */ u_char cmdstr[NG_CMDSTRLEN+1]; /* Cmd string (for debug) */ } header; char data[0]; /* Start of cmd/resp data */ }; #define NG_ABI_VERSION 5 /* Netgraph kernel ABI version */ #define NG_VERSION 4 /* Netgraph message version */ #define NGF_ORIG 0x0000 /* Command */ #define NGF_RESP 0x0001 /* Response */ .Ed .Pp Control messages have the fixed header shown above, followed by a variable length data section which depends on the type cookie and the command. Each field is explained below: .Bl -tag -width xxx .It Dv version Indicates the version of the netgraph message protocol itself. The current version is .Dv NG_VERSION . .It Dv arglen This is the length of any extra arguments, which begin at .Dv data . .It Dv flags Indicates whether this is a command or a response control message. .It Dv token The .Dv token is a means by which a sender can match a reply message to the corresponding command message; the reply always has the same token. .Pp .It Dv typecookie The corresponding node type's unique 32-bit value. If a node doesn't recognize the type cookie it must reject the message by returning .Er EINVAL . .Pp Each type should have an include file that defines the commands, argument format, and cookie for its own messages. The typecookie insures that the same header file was included by both sender and receiver; when an incompatible change in the header file is made, the typecookie .Em must be changed. The de facto method for generating unique type cookies is to take the seconds from the epoch at the time the header file is written (i.e., the output of .Dv "date -u +'%s'" ) . .Pp There is a predefined typecookie .Dv NGM_GENERIC_COOKIE for the .Dq generic node type, and a corresponding set of generic messages which all nodes understand. The handling of these messages is automatic. .It Dv command The identifier for the message command. This is type specific, and is defined in the same header file as the typecookie. .It Dv cmdstr Room for a short human readable version of .Dq command (for debugging purposes only). .El .Pp Some modules may choose to implement messages from more than one of the header files and thus recognize more than one type cookie. -.Sh Control Message ASCII Form +.Ss Control Message ASCII Form Control messages are in binary format for efficiency. However, for debugging and human interface purposes, and if the node type supports it, control messages may be converted to and from an equivalent .Tn ASCII form. The .Tn ASCII form is similar to the binary form, with two exceptions: .Pp .Bl -tag -compact -width xxx .It o The .Dv cmdstr header field must contain the .Tn ASCII name of the command, corresponding to the .Dv cmd header field. .It o The .Dv args field contains a NUL-terminated .Tn ASCII string version of the message arguments. .El .Pp In general, the arguments field of a control message can be any arbitrary C data type. Netgraph includes parsing routines to support some pre-defined datatypes in .Tn ASCII with this simple syntax: .Pp .Bl -tag -compact -width xxx .It o Integer types are represented by base 8, 10, or 16 numbers. .It o Strings are enclosed in double quotes and respect the normal C language backslash escapes. .It o IP addresses have the obvious form. .It o Arrays are enclosed in square brackets, with the elements listed consecutively starting at index zero. An element may have an optional index and equals sign preceding it. Whenever an element does not have an explicit index, the index is implicitly the previous element's index plus one. .It o Structures are enclosed in curly braces, and each field is specified in the form .Dq fieldname=value . .It o Any array element or structure field whose value is equal to its .Dq default value may be omitted. For integer types, the default value is usually zero; for string types, the empty string. .It o Array elements and structure fields may be specified in any order. .El .Pp Each node type may define its own arbitrary types by providing the necessary routines to parse and unparse. .Tn ASCII forms defined for a specific node type are documented in the documentation for that node type. -.Sh Generic Control Messages +.Ss Generic Control Messages There are a number of standard predefined messages that will work for any node, as they are supported directly by the framework itself. These are defined in .Pa ng_message.h along with the basic layout of messages and other similar information. .Bl -tag -width xxx .It Dv NGM_CONNECT Connect to another node, using the supplied hook names on either end. .It Dv NGM_MKPEER Construct a node of the given type and then connect to it using the supplied hook names. .It Dv NGM_SHUTDOWN The target node should disconnect from all its neighbours and shut down. Persistent nodes such as those representing physical hardware might not disappear from the node namespace, but only reset themselves. The node must disconnect all of its hooks. This may result in neighbors shutting themselves down, and possibly a cascading shutdown of the entire connected graph. .It Dv NGM_NAME Assign a name to a node. Nodes can exist without having a name, and this is the default for nodes created using the .Dv NGM_MKPEER method. Such nodes can only be addressed relatively or by their ID number. .It Dv NGM_RMHOOK Ask the node to break a hook connection to one of its neighbours. Both nodes will have their .Dq disconnect method invoked. Either node may elect to totally shut down as a result. .It Dv NGM_NODEINFO Asks the target node to describe itself. The four returned fields are the node name (if named), the node type, the node ID and the number of hooks attached. The ID is an internal number unique to that node. .It Dv NGM_LISTHOOKS This returns the information given by .Dv NGM_NODEINFO , but in addition includes an array of fields describing each link, and the description for the node at the far end of that link. .It Dv NGM_LISTNAMES This returns an array of node descriptions (as for .Dv NGM_NODEINFO ")" where each entry of the array describes a named node. All named nodes will be described. .It Dv NGM_LISTNODES This is the same as .Dv NGM_LISTNAMES except that all nodes are listed regardless of whether they have a name or not. .It Dv NGM_LISTTYPES This returns a list of all currently installed netgraph types. .It Dv NGM_TEXT_STATUS The node may return a text formatted status message. The status information is determined entirely by the node type. It is the only "generic" message that requires any support within the node itself and as such the node may elect to not support this message. The text response must be less than .Dv NG_TEXTRESPONSE bytes in length (presently 1024). This can be used to return general status information in human readable form. .It Dv NGM_BINARY2ASCII This message converts a binary control message to its .Tn ASCII form. The entire control message to be converted is contained within the arguments field of the .Dv NGM_BINARY2ASCII message itself. If successful, the reply will contain the same control message in .Tn ASCII form. A node will typically only know how to translate messages that it itself understands, so the target node of the .Dv NGM_BINARY2ASCII is often the same node that would actually receive that message. .It Dv NGM_ASCII2BINARY The opposite of .Dv NGM_BINARY2ASCII . The entire control message to be converted, in .Tn ASCII form, is contained in the arguments section of the .Dv NGM_ASCII2BINARY and need only have the .Dv flags , .Dv cmdstr , and .Dv arglen header fields filled in, plus the NUL-terminated string version of the arguments in the arguments field. If successful, the reply contains the binary version of the control message. .El -.Sh Flow Control Messages +.Ss Flow Control Messages In addition to the control messages that affect nodes with respect to the graph, there are also a number of .Em Flow-control messages defined. At present these are .Em NOT handled automatically by the system, so nodes need to handle them if they are going to be used in a graph utilising -flow control, and will be in the likely path of these messages. The -default action of a node that doesn't understand these messages should -be to pass them onto the next node. Hopefully some helper functions -will assist in this eventually. These messages are also defined in +flow control, and will be in the likely path of these messages. +The default action of a node that doesn't understand these messages should +be to pass them onto the next node. +Hopefully some helper functions will assist in this eventually. +These messages are also defined in .Pa sys/netgraph/ng_message.h and have a separate cookie .Em NG_FLOW_COOKIE -to help identify them. They will not be covered in depth here. -.Sh Metadata +to help identify them. +They will not be covered in depth here. +.Ss Metadata Data moving through the .Nm system can be accompanied by meta-data that describes some -aspect of that data. The form of the meta-data is a fixed header, +aspect of that data. +The form of the meta-data is a fixed header, which contains enough information for most uses, and can optionally be supplemented by trailing .Em option structures, which contain a .Em cookie (see the section on control messages), an identifier, a length and optional data. If a node does not recognize the cookie associated with an option, it should ignore that option. .Pp Meta data might include such things as priority, discard eligibility, -or special processing requirements. It might also mark a packet for -debug status, etc. The use of meta-data is still experimental. +or special processing requirements. +It might also mark a packet for +debug status, etc. +The use of meta-data is still experimental. .Sh INITIALIZATION The base .Nm code may either be statically compiled into the kernel or else loaded dynamically as a KLD via .Xr kldload 8 . In the former case, include .Pp .Dl options NETGRAPH .Pp -in your kernel configuration file. You may also include selected +in your kernel configuration file. +You may also include selected node types in the kernel compilation, for example: .Bd -literal -offset indent options NETGRAPH options NETGRAPH_SOCKET options NETGRAPH_ECHO .Ed .Pp Once the .Nm subsystem is loaded, individual node types may be loaded at any time as KLD modules via .Xr kldload 8 . Moreover, .Nm knows how to automatically do this; when a request to create a new node of unknown type .Em type is made, .Nm will attempt to load the KLD module .Pa ng_type.ko . .Pp Types can also be installed at boot time, as certain device drivers may want to export each instance of the device as a netgraph node. .Pp In general, new types can be installed at any time from within the kernel by calling .Fn ng_newtype , supplying a pointer to the type's .Dv struct ng_type structure. .Pp The .Fn NETGRAPH_INIT macro automates this process by using a linker set. .Sh EXISTING NODE TYPES -Several node types currently exist. Each is fully documented -in its own man page: +Several node types currently exist. +Each is fully documented in its own man page: .Bl -tag -width xxx .It SOCKET The socket type implements two new sockets in the new protocol domain .Dv PF_NETGRAPH . The new sockets protocols are .Dv NG_DATA and .Dv NG_CONTROL , both of type .Dv SOCK_DGRAM . Typically one of each is associated with a socket node. -When both sockets have closed, the node will shut down. The +When both sockets have closed, the node will shut down. +The .Dv NG_DATA socket is used for sending and receiving data, while the .Dv NG_CONTROL socket is used for sending and receiving control messages. Data and control messages are passed using the .Xr sendto 2 and .Xr recvfrom 2 calls, using a .Dv struct sockaddr_ng socket address. .Pp .It HOLE Responds only to generic messages and is a .Dq black hole for data, Useful for testing. Always accepts new hooks. .Pp .It ECHO Responds only to generic messages and always echoes data back through the hook from which it arrived. Returns any non generic messages as their own response. Useful for testing. Always accepts new hooks. .Pp .It TEE This node is useful for .Dq snooping . It has 4 hooks: .Dv left , .Dv right , .Dv left2right , and .Dv right2left . Data entering from the right is passed to the left and duplicated on .Dv right2left , and data entering from the left is passed to the right and duplicated on .Dv left2right . Data entering from .Dv left2right is sent to the right and data from .Dv right2left to left. .Pp .It RFC1490 MUX Encapsulates/de-encapsulates frames encoded according to RFC 1490. Has a hook for the encapsulated packets .Pq Dq downstream and one hook for each protocol (i.e., IP, PPP, etc.). .Pp .It FRAME RELAY MUX Encapsulates/de-encapsulates Frame Relay frames. Has a hook for the encapsulated packets .Pq Dq downstream and one hook for each DLCI. .Pp .It FRAME RELAY LMI Automatically handles frame relay .Dq LMI (link management interface) operations and packets. Automatically probes and detects which of several LMI standards is in use at the exchange. .Pp .It TTY This node is also a line discipline. It simply converts between mbuf frames and sequential serial data, allowing a tty to appear as a netgraph node. It has a programmable .Dq hotkey character. .Pp .It ASYNC This node encapsulates and de-encapsulates asynchronous frames according to RFC 1662. This is used in conjunction with the TTY node type for supporting PPP links over asynchronous serial lines. .Pp .It INTERFACE This node is also a system networking interface. It has hooks representing each protocol family (IP, AppleTalk, IPX, etc.) and appears in the output of .Xr ifconfig 8 . The interfaces are named .Em ng0 , .Em ng1 , etc. .It ONE2MANY This node implements a simple round-robin multiplexer. It can be used for example to make several LAN ports act together to get a higher speed link between two machines. .It Various PPP related nodes. There is a full multilink PPP implementation that runs in Netgraph. The .Em Mpd port can use these modules to make a very low latency high capacity ppp system. It also supports .Em PPTP vpns using the .Em PPTP node. .It PPPOE A server and client side implementation of PPPoE. Used in conjunction with either .Xr ppp 8 or the .Em mpd port . .It BRIDGE This node, together with the ethernet nodes allows a very flexible bridging system to be implemented. .It KSOCKET This intriguing node looks like a socket to the system but diverts all data to and from the netgraph system for further processing. This allows such things as UDP tunnels to be almost trivially implemented from the command line. .El .Pp Refer to the section at the end of this man page for more nodes types. .Sh NOTES Whether a named node exists can be checked by trying to send a control message to it (e.g., .Dv NGM_NODEINFO ) . If it does not exist, .Er ENOENT will be returned. .Pp All data messages are mbuf chains with the M_PKTHDR flag set. .Pp Nodes are responsible for freeing what they allocate. There are three exceptions: .Bl -tag -width xxxx .It 1 Mbufs sent across a data link are never to be freed by the sender. In the case of error, they should be considered freed. .It 2 Any meta-data information traveling with the data has the same restriction. It might be freed by any node the data passes through, and a .Dv NULL passed onwards, but the caller will never free it. Two macros .Fn NG_FREE_META "meta" and .Fn NG_FREE_M "m" should be used if possible to free data and meta data (see .Pa netgraph.h ) . .It 3 Messages sent using .Fn ng_send_message are freed by the recipient. As in the case above, the addresses associated with the message are freed by whatever allocated them so the recipient should copy them if it wants to keep that information. .It 4 Both control messages and data are delivered and queued with a netgraph .Em item . The item must be freed using .Fn NG_FREE_ITEM "item" or passed on to another node. .El .Sh FILES .Bl -tag -width xxxxx -compact .It Pa /sys/netgraph/netgraph.h Definitions for use solely within the kernel by .Nm nodes. .It Pa /sys/netgraph/ng_message.h Definitions needed by any file that needs to deal with .Nm messages. .It Pa /sys/netgraph/ng_socket.h Definitions needed to use .Nm socket type nodes. .It Pa /sys/netgraph/ng_{type}.h Definitions needed to use .Nm {type} nodes, including the type cookie definition. .It Pa /boot/kernel/netgraph.ko Netgraph subsystem loadable KLD module. .It Pa /boot/kernel/ng_{type}.ko Loadable KLD module for node type {type}. .It Pa /sys/netgraph/ng_sample.c Skeleton netgraph node. Use this as a starting point for new node types. .El .Sh USER MODE SUPPORT There is a library for supporting user-mode programs that wish to interact with the netgraph system. See .Xr netgraph 3 for details. .Pp Two user-mode support programs, .Xr ngctl 8 and .Xr nghook 8 , are available to assist manual configuration and debugging. .Pp There are a few useful techniques for debugging new node types. First, implementing new node types in user-mode first makes debugging easier. The .Em tee node type is also useful for debugging, especially in conjunction with .Xr ngctl 8 and .Xr nghook 8 . .Pp Also look in /usr/share/examples/netgraph for solutions to several common networking problems, solved using .Nm . .Sh SEE ALSO .Xr socket 2 , .Xr netgraph 3 , .Xr ng_async 4 , .Xr ng_bpf 4 , .Xr ng_bridge 4 , .Xr ng_cisco 4 , .Xr ng_echo 4 , .Xr ng_ether 4 , .Xr ng_frame_relay 4 , .Xr ng_hole 4 , .Xr ng_iface 4 , .Xr ng_ksocket 4 , .Xr ng_lmi 4 , .Xr ng_mppc 4 , .Xr ng_ppp 4 , .Xr ng_pppoe 4 , .Xr ng_pptpgre 4 , .Xr ng_rfc1490 4 , .Xr ng_socket 4 , .Xr ng_tee 4 , .Xr ng_tty 4 , .Xr ng_UI 4 , .Xr ng_vjc 4 , .Xr ngctl 8 , .Xr nghook 8 .Sh HISTORY The .Nm system was designed and first implemented at Whistle Communications, Inc.\& in a version of .Fx 2.2 customized for the Whistle InterJet. It first made its debut in the main tree in .Fx 3.4 . .Sh AUTHORS .An -nosplit .An Julian Elischer Aq julian@FreeBSD.org , with contributions by .An Archie Cobbs Aq archie@FreeBSD.org . Index: head/share/man/man4/netintro.4 =================================================================== --- head/share/man/man4/netintro.4 (revision 117010) +++ head/share/man/man4/netintro.4 (revision 117011) @@ -1,374 +1,389 @@ .\" Copyright (c) 1983, 1990, 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. .\" .\" @(#)netintro.4 8.2 (Berkeley) 11/30/93 .\" $FreeBSD$ .\" .Dd November 30, 1993 .Dt NETINTRO 4 .Os .Sh NAME .Nm networking .Nd introduction to networking facilities .Sh SYNOPSIS .In sys/types.h .In sys/time.h .In sys/socket.h .In net/if.h .In net/route.h .Sh DESCRIPTION This section is a general introduction to the networking facilities available in the system. Documentation in this part of section 4 is broken up into three areas: .Em protocol families (domains), .Em protocols , and .Em network interfaces . .Pp All network protocols are associated with a specific .Em protocol family . A protocol family provides basic services to the protocol implementation to allow it to function within a specific -network environment. These services may include +network environment. +These services may include packet fragmentation and reassembly, routing, addressing, and -basic transport. A protocol family may support multiple +basic transport. +A protocol family may support multiple methods of addressing, though the current protocol implementations -do not. A protocol family is normally comprised of a number -of protocols, one per +do not. +A protocol family is normally comprised of a number of protocols, one per .Xr socket 2 -type. It is not required that a protocol family support -all socket types. A protocol family may contain multiple +type. +It is not required that a protocol family support all socket types. +A protocol family may contain multiple protocols supporting the same socket abstraction. .Pp A protocol supports one of the socket abstractions detailed in .Xr socket 2 . A specific protocol may be accessed either by creating a socket of the appropriate type and protocol family, or by requesting the protocol explicitly when creating a socket. Protocols normally accept only one type of address format, usually determined by the addressing structure inherent in the design of the protocol family/network architecture. Certain semantics of the basic socket abstractions are -protocol specific. All protocols are expected to support +protocol specific. +All protocols are expected to support the basic model for their particular socket type, but may, in addition, provide non-standard facilities or extensions -to a mechanism. For example, a protocol supporting the +to a mechanism. +For example, a protocol supporting the .Dv SOCK_STREAM abstraction may allow more than one byte of out-of-band data to be transmitted per out-of-band message. .Pp A network interface is similar to a device interface. Network interfaces comprise the lowest layer of the networking subsystem, interacting with the actual transport -hardware. An interface may support one or more protocol -families and/or address formats. +hardware. +An interface may support one or more protocol families and/or address formats. The SYNOPSIS section of each network interface entry gives a sample specification of the related drivers for use in providing a system description to the .Xr config 8 program. The DIAGNOSTICS section lists messages which may appear on the console and/or in the system error log, .Pa /var/log/messages (see .Xr syslogd 8 ) , due to errors in device operation. .Sh PROTOCOLS The system currently supports the Internet protocols, the Xerox Network Systems(tm) protocols, and some of the .Tn ISO OSI protocols. Raw socket interfaces are provided to the .Tn IP protocol layer of the Internet, and to the .Tn IDP protocol of Xerox .Tn NS . Consult the appropriate manual pages in this section for more information regarding the support for each protocol family. .Sh ADDRESSING Associated with each protocol family is an address -format. All network addresses adhere to a general structure, +format. +All network addresses adhere to a general structure, called a sockaddr, described below. However, each protocol imposes finer and more specific structure, generally renaming the variant, which is discussed in the protocol family manual page alluded to above. .Bd -literal -offset indent struct sockaddr { u_char sa_len; u_char sa_family; char sa_data[14]; }; .Ed .Pp The field .Va sa_len contains the total length of the structure, which may exceed 16 bytes. The following address values for .Va sa_family are known to the system (and additional formats are defined for possible future implementation): .Bd -literal #define AF_UNIX 1 /* local to host (pipes, portals) */ #define AF_INET 2 /* internetwork: UDP, TCP, etc. */ #define AF_NS 6 /* Xerox NS protocols */ #define AF_CCITT 10 /* CCITT protocols, X.25 etc */ #define AF_HYLINK 15 /* NSC Hyperchannel */ #define AF_ISO 18 /* ISO protocols */ .Ed .Sh ROUTING .Fx provides some packet routing facilities. The kernel maintains a routing information database, which is used in selecting the appropriate network interface when transmitting packets. .Pp A user process (or possibly multiple co-operating processes) maintains this database by sending messages over a special kind of socket. This supplants fixed size .Xr ioctl 2 used in earlier releases. .Pp This facility is described in .Xr route 4 . .Sh INTERFACES Each network interface in a system corresponds to a -path through which messages may be sent and received. A network -interface usually has a hardware device associated with it, though +path through which messages may be sent and received. +A network interface usually has a hardware device associated with it, though certain interfaces such as the loopback interface, .Xr lo 4 , do not. .Pp The following .Xr ioctl 2 calls may be used to manipulate network interfaces. The .Fn ioctl is made on a socket (typically of type .Dv SOCK_DGRAM ) in the desired domain. Most of the requests supported in earlier releases take an .Vt ifreq -structure as its parameter. This structure has the form +structure as its parameter. +This structure has the form .Bd -literal struct ifreq { #define IFNAMSIZ 16 char ifr_name[IFNAMSIZ]; /* if name, e.g. "en0" */ union { struct sockaddr ifru_addr; struct sockaddr ifru_dstaddr; struct sockaddr ifru_broadaddr; short ifru_flags[2]; int ifru_metric; int ifru_mtu; int ifru_phys; caddr_t ifru_data; } ifr_ifru; #define ifr_addr ifr_ifru.ifru_addr /* address */ #define ifr_dstaddr ifr_ifru.ifru_dstaddr /* other end of p-to-p link */ #define ifr_broadaddr ifr_ifru.ifru_broadaddr /* broadcast address */ #define ifr_flags ifr_ifru.ifru_flags[0] /* flags (low 16 bits) */ #define ifr_flagshigh ifr_ifru.ifru_flags[1] /* flags (high 16 bits) */ #define ifr_metric ifr_ifru.ifru_metric /* metric */ #define ifr_mtu ifr_ifru.ifru_mtu /* mtu */ #define ifr_phys ifr_ifru.ifru_phys /* physical wire */ #define ifr_data ifr_ifru.ifru_data /* for use by interface */ }; .Ed .Pp Calls which are now deprecated are: .Bl -tag -width SIOCGIFBRDADDR .It Dv SIOCSIFADDR -Set interface address for protocol family. Following the address -assignment, the ``initialization'' routine for -the interface is called. +Set interface address for protocol family. +Following the address assignment, the +.Dq initialization +routine for the interface is called. .It Dv SIOCSIFDSTADDR Set point to point address for protocol family and interface. .It Dv SIOCSIFBRDADDR Set broadcast address for protocol family and interface. .El .Pp .Fn Ioctl requests to obtain addresses and requests both to set and retrieve other data are still fully supported and use the .Vt ifreq structure: .Bl -tag -width SIOCGIFBRDADDR .It Dv SIOCGIFADDR Get interface address for protocol family. .It Dv SIOCGIFDSTADDR Get point to point address for protocol family and interface. .It Dv SIOCGIFBRDADDR Get broadcast address for protocol family and interface. .It Dv SIOCSIFFLAGS -Set interface flags field. If the interface is marked down, +Set interface flags field. +If the interface is marked down, any processes currently routing packets through the interface are notified; some interfaces may be reset so that incoming packets are no longer received. When marked up again, the interface is reinitialized. .It Dv SIOCGIFFLAGS Get interface flags. .It Dv SIOCSIFMETRIC Set interface routing metric. The metric is used only by user-level routers. .It Dv SIOCGIFMETRIC Get interface metric. .It Dv SIOCIFCREATE Attempt to create the specified interface. If the interface name is given without a unit number the system will attempt to create a new interface with an arbitrary unit number. On successful return the .Va ifr_name field will contain the new interface name. .It Dv SIOCIFDESTROY Attempt to destroy the specified interface. .El .Pp There are two requests that make use of a new structure: .Bl -tag -width SIOCGIFBRDADDR .It Dv SIOCAIFADDR An interface may have more than one address associated with it -in some protocols. This request provides a means to +in some protocols. +This request provides a means to add additional addresses (or modify characteristics of the primary address if the default address for the address family -is specified). Rather than making separate calls to +is specified). +Rather than making separate calls to set destination or broadcast addresses, or network masks (now an integral feature of multiple protocols) a separate structure is used to specify all three facets simultaneously (see below). One would use a slightly tailored version of this struct specific to each family (replacing each sockaddr by one of the family-specific type). Where the sockaddr itself is larger than the default size, one needs to modify the .Fn ioctl identifier itself to include the total size, as described in .Fn ioctl . .It Dv SIOCDIFADDR This requests deletes the specified address from the list -associated with an interface. It also uses the +associated with an interface. +It also uses the .Vt ifaliasreq structure to allow for the possibility of protocols allowing multiple masks or destination addresses, and also adopts the convention that specification of the default address means to delete the first address for the interface belonging to the address family in which the original socket was opened. .It Dv SIOCGIFCONF -Get interface configuration list. This request takes an +Get interface configuration list. +This request takes an .Vt ifconf -structure (see below) as a value-result parameter. The +structure (see below) as a value-result parameter. +The .Va ifc_len field should be initially set to the size of the buffer pointed to by .Va ifc_buf . On return it will contain the length, in bytes, of the configuration list. .It Dv SIOCIFGCLONERS Get list of clonable interfaces. This request takes an .Vt if_clonereq structure (see below) as a value-result parameter. The .Va ifcr_count field should be set to the number of .Dv IFNAMSIZ sized strings that can be fit in the buffer pointed to by .Va ifcr_buffer . On return, .Va ifcr_total will be set to the number of clonable interfaces and the buffer pointed to by .Va ifcr_buffer will be filled with the names of clonable interfaces aligned on .Dv IFNAMSIZ boundaries. .El .Bd -literal /* * Structure used in SIOCAIFCONF request. */ struct ifaliasreq { char ifra_name[IFNAMSIZ]; /* if name, e.g. "en0" */ struct sockaddr ifra_addr; struct sockaddr ifra_broadaddr; struct sockaddr ifra_mask; }; .Ed .Pp .Bd -literal /* * Structure used in SIOCGIFCONF request. * Used to retrieve interface configuration * for machine (useful for programs which * must know all networks accessible). */ struct ifconf { int ifc_len; /* size of associated buffer */ union { caddr_t ifcu_buf; struct ifreq *ifcu_req; } ifc_ifcu; #define ifc_buf ifc_ifcu.ifcu_buf /* buffer address */ #define ifc_req ifc_ifcu.ifcu_req /* array of structures returned */ }; .Ed .Pp .Bd -literal /* Structure used in SIOCIFGCLONERS request. */ struct if_clonereq { int ifcr_total; /* total cloners (out) */ int ifcr_count; /* room for this many in user buffer */ char *ifcr_buffer; /* buffer for cloner names */ }; .Ed .Sh SEE ALSO .Xr ioctl 2 , .Xr socket 2 , .Xr intro 4 , .Xr config 8 , -.Xr routed 8 +.Xr routed 8 , +.Xr ifnet 9 .Sh HISTORY The .Nm netintro manual appeared in .Bx 4.3 tahoe . Index: head/share/man/man4/ng_ksocket.4 =================================================================== --- head/share/man/man4/ng_ksocket.4 (revision 117010) +++ head/share/man/man4/ng_ksocket.4 (revision 117011) @@ -1,188 +1,200 @@ .\" Copyright (c) 1999 Whistle Communications, Inc. .\" All rights reserved. .\" .\" Subject to the following obligations and disclaimer of warranty, use and .\" redistribution of this software, in source or object code forms, with or .\" without modifications are expressly permitted by Whistle Communications; .\" provided, however, that: .\" 1. Any and all reproductions of the source or object code must include the .\" copyright notice above and the following disclaimer of warranties; and .\" 2. No rights are granted, in any manner or form, to use Whistle .\" Communications, Inc. trademarks, including the mark "WHISTLE .\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as .\" such appears in the above copyright notice or in the software. .\" .\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, .\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. .\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY .\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS .\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. .\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES .\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING .\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, .\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY .\" OF SUCH DAMAGE. .\" .\" Author: Archie Cobbs .\" .\" $FreeBSD$ .\" .Dd November 15, 1999 .Dt NG_KSOCKET 4 .Os .Sh NAME .Nm ng_ksocket .Nd kernel socket netgraph node type .Sh SYNOPSIS .In netgraph/ng_ksocket.h .Sh DESCRIPTION A .Nm ksocket node is both a netgraph node and a .Bx -socket. The +socket. +The .Nm node type allows one to open a socket inside the kernel and have -it appear as a Netgraph node. The +it appear as a Netgraph node. +The .Nm node type is the reverse of the socket node type (see .Xr ng_socket 4 ) : whereas the socket node type enables the user-level manipulation (via a socket) of what is normally a kernel-level entity (the associated Netgraph node), the .Nm node type enables the kernel-level manipulation (via a Netgraph node) of what is normally a user-level entity (the associated socket). .Pp A .Nm -node allows at most one hook connection. Connecting to the node is -equivalent to opening the associated socket. The name given to the hook +node allows at most one hook connection. +Connecting to the node is +equivalent to opening the associated socket. +The name given to the hook determines what kind of socket the node will open (see below). When the hook is disconnected and/or the node is shutdown, the associated socket is closed. .Sh HOOKS This node type supports a single hook connection at a time. The name of the hook must be of the form .Em // , where the .Em family , .Em type , and .Em proto are the decimal equivalent of the same arguments to .Xr socket 2 . Alternately, aliases for the commonly used values are accepted as well. For example .Dv inet/dgram/udp is a more readable but equivalent version of .Dv 2/2/17 . .Sh CONTROL MESSAGES This node type supports the generic control messages, plus the following: .Bl -tag -width foo .It Dv NGM_KSOCKET_BIND This functions exactly like the .Xr bind 2 -system call. The +system call. +The .Dv "struct sockaddr" socket address parameter should be supplied as an argument. .It Dv NGM_KSOCKET_LISTEN This functions exactly like the .Xr listen 2 -system call. The backlog parameter (a single 32 bit +system call. +The backlog parameter (a single 32 bit .Dv int ) should be supplied as an argument. .It Dv NGM_KSOCKET_CONNECT This functions exactly like the .Xr connect 2 -system call. The +system call. +The .Dv "struct sockaddr" destination address parameter should be supplied as an argument. .It Dv NGM_KSOCKET_ACCEPT Currently unimplemented. .It Dv NGM_KSOCKET_GETNAME Equivalent to the .Xr getsockname 2 -system call. The name is returned as a +system call. +The name is returned as a .Dv "struct sockaddr" in the arguments field of the reply. .It Dv NGM_KSOCKET_GETPEERNAME Equivalent to the .Xr getpeername 2 -system call. The name is returned as a +system call. +The name is returned as a .Dv "struct sockaddr" in the arguments field of the reply. .It Dv NGM_KSOCKET_SETOPT Equivalent to the .Xr setsockopt 2 system call, except that the option name, level, and value are passed in a .Dv "struct ng_ksocket_sockopt" . .It Dv NGM_KSOCKET_GETOPT Equivalent to the .Xr getsockopt 2 system call, except that the option is passed in a .Dv "struct ng_ksocket_sockopt" . When sending this command, the .Dv value field should be empty; upon return, it will contain the retrieved value. .El .Sh ASCII FORM CONTROL MESSAGES For control messages that pass a .Dv "struct sockaddr" in the argument field, the normal .Tn ASCII equivalent of the C structure -is an acceptable form. For the +is an acceptable form. +For the .Dv PF_INET and .Dv PF_LOCAL address families, a more convenient form is also used, which is the protocol family name, followed by a slash, followed by the actual -address. For +address. +For .Dv PF_INET , the address is an IP address followed by an optional colon and port number. For .Dv PF_LOCAL , the address is the pathname as a doubly quoted string. .Pp Examples: .Bl -tag -width XXXXXXXXXX .It Dv PF_LOCAL local/"/tmp/foo.socket" .It Dv PF_INET inet/192.168.1.1:1234 .It Other .Dv "\&{ family=16 len=16 data=[0x70 0x00 0x01 0x23] \&}" .El .Pp For control messages that pass a .Dv "struct ng_ksocket_sockopt" , the normal .Tn ASCII -form for that structure is used. In the future, more +form for that structure is used. +In the future, more convenient encoding of the more common socket options may be supported. .Sh SHUTDOWN This node shuts down upon receipt of a .Dv NGM_SHUTDOWN control message, or when the hook is disconnected. Shutdown of the node closes the associated socket. .Sh SEE ALSO .Xr socket 2 , .Xr netgraph 4 , .Xr ng_socket 4 , .Xr ngctl 8 .Sh HISTORY The .Nm node type was implemented in .Fx 4.0 . .Sh AUTHORS .An Archie Cobbs Aq archie@FreeBSD.org Index: head/share/man/man4/ng_l2cap.4 =================================================================== --- head/share/man/man4/ng_l2cap.4 (revision 117010) +++ head/share/man/man4/ng_l2cap.4 (revision 117011) @@ -1,425 +1,425 @@ .\" Copyright (c) 2001-2002 Maksim Yevmenkin .\" 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. .\" .\" $Id: ng_l2cap.4,v 1.2 2003/04/28 20:16:29 max Exp $ .\" $FreeBSD$ .\" .Dd July 4, 2002 .Dt NG_L2CAP 4 .Os .Sh NAME .Nm ng_l2cap .Nd Netgraph node type that implements Bluetooth Logical Link Control and Adaptation Protocol (L2CAP) .Sh SYNOPSIS .In sys/types.h .In netgraph/ng_message.h .In netgraph/netgraph.h .In netgraph/ng_hci.h .In netgraph/ng_l2cap.h .Sh DESCRIPTION The .Nm l2cap node type is a Netgraph node type that implements Bluetooth Logical Link Control and Adaptation Protocol as per chapter D of the Bluetooth Specification Book v1.1. .Pp L2CAP provides connection-oriented and connectionless data services to upper layer protocols with protocol multiplexing capability, segmentation and reassembly operation, and group abstractions. L2CAP permits higher level protocols and applications to transmit and receive L2CAP data packets up to 64 kilobytes in length. .Ss L2CAP Assumptions .Bl -enum -offset indent .It The ACL link between two units is set up. The Baseband provides orderly delivery of data packets, although there might be individual packet corruption and duplicates. No more than 1 ACL link exists between any two devices. .It The Baseband always provides the impression of full-duplex communication channels. This does not imply that all L2CAP communications are bi-directional. Multicasts and unidirectional traffic (e.g., video) do not require duplex channels. .It L2CAP provides a reliable channel using the mechanisms available at the Baseband layer. The Baseband always performs data integrity checks when requested and resends data until it has been successfully acknowledged or a timeout occurs. -Because acknowledgements may be lost, timeouts may +As acknowledgements may be lost, timeouts may occur even after the data has been successfully sent. .El .Sh L2CAP GENERAL OPERATION The Logical Link Control and Adaptation Protocol (L2CAP) is based around the concept of .Dq channels . Each channel is bound to a single protocol in a many-to-one fashion. Multiple channels can be bound to the same protocol, but a channel cannot be bound to multiple protocols. Each L2CAP packet received on a channel is directed to the appropriate higher level protocol. .Pp Each one of the end-points of an L2CAP channel is referred to by a channel identifier. Channel identifiers (CIDs) are local names representing a logical channel end-point on the device. Identifiers from 0x0001 to 0x003F are reserved for specific L2CAP functions. The null identifier (0x0000) is defined as an illegal identifier and must never be used as a destination end-point. All L2CAP signalling commands are sent to CID 0x0001. CID 0x0002 is reserved for group-oriented channel. The same CID must not be reused as a local L2CAP channel endpoint for multiple simultaneous L2CAP channels between a local device and some remote device. .Pp CID assignment is relative to a particular device and a device can assign CIDs independently from other devices. Thus, even if the same CID value has been assigned to (remote) channel endpoints by several remote devices connected to a single local device, the local device can still uniquely associate each remote CID with a different device. .Ss Channel Operational States .Bl -tag -width indent .It Dv NG_L2CAP_CLOSED In this state, there is no channel associated with this CID. This is the only state when a link level connection (Baseband) may not exist. Link disconnection forces all other states into the .Dv NG_L2CAP_CLOSED state. .It Dv NG_L2CAP_W4_L2CAP_CON_RSP In this state, the CID represents a local end-point and an L2CAP Connect Request message has been sent referencing this endpoint and it is now waiting for the corresponding L2CAP Connect Response message. .It Dv NG_L2CAP_W4_L2CA_CON_RSP In this state, the remote end-point exists and an L2CAP Connect Request has been received by the local L2CAP entity. An L2CA Connect Indication has been sent to the upper layer and the part of the local L2CAP entity processing the received L2CAP Connect Request waits for the corresponding response. The response may require a security check to be performed. .It Dv NG_L2CAP_CONFIG In this state, the connection has been established but both sides are still negotiating the channel parameters. The Configuration state may also be entered when the channel parameters are being renegotiated. Prior to entering the .Dv NG_L2CAP_CONFIG state, all outgoing data traffic is suspended since the traffic parameters of the data traffic are to be renegotiated. Incoming data traffic is accepted until the remote channel endpoint has entered the .Dv NG_L2CAP_CONFIG state. In the .Dv NG_L2CAP_CONFIG state, both sides will issue L2CAP Configuration Request messages if only defaults are being used, a null message will be sent. If a large amount of parameters need to be negotiated, multiple messages will be sent to avoid any MTU limitations and negotiate incrementally. Moving from the .Dv NG_L2CAP_CONFIG state to the .Dv NG_L2CAP_OPEN state requires both sides to be ready. An L2CAP entity is ready when it has received a positive response to its final request and it has positively responded to the final request from the remote device. .It Dv NG_L2CAP_OPEN In this state, the connection has been established and configured, and data flow may proceed. .It Dv NG_L2CAP_W4_L2CAP_DISCON_RSP In this state, the connection is shutting down and an L2CAP Disconnect Request message has been sent. This state is now waiting for the corresponding response. .It Dv NG_L2CAP_W4_L2CA_DISCON_RSP In this state, the connection on the remote endpoint is shutting down and an L2CAP Disconnect Request message has been received. An L2CA Disconnect Indication has been sent to the upper layer to notify the owner of the CID that the remote endpoint is being closed. This state is now waiting for the corresponding response from the upper layer before responding to the remote endpoint. .El .Ss Protocol Multiplexing L2CAP supports protocol multiplexing because the Baseband Protocol does not support any .Dq type field identifying the higher layer protocol being multiplexed above it. L2CAP is able to distinguish between upper layer protocols such as the Service Discovery Protocol, RFCOMM and Telephony Control. .Ss Segmentation and Reassembly The data packets defined by the Baseband Protocol are limited in size. Large L2CAP packets must be segmented into multiple smaller Baseband packets prior to their transmission over the air. Similarly, multiple received Baseband packets may be reassembled into a single larger L2CAP packet. .Ss Quality of Service The L2CAP connection establishment process allows the exchange of information regarding the quality of service (QoS) expected between two Bluetooth units. .Ss Groups The Baseband Protocol supports the concept of a piconet, a group of devices synchronously hopping together using the same clock. The L2CAP group abstraction permits implementations to efficiently map protocol groups on to piconets. .Pp The following features are outside the scope of L2CAP responsibilities: .Bl -dash -offset indent .It L2CAP does not transport audio designated for SCO links. .It L2CAP does not enforce a reliable channel or ensure data integrity, that is, L2CAP performs no retransmissions or checksum calculations. .It L2CAP does not support a reliable multicast channel. .It L2CAP does not support the concept of a global group name. .El .Sh HOOKS This node type supports the following hooks: .Pp .Bl -tag -width indent .It Dv hci Bluetooth Host Controller Interface downstream hook. .It Dv l2c Upper layer protocol upstream hook. Usually the Bluetooth L2CAP socket layer is connected to the hook. .It Dv ctl Control hook. Usually Bluetooth raw L2CAP sockets layer is connected to the hook. .El .Sh INTERFACE TO THE UPPER LAYER PROTOCOLS (L2CA CONTROL MESSAGES) Bluetooth specification says that L2CA request must block until response is ready. L2CAP node uses .Va token field from Netgraph message header to match L2CA request and response. The upper layer protocol must populate .Va token . L2CAP node will queue request and start processing. Later, when response is ready or timeout has occured, L2CAP node will create new Netgraph message, set .Va token and .Dv NFG_RESP flag and send message to the upper layer. Note that L2CA indication messages will not populate .Va token and will not set .Dv NGF_RESP flag. There is no reason for this, because they are just notifications and do not require acknowledgment. .Bl -tag -width indent .It Dv NGM_L2CAP_L2CA_CON Requests the creation of a channel representing a logical connection to a physical address. Input parameters are the target protocol (PSM) and remote device's 48-bit address (BD_ADDR). Output parameters are the local CID (LCID) allocated by the local L2CAP entity, and Result of the request. If Result indicates a pending notification, the Status value may contain more information of what processing is delaying the establishment of the connection. .It Dv NGM_L2CAP_L2CA_CON_IND This message includes the parameters for the address of the remote device that issued the connection request, the local CID representing the channel being requested, the Identifier contained in the request, and the PSM value the request is targeting. .It Dv NGM_L2CAP_L2CA_CON_RSP Issues a response to a connection request event indication. Input parameters are the remote device's 48-bit address, Identifier sent in the request, local CID, the Response code, and the Status attached to the Response code. The output parameter is the Result of the service request. This primitive must be called no more than once after receiving the indication. .It Dv NGM_L2CAP_L2CA_CFG Requests the initial configuration (or reconfiguration) of a channel to a new set of channel parameters. Input parameters are the local CID endpoint, new incoming receivable MTU (InMTU), new outgoing flow spec-ification, and flush and link timeouts. Output parameters are the Result, accepted incoming MTU (InMTU), the remote side's flow requests, and flush and link timeouts. .It Dv NGM_L2CAP_L2CA_CFG_IND This message includes the parameters indicating the local CID of the channel the request has been sent to, the outgoing MTU size (maximum packet that can be sent across the channel) and the flowspec describing the characteristics of the incoming data. All other channel parameters are set to their default values if not provided by the remote device. .It Dv NGM_L2CAP_L2CA_CFG_RSP Issues a response to a configuration request event indication. Input parameters include the local CID of the endpoint being configured, outgoing transmit MTU (which may be equal or less to the OutMTU parameter in the configuration indication event) and the accepted flowspec for incoming traffic. The output parameter is the Result value. .It Dv NGM_L2CAP_L2CA_QOS_IND This message includes the parameter indicating the address of the remote Bluetooth device where the QoS contract has been violated. .It Dv NGM_L2CAP_L2CA_DISCON Requests the disconnection of the channel. Input parameter is the CID representing the local channel endpoint. Output parameter is Result. Result is zero if an L2CAP Disconnect Response is received, otherwise a non-zero value is returned. Once disconnection has been requested, no process will be able to successfully read or write from the CID. .It Dv NGM_L2CAP_L2CA_DISCON_IND This message includes the parameter indicating the local CID the request has been sent to. .It Dv NGM_L2CAP_L2CA_WRITE Response to transfer of data request. Actual data must be received from appropriate upstream hook and must be prepended with header defined as follows. .Bd -literal -offset indent /* L2CA data packet header */ typedef struct { u_int32_t token; /* token to use in L2CAP_L2CA_WRITE */ u_int16_t length; /* length of the data */ u_int16_t lcid; /* local channel ID */ } __attribute__ ((packed)) ng_l2cap_l2ca_hdr_t; .Ed .Pp The output parameters are Result and Length of data written. .It Dv NGM_L2CAP_L2CA_GRP_CREATE Requests the creation of a CID to represent a logical connection to multiple devices. Input parameter is the PSM value that the outgoing connectionless traffic is labelled with, and the filter used for incoming traffic. Output parameter is the CID representing the local endpoint. On creation, the group is empty but incoming traffic destined for the PSM value is readable. .Bf -emphasis This request has not been implemented. .Ef .It Dv NGM_L2CAP_L2CA_GRP_CLOSE The use of this message closes down a Group. .Bf -emphasis This request has not been implemented. .Ef .It Dv NGM_L2CAP_L2CA_GRP_ADD_MEMBER Requests the addition of a member to a group. The input parameter includes the CID representing the group and the BD_ADDR of the group member to be added. The output parameter Result confirms the success or failure of the request. .Bf -emphasis This request has not been implemented. .Ef .It Dv NGM_L2CAP_L2CA_GRP_REM_MEMBER Requests the removal of a member from a group. The input parameters include the CID representing the group and BD_ADDR of the group member to be removed. The output parameter Result confirms the success or failure of the request. .Bf -emphasis This request has not been implemented. .Ef .It Dv NGM_L2CAP_L2CA_GRP_MEMBERSHIP Requests a report of the members of a group. The input parameter CID represents the group being queried. The output parameter Result confirms the success or failure of the operation. If the Result is successful, BD_ADDR_Lst is a list of the Bluetooth addresses of the N members of the group. .Bf -emphasis This request has not been implemented. .Ef .It Dv NGM_L2CAP_L2CA_PING Initiates an L2CA Echo Request message and the reception of the corresponding L2CAP Echo Response message. The input parameters are remote Bluetooth device BD_ADDR, Echo Data and Length of the echo data. The output parameters are Result, Echo Data and Length of the echo data. .It Dv NGM_L2CAP_L2CA_GET_INFO Initiates an L2CA Information Request message and the reception of the corresponding L2CAP Info Response message. The input parameters are remote Bluetooth device BD_ADDR and Information Type. The output parameters are Result, Information Data and Size of the information data. .It Dv NGM_L2CAP_L2CA_ENABLE_CLT Request to disable (enable) the reception of connectionless packets. The input parameter is the PSM value indicating service that should be blocked (unblocked) and Enable flag. .El .Sh NETGRAPH CONTROL MESSAGES This node type supports the generic control messages, plus the following: .Bl -tag -width indent .It Dv NGM_L2CAP_NODE_GET_FLAGS Returns current state for the node. .It Dv NGM_L2CAP_NODE_GET_DEBUG Returns an integer containing the current debug level for the node. .It Dv NGM_L2CAP_NODE_SET_DEBUG This command takes an integer argument and sets current debug level for the node. .It Dv NGM_L2CAP_NODE_GET_CON_LIST Returns list of active baseband connections (i.e. ACL links). .It Dv NGM_L2CAP_NODE_GET_CHAN_LIST Returns list of active L2CAP channels. .It Dv NGM_L2CAP_NODE_GET_AUTO_DISCON_TIMO Returns an integer containing the current value of the auto disconnect timeout (in sec). .It Dv NGM_L2CAP_NODE_SET_AUTO_DISCON_TIMO This command accepts an integer and sets the value of the auto disconnect timeout (in sec). The special value of 0 (zero) disables auto disconnect timeout. .El .Sh SHUTDOWN This node shuts down upon receipt of an .Dv NGM_SHUTDOWN control message, or when all hooks have been disconnected. .Sh BUGS Most likely. Please report if found. .Sh SEE ALSO .Xr netgraph 4 , .Xr l2control 8 , .Xr l2ping 8 , .Xr ngctl 8 .Sh HISTORY The .Nm l2cap node type was implemented in .Fx 5.0 . .Sh AUTHORS .An Maksim Yevmenkin Aq m_evmenkin@yahoo.com Index: head/share/man/man4/ng_ppp.4 =================================================================== --- head/share/man/man4/ng_ppp.4 (revision 117010) +++ head/share/man/man4/ng_ppp.4 (revision 117011) @@ -1,387 +1,405 @@ .\" Copyright (c) 1996-1999 Whistle Communications, Inc. .\" All rights reserved. .\" .\" Subject to the following obligations and disclaimer of warranty, use and .\" redistribution of this software, in source or object code forms, with or .\" without modifications are expressly permitted by Whistle Communications; .\" provided, however, that: .\" 1. Any and all reproductions of the source or object code must include the .\" copyright notice above and the following disclaimer of warranties; and .\" 2. No rights are granted, in any manner or form, to use Whistle .\" Communications, Inc. trademarks, including the mark "WHISTLE .\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as .\" such appears in the above copyright notice or in the software. .\" .\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, .\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. .\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY .\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS .\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. .\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES .\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING .\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, .\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY .\" OF SUCH DAMAGE. .\" .\" Author: Archie Cobbs .\" .\" $FreeBSD$ .\" $Whistle: ng_ppp.8,v 1.3 1999/01/25 23:46:27 archie Exp $ .\" .Dd January 19, 1999 .Dt NG_PPP 4 .Os .Sh NAME .Nm ng_ppp .Nd PPP protocol netgraph node type .Sh SYNOPSIS .In netgraph/ng_ppp.h .Sh DESCRIPTION The .Nm ppp -node type performs multiplexing for the PPP protocol. It handles -only packets that contain data, and forwards protocol negotiation +node type performs multiplexing for the PPP protocol. +It handles only packets that contain data, and forwards protocol negotiation and control packets to a separate controlling entity (e.g., a -user-land daemon). This approach combines the fast dispatch of +user-land daemon). +This approach combines the fast dispatch of kernel implementations with the configuration flexibility of a -user-land implementations. The PPP node type directly supports +user-land implementations. +The PPP node type directly supports multi-link PPP, Van Jacobson compression, PPP compression, PPP -encryption, and the IP, IPX, and AppleTalk protocols. A single -PPP node corresponds to one PPP multi-link bundle. +encryption, and the IP, IPX, and AppleTalk protocols. +A single PPP node corresponds to one PPP multi-link bundle. .Pp There is a separate hook for each PPP link in the bundle, plus several hooks corresponding to the directly supported protocols. For compression and encryption, separate attached nodes are required -to do the actual work. The node type used will of course depend -on the algorithm negotiated. There is also a +to do the actual work. +The node type used will of course depend on the algorithm negotiated. +There is also a .Dv bypass hook which is used to handle any protocol not directly supported -by the node. This includes all of the control protocols: LCP, IPCP, -CCP, etc. Typically this node is connected to a user-land daemon -via a +by the node. +This includes all of the control protocols: LCP, IPCP, +CCP, etc. +Typically this node is connected to a user-land daemon via a .Xr ng_socket 4 type node. .Sh ENABLING FUNCTIONALITY In general, the PPP node enables a specific link or functionality when (a) a .Dv NGM_PPP_SET_CONFIG message has been received which enables it, and (b) the corresponding hook(s) are connected. This allows the controlling entity to use either method (a) or (b) (or both) to control the node's behavior. When a link is connected but disabled, traffic can still flow on the link via the .Dv bypass hook (see below). .Sh LINK HOOKS During normal operation, the individual PPP links are connected to hooks .Dv link0 , .Dv link1 , etc. Up to .Dv NG_PPP_MAX_LINKS links are supported. These device-independent hooks transmit and receive full PPP frames, which include the PPP protocol, address, control, and information fields, but no checksum or other link-specific fields. .Pp On outgoing frames, when protocol compression has been enabled and the protocol number is suitable for compression, the protocol field will be compressed (i.e., sent as one byte -instead of two). Either compressed or uncompressed protocol fields -are accepted on incoming frames. Similarly, if address and control +instead of two). +Either compressed or uncompressed protocol fields +are accepted on incoming frames. +Similarly, if address and control field compression has been enabled for the link, the address and control fields will be omitted (except for LCP frames as required -by the standards). Incoming frames have the address and control fields +by the standards). +Incoming frames have the address and control fields stripped automatically if present. .Pp Since all negotiation is handled outside the PPP node, the links should not be connected and enabled until the corresponding link has reached the network phase (i.e., LCP negotiation and authentication have completed successfully) and the PPP node has been informed of the link parameters via the .Dv NGM_PPP_LINK_CONFIG message. .Pp When a link is connected but disabled, all received frames are forwarded directly out the .Dv bypass hook, and conversely, frames may be transmitted via the .Dv bypass -hook as well. This mode is appropriate for the link authentication phase. +hook as well. +This mode is appropriate for the link authentication phase. As soon as the link is enabled, the PPP node will begin processing frames received on the link. .Sh COMPRESSION AND ENCRYPTION Compression is supported via two hooks, .Dv compress and .Dv decompress . When enabled and connected, the PPP node writes outgoing frames on the .Dv comp hook and expects to receive back the compressed frame on the same hook. Similarly, the .Dv decompress hook is used to uncompress incoming frames when decompression is negotiated (compression and decompression are independently negotiable). The type of node attached to these hooks should correspond to the type of compression negotiated, e.g., Deflate, Predictor-1, etc. .Pp Encryption works exactly analogously via the .Dv encrypt and .Dv decrypt -nodes. Data is always compressed before being encrypted, +nodes. +Data is always compressed before being encrypted, and decrypted before being decompressed. .Pp Only bundle-level compression and encryption is directly supported; link-level compression and encryption can be handled transparently by downstream nodes. .Sh VAN JACOBSON COMPRESSION When all of the .Dv vjc_ip , .Dv vjc_vjcomp , .Dv vjc_vjuncomp , and .Dv vjc_vjip hooks are connected, and the corresponding configuration flag is enabled, Van Jacobson compression and/or decompression will become active. Normally these hooks connect to the corresponding hooks of a single .Xr ng_vjc 4 node. The PPP node is compatible with the .Dq pass through modes of the .Xr ng_vjc 4 node type. .Sh BYPASS HOOK When a frame is received on a link with an unsupported protocol, or a protocol which is disabled or for which the corresponding hook is unconnected, the PPP node forwards the frame out the .Dv bypass -hook, prepended with a four byte prefix. This first two bytes of +hook, prepended with a four byte prefix. +This first two bytes of the prefix indicate the link number on which the frame was received (in network order). For such frames received over the bundle (i.e., encapsulated in the multi-link protocol), the special link number .Dv NG_PPP_BUNDLE_LINKNUM is used. After the two byte link number is the two byte PPP protocol number (also in network order). The PPP protocol number is two bytes long even if the original frame was protocol compressed. .Pp Conversely, any data written to the .Dv bypass -hook is assumed to be in this same format. The four byte header is +hook is assumed to be in this same format. +The four byte header is stripped off, the PPP protocol number is prepended (possibly compressed), and the frame is delivered over the desired link. If the link number is .Dv NG_PPP_BUNDLE_LINKNUM the frame will be delivered over the multi-link bundle; or, if multi-link is disabled, over the (single) PPP link. .Pp Typically when the controlling entity receives an unexpected packet on the .Dv bypass hook it responds either by dropping the frame (if it's not ready for the protocol) or with an LCP protocol reject (if it doesn't recognize or expect the protocol). .Sh MULTILINK OPERATION To enable multi-link PPP, the corresponding configuration flag must be set -and at least one link connected. The PPP node will not allow more than +and at least one link connected. +The PPP node will not allow more than one link to be connected if multi-link is not enabled, nor will it allow certain multi-link settings to be changed while multi-link operation is active (e.g., short sequence number header format). .Pp -Because packets are sent as fragments across multiple individual links, +Since packets are sent as fragments across multiple individual links, it is important that when a link goes down the PPP node is notified immediately, either by disconnecting the corresponding hook or disabling the link via the .Dv NGM_PPP_SET_CONFIG control message. .Pp Each link has configuration parameters for latency (specified in milliseconds) and bandwidth (specified in tens of bytes per second). The PPP node can be configured for .Em round-robin or .Em optimized packet delivery. .Pp When configured for round-robin delivery, the latency and bandwidth values are ignored and the PPP node simply sends each frame as a single fragment, alternating frames across all the links in the -bundle. This scheme has the advantage that even if one link fails -silently, some packets will still get through. It has the disadvantage +bundle. +This scheme has the advantage that even if one link fails +silently, some packets will still get through. +It has the disadvantage of sub-optimal overall bundle latency, which is important for interactive response time, and sub-optimal overall bundle bandwidth when links with different bandwidths exist in the same bundle. .Pp When configured for optimal delivery, the PPP node distributes the packet across the links in a way that minimizes the time it takes -for the completed packet to be received by the far end. This -involves taking into account each link's latency, bandwidth, and -current queue length. Therefore these numbers should be -configured as accurately as possible. The algorithm does require +for the completed packet to be received by the far end. +This involves taking into account each link's latency, bandwidth, and +current queue length. +Therefore these numbers should be configured as accurately as possible. +The algorithm does require some computation, so may not be appropriate for very slow machines and/or very fast links. .Pp As a special case, if all links have identical latency and bandwidth, then the above algorithm is disabled (because it is unnecessary) and the PPP node simply fragments frames into equal sized portions across all of the links. .Sh HOOKS This node type supports the following hooks: .Pp .Bl -tag -compact -width vjc_vjuncomp .It Dv link Individual PPP link number .Dv .It Dv compress Connection to compression engine .It Dv decompress Connection to decompression engine .It Dv encrypt Connection to encryption engine .It Dv decrypt Connection to decryption engine .It Dv vjc_ip Connection to .Xr ng_vjc 4 .Dv ip hook .It Dv vjc_vjcomp Connection to .Xr ng_vjc 4 .Dv vjcomp hook .It Dv vjc_vjuncomp Connection to .Xr ng_vjc 4 .Dv vjuncomp hook .It Dv vjc_vjip Connection to .Xr ng_vjc 4 .Dv vjip hook .It Dv inet IP packet data .It Dv atalk AppleTalk packet data .It Dv ipx IPX packet data .It Dv bypass Bypass hook; frames have a four byte header consisting of a link number and a PPP protocol number. .El .Sh CONTROL MESSAGES This node type supports the generic control messages, plus the following: .Bl -tag -width foo .It Dv NGM_PPP_SET_CONFIG -This command configures all aspects of the node. This includes enabling +This command configures all aspects of the node. +This includes enabling multi-link PPP, encryption, compression, Van Jacobson compression, and IP, -AppleTalk, and IPX packet delivery. It includes per-link configuration, +AppleTalk, and IPX packet delivery. +It includes per-link configuration, including enabling the link, setting latency and bandwidth parameters, -and enabling protocol field compression. Note that no link or functionality +and enabling protocol field compression. +Note that no link or functionality is active until the corresponding hook is also connected. This command takes a .Dv "struct ng_ppp_node_config" as an argument: .Bd -literal -offset 0n /* Per-link config structure */ struct ng_ppp_link_config { u_char enableLink; /* enable this link */ u_char enableProtoComp;/* enable protocol field compression */ u_char enableACFComp; /* enable addr/ctrl field compression */ u_int16_t mru; /* peer MRU */ u_int32_t latency; /* link latency (in milliseconds) */ u_int32_t bandwidth; /* link bandwidth (in bytes/second) */ }; /* Node config structure */ struct ng_ppp_node_config { u_int16_t mrru; /* multilink peer MRRU */ u_char enableMultilink; /* enable multilink */ u_char recvShortSeq; /* recv multilink short seq # */ u_char xmitShortSeq; /* xmit multilink short seq # */ u_char enableRoundRobin; /* xmit whole packets */ u_char enableIP; /* enable IP data flow */ u_char enableAtalk; /* enable AppleTalk data flow */ u_char enableIPX; /* enable IPX data flow */ u_char enableCompression; /* enable PPP compression */ u_char enableDecompression; /* enable PPP decompression */ u_char enableEncryption; /* enable PPP encryption */ u_char enableDecryption; /* enable PPP decryption */ u_char enableVJCompression; /* enable VJ compression */ u_char enableVJDecompression; /* enable VJ decompression */ struct ng_ppp_link_config /* per link config params */ links[NG_PPP_MAX_LINKS]; }; .Ed .Pp .It Dv NGM_PPP_GET_CONFIG Returns the current configuration as a .Dv "struct ng_ppp_node_config" . .It Dv NGM_PPP_GET_LINK_STATS This command takes a two byte link number as an argument and returns a .Dv "struct ng_ppp_link_stat" containing statistics for the corresponding link. Here .Dv NG_PPP_BUNDLE_LINKNUM is a valid link number corresponding to the multi-link bundle. .It Dv NGM_PPP_CLR_LINK_STATS This command takes a two byte link number as an argument and clears the statistics for that link. .It Dv NGM_PPP_GETCLR_LINK_STATS Same as .Dv NGM_PPP_GET_LINK_STATS , but also atomically clears the statistics as well. .El .Pp This node type also accepts the control messages accepted by the .Xr ng_vjc 4 node type. When received, these messages are simply forwarded to the adjacent .Xr ng_vjc 4 node, if any. This is particularly useful when the individual PPP links are able to generate .Dv NGM_VJC_RECV_ERROR messages (see .Xr ng_vjc 4 for a description). .Sh SHUTDOWN This node shuts down upon receipt of a .Dv NGM_SHUTDOWN control message, or when all hooks have been disconnected. .Sh SEE ALSO .Xr netgraph 4 , .Xr ng_async 4 , .Xr ng_iface 4 , .Xr ng_mppc 4 , .Xr ng_pppoe 4 , .Xr ng_vjc 4 , .Xr ngctl 8 .Rs .%A W. Simpson .%T "The Point-to-Point Protocol (PPP)" .%O RFC 1661 .Re .Rs .%A K. Sklower .%A B. Lloyd .%A G. McGregor .%A D. Carr .%A T. Coradetti .%T "The PPP Multilink Protocol (MP)" .%O RFC 1990 .Re .Sh HISTORY The .Nm node type was implemented in .Fx 4.0 . .Sh AUTHORS .An Archie Cobbs Aq archie@FreeBSD.org Index: head/share/man/man4/ng_pppoe.4 =================================================================== --- head/share/man/man4/ng_pppoe.4 (revision 117010) +++ head/share/man/man4/ng_pppoe.4 (revision 117011) @@ -1,422 +1,436 @@ .\" Copyright (c) 1996-1999 Whistle Communications, Inc. .\" All rights reserved. .\" .\" Subject to the following obligations and disclaimer of warranty, use and .\" redistribution of this software, in source or object code forms, with or .\" without modifications are expressly permitted by Whistle Communications; .\" provided, however, that: .\" 1. Any and all reproductions of the source or object code must include the .\" copyright notice above and the following disclaimer of warranties; and .\" 2. No rights are granted, in any manner or form, to use Whistle .\" Communications, Inc. trademarks, including the mark "WHISTLE .\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as .\" such appears in the above copyright notice or in the software. .\" .\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, .\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. .\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY .\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS .\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. .\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES .\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING .\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, .\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY .\" OF SUCH DAMAGE. .\" .\" Author: Archie Cobbs .\" .\" $FreeBSD$ .\" $Whistle: ng_pppoe.8,v 1.1 1999/01/25 23:46:27 archie Exp $ .\" .Dd October 28, 1999 .Dt NG_PPPOE 4 .Os .Sh NAME .Nm ng_pppoe .Nd RFC 2516 PPPOE protocol netgraph node type .Sh SYNOPSIS .In net/ethernet.h .In netgraph/ng_pppoe.h .Sh DESCRIPTION The .Nm pppoe node type performs the PPPoE protocol. It is used in conjunction with the .Xr netgraph 4 extensions to the Ethernet framework to divert and inject Ethernet packets to and from a PPP agent (which is not specified). .Pp The .Dv NGM_PPPOE_GET_STATUS control message can be used at any time to query the current status of the PPPOE module. The only statistics presently available are the -total packet counts for input and output. This node does not yet support +total packet counts for input and output. +This node does not yet support the .Dv NGM_TEXT_STATUS control message. .Sh HOOKS This node type supports the following hooks: .Pp .Bl -tag -width foobarbaz .It Dv ethernet The hook that should normally be connected to an Ethernet node. .It Dv debug Presently no use. .It Dv [unspecified] Any other name is assumed to be a session hook that will be connected to a PPP client agent, or a ppp server agent. .El .Sh CONTROL MESSAGES This node type supports the generic control messages, plus the following: .Bl -tag -width foo .It Dv NGM_PPPOE_GET_STATUS This command returns status information in a .Dv "struct ngpppoestat" : .Bd -literal -offset 4n struct ngpppoestat { u_int packets_in; /* packets in from ethernet */ u_int packets_out; /* packets out towards ethernet */ }; .Ed .It Dv NGM_TEXT_STATUS This generic message returns is a human-readable version of the node status. (not yet) .It Dv NGM_PPPOE_CONNECT Tell a nominated newly created hook that it's session should enter -the state machine in a manner to become a client. It must be newly created and +the state machine in a manner to become a client. +It must be newly created and a service name can be given as an argument. It is legal to specify a zero length -service name. This is common on some DSL setups. A session request packet +service name. +This is common on some DSL setups. A session request packet will be broadcast on the Ethernet. This command uses the .Dv ngpppoe_init_data structure shown below. .It Dv NGM_PPPOE_LISTEN Tell a nominated newly created hook that it's session should enter -the state machine in a manner to become a server listener. The argument -given is the name of the service to listen on behalf of. A zero length service -length will match all requests for service. A matching service request +the state machine in a manner to become a server listener. +The argument +given is the name of the service to listen on behalf of +a zero length service length will match all requests for service. +A matching service request packet will be passed unmodified back to the process responsible -for starting the service. It can then examine it and pass it on to +for starting the service. +It can then examine it and pass it on to the session that is started to answer the request. This command uses the .Dv ngpppoe_init_data structure shown below. .It Dv NGM_PPPOE_OFFER Tell a nominated newly created hook that it's session should enter -the state machine in a manner to become a server. The argument -given is the name of the service to offer. A zero length service -is legal. The State machine will progress to a state where it will await +the state machine in a manner to become a server. +The argument given is the name of the service to offer. +A zero length service +is legal. +The State machine will progress to a state where it will await a request packet to be forwarded to it from the startup server, which in turn probably received it from a LISTEN mode hook ( see above). This is so that information that is required for the session that is embedded in the original session request packet, is made available to the state machine -that eventually answers the request. When the Session request packet is +that eventually answers the request. +When the Session request packet is received, the session negotiation will proceed. This command uses the .Dv ngpppoe_init_data structure shown below. .Pp The three commands above use a common data structure: .Bd -literal -offset 4n struct ngpppoe_init_data { char hook[NG_HOOKLEN + 1]; /* hook to monitor on */ u_int16_t data_len; /* service name length */ char data[0]; /* init data goes here */ }; .Ed .It Dv NGM_PPPOE_SUCCESS This command is sent to the node that started this session with one of the -above messages, and reports a state change. This message reports -successful Session negotiation. It uses the structure shown below, and +above messages, and reports a state change. +This message reports successful Session negotiation. +It uses the structure shown below, and reports back the hook name corresponding to the successful session. .It Dv NGM_NGM_PPPOE_FAIL This command is sent to the node that started this session with one of the -above messages, and reports a state change. This message reports -failed Session negotiation. It uses the structure shown below, and +above messages, and reports a state change. +This message reports failed Session negotiation. +It uses the structure shown below, and reports back the hook name corresponding to the failed session. The hook will probably have been removed immediately after sending this message .It Dv NGM_NGM_PPPOE_CLOSE This command is sent to the node that started this session with one of the above messages, and reports a state change. This message reports -a request to close a session. It uses the structure shown below, and +a request to close a session. +It uses the structure shown below, and reports back the hook name corresponding to the closed session. The hook will probably have been removed immediately after sending this -message. At present this message is not yet used and a 'failed' message +message. +At present this message is not yet used and a 'failed' message will be received at closure instead. .It Dv NGM_PPPOE_ACNAME This command is sent to the node that started this session with one of the above messages, and reports the Access Concentrator Name. .El .Pp The four commands above use a common data structure: .Bd -literal -offset 4n struct ngpppoe_sts { char hook[NG_HOOKLEN + 1]; /* hook associated with event session */ }; .Ed .Sh SHUTDOWN This node shuts down upon receipt of a .Dv NGM_SHUTDOWN control message, when all session have been disconnected or when the .Dv ethernet hook is disconnected. .Sh SYSCTLs If you are one of the unfortunate people who have an ISP that uses some "pppoe" equipment from (I believe) 3com, and who have to use a different ethertype on pppoe packets (hey why not change it from the standard for no reason?) then after you have kldloaded or compiled in your pppoe node, you may have to do the following sysctl: .Bd -literal (kldload netgraph) (kldload ng_pppoe) sysctl net.graph.stupid_isp=1 .Ed .Pp to enable the alternate ethertypes. Then phone your ISP and ask them why you need to set option "stupid_isp" for you to be able to connect. .Sh EXAMPLES The following code uses .Dv libnetgraph to set up a .Nm -node and connect it to both a socket node and an Ethernet node. It can handle -the case of when a +node and connect it to both a socket node and an Ethernet node. +It can handle the case of when a .Nm -node is already attached to the Ethernet. It then starts a client session. +node is already attached to the Ethernet. +It then starts a client session. .Bd -literal #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include static int setup(char *ethername, char *service, char *sessname, int *dfd, int *cfd); int main() { int fd1, fd2; setup("xl0", NULL, "fred", &fd1, &fd2); sleep (30); } static int setup(char *ethername, char *service, char *sessname, int *dfd, int *cfd) { struct ngm_connect ngc; /* connect */ struct ngm_mkpeer mkp; /* mkpeer */ /******** nodeinfo stuff **********/ u_char rbuf[2 * 1024]; struct ng_mesg *const resp = (struct ng_mesg *) rbuf; struct hooklist *const hlist = (struct hooklist *) resp->data; struct nodeinfo *const ninfo = &hlist->nodeinfo; int ch, no_hooks = 0; struct linkinfo *link; struct nodeinfo *peer; /****message to connect pppoe session*****/ struct { struct ngpppoe_init_data idata; char service[100]; } message; /********tracking our little graph ********/ char path[100]; char source_ID[NG_NODELEN + 1]; char pppoe_node_name[100]; int k; /* * Create the data and control sockets */ if (NgMkSockNode(NULL, cfd, dfd) < 0) { return (errno); } /* * find the ether node of the name requested by asking it for * it's inquiry information. */ if (strlen(ethername) > 16) return (EINVAL); sprintf(path, "%s:", ethername); if (NgSendMsg(*cfd, path, NGM_GENERIC_COOKIE, NGM_LISTHOOKS, NULL, 0) < 0) { return (errno); } /* * the command was accepted so it exists. Await the reply (It's * almost certainly already waiting). */ if (NgRecvMsg(*cfd, resp, sizeof(rbuf), NULL) < 0) { return (errno); } /** * The following is available about the node: * ninfo->name (string) * ninfo->type (string) * ninfo->id (u_int32_t) * ninfo->hooks (u_int32_t) (count of hooks) * check it is the correct type. and get it's ID for use * with mkpeer later. */ if (strncmp(ninfo->type, NG_ETHER_NODE_TYPE, strlen(NG_ETHER_NODE_TYPE)) != 0) { return (EPROTOTYPE); } sprintf(source_ID, "[%08x]:", ninfo->id); /* * look for a hook already attached. */ for (k = 0; k < ninfo->hooks; k++) { /** * The following are available about each hook. * link->ourhook (string) * link->peerhook (string) * peer->name (string) * peer->type (string) * peer->id (u_int32_t) * peer->hooks (u_int32_t) */ link = &hlist->link[k]; peer = &hlist->link[k].nodeinfo; /* Ignore debug hooks */ if (strcmp("debug", link->ourhook) == 0) continue; /* If the orphans hook is attached, use that */ if (strcmp(NG_ETHER_HOOK_ORPHAN, link->ourhook) == 0) { break; } /* the other option is the 'divert' hook */ if (strcmp("NG_ETHER_HOOK_DIVERT", link->ourhook) == 0) { break; } } /* * See if we found a hook there. */ if (k < ninfo->hooks) { if (strcmp(peer->type, NG_PPPOE_NODE_TYPE) == 0) { /* * If it's a type pppoe, we skip making one * ourself, but we continue, using * the existing one. */ sprintf(pppoe_node_name, "[%08x]:", peer->id); } else { /* * There is already someone hogging the data, * return an error. Some day we'll try * daisy-chaining.. */ return (EBUSY); } } else { /* * Try make a node of type pppoe against node "ID" * On hook NG_ETHER_HOOK_ORPHAN. */ snprintf(mkp.type, sizeof(mkp.type), "%s", NG_PPPOE_NODE_TYPE); snprintf(mkp.ourhook, sizeof(mkp.ourhook), "%s", NG_ETHER_HOOK_ORPHAN); snprintf(mkp.peerhook, sizeof(mkp.peerhook), "%s", NG_PPPOE_HOOK_ETHERNET); /* Send message */ if (NgSendMsg(*cfd, source_ID, NGM_GENERIC_COOKIE, NGM_MKPEER, &mkp, sizeof(mkp)) < 0) { return (errno); } /* * Work out a name for the new node. */ sprintf(pppoe_node_name, "%s:%s", source_ID, NG_ETHER_HOOK_ORPHAN); } /* * We now have a pppoe node attached to the ethernet * card. The Ethernet is addressed as ethername: The pppoe * node is addressed as pppoe_node_name: attach to it. * Connect socket node to specified node Use the same hook * name on both ends of the link. */ snprintf(ngc.path, sizeof(ngc.path), "%s", pppoe_node_name); snprintf(ngc.ourhook, sizeof(ngc.ourhook), "%s", sessname); snprintf(ngc.peerhook, sizeof(ngc.peerhook), "%s", sessname); if (NgSendMsg(*cfd, ".:", NGM_GENERIC_COOKIE, NGM_CONNECT, &ngc, sizeof(ngc)) < 0) { return (errno); } /* * Send it a message telling it to start up. */ bzero(&message, sizeof(message)); snprintf(message.idata.hook, sizeof(message.idata.hook), "%s", sessname); if (service == NULL) { message.idata.data_len = 0; } else { snprintf(message.idata.data, sizeof(message.idata.data), "%s", service); message.idata.data_len = strlen(service); } /* Tell session/hook to start up as a client */ if (NgSendMsg(*cfd, ngc.path, NGM_PPPOE_COOKIE, NGM_PPPOE_CONNECT, &message.idata, sizeof(message.idata) + message.idata.data_len) < 0) { return (errno); } return (0); } .Ed .Sh SEE ALSO .Xr netgraph 3 , .Xr netgraph 4 , .Xr ng_ppp 4 , .Xr ng_socket 4 , .Xr ngctl 8 .Rs .%A L. Mamakos .%A K. Lidl .%A J. Evarts .%A D. Carrel .%A D. Simone .%A R. Wheeler .%T "A Method for transmitting PPP over Ethernet (PPPoE)" .%O RFC 2516 .Re .Sh HISTORY The .Nm node type was implemented in .Fx 4.0 . .Sh AUTHORS .An Julian Elischer Aq julian@FreeBSD.org Index: head/share/man/man4/ng_socket.4 =================================================================== --- head/share/man/man4/ng_socket.4 (revision 117010) +++ head/share/man/man4/ng_socket.4 (revision 117011) @@ -1,182 +1,187 @@ .\" Copyright (c) 1996-1999 Whistle Communications, Inc. .\" All rights reserved. .\" .\" Subject to the following obligations and disclaimer of warranty, use and .\" redistribution of this software, in source or object code forms, with or .\" without modifications are expressly permitted by Whistle Communications; .\" provided, however, that: .\" 1. Any and all reproductions of the source or object code must include the .\" copyright notice above and the following disclaimer of warranties; and .\" 2. No rights are granted, in any manner or form, to use Whistle .\" Communications, Inc. trademarks, including the mark "WHISTLE .\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as .\" such appears in the above copyright notice or in the software. .\" .\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, .\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. .\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY .\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS .\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. .\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES .\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING .\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, .\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY .\" OF SUCH DAMAGE. .\" .\" Author: Archie Cobbs .\" .\" $FreeBSD$ .\" $Whistle: ng_socket.8,v 1.5 1999/01/25 23:46:27 archie Exp $ .\" .Dd January 19, 1999 .Dt NG_SOCKET 4 .Os .Sh NAME .Nm ng_socket .Nd netgraph socket node type .Sh SYNOPSIS .In netgraph/ng_message.h .In netgraph/ng_socket.h .Sh DESCRIPTION A .Nm socket node is both a .Bx socket and a netgraph node. The .Nm node type allows user-mode processes to participate in the kernel .Xr netgraph 4 networking subsystem using the .Bx -socket interface. The process must have +socket interface. +The process must have root privileges to be able to create netgraph sockets however once created, any process that has one may use it. .Pp A new .Nm node is created by creating a new socket of type .Dv NG_CONTROL in the protocol family .Dv PF_NETGRAPH , using the .Xr socket 2 system call. Any control messages received by the node and not having a cookie value of .Dv NGM_SOCKET_COOKIE are received by the process, using .Xr recvfrom 2 ; the socket address argument is a .Dv "struct sockaddr_ng" -containing the sender's netgraph address. Conversely, control messages -can be sent to any node by calling +containing the sender's netgraph address. +Conversely, control messages can be sent to any node by calling .Xr sendto 2 , supplying the recipient's address in a .Dv "struct sockaddr_ng" . The .Xr bind 2 system call may be used to assign a global netgraph name to the node. .Pp To transmit and receive netgraph data packets, a .Dv NG_DATA socket must also be created using .Xr socket 2 and associated with a .Nm node. .Dv NG_DATA sockets do not automatically have nodes associated with them; they are bound to a specific node via the .Xr connect 2 -system call. The address argument is the netgraph address of the +system call. +The address argument is the netgraph address of the .Nm -node already created. Once a data socket is associated with a node, +node already created. +Once a data socket is associated with a node, any data packets received by the node are read using .Xr recvfrom 2 and any packets to be sent out from the node are written using .Xr sendto 2 . In the case of data sockets, the .Dv "struct sockaddr_ng" contains the name of the .Em hook on which the data was received or should be sent. .Pp As a special case, to allow netgraph data sockets to be used as stdin or stdout on naive programs, a .Xr sendto 2 with a NULL sockaddr pointer, a .Xr send 2 or a .Xr write 2 will succeed in the case where there is exactly ONE hook attached to the socket node, (and thus the path is unambiguous). .Pp There is a user library that simplifies using netgraph sockets; see .Xr netgraph 3 . .Sh HOOKS This node type supports hooks with arbitrary names (as long as they are unique) and always accepts hook connection requests. .Sh CONTROL MESSAGES This node type supports the generic control messages, plus the following: .Bl -tag -width foo .It Dv NGM_SOCK_CMD_NOLINGER When the last hook is removed from this node, it will shut down as if it had received a .Dv NGM_SHUTDOWN message. Attempts to access the sockets associated will return .Er ENOTCONN . .It Dv NGM_SOCK_CMD_LINGER -This is the default mode. When the last hook is removed, the node will +This is the default mode. +When the last hook is removed, the node will continue to exist, ready to accept new hooks until it is explicitly shut down. .El .Pp All other messages with neither the .Dv NGM_SOCKET_COOKIE or .Dv NGM_GENERIC_COOKIE will be passed unaltered up the .Dv NG_CONTROL socket. .Sh SHUTDOWN This node type shuts down and disappears when both the associated .Dv NG_CONTROL and .Dv NG_DATA sockets have been closed, or a .Dv NGM_SHUTDOWN -control message is received. In the latter case, attempts to write +control message is received. +In the latter case, attempts to write to the still-open sockets will return .Er ENOTCONN . If the .Dv NGM_SOCK_CMD_NOLINGER message has been received, closure of the last hook will also initiate a shutdown of the node. .Sh BUGS It is not possible to reject the connection of a hook, though any data received on that hook can certainly be ignored. .Pp The controlling process is not notified of all events that an in-kernel node -would be notified of, e.g. a new hook, or hook removal. We should define -some node-initiated messages for this purpose (to be sent up the control -socket). +would be notified of, e.g. a new hook, or hook removal. +Some node-initiated messages should be defined for this purpose (to be +sent up the control socket). .Sh SEE ALSO .Xr socket 2 , .Xr netgraph 3 , .Xr netgraph 4 , .Xr ng_ksocket 4 , .Xr ngctl 8 .Sh HISTORY The .Nm node type was implemented in .Fx 4.0 . .Sh AUTHORS .An Julian Elischer Aq julian@FreeBSD.org Index: head/share/man/man4/ng_vjc.4 =================================================================== --- head/share/man/man4/ng_vjc.4 (revision 117010) +++ head/share/man/man4/ng_vjc.4 (revision 117011) @@ -1,225 +1,232 @@ .\" Copyright (c) 1996-1999 Whistle Communications, Inc. .\" All rights reserved. .\" .\" Subject to the following obligations and disclaimer of warranty, use and .\" redistribution of this software, in source or object code forms, with or .\" without modifications are expressly permitted by Whistle Communications; .\" provided, however, that: .\" 1. Any and all reproductions of the source or object code must include the .\" copyright notice above and the following disclaimer of warranties; and .\" 2. No rights are granted, in any manner or form, to use Whistle .\" Communications, Inc. trademarks, including the mark "WHISTLE .\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as .\" such appears in the above copyright notice or in the software. .\" .\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, .\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. .\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY .\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS .\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. .\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES .\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING .\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, .\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY .\" OF SUCH DAMAGE. .\" .\" Author: Archie Cobbs .\" .\" $FreeBSD$ .\" $Whistle: ng_vjc.8,v 1.4 1999/01/25 23:46:28 archie Exp $ .\" .Dd January 19, 1999 .Dt NG_VJC 4 .Os .Sh NAME .Nm ng_vjc .Nd Van Jacobson compression netgraph node type .Sh SYNOPSIS .In net/slcompress.h .In netgraph/ng_vjc.h .Sh DESCRIPTION The .Nm vjc node type performs Van Jacobson compression, which is used over PPP, SLIP, and other point-to-point IP connections to compress TCP packet headers. The .Dv ip hook represents the uncompressed side of the node, while the .Dv vjcomp , .Dv vjuncomp , and .Dv vjip -hooks represent the compressed side of the node. Packets received on the +hooks represent the compressed side of the node. +Packets received on the .Dv ip -will be compressed or passed through as appropriate. Packets received -on the other three hooks will be uncompressed as appropriate. +will be compressed or passed through as appropriate. +Packets received on the other three hooks will be uncompressed as appropriate. This node also supports .Dq always pass through mode in either direction. .Pp Van Jacobson compression only applies to TCP packets. Only .Dq normal (i.e., common case) TCP packets are actually compressed. These are output on the .Dv vjcomp -hook. Other TCP packets are run through the state machine but not +hook. +Other TCP packets are run through the state machine but not compressed; these appear on the .Dv vjuncomp hook. Other non-TCP IP packets are forwarded unchanged to .Dv vjip . .Pp When connecting to a .Xr ng_ppp 4 node, the .Dv ip , .Dv vjuncomp , .Dv vjcomp , and .Dv vjip hooks should be connected to the .Xr ng_ppp 4 node's .Dv vjc_ip , .Dv vjc_vjcomp , .Dv vjc_vjuncomp , and .Dv vjc_ip hooks, respectively. .Sh HOOKS This node type supports the following hooks: .Pp .Bl -tag -width foobarbazi .It Dv ip Upstream (uncompressed) IP packets. .It Dv vjcomp Downstream compressed TCP packets. .It Dv vjuncomp Downstream uncompressed TCP packets. .It Dv vjip Downstream uncompressed IP packets. .El .Sh CONTROL MESSAGES This node type supports the generic control messages, plus the following: .Bl -tag -width foo .It Dv NGM_VJC_SET_CONFIG This command resets the compression state and configures it according to the supplied .Dv "struct ngm_vjc_config" argument. This structure contains the following fields: .Bd -literal -offset 4n struct ngm_vjc_config { u_char enableComp; /* Enable compression */ u_char enableDecomp; /* Enable decompression */ u_char maxChannel; /* Number of outgoing channels - 1 */ u_char compressCID; /* OK to compress outgoing CID's */ }; .Ed .Pp When .Dv enableComp is set to zero, all packets received on the .Dv ip hook are forwarded unchanged out the .Dv vjip hook. Similarly, when .Dv enableDecomp is set to zero, all packets received on the .Dv vjip hook are forwarded unchanged out the .Dv ip hook, and packets are not accepted on the .Dv vjcomp and .Dv vjuncomp hooks. When a node is first created, both compression and decompression are disabled and the node is therefore operating in bi-directional .Dq pass through mode. .Pp When enabling compression, .Dv maxChannel should be set to the number of outgoing compression channels minus one, -and is a value between 3 and 15, inclusive. The +and is a value between 3 and 15, inclusive. +The .Dv compressCID field indicates whether it is OK to compress the CID header field for -outgoing compressed TCP packets. This value should be zero unless +outgoing compressed TCP packets. +This value should be zero unless either (a) it is not possible for an outgoing frame to be lost, or (b) lost frames can be reliably detected and immediately reported to the peer's decompression engine (see .Dv NGM_VJC_RECV_ERROR below). .It Dv NGM_VJC_GET_STATE This command returns the node's current state described by the .Dv "struct slcompress" structure, which is defined in .Pa net/slcompress.h . .It Dv NGM_VJC_CLR_STATS -Clears the node statistics counters. Statistics are also cleared whenever the +Clears the node statistics counters. +Statistics are also cleared whenever the .Dv enableComp or .Dv enableDecomp fields are changed from zero to one by a .Dv NGM_VJC_SET_CONFIG control message. .It Dv NGM_VJC_RECV_ERROR When the peer has CID header field compression enabled, this message must be sent to the local .Nm vjc node immediately after detecting that a received frame has been lost, due to a bad -checksum or for any other reason. Failing to do this can result -in corrupted TCP stream data. +checksum or for any other reason. +Failing to do this can result in corrupted TCP stream data. .El .Sh SHUTDOWN This node shuts down upon receipt of a .Dv NGM_SHUTDOWN control message, or when all hooks have been disconnected. .Sh BUGS -Because the initialization routine in the kernel implementation of +As the initialization routine in the kernel implementation of Van Jacobson compression initializes both compression and decompression at once, this node does not allow compression and decompression to -be enabled in separate operations. In order to enable one when +be enabled in separate operations. +In order to enable one when the other is already enabled, first both must be disabled, then -both enabled. This of course resets the node state. This restriction -may be lifted in a later version. +both enabled. +This of course resets the node state. +This restriction may be lifted in a later version. .Pp When built as a loadable kernel module, this module includes the file .Pa net/slcompress.c . Although loading the module should fail if .Pa net/slcompress.c already exists in the kernel, currently it does not, and the duplicate copies of the file do not interfere. However, this may change in the future. .Sh SEE ALSO .Xr netgraph 4 , .Xr ng_iface 4 , .Xr ng_ppp 4 , .Xr ngctl 8 .Rs .%A V. Jacobson .%T "Compressing TCP/IP Headers" .%O RFC 1144 .Re .Rs .%A G. McGregor .%T "The PPP Internet Control Protocol (IPCP)" .%O RFC 1332 .Re .Sh HISTORY The .Nm node type was implemented in .Fx 4.0 . .Sh AUTHORS .An Archie Cobbs Aq archie@FreeBSD.org Index: head/share/man/man4/pass.4 =================================================================== --- head/share/man/man4/pass.4 (revision 117010) +++ head/share/man/man4/pass.4 (revision 117011) @@ -1,113 +1,119 @@ .\" .\" Copyright (c) 1998, 1999 Kenneth D. Merry. .\" 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 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 10, 1998 .Dt PASS 4 .Os .Sh NAME .Nm pass .Nd CAM application passthrough driver .Sh SYNOPSIS .Cd device pass .Sh DESCRIPTION The .Nm driver provides a way for userland applications to issue CAM CCBs to the kernel. .Pp Since the .Nm driver allows direct access to the CAM subsystem, system administrators -should exercise caution when granting access to this driver. If used +should exercise caution when granting access to this driver. +If used improperly, this driver can allow userland applications to crash a machine or cause data loss. .Pp The .Nm driver attaches to every .Tn SCSI device found in the system. Since it attaches to every device, it provides a generic means of accessing .Tn SCSI devices, and allows the user to access devices which have no "standard" peripheral driver associated with them. .Sh KERNEL CONFIGURATION It is only necessary to configure one .Nm device in the kernel; .Nm devices are automatically allocated as .Tn SCSI devices are found. .Sh IOCTLS .Bl -tag -width 012345678901234 .It CAMIOCOMMAND This ioctl takes most kinds of CAM CCBs and passes them through to the CAM -transport layer for action. Note that some CCB types are not allowed +transport layer for action. +Note that some CCB types are not allowed through the passthrough device, and must be sent through the .Xr xpt 4 -device instead. Some examples of xpt-only CCBs are XPT_SCAN_BUS, +device instead. +Some examples of xpt-only CCBs are XPT_SCAN_BUS, XPT_DEV_MATCH, XPT_RESET_BUS, XPT_SCAN_LUN, XPT_ENG_INQ, and XPT_ENG_EXEC. These CCB types have various attributes that make it illogical or impossible to service them through the passthrough interface. .It CAMGETPASSTHRU This ioctl takes an XPT_GDEVLIST CCB, and returns the passthrough device -corresponding to the device in question. Although this ioctl is available -through the +corresponding to the device in question. +Although this ioctl is available through the .Nm driver, it is of limited use, since the caller must already know that the device in question is a passthrough device if they're issuing this -ioctl. It is probably more useful to issue this ioctl through the +ioctl. +It is probably more useful to issue this ioctl through the .Xr xpt 4 device. .El .Sh FILES .Bl -tag -width /dev/passn -compact .It Pa /dev/pass Ns Ar n Character device nodes for the .Nm -driver. There should be one of these for each device accessed through the +driver. +There should be one of these for each device accessed through the CAM subsystem. .El .Sh DIAGNOSTICS None. .Sh SEE ALSO .Xr cam 3 , .Xr cam_cdbparse 3 , .Xr xpt 4 , .Xr camcontrol 8 .Sh HISTORY The CAM passthrough driver first appeared in .Fx 3.0 . .Sh AUTHORS .An Kenneth Merry Aq ken@FreeBSD.org .Sh BUGS It might be nice to have a way to asynchronously send CCBs through the -passthrough driver. This would probably require some sort of read/write +passthrough driver. +This would probably require some sort of read/write interface or an asynchronous ioctl interface. Index: head/share/man/man4/pci.4 =================================================================== --- head/share/man/man4/pci.4 (revision 117010) +++ head/share/man/man4/pci.4 (revision 117011) @@ -1,304 +1,318 @@ .\" .\" Copyright (c) 1999 Kenneth D. Merry. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd October 24, 1999 .Dt PCI 4 .Os .Sh NAME .Nm pci .Nd generic PCI driver .Sh SYNOPSIS .Cd device pci .Sh DESCRIPTION The .Nm driver provides a way for userland programs to read and write .Tn PCI -configuration registers. It also provides a way for userland programs to -get a list of all +configuration registers. +It also provides a way for userland programs to get a list of all .Tn PCI devices, or all .Tn PCI devices that match various patterns. .Pp Since the .Nm driver provides a write interface for .Tn PCI configuration registers, system administrators should exercise caution when granting access to the .Nm -device. If used improperly, this driver can allow userland applications to +device. +If used improperly, this driver can allow userland applications to crash a machine or cause data loss. .Sh KERNEL CONFIGURATION It is only necessary to specify one .Nm -controller in the kernel. Additional +controller in the kernel. +Additional .Tn PCI busses are handled automatically as they are encountered. .Sh IOCTLS The following .Xr ioctl 2 calls are supported by the .Nm -driver. They are defined in the header file +driver. +They are defined in the header file .Aq Pa sys/pciio.h . .Bl -tag -width 012345678901234 .Pp .It PCIOCGETCONF This .Xr ioctl 2 takes a .Va pci_conf_io -structure. It allows the user to retrieve information on all +structure. +It allows the user to retrieve information on all .Tn PCI devices in the system, or on .Tn PCI devices matching patterns supplied by the user. The call may set .Va errno to any value specified in either .Xr copyin 9 or .Xr copyout 9 . The .Va pci_conf_io structure consists of a number of fields: .Bl -tag -width match_buf_len .It pat_buf_len The length, in bytes, of the buffer filled with user-supplied patterns. .It num_patterns The number of user-supplied patterns. .It patterns Pointer to a buffer filled with user-supplied patterns. .Va patterns is a pointer to .Va num_patterns .Va pci_match_conf structures. The .Va pci_match_conf structure consists of the following elements: .Bl -tag -width pd_vendor .It pc_sel .Tn PCI bus, slot and function. .It pd_name .Tn PCI device driver name. .It pd_unit .Tn PCI device driver unit number. .It pc_vendor .Tn PCI vendor ID. .It pc_device .Tn PCI device ID. .It pc_class .Tn PCI device class. .It flags The flags describe which of the fields the kernel should match against. -A device must match all specified fields in order to be returned. The -match flags are enumerated in the +A device must match all specified fields in order to be returned. +The match flags are enumerated in the .Va pci_getconf_flags structure. Hopefully the flag values are obvious enough that they don't need to described in detail. .El .It match_buf_len Length of the .Va matches buffer allocated by the user to hold the results of the .Dv PCIOCGETCONF query. .It num_matches Number of matches returned by the kernel. .It matches -Buffer containing matching devices returned by the kernel. The items in -this buffer are of type +Buffer containing matching devices returned by the kernel. +The items in this buffer are of type .Va pci_conf , which consists of the following items: .Bl -tag -width pc_subvendor .It pc_sel .Tn PCI bus, slot and function. .It pc_hdr .Tn PCI header type. .It pc_subvendor .Tn PCI subvendor ID. .It pc_subdevice .Tn PCI subdevice ID. .It pc_vendor .Tn PCI vendor ID. .It pc_device .Tn PCI device ID. .It pc_class .Tn PCI device class. .It pc_subclass .Tn PCI device subclass. .It pc_progif .Tn PCI device programming interface. .It pc_revid .Tn PCI revision ID. .It pd_name Driver name. .It pd_unit Driver unit number. .El .It offset The offset is passed in by the user to tell the kernel where it should -start traversing the device list. The value passed out by the kernel -points to the record immediately after the last one returned. The user may +start traversing the device list. +The value passed out by the kernel +points to the record immediately after the last one returned. +The user may pass the value returned by the kernel in subsequent calls to the .Dv PCIOCGETCONF -ioctl. If the user does not intend to use the offset, it must be set to -zero. +ioctl. +If the user does not intend to use the offset, it must be set to zero. .It generation .Tn PCI -configuration generation. This value only needs to be set if the offset is -set. The kernel will compare the current generation number of its internal +configuration generation. +This value only needs to be set if the offset is set. +The kernel will compare the current generation number of its internal device list to the generation passed in by the user to determine whether its device list has changed since the user last called the .Dv PCIOCGETCONF -ioctl. If the device list has changed, a status of +ioctl. +If the device list has changed, a status of .Va PCI_GETCONF_LIST_CHANGED will be passed back. .It status The status tells the user the disposition of his request for a device list. The possible status values are: .Bl -ohang .It PCI_GETCONF_LAST_DEVICE This means that there are no more devices in the PCI device list after the ones returned in the .Va matches buffer. .It PCI_GETCONF_LIST_CHANGED This status tells the user that the .Tn PCI device list has changed since his last call to the .Dv PCIOCGETCONF ioctl and he must reset the .Va offset and .Va generation to zero to start over at the beginning of the list. .It PCI_GETCONF_MORE_DEVS This tells the user that his buffer was not large enough to hold all of the -remaining devices in the device list that possibly match his criteria. It -is possible for this status to be returned, even when none of the remaining +remaining devices in the device list that possibly match his criteria. +It is possible for this status to be returned, even when none of the remaining devices in the list would match the user's criteria. .It PCI_GETCONF_ERROR -This indicates a general error while servicing the user's request. If the +This indicates a general error while servicing the user's request. +If the .Va pat_buf_len is not equal to .Va num_patterns times -.Va sizeof(struct pci_match_conf) , errno -will be set to EINVAL. +.Fn sizeof "struct pci_match_conf" , +.Va errno +will be set to +.Er EINVAL . .El .El .It PCIOCREAD This .Xr ioctl 2 reads the .Tn PCI configuration registers specified by the passed-in .Va pci_io structure. The .Va pci_io structure consists of the following fields: .Bl -tag -width pi_width .It pi_sel A .Va pcisel structure which specifies the bus, slot and function the user would like to query. If the specific bus is not found, errno will be set to ENODEV and -1 returned from the ioctl. .It pi_reg The .Tn PCI configuration register the user would like to access. .It pi_width -The width, in bytes, of the data the user would like to read. This value +The width, in bytes, of the data the user would like to read. +This value may be either 1, 2, or 4. 3-byte reads and reads larger than 4 bytes are not supported. If an invalid width is passed, errno will be set to EINVAL. .It pi_data The data returned by the kernel. .El .It PCIOCWRITE This .Xr ioctl 2 allows users to write to the .Tn PCI specified in the passed-in .Va pci_io structure. The .Va pci_io -structure is described above. The limitations on data width described for +structure is described above. +The limitations on data width described for reading registers, above, also apply to writing .Tn PCI configuration registers. .El .Sh FILES .Bl -tag -width /dev/pci -compact .It Pa /dev/pci Character device for the .Nm driver. .El .Sh DIAGNOSTICS None. .Sh SEE ALSO .Xr pciconf 8 .Sh HISTORY The .Nm driver (not the kernel's .Tn PCI support code) first appeared in .Fx 2.2 , and was written by Stefan Esser and Garrett Wollman. Support for device listing and matching was re-implemented by Kenneth Merry, and first appeared in .Fx 3.0 . .Sh AUTHORS .An Kenneth Merry Aq ken@FreeBSD.org .Sh BUGS It isn't possible for users to specify an accurate offset into the device list without calling the .Dv PCIOCGETCONF at least once, since they have no way of knowing the current generation -number otherwise. This probably isn't a serious problem, though, since +number otherwise. +This probably isn't a serious problem, though, since users can easily narrow their search by specifying a pattern or patterns for the kernel to match against. Index: head/share/man/man4/pcm.4 =================================================================== --- head/share/man/man4/pcm.4 (revision 117010) +++ head/share/man/man4/pcm.4 (revision 117011) @@ -1,181 +1,183 @@ .\" .\" Copyright (c) 1998, Luigi Rizzo .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd June 3, 1998 .Dt PCM 4 .Os .Sh NAME .Nm pcm , .Nm snd .Nd FreeBSD PCM audio device driver .Sh SYNOPSIS For a card with bridge driver support, and a PnP card: .Cd "device pcm" .Pp For a card without bridge driver support, and a non-PnP card, the following lines may be required in .Pa /boot/device.hints : .Cd hint.pcm.0.at="isa" .Cd hint.pcm.0.irq="5" .Cd hint.pcm.0.drq="1" .Cd hint.pcm.0.flags="0x0" .Sh DESCRIPTION The .Nm driver provides support for PCM audio play and capture. This driver also supports various PCI and WSS/MSS compatible ISA sound cards, and AC97 mixer. True full duplex operation is available on most cards. .Pp If your sound card is supported by a bridge driver, .Nm driver works in conjunction with the bridge driver. .Pp Apart from the usual parameters, the flags field is used to specify the secondary DMA channel (generally used for capture in full duplex cards). Flags are set to 0 for cards not using a secondary DMA channel, or to 0x10 + C to specify channel C. .Pp The driver works best with WSS/MSS cards, which have a very clean architecture and an orthogonal set of features. They also happen to be among the cheapest audio cards on the market. .Pp The driver does its best to recognize the installed hardware and drive it correctly, so that you don't have to give too many details in .Pa /boot/device.hints . For PCI and ISA PnP cards this is actually easy since they identify themselves. For legacy ISA cards, the driver looks for MSS cards at addresses 0x530 and 0x604 (obviously, unless overridden in .Pa /boot/device.hints ) . .Sh IOCTL The driver supports most of the Voxware ioctls(), and most applications work unmodified (including popular mpeg players and linux binaries). A few differences exist (the most important one is the ability to use memory-mapped access to the audio buffers). As a consequence, some applications may need to be recompiled with a slightly modified -audio module. See /usr/include/sys/soundcard.h for a complete -list of the supported ioctls. +audio module. +See +.Aq Pa sys/soundcard.h +for a complete list of the supported ioctls. .Sh SUPPORTED CARDS Below we include a list of supported codecs/cards. If your sound card is not listed here, it may be supported by a bridge driver. .Bl -tag -width 2m .It CS4237, CS4236, CS4232, CS4231 (ISA) All these cards work perfectly in full duplex using the MSS mode. This chipset is used, among others, on the A/Open AW35 and AW32, on some Intel motherboards, and (the CS4231) on some non-PnP cards. .Pp The CS4232 is reported as buggy in the Voxware documentation but I am not sure if this is true. On one of my Intel motherboards, capture does not work simply because the capture DMA channel is not wired to the ISA DMA controller. .It Yamaha OPL-SAx (ISA) Works perfectly in all modes. This chip is used in several PnP cards, but also (in non-PnP mode) on motherboards and laptops (e.g. the Toshiba Libretto). .It OPTi931 (ISA) The chip is buggy, but the driver has many workarounds to make it work in full duplex because for some time these were the only full duplex cards I could find. u-law formats uses U8 format internally because of a bug in the chip. .It Trident 4DWave DX/NX (PCI) .It ENSONIQ AudioPCI ES1370/1371 (PCI) Creative Labs SoundBlaster PCI is supported as well. .It ESS Solo-1/1E (PCI) .It NeoMagic 256AV/ZX (PCI) .El .Sh FILES The following commonly used symbolic links to real device nodes should be present: .Pp .Bl -tag -width /dev/sequencer -compact .It Pa /dev/audio Sparc-compatible audio device .It Pa /dev/dsp Digitized voice device .It Pa /dev/dspW Like .Pa /dev/dsp , but 16 bits per sample .It Pa /dev/midi Raw midi access device .It Pa /dev/mixer Control port mixer device .It Pa /dev/music Level 2 sequencer interface .It Pa /dev/sequencer Sequencer device .It Pa /dev/pss Programmable device interface .El .Pp Each symbolic link refers to a device node of the same name, but with a unit number appended. The unit number for each device matches the unit number of the device probed at boot time. Device probe messages can be examined with the .Xr dmesg 8 utility. .Sh DIAGNOSTICS AND TROUBLESHOOTING .Bl -tag -width 2m .It ac97: dac not ready AC97 codec is not likely to be accompanied with the sound card. .It unsupported subdevice XX A device node is not created properly. .El .Sh BUGS Some features of your cards (e.g. global volume control) might not be supported on all devices. .Sh HISTORY The .Nm device driver first appeared in .Fx 2.2.6 , rewritten in .Fx 4.0 . .Sh SEE ALSO .Xr csa 4 , .Xr gusc 4 , .Xr sbc 4 , .Xr devfs 5 .Sh AUTHORS .An Luigi Rizzo Aq luigi@iet.unipi.it initially wrote the .Nm device driver and this manual page. .An Cameron Grant Aq gandalf@vilnya.demon.co.uk totally revised the device driver. .An Seigo Tanimura Aq tanimura@r.dl.itc.u-tokyo.ac.jp revised this manual page. Index: head/share/man/man4/polling.4 =================================================================== --- head/share/man/man4/polling.4 (revision 117010) +++ head/share/man/man4/polling.4 (revision 117011) @@ -1,114 +1,114 @@ .\" .\" $FreeBSD$ .\" .Dd February 15, 2002 .Dt POLLING 4 .Os .Sh NAME .Nm polling .Nd device polling support .Sh SYNOPSIS .Cd "options DEVICE_POLLING" .Cd "options HZ=1000" .Sh DESCRIPTION .Dq "Device polling" (polling for brevity) refers to a technique to handle devices that does not rely on the latter to generate interrupts when they need attention, but rather lets the CPU poll devices to service their needs. This might seem inefficient and counterintuitive, but when done properly, .Nm gives more control to the operating system on when and how to handle devices, with a number of advantages in terms of system responsivity and performance. .Pp In particular, .Nm reduces the overhead for context switches which is incurred when servicing interrupts, and gives more control on the scheduling of the CPU between various tasks (user processes, software interrupts, device handling) which ultimately reduces the chances of livelock in the system. .Sh PRINCIPLES OF OPERATION In the normal, interrupt-based mode, devices generate an interrupt whenever they need attention. This in turn causes a context switch and the execution of an interrupt handler which performs whatever processing is needed by the device. The duration of the interrupt handler is potentially unbounded unless the device driver has been programmed with real-time concerns in mind (which is generally not the case for .Fx drivers). Furthermore, under heavy traffic, the system might be persistently processing interrupts without being able to complete other work, either in the kernel or in userland. .Pp .Nm Polling disables interrupts by polling devices at appropriate times, i.e., on clock interrupts, system calls and within the idle loop. This way, the context switch overhead is removed. Furthermore, the operating system can control accurately how much work to spend in handling device events, and thus prevent livelock by reserving some amount of CPU to other tasks. .Pp .Nm Polling is enabled with a .Xr sysctl 8 variable .Va kern.polling.enable whereas the percentage of CPU cycles reserved to userland processes is controlled by the .Xr sysctl 8 variable .Va kern.polling.user_frac whose range is 0 to 100 (50 is the default value). .Pp When .Nm is enabled, and provided that there is work to do, up to .Va kern.polling.user_frac percent of the CPU cycles is reserved to userland tasks, the remaining fraction being available for device processing. .Pp Enabling .Nm also changes the way network software interrupts are scheduled, so there is never the risk of livelock because packets are not processed to completion. .Pp There are other variables which control or monitor the behaviour of devices operating in polling mode, but they are unlikely to require modifications, and are documented in the source file .Pa sys/kern/kern_poll.c . .Sh SUPPORTED DEVICES .Nm Polling requires explicit modifications to the device drivers. As of this writing, the .Xr dc 4 , .Xr em 4 , .Xr fxp 4 , .Xr rl 4 , and .Xr sis 4 devices are supported, with other in the works. The modifications are rather straightforward, consisting in the extraction of the inner part of the interrupt service routine and writing a callback function, .Fn *_poll , which is invoked to probe the device for events and process them. See the conditionally compiled sections of the devices mentioned above for more details. .Pp -Because in the worst case devices are only polled on +As in the worst case devices are only polled on clock interrupts, in order to reduce the latency in processing packets, it is advisable to increase the frequency of the clock to at least 1000 HZ. .Sh HISTORY Device polling was introduced in February 2002 by .An Luigi Rizzo Aq luigi@iet.unipi.it . Index: head/share/man/man4/ppi.4 =================================================================== --- head/share/man/man4/ppi.4 (revision 117010) +++ head/share/man/man4/ppi.4 (revision 117011) @@ -1,106 +1,107 @@ .\" Copyright (c) 1997 .\" Michael Smith .\" .\" 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 2, 1998 .Dt PPI 4 .Os .Sh NAME .Nm ppi .Nd "user-space interface to ppbus parallel 'geek' port" .Sh SYNOPSIS .Cd "device ppi" .Pp Minor numbering: Unit numbers correspond directly to ppbus numbers. .Sh DESCRIPTION The .Nm driver provides a convenient means for user applications to manipulate the state of the parallel port, enabling easy low-speed I/O operations without the security problems inherent with the use of the .Pa /dev/io interface. .Sh PROGRAMMING INTERFACE .In dev/ppbus/ppi.h .In dev/ppbus/ppbconf.h .Pp All I/O on the .Nm interface is performed using .Fn ioctl -calls. Each command takes a single +calls. +Each command takes a single .Ft u_int8_t -argument, transferring one byte of data. The following commands are -available: +argument, transferring one byte of data. +The following commands are available: .Bl -tag -width indent .It Dv PPIGDATA , PPISDATA Get and set the contents of the data register. .It Dv PPIGSTATUS , PPISSTATUS Get and set the contents of the status register. .It Dv PPIGCTRL , PPISCTRL Get and set the contents of the control register. -The following defines correspond to bits in this register. Setting -a bit in the control register drives the corresponding output low. +The following defines correspond to bits in this register. +Setting a bit in the control register drives the corresponding output low. .Bl -tag -width indent -compact .It Dv STROBE .It Dv AUTOFEED .It Dv nINIT .It Dv SELECTIN .It Dv PCD .El .It Dv PPIGEPP , PPISEPP Get and set the contents of the EPP control register. .It Dv PPIGECR , PPISECR Get and set the contents of the ECP control register. .It Dv PPIGFIFO , PPISFIFO Read and write the ECP FIFO (8-bit operations only). .El .Sh EXAMPLES To present the value 0x5a to the data port, drive STROBE low and then high again, the following code fragment can be used: .Bd -literal -compact int fd; u_int8_t val; val = 0x5a; ioctl(fd, PPISDATA, &val); ioctl(fd, PPIGCTRL, &val); val |= STROBE; ioctl(fd, PPISCTRL, &val); val &= ~STROBE; ioctl(fd, PPISCTRL, &val); .Ed .Sh BUGS The inverse sense of signals is confusing. .Pp The .Fn ioctl interface is slow, and there is no way (yet) to chain multiple operations together. .Pp The headers required for user applications are not installed as part of the standard system. Index: head/share/man/man4/ppp.4 =================================================================== --- head/share/man/man4/ppp.4 (revision 117010) +++ head/share/man/man4/ppp.4 (revision 117011) @@ -1,83 +1,84 @@ .\" $NetBSD: ppp.4,v 1.1 1996/08/10 21:26:12 explorer Exp $ .\" .\" 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. .\" .\" From: @(#)lo.4 8.1 (Berkeley) 6/5/93 .\" $FreeBSD$ .\" .Dd August 10, 1996 .Dt PPP 4 .Os .Sh NAME .Nm ppp .Nd point to point protocol network interface .Sh SYNOPSIS .Cd "device ppp" .Sh DESCRIPTION The .Nm interface allows serial lines to be used as network interfaces using the .Em point-to-point -protocol. The +protocol. +The .Nm interface can use various types of compression and has many features over the .Xr sl 4 protocol. .Pp Each .Nm interface is created at runtime using interface cloning. This is most easily done with the .Xr ifconfig 8 .Cm create command or using the .Va cloned_interfaces variable in .Xr rc.conf 5 . .Sh DIAGNOSTICS .Bl -diag .It ppp%d: af%d not supported. The interface was handed a message with addresses formatted in an unsuitable address family; the packet was dropped. .El .Sh SEE ALSO .Xr inet 4 , .Xr intro 4 , .Xr sl 4 , .Xr pppd 8 , .Xr pppstats 8 .Sh BUGS Currently, only the .Xr ip 4 protocol is supported. Index: head/share/man/man4/psm.4 =================================================================== --- head/share/man/man4/psm.4 (revision 117010) +++ head/share/man/man4/psm.4 (revision 117011) @@ -1,827 +1,828 @@ .\" .\" Copyright (c) 1997 .\" 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 April 1, 2000 .Dt PSM 4 .Os .Sh NAME .Nm psm .Nd PS/2 mouse style pointing device driver .Sh SYNOPSIS .Cd "options KBD_RESETDELAY=N" .Cd "options KBD_MAXWAIT=N" .Cd "options PSM_DEBUG=N" .Cd "options KBDIO_DEBUG=N" .Cd "device psm" .Pp In .Pa /boot/device.hints : .Cd hint.psm.0.at="atkbdc" .Cd hint.psm.0.irq="12" .Sh DESCRIPTION The .Nm driver provides support for the PS/2 mouse style pointing device. Currently there can be only one .Nm device node in the system. As the PS/2 mouse port is located at the auxiliary port of the keyboard controller, the keyboard controller driver, .Nm atkbdc , must also be configured in the kernel. Note that there is currently no provision of changing the .Em irq number. .Pp Basic PS/2 style pointing device has two or three buttons. Some devices may have a roller or a wheel and/or additional buttons. .Ss Device Resolution The PS/2 style pointing device usually has several grades of resolution, that is, sensitivity of movement. They are typically 25, 50, 100 and 200 pulse per inch. Some devices may have finer resolution. The current resolution can be changed at runtime. The .Nm driver allows the user to initially set the resolution via the driver flag (see .Sx "DRIVER CONFIGURATION" ) or change it later via the .Xr ioctl 2 command .Dv MOUSE_SETMODE (see .Sx IOCTLS ) . .Ss Report Rate Frequency, or report rate, at which the device sends movement and button state reports to the host system is also configurable. The PS/2 style pointing device typically supports 10, 20, 40, 60, 80, 100 and 200 reports per second. 60 or 100 appears to be the default value for many devices. Note that when there is no movement and no button has changed its state, the device won't send anything to the host system. The report rate can be changed via an ioctl call. .Ss Operation Levels The .Nm driver has three levels of operation. The current operation level can be set via an ioctl call. .Pp At the level zero the basic support is provided; the device driver will report horizontal and vertical movement of the attached device and state of up to three buttons. The movement and status are encoded in a series of fixed-length data packets (see .Sx "Data Packet Format" ) . This is the default level of operation and the driver is initially at this level when opened by the user program. .Pp The operation level one, the `extended' level, supports a roller (or wheel), if any, and up to 11 buttons. The movement of the roller is reported as movement along the Z axis. 8 byte data packets are sent to the user program at this level. .Pp At the operation level two, data from the pointing device is passed to the user program as is. Modern PS/2 type pointing devices often use proprietary data format. Therefore, the user program is expected to have intimate knowledge about the format from a particular device when operating the driver at this level. This level is called `native' level. .Ss Data Packet Format Data packets read from the .Nm driver are formatted differently at each operation level. .Pp A data packet from the PS/2 mouse style pointing device is three bytes long at the operation level zero: .Pp .Bl -tag -width Byte_1 -compact .It Byte 1 .Bl -tag -width bit_7 -compact .It bit 7 One indicates overflow in the vertical movement count. .It bit 6 One indicates overflow in the horizontal movement count. .It bit 5 Set if the vertical movement count is negative. .It bit 4 Set if the horizontal movement count is negative. .It bit 3 Always one. .\" The ALPS GlidePoint clears this bit when the user `taps' the surface of .\" the pad, otherwise the bit is set. .\" Most, if not all, other devices always set this bit. .It bit 2 Middle button status; set if pressed. For devices without the middle button, this bit is always zero. .It bit 1 Right button status; set if pressed. .It bit 0 Left button status; set if pressed. .El .It Byte 2 Horizontal movement count in two's complement; -256 through 255. Note that the sign bit is in the first byte. .It Byte 3 Vertical movement count in two's complement; -256 through 255. Note that the sign bit is in the first byte. .El .Pp At the level one, a data packet is encoded in the standard format .Dv MOUSE_PROTO_SYSMOUSE as defined in .Xr mouse 4 . .Pp At the level two, native level, there is no standard on the size and format of the data packet. .Ss Acceleration The .Nm driver can somewhat `accelerate' the movement of the pointing device. The faster you move the device, the further the pointer travels on the screen. The driver has an internal variable which governs the effect of the acceleration. Its value can be modified via the driver flag or via an ioctl call. .Ss Device Number The minor device number of the .Nm is made up of: .Bd -literal -offset indent minor = (`unit' << 1) | `non-blocking' .Ed .Pp where `unit' is the device number (usually 0) and the `non-blocking' bit is set to indicate ``don't block waiting for mouse input, return immediately''. The `non-blocking' bit should be set for \fIXFree86\fP, therefore the minor device number usually used for \fIXFree86\fP is 1. See .Sx FILES for device node names. .Sh DRIVER CONFIGURATION .Ss Kernel Configuration Options There are following kernel configuration options to control the .Nm driver. They may be set in the kernel configuration file (see .Xr config 8 ) . .Bl -tag -width MOUSE .It Em KBD_RESETDELAY=X , KBD_MAXWAIT=Y The .Nm driver will attempt to reset the pointing device during the boot process. It sometimes takes a long while before the device will respond after reset. These options control how long the driver should wait before it eventually gives up waiting. The driver will wait .Fa X * .Fa Y msecs at most. If the driver seems unable to detect your pointing device, you may want to increase these values. The default values are 200 msec for .Fa X and 5 for .Fa Y . .It Em PSM_DEBUG=N , KBDIO_DEBUG=N Sets the debug level to .Fa N . The default debug level is zero. See .Sx DIAGNOSTICS for debug logging. .El .Ss Driver Flags The .Nm driver accepts the following driver flags. Set them in .Pa /boot/device.hints (see .Sx EXAMPLES below). .Pp .Bl -tag -width MOUSE .It bit 0..3 RESOLUTION This flag specifies the resolution of the pointing device. It must be zero through four. The greater the value is, the finer resolution the device will select. Actual resolution selected by this field varies according to the model of the device. Typical resolutions are: .Pp .Bl -tag -width 0_(medium_high)__ -compact .It Em 1 (low) 25 pulse per inch (ppi) .It Em 2 (medium low) 50 ppi .It Em 3 (medium high) 100 ppi .It Em 4 (high) 200 ppi .El .Pp Leaving this flag zero will selects the default resolution for the device (whatever it is). .It bit 4..7 ACCELERATION This flag controls the amount of acceleration effect. The smaller the value of this flag is, more sensitive the movement becomes. The minimum value allowed, thus the value for the most sensitive setting, is one. Setting this flag to zero will completely disables the acceleration effect. .It bit 8 NOCHECKSYNC The .Nm driver tries to detect the first byte of the data packet by checking the bit pattern of that byte. Although this method should work with most PS/2 pointing devices, it may interfere with some devices which are not so compatible with known devices. If you think your pointing device is not functioning as expected, and the kernel frequently prints the following message to the console, .Bd -literal -offset indent psmintr: out of sync (xxxx != yyyy). .Ed .Pp set this flag to disable synchronization check and see if it helps. .It bit 9 NOIDPROBE The .Nm driver will not try to identify the model of the pointing device and will not carry out model-specific initialization. The device should always act like a standard PS/2 mouse without such initialization. Extra features, such as wheels and additional buttons, won't be recognized by the .Nm driver. .It bit 10 NORESET When this flag is set, the .Nm driver won't reset the pointing device when initializing the device. If the .Fx kernel is started after another OS has run, the pointing device will inherit settings from the previous OS. However, because there is no way for the .Nm driver to know the settings, the device and the driver may not work correctly. The flag should never be necessary under normal circumstances. .It bit 11 FORCETAP Some pad devices report as if the fourth button is pressed when the user `taps' the surface of the device (see .Sx CAVEATS ) . This flag will make the .Nm driver assume that the device behaves this way. Without the flag, the driver will assume this behavior for ALPS GlidePoint models only. .It bit 12 IGNOREPORTERROR This flag makes .Nm driver ignore certain error conditions when probing the PS/2 mouse port. It should never be necessary under normal circumstances. .It bit 13 HOOKRESUME The built-in PS/2 pointing device of some laptop computers is somehow not operable immediately after the system `resumes' from the power saving mode, though it will eventually become available. There are reports that stimulating the device by performing I/O will help waking up the device quickly. This flag will enable a piece of code in the .Nm driver to hook the `resume' event and exercise some harmless I/O operations on the device. .It bit 14 INITAFTERSUSPEND This flag adds more drastic action for the above problem. It will cause the .Nm driver to reset and re-initialize the pointing device after the `resume' event. It has no effect unless the .Em HOOKRESUME flag is set as well. .El .Sh IOCTLS There are a few .Xr ioctl 2 commands for mouse drivers. These commands and related structures and constants are defined in .Ao Pa sys/mouse.h Ac . General description of the commands is given in .Xr mouse 4 . This section explains the features specific to the .Nm driver. .Pp .Bl -tag -width MOUSE -compact .It Dv MOUSE_GETLEVEL Ar int *level .It Dv MOUSE_SETLEVEL Ar int *level These commands manipulate the operation level of the .Nm driver. .Pp .It Dv MOUSE_GETHWINFO Ar mousehw_t *hw Returns the hardware information of the attached device in the following structure. .Bd -literal typedef struct mousehw { int buttons; /* number of buttons */ int iftype; /* I/F type */ int type; /* mouse/track ball/pad... */ int model; /* I/F dependent model ID */ int hwid; /* I/F dependent hardware ID */ } mousehw_t; .Ed .Pp The .Dv buttons field holds the number of buttons on the device. The .Nm driver currently can detect the 3 button mouse from Logitech and report accordingly. The 3 button mouse from the other manufacturer may or may not be reported correctly. However, it will not affect the operation of the driver. .Pp The .Dv iftype is always .Dv MOUSE_IF_PS2 . .Pp The .Dv type tells the device type: .Dv MOUSE_MOUSE , .Dv MOUSE_TRACKBALL , .Dv MOUSE_STICK , .Dv MOUSE_PAD , or .Dv MOUSE_UNKNOWN . The user should not heavily rely on this field, as the driver may not always, in fact it is very rarely able to, identify the device type. .Pp The .Dv model is always .Dv MOUSE_MODEL_GENERIC at the operation level 0. It may be .Dv MOUSE_MODEL_GENERIC or one of .Dv MOUSE_MODEL_XXX constants at higher operation levels. Again the .Nm driver may or may not set an appropriate value in this field. .Pp The .Dv hwid is the ID value returned by the device. Known IDs include: .Pp .Bl -tag -width 0__ -compact .It Em 0 Mouse (Microsoft, Logitech and many other manufacturers) .It Em 2 Microsoft Ballpoint mouse .It Em 3 Microsoft IntelliMouse .El .Pp .It Dv MOUSE_GETMODE Ar mousemode_t *mode The command gets the current operation parameters of the mouse driver. .Bd -literal typedef struct mousemode { int protocol; /* MOUSE_PROTO_XXX */ int rate; /* report rate (per sec), -1 if unknown */ int resolution; /* MOUSE_RES_XXX, -1 if unknown */ int accelfactor; /* acceleration factor */ int level; /* driver operation level */ int packetsize; /* the length of the data packet */ unsigned char syncmask[2]; /* sync. bits */ } mousemode_t; .Ed .Pp The .Dv protocol is .Dv MOUSE_PROTO_PS2 at the operation level zero and two. .Dv MOUSE_PROTO_SYSMOUSE at the operation level one. .Pp The .Dv rate is the status report rate (reports/sec) at which the device will send movement report to the host computer. Typical supported values are 10, 20, 40, 60, 80, 100 and 200. Some mice may accept other arbitrary values too. .Pp The .Dv resolution of the pointing device must be one of .Dv MOUSE_RES_XXX constants or a positive value. The greater the value is, the finer resolution the mouse will select. Actual resolution selected by the .Dv MOUSE_RES_XXX constant varies according to the model of mouse. Typical resolutions are: .Pp .Bl -tag -width MOUSE_RES_MEDIUMHIGH__ -compact .It Dv MOUSE_RES_LOW 25 ppi .It Dv MOUSE_RES_MEDIUMLOW 50 ppi .It Dv MOUSE_RES_MEDIUMHIGH 100 ppi .It Dv MOUSE_RES_HIGH 200 ppi .El .Pp The .Dv accelfactor field holds a value to control acceleration feature (see .Sx Acceleration ) . -It must be zero or greater. If it is zero, acceleration is disabled. +It must be zero or greater. +If it is zero, acceleration is disabled. .Pp The .Dv packetsize field specifies the length of the data packet. It depends on the operation level and the model of the pointing device. .Pp .Bl -tag -width level_0__ -compact .It Em level 0 3 bytes .It Em level 1 8 bytes .It Em level 2 Depends on the model of the device .El .Pp The array .Dv syncmask holds a bit mask and pattern to detect the first byte of the data packet. .Dv syncmask[0] is the bit mask to be ANDed with a byte. If the result is equal to .Dv syncmask[1] , the byte is likely to be the first byte of the data packet. Note that this detection method is not 100% reliable, thus, should be taken only as an advisory measure. .Pp .It Dv MOUSE_SETMODE Ar mousemode_t *mode The command changes the current operation parameters of the mouse driver as specified in .Ar mode . Only .Dv rate , .Dv resolution , .Dv level and .Dv accelfactor may be modifiable. Setting values in the other field does not generate error and has no effect. .Pp If you do not want to change the current setting of a field, put -1 there. You may also put zero in .Dv resolution and .Dv rate , and the default value for the fields will be selected. .\" .Pp .\" .It Dv MOUSE_GETVARS Ar mousevar_t *vars .\" .It Dv MOUSE_SETVARS Ar mousevar_t *vars .\" These commands are not supported by the .\" .Nm .\" driver. .Pp .It Dv MOUSE_READDATA Ar mousedata_t *data .\" The command reads the raw data from the device. .\" .Bd -literal .\" typedef struct mousedata { .\" int len; /* # of data in the buffer */ .\" int buf[16]; /* data buffer */ .\" } mousedata_t; .\" .Ed .\" .Pp .\" Upon returning to the user program, the driver will place the number .\" of valid data bytes in the buffer in the .\" .Dv len .\" field. .\" .Pp .It Dv MOUSE_READSTATE Ar mousedata_t *state .\" The command reads the hardware settings from the device. .\" Upon returning to the user program, the driver will place the number .\" of valid data bytes in the buffer in the .\" .Dv len .\" field. It is usually 3 bytes. .\" The buffer is formatted as follows: .\" .Pp .\" .Bl -tag -width Byte_1 -compact .\" .It Byte 1 .\" .Bl -tag -width bit_6 -compact .\" .It bit 7 .\" Reserved. .\" .It bit 6 .\" 0 - stream mode, 1 - remote mode. .\" In the stream mode, the pointing device sends the device status .\" whenever its state changes. In the remote mode, the host computer .\" must request the status to be sent. .\" The .\" .Nm .\" driver puts the device in the stream mode. .\" .It bit 5 .\" Set if the pointing device is currently enabled. Otherwise zero. .\" .It bit 4 .\" 0 - 1:1 scaling, 1 - 2:1 scaling. .\" 1:1 scaling is the default. .\" .It bit 3 .\" Reserved. .\" .It bit 2 .\" Left button status; set if pressed. .\" .It bit 1 .\" Middle button status; set if pressed. .\" .It bit 0 .\" Right button status; set if pressed. .\" .El .\" .It Byte 2 .\" .Bl -tag -width bit_6_0 -compact .\" .It bit 7 .\" Reserved. .\" .It bit 6..0 .\" Resolution code: zero through three. Actual resolution for .\" the resolution code varies from one device to another. .\" .El .\" .It Byte 3 .\" The status report rate (reports/sec) at which the device will send .\" movement report to the host computer. .\" .El These commands are not currently supported by the .Nm driver. .Pp .It Dv MOUSE_GETSTATUS Ar mousestatus_t *status The command returns the current state of buttons and movement counts as described in .Xr mouse 4 . .El .Sh FILES .Bl -tag -width /dev/npsm0 -compact .It Pa /dev/psm0 `non-blocking' device node .It Pa /dev/bpsm0 `blocking' device node under .Em devfs . .El .Sh EXAMPLES In order to install the .Nm driver, you need to add .Pp .Dl "device atkbdc" .Dl "device psm" .Pp to your kernel configuration file, and put the following lines to .Pa /boot/device.hints . .Pp .Dl hint.atkbdc.0.at="isa" .Dl hint.atkbdc.0.port="0x060" .Dl hint.psm.0.at="atkbdc" .Dl hint.psm.0.irq="12" .Pp If you add the following statement to .Pa /boot/device.hints , .Pp .Dl hint.psm.0.flags="0x2000" .Pp you will add the optional code to stimulate the pointing device after the `resume' event. .Pp .Dl hint.psm.0.flags="0x24" .Pp The above line will set the device resolution high (4) and the acceleration factor to 2. .Sh DIAGNOSTICS At debug level 0, little information is logged except for the following line during boot process: .Bd -literal -offset indent psm0: device ID X .Ed .Pp where .Fa X the device ID code returned by the found pointing device. See .Dv MOUSE_GETINFO for known IDs. .Pp At debug level 1 more information will be logged while the driver probes the auxiliary port (mouse port). Messages are logged with the LOG_KERN facility at the LOG_DEBUG level (see .Xr syslogd 8 ) . .Bd -literal -offset indent psm0: current command byte:xxxx kbdio: TEST_AUX_PORT status:0000 kbdio: RESET_AUX return code:00fa kbdio: RESET_AUX status:00aa kbdio: RESET_AUX ID:0000 [...] psm: status 00 02 64 psm0 irq 12 on isa psm0: model AAAA, device ID X, N buttons psm0: config:00000www, flags:0000uuuu, packet size:M psm0: syncmask:xx, syncbits:yy .Ed .Pp The first line shows the command byte value of the keyboard controller just before the auxiliary port is probed. It usually is 4D, 45, 47 or 65, depending on how the motherboard BIOS initialized the keyboard controller upon power-up. .Pp The second line shows the result of the keyboard controller's test on the auxiliary port interface, with zero indicating no error; note that some controllers report no error even if the port does not exist in the system, however. .Pp The third through fifth lines show the reset status of the pointing device. The functioning device should return the sequence of FA AA . The ID code is described above. .Pp The seventh line shows the current hardware settings. .\" See .\" .Dv MOUSE_READSTATE .\" for definitions. These bytes are formatted as follows: .Pp .Bl -tag -width Byte_1 -compact .It Byte 1 .Bl -tag -width bit_6 -compact .It bit 7 Reserved. .It bit 6 0 - stream mode, 1 - remote mode. In the stream mode, the pointing device sends the device status whenever its state changes. In the remote mode, the host computer must request the status to be sent. The .Nm driver puts the device in the stream mode. .It bit 5 Set if the pointing device is currently enabled. Otherwise zero. .It bit 4 0 - 1:1 scaling, 1 - 2:1 scaling. 1:1 scaling is the default. .It bit 3 Reserved. .It bit 2 Left button status; set if pressed. .It bit 1 Middle button status; set if pressed. .It bit 0 Right button status; set if pressed. .El .It Byte 2 .Bl -tag -width bit_6_0 -compact .It bit 7 Reserved. .It bit 6..0 Resolution code: zero through three. Actual resolution for the resolution code varies from one device to another. .El .It Byte 3 The status report rate (reports/sec) at which the device will send movement report to the host computer. .El .Pp Note that the pointing device will not be enabled until the .Nm driver is opened by the user program. .Pp The rest of the lines show the device ID code, the number of detected buttons and internal variables. .Pp At debug level 2, much more detailed information is logged. .Sh CAVEATS Many pad devices behave as if the first (left) button were pressed if the user `taps' the surface of the pad. In contrast, some pad products, e.g. some versions of ALPS GlidePoint and Interlink VersaPad, treat the tapping action as fourth button events. .Pp It is reported that Interlink VersaPad requires both .Em HOOKRESUME and .Em INITAFTERSUSPEND flags in order to recover from suspended state. These flags are automatically set when VersaPad is detected by the .Nm driver. .Pp Some PS/2 mouse models from MouseSystems require to be put in the high resolution mode to work properly. Use the driver flag to set resolution. .Pp There is not a guaranteed way to re-synchronize with the first byte of the packet once we are out of synchronization with the data stream. However, if you are using the \fIXFree86\fP server and experiencing the problem, you may be able to make the X server synchronize with the mouse by switching away to a virtual terminal and getting back to the X server, unless the X server is accessing the mouse via .Xr moused 8 . Clicking any button without moving the mouse may also work. .Sh BUGS The ioctl command .Dv MOUSEIOCREAD has been removed. It was never functional anyway. .Sh SEE ALSO .Xr ioctl 2 , .Xr syslog 3 , .Xr atkbdc 4 , .Xr mouse 4 , .Xr mse 4 , .Xr sysmouse 4 , .Xr moused 8 , .Xr syslogd 8 .\".Sh HISTORY .Sh AUTHORS .An -nosplit The .Nm driver is based on the work done by quite a number of people, including .An Eric Forsberg , .An Sandi Donno , .An Rick Macklem , .An Andrew Herbert , .An Charles Hannum , .An Shoji Yuen and .An Kazutaka Yokota to name the few. .Pp This manual page was written by .An Kazutaka Yokota Aq yokota@FreeBSD.org . Index: head/share/man/man4/pt.4 =================================================================== --- head/share/man/man4/pt.4 (revision 117010) +++ head/share/man/man4/pt.4 (revision 117011) @@ -1,89 +1,91 @@ .\" Copyright (c) 1995 .\" Peter Dufault, 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 2, 1995 .Dt PT 4 .Os .Sh NAME .Nm pt .Nd SCSI processor type driver .Sh SYNOPSIS .Cd device pt .Sh DESCRIPTION The .Nm driver provides support for a .Tn SCSI -processor type device. These are usually scanners and other -devices using the +processor type device. +These are usually scanners and other devices using the .Tn SCSI link as a communication interface with device specific commands embedded in the data stream. .Pp A .Tn SCSI adapter must be separately configured into the system before this driver can be used. .Pp This device supports .Xr read 2 and .Xr write 2 , and the .Xr ioctl 2 calls described below. .Sh IOCTLS .Bl -tag -width 012345678901234 The following .Xr ioctl 2 calls are supported by the .Nm driver. They are defined in the header file .Aq Pa sys/ptio.h . .Pp .It PTIOCGETTIMEOUT This ioctl allows userland applications to fetch the current .Nm -driver read and write timeout. The value returned is in seconds. +driver read and write timeout. +The value returned is in seconds. .It PTIOCSETTIMEOUT This ioctl allows userland applications to set the current .Nm -driver read and write timeouts. The value should be in seconds. +driver read and write timeouts. +The value should be in seconds. .El .Sh FILES .Bl -tag -width /dev/ptQQQ -compact .It Pa /dev/pt Ns Ar N the .Ar N Ns th processor device. .El .Sh SEE ALSO .Xr scsi 4 .Sh HISTORY The .Nm driver appeared in .Fx 2.1 . Index: head/share/man/man4/pty.4 =================================================================== --- head/share/man/man4/pty.4 (revision 117010) +++ head/share/man/man4/pty.4 (revision 117011) @@ -1,208 +1,210 @@ .\" 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. .\" .\" @(#)pty.4 8.2 (Berkeley) 11/30/93 .\" $FreeBSD$ .\" .Dd November 30, 1993 .Dt PTY 4 .Os .Sh NAME .Nm pty .Nd pseudo terminal driver .Sh SYNOPSIS .Cd "device pty" .Sh DESCRIPTION The .Nm driver provides support for a device-pair termed a .Em pseudo terminal . A pseudo terminal is a pair of character devices, a .Em master device and a .Em slave -device. The slave device provides to a process -an interface identical +device. +The slave device provides to a process an interface identical to that described in .Xr tty 4 . However, whereas all other devices which provide the interface described in .Xr tty 4 have a hardware device of some sort behind them, the slave device has, instead, another process manipulating it through the master half of the pseudo terminal. That is, anything written on the master device is given to the slave device as input and anything written on the slave device is presented as input on the master device. .Pp The following .Xr ioctl 2 calls apply only to pseudo terminals: .Bl -tag -width TIOCREMOTE .It Dv TIOCSTOP Stops output to a terminal (e.g. like typing .Ql ^S ) . Takes no parameter. .It Dv TIOCSTART Restarts output (stopped by .Dv TIOCSTOP or by typing .Ql ^S ) . Takes no parameter. .It Dv TIOCPKT Enable/disable .Em packet -mode. Packet mode is enabled by specifying (by reference) +mode. +Packet mode is enabled by specifying (by reference) a nonzero parameter and disabled by specifying (by reference) -a zero parameter. When applied to the master side of a pseudo -terminal, each subsequent +a zero parameter. +When applied to the master side of a pseudo terminal, each subsequent .Xr read 2 from the terminal will return data written on the slave part of the pseudo terminal preceded by a zero byte (symbolically defined as .Dv TIOCPKT_DATA ) , or a single byte reflecting control status information. In the latter case, the byte is an inclusive-or of zero or more of the bits: .Bl -tag -width TIOCPKT_FLUSHWRITE .It Dv TIOCPKT_FLUSHREAD whenever the read queue for the terminal is flushed. .It Dv TIOCPKT_FLUSHWRITE whenever the write queue for the terminal is flushed. .It Dv TIOCPKT_STOP whenever output to the terminal is stopped a la .Ql ^S . .It Dv TIOCPKT_START whenever output to the terminal is restarted. .It Dv TIOCPKT_DOSTOP whenever .Em t_stopc is .Ql ^S and .Em t_startc is .Ql ^Q . .It Dv TIOCPKT_NOSTOP whenever the start and stop characters are not .Ql ^S/^Q . .Pp While this mode is in use, the presence of control status information to be read from the master side may be detected by a .Xr select 2 for exceptional conditions. .Pp This mode is used by .Xr rlogin 1 and .Xr rlogind 8 to implement a remote-echoed, locally .Ql ^S/^Q flow-controlled remote login with proper back-flushing of output; it can be used by other similar programs. .El .It Dv TIOCUCNTL Enable/disable a mode that allows a small number of simple user .Xr ioctl 2 commands to be passed through the pseudo-terminal, using a protocol similar to that of .Dv TIOCPKT . The .Dv TIOCUCNTL and .Dv TIOCPKT modes are mutually exclusive. This mode is enabled from the master side of a pseudo terminal by specifying (by reference) a nonzero parameter and disabled by specifying (by reference) a zero parameter. Each subsequent .Xr read 2 from the master side will return data written on the slave part of the pseudo terminal preceded by a zero byte, or a single byte reflecting a user control operation on the slave side. A user control command consists of a special .Xr ioctl 2 operation with no data; the command is given as .Dv UIOCCMD Ns (n) , where .Ar n is a number in the range 1-255. The operation value .Ar n will be received as a single byte on the next .Xr read 2 from the master side. The .Xr ioctl 2 .Dv UIOCCMD Ns (0) is a no-op that may be used to probe for the existence of this facility. As with .Dv TIOCPKT mode, command operations may be detected with a .Xr select 2 for exceptional conditions. .It Dv TIOCREMOTE A mode for the master half of a pseudo terminal, independent of .Dv TIOCPKT . This mode causes input to the pseudo terminal to be flow controlled and not input edited (regardless of the -terminal mode). Each write to the control terminal produces -a record boundary for the process reading the terminal. In -normal usage, a write of data is like the data typed as a line +terminal mode). +Each write to the control terminal produces +a record boundary for the process reading the terminal. +In normal usage, a write of data is like the data typed as a line on the terminal; a write of 0 bytes is like typing an end-of-file character. .Dv TIOCREMOTE can be used when doing remote line editing in a window manager, or whenever flow controlled input is required. .El .Sh FILES .Bl -tag -width /dev/tty[p-sP-S][0-9a-v]x -compact .It Pa /dev/pty[p-sP-S][0-9a-v] master pseudo terminals .It Pa /dev/tty[p-sP-S][0-9a-v] slave pseudo terminals .El .Sh DIAGNOSTICS None. .Sh SEE ALSO .Xr tty 4 .Sh HISTORY The .Nm driver appeared in .Bx 4.2 . Index: head/share/man/man4/route.4 =================================================================== --- head/share/man/man4/route.4 (revision 117010) +++ head/share/man/man4/route.4 (revision 117011) @@ -1,321 +1,325 @@ .\" Copyright (c) 1990, 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. .\" .\" From: @(#)route.4 8.6 (Berkeley) 4/19/94 .\" $FreeBSD$ .\" .Dd January 18, 2002 .Dt ROUTE 4 .Os .Sh NAME .Nm route .Nd kernel packet forwarding database .Sh SYNOPSIS .In sys/types.h .In sys/time.h .In sys/socket.h .In net/if.h .In net/route.h .Ft int .Fn socket PF_ROUTE SOCK_RAW "int family" .Sh DESCRIPTION .Fx provides some packet routing facilities. The kernel maintains a routing information database, which is used in selecting the appropriate network interface when transmitting packets. .Pp A user process (or possibly multiple co-operating processes) maintains this database by sending messages over a special kind of socket. This supplants fixed size .Xr ioctl 2 Ns 's used in earlier releases. Routing table changes may only be carried out by the super user. .Pp The operating system may spontaneously emit routing messages in response to external events, such as receipt of a re-direct, or failure to locate a suitable route for a request. The message types are described in greater detail below. .Pp Routing database entries come in two flavors: for a specific host, or for all hosts on a generic subnetwork (as specified by a bit mask and value under the mask. The effect of wildcard or default route may be achieved by using a mask of all zeros, and there may be hierarchical routes. .Pp When the system is booted and addresses are assigned to the network interfaces, each protocol family installs a routing table entry for each interface when it is ready for traffic. Normally the protocol specifies the route through each interface as a .Dq direct connection to the destination host -or network. If the route is direct, the transport layer of +or network. +If the route is direct, the transport layer of a protocol family usually requests the packet be sent to the -same host specified in the packet. Otherwise, the interface +same host specified in the packet. +Otherwise, the interface is requested to address the packet to the gateway listed in the routing entry (i.e. the packet is forwarded). .Pp When routing a packet, the kernel will attempt to find the most specific route matching the destination. (If there are two different mask and value-under-the-mask pairs that match, the more specific is the one with more bits in the mask. A route to a host is regarded as being supplied with a mask of as many ones as there are bits in the destination). If no entry is found, the destination is declared to be unreachable, and a routing\-miss message is generated if there are any listeners on the routing control socket described below. .Pp A wildcard routing entry is specified with a zero destination address value, and a mask of all zeroes. Wildcard routes will be used when the system fails to find other routes matching the -destination. The combination of wildcard +destination. +The combination of wildcard routes and routing redirects can provide an economical mechanism for routing traffic. .Pp One opens the channel for passing routing control messages by using the socket call shown in the synopsis above: .Pp The .Fa family parameter may be .Dv AF_UNSPEC which will provide routing information for all address families, or can be restricted to a specific address family by specifying which one is desired. There can be more than one routing socket open per system. .Pp Messages are formed by a header followed by a small number of sockaddrs (now variable length particularly in the .Tn ISO case), interpreted by position, and delimited by the new length entry in the sockaddr. An example of a message with four addresses might be an .Tn ISO redirect: Destination, Netmask, Gateway, and Author of the redirect. The interpretation of which address are present is given by a bit mask within the header, and the sequence is least significant to most significant bit within the vector. .Pp Any messages sent to the kernel are returned, and copies are sent -to all interested listeners. The kernel will provide the process +to all interested listeners. +The kernel will provide the process ID for the sender, and the sender may use an additional sequence -field to distinguish between outstanding messages. However, -message replies may be lost when kernel buffers are exhausted. +field to distinguish between outstanding messages. +However, message replies may be lost when kernel buffers are exhausted. .Pp The kernel may reject certain messages, and will indicate this by filling in the .Ar rtm_errno field. The routing code returns .Er EEXIST if requested to duplicate an existing entry, .Er ESRCH if requested to delete a non-existent entry, or .Er ENOBUFS if insufficient resources were available to install a new route. In the current implementation, all routing processes run locally, and the values for .Ar rtm_errno are available through the normal .Em errno mechanism, even if the routing reply message is lost. .Pp A process may avoid the expense of reading replies to its own messages by issuing a .Xr setsockopt 2 call indicating that the .Dv SO_USELOOPBACK option at the .Dv SOL_SOCKET level is to be turned off. A process may ignore all messages from the routing socket by doing a .Xr shutdown 2 system call for further input. .Pp If a route is in use when it is deleted, the routing entry will be marked down and removed from the routing table, but the resources associated with it will not be reclaimed until all references to it are released. User processes can obtain information about the routing entry to a specific destination by using a .Dv RTM_GET message, or by calling .Xr sysctl 3 . .Pp Messages include: .Bd -literal #define RTM_ADD 0x1 /* Add Route */ #define RTM_DELETE 0x2 /* Delete Route */ #define RTM_CHANGE 0x3 /* Change Metrics, Flags, or Gateway */ #define RTM_GET 0x4 /* Report Information */ #define RTM_LOSING 0x5 /* Kernel Suspects Partitioning */ #define RTM_REDIRECT 0x6 /* Told to use different route */ #define RTM_MISS 0x7 /* Lookup failed on this address */ #define RTM_LOCK 0x8 /* fix specified metrics */ #define RTM_RESOLVE 0xb /* request to resolve dst to LL addr */ #define RTM_NEWADDR 0xc /* address being added to iface */ #define RTM_DELADDR 0xd /* address being removed from iface */ #define RTM_IFINFO 0xe /* iface going up/down etc. */ #define RTM_NEWMADDR 0xf /* mcast group membership being added to if */ #define RTM_DELMADDR 0x10 /* mcast group membership being deleted */ #define RTM_IFANNOUNCE 0x11 /* iface arrival/departure */ .Ed .Pp A message header consists of one of the following: .Bd -literal struct rt_msghdr { u_short rtm_msglen; /* to skip over non-understood messages */ u_char rtm_version; /* future binary compatibility */ u_char rtm_type; /* message type */ u_short rtm_index; /* index for associated ifp */ int rtm_flags; /* flags, incl. kern & message, e.g. DONE */ int rtm_addrs; /* bitmask identifying sockaddrs in msg */ pid_t rtm_pid; /* identify sender */ int rtm_seq; /* for sender to identify action */ int rtm_errno; /* why failed */ int rtm_use; /* from rtentry */ u_long rtm_inits; /* which metrics we are initializing */ struct rt_metrics rtm_rmx; /* metrics themselves */ }; struct if_msghdr { u_short ifm_msglen; /* to skip over non-understood messages */ u_char ifm_version; /* future binary compatibility */ u_char ifm_type; /* message type */ int ifm_addrs; /* like rtm_addrs */ int ifm_flags; /* value of if_flags */ u_short ifm_index; /* index for associated ifp */ struct if_data ifm_data; /* statistics and other data about if */ }; struct ifa_msghdr { u_short ifam_msglen; /* to skip over non-understood messages */ u_char ifam_version; /* future binary compatibility */ u_char ifam_type; /* message type */ int ifam_addrs; /* like rtm_addrs */ int ifam_flags; /* value of ifa_flags */ u_short ifam_index; /* index for associated ifp */ int ifam_metric; /* value of ifa_metric */ }; struct ifma_msghdr { u_short ifmam_msglen; /* to skip over non-understood messages */ u_char ifmam_version; /* future binary compatibility */ u_char ifmam_type; /* message type */ int ifmam_addrs; /* like rtm_addrs */ int ifmam_flags; /* value of ifa_flags */ u_short ifmam_index; /* index for associated ifp */ }; struct if_announcemsghdr { u_short ifan_msglen; /* to skip over non-understood messages */ u_char ifan_version; /* future binary compatibility */ u_char ifan_type; /* message type */ u_short ifan_index; /* index for associated ifp */ char ifan_name[IFNAMSIZ]; /* if name, e.g. "en0" */ u_short ifan_what; /* what type of announcement */ }; .Ed .Pp The .Dv RTM_IFINFO message uses a .Ar if_msghdr header, the .Dv RTM_NEWADDR and .Dv RTM_DELADDR messages use a .Ar ifa_msghdr header, the .Dv RTM_NEWMADDR and .Dv RTM_DELMADDR messages use a .Vt ifma_msghdr header, the .Dv RTM_IFANNOUNCE message uses a .Vt if_announcemsghdr header, and all other messages use the .Ar rt_msghdr header. .Pp The .Dq Li "struct rt_metrics" and the flag bits are as defined in .Xr rtentry 9 . .Pp Specifiers for metric values in rmx_locks and rtm_inits are: .Bd -literal #define RTV_MTU 0x1 /* init or lock _mtu */ #define RTV_HOPCOUNT 0x2 /* init or lock _hopcount */ #define RTV_EXPIRE 0x4 /* init or lock _expire */ #define RTV_RPIPE 0x8 /* init or lock _recvpipe */ #define RTV_SPIPE 0x10 /* init or lock _sendpipe */ #define RTV_SSTHRESH 0x20 /* init or lock _ssthresh */ #define RTV_RTT 0x40 /* init or lock _rtt */ #define RTV_RTTVAR 0x80 /* init or lock _rttvar */ .Ed .Pp Specifiers for which addresses are present in the messages are: .Bd -literal #define RTA_DST 0x1 /* destination sockaddr present */ #define RTA_GATEWAY 0x2 /* gateway sockaddr present */ #define RTA_NETMASK 0x4 /* netmask sockaddr present */ #define RTA_GENMASK 0x8 /* cloning mask sockaddr present */ #define RTA_IFP 0x10 /* interface name sockaddr present */ #define RTA_IFA 0x20 /* interface addr sockaddr present */ #define RTA_AUTHOR 0x40 /* sockaddr for author of redirect */ #define RTA_BRD 0x80 /* for NEWADDR, broadcast or p-p dest addr */ .Ed .Sh SEE ALSO .Xr sysctl 3 , .Xr route 8 , .Xr rtentry 9 .Sh HISTORY A .Dv PF_ROUTE protocol family first appeared in .Bx 4.3 reno . Index: head/share/man/man4/sa.4 =================================================================== --- head/share/man/man4/sa.4 (revision 117010) +++ head/share/man/man4/sa.4 (revision 117011) @@ -1,231 +1,246 @@ .\" Copyright (c) 1996 .\" Julian Elischer . All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd June 6, 1999 .Dt SA 4 .Os .Sh NAME .Nm sa .Nd SCSI Sequential Access device driver .Sh SYNOPSIS .Cd device sa .Sh DESCRIPTION The .Nm driver provides support for all .Tn SCSI devices of the sequential access class that are attached to the system through a supported .Tn SCSI Host Adapter. The sequential access class includes tape and other linear access devices. .Pp A .Tn SCSI Host adapter must also be separately configured into the system before a .Tn SCSI sequential access device can be configured. .Sh MOUNT SESSIONS The .Nm driver is based around the concept of a .Dq Em mount session , which is defined as the period between the time that a tape is -mounted, and the time when it is unmounted. Any parameters set during +mounted, and the time when it is unmounted. +Any parameters set during a mount session remain in effect for the remainder of the session or until replaced. The tape can be unmounted, bringing the session to a -close in several ways. These include: +close in several ways. +These include: .Bl -enum .It Closing a `rewind device', referred to as sub-mode 00 below. An example is .Pa /dev/sa0 . .It Using the MTOFFL .Xr ioctl 2 command, reachable through the .Sq Cm offline command of .Xr mt 1 . .El .Pp It should be noted that tape devices are exclusive open devices, except in the case where a control mode device is opened. In the latter case, exclusive access is only sought when needed (e.g., to set parameters). .Sh SUB-MODES Bits 0 and 1 of the minor number are interpreted as .Sq sub-modes . The sub-modes differ in the action taken when the device is closed: .Bl -tag -width XXXX .It 00 A close will rewind the device; if the tape has been written, then a file mark will be written before the rewind is requested. The device is unmounted. .It 01 A close will leave the tape mounted. If the tape was written to, a file mark will be written. No other head positioning takes place. Any further reads or writes will occur directly after the last read, or the written file mark. .It 10 A close will rewind the device. If the tape has been written, then a file mark will be written before the rewind is requested. On completion of the rewind an unload command will be issued. The device is unmounted. .El .Sh BLOCKING MODES .Tn SCSI tapes may run in either .Sq Em variable or .Sq Em fixed block-size modes. Most .Tn QIC Ns -type devices run in fixed block-size mode, where most nine-track tapes and -many new cartridge formats allow variable block-size. The difference -between the two is as follows: +many new cartridge formats allow variable block-size. +The difference between the two is as follows: .Bl -inset .It Variable block-size: Each write made to the device results in a single logical record -written to the tape. One can never read or write +written to the tape. +One can never read or write .Em part of a record from tape (though you may request a larger block and read -a smaller record); nor can one read multiple blocks. Data from a -single write is therefore read by a single read. +a smaller record); nor can one read multiple blocks. +Data from a single write is therefore read by a single read. The block size used may be any value supported by the device, the .Tn SCSI adapter and the system (usually between 1 byte and 64 Kbytes, sometimes more). .Pp When reading a variable record/block from the tape, the head is logically considered to be immediately after the last item read, and before the next item after that. If the next item is a file mark, but it was never read, then the next process to read will immediately hit the file mark and receive an end-of-file notification. .It Fixed block-size: Data written by the user is passed to the tape as a succession of -fixed size blocks. It may be contiguous in memory, but it is +fixed size blocks. +It may be contiguous in memory, but it is considered to be a series of independent blocks. One may never write -an amount of data that is not an exact multiple of the blocksize. One -may read and write the same data as a different set of records, In -other words, blocks that were written together may be read separately, +an amount of data that is not an exact multiple of the blocksize. +One may read and write the same data as a different set of records. +In other words, blocks that were written together may be read separately, and vice-versa. .Pp If one requests more blocks than remain in the file, the drive will -encounter the file mark. Because there is some data to return (unless +encounter the file mark. +As there is some data to return (unless there were no records before the file mark), the read will succeed, -returning that data, The next read will return immediately with a value -of 0. (As above, if the file mark is never read, it remains for the next +returning that data. +The next read will return immediately with a value +of 0. +(As above, if the file mark is never read, it remains for the next process to read if in no-rewind mode.) .El .Sh FILE MARK HANDLING The handling of file marks on write is automatic. If the user has written to the tape, and has not done a read since the last write, then a file mark will be written to the tape when the device is -closed. If a rewind is requested after a write, then the driver +closed. +If a rewind is requested after a write, then the driver assumes that the last file on the tape has been written, and ensures -that there are two file marks written to the tape. The exception to +that there are two file marks written to the tape. +The exception to this is that there seems to be a standard (which we follow, but don't understand why) that certain types of tape do not actually write two file marks to tape, but when read, report a `phantom' file mark when the -last file is read. These devices include the QIC family of devices. +last file is read. +These devices include the QIC family of devices. (It might be that this set of devices is the same set as that of fixed -block devices. This has not been determined yet, and they are treated +block devices. +This has not been determined yet, and they are treated as separate behaviors by the driver at this time.) .Sh IOCTLS The .Nm driver supports all of the ioctls of .Xr mtio 4 . .Sh FILES .Bl -tag -width /dev/[n][e]sa[0-9] -compact .It Pa /dev/[n][e]sa[0-9] general form: .It Pa /dev/sa0 Rewind on close .It Pa /dev/nsa0 No rewind on close .It Pa /dev/esa0 Eject on close (if capable) .It Pa /dev/sa0.ctl Control mode device (to examine state while another program is accessing the device, e.g.). .El .Sh BUGS This driver lacks many of the hacks required to deal with older devices. Many older .Tn SCSI-1 devices may not work properly with this driver yet. .Pp Additionally, certain tapes (QIC tapes mostly) that were written under .Fx 2.X aren't automatically read correctly with this driver: you may need to explicitly set variable block mode or set to the blocksize that works best for your device in order to read tapes written under .Fx 2.X. .Pp Fine grained density and compression mode support that is bound to specific device names needs to be added. .Pp Support for fast indexing by use of partitions is missing. .Sh DIAGNOSTICS None. .Sh SEE ALSO .Xr mt 1 , .Xr scsi 4 -.Sh HISTORY +.Sh AUTHORS +.An -nosplit The .Nm driver was written for the .Tn CAM .Tn SCSI -subsystem by Justin T. Gibbs and Kenneth Merry. +subsystem by +.An Justin T. Gibbs +and +.An Kenneth Merry . Many ideas were gleaned from the .Nm st device driver written and ported from .Tn Mach 2.5 by .An Julian Elischer . .Pp The current owner of record is .An Matthew Jacob who has suffered too many years of breaking tape drivers. Index: head/share/man/man4/scsi.4 =================================================================== --- head/share/man/man4/scsi.4 (revision 117010) +++ head/share/man/man4/scsi.4 (revision 117011) @@ -1,280 +1,303 @@ .\" Copyright (c) 1996 .\" Julian Elischer . All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .Dd October 15, 1998 .Dt SCSI 4 .Os .Sh NAME .Nm SCSI , .Nm CAM .Nd CAM SCSI subsystem .Sh SYNOPSIS .Cd "device scbus" .Cd "device cd" .Cd "device ch" .Cd "device da" .Cd "device pass" .Cd "device pt" .Cd "device sa" .Cd "device ch" .Cd "options CAMDEBUG" .Cd "options CAM_DEBUG_BUS=-1" .Cd "options CAM_DEBUG_TARGET=-1" .Cd "options CAM_DEBUG_LUN=-1" .Cd "options CAM_DEBUG_FLAGS=CAM_DEBUG_INFO|CAM_DEBUG_CDB" .Cd "options CAM_MAX_HIGHPOWER=4" .Cd "options SCSI_NO_SENSE_STRINGS" .Cd "options SCSI_NO_OP_STRINGS" .Cd "options SCSI_DELAY=8000" .Sh DESCRIPTION The CAM .Tn SCSI subsystem provides a uniform and modular system for the implementation of drivers to control various .Tn SCSI devices, and to utilize different .Tn SCSI host adapters through host adapter drivers. When the system probes the .Tn SCSI busses, it attaches any devices it finds to the appropriate -drivers. The +drivers. +The .Xr pass 4 driver, if it is configured in the kernel, will attach to all .Tn SCSI devices. .Sh KERNEL CONFIGURATION There are a number of generic kernel configuration options for the CAM .Tn SCSI subsystem: .Bl -tag -width SCSI_NO_SENSE_STRINGS .It Dv CAMDEBUG -This option enables the CAM debugging printf code. This won't actually +This option enables the CAM debugging printf code. +This won't actually cause any debugging information to be printed out when included by itself. -Enabling printouts requires additional configuration. See below for -details. +Enabling printouts requires additional configuration. +See below for details. .It Dv "CAM_MAX_HIGHPOWER=4" This sets the maximum allowable number of concurrent "high power" commands. A "high power" command is a command that takes more electrical power than -most to complete. An example of this (and the only command currently +most to complete. +An example of this (and the only command currently tagged as "high power") is the .Tn SCSI -START UNIT command. Starting a SCSI disk often takes significantly more -electrical power than normal operation of the disk. This option allows the +START UNIT command. +Starting a SCSI disk often takes significantly more +electrical power than normal operation of the disk. +This option allows the user to specify how many concurrent high power commands may be outstanding without overloading the power supply on his computer. .It Dv SCSI_NO_SENSE_STRINGS This eliminates text descriptions of each .Tn SCSI -Additional Sense Code and Additional Sense Code Qualifier pair. Since this +Additional Sense Code and Additional Sense Code Qualifier pair. +Since this is a fairly large text database, eliminating it reduces the size of the -kernel somewhat. This is primarily necessary for boot floppies and other -low disk space or low memory space environments. In most cases, though, +kernel somewhat. +This is primarily necessary for boot floppies and other +low disk space or low memory space environments. +In most cases, though, this should be enabled, since it speeds the interpretation of .Tn SCSI error messages. Don't let the "kernel bloat" zealots get to you -- leave the sense descriptions in your kernel! .It Dv SCSI_NO_OP_STRINGS This disables text descriptions of each .Tn SCSI -opcode. This option, like the sense string option above, is primarily +opcode. +This option, like the sense string option above, is primarily useful for environments like a boot floppy where kernel size is critical. Enabling this option for normal use isn't recommended, since it slows debugging of .Tn SCSI problems. .It Dv SCSI_DELAY=8000 This is the .Tn SCSI -"bus settle delay." In CAM, it is specified in +"bus settle delay." +In CAM, it is specified in .Em milliseconds , not seconds like the old .Tn SCSI -layer used to do. When the kernel boots, it sends a bus reset to each +layer used to do. +When the kernel boots, it sends a bus reset to each .Tn SCSI bus to tell each device to reset itself to a default set of transfer -negotiations and other settings. Most +negotiations and other settings. +Most .Tn SCSI -devices need some amount of time to recover from a bus reset. Newer disks +devices need some amount of time to recover from a bus reset. +Newer disks may need as little as 100ms, while old, slow devices may need much longer. If the .Dv SCSI_DELAY -isn't specified, it defaults to 2 seconds. The minimum allowable value for +isn't specified, it defaults to 2 seconds. +The minimum allowable value for .Dv SCSI_DELAY -is "100", or 100ms. One special case is that if the +is "100", or 100ms. +One special case is that if the .Dv SCSI_DELAY -is set to 0, that will be taken to mean the "lowest possible value." In -that case, the +is set to 0, that will be taken to mean the "lowest possible value." +In that case, the .Dv SCSI_DELAY will be reset to 100ms. .El .Pp All devices and the SCSI busses support boot time allocation so that an upper number of devices and controllers does not need to be configured; .Cd "device da0" will suffice for any number of disk drivers. .Pp The devices are either .Em wired so they appear as a particular device unit or .Em counted so that they appear as the next available unused unit. .Pp To configure a driver in the kernel without wiring down the device use a config line similar to .Cd "device ch0" to include the changer driver. .Pp To wire down a unit use a config line similar to .Cd "device ch1 at scbus0 target 4 unit 0" to assign changer 1 as the changer with SCSI ID 4, SCSI logical unit 0 on SCSI bus 0. Individual scbuses can be wired down to specific controllers with a config line similar to .Cd "device scbus0 at ahc0" which assigns scsi bus 0 to the first unit using the ahc driver. For controllers supporting more than one bus, the particular bus can be specified as in .Cd "device scbus3 at ahc1 bus 1" which assigns scbus 1 to the second bus probed on the ahc1 device. .Pp When you have a mixture of wired down and counted devices then the counting begins with the first non-wired down unit for a particular -type. That is, if you have a disk wired down as +type. +That is, if you have a disk wired down as .Em "device da1" , then the first non-wired disk shall come on line as .Em da2 . .Sh ADAPTERS The system allows common device drivers to work through many different types of adapters. The adapters take requests from the upper layers and do all IO between the .Em SCSI bus and the system. The maximum size of a transfer is governed by the adapter. Most adapters can transfer 64KB in a single operation, however many can transfer larger amounts. .Sh TARGET MODE Some adapters support .Em target mode in which the system is capable of operating as a device, responding to operations initiated by another system. Target mode is supported for some adapters, but is not yet complete for this version of the CAM .Tn SCSI subsystem. .Sh FILES see other scsi device entries. .Sh DIAGNOSTICS When the kernel is compiled with options CAMDEBUG, an XPT_DEBUG CCB can be used to enable various amounts of tracing information on any specific device. Devices not being traced will not produce trace information. There are currently four debugging flags that may be turned on: .Bl -tag -width CAM_DEBUG_SUBTRACE .It Dv CAM_DEBUG_INFO This debugging flag enables general informational printfs for the device or devices in question. .It Dv CAM_DEBUG_TRACE This debugging flag enables function-level command flow tracing. i.e.\& kernel printfs will happen at the entrance and exit of various functions. .It Dv CAM_DEBUG_SUBTRACE This debugging flag enables debugging output internal to various functions. .It Dv CAM_DEBUG_CDB This debugging flag will cause the kernel to print out all .Tn SCSI commands sent to a particular device or devices. .El .Pp Some of these flags, most notably .Dv CAM_DEBUG_TRACE and .Dv CAM_DEBUG_SUBTRACE -will produce kernel printfs in EXTREME numbers. Because of that, they -aren't especially useful. There aren't many things logged at the +will produce kernel printfs in EXTREME numbers, +and because of that, they aren't especially useful. +There aren't many things logged at the .Dv CAM_DEBUG_INFO -level, so it isn't especially useful. The most useful debugging flag is -the +level, so it isn't especially useful. +The most useful debugging flag is the .Dv CAM_DEBUG_CDB flag. Users can enable debugging from their kernel config file, by using the following kernel config options: .Bl -tag -width CAM_DEBUG_TARGET .It Dv CAMDEBUG -This enables CAM debugging. Without this option, users will not even be able +This enables CAM debugging. +Without this option, users will not even be able to turn on debugging from userland via .Xr camcontrol 8 . .It Dv CAM_DEBUG_FLAGS This allows the user to set the various debugging flags described above -in a kernel config file. Flags may be ORed together if the user wishes to +in a kernel config file. +Flags may be ORed together if the user wishes to see printfs for multiple debugging levels. .It Dv CAM_DEBUG_BUS -Specify a bus to debug. To debug all busses, set this to -1. +Specify a bus to debug. +To debug all busses, set this to -1. .It Dv CAM_DEBUG_TARGET -Specify a target to debug. To debug all targets, set this to -1. +Specify a target to debug. +To debug all targets, set this to -1. .It Dv CAM_DEBUG_LUN -Specify a lun to debug. To debug all luns, set this to -1. +Specify a lun to debug. +To debug all luns, set this to -1. .El .Pp When specifying a bus, target or lun to debug, you .Em MUST -specify all three bus/target/lun options above. Using wildcards, you +specify all three bus/target/lun options above. +Using wildcards, you should be able to enable debugging on most anything. .Pp Users may also enable debugging printfs on the fly, if the .Dv CAMDEBUG option is their config file, by using the .Xr camcontrol 8 utility. See .Xr camcontrol 8 for details. .Sh SEE ALSO .Xr aha 4 , .Xr ahb 4 , .Xr ahc 4 , .Xr bt 4 , .Xr cd 4 , .Xr ch 4 , .Xr da 4 , .Xr pass 4 , .Xr pt 4 , .Xr sa 4 , .Xr xpt 4 , .Xr camcontrol 8 .Sh HISTORY The CAM .Tn SCSI subsystem first appeared in .Fx 3.0 . .Sh AUTHORS .An -nosplit The CAM .Tn SCSI subsystem was written by .An Justin Gibbs and .An Kenneth Merry . Index: head/share/man/man4/si.4 =================================================================== --- head/share/man/man4/si.4 (revision 117010) +++ head/share/man/man4/si.4 (revision 117011) @@ -1,172 +1,178 @@ .\" $FreeBSD$ .Dd September 16, 1995 .Os .Dt SI 4 .Sh NAME .Nm si .Nd "driver for Specialix International SI/XIO or SX intelligent serial card" .Sh SYNOPSIS .Cd "device si" .Pp For ISA host cards put the following lines in .Pa /boot/device.hints : .Cd hint.si.0.at="isa" .Cd hint.si.0.maddr="0xd0000" .Cd hint.si.0.irq="12" .Sh DESCRIPTION The Specialix SI/XIO and SX hardware makes up an 8 to 32 port RS-232 serial multiplexor. .Pp The system uses two components: A "Host adapter", which is plugged into an ISA, EISA or PCI slot and provides intelligence and buffering/processing capabilities, as well as an external bus in the form of a 37 pin cable. .Pp -On this cable, "modules" are connected. The "SI" module comes in a 4 and 8 -port version. The "XIO" and "SX" modules come only in +On this cable, "modules" are connected. +The "SI" module comes in a 4 and 8 port version. +The "XIO" and "SX" modules come only in 8 port versions. .Pp The host adapter polls and transfers data between the modules and the rest of the machine. The Host adapter provides a 256 byte transmit and 256 byte receive FIFO for each of the 32 ports that it can maintain. .Pp The XIO modules can operate each of their 8 ports at 115,200 baud. The SI version can run at 57,600 baud. The SX modules can operate each of their 8 ports at up to 921,600 baud. .Pp SX modules are only supported when connected to an SX host card. SI or XIO modules are supported on any host card. .Pp The host adapter uses a shared memory block in the traditional ISA bus -"hole" between 0xA0000 and 0xEFFFF. The adapter can be configured outside -range, but requires the memory range to be explicitly non-cached. The -driver does not yet support this mode of operation. +"hole" between 0xA0000 and 0xEFFFF. +The adapter can be configured outside +range, but requires the memory range to be explicitly non-cached. +The driver does not yet support this mode of operation. .Pp SX ISA Host cards have an 8/16 bit mode switch or jumper on them. This switch or jumper MUST be set for 8 bit mode. .Pp The ISA adapters can use Irq's 11, 12 or 15 (and 9 and 10 in the case of SX host cards). .Pp The si device driver may have some of its configuration settings changed at run-time with the .Xr sicontrol 8 utility. .Pp The si device driver also responds to the .Xr comcontrol 8 utility for configuring drain-on-close timeouts. .Pp The driver also defines 3 sysctl variables that can be manipulated: machdep.si_debug sets the debug level for the whole driver. It depends on the driver being compiled with SI_DEBUG. machdep.si_pollrate sets how often per second the driver polls for lost interrupts. machdep.si_realpoll sets whether or not the card will treat the poll intervals as if they were interrupts. .Pp An open on a /dev device node controlled by the si driver obeys the same semantics as the .Xr sio 4 -driver. It fully supports the usual semantics of the cua ports, and the -"initial termios" and "locked termios" settings. In summary, an open on a +driver. +It fully supports the usual semantics of the cua ports, and the +"initial termios" and "locked termios" settings. +In summary, an open on a tty port will block until DCD is raised, unless O_NONBLOCK is specified. CLOCAL is honored. An open on a cua port will always succeed, but DCD transitions will be honored after DCD rises for the first time. .Pp Up to four SI/XIO host cards may be controlled by the si driver. Due to the lack of available interrupts, only 3 ISA SI/XIO host cards can be used at once. .Pp The lowest 5 bits of the minor device number are used to select the port number on the module cluster. The next 2 bits select which of 4 host adapter cards. This allows a maximum of 128 ports on this driver. .Pp Bit 7 is used to differentiate a tty/dialin port (bit 7=0) and a cua/callout port (bit 7=1). .Pp Bit 8 through 15 (on .Fx ) are unavailable as they are a shadow of the major device number. .Pp If bit 16 is a 1, the device node is referring to the "initial state" device. This "initial state" is used to prime the .Xr termios 4 settings of the device when it is initially opened. If bit 17 is a 1, the device node is referring to the "locked state" device. The "locked state" is used to prevent the .Xr termios 4 settings from being changed. .Pp To manipulate the initial/locked settings, the .Xr stty 1 -command is useful. When setting the "locked" variables, enabling the mode +command is useful. +When setting the "locked" variables, enabling the mode on the lock device will lock the termios mode, while disabling the mode will unlock it. .Sh FILES .Bl -tag -width /dev/si_control -compact .It Pa /dev/si_control global driver control file for .Xr sicontrol 8 .It Pa /dev/ttyA* terminal/dialin ports .It Pa /dev/cuaA* dialout ports .It Pa /dev/ttyiA* initial termios state devices .It Pa /dev/ttylA* locked termios state devices .It Pa /dev/cuaiA* initial termios state devices for dialout ports .It Pa /dev/cualA* locked termios state devices for dialout ports .El .Sh SEE ALSO .Xr stty 1 , .Xr sio 4 , .Xr termios 4 , .Xr tty 4 , .Xr comcontrol 8 , .Xr sicontrol 8 .Sh HISTORY This driver is loosely based on driver code originating at Specialix, which was ported to run on BSDI by .An Andy Rutter Aq andy@specialix.co.uk . The System V driver source is/was available by ftp from .Sy ftp.specialix.co.uk . .Pp This driver is not supported by Specialix International. .Sh AUTHORS .An -nosplit .An Peter Wemm Aq peter@netplex.com.au obtained the code from .An Andy Rutter and ported it to .Fx and threw the man page together. .An Bruce Evans Aq bde@zeta.org.au provided a large amount of assistance during porting. .An Nick Sayer Aq nick@specialix.com wrote the EISA, PCI and SX portions. .Sh BUGS The interrupt tuning rate is not believed to be optimal at this time for maximum efficiency. .Pp Polled mode (a feature of standard Specialix drivers) is not implemented, -but it can be approximated by turning on machdep.si_realpoll. The poll +but it can be approximated by turning on machdep.si_realpoll. +The poll frequency is set by machdep.si_pollrate (in units of 1/100th of a second). .Pp The driver does not yet support baud rates higher than 115,200 on SX modules. .Pp Operation outside the traditional ISA "hole" is not yet supported, although it should work if the test is removed from the probe routine. .Pp Multiple host cards are supported although combinations of hosts on different bus types have not been tested - device numbering is known to be a problem and may lead to unexpected results. Index: head/share/man/man4/sio.4 =================================================================== --- head/share/man/man4/sio.4 (revision 117010) +++ head/share/man/man4/sio.4 (revision 117011) @@ -1,416 +1,422 @@ .\" 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 .\" $FreeBSD$ .\" .Dd July 10, 2002 .Dt SIO 4 .Os .Sh NAME .Nm sio .Nd "fast interrupt driven asynchronous serial communications interface" .Sh SYNOPSIS For standard ISA ports: .Bd -ragged -offset indent -compact .Cd "device sio" .Pp In .Pa /boot/device.hints : .Cd hint.sio.0.at="isa" .Cd hint.sio.0.port="0x3f8" .Cd hint.sio.0.flags="0x10" .Cd hint.sio.0.irq="4" .Cd hint.sio.1.at="isa" .Cd hint.sio.1.port="0x2f8" .Cd hint.sio.1.flags="0x0" .Cd hint.sio.1.irq="3" .Ed .Pp For AST compatible multiport cards with 4 ports: .Bd -ragged -offset indent -compact .Cd "options COM_MULTIPORT" .Cd "device sio" .Pp In .Pa /boot/device.hints : .Cd hint.sio.4.at="isa" .Cd hint.sio.4.port="0x2a0" .Cd hint.sio.4.flags="0x701" .Cd hint.sio.5.at="isa" .Cd hint.sio.5.port="0x2a8" .Cd hint.sio.5.flags="0x701" .Cd hint.sio.6.at="isa" .Cd hint.sio.6.port="0x2b0" .Cd hint.sio.6.flags="0x701" .Cd hint.sio.7.at="isa" .Cd hint.sio.7.port="0x2b8" .Cd hint.sio.7.flags="0x701" .Cd hint.sio.7.irq="12" .Ed .Pp For Boca Board compatible multiport cards with 8 ports: .Bd -ragged -offset indent -compact .Cd "options COM_MULTIPORT" .Cd "device sio" .Pp In .Pa /boot/device.hints : .Cd hint.sio.4.at="isa" .Cd hint.sio.4.port="0x100" .Cd hint.sio.4.flags="0xb05" .Cd "..." .Cd hint.sio.11.at="isa" .Cd hint.sio.11.port="0x138" .Cd hint.sio.11.flags="0xb05" .Cd hint.sio.11.irq="12" .Ed .Pp For Netmos Nm9845 multiport cards with 6 ports: .Bd -ragged -offset indent -compact .Cd "options COM_MULTIPORT" .Cd "device sio" .Pp In .Pa /boot/device.hints : .Cd hint.sio.4.at="isa" .Cd hint.sio.4.port="0xb000" .Cd hint.sio.4.flags="0x901" .Cd hint.sio.5.at="isa" .Cd hint.sio.5.port="0xb400" .Cd hint.sio.5.flags="0x901" .Cd hint.sio.6.at="isa" .Cd hint.sio.6.port="0xb800" .Cd hint.sio.6.flags="0x901" .Cd hint.sio.7.at="isa" .Cd hint.sio.7.port="0xbc00" .Cd hint.sio.7.flags="0x901" .Cd hint.sio.8.at="isa" .Cd hint.sio.8.port="0xc000" .Cd hint.sio.8.flags="0x901" .Cd hint.sio.9.at="isa" .Cd hint.sio.9.port="0xac00" .Cd hint.sio.9.flags="0x901" .Cd hint.sio.9.irq="12" .Ed .Pp For Hayes ESP cards: .Bd -ragged -offset indent -compact .Cd "options COM_ESP" .Cd "device sio" .Cd "..." .Ed .Pp For single port PCI and PCCARD cards: .Bd -ragged -offset indent -compact .Cd "device sio" .Pp No lines are required in .Pa /boot/device.hints for these cards. .Ed .Pp For dual port PCI cards that share an interrupt: .Bd -ragged -offset indent -compact .Cd "device sio" .Cd "options COM_MULTIPORT" .Pp In .Pa /boot/device.hints : .Cd hint.sio.2.flags="0x201" .Cd hint.sio.3.flags="0x201" .Ed .Pp Meaning of .Ar flags : .Bl -tag -offset indent -compact -width 0x000000 .It 0x00001 shared IRQs .It 0x00002 disable FIFO .It 0x00004 no AST/4 compatible IRQ control register .It 0x00008 recover sooner from lost output interrupts .It 0x00010 device is potential system console .It 0x00020 device is forced to become system console .It 0x00040 device is reserved for low-level IO (e. g. for remote kernel debugging) .It 0x00080 use this port for remote kernel debugging .It 0x0 Ns Em ?? Ns 00 minor number of master port .It 0x10000 PPS timestamping on CTS instead of DCD .It 0x20000 device is assumed to use a 16650A-type (extended FIFO) chip .El .Pp Minor numbering: .Bd -literal -offset indent -compact 0b\fIOLIMMMMM\fR call\fBO\fRut \fBL\fRock \fBI\fRnitial \fBMMMMM\fRinor .Ed .Sh DESCRIPTION The .Nm driver provides support for NS8250-, NS16450-, NS16550 and NS16550A-based .Tn EIA .Tn RS-232C .Pf ( Tn CCITT .Tn V.24 ) -communications interfaces. The NS8250 and NS16450 have single character +communications interfaces. +The NS8250 and NS16450 have single character buffers, the NS16550A has 16 character FIFO input and output buffers. .Pp Input and output for each line may set to one of following baud rates; 50, 75, 110, 134.5, 150, 300, 600, 1200, 1800, 2400, 4800, 9600, -19200, 28800, 38400, 57600, or 115200. Your hardware may limit your baud -rate choices. +19200, 28800, 38400, 57600, or 115200. +Your hardware may limit your baud rate choices. .Pp The driver supports `multiport' cards. Multiport cards are those that have one or more groups of ports that share an Interrupt Request (IRQ) line per group. Shared IRQs on different cards are not supported. Frequently 4 ports share 1 IRQ; some 8 port cards have 2 groups of 4 ports, thus using 2 IRQs. Some cards allow the first 2 serial ports to have separate IRQs per port (as per DOS PC standard). .Pp Some cards have an IRQ control register for each group. Some cards require special initialization related to such registers. Only AST/4 compatible IRQ control registers are supported. Some cards have an IRQ status register for each group. The driver does not require or use such registers yet. To work, the control and status registers for a group, if any, must be mapped to the scratch register (register 7) of a port in the group. Such a port is called a .Em master port. .Pp The driver supports controller based PCI modems. The 3Com FaxModem PCI and the Advantec 56k Voice Messaging PCI FaxModem are the only cards supported. WinModems, softmodems, hfc modems and any other modems that aren't controller based are not supported. .Pp The .Em flags keyword may be used on each .Em device sio line in the kernel configuration file to disable the FIFO on 16550A UARTs (see the synopsis). Disabling the FIFO should rarely be necessary. .Pp The .Em flags keyword .Em must be used for all ports that are part of an IRQ sharing group. One bit specifies IRQ sharing; another bit specifies whether the port does .Em not require AST/4 compatible initialization. The minor number of the device corresponding a master port for the group is encoded as a bitfield in the high byte. The same master port must be specified for all ports in a group. .Pp The .Em irq specification must be given for master ports and for ports that are not part of an IRQ sharing group, and not for other ports. .Pp In the synopsis, .Em flags 0x701 means that the 8th port (sio7) is the master port, and that the port is on a multiport card with shared IRQs and an AST/4 compatible IRQ control register. .Pp .Em flags 0xb05 means that the 12th port (sio11) is the master port, and that the port is on a multiport card with shared IRQs and no special IRQ control register. .Pp Which port is the master port depends on the card type. Consult the hardware documentation of your card. Since IRQ status registers are never used, and IRQ control registers are only used for AST/4 compatible cards, and some cards map the control/status registers to all ports in a group, any port in a group will sometimes do for the master port. Choose a port containing an IRQ status register for forwards compatibility, and the highest possible port for consistency. .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 +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 +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 don't -support it at all. CLOCAL should be locked on for devices -that don't support carrier. HUPCL may be locked off if you don't -want to hang up for some reason. In general, very bad things happen +support it at all. +CLOCAL should be locked on for devices that don't support carrier. +HUPCL may be locked off if you don't +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 +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. .Sh FILES .Bl -tag -width /dev/ttyid? -compact .It Pa /dev/ttyd? for callin ports .It Pa /dev/ttyid? .It Pa /dev/ttyld? corresponding callin initial-state and lock-state devices .Pp .It Pa /dev/cuaa? for callout ports .It Pa /dev/cuaia? .It Pa /dev/cuala? 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 device numbers are made from the set [0-9a-v] so that more than 10 ports can be supported. .Sh DIAGNOSTICS .Bl -diag .It sio%d: silo overflow. Problem in the interrupt handler. .El .Bl -diag .It sio%d: interrupt-level buffer overflow. Problem in the bottom half of the driver. .El .Bl -diag .It sio%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 .Sh HISTORY The .Nm driver is derived from the .Tn HP9000/300 .Xr dca 4 driver and is .Ud .Sh BUGS Data loss may occur at very high baud rates on slow systems, or with too many ports on any system, or on heavily loaded systems when crtscts cannot be used. The use of NS16550A's reduces system load and helps to avoid data loss. .Pp -Stay away from plain NS16550's. These are early -implementations of the chip with non-functional FIFO hardware. +Stay away from plain NS16550's. +These are early implementations of the chip with non-functional FIFO hardware. .Pp The constants which define the locations of the various serial ports are holdovers from .Tn DOS . As shown, hex addresses can be and for clarity probably should be used instead. .Pp Note that on the AST/4 the card's dipswitches should .Em not be set to use interrupt sharing. AST/4-like interrupt sharing is only used when .Em multiple -AST/4 cards are installed in the same system. The sio driver does not -support more than 1 AST/4 on one IRQ. +AST/4 cards are installed in the same system. +The +.Nm +driver does not support more than 1 AST/4 on one IRQ. .Pp The examples in the synopsis are too vendor-specific. Index: head/share/man/man4/sl.4 =================================================================== --- head/share/man/man4/sl.4 (revision 117010) +++ head/share/man/man4/sl.4 (revision 117011) @@ -1,80 +1,82 @@ .\" $NetBSD: sl.4,v 1.1 1996/08/10 21:26:14 explorer Exp $ .\" .\" 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. .\" .\" From: @(#)lo.4 8.1 (Berkeley) 6/5/93 .\" $FreeBSD$ .\" .Dd August 10, 1996 .Dt SL 4 .Os .Sh NAME .Nm sl .Nd slip network interface .Sh SYNOPSIS .Cd "device sl" Op Ar count .Sh DESCRIPTION The .Nm interface allows serial lines to be used as network interfaces using the .Em slip -protocol. The +protocol. +The .Nm interface can use Van Jacobson TCP header compression and ICMP filtering. This is arranged by using the various link-level flags to the .Xr ifconfig 8 command: .Pp .Bl -tag -width LINK0X -compact .It Em link0 Enable VJ header compression. .It Em link1 Suppress ICMP traffic. .It Em link2 -Enable VJ header compression autodetection. This will turn on the +Enable VJ header compression autodetection. +This will turn on the .Em link0 flag as soon as the first VJ-compressed packet has been seen by the driver. .El .Sh DIAGNOSTICS .Bl -diag .It sl%d: af%d not supported. The interface was handed a message with addresses formatted in an unsuitable address family; the packet was dropped. .El .Sh SEE ALSO .Xr inet 4 , .Xr intro 4 , .Xr slattach 8 , .Xr sliplogin 8 , .Xr slstat 8 Index: head/share/man/man4/smp.4 =================================================================== --- head/share/man/man4/smp.4 (revision 117010) +++ head/share/man/man4/smp.4 (revision 117011) @@ -1,97 +1,99 @@ .\" Copyright (c) 1997 .\" Steve Passe . 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 developer 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 December 5, 2002 .Dt SMP 4 .Os .Sh NAME .Nm SMP .Nd description of the FreeBSD Symmetric MultiProcessor kernel .Sh SYNOPSIS .Cd options SMP .Sh DESCRIPTION The .Nm kernel implements symmetric multiprocessor support. .Sh COMPATIBILITY Support for multi-processor systems is present for all Tier-1 architectures on .Fx . Currently, this includes alpha, i386, ia64, and sparc64. Support is enabled using .Cd options SMP . On most platforms it is permissible to use the SMP kernel configuration on non-SMP equipped motherboards. The only exception to this rule is the i386 platform. .Pp For i386 systems, the .Nm kernel supports motherboards that follow the Intel MP specification, version 1.4. In addition to .Cd options SMP , i386 also requires .Cd options APIC_IO . The .Xr mptable 1 command may be used to view the status of multi-processor support. .Pp .Fx supports hyperthreading on Intel CPU's on the i386 platform. By default, logical CPUs are not used to execute user processes due to performance penalties under common loads. To allow the logical CPUs to execute user processes, turn off the .Va machdep.hlt_logical_cpus sysctl by setting its value to zero. .Sh SEE ALSO .Xr mptable 1 , .Xr condvar 9 , .Xr msleep 9 , .Xr mtx_pool 9 , .Xr mutex 9 , .Xr sema 9 , .Xr sx 9 .Sh HISTORY The .Nm -kernel's early history is not (properly) recorded. It was developed +kernel's early history is not (properly) recorded. +It was developed in a separate CVS branch until April 26, 1997, at which point it was -merged into 3.0-current. By this date 3.0-current had already been +merged into 3.0-current. +By this date 3.0-current had already been merged with Lite2 kernel code. .Pp .Fx 5.0 introduced support for a host of new synchronization primitives, and a move towards fine-grained kernel locking rather than reliance on a Giant kernel lock. The SMPng Project relied heavily on the support of BSDi, who provided reference source code from the fine-grained SMP implementation found in .Bsx . .Pp .Fx 5.0 also introduced support for SMP on the alpha, ia64, and sparc64 architectures. .Sh AUTHORS .An Steve Passe Aq fsmp@FreeBSD.org Index: head/share/man/man4/syncer.4 =================================================================== --- head/share/man/man4/syncer.4 (revision 117010) +++ head/share/man/man4/syncer.4 (revision 117011) @@ -1,91 +1,92 @@ .\" Copyright (c) 2000 Sheldon Hearn .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd July 14, 2000 .Dt SYNCER 4 .Os .Sh NAME .Nm syncer .Nd file system synchronizer kernel process .Sh SYNOPSIS .Nm .Sh DESCRIPTION The .Nm kernel process helps protect the integrity of disk volumes by flushing volatile cached file system data to disk. .Pp The kernel places all .Xr vnode 9 Ns 's in a number of queues. The .Nm process works through the queues in a round-robin fashion, usually processing one queue per second. For each .Xr vnode 9 on that queue, the .Nm process forces a write out to disk of its dirty buffers. .Pp The usual delay between the time buffers are dirtied and the time they are synced is controlled by the following .Xr sysctl 8 tunable variables: .Bl -column "filedelayXXXX" "DefaultXX" "DescriptionXX" .It Em Variable Ta Em Default Ta Em Description .It Va kern.filedelay Ta 30 Ta "time to delay syncing files" .It Va kern.dirdelay Ta 29 Ta "time to delay syncing directories" .It Va kern.metadelay Ta 28 Ta "time to delay syncing metadata" .El .Sh SEE ALSO .Xr sync 2 , .Xr fsck 8 , .Xr sync 8 , .Xr sysctl 8 .Sh HISTORY The .Nm process is a descendant of the .Sq update command, which appeared in .At v6 , and was usually started by .Pa /etc/rc when the system went multi-user. A kernel initiated .Sq update process first appeared in .Fx 2.0 . .Sh BUGS It is possible on some systems that a .Xr sync 2 occurring simultaneously with a crash may cause -file system damage. See +file system damage. +See .Xr fsck 8 . Index: head/share/man/man4/sysmouse.4 =================================================================== --- head/share/man/man4/sysmouse.4 (revision 117010) +++ head/share/man/man4/sysmouse.4 (revision 117011) @@ -1,473 +1,476 @@ .\" Copyright (c) 1997 .\" John-Mark Gurney. 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 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 John-Mark Gurney AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd December 3, 1997 .Dt SYSMOUSE 4 .Os .Sh NAME .Nm sysmouse .\" .Nd supplies mouse data from syscons for other applications .Nd virtualized mouse driver .Sh SYNOPSIS .In sys/mouse.h .In sys/consio.h .Sh DESCRIPTION The console driver, in conjunction with the mouse daemon .Xr moused 8 , supplies mouse data to the user process in the standardized way via the .Nm driver. This arrangement makes it possible for the console and the user process (such as the .Tn X\ Window System ) to share the mouse. .Pp The user process which wants to utilize mouse operation simply opens .Pa /dev/sysmouse with a .Xr open 2 call and reads mouse data from the device via .Xr read 2 . Make sure that .Xr moused 8 is running, otherwise the user process won't see any data coming from the mouse. .Pp .Ss Operation Levels The .Nm driver has two levels of operation. The current operation level can be referred to and changed via ioctl calls. .Pp The level zero, the basic level, is the lowest level at which the driver offers the basic service to user programs. The .Nm driver provides horizontal and vertical movement of the mouse and state of up to three buttons in the .Tn MouseSystems format as follows. .Pp .Bl -tag -width Byte_1 -compact .It Byte 1 .Bl -tag -width bit_7 -compact .It bit 7 Always one. .It bit 6..3 Always zero. .It bit 2 Left button status; cleared if pressed, otherwise set. .It bit 1 Middle button status; cleared if pressed, otherwise set. Always one, if the device does not have the middle button. .It bit 0 Right button status; cleared if pressed, otherwise set. .El .It Byte 2 The first half of horizontal movement count in two's complement; -128 through 127. .It Byte 3 The first half of vertical movement count in two's complement; -128 through 127. .It Byte 4 The second half of the horizontal movement count in two's complement; -128 through 127. To obtain the full horizontal movement count, add the byte 2 and 4. .It Byte 5 The second half of the vertical movement count in two's complement; -128 through 127. To obtain the full vertical movement count, add the byte 3 and 5. .El .Pp At the level one, the extended level, mouse data is encoded in the standard format .Dv MOUSE_PROTO_SYSMOUSE as defined in .Xr mouse 4 . .\" .Ss Acceleration .\" The .\" .Nm .\" driver can somewhat `accelerate' the movement of the pointing device. .\" The faster you move the device, the further the pointer .\" travels on the screen. .\" The driver has an internal variable which governs the effect of .\" the acceleration. Its value can be modified via the driver flag .\" or via an ioctl call. .Sh IOCTLS This section describes two classes of .Xr ioctl 2 commands: commands for the .Nm driver itself, and commands for the console and the console control drivers. .Ss Sysmouse Ioctls There are a few commands for mouse drivers. General description of the commands is given in .Xr mouse 4 . Following are the features specific to the .Nm driver. .Pp .Bl -tag -width MOUSE -compact .It Dv MOUSE_GETLEVEL Ar int *level .It Dv MOUSE_SETLEVEL Ar int *level These commands manipulate the operation level of the mouse driver. .Pp .It Dv MOUSE_GETHWINFO Ar mousehw_t *hw Returns the hardware information of the attached device in the following -structure. Only the +structure. +Only the .Dv iftype field is guaranteed to be filled with the correct value in the current version of the .Nm driver. .Bd -literal typedef struct mousehw { int buttons; /* number of buttons */ int iftype; /* I/F type */ int type; /* mouse/track ball/pad... */ int model; /* I/F dependent model ID */ int hwid; /* I/F dependent hardware ID */ } mousehw_t; .Ed .Pp The .Dv buttons field holds the number of buttons detected by the driver. .Pp The .Dv iftype is always .Dv MOUSE_IF_SYSMOUSE . .Pp The .Dv type tells the device type: .Dv MOUSE_MOUSE , .Dv MOUSE_TRACKBALL , .Dv MOUSE_STICK , .Dv MOUSE_PAD , or .Dv MOUSE_UNKNOWN . .Pp The .Dv model is always .Dv MOUSE_MODEL_GENERIC at the operation level 0. It may be .Dv MOUSE_MODEL_GENERIC or one of .Dv MOUSE_MODEL_XXX constants at higher operation levels. .Pp The .Dv hwid is always zero. .Pp .It Dv MOUSE_GETMODE Ar mousemode_t *mode The command gets the current operation parameters of the mouse driver. .Bd -literal typedef struct mousemode { int protocol; /* MOUSE_PROTO_XXX */ int rate; /* report rate (per sec) */ int resolution; /* MOUSE_RES_XXX, -1 if unknown */ int accelfactor; /* acceleration factor */ int level; /* driver operation level */ int packetsize; /* the length of the data packet */ unsigned char syncmask[2]; /* sync. bits */ } mousemode_t; .Ed .Pp The .Dv protocol field tells the format in which the device status is returned when the mouse data is read by the user program. It is .Dv MOUSE_PROTO_MSC at the operation level zero. .Dv MOUSE_PROTO_SYSMOUSE at the operation level one. .Pp The .Dv rate is always set to -1. .Pp The .Dv resolution is always set to -1. .Pp The .Dv accelfactor is always 0. .Pp The .Dv packetsize field specifies the length of the data packet. It depends on the operation level. .Pp .Bl -tag -width level_0__ -compact .It Em level 0 5 bytes .It Em level 1 8 bytes .El .Pp The array .Dv syncmask holds a bit mask and pattern to detect the first byte of the data packet. .Dv syncmask[0] is the bit mask to be ANDed with a byte. If the result is equal to .Dv syncmask[1] , the byte is likely to be the first byte of the data packet. Note that this method of detecting the first byte is not 100% reliable; thus, it should be taken only as an advisory measure. .Pp .It Dv MOUSE_SETMODE Ar mousemode_t *mode The command changes the current operation parameters of the mouse driver as specified in .Ar mode . Only .Dv level may be modifiable. Setting values in the other field does not generate error and has no effect. .\" .Pp .\" .It Dv MOUSE_GETVARS Ar mousevar_t *vars .\" .It Dv MOUSE_SETVARS Ar mousevar_t *vars .\" These commands are not supported by the .\" .Nm .\" driver. .Pp .It Dv MOUSE_READDATA Ar mousedata_t *data .It Dv MOUSE_READSTATE Ar mousedata_t *state These commands are not supported by the .Nm driver. .Pp .It Dv MOUSE_GETSTATUS Ar mousestatus_t *status The command returns the current state of buttons and movement counts in the structure as defined in .Xr mouse 4 . .El .Ss Console and Consolectl Ioctls The user process issues console .Fn ioctl calls to the current virtual console in order to control the mouse pointer. The console .Fn ioctl also provides a method for the user process to receive a .Xr signal 3 when a button is pressed. .Pp The mouse daemon .Xr moused 8 uses .Fn ioctl calls to the console control device .Pa /dev/consolectl to inform the console of mouse actions including mouse movement and button status. .Pp Both classes of .Fn ioctl commands are defined as .Dv CONS_MOUSECTL which takes the following argument. .Bd -literal struct mouse_info { int operation; union { struct mouse_data data; struct mouse_mode mode; struct mouse_event event; } u; }; .Ed .Pp .Bl -tag -width operation -compact .It Dv operation This can be one of .Pp .Bl -tag -width MOUSE_MOVEABS -compact .It Dv MOUSE_SHOW Enables and displays mouse cursor. .It Dv MOUSE_HIDE Disables and hides mouse cursor. .It Dv MOUSE_MOVEABS Moves mouse cursor to position supplied in .Dv u.data . .It Dv MOUSE_MOVEREL Adds position supplied in .Dv u.data to current position. .It Dv MOUSE_GETINFO Returns current mouse position in the current virtual console and button status in .Dv u.data . .It Dv MOUSE_MODE This sets the .Xr signal 3 to be delivered to the current process when a button is pressed. The signal to be delivered is set in .Dv u.mode . .El .Pp The above operations are for virtual consoles. The operations defined below are for the console control device and are used by .Xr moused 8 to pass mouse data to the console driver. .Pp .Bl -tag -width MOUSE_MOVEABS -compact .It Dv MOUSE_ACTION .It Dv MOUSE_MOTIONEVENT These operations take the information in .Dv u.data -and act upon it. Mouse data will be sent to the +and act upon it. +Mouse data will be sent to the .Nm driver if it is open. .Dv MOUSE_ACTION also processes button press actions and sends signal to the process if requested or performs cut and paste operations if the current console is a text interface. .It Dv MOUSE_BUTTONEVENT .Dv u.data specifies a button and its click count. The console driver will use this information for signal delivery if requested or for cut and paste operations if the console is in text mode. .El .Pp .Dv MOUSE_MOTIONEVENT and .Dv MOUSE_BUTTONEVENT are newer interface and are designed to be used together. They are intended to replace functions performed by .Dv MOUSE_ACTION alone. .Pp .It Dv u This union is one of .Pp .Bl -tag -width data -compact .It Dv data .Bd -literal struct mouse_data { int x; int y; int z; int buttons; }; .Ed .Pp .Dv x , .Dv y and .Dv z represent movement of the mouse along respective directions. .Dv buttons tells the state of buttons. It encodes up to 31 buttons in the bit 0 though -the bit 30. If a button is held down, the corresponding bit is set. +the bit 30. +If a button is held down, the corresponding bit is set. .Pp .It Dv mode .Bd -literal struct mouse_mode { int mode; int signal; }; .Ed .Pp The .Dv signal field specifies the signal to be delivered to the process. It must be one of the values defined in .Ao Pa signal.h Ac . The .Dv mode field is currently unused. .Pp .It Dv event .Bd -literal struct mouse_event { int id; int value; }; .Ed .Pp The .Dv id field specifies a button number as in .Dv u.data.buttons . Only one bit/button is set. The .Dv value field holds the click count: the number of times the user has clicked the button successively. .Pp .El .El .Sh FILES .Bl -tag -width /dev/consolectl -compact .It Pa /dev/consolectl device to control the console .It Pa /dev/sysmouse virtualized mouse driver .It Pa /dev/ttyv%d virtual consoles .El .Sh SEE ALSO .Xr vidcontrol 1 , .Xr ioctl 2 , .Xr signal 3 , .Xr mouse 4 , .Xr moused 8 .Sh HISTORY The .Nm manual page example first appeared in .Fx 2.2 . .Sh AUTHORS .An -nosplit This manual page was written by .An John-Mark Gurney Aq gurney_j@efn.org and .An Kazutaka Yokota Aq yokota@FreeBSD.org . Index: head/share/man/man4/termios.4 =================================================================== --- head/share/man/man4/termios.4 (revision 117010) +++ head/share/man/man4/termios.4 (revision 117011) @@ -1,1457 +1,1546 @@ .\" Copyright (c) 1991, 1992, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. 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. .\" .\" @(#)termios.4 8.4 (Berkeley) 4/19/94 .\" $FreeBSD$ .\" .Dd April 19, 1994 .Dt TERMIOS 4 .Os .Sh NAME .Nm termios .Nd general terminal line discipline .Sh SYNOPSIS .In termios.h .Sh DESCRIPTION This describes a general terminal line discipline that is supported on tty asynchronous communication ports. .Ss Opening a Terminal Device File When a terminal file is opened, it normally causes the process to wait -until a connection is established. For most hardware, the presence +until a connection is established. +For most hardware, the presence of a connection is indicated by the assertion of the hardware .Dv CARRIER line. If the termios structure associated with the terminal file has the .Dv CLOCAL flag set in the cflag, or if the .Dv O_NONBLOCK flag is set in the .Xr open 2 call, then the open will succeed even without a connection being present. In practice, applications seldom open these files; they are opened by special programs, such as .Xr getty 8 or .Xr rlogind 8 , and become an application's standard input, output, and error files. .Ss Job Control in a Nutshell Every process is associated with a particular process group and session. The grouping is hierarchical: every member of a particular process group is a -member of the same session. This structuring is used in managing groups +member of the same session. +This structuring is used in managing groups of related processes for purposes of .\" .Gw "job control" ; .Em "job control" ; that is, the ability from the keyboard (or from program control) to simultaneously stop or restart a complex command (a command composed of one or more related -processes). The grouping into process groups allows delivering +processes). +The grouping into process groups allows delivering of signals that stop or start the group as a whole, along with arbitrating which process group has access to the single controlling -terminal. The grouping at a higher layer into sessions is to restrict +terminal. +The grouping at a higher layer into sessions is to restrict the job control related signals and system calls to within processes -resulting from a particular instance of a "login". Typically, a session +resulting from a particular instance of a +.Dq login . +Typically, a session is created when a user logs in, and the login terminal is setup to be the controlling terminal; all processes spawned from that login shell are in the same session, and inherit the controlling terminal. .Pp A job control shell operating interactively (that is, reading commands from a terminal) normally groups related processes together by placing them into the -same process group. A set of processes in the same process group -is collectively referred to as a "job". When the foreground process +same process group. +A set of processes in the same process group +is collectively referred to as a +.Dq job . +When the foreground process group of the terminal is the same as the process group of a particular -job, that job is said to be in the "foreground". When the process -group of the terminal is different from the process group of +job, that job is said to be in the +.Dq foreground . +When the process group of the terminal is different from the process group of a job (but is still the controlling terminal), that job is said -to be in the "background". Normally the +to be in the +.Dq background . +Normally the shell reads a command and starts the job that implements that -command. If the command is to be started in the foreground (typical), it +command. +If the command is to be started in the foreground (typical), it sets the process group of the terminal to the process group of the started job, waits for the job to complete, and then sets the process group of the terminal back to its own process -group (it puts itself into the foreground). If the job is to +group (it puts itself into the foreground). +If the job is to be started in the background (as denoted by the shell operator "&"), it never changes the process group of the terminal and doesn't wait for the job to complete (that is, it immediately attempts to read the next -command). If the job is started in the foreground, the user may +command). +If the job is started in the foreground, the user may type a key (usually .Ql \&^Z ) which generates the terminal stop signal .Pq Dv SIGTSTP and has the effect of stopping the entire job. The shell will notice that the job stopped, and will resume running after placing itself in the foreground. The shell also has commands for placing stopped jobs in the background, and for placing stopped or background jobs into the foreground. .Ss Orphaned Process Groups An orphaned process group is a process group that has no process whose parent is in a different process group, yet is in the same -session. Conceptually it means a process group that doesn't have -a parent that could do anything if it were to be stopped. For example, +session. +Conceptually it means a process group that doesn't have +a parent that could do anything if it were to be stopped. +For example, the initial login shell is typically in an orphaned process group. Orphaned process groups are immune to keyboard generated stop signals and job control signals resulting from reads or writes to the controlling terminal. .Ss The Controlling Terminal -A terminal may belong to a process as its controlling terminal. Each +A terminal may belong to a process as its controlling terminal. +Each process of a session that has a controlling terminal has the same -controlling terminal. A terminal may be the controlling terminal for at -most one session. The controlling terminal for a session is allocated by +controlling terminal. +A terminal may be the controlling terminal for at +most one session. +The controlling terminal for a session is allocated by the session leader by issuing the .Dv TIOCSCTTY ioctl. A controlling terminal is never acquired by merely opening a terminal device file. When a controlling terminal becomes associated with a session, its foreground process group is set to the process group of the session leader. .Pp The controlling terminal is inherited by a child process during a .Xr fork 2 -function call. A process relinquishes its controlling terminal when it +function call. +A process relinquishes its controlling terminal when it creates a new session with the .Xr setsid 2 function; other processes remaining in the old session that had this terminal as their controlling terminal continue to have it. A process does not relinquish its controlling terminal simply by closing all of its file descriptors associated with the controlling terminal if other processes continue to have it open. .Pp When a controlling process terminates, the controlling terminal is disassociated from the current session, allowing it to be acquired by a -new session leader. Subsequent access to the terminal by other processes +new session leader. +Subsequent access to the terminal by other processes in the earlier session will be denied, with attempts to access the terminal treated as if modem disconnect had been sensed. .Ss Terminal Access Control If a process is in the foreground process group of its controlling terminal, read operations are allowed. Any attempts by a process in a background process group to read from its controlling terminal causes a .Dv SIGTTIN signal to be sent to the process's group unless one of the following special cases apply: If the reading process is ignoring or blocking the .Dv SIGTTIN signal, or if the process group of the reading process is orphaned, the .Xr read 2 returns -1 with .Va errno set to .Er EIO and no signal is sent. The default action of the .Dv SIGTTIN signal is to stop the process to which it is sent. .Pp If a process is in the foreground process group of its controlling terminal, write operations are allowed. Attempts by a process in a background process group to write to its controlling terminal will cause the process group to be sent a .Dv SIGTTOU signal unless one of the following special cases apply: If .Dv TOSTOP is not set, or if .Dv TOSTOP is set and the process is ignoring or blocking the .Dv SIGTTOU signal, the process is allowed to write to the terminal and the .Dv SIGTTOU -signal is not sent. If +signal is not sent. +If .Dv TOSTOP is set, and the process group of the writing process is orphaned, and the writing process is not ignoring or blocking .Dv SIGTTOU , the .Xr write 2 returns -1 with errno set to .Er EIO and no signal is sent. .Pp Certain calls that set terminal parameters are treated in the same fashion as write, except that .Dv TOSTOP is ignored; that is, the effect is identical to that of terminal writes when .Dv TOSTOP is set. .Ss Input Processing and Reading Data A terminal device associated with a terminal device file may operate in full-duplex mode, so that data may arrive even while output is occurring. Each terminal device file has associated with it an input queue, into which incoming data is stored by the system before being read by a process. The system imposes a limit, .Pf \&{ Dv MAX_INPUT Ns \&} , on the number of -bytes that may be stored in the input queue. The behavior of the system +bytes that may be stored in the input queue. +The behavior of the system when this limit is exceeded depends on the setting of the .Dv IMAXBEL flag in the termios .Fa c_iflag . If this flag is set, the terminal is sent an .Tn ASCII .Dv BEL character each time a character is received -while the input queue is full. Otherwise, the input queue is flushed -upon receiving the character. +while the input queue is full. +Otherwise, the input queue is flushed upon receiving the character. .Pp Two general kinds of input processing are available, determined by whether the terminal device file is in canonical mode or noncanonical mode. Additionally, input characters are processed according to the .Fa c_iflag and .Fa c_lflag fields. Such processing can include echoing, which in general means transmitting input characters immediately back to the -terminal when they are received from the terminal. This is useful for -terminals that can operate in full-duplex mode. +terminal when they are received from the terminal. +This is useful for terminals that can operate in full-duplex mode. .Pp The manner in which data is provided to a process reading from a terminal device file is dependent on whether the terminal device file is in canonical or noncanonical mode. .Pp Another dependency is whether the .Dv O_NONBLOCK flag is set by .Xr open 2 or .Xr fcntl 2 . If the .Dv O_NONBLOCK flag is clear, then the read request is -blocked until data is available or a signal has been received. If the +blocked until data is available or a signal has been received. +If the .Dv O_NONBLOCK flag is set, then the read request is completed, without blocking, in one of three ways: .Bl -enum -offset indent .It If there is enough data available to satisfy the entire request, and the read completes successfully the number of bytes read is returned. .It If there is not enough data available to satisfy the entire request, and the read completes successfully, having read as much data as possible, the number of bytes read is returned. .It If there is no data available, the read returns -1, with errno set to .Er EAGAIN . .El .Pp When data is available depends on whether the input processing mode is canonical or noncanonical. .Ss Canonical Mode Input Processing In canonical mode input processing, terminal input is processed in units of lines. A line is delimited by a newline .Ql \&\en character, an end-of-file .Pq Dv EOF character, or an end-of-line .Pq Dv EOL character. See the .Sx "Special Characters" section for more information on .Dv EOF and .Dv EOL . This means that a read request will not return until an entire line has been typed, or a signal has been -received. Also, no matter how many bytes are requested in the read call, -at most one line is returned. It is not, however, necessary to +received. +Also, no matter how many bytes are requested in the read call, +at most one line is returned. +It is not, however, necessary to read a whole line at once; any number of bytes, even one, may be requested in a read without losing information. .Pp .Pf \&{ Dv MAX_CANON Ns \&} is a limit on the number of bytes in a line. The behavior of the system when this limit is exceeded is the same as when the input queue limit .Pf \&{ Dv MAX_INPUT Ns \&} , is exceeded. .Pp Erase and kill processing occur when either of two special characters, the .Dv ERASE and .Dv KILL characters (see the .Sx "Special Characters section" ) , is received. This processing affects data in the input queue that has not yet been delimited by a newline .Dv NL , .Dv EOF , or .Dv EOL character. This un-delimited -data makes up the current line. The +data makes up the current line. +The .Dv ERASE character deletes the last -character in the current line, if there is any. The +character in the current line, if there is any. +The .Dv KILL character -deletes all data in the current line, if there is any. The +deletes all data in the current line, if there is any. +The .Dv ERASE and .Dv KILL characters have no effect if there is no data in the current line. The .Dv ERASE and .Dv KILL characters themselves are not placed in the input queue. .Ss Noncanonical Mode Input Processing In noncanonical mode input processing, input bytes are not assembled into -lines, and erase and kill processing does not occur. The values of the +lines, and erase and kill processing does not occur. +The values of the .Dv VMIN and .Dv VTIME members of the .Fa c_cc array are used to determine how to process the bytes received. .Pp .Dv MIN represents the minimum number of bytes that should be received when the .Xr read 2 function successfully returns. .Dv TIME is a timer of 0.1 second granularity that is used to time out bursty and short term data transmissions. If .Dv MIN is greater than .Dv \&{ Dv MAX_INPUT Ns \&} , the response to the -request is undefined. The four possible values for +request is undefined. +The four possible values for .Dv MIN and .Dv TIME and their interactions are described below. .Ss "Case A: MIN > 0, TIME > 0" In this case .Dv TIME serves as an inter-byte timer and is activated after -the first byte is received. Since it is an inter-byte timer, it is reset -after a byte is received. The interaction between +the first byte is received. +Since it is an inter-byte timer, it is reset +after a byte is received. +The interaction between .Dv MIN and .Dv TIME is as follows: as soon as one byte is received, the inter-byte timer is started. If .Dv MIN bytes are received before the inter-byte timer expires (remember that the timer is reset upon receipt of each byte), the read is -satisfied. If the timer expires before +satisfied. +If the timer expires before .Dv MIN bytes are received, the -characters received to that point are returned to the user. Note that if +characters received to that point are returned to the user. +Note that if .Dv TIME expires at least one byte is returned because the timer would -not have been enabled unless a byte was received. In this case +not have been enabled unless a byte was received. +In this case .Pf \&( Dv MIN > 0, .Dv TIME > 0) the read blocks until the .Dv MIN and .Dv TIME mechanisms are -activated by the receipt of the first byte, or a signal is received. If -data is in the buffer at the time of the +activated by the receipt of the first byte, or a signal is received. +If data is in the buffer at the time of the .Fn read , the result is as if data had been received immediately after the .Fn read . .Ss "Case B: MIN > 0, TIME = 0" In this case, since the value of .Dv TIME is zero, the timer plays no role and only .Dv MIN -is significant. A pending read is not satisfied until +is significant. +A pending read is not satisfied until .Dv MIN bytes are received (i.e., the pending read blocks until .Dv MIN bytes -are received), or a signal is received. A program that uses this case to -read record-based terminal +are received), or a signal is received. +A program that uses this case to read record-based terminal .Dv I/O may block indefinitely in the read operation. .Ss "Case C: MIN = 0, TIME > 0" In this case, since .Dv MIN = 0, .Dv TIME no longer represents an inter-byte -timer. It now serves as a read timer that is activated as soon as the -read function is processed. A read is satisfied as soon as a single -byte is received or the read timer expires. Note that in this case if -the timer expires, no bytes are returned. If the timer does not +timer. +It now serves as a read timer that is activated as soon as the +read function is processed. +A read is satisfied as soon as a single +byte is received or the read timer expires. +Note that in this case if the timer expires, no bytes are returned. +If the timer does not expire, the only way the read can be satisfied is if a byte is received. In this case the read will not block indefinitely waiting for a byte; if no byte is received within .Dv TIME Ns *0.1 seconds after the read is initiated, -the read returns a value of zero, having read no data. If data is +the read returns a value of zero, having read no data. +If data is in the buffer at the time of the read, the timer is started as if data had been received immediately after the read. .Ss Case D: MIN = 0, TIME = 0 The minimum of either the number of bytes requested or the number of bytes currently available is returned without waiting for more -bytes to be input. If no characters are available, read returns a +bytes to be input. +If no characters are available, read returns a value of zero, having read no data. .Ss Writing Data and Output Processing When a process writes one or more bytes to a terminal device file, they are processed according to the .Fa c_oflag field (see the .Sx "Output Modes section). The implementation may provide a buffering mechanism; as such, when a call to .Fn write completes, all of the bytes written have been scheduled for transmission to the device, but the transmission will not necessarily have been completed. .\" See also .Sx "6.4.2" for the effects of .\" .Dv O_NONBLOCK .\" on write. .Ss Special Characters Certain characters have special functions on input or output or both. These functions are summarized as follows: .Bl -tag -width indent .It Dv INTR Special character on input and is recognized if the .Dv ISIG flag (see the .Sx "Local Modes" -section) is enabled. Generates a +section) is enabled. +Generates a .Dv SIGINT signal which is sent to all processes in the foreground process group for which the terminal is the controlling terminal. If .Dv ISIG is set, the .Dv INTR character is discarded when processed. .It Dv QUIT Special character on input and is recognized if the .Dv ISIG -flag is enabled. Generates a +flag is enabled. +Generates a .Dv SIGQUIT signal which is sent to all processes in the foreground process group -for which the terminal is the controlling terminal. If +for which the terminal is the controlling terminal. +If .Dv ISIG is set, the .Dv QUIT character is discarded when processed. .It Dv ERASE Special character on input and is recognized if the .Dv ICANON -flag is set. Erases the last character in the +flag is set. +Erases the last character in the current line; see .Sx "Canonical Mode Input Processing" . It does not erase beyond the start of a line, as delimited by an .Dv NL , .Dv EOF , or .Dv EOL -character. If +character. +If .Dv ICANON is set, the .Dv ERASE character is discarded when processed. .It Dv KILL Special character on input and is recognized if the .Dv ICANON -flag is set. Deletes the entire line, as +flag is set. +Deletes the entire line, as delimited by a .Dv NL , .Dv EOF , or .Dv EOL -character. If +character. +If .Dv ICANON is set, the .Dv KILL character is discarded when processed. .It Dv EOF Special character on input and is recognized if the .Dv ICANON -flag is set. When received, all the bytes +flag is set. +When received, all the bytes waiting to be read are immediately passed to the process, without waiting for a newline, and the .Dv EOF -is discarded. Thus, if there are no bytes waiting (that -is, the +is discarded. +Thus, if there are no bytes waiting (that is, the .Dv EOF occurred at the beginning of a line), a byte count of zero is returned from the .Fn read , -representing an end-of-file indication. If +representing an end-of-file indication. +If .Dv ICANON is set, the .Dv EOF character is discarded when processed. .It Dv NL Special character on input and is recognized if the .Dv ICANON -flag is set. It is the line delimiter +flag is set. +It is the line delimiter .Ql \&\en . .It Dv EOL Special character on input and is recognized if the .Dv ICANON -flag is set. Is an additional line delimiter, -like +flag is set. +Is an additional line delimiter, like .Dv NL . .It Dv SUSP If the .Dv ISIG flag is enabled, receipt of the .Dv SUSP character causes a .Dv SIGTSTP signal to be sent to all processes in the foreground process group for which the terminal is the controlling terminal, and the .Dv SUSP character is discarded when processed. .It Dv STOP Special character on both input and output and is recognized if the .Dv IXON (output control) or .Dv IXOFF (input -control) flag is set. Can be used to temporarily -suspend output. It is useful with fast terminals to +control) flag is set. +Can be used to temporarily suspend output. +It is useful with fast terminals to prevent output from disappearing before it can be read. If .Dv IXON is set, the .Dv STOP character is discarded when processed. .It Dv START Special character on both input and output and is recognized if the .Dv IXON (output control) or .Dv IXOFF (input -control) flag is set. Can be used to resume output that -has been suspended by a +control) flag is set. +Can be used to resume output that has been suspended by a .Dv STOP character. If .Dv IXON is set, the .Dv START character is discarded when processed. .It Dv CR Special character on input and is recognized if the .Dv ICANON flag is set; it is the .Ql \&\er , as denoted in the .Tn \&C -Standard {2}. When +Standard {2}. +When .Dv ICANON and .Dv ICRNL are set and .Dv IGNCR is not set, this character is translated into a .Dv NL , and has the same effect as a .Dv NL character. .El .Pp The following special characters are extensions defined by this system and are not a part of .St -p1003.1 termios. .Bl -tag -width indent .It Dv EOL2 Secondary .Dv EOL character. Same function as .Dv EOL . .It Dv WERASE Special character on input and is recognized if the .Dv ICANON -flag is set. Erases the last word in the current -line according to one of two algorithms. If the +flag is set. +Erases the last word in the current line according to one of two algorithms. +If the .Dv ALTWERASE flag is not set, first any preceding whitespace is erased, and then the maximal sequence of non-whitespace -characters. If +characters. +If .Dv ALTWERASE is set, first any preceding whitespace is erased, and then the maximal sequence of alphabetic/underscores or non alphabetic/underscores. As a special case in this second algorithm, the first previous non-whitespace character is skipped in determining whether the preceding word is a sequence of -alphabetic/underscores. This sounds confusing but turns -out to be quite practical. +alphabetic/underscores. +This sounds confusing but turns out to be quite practical. .It Dv REPRINT Special character on input and is recognized if the .Dv ICANON -flag is set. Causes the current input edit line -to be retyped. +flag is set. +Causes the current input edit line to be retyped. .It Dv DSUSP Has similar actions to the .Dv SUSP character, except that the .Dv SIGTSTP signal is delivered when one of the processes in the foreground process group issues a .Fn read to the controlling terminal. .It Dv LNEXT Special character on input and is recognized if the .Dv IEXTEN -flag is set. Receipt of this character causes the next -character to be taken literally. +flag is set. +Receipt of this character causes the next character to be taken literally. .It Dv DISCARD Special character on input and is recognized if the .Dv IEXTEN -flag is set. Receipt of this character toggles the flushing -of terminal output. +flag is set. +Receipt of this character toggles the flushing of terminal output. .It Dv STATUS Special character on input and is recognized if the .Dv ICANON -flag is set. Receipt of this character causes a +flag is set. +Receipt of this character causes a .Dv SIGINFO signal to be sent to the foreground process group of the -terminal. Also, if the +terminal. +Also, if the .Dv NOKERNINFO flag is not set, it causes the kernel to write a status message to the terminal that displays the current load average, the name of the command in the foreground, its process ID, the symbolic wait channel, the number of user and system seconds used, the percentage of cpu the process is getting, and the resident set size of the process. .El .Pp The .Dv NL and .Dv CR characters cannot be changed. The values for all the remaining characters can be set and are described later in the document under Special Control Characters. .Pp Special character functions associated with changeable special control characters can be disabled individually by setting their value to .Dv {_POSIX_VDISABLE} ; see .Sx "Special Control Characters" . .Pp If two or more special characters have the same value, the function performed when that character is received is undefined. .Ss Modem Disconnect If a modem disconnect is detected by the terminal interface for a controlling terminal, and if .Dv CLOCAL is not set in the .Fa c_cflag field for the terminal, the .Dv SIGHUP signal is sent to the controlling -process associated with the terminal. Unless other arrangements have +process associated with the terminal. +Unless other arrangements have been made, this causes the controlling process to terminate. Any subsequent call to the .Fn read function returns the value zero, -indicating end of file. Thus, processes that read a terminal +indicating end of file. +Thus, processes that read a terminal file and test for end-of-file can terminate appropriately after a disconnect. .\" If the .\" .Er EIO .\" condition specified in 6.1.1.4 that applies .\" when the implementation supports job control also exists, it is .\" unspecified whether the .\" .Dv EOF .\" condition or the .\" .Pf [ Dv EIO .\" ] is returned. Any subsequent .Fn write to the terminal device returns -1, with .Va errno set to .Er EIO , until the device is closed. .Sh General Terminal Interface .Ss Closing a Terminal Device File The last process to close a terminal device file causes any output -to be sent to the device and any input to be discarded. Then, if +to be sent to the device and any input to be discarded. +Then, if .Dv HUPCL is set in the control modes, and the communications port supports a disconnect function, the terminal device performs a disconnect. .Ss Parameters That Can Be Set Routines that need to control certain terminal .Tn I/O characteristics do so by using the termios structure as defined in the header .Aq Pa termios.h . This structure contains minimally four scalar elements of bit flags -and one array of special characters. The scalar flag elements are -named: +and one array of special characters. +The scalar flag elements are named: .Fa c_iflag , .Fa c_oflag , .Fa c_cflag , and .Fa c_lflag . The character array is named .Fa c_cc , and its maximum index is .Dv NCCS . .Ss Input Modes Values of the .Fa c_iflag field describe the basic terminal input control, and are composed of following masks: .Pp .Bl -tag -width IMAXBEL -offset indent -compact .It Dv IGNBRK /* ignore BREAK condition */ .It Dv BRKINT /* map BREAK to SIGINTR */ .It Dv IGNPAR /* ignore (discard) parity errors */ .It Dv PARMRK /* mark parity and framing errors */ .It Dv INPCK /* enable checking of parity errors */ .It Dv ISTRIP /* strip 8th bit off chars */ .It Dv INLCR /* map NL into CR */ .It Dv IGNCR /* ignore CR */ .It Dv ICRNL /* map CR to NL (ala CRMOD) */ .It Dv IXON /* enable output flow control */ .It Dv IXOFF /* enable input flow control */ .It Dv IXANY /* any char will restart after stop */ .It Dv IMAXBEL /* ring bell on input queue full */ .El .Pp In the context of asynchronous serial data transmission, a break condition is defined as a sequence of zero-valued bits that continues for -more than the time to send one byte. The entire sequence of zero-valued +more than the time to send one byte. +The entire sequence of zero-valued bits is interpreted as a single break condition, even if it continues for -a time equivalent to more than one byte. In contexts other than +a time equivalent to more than one byte. +In contexts other than asynchronous serial data transmission the definition of a break condition is implementation defined. .Pp If .Dv IGNBRK is set, a break condition detected on input is ignored, that -is, not put on the input queue and therefore not read by any process. If +is, not put on the input queue and therefore not read by any process. +If .Dv IGNBRK is not set and .Dv BRKINT is set, the break condition flushes the input and output queues and if the terminal is the controlling terminal of a foreground process group, the break condition generates a single .Dv SIGINT -signal to that foreground process group. If neither +signal to that foreground process group. +If neither .Dv IGNBRK nor .Dv BRKINT is set, a break condition is read as a single .Ql \&\e0 , or if .Dv PARMRK is set, as .Ql \&\e377 , .Ql \&\e0 , .Ql \&\e0 . .Pp If .Dv IGNPAR is set, a byte with a framing or parity error (other than break) is ignored. .Pp If .Dv PARMRK is set, and .Dv IGNPAR is not set, a byte with a framing or parity error (other than break) is given to the application as the three-character sequence .Ql \&\e377 , .Ql \&\e0 , X, where .Ql \&\e377 , .Ql \&\e0 is a two-character flag preceding each sequence and X is the data of the character received in error. To avoid ambiguity in this case, if .Dv ISTRIP is not set, a valid character of .Ql \&\e377 is given to the application as .Ql \&\e377 , .Ql \&\e377 . If neither .Dv PARMRK nor .Dv IGNPAR is set, a framing or parity error (other than break) is given to the application as a single character .Ql \&\e0 . .Pp If .Dv INPCK -is set, input parity checking is enabled. If +is set, input parity checking is enabled. +If .Dv INPCK is not set, input parity checking is disabled, allowing output parity generation -without input parity errors. Note that whether input parity checking is +without input parity errors. +Note that whether input parity checking is enabled or disabled is independent of whether parity detection is enabled or disabled (see .Sx "Control Modes" ) . If parity detection is enabled but input parity checking is disabled, the hardware to which the terminal is connected recognizes the parity bit, but the terminal special file does not check whether this bit is set correctly or not. .Pp If .Dv ISTRIP is set, valid input bytes are first stripped to seven bits, otherwise all eight bits are processed. .Pp If .Dv INLCR is set, a received .Dv NL character is translated into a .Dv CR character. If .Dv IGNCR is set, a received .Dv CR character is ignored (not read). If .Dv IGNCR is not set and .Dv ICRNL is set, a received .Dv CR character is translated into a .Dv NL character. .Pp If .Dv IXON -is set, start/stop output control is enabled. A received +is set, start/stop output control is enabled. +A received .Dv STOP character suspends output and a received .Dv START character restarts output. If .Dv IXANY is also set, then any character may restart output. When .Dv IXON is set, .Dv START and .Dv STOP characters are not -read, but merely perform flow control functions. When +read, but merely perform flow control functions. +When .Dv IXON is not set, the .Dv START and .Dv STOP characters are read. .Pp If .Dv IXOFF -is set, start/stop input control is enabled. The system shall -transmit one or more +is set, start/stop input control is enabled. +The system shall transmit one or more .Dv STOP characters, which are intended to cause the terminal device to stop transmitting data, as needed to prevent the input queue from overflowing and causing the undefined behavior described in .Sx "Input Processing and Reading Data" , and shall transmit one or more .Dv START characters, which are intended to cause the terminal device to resume transmitting data, as soon as the device can continue transmitting data without risk of -overflowing the input queue. The precise conditions under which +overflowing the input queue. +The precise conditions under which .Dv STOP and START characters are transmitted are implementation defined. .Pp If .Dv IMAXBEL is set and the input queue is full, subsequent input shall cause an .Tn ASCII .Dv BEL character to be transmitted to the output queue. .Pp The initial input control value after .Fn open is implementation defined. .Ss Output Modes Values of the .Fa c_oflag field describe the basic terminal output control, and are composed of the following masks: .Pp .Bl -tag -width OXTABS -offset indent -compact .It Dv OPOST /* enable following output processing */ .It Dv ONLCR /* map NL to CR-NL (ala .Dv CRMOD ) */ .It Dv OCRNL /* map CR to NL */ .It Dv OXTABS /* expand tabs to spaces */ .It Dv ONOEOT /* discard .Dv EOT Ns 's .Ql \&^D on output) */ .It Dv ONOCR /* do not transmit CRs on column 0 */ .It Dv ONLRET /* on the terminal NL performs the CR function */ .El .Pp If .Dv OPOST is set, the remaining flag masks are interpreted as follows; otherwise characters are transmitted without change. .Pp If .Dv ONLCR is set, newlines are translated to carriage return, linefeeds. .Pp If .Dv OCRNL is set, carriage returns are translated to newlines. .Pp If .Dv OXTABS is set, tabs are expanded to the appropriate number of spaces (assuming 8 column tab stops). .Pp If .Dv ONOEOT is set, .Tn ASCII .Dv EOT Ns 's are discarded on output. .Pp If .Dv ONOCR is set, no CR character is transmitted when at column 0 (first position). .Pp If .Dv ONLRET is set, the NL character is assumed to do the carriage-return function; the column pointer will be set to 0. .Ss Control Modes Values of the .Fa c_cflag field describe the basic terminal hardware control, and are composed of the following masks. Not all values specified are supported by all hardware. .Pp .Bl -tag -width CRTSXIFLOW -offset indent -compact .It Dv CSIZE /* character size mask */ .It Dv CS5 /* 5 bits (pseudo) */ .It Dv CS6 /* 6 bits */ .It Dv CS7 /* 7 bits */ .It Dv CS8 /* 8 bits */ .It Dv CSTOPB /* send 2 stop bits */ .It Dv CREAD /* enable receiver */ .It Dv PARENB /* parity enable */ .It Dv PARODD /* odd parity, else even */ .It Dv HUPCL /* hang up on last close */ .It Dv CLOCAL /* ignore modem status lines */ .It Dv CCTS_OFLOW /* .Dv CTS flow control of output */ .It Dv CRTSCTS /* same as .Dv CCTS_OFLOW */ .It Dv CRTS_IFLOW /* RTS flow control of input */ .It Dv MDMBUF /* flow control output via Carrier */ .El .Pp The .Dv CSIZE bits specify the byte size in bits for both transmission and -reception. The +reception. +The .Fa c_cflag is masked with .Dv CSIZE and compared with the values .Dv CS5 , .Dv CS6 , .Dv CS7 , or .Dv CS8 . -This size does not include the parity bit, if any. If +This size does not include the parity bit, if any. +If .Dv CSTOPB -is set, two stop bits are used, otherwise one stop bit. For example, at -110 baud, two stop bits are normally used. +is set, two stop bits are used, otherwise one stop bit. +For example, at 110 baud, two stop bits are normally used. .Pp If .Dv CREAD -is set, the receiver is enabled. Otherwise, no character is -received. -Not all hardware supports this bit. In fact, this flag -is pretty silly and if it were not part of the +is set, the receiver is enabled. +Otherwise, no character is received. +Not all hardware supports this bit. +In fact, this flag is pretty silly and if it were not part of the .Nm specification it would be omitted. .Pp If .Dv PARENB is set, parity generation and detection are enabled and a parity -bit is added to each character. If parity is enabled, +bit is added to each character. +If parity is enabled, .Dv PARODD specifies odd parity if set, otherwise even parity is used. .Pp If .Dv HUPCL is set, the modem control lines for the port are lowered when the last process with the port open closes the port or the process -terminates. The modem connection is broken. +terminates. +The modem connection is broken. .Pp If .Dv CLOCAL is set, a connection does not depend on the state of the modem -status lines. If +status lines. +If .Dv CLOCAL is clear, the modem status lines are monitored. .Pp Under normal circumstances, a call to the .Fn open function waits for -the modem connection to complete. However, if the +the modem connection to complete. +However, if the .Dv O_NONBLOCK flag is set or if .Dv CLOCAL has been set, the .Fn open function returns immediately without waiting for the connection. .Pp The .Dv CCTS_OFLOW .Pf ( Dv CRTSCTS ) flag is currently unused. .Pp If .Dv MDMBUF is set then output flow control is controlled by the state of Carrier Detect. .Pp If the object for which the control modes are set is not an asynchronous serial connection, some of the modes may be ignored; for example, if an attempt is made to set the baud rate on a network connection to a terminal on another host, the baud rate may or may not be set on the connection between that terminal and the machine it is directly connected to. .Ss Local Modes Values of the .Fa c_lflag field describe the control of various functions, and are composed of the following masks. .Pp .Bl -tag -width NOKERNINFO -offset indent -compact .It Dv ECHOKE /* visual erase for line kill */ .It Dv ECHOE /* visually erase chars */ .It Dv ECHO /* enable echoing */ .It Dv ECHONL /* echo .Dv NL even if .Dv ECHO is off */ .It Dv ECHOPRT /* visual erase mode for hardcopy */ .It Dv ECHOCTL /* echo control chars as ^(Char) */ .It Dv ISIG /* enable signals .Dv INTR , .Dv QUIT , .Dv [D]SUSP */ .It Dv ICANON /* canonicalize input lines */ .It Dv ALTWERASE /* use alternate .Dv WERASE algorithm */ .It Dv IEXTEN /* enable .Dv DISCARD and .Dv LNEXT */ .It Dv EXTPROC /* external processing */ .It Dv TOSTOP /* stop background jobs from output */ .It Dv FLUSHO /* output being flushed (state) */ .It Dv NOKERNINFO /* no kernel output from .Dv VSTATUS */ .It Dv PENDIN /* XXX retype pending input (state) */ .It Dv NOFLSH /* don't flush after interrupt */ .El .Pp If .Dv ECHO -is set, input characters are echoed back to the terminal. If +is set, input characters are echoed back to the terminal. +If .Dv ECHO is not set, input characters are not echoed. .Pp If .Dv ECHOE and .Dv ICANON are set, the .Dv ERASE character causes the terminal to erase the last character in the current line from the display, if -possible. If there is no character to erase, an implementation may echo +possible. +If there is no character to erase, an implementation may echo an indication that this was the case or do nothing. .Pp If .Dv ECHOK and .Dv ICANON are set, the .Dv KILL character causes the current line to be discarded and the system echoes the .Ql \&\en character after the .Dv KILL character. .Pp If .Dv ECHOKE and .Dv ICANON are set, the .Dv KILL character causes the current line to be discarded and the system causes the terminal to erase the line from the display. .Pp If .Dv ECHOPRT and .Dv ICANON are set, the system assumes that the display is a printing device and prints a backslash and the erased characters when processing .Dv ERASE characters, followed by a forward slash. .Pp If .Dv ECHOCTL is set, the system echoes control characters in a visible fashion using a caret followed by the control character. .Pp If .Dv ALTWERASE is set, the system uses an alternative algorithm for determining what constitutes a word when processing .Dv WERASE characters (see .Dv WERASE ) . .Pp If .Dv ECHONL and .Dv ICANON are set, the .Ql \&\en character echoes even if .Dv ECHO is not set. .Pp If .Dv ICANON -is set, canonical processing is enabled. This enables the +is set, canonical processing is enabled. +This enables the erase and kill edit functions, and the assembly of input characters into lines delimited by .Dv NL , .Dv EOF , and .Dv EOL , as described in .Sx "Canonical Mode Input Processing" . .Pp If .Dv ICANON is not set, read requests are satisfied directly from the input -queue. A read is not satisfied until at least +queue. +A read is not satisfied until at least .Dv MIN bytes have been received or the timeout value .Dv TIME -expired between bytes. The time value +expired between bytes. +The time value represents tenths of seconds. See .Sx "Noncanonical Mode Input Processing" for more details. .Pp If .Dv ISIG is set, each input character is checked against the special control characters .Dv INTR , .Dv QUIT , and .Dv SUSP -(job control only). If an input +(job control only). +If an input character matches one of these control characters, the function -associated with that character is performed. If +associated with that character is performed. +If .Dv ISIG is not set, no -checking is done. Thus these special input functions are possible only +checking is done. +Thus these special input functions are possible only if .Dv ISIG is set. .Pp If .Dv IEXTEN is set, implementation-defined functions are recognized -from the input data. How +from the input data. +How .Dv IEXTEN being set interacts with .Dv ICANON , .Dv ISIG , .Dv IXON , or .Dv IXOFF is implementation defined. If .Dv IEXTEN is not set, then implementation-defined functions are not recognized, and the corresponding input characters are not processed as described for .Dv ICANON , .Dv ISIG , .Dv IXON , and .Dv IXOFF . .Pp If .Dv NOFLSH is set, the normal flush of the input and output queues associated with the .Dv INTR , .Dv QUIT , and .Dv SUSP characters are not be done. .Pp If .Dv TOSTOP is set, the signal .Dv SIGTTOU is sent to the process group of a process that tries to write to its controlling terminal if it is not in the foreground process group for -that terminal. This signal, by default, stops the members of the process -group. Otherwise, the output generated by that process is output to the -current output stream. Processes that are blocking or ignoring +that terminal. +This signal, by default, stops the members of the process group. +Otherwise, the output generated by that process is output to the +current output stream. +Processes that are blocking or ignoring .Dv SIGTTOU signals are excepted and allowed to produce output and the .Dv SIGTTOU signal is not sent. .Pp If .Dv NOKERNINFO is set, the kernel does not produce a status message when processing .Dv STATUS characters (see .Dv STATUS ) . .Ss Special Control Characters The special control characters values are defined by the array .Fa c_cc . This table lists the array index, the corresponding special character, -and the system default value. For an accurate list of +and the system default value. +For an accurate list of the system defaults, consult the header file .Aq Pa ttydefaults.h . .Pp .Bl -column "Index Name" "Special Character" -offset indent -compact .It Em "Index Name Special Character Default Value" .It Dv VEOF Ta EOF Ta \&^D .It Dv VEOL Ta EOL Ta _POSIX_VDISABLE .It Dv VEOL2 Ta EOL2 Ta _POSIX_VDISABLE .It Dv VERASE Ta ERASE Ta \&^? Ql \&\e177 .It Dv VWERASE Ta WERASE Ta \&^W .It Dv VKILL Ta KILL Ta \&^U .It Dv VREPRINT Ta REPRINT Ta \&^R .It Dv VINTR Ta INTR Ta \&^C .It Dv VQUIT Ta QUIT Ta \&^\e\e Ql \&\e34 .It Dv VSUSP Ta SUSP Ta \&^Z .It Dv VDSUSP Ta DSUSP Ta \&^Y .It Dv VSTART Ta START Ta \&^Q .It Dv VSTOP Ta STOP Ta \&^S .It Dv VLNEXT Ta LNEXT Ta \&^V .It Dv VDISCARD Ta DISCARD Ta \&^O .It Dv VMIN Ta --- Ta \&1 .It Dv VTIME Ta --- Ta \&0 .It Dv VSTATUS Ta STATUS Ta \&^T .El .Pp If the value of one of the changeable special control characters (see .Sx "Special Characters" ) is .Dv {_POSIX_VDISABLE} , that function is disabled; that is, no input data is recognized as the disabled special character. If .Dv ICANON is not set, the value of .Dv {_POSIX_VDISABLE} has no special meaning for the .Dv VMIN and .Dv VTIME entries of the .Fa c_cc array. .Pp The initial values of the flags and control characters after .Fn open is set according to the values in the header .Aq Pa sys/ttydefaults.h . Index: head/share/man/man4/ti.4 =================================================================== --- head/share/man/man4/ti.4 (revision 117010) +++ head/share/man/man4/ti.4 (revision 117011) @@ -1,314 +1,322 @@ .\" Copyright (c) 1997, 1998, 1999 .\" Bill Paul . 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 Bill Paul. .\" 4. 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 Bill Paul 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 Bill Paul OR THE VOICES IN HIS HEAD .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF .\" THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd June 26, 2002 .Dt TI 4 .Os .Sh NAME .Nm ti .Nd "Alteon Networks Tigon I and Tigon II gigabit ethernet driver" .Sh SYNOPSIS .Cd "device ti" .Cd "options TI_PRIVATE_JUMBOS" .Cd "options TI_JUMBO_HDRSPLIT" .Sh DESCRIPTION The .Nm driver provides support for PCI gigabit ethernet adapters based on the Alteon Networks Tigon gigabit ethernet controller chip. The Tigon contains an embedded R4000 CPU, gigabit MAC, dual DMA channels and a PCI interface unit. The Tigon II contains two R4000 CPUs and other refinements. Either chip can be used in either a 32-bit or 64-bit PCI slot. Communication with the chip is achieved via PCI shared memory and bus master DMA. The Tigon I and II support hardware multicast address filtering, VLAN tag extraction and insertion, and jumbo ethernet frames sizes up to 9000 bytes. Note that the Tigon I chipset is no longer in active production: all new adapters should come equipped with Tigon II chipsets. .Pp There are several PCI boards available from both Alteon and other vendors that use the Tigon chipset under OEM contract. The .Nm driver has been tested with the following Tigon-based adapters: .Pp .Bl -bullet -compact -offset indent .It The Alteon AceNIC V gigabit ethernet adapter (1000baseSX) .It The Alteon AceNIC V gigabit ethernet adapter (1000baseT) .It The 3Com 3c985-SX gigabit ethernet adapter (Tigon 1) .It The 3Com 3c985B-SX gigabit ethernet adapter (Tigon 2) .It The Netgear GA620 gigabit ethernet adapter (1000baseSX) .It The Netgear GA620T gigabit ethernet adapter (1000baseT) .El .Pp The following should also be supported but have not yet been tested: .Pp .Bl -bullet -compact -offset indent .It The Digital EtherWORKS 1000SX PCI Gigabit Adapter .It Silicon Graphics PCI gigabit ethernet adapter .It Farallon PN9000SX Gigabit Ethernet adapter .It Asante PCI 1000BASE-SX Gigabit Ethernet Adapter .It Asante GigaNIX1000T Gigabit Ethernet Adapter .El .Pp While the Tigon chipset supports 10, 100 and 1000Mbps speeds, support for 10 and 100Mbps speeds is only available on boards with the proper transceivers. Most adapters are only designed to work at 1000Mbps, however the driver should support those NICs that work at lower speeds as well. .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. Using jumbo frames can greatly improve performance for certain tasks, such as file transfers and data streaming. .Pp Header splitting support for Tigon 2 boards (this option has no effect for the Tigon 1) can be turned on with the .Dv TI_JUMBO_HDRSPLIT -option. See +option. +See .Xr zero_copy 9 for more discussion on zero copy receive and header splitting. .Pp The .Nm driver normally uses jumbo receive buffers allocated by the .Xr jumbo 9 buffer allocator, but can be configured to use its own private pool of jumbo buffers that are contiguous instead of buffers from the jumbo -allocator, which are made up of multiple page sized chunks. To turn on -private jumbos, use the +allocator, which are made up of multiple page sized chunks. +To turn on private jumbos, use the .Dv TI_PRIVATE_JUMBOS option. .Pp Support for vlans is also available using the .Xr vlan 4 mechanism. See the .Xr vlan 4 man page for more details. .Pp The .Nm driver supports the following media types: .Pp .Bl -tag -width xxxxxxxxxxxxxxxxxxxx .It autoselect Enable autoselection of the media type and options. The user can manually override the autoselected mode by adding media options to the .Pa /etc/rc.conf file. .It 10baseT/UTP Set 10Mbps operation. The .Ar mediaopt option can also be used to select either .Ar full-duplex or .Ar half-duplex modes. .It 100baseTX Set 100Mbps (fast ethernet) operation. The .Ar mediaopt option can also be used to select either .Ar full-duplex or .Ar half-duplex modes. .It 1000baseSX Set 1000Mbps (gigabit ethernet) operation. Only full .Ar full-duplex mode is supported at this speed. .El .Pp The .Nm driver supports the following media options: .Pp .Bl -tag -width xxxxxxxxxxxxxxxxxxxx .It full-duplex Force full duplex operation .It half-duplex Force half duplex operation. .El .Pp For more information on configuring this device, see .Xr ifconfig 8 . .Sh IOCTLS In addition to the standard .Xr socket 2 .Xr ioctl 2 calls implemented by most network drivers, the .Nm driver also includes a character device interface that can be used for -additional diagnostics, configuration and debugging. With this character +additional diagnostics, configuration and debugging. +With this character device interface, and a specially patched version of .Xr gdb 1 , the user can debug firmware running on the Tigon board. .Pp These ioctls and their arguments are defined in the .Aq Pa sys/tiio.h header file. .Bl -tag -width ".Dv ALT_WRITE_TG_MEM" .It Dv TIIOCGETSTATS Return card statistics DMAed from the card into kernel memory approximately every 2 seconds. (That time interval can be changed via the .Dv TIIOCSETPARAMS ioctl.) The argument is .Vt "struct ti_stats" . .It Dv TIIOCGETPARAMS Get various performance-related firmware parameters that largely affect how -interrupts are coalesced. The argument is +interrupts are coalesced. +The argument is .Vt "struct ti_params" . .It Dv TIIOCSETPARAMS Set various performance-related firmware parameters that largely affect how interrupts are coalesced. The argument is .Vt "struct ti_params" . .It Dv TIIOCSETTRACE Tell the NIC to trace the requested types of information. The argument is .Vt ti_trace_type . .It Dv TIIOCGETTRACE -Dump the trace buffer from the card. The argument is +Dump the trace buffer from the card. +The argument is .Vt "struct ti_trace_buf" . .It Dv ALT_ATTACH -This ioctl is used for compatibility with Alteon's Solaris driver. They -apparently only have one character interface for debugging, so they have -to tell it which Tigon instance they want to debug. This ioctl is a noop -for +This ioctl is used for compatibility with Alteon's Solaris driver. +They apparently only have one character interface for debugging, so they have +to tell it which Tigon instance they want to debug. +This ioctl is a noop for .Fx . .It Dv ALT_READ_TG_MEM -Read the requested memory region from the Tigon board. The argument is +Read the requested memory region from the Tigon board. +The argument is .Vt "struct tg_mem" . .It Dv ALT_WRITE_TG_MEM -Write to the requested memory region on the Tigon board. The argument is +Write to the requested memory region on the Tigon board. +The argument is .Vt "struct tg_mem" . .It Dv ALT_READ_TG_REG -Read the requested register on the Tigon board. The argument is +Read the requested register on the Tigon board. +The argument is .Vt "struct tg_reg" . .It Dv ALT_WRITE_TG_REG -Write to the requested register on the Tigon board. The argument is +Write to the requested register on the Tigon board. +The argument is .Vt "struct tg_reg" . .El .Sh FILES .Bl -tag -width ".Pa /dev/ti[0-255]" -compact .It Pa /dev/ti[0-255] Tigon driver character interface. .El .Sh DIAGNOSTICS .Bl -diag .It "ti%d: couldn't map memory" A fatal initialization error has occurred. .It "ti%d: couldn't map interrupt" A fatal initialization error has occurred. .It "ti%d: no memory for softc struct!" The driver failed to allocate memory for per-device instance information during initialization. .It "ti%d: failed to enable memory mapping!" The driver failed to initialize PCI shared memory mapping. This might happen if the card is not in a bus-master slot. .It "ti%d: no memory for jumbo buffers!" The driver failed to allocate memory for jumbo frames during initialization. .It "ti%d: bios thinks we're in a 64 bit slot, but we aren't" The BIOS has programmed the NIC as though it had been installed in a 64-bit PCI slot, but in fact the NIC is in a 32-bit slot. This happens as a result of a bug in some BIOSes. This can be worked around on the Tigon II, but on the Tigon I initialization will fail. .It "ti%d: board self-diagnostics failed!" The ROMFAIL bit in the CPU state register was set after system startup, indicating that the on-board NIC diagnostics failed. .It "ti%d: unknown hwrev" The driver detected a board with an unsupported hardware revision. The .Nm driver supports revision 4 (Tigon 1) and revision 6 (Tigon 2) chips and has firmware only for those devices. .It "ti%d: watchdog timeout" The device has stopped responding to the network, or there is a problem with the network connection (cable). .El .Sh SEE ALSO .Xr arp 4 , .Xr netintro 4 , .Xr ng_ether 4 , .Xr vlan 4 , .Xr ifconfig 8 , .Xr jumbo 9 , .Xr zero_copy 9 .Rs .%T Alteon Gigabit Ethernet/PCI NIC manuals .%O http://sanjose.alteon.com/open.shtml .Re .Sh HISTORY The .Nm device driver first appeared in .Fx 3.0 . .Sh AUTHORS .An -nosplit The .Nm driver was written by .An Bill Paul Aq wpaul@bsdi.com . The header splitting firmware modifications, character .Xr ioctl 2 interface and debugging support were written by .An Kenneth Merry Aq ken@FreeBSD.org . Initial zero copy support was written by .An Andrew Gallatin Aq gallatin@FreeBSD.org . Index: head/share/man/man4/ttcp.4 =================================================================== --- head/share/man/man4/ttcp.4 (revision 117010) +++ head/share/man/man4/ttcp.4 (revision 117011) @@ -1,229 +1,234 @@ .\" Copyright 1994, 1995 Massachusetts Institute of Technology .\" .\" Permission to use, copy, modify, and distribute this software and .\" its documentation for any purpose and without fee is hereby .\" granted, provided that both the above copyright notice and this .\" permission notice appear in all copies, that both the above .\" copyright notice and this permission notice appear in all .\" supporting documentation, and that the name of M.I.T. not be used .\" in advertising or publicity pertaining to distribution of the .\" software without specific, written prior permission. M.I.T. makes .\" no representations about the suitability of this software for any .\" purpose. It is provided "as is" without express or implied .\" warranty. .\" .\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''. M.I.T. DISCLAIMS .\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE, .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT .\" SHALL M.I.T. 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 18, 1995 .Dt TTCP 4 .Os .Sh NAME .Nm ttcp .Nd Transmission Control Protocol Extensions for Transactions .Sh SYNOPSIS .In sys/types.h .In sys/socket.h .In netinet/in.h .In netinet/tcp.h .Ft int .Fn setsockopt sock IPPROTO_TCP TCP_NOPUSH &One "sizeof One" .Ft ssize_t .Fn sendto sock msg len MSG_EOF &sin "sizeof sin" .Ft ssize_t .Fn sendto sock msg len MSG_EOF 0 0 .Sh DESCRIPTION .Tn T/TCP refers to a set of extensions to the .Tn TCP protocol (see .Xr tcp 4 ) which permit hosts to reliably exchange a small amount of data in a two-packet exchange, thus eliminating the extra round-trip delays inherent in a standard .Tn TCP -connection. The socket interface includes modifications to support +connection. +The socket interface includes modifications to support .Tn T/TCP , detailed here for the specific case, and in the .Xr socket 2 and .Xr send 2 manual pages for the protocol-independent support. .Tn T/TCP is defined in RFC 1644. .Pp The .Tn T/TCP extensions work by including certain options in all segments of a particular connection, which enable the implementation to avoid the three-way handshake for all but the first connection between a pair of -hosts. These same options also make it possible to more reliably +hosts. +These same options also make it possible to more reliably recognize old, duplicate packets, which in turn reduces the amount of time the .Tn TCP -protocol must maintain state after a connection closes. The +protocol must maintain state after a connection closes. +The .Dq Li net.inet.tcp.rfc1644 MIB variable can be used to disable .Tn T/TCP negotiation at run time; however, the protocol has been designed to ensure that attempts by non-T/TCP systems to communicate with T/TCP-enhanced ones automatically degenerate into standard .Tn TCP . .Sh TRANSACTION MODEL The expected model of a .Dq transaction as used by .Tn T/TCP is a fairly simple one: .Bl -enum .It A client program generates a request to be sent to the server, which is small enough to fit in a single .Tn TCP segment, and sends a SYN PUSH FIN segment with options and data to the server. .It The server program accepts the request in the same manner as for regular .Tn TCP connections, interprets it, and generates a reply which may be small -enough to fit in a single segment. If it is, the reply is sent in a +enough to fit in a single segment. +If it is, the reply is sent in a single SYN PUSH FIN ACK segment with (different) options and data back -to the client. If not, then the connection degenerates into (almost) -the usual case for +to the client. +If not, then the connection degenerates into (almost) the usual case for .Tn TCP . The server then closes its socket. .It The client reads the reply and closes its socket. .El .Sh CLIENT SUPPORT Support on the client side is provided by extending the semantics of the .Xr sendto 2 and .Xr sendmsg 2 system calls to understand the notion of .Dq implied connect and .Dq send and shutdown . To send the request in a transaction, the .Xr sendto 2 system call is typically used, as in the following example: .Bd -literal -offset indent char request[REQ_LEN]; struct sockaddr_in sin; int sock, req_len; sock = socket(PF_INET, SOCK_STREAM, 0); /* prepare request[] and sin */ err = sendto(sock, request, req_len, MSG_EOF, (struct sockaddr *)&sin, sin.sin_len); /* do something if error */ req_len = read(sock, request, sizeof request); close(sock); /* do something with the reply */ .Ed .Pp Note that, after the call to .Fn sendto , the socket is now in the same state as if the .Xr connect 2 and .Xr shutdown 2 -system calls had been used. That is to say, the only reasonable -operations to perform on this socket are +system calls had been used. +That is to say, the only reasonable operations to perform on this socket are .Xr read 2 and .Xr close 2 . -(Because the client's +(As the client's .Tn TCP sender is already shut down, it is not possible to .Xr connect 2 this socket to another destination.) .Sh SERVER SUPPORT There are two different options available for servers using .Tn T/TCP : .Bl -enum .It Set the .Dv TCP_NOPUSH socket option, and use normal .Xr write 2 calls when formulating the response. .It Use .Xr sendto 2 with the .Dv MSG_EOF flag, as in the client, but with the destination unspecified. .El .Pp The first option is generally the appropriate choice when converting existing servers to use .Tn T/TCP extensions; simply add a call to .Fn setsockopt sock IPPROTO_TCP TCP_NOPUSH &One "sizeof One" (where .Va One -is an integer variable with a non-zero value). The server socket must +is an integer variable with a non-zero value). +The server socket must be closed before any data is sent (unless the socket buffers fill up). .Pp The second option is preferable for new servers, and is sometimes easy -enough to retrofit into older servers. In this case, where the reply -phase would ordinarily have included a call to +enough to retrofit into older servers. +In this case, where the reply phase would ordinarily have included a call to .Fn write , one substitutes: .Pp .Dl "sendto(sock, buf, len, MSG_EOF, (struct sockaddr *)0, 0)" .Pp In this case, the reply is sent immediately, but as in the client case, the socket is no longer useful for anything and should be immediately closed. .Sh MIB VARIABLES The .Tn T/TCP extensions require the .Dq Li net.inet.tcp.rfc1644 MIB variable to be true in order for the appropriate .Tn TCP options to be sent. See .Xr tcp 4 for more information. .Sh SEE ALSO .Xr send 2 , .Xr setsockopt 2 , .Xr inet 4 , .Xr tcp 4 .Rs .%A R. Braden .%T "T/TCP \- TCP Extensions for Transactions" .%O RFC 1644 .Re .Sh HISTORY Support for .Tn T/TCP first appeared in .Fx 2.1 , based on code written by Bob Braden and Liming Wei at the University of Southern California, Information Sciences Institute, and ported by Andras Olah at the University of Twente. Index: head/share/man/man4/tty.4 =================================================================== --- head/share/man/man4/tty.4 (revision 117010) +++ head/share/man/man4/tty.4 (revision 117011) @@ -1,412 +1,425 @@ .\" Copyright (c) 1991, 1992, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. 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. .\" .\" @(#)tty.4 8.3 (Berkeley) 4/19/94 .\" $FreeBSD$ .\" .Dd August 14, 1992 .Dt TTY 4 .Os .Sh NAME .Nm tty .Nd general terminal interface .Sh SYNOPSIS .In sys/ioctl.h .Sh DESCRIPTION This section describes the interface to the terminal drivers in the system. .Ss Terminal Special Files Each hardware terminal port on the system usually has a terminal special device file associated with it in the directory ``/dev/'' (for example, ``/dev/tty03''). When a user logs into the system on one of these hardware terminal ports, the system has already opened the associated device and prepared the line for normal interactive use (see .Xr getty 8 . ) There is also a special case of a terminal file that connects not to a hardware terminal port, but to another program on the other side. These special terminal devices are called .Em ptys and provide the mechanism necessary to give users the same interface to the system when logging in over a network (using .Xr rlogin 1 , or .Xr telnet 1 -for example). Even in these cases the details of how the terminal +for example). +Even in these cases the details of how the terminal file was opened and set up is already handled by special software in the system. Thus, users do not normally need to worry about the details of -how these lines are opened or used. Also, these lines are often used +how these lines are opened or used. +Also, these lines are often used for dialing out of a system (through an out-calling modem), but again the system provides programs that hide the details of accessing these terminal special files (see .Xr tip 1 ) . .Pp When an interactive user logs in, the system prepares the line to behave in a certain way (called a .Em "line discipline" ) , the particular details of which is described in .Xr stty 1 at the command level, and in .Xr termios 4 -at the programming level. A user may be concerned with changing +at the programming level. +A user may be concerned with changing settings associated with his particular login terminal and should refer -to the preceding man pages for the common cases. The remainder of -this man page is concerned +to the preceding man pages for the common cases. +The remainder of this man page is concerned with describing details of using and controlling terminal devices at a low level, such as that possibly required by a program wishing to provide features similar to those provided by the system. .Ss Line disciplines A terminal file is used like any other file in the system in that it can be opened, read, and written to using standard system -calls. For each existing terminal file, there is a software processing module +calls. +For each existing terminal file, there is a software processing module called a .Em "line discipline" is associated with it. The .Em "line discipline" essentially glues the low level device driver code with the high level generic interface routines (such as .Xr read 2 and .Xr write 2 ) , and is responsible for implementing the semantics associated -with the device. When a terminal file is first opened by a program, -the default +with the device. +When a terminal file is first opened by a program, the default .Em "line discipline" called the .Dv termios -line discipline is associated with the file. This is the primary +line discipline is associated with the file. +This is the primary line discipline that is used in most cases and provides the semantics -that users normally associate with a terminal. When the +that users normally associate with a terminal. +When the .Dv termios line discipline is in effect, the terminal file behaves and is operated according to the rules described in .Xr termios 4 . Please refer to that man page for a full description of the terminal semantics. The operations described here generally represent features common across all .Em "line disciplines" , however some of these calls may not make sense in conjunction with a line discipline other than .Dv termios , and some may not be supported by the underlying hardware (or lack thereof, as in the case of ptys). .Ss Terminal File Operations All of the following operations are invoked using the .Xr ioctl 2 -system call. Refer to that man page for a description of -the +system call. +Refer to that man page for a description of the .Em request and .Em argp parameters. In addition to the ioctl .Em requests defined here, the specific line discipline in effect will define other .Em requests specific to it (actually .Xr termios 4 defines them as function calls, not ioctl .Em requests . ) -The following section lists the available ioctl requests. The -name of the request, a description of its purpose, and the typed +The following section lists the available ioctl requests. +The name of the request, a description of its purpose, and the typed .Em argp parameter (if any) are listed. For example, the first entry says .Pp .D1 Em "TIOCSETD int *ldisc" .Pp and would be called on the terminal associated with file descriptor zero by the following code fragment: .Bd -literal int ldisc; ldisc = TTYDISC; ioctl(0, TIOCSETD, &ldisc); .Ed .Ss Terminal File Request Descriptions .Bl -tag -width TIOCGWINSZ .It Dv TIOCSETD Fa int *ldisc Change to the new line discipline pointed to by .Fa ldisc . The available line disciplines are listed in .Aq Pa sys/ttycom.h and currently are: .Pp .Bl -tag -width NETGRAPHDISC -compact .It TTYDISC Termios interactive line discipline. .It TABLDISC Tablet line discipline. .It SLIPDISC Serial IP line discipline. .It PPPDISC PPP line discipline. .It NETGRAPHDISC Netgraph .Xr ng_tty 4 line discipline. .El .Pp .It Dv TIOCGETD Fa int *ldisc Return the current line discipline in the integer pointed to by .Fa ldisc . .It Dv TIOCSBRK Fa void Set the terminal hardware into BREAK condition. .It Dv TIOCCBRK Fa void Clear the terminal hardware BREAK condition. .It Dv TIOCSDTR Fa void Assert data terminal ready (DTR). .It Dv TIOCCDTR Fa void Clear data terminal ready (DTR). .It Dv TIOCGPGRP Fa int *tpgrp Return the current process group with which the terminal is associated in the integer pointed to by .Fa tpgrp . This is the underlying call that implements the .Xr termios 4 .Fn tcgetattr call. .It Dv TIOCSPGRP Fa int *tpgrp Associate the terminal with the process group (as an integer) pointed to by .Fa tpgrp . This is the underlying call that implements the .Xr termios 4 .Fn tcsetattr call. .It Dv TIOCGETA Fa struct termios *term Place the current value of the termios state associated with the device in the termios structure pointed to by .Fa term . This is the underlying call that implements the .Xr termios 4 .Fn tcgetattr call. .It Dv TIOCSETA Fa struct termios *term Set the termios state associated with the device immediately. This is the underlying call that implements the .Xr termios 4 .Fn tcsetattr call with the .Dv TCSANOW option. .It Dv TIOCSETAW Fa struct termios *term First wait for any output to complete, then set the termios state associated with the device. This is the underlying call that implements the .Xr termios 4 .Fn tcsetattr call with the .Dv TCSADRAIN option. .It Dv TIOCSETAF Fa struct termios *term First wait for any output to complete, clear any pending input, then set the termios state associated with the device. This is the underlying call that implements the .Xr termios 4 .Fn tcsetattr call with the .Dv TCSAFLUSH option. .It Dv TIOCOUTQ Fa int *num Place the current number of characters in the output queue in the integer pointed to by .Fa num . .It Dv TIOCSTI Fa char *cp -Simulate typed input. Pretend as if the terminal received the -character pointed to by +Simulate typed input. +Pretend as if the terminal received the character pointed to by .Fa cp . .It Dv TIOCNOTTY Fa void -This call is obsolete but left for compatibility. In the past, when -a process that didn't have a controlling terminal (see +This call is obsolete but left for compatibility. +In the past, when a process that didn't have a controlling terminal (see .Em The Controlling Terminal in .Xr termios 4 ) first opened a terminal device, it acquired that terminal as its -controlling terminal. For some programs this was a hazard as they +controlling terminal. +For some programs this was a hazard as they didn't want a controlling terminal in the first place, and this provided a mechanism to disassociate the controlling terminal from -the calling process. It +the calling process. +It .Em must be called by opening the file .Pa /dev/tty and calling .Dv TIOCNOTTY on that file descriptor. .Pp The current system does not allocate a controlling terminal to a process on an .Fn open call: there is a specific ioctl called .Dv TIOSCTTY to make a terminal the controlling terminal. In addition, a program can .Fn fork and call the .Fn setsid system call which will place the process into its own session - which -has the effect of disassociating it from the controlling terminal. This -is the new and preferred method for programs to lose their controlling +has the effect of disassociating it from the controlling terminal. +This is the new and preferred method for programs to lose their controlling terminal. .It Dv TIOCSTOP Fa void Stop output on the terminal (like typing ^S at the keyboard). .It Dv TIOCSTART Fa void Start output on the terminal (like typing ^Q at the keyboard). .It Dv TIOCSCTTY Fa void Make the terminal the controlling terminal for the process (the process must not currently have a controlling terminal). .It Dv TIOCDRAIN Fa void Wait until all output is drained. .It Dv TIOCEXCL Fa void -Set exclusive use on the terminal. No further opens are permitted -except by root. Of course, this means that programs that are run by +Set exclusive use on the terminal. +No further opens are permitted except by root. +Of course, this means that programs that are run by root (or setuid) will not obey the exclusive setting - which limits the usefulness of this feature. .It Dv TIOCNXCL Fa void -Clear exclusive use of the terminal. Further opens are permitted. +Clear exclusive use of the terminal. +Further opens are permitted. .It Dv TIOCFLUSH Fa int *what If the value of the int pointed to by .Fa what contains the .Dv FREAD bit as defined in .Aq Pa sys/file.h , -then all characters in the input queue are cleared. If it contains -the +then all characters in the input queue are cleared. +If it contains the .Dv FWRITE -bit, then all characters in the output queue are cleared. If the -value of the integer is zero, then it behaves as if both the +bit, then all characters in the output queue are cleared. +If the value of the integer is zero, then it behaves as if both the .Dv FREAD and .Dv FWRITE bits were set (i.e. clears both queues). .It Dv TIOCGWINSZ Fa struct winsize *ws Put the window size information associated with the terminal in the .Va winsize structure pointed to by .Fa ws . The window size structure contains the number of rows and columns (and pixels -if appropriate) of the devices attached to the terminal. It is set by user software +if appropriate) of the devices attached to the terminal. +It is set by user software and is the means by which most full\&-screen oriented programs determine the -screen size. The +screen size. +The .Va winsize structure is defined in .Aq Pa sys/ioctl.h . .It Dv TIOCSWINSZ Fa struct winsize *ws Set the window size associated with the terminal to be the value in the .Va winsize structure pointed to by .Fa ws (see above). .It Dv TIOCCONS Fa int *on If .Fa on points to a non-zero integer, redirect kernel console output (kernel printf's) to this terminal. If .Fa on points to a zero integer, redirect kernel console output back to the normal -console. This is usually used on workstations to redirect kernel messages +console. +This is usually used on workstations to redirect kernel messages to a particular window. .It Dv TIOCMSET Fa int *state The integer pointed to by .Fa state -contains bits that correspond to modem state. Following is a list -of defined variables and the modem state they represent: +contains bits that correspond to modem state. +Following is a list of defined variables and the modem state they represent: .Pp .Bl -tag -width TIOCMXCTS -compact .It TIOCM_LE Line Enable. .It TIOCM_DTR Data Terminal Ready. .It TIOCM_RTS Request To Send. .It TIOCM_ST Secondary Transmit. .It TIOCM_SR Secondary Receive. .It TIOCM_CTS Clear To Send. .It TIOCM_CAR Carrier Detect. .It TIOCM_CD Carrier Detect (synonym). .It TIOCM_RNG Ring Indication. .It TIOCM_RI Ring Indication (synonym). .It TIOCM_DSR Data Set Ready. .El .Pp This call sets the terminal modem state to that represented by .Fa state . Not all terminals may support this. .It Dv TIOCMGET Fa int *state Return the current state of the terminal modem lines as represented above in the integer pointed to by .Fa state . .It Dv TIOCMBIS Fa int *state The bits in the integer pointed to by .Fa state represent modem state as described above, however the state is OR-ed in with the current state. .It Dv TIOCMBIC Fa int *state The bits in the integer pointed to by .Fa state represent modem state as described above, however each bit which is on in .Fa state is cleared in the terminal. .El .Sh IMPLEMENTATION NOTES The total number of input and output bytes through all terminal devices are available via the .Va kern.tk_nin and .Va kern.tk_nout read-only .Xr sysctl 8 variables. .Sh SEE ALSO .Xr stty 1 , .Xr ioctl 2 , .Xr ng_tty 4 , .Xr pty 4 , .Xr termios 4 , .Xr getty 8 Index: head/share/man/man4/udp.4 =================================================================== --- head/share/man/man4/udp.4 (revision 117010) +++ head/share/man/man4/udp.4 (revision 117011) @@ -1,167 +1,170 @@ .\" 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. .\" .\" @(#)udp.4 8.1 (Berkeley) 6/5/93 .\" $FreeBSD$ .\" .Dd June 5, 1993 .Dt UDP 4 .Os .Sh NAME .Nm udp .Nd Internet User Datagram Protocol .Sh SYNOPSIS .In sys/types.h .In sys/socket.h .In netinet/in.h .Ft int .Fn socket AF_INET SOCK_DGRAM 0 .Sh DESCRIPTION .Tn UDP is a simple, unreliable datagram protocol which is used to support the .Dv SOCK_DGRAM abstraction for the Internet protocol family. .Tn UDP 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 recv 2 or .Xr read 2 and .Xr send 2 or .Xr write 2 system calls may be used). .Pp .Tn UDP address formats are identical to those used by .Tn TCP . In particular .Tn UDP provides a port identifier in addition -to the normal Internet address format. Note that the +to the normal Internet address format. +Note that the .Tn UDP port space is separate from the .Tn TCP port space (i.e. a .Tn UDP port may not be .Dq connected to a .Tn TCP -port). In addition broadcast +port). +In addition broadcast packets may be sent (assuming the underlying network supports this) by using a reserved .Dq broadcast address ; this address is network interface dependent. .Pp Options at the .Tn IP transport level may be used with .Tn UDP ; see .Xr ip 4 . .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 hasn't been connected; .It Bq Er ENOBUFS when the system runs out of memory for an internal data structure; .It Bq Er EADDRINUSE when an attempt is made to create a socket with a port which has already been allocated; .It Bq Er EADDRNOTAVAIL when an attempt is made to create a socket with a network address for which no network interface exists. .El .Sh MIB VARIABLES The .Nm protocol implements a number of variables in the .Li net.inet branch of the .Xr sysctl 3 MIB. .Bl -tag -width UDPCTL_RECVSPACEX .It UDPCTL_CHECKSUM .Pq udp.checksum Enable udp checksums (enabled by default). .It UDPCTL_MAXDGRAM .Pq udp.maxdgram Maximum outgoing UDP datagram size .It UDPCTL_RECVSPACE .Pq udp.recvspace Maximum space for incoming UDP datagrams .It udp.log_in_vain For all udp datagrams, to ports on which there is no socket listening, log the connection attempt (disabled by default). .It udp.blackhole When a datagram is received on a port where there is no socket listening, do not return an ICMP port unreachable message. -(Disabled by default. See +(Disabled by default. +See .Xr blackhole 4 . ) .El .Sh SEE ALSO .Xr getsockopt 2 , .Xr recv 2 , .Xr send 2 , .Xr socket 2 , .Xr blackhole 4 , .Xr inet 4 , .Xr intro 4 , .Xr ip 4 .Sh HISTORY The .Nm protocol appeared in .Bx 4.2 .