HardenedBSD/share/man/man4/worm.4

.\" 
.\" Copyright (C) 1996
.\"   interface business GmbH
.\"   Tolkewitzer Strasse 49
.\"   D-01277 Dresden
.\"   F.R. Germany
.\"
.\" All rights reserved.
.\"
.\" Written by Joerg Wunsch <joerg_wunsch@interface-business.de>
.\"
.\" 
.\" 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(S) ``AS IS'' AND ANY
.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
.\" OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
.\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
.\" USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
.\" DAMAGE.
.\"
.\" $Id: worm.4,v 1.11 1997/05/19 17:30:50 jmz Exp $
.\" "
.Dd January 27, 1996
.Dt WORM 4
.Os FreeBSD
.Sh NAME
.Nm worm
.Nd write-once (CD-R) disk driver
.Sh SYNOPSIS
.Cd disk worm0
.Cd disk worm0 target 5 lun 0
.Sh DESCRIPTION
The
.Nm worm
driver provides support for a 
.Em SCSI
write-once device, in particular for a CD-R recording device.  The
driver attempts to abstract the dirty hardware work to a common API as
good as possible.  Due to the very special nature of CD-R devices and
their handling requirements, this API applies some more constraints to
the user than those of other disk-like devices.
.Pp
A CD is usually structured into sessions and tracks.  Each track can
hold a different type of data, basically either audio information, or
CD-ROM data.  In order to record a CD-R, the device must be told which
kind of data is to be recorded, at which speed, etc.  Once all tracks
of a session have been written, the medium must finally be
.Em fixated
which basically means that the table of contents will be written, and
the session is marked as usable.  Optionally, a new session can be
enabled at this time, or the disk can be entirely closed to prevent
further writing.
.Pp
One particular feature of all existing CD-R recorders is that they
require a constant data stream while the write channel is open.  This
usually requires some precautions like using a multiple-buffering
filter to read the data from the disk, and/or running at real-time
priority.
.Pp
There is no official standard for CD-R devices, so every vendor seems
to implement his own set of controlling commands.  Some vendors use
rather similar command sets, while other devices behave entirely
different.  The driver has builtin knowledge about the odds and ends
of some devices, which must then be selected first at run-time in
order to make the driver operational at all.  This builtin knowledge
will be replaced by a loadable module scenario in the future.
.Pp
Due to the requirement of adjusting several parameters before actually
being able to write some data to the CD-R, and due to the tight timing
requirements when writing data, the driver distinguishes two different
operation modes.  When opening a file descriptor for a device belonging
to the
.Nm
driver with
.Dv O_NONBLOCK
being set
.Pq see Xr open 2 ,
the driver does not enforce the tight timing that is needed to write
data to the CD-R, but it allows for sending
.Xr ioctl 2
commands to adjust parameters.  Any number of ioctls can be performed
on the device as long as the required sequence of actions is being
maintained.  The first thing that must be done is to select a set of
quirks for the actual device.  Then, the per-session parameters must
be specified.  Each track requires a set of per-track parameters
finally.
.Pp
Once all preparations have been done, the device can be opened with
write intent, at which point the driver starts to activate the
time-critical handling, and is expecting any number of
.Xr write 2
system calls that is required in order to transfer all the data to the
device.  Failure in providing these data in a timely fashion will render
the current medium unusable.  The device-specific sequence for telling
that the current track is finally complete will be issued to the device
when calling
.Xr close 2
on the file descriptor that has been used to write the data.
.Pp
After this happened, things are no longer time-critical.  Any number of
further tracks can be written to the device.  Finally, the session must
be fixated by another ioctl.
.Pp
Opening a read-only file descriptor on a
.Nm worm
device can be used in order to read a normal CD-ROM medium.  No special
preparations are required in this case.
.Sh IOCTLS
The following 
.Xr ioctl 2
calls apply to CD-R devices.  Their declaration can be found in the
header file
.Pa <sys/wormio.h> .
.Bl -tag -width WORMIOFINISHTRACK
.It Dv WORMIOCPREPDISK
This command selects several session-wide parameters in the driver.
The argument structure,
.Dv struct wormio_prepare_disk
takes two integer values,
.Dv dummy ,
and
.Dv speed .
By setting
.Dv dummy
to 1, the drive will be told to simulate all actions, without actually
turning on the laser.  It is mainly used to test the environment
whether it could cope with the timing constraints, without risking a
damaged medium.  The parameter
.Dv speed
is device-dependent, where a speed value of one generally applies to
audio disks, and a speed value of 2 (or more) is used for recording
data.
.It Dv WORMIOCPREPTRACK
This command selects several options for writing the next track.
The argument structure,
.Dv struct wormio_prepare_track
is as follows:
.Bd -literal -offset indent
struct wormio_prepare_track {
	int audio;
	int preemp;
        int track_type;
        int copy_bits; 
        int track_number;
        char ISRC_country[2];
        char ISRC_owner[3];
        int ISRC_year;
        char ISRC_serial[5];
};
.Ed
.Dv audio
should be set to 1 if you are recording an audio track.
If
.Dv preemp
is also set to 1, the audio data are assumed to be recorded with
preemphasis.
.Dv track_type 
defines both the the specific data fields in a user data block and
its size. Currently available types are
.Bl -tag -width BLOCK_MODE_2_FORM_2b
.It Dv BLOCK_RAW
2352 bytes, raw data.
.It Dv BLOCK_RAWPQ
2368 bytes, raw data with P and Q subchannels.
.It Dv BLOCK_RAWPW
2448 bytes, raw data with P-W subchannel appended.
.It Dv BLOCK_MODE_1
2048 bytes, mode 1 (ISO/IEC 10149).
.It Dv BLOCK_MODE_2
2336 bytes, mode 2 (ISO/IEC 10149).
.It Dv BLOCK_MODE_2_FORM_1
2048 bytes, CD-ROM XA form 1.
.It Dv BLOCK_MODE_2_FORM_1b 
2056 bytes, CD-ROM XA form 1.
.It Dv BLOCK_MODE_2_FORM_2
2324 bytes, CD-ROM XA form 2.
.It Dv BLOCK_MODE_2_FORM_2b
2332 bytes, CD-ROM XA form 2.
.El
.Pp
Note that not all track types are supported for a given drive.
.Pp
.Dv copy_bits
define the permissions for copying the track. Available values are
.Bl -tag -width  COPY_PERMITTED
.It Dv COPY_INHIBIT
No copy is allowed.
.It Dv COPY_PERMITTED
The track can be copied.
.It Dv COPY_SCMS 
The track can be copied once.
.El

.Dv track_number :
if the track number is zero, a new track will be created with a track
number one higher than the previous track. If the track number is not
zero, then this track number must point to a reserved track, unless it
is an  empty disc which will start with the given track number.

.Dv ISRC_country :
two characters in the range [0-9A-Z] defining the country code.

.Dv ISRC_owner :
three characters in the range [0-9A-Z] defining the owner code.

.Dv ISRC_year :
the year of recording.

.Dv ISRC_serial :
a serial number, composed of 5 digits.
.Pp
For writing an audio track, setting 
.Dv audio
to 1,
.Dv preemp
to 0 or 1 and all the other field to 0 will do the job. For writing a
data track, you can just set
.Dv track_type 
to
.Dv BLOCK_MODE_1 .

.It Dv WORMIOCREADSESSIONINFO
This command returns the information needed for writing a complete
session at once. The argument structure,
.Dv struct wormio_session_info ,
is as follows:
.Bd -literal -offset indent
struct wormio_session_info {
    u_short lead_in;
    u_short lead_out;
};
.Ed
.Dv lead_in 
gives the length (in blocks) of the lead-in area.
.Dv lead_out
gives the length (in blocks) of the lead-out area.

.It WORMIOCWRITESESSION
This command enables to write a session without interruption. You must
then supply raw data blocks for the lead-in, the program area
(including pregaps) and the lead-out. The session is closed with a 
.Dv WORMIOCFINISHTRACK
command. The argument structure,
.Dv wormio_write_session ,
is as follows:
.Bd -literal -offset indent
struct wormio_write_session {
    int toc_type;
    int onp;
    int lofp;
    int length;
    char catalog[13];
    u_char *track_desc;
};
.Ed
.Dv toc_type
determines what type of table of contents will be recorded in the
lead-in. Possible values are:

.Bl -tag -width XXX
.It Dv 0
CD-DA
.It Dv 1
CD_ROM
.It Dv 2
CD-ROM XA with first track in mode 1
.It Dv 3
CD-ROM XA with first track in mode 2
.It Dv 4
CDI
.El

.Dv onp ,
if set to 1 requests a new program area to be opened. This implies
that the start time of the new program area is included in the lead-in
of the current session.
.Dv lofp
is a parameter only valid when
.Dv toc_type
is equal to 1 and specifies whether the lead-out must be written in
mode 1 or mode 2. The mode of the lead-out must be equal to the mode
of the last track of the session.
.Dv length 
specifies the length of the track descriptor.
.Dv catalog 
can be used to set the catalog number information and is composed of
13 digits. If this array is composed of null bytes, no catalog will be
written.
.Dv track_desc
is a pointer to the array containing the encoding of the table of
contents.

.It Dv WORMIOCFINISHTRACK
Will terminate the track. It takes no argument. Note that closing the
device will also terminate the track.

.It Dv WORMIOCFIXATION
This closes the current session.  The argument is a pointer to
.Dv struct wormio_fixation ,
with the elements
.Dv toc_type ,
an integer between 0 and 4, describing the table-of-contents type.  See
.Xr wormcontrol 8
for a list of useful values.  Optionally, setting the field
.Dv onp
to 1 will cause the next session being opened, so further recording
can be performed into the remaining space.  If
.Dv onp
is 0, the disk will be closed once and for all.

.It Dv WORMIOERROR
This call may be used to get additional information when a I/O error
occured or to check if the last command ended with a recovered
error or a warning. The argument is  a pointer to an integer. The
returned value can be:
.Bl -tag -width  WORM_
.It Dv WORM_SEQUENCE_ERROR
Occurs if a write is performed when the track has not been prepared or
if 
.Dv WORMCPREPTRACK 
is done without a prior 
.Dv WORMIOCPREPDISK .
.It Dv WORM_BUFFER_UNDERRUN
Indicates that the write action stopped because the cache buffer emptied.
.It Dv WORM_DUMMY_BLOCKS_ADDED
This a warning which may occur when the track is closed. Indicates
that during writing dummy blocks are added to meet the disc
specification (minimum of 300 blocks for a track).
.It Dv WORM_CALIBRATION_AREA_ALMOST_FULL
This is warning which indicates that a few Optimum Power Calibration
areas are left. It is recommended to fixate after the tracks are written.
.It Dv WORM_CALIBRATION_AREA_FULL
Indicates that the Calibration area is full. This means that no further
writes can be performed on this disc.
.It Dv WORM_ABSORPTION_CONTROL_ERROR
Indicates that an error might have occurred in the recorded data that
was written, caused by laser power clipping. This is a warning.
.It Dv WORM_END_OF_MEDIUM
Indicates that during writing the end of medium is detected or the
amount of track reached the limit of 99.
.It Dv WORM_OPTIMUM_POWER_CALIBRATION_ERROR
Indicates that power calibration failed. This could indicate: Wrong WO
medium installed, laser failure or drive failure.
.Pp
.El
If an unknown error occured, the returned value will be -1.

.El
Specifying wrong argument values to the above ioctl command will cause
the driver to return an error condition with
.Va errno
set to
.Er EINVAL .
.Pp
In addition, the 
.Xr scsi 4
general ioctls may be used with the 
.Nm
driver, but only against the control device.
.Sh BUGS
The driver is considered beta quality.  There's still a lot of
polishing required.
.Pp
Preparing the driver for a CD-R from another vendor will require you
to understand the source code, be used to the SCSI-2 specification,
hold a copy of the vendor's SCSI reference manual on your desk, and
have a lot of patience and CD-R's.
.Pp
The driver should include all the functionality of the
.Xr cd 4
driver.  No strategy for implementing this kind of interaction has
been designed yet, altough it's now finally possible to at least
read CD-ROM media through it.
.Pp
The first
.Em Unit Attention
conditition after a media change is often not yet caught, although
the driver was designed to catch it.  This can royally screw a user
of the driver, thus make sure to manually catch it before actually
starting a burn.  This can be done for example with a dummy
.Em Test Unit Ready
command:
.Bd -literal
scsi -f /dev/rworm0.ctl -c "0 0 0 0 0 0" >/dev/null 2>&1
.Ed
.Sh FILES
.Bl -tag -width /dev/rworm[0-9].ctl -compact
.It Pa /dev/rworm[0-9]
device for ioctl's and to write a CD-R
.It Pa /dev/rworm[0-9].ctl
the control device, as being used by
.Xr scsi 8
.It Pa /dev/worm[0-9]
the buffered devices that can be used to mount a CD-ROM.
.El
.Sh DIAGNOSTICS
See above.
.Sh SEE ALSO
.Xr close 2 ,
.Xr ioctl 2 ,
.Xr open 2 ,
.Xr write 2 ,
.Xr cd 4 ,
.Xr scsi 4 ,
.Xr scsi 8 ,
.Xr wormcontrol 8
.Sh AUTHORS
The first skeleton for a
.Nm
driver has been written by Peter Dufault in May, 1995.  The driver has
then been improved and made actually usable at all by
.ie t J\(:org Wunsch
.el Joerg Wunsch
in January, 1996.
.Sh HISTORY
The
.Nm
driver appeared in
.Fx 2.1 .