454 lines
15 KiB
Groff
454 lines
15 KiB
Groff
.\"
|
|
.\" 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.15 1998/03/31 01:55:11 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 at scbus?
|
|
.Cd disk worm0 at scbus 1 target 5 lun 0
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm worm
|
|
driver provides support for
|
|
.Em SCSI
|
|
CD-R recording devices. 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 WORMIOCFIRSTWRITABLEADDR
|
|
This command will return the next logical writable address for the
|
|
write command. The argument is a pointer to
|
|
.Dv struct wormio_first_writable_addr ,
|
|
with the elements
|
|
.Dv track ,
|
|
the track for which the write address will be returned,
|
|
.Dv mode ,
|
|
which can take the values 1 or 2,
|
|
.Dv raw ,
|
|
which must be set to 1 if the pregap must not be taken in account,
|
|
.Dv audio ,
|
|
which must be set to 1 for an audio track (in this case, mode
|
|
indicates if there is preemphasis) and
|
|
.Dv addr .
|
|
|
|
addr will be the address corresponding to the next write command.
|
|
|
|
.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, although it's now finally possible to at least
|
|
read CD-ROM media through it.
|
|
.Pp
|
|
The first
|
|
.Em Unit Attention
|
|
condition 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
|
|
.An 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 .
|