Index: bktr.4 =================================================================== RCS file: /home/ncvs/src/share/man/man4/bktr.4,v retrieving revision 1.20 diff -u -p -r1.20 bktr.4 --- bktr.4 28 Mar 2002 17:03:21 -0000 1.20 +++ bktr.4 18 Jun 2003 08:45:19 -0000 @@ -20,8 +20,9 @@ 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 @@ -62,7 +63,8 @@ The following kernel parameters may be u .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 Index: ch.4 =================================================================== RCS file: /home/ncvs/src/share/man/man4/ch.4,v retrieving revision 1.29 diff -u -p -r1.29 ch.4 --- ch.4 21 Jan 2002 12:09:13 -0000 1.29 +++ ch.4 18 Jun 2003 08:13:21 -0000 @@ -40,7 +40,8 @@ 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 @@ -75,10 +76,11 @@ so a large number of configured devices 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). @@ -99,9 +101,11 @@ in the header file .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 @@ -111,17 +115,24 @@ u_int cm_totype; /* element type to mo 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 */ @@ -132,32 +143,41 @@ u_int ce_sdsttype; /* element type of se 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 @@ -168,27 +188,36 @@ 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 @@ -201,25 +230,36 @@ struct changer_element_status *cesr_elem .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 */ @@ -236,11 +276,16 @@ u_char ces_lunvalid; /* ces_s 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. Index: ifmib.4 =================================================================== RCS file: /home/ncvs/src/share/man/man4/ifmib.4,v retrieving revision 1.17 diff -u -p -r1.17 ifmib.4 --- ifmib.4 30 Aug 2002 10:52:17 -0000 1.17 +++ ifmib.4 18 Jun 2003 08:17:15 -0000 @@ -51,14 +51,16 @@ to client applications such as .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 @@ -71,7 +73,8 @@ 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 @@ -147,8 +150,10 @@ more information from a structure define .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 Index: intro.4 =================================================================== RCS file: /home/ncvs/src/share/man/man4/intro.4,v retrieving revision 1.26 diff -u -p -r1.26 intro.4 --- intro.4 25 Mar 2003 12:09:06 -0000 1.26 +++ intro.4 18 Jun 2003 08:18:16 -0000 @@ -37,10 +37,12 @@ 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 @@ -48,7 +50,8 @@ 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 , @@ -79,7 +82,8 @@ Note that this could lead to an inconsis 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 . @@ -92,7 +96,8 @@ 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 @@ -100,11 +105,13 @@ as the file type identification in the o .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 @@ -115,7 +122,8 @@ is the corresponding device node for the .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 @@ -126,7 +134,8 @@ file permissions of the device node entr 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 @@ -135,10 +144,11 @@ call .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 @@ -157,13 +167,12 @@ architecture). .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: mem.4 =================================================================== RCS file: /home/ncvs/src/share/man/man4/mem.4,v retrieving revision 1.14 diff -u -p -r1.14 mem.4 --- mem.4 10 Feb 2002 08:52:25 -0000 1.14 +++ mem.4 18 Jun 2003 08:31:43 -0000 @@ -41,19 +41,19 @@ .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 @@ -72,30 +72,32 @@ 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 \(**/ @@ -133,25 +135,32 @@ 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 @@ -185,7 +194,8 @@ Busy range attributes are not yet manage .Xr memcontrol 8 .Sh HISTORY The -.Nm , +.Nm mem +and .Nm kmem files appeared in .At v6 . Index: pcm.4 =================================================================== RCS file: /home/ncvs/src/share/man/man4/pcm.4,v retrieving revision 1.29 diff -u -p -r1.29 pcm.4 --- pcm.4 25 Mar 2003 14:49:02 -0000 1.29 +++ pcm.4 18 Jun 2003 08:33:18 -0000 @@ -83,8 +83,10 @@ 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 Index: sa.4 =================================================================== RCS file: /home/ncvs/src/share/man/man4/sa.4,v retrieving revision 1.34 diff -u -p -r1.34 sa.4 --- sa.4 13 Oct 2001 09:08:30 -0000 1.34 +++ sa.4 18 Jun 2003 08:40:43 -0000 @@ -57,11 +57,13 @@ The 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', @@ -112,16 +114,17 @@ or 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 @@ -136,19 +139,23 @@ 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. +Because 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 @@ -156,15 +163,19 @@ The handling of file marks on write is a 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 @@ -210,13 +221,17 @@ 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