Documentation/cdrom/cdrom-standard.tex

2 \def\version{$Id: cdrom-standard.tex,v 1.9 1997/12/28 15:42:49 david Exp $}
11 \def\cdrom{{\sc cd-rom}}
13 \def\cdromc{{\tt {cdrom.c}}}
14 \def\cdromh{{\tt {cdrom.h}}}
24 \title{A \linux\ \cdrom\ standard}
52 This divergence of behavior has been very significant for \cdrom\
55 their drivers totally inconsistent, the writers of \linux\ \cdrom\
58 maintain uniform behavior across all the \linux\ \cdrom\ drivers.
61 all the different \cdrom\ device drivers for \linux. This document also
62 defines the various $ioctl$s, and how the low-level \cdrom\ device
64 development kernels) several low-level \cdrom\ device drivers, including
67 When the \cdrom\ was developed, the interface between the \cdrom\ drive
69 different \cdrom\ interfaces were developed. Some of them had their
78 driver had to be enhanced. History has delivered us \cdrom\ support for
79 many of these different interfaces. Nowadays, almost all new \cdrom\
100 I decided to start a discussion on how to make all the \linux\ \cdrom\
102 the many \cdrom\ drivers found in the \linux\ kernel. Their reactions
106 of the low-level device drivers for each \cdrom\ drive. By adding this
107 additional layer, it is possible to have all the different \cdrom\
113 simply to give people writing application programs for \cdrom\ drives
114 {\em one\/} \linux\ \cdrom\ interface with consistent behavior for all
115 \cdrom\ devices. In addition, this also provides a consistent interface
119 help \cdrom\ driver developers adapt their code to use the \UCD\ code
125 more than one \cdrom\ drive, possibly of mixed types. It is important
127 cheapest \cdrom\ drives was a Philips cm206, a double-speed proprietary
132 16 speed \cdrom\ drive, and 24 speed drives are common.
135 \label{cdrom.c}
138 implemented the \cdrom\ $ioctl()$ calls through their own routines. This
144 For this reason, the \UCD\ was created to enforce consistent \cdrom\
146 low-level \cdrom\ device drivers. The \UCD\ now provides another
151 \cdrom\ drivers' header files to the kernel's cdrom directory. This was
152 done to help ensure that the user is only presented with only one cdrom
155 \cdrom\ drives are specific enough (\ie, different from other
157 of common {\em \cdrom\ device operations}, $<cdrom-device>_dops$.
184 Every active \cdrom\ device shares this $struct$. The routines
186 place where the behavior of all \cdrom-devices is defined and
187 standardized. The actual interface to the various types of \cdrom\
188 hardware is still performed by various low-level \cdrom-device
190 that are common to all \cdrom\ (and really, all removable-media
193 Registration of a low-level \cdrom\ device driver is now done through
202   \cdrom\ device. This structure is conceptually connected to the major
206   This structure contains information about a particular \cdrom\ drive,
211 Registering a particular \cdrom\ drive with the \UCD\ is done by the
217 \cdrom\ device driver. One of the most important entries in this
223 device driver. When \cdromc\ accesses a \cdrom\ device, it does it
225 the capabilities of future \cdrom\ drives, so it is expected that this
260 \cdrom\ hardware and/or low-level \cdrom\ driver when a \cdrom\ drive
274 \cdrom\ drivers don't even look at the major and minor number though,
314 A few registers contain variables local to the \cdrom\ drive. The
315 flags $options$ are used to specify how the general \cdrom\ routines
425 Some \cdrom\ drives are capable of changing their head-speed. There
426 are several reasons for changing the speed of a \cdrom\ drive. Badly
427 pressed \cdrom s may benefit from less-than-maximum head rate. Modern
428 \cdrom\ drives can obtain very high head rates (up to $24\times$ is
439 drive, measured in units of standard cdrom speed (176\,kB/sec raw data
440 or 150\,kB/sec file system data). So to request that a \cdrom\ drive
487 longer listening, it may be wise for the underlying low-level cdrom
493 Some of the \cdrom-$ioctl$s defined in \cdromh\ can be
519 Some $ioctl$s seem to be specific to certain \cdrom\ drives. That is,
540 the general \cdrom\ $ioctl$ number, {\tt {0x53}}. Currently the
546 \subsection{\cdrom\ capabilities}
551 of a \cdrom\ drive. This can be done by ORing any number of
574 the $cdrom_device_info$ variable $mask$. For instance, the SCSI \cdrom\
575 driver has implemented the code for loading and ejecting \cdrom's, and
577 \cdrom\ drive might be a caddy system, which can't load the tray, and
592 A final flag register controls the {\em behavior\/} of the \cdrom\
625 \newsection{The need to know the purpose of opening the \cdrom\ device}
630 call. The problem with \cdrom\ drives, is that they can be used for
632 file systems, \cdrom s, the other is to play audio CD's. Audio commands
640 original purpose of \cdrom s is) we would like to make sure that the
642 scheme, some \cdrom\ drivers don't do any integrity checking, resulting
644 attempt for mounting a \cdrom\ on an empty drive occurs. This is not a
645 particularly elegant way to find out that there is no \cdrom\ inserted;
651 availability of a \cdrom\ and its correct type (data), would be
654 These two ways of using a \cdrom\ drive, principally for data and
661 parameter (see {\tt {open(2)}}). For \cdrom\ devices, these flags aren't
665 \cdrom\ devices: $O_CREAT$, $O_NOCTTY$, $O_TRUNC$, $O_APPEND$, and
666 $O_SYNC$ have no meaning to a \cdrom.
673 inserted some valid data-\cdrom.'' Thus, our proposal of the
674 implementation for the $open()$ call for \cdrom s is:
679 on the \cdrom, such as closing the tray.
695 mounting \cdrom s is very good in origin: under Solaris a
696 volume-daemon automatically mounts a newly inserted \cdrom\ under {\tt
697 {/cdrom/$<volume-name>$/}}. In my opinion they should have pushed this
698 further and have {\em every\/} \cdrom\ on the local area network be
700 machine you insert a \cdrom, it will always appear at the same
718 configuration of the behavior of \cdrom\ devices (of {\em any\/} type)
735 the tray is opened on the last release, \ie, if a \cdrom\ is unmounted,
739 maintainers and user program developers) to adopt the new \cdrom\
746 over' the \cdrom\ interface to the kernel. The header file belonging
753 The contents of this structure were described in section~\ref{cdrom.c}.
761 as described in section~\ref{cdrom.c}, should be registered with the
785 routines from the \cdrom\ interface. This function returns zero upon
808 \label{cdrom-ioctl}
810 This function handles all the standard $ioctl$ requests for \cdrom\
820 The following `old' \cdrom-$ioctl$s are implemented by directly
824 \item[CDROMMULTISESSION] Requests the last session on a \cdrom.
864 control the behavior of individual \cdrom\ devices. New $ioctl$
873   by $arg$ in units of standard cdrom speed (176\,kB/sec raw data or
978   in section~\ref{cdrom.c}. Most likely you have already implemented
983   part in section~\ref{cdrom-ioctl}, if your code was OK, these are
987   listed in the second part of section~\ref{cdrom-ioctl}). There is no
1001   for {\tt {cdrom.o}} and your driver, as debugging is much easier this
1009 \cdrom-related code in the 2.1-kernel.  Thanks to Scott Snyder and
1014 Kroll, the \linux\ \cdrom\ device driver developers who were kind