diff options
| -rw-r--r-- | share/man/man4/pass.4 | 8 | ||||
| -rw-r--r-- | share/man/man4/worm.4 | 423 | ||||
| -rw-r--r-- | share/man/man4/xpt.4 | 8 | ||||
| -rw-r--r-- | share/man/man9/cd.9 | 5 |
4 files changed, 45 insertions, 399 deletions
diff --git a/share/man/man4/pass.4 b/share/man/man4/pass.4 index 01413f5..384ffab 100644 --- a/share/man/man4/pass.4 +++ b/share/man/man4/pass.4 @@ -25,7 +25,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id$ +.\" $Id: pass.4,v 1.1 1998/10/12 00:26:03 ken Exp $ .\" .Dd October 10, 1998 .Dt PASS 4 @@ -94,11 +94,9 @@ CAM subsystem. None. .Sh SEE ALSO .Xr cam 3 , +.Xr cam_cdbparse 3 , .Xr xpt 4 , -.Xr camcontrol 8 , -.Xr cam 9 , -.Xr ccb 9 , -.Xr xpt 9 , +.Xr camcontrol 8 .Sh HISTORY The CAM passthrough driver first appeared in .Fx 3.0 . diff --git a/share/man/man4/worm.4 b/share/man/man4/worm.4 index ab3d777..91cfb12 100644 --- a/share/man/man4/worm.4 +++ b/share/man/man4/worm.4 @@ -32,410 +32,56 @@ .\" 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 $ +.\" $Id: worm.4,v 1.16 1998/06/08 06:12:02 jkoshy Exp $ .\" " -.Dd January 27, 1996 +.Dd October 15, 1998 .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 +None. .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. +driver was provided under FreeBSD releases prior to +.Fx 3.0 . .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 +The FreeBSD +.Tn SCSI +layer was replaced for +.Fx 3.0 +by a CAM-compliant +.Tn SCSI +layer. The new +.Tn SCSI +layer doesn't include a +.Xr worm 4 +driver, and isn't likely to include one in the future. Future in-kernel +support for CD-R/CD-RW/DVD drives will likely be implemented through 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. +driver. Users who wish +to write CDs on a WORM, CD-R, or CD-RW drive +should use +.Nm cdrecord , +which is in the FreeBSD ports collection. .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. +The +.Xr cd 4 +driver provides read-only access to CD, CD-R, and CD-RW drives, as well as +WORM drives that support the CDROM command set. Therefore, users wishing +to mount CDs in a WORM drive should use the +.Xr cd 4 +driver instead. .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 +.Xr pass 4 , +.Xr xpt 4 .Sh AUTHORS The first skeleton for a .Nm @@ -450,4 +96,9 @@ in January, 1996. The .Nm driver appeared in -.Fx 2.1 . +.Fx 2.1 , +and disappeared in +.Fx 3.0 +with the advent of the CAM +.Tn SCSI +layer. diff --git a/share/man/man4/xpt.4 b/share/man/man4/xpt.4 index 378619a..0f75891 100644 --- a/share/man/man4/xpt.4 +++ b/share/man/man4/xpt.4 @@ -25,7 +25,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id$ +.\" $Id: xpt.4,v 1.1 1998/10/12 00:31:42 ken Exp $ .\" .Dd October 10, 1998 .Dt XPT 4 @@ -92,11 +92,9 @@ driver. None. .Sh SEE ALSO .Xr cam 3 , +.Xr cam_cdbparse 3 , .Xr pass 4 , -.Xr camcontrol 8 , -.Xr cam 9 , -.Xr ccb 9 , -.Xr xpt 9 , +.Xr camcontrol 8 .Sh HISTORY The CAM transport layer driver first appeared in .Fx 3.0 . diff --git a/share/man/man9/cd.9 b/share/man/man9/cd.9 index ebe9cd8..e1596cd 100644 --- a/share/man/man9/cd.9 +++ b/share/man/man9/cd.9 @@ -25,7 +25,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: cd.9,v 1.7 1998/03/12 07:31:16 charnier Exp $ +.\" $Id: cd.9,v 1.8 1998/10/12 04:09:49 ken Exp $ .\" .Dd October 10, 1998 .Dt CD 9 @@ -84,8 +84,7 @@ is the driver source file. .El .Sh SEE ALSO .Xr cd 4 , -.Xr scsi 4 , -.Xr xpt 9 +.Xr scsi 4 .Sh HISTORY The .Nm |
