Add od(4). Closes PR# 3170.

Submitted by:	Shunsuke Akiyama <akiyama@jp.freebsd.org>

2 files changed, 289 insertions, 1 deletions

diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
index de7e346..a674156 100644
--- a/share/man/man4/Makefile
+++ b/share/man/man4/Makefile
@@ -3,7 +3,7 @@
 MAN4=	bpf.4 ccd.4 cd.4 ch.4 ddb.4 divert.4 drum.4 fd.4 fpa.4 \
 	icmp.4 ifmib.4 inet.4 intro.4 ip.4 ipfirewall.4 \
 	lkm.4 lo.4 netintro.4 \
-	null.4 ppp.4 pt.4 pty.4 route.4 \
+	null.4 od.4 ppp.4 pt.4 pty.4 route.4 \
 	scsi.4 sd.4 sl.4 snp.4 st.4 su.4 tcp.4 \
 	ttcp.4 termios.4 tty.4 udp.4 uk.4 update.4 unix.4 vn.4 worm.4 yp.4 \
 	zero.4
diff --git a/share/man/man4/od.4 b/share/man/man4/od.4
new file mode 100644
index 0000000..ef5b023
--- /dev/null
+++ b/share/man/man4/od.4
@@ -0,0 +1,288 @@
+.\" Copyright (c) 1996,1997 Shunsuke Akiyama <akiyama@jp.FreeBSD.org>.
+.\"   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 Shunsuke Akiyama.
+.\" 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 Shunsuke Akiyama 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 Shunsuke Akiyama 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$
+.\"
+.Dd March 16, 1997
+.Dt OD 4
+.Os FreeBSD
+.Sh NAME
+.Nm od
+.Nd SCSI optical disk driver
+.Sh SYNOPSIS
+.Cd device od
+.Cd device od1 at scbus0 target 3 lun 0
+.Pp
+To use a drive which returns bogus ASC/ASCQ values:
+.Cd options OD_BOGUS_NOT_READY
+.Pp
+To enable an automatic spindown:
+.Cd options OD_AUTO_TURNOFF
+.Sh DESCRIPTION
+The
+.Nm
+driver provides support for a
+.Em SCSI
+optical disk (AKA. Magneto-Optical or Phase change optical Disk) drive.
+It enables the media change operation and the disk to be divided
+up into a set of pseudo devices called
+.Em partitions .
+A partition has both a 
+.Em raw
+interface
+and a
+.Em block mode
+interface.
+In general the interfaces are similar to those described by 
+.Xr wd 4
+and
+.Xr sd 4 .
+.Pp
+As the SCSI adapter is probed during boot, the 
+.Em SCSI
+bus is scanned for devices. Any devices found which answered as
+.Sq Em Optical
+and
+.Sq Em removable
+type device will be attached to the 
+.Nm
+driver.
+In
+.Fx 2.1.5
+or later, the first device found will be attached as
+.Em od0
+and the next, 
+.Em od1 ,
+and so on.
+It is possible to specify which od unit a device should
+come on line as; refer to
+.Xr scsi 4
+for details on kernel configuration.
+Beginning in
+.Fx 2.2
+the
+.Nm
+driver can handle any device which answers as being type
+.Sq Em Direct
+and
+.Sq Em removable
+as well as
+.Sq Em Optical
+and
+.Sq Em removable
+type devices.
+.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
+.Tn FreeBSD
+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
+.Tn FreeBSD
+slices into areas for individual filesystems.
+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
+.Tn FreeBSD
+slice spanning the entire disk.  Similarly, if an uninitialized
+(or
+.No non- Ns Tn FreeBSD )
+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 KERNEL CONFIGURATION
+Only one
+.Nm
+device is necessary in the config file; data structures are dynamically
+allocated as disks are found on the
+.Tn SCSI
+bus.
+.Sh IOCTLS
+The following 
+.Xr ioctl 2
+calls apply to optical disks as well as to other disks.
+They are defined in the header file
+.Aq Pa sys/disklabel.h .
+.Pp
+.Bl -tag -width CDIOCPREVENT
+.It Dv DIOCSBAD
+Usually used to set up a bad-block mapping system on the disk. SCSI
+drives incorporate their own bad-block mapping so this is not
+implemented, however it MAY be implemented in the future as a 'kludged'
+interface to the SCSI bad-block mapping.
+.It Dv DIOCGDINFO
+Read the in-core copy of the disklabel for the
+drive from the kernel. This may be a fictitious disklabel if the drive 
+has never been initialised, in which case it will contain information read
+from the SCSI inquiry commands, and should be the same as
+the information printed at boot.
+.It Dv DIOCSDINFO
+Give the driver a new disklabel to use. The driver will NOT try 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 WILL try write the
+new disklabel to the disk.
+.El
+.Pp
+And the following
+.Xr ioctl 2
+calls which apply to optical disks are defined in the header file
+.Aq Pa sys/cdio.h .
+.Bl -tag -width CDIOCPREVENT
+.It Dv CDIOCEJECT
+Eject the optical disk media.
+.It Dv CDIOCALLOW
+Tell the drive to allow manual ejection of the optical disk media.
+.It Dv CDIOCPREVENT
+Tell the drive to prevent manual ejection of the optical disk media.
+.El
+.Pp
+In addition, the 
+.Xr scsi 4
+general ioctls may be used with the 
+.Nm
+driver, but only against the fourth (whole disk) partition.
+.Sh NOTES
+Currently the
+.Nm
+driver accepts 512, 1024 and 2048 byte/sector media.
+Raw and block mode device access to non-512 byte/sector media
+would be allowed only on each sector size boundary start position and 
+I/O size.
+.Sh FILES
+.Bl -tag -width /dev/rodXXXXX -compact
+.It Pa /dev/rod Ns Ar u
+raw mode
+.Tn SCSI
+optical disk unit
+.Ar u ,
+accessed as an unpartitioned device
+.Sm off
+.It Pa /dev/od Ar u Pa s Ar n
+.Sm on
+block mode
+.Tn SCSI
+optical disk unit
+.Ar u ,
+slice
+.Ar n ,
+accessed as an unpartitioned device
+.Sm off
+.It Pa /dev/rod Ar u Pa s Ar n
+.Sm on
+raw mode
+.Tn SCSI
+optical disk unit
+.Ar u ,
+slice
+.ar n ,
+accessed as an unpartitioned device
+.It Pa /dev/od Ns Ar u Ns Ar p
+block mode
+.Tn SCSI
+optical disk unit
+.Ar u ,
+first
+.Tn FreeBSD
+slice, partition
+.Ar p
+.It Pa /dev/rod Ns Ar u Ns Ar p
+raw mode
+.Tn SCSI
+optical disk unit
+.Ar u ,
+first
+.Tn FreeBSD
+slice, partition
+.Ar p
+.Sm off
+.It Xo
+.Pa /dev/od Ar u Pa s Ar n Ar p
+.Xc
+.Sm on
+block mode
+.Tn SCSI
+optical disk unit
+.Ar u ,
+.No Ar n Ns th
+slice, partition
+.Ar p
+.Sm off
+.It Xo
+.Pa /dev/rod Ar u Pa s Ar n Ar p
+.Xc
+raw mode
+.Tn SCSI
+optical disk unit
+.Ar u ,
+.No Ar n Ns th
+slice, partition
+.Ar p
+.Sm off
+.It Xo
+.Pa /dev/rod Ar u Pa .ctl
+.Xc
+the control device unit
+.Ar u ,
+as being used by
+.Xr scsi 8
+.El
+.Sh DIAGNOSTICS
+None.
+.Sh SEE ALSO
+.Xr fdisk 1 ,
+.Xr scsi 4 ,
+.Xr sd 4 ,
+.Xr cd 4 ,
+.Xr disklabel 5 ,
+.Xr disklabel 8
+.Sh AUTHOR
+Shunsuke Akiyama <akiyama@jp.FreeBSD.org>
+.Sh HISTORY
+The
+.Nm
+driver first appeared in
+.Fx 2.1.5 .