cdrom-standard.tex

讲述linux的初始化过程

driver's $<device>_dops$, as in 
$$
\vbox{\halign{&$#$\hfil\cr
struct\ &cdrom_device_info\ <device>_info = \{\cr
& <device>_dops;\cr
&\ldots\cr
\}\cr
}}$$
Note that a driver must have one static structure, $<device>_dops$, while
it may have as many structures $<device>_info$ as there are minor devices
active. $Register_cdrom()$ builds a linked list from these. 

\subsection{$Int\ unregister_cdrom(struct\ cdrom_device_info * cdi)$}

Unregistering device $cdi$ with minor number $MINOR(cdi\to dev)$ removes
the minor device from the list. If it was the last registered minor for
the low-level driver, this disconnects the registered device-operation
routines from the \cdrom\ interface. This function returns zero upon
success, and non-zero upon failure.

\subsection{$Int\ cdrom_open(struct\ inode * ip, struct\ file * fp)$}

This function is not called directly by the low-level drivers, it is
listed in the standard $cdrom_fops$. If the VFS opens a file, this
function becomes active. A strategy is implemented in this routine,
taking care of all capabilities and options that are set in the
$cdrom_device_ops$ connected to the device. Then, the program flow is
transferred to the device_dependent $open()$ call.

\subsection{$Void\ cdrom_release(struct\ inode *ip, struct\ file
*fp)$}

This function implements the reverse-logic of $cdrom_open()$, and then
calls the device-dependent $release()$ routine. When the use-count has
reached 0, the allocated buffers are flushed by calls to $sync_dev(dev)$
and $invalidate_buffers(dev)$.


\subsection{$Int\ cdrom_ioctl(struct\ inode *ip, struct\ file *fp,
unsigned\ int\ cmd, unsigned\ long\ arg)$}
\label{cdrom-ioctl}

This function handles all the standard $ioctl$ requests for \cdrom\
devices in a uniform way. The different calls fall into three
categories: $ioctl$s that can be directly implemented by device
operations, ones that are routed through the call $audio_ioctl()$, and
the remaining ones, that are presumable device-dependent. Generally, a
negative return value indicates an error.

\subsubsection{Directly implemented $ioctl$s}
\label{ioctl-direct}

The following `old' \cdrom-$ioctl$s are implemented by directly
calling device-operations in $cdrom_device_ops$, if implemented and
not masked:
\begin{description}
\item[CDROMMULTISESSION] Requests the last session on a \cdrom.
\item[CDROMEJECT] Open tray. 
\item[CDROMCLOSETRAY] Close tray.
\item[CDROMEJECT_SW] If $arg\not=0$, set behavior to auto-close (close
tray on first open) and auto-eject (eject on last release), otherwise
set behavior to non-moving on $open()$ and $release()$ calls.
\item[CDROM_GET_MCN] Get the Media Catalog Number from a CD.
\end{description}

\subsubsection{$Ioctl$s routed through $audio_ioctl()$}
\label{ioctl-audio}

The following set of $ioctl$s are all implemented through a call to
the $cdrom_fops$ function $audio_ioctl()$. Memory checks and
allocation are performed in $cdrom_ioctl()$, and also sanitization of
address format ($CDROM_LBA$/$CDROM_MSF$) is done.
\begin{description}
\item[CDROMSUBCHNL] Get sub-channel data in argument $arg$ of type $struct\
cdrom_subchnl *{}$.
\item[CDROMREADTOCHDR] Read Table of Contents header, in $arg$ of type
$struct\ cdrom_tochdr *{}$. 
\item[CDROMREADTOCENTRY] Read a Table of Contents entry in $arg$ and
specified by $arg$ of type $struct\ cdrom_tocentry *{}$.
\item[CDROMPLAYMSF] Play audio fragment specified in Minute, Second,
Frame format, delimited by $arg$ of type $struct\ cdrom_msf *{}$.
\item[CDROMPLAYTRKIND] Play audio fragment in track-index format
delimited by $arg$ of type $struct\ \penalty-1000 cdrom_ti *{}$.
\item[CDROMVOLCTRL] Set volume specified by $arg$ of type $struct\
cdrom_volctrl *{}$.
\item[CDROMVOLREAD] Read volume into by $arg$ of type $struct\
cdrom_volctrl *{}$.
\item[CDROMSTART] Spin up disc.
\item[CDROMSTOP] Stop playback of audio fragment.
\item[CDROMPAUSE] Pause playback of audio fragment.
\item[CDROMRESUME] Resume playing.
\end{description}

\subsubsection{New $ioctl$s in \cdromc}

The following $ioctl$s have been introduced to allow user programs to
control the behavior of individual \cdrom\ devices. New $ioctl$
commands can be identified by the underscores in their names.
\begin{description}
\item[CDROM_SET_OPTIONS] Set options specified by $arg$. Returns the
option flag register after modification. Use  $arg = \rm0$ for reading
the current flags.
\item[CDROM_CLEAR_OPTIONS] Clear options specified by $arg$. Returns
  the option flag register after modification.
\item[CDROM_SELECT_SPEED] Select head-rate speed of disc specified as
  by $arg$ in units of standard cdrom speed (176\,kB/sec raw data or
  150\,kB/sec file system data). The value 0 means `auto-select', \ie,
  play audio discs at real time and data discs at maximum speed. The value
  $arg$ is checked against the maximum head rate of the drive found in the
  $cdrom_dops$.
\item[CDROM_SELECT_DISC] Select disc numbered $arg$ from a juke-box.
  First disc is numbered 0. The number $arg$ is checked against the
  maximum number of discs in the juke-box found in the $cdrom_dops$.
\item[CDROM_MEDIA_CHANGED] Returns 1 if a disc has been changed since
  the last call. Note that calls to $cdrom_media_changed$ by the VFS
  are treated by an independent queue, so both mechanisms will detect
  a media change once. For juke-boxes, an extra argument $arg$
  specifies the slot for which the information is given. The special
  value $CDSL_CURRENT$ requests that information about the currently
  selected slot be returned.
\item[CDROM_DRIVE_STATUS] Returns the status of the drive by a call to
  $drive_status()$. Return values are defined in section~\ref{drive
   status}. Note that this call doesn't return information on the
  current playing activity of the drive; this can be polled through an
  $ioctl$ call to $CDROMSUBCHNL$. For juke-boxes, an extra argument
  $arg$ specifies the slot for which (possibly limited) information is
  given. The special value $CDSL_CURRENT$ requests that information
  about the currently selected slot be returned.
\item[CDROM_DISC_STATUS] Returns the type of the disc currently in the
  drive.  It should be viewed as a complement to $CDROM_DRIVE_STATUS$.
  This $ioctl$ can provide \emph {some} information about the current
  disc that is inserted in the drive.  This functionality used to be
  implemented in the low level drivers, but is now carried out
  entirely in \UCD.
  
  The history of development of the CD's use as a carrier medium for
  various digital information has lead to many different disc types.
  This $ioctl$ is useful only in the case that CDs have \emph {only
    one} type of data on them.  While this is often the case, it is
  also very common for CDs to have some tracks with data, and some
  tracks with audio.  Because this is an existing interface, rather
  than fixing this interface by changing the assumptions it was made
  under, thereby breaking all user applications that use this
  function, the \UCD\ implements this $ioctl$ as follows: If the CD in
  question has audio tracks on it, and it has absolutely no CD-I, XA,
  or data tracks on it, it will be reported as $CDS_AUDIO$.  If it has
  both audio and data tracks, it will return $CDS_MIXED$.  If there
  are no audio tracks on the disc, and if the CD in question has any
  CD-I tracks on it, it will be reported as $CDS_XA_2_2$.  Failing
  that, if the CD in question has any XA tracks on it, it will be
  reported as $CDS_XA_2_1$.  Finally, if the CD in question has any
  data tracks on it, it will be reported as a data CD ($CDS_DATA_1$).

  This $ioctl$ can return:
  $$
  \halign{$#$\ \hfil&$/*$ \rm# $*/$\hfil\cr
    CDS_NO_INFO& no information available\cr
    CDS_NO_DISC& no disc is inserted, or tray is opened\cr
    CDS_AUDIO& Audio disc (2352 audio bytes/frame)\cr
    CDS_DATA_1& data disc, mode 1 (2048 user bytes/frame)\cr
    CDS_XA_2_1& mixed data (XA), mode 2, form 1 (2048 user bytes)\cr
    CDS_XA_2_2& mixed data (XA), mode 2, form 1 (2324  user bytes)\cr
    CDS_MIXED& mixed audio/data disc\cr
    }
  $$
  For some information concerning frame layout of the various disc
  types, see a recent version of \cdromh.

\item[CDROM_CHANGER_NSLOTS] Returns the number of slots in a
  juke-box. 
\item[CDROMRESET] Reset the drive. 
\item[CDROM_GET_CAPABILITY] Returns the $capability$ flags for the
  drive. Refer to section \ref{capability} for more information on
  these flags.
\item[CDROM_LOCKDOOR] Locks the door of the drive. $arg == \rm0$
  unlocks the door, any other value locks it.
\item[CDROM_DEBUG] Turns on debugging info. Only root is allowed
  to do this. Same semantics as CDROM_LOCKDOOR.
\end{description}

\subsubsection{Device dependent $ioctl$s}

Finally, all other $ioctl$s are passed to the function $dev_ioctl()$,
if implemented. No memory allocation or verification is carried out. 

\newsection{How to update your driver}

\begin{enumerate}
\item Make a backup of your current driver. 
\item Get hold of the files \cdromc\ and \cdromh, they should be in
  the directory tree that came with this documentation.
\item Make sure you include \cdromh.
\item Change the 3rd argument of $register_blkdev$ from
$\&<your-drive>_fops$ to $\&cdrom_fops$. 
\item Just after that line, add the following to register with the \UCD:
  $$register_cdrom(\&<your-drive>_info);$$
  Similarly, add a call to $unregister_cdrom()$ at the appropriate place.
\item Copy an example of the device-operations $struct$ to your
  source, \eg, from {\tt {cm206.c}} $cm206_dops$, and change all
  entries to names corresponding to your driver, or names you just
  happen to like. If your driver doesn't support a certain function,
  make the entry $NULL$. At the entry $capability$ you should list all
  capabilities your driver currently supports. If your driver
  has a capability that is not listed, please send me a message.
\item Copy the $cdrom_device_info$ declaration from the same example
  driver, and modify the entries according to your needs. If your
  driver dynamically determines the capabilities of the hardware, this
  structure should also be declared dynamically. 
\item Implement all functions in your $<device>_dops$ structure,
  according to prototypes listed in \cdromh, and specifications given
  in section~\ref{cdrom.c}. Most likely you have already implemented
  the code in a large part, and you will almost certainly need to adapt the
  prototype and return values.
\item Rename your $<device>_ioctl()$ function to $audio_ioctl$ and
  change the prototype a little. Remove entries listed in the first
  part in section~\ref{cdrom-ioctl}, if your code was OK, these are
  just calls to the routines you adapted in the previous step.
\item You may remove all remaining memory checking code in the
  $audio_ioctl()$ function that deals with audio commands (these are
  listed in the second part of section~\ref{cdrom-ioctl}). There is no
  need for memory allocation either, so most $case$s in the $switch$
  statement look similar to:
  $$
  case\ CDROMREADTOCENTRY\colon get_toc_entry\bigl((struct\ 
  cdrom_tocentry *{})\ arg\bigr);
  $$
\item All remaining $ioctl$ cases must be moved to a separate
  function, $<device>_ioctl$, the device-dependent $ioctl$s. Note that
  memory checking and allocation must be kept in this code!
\item Change the prototypes of $<device>_open()$ and
  $<device>_release()$, and remove any strategic code (\ie, tray
  movement, door locking, etc.).
\item Try to recompile the drivers. We advise you to use modules, both
  for {\tt {cdrom.o}} and your driver, as debugging is much easier this
  way.
\end{enumerate} 

\newsection{Thanks}

Thanks to all the people involved.  First, Erik Andersen, who has
taken over the torch in maintaining \cdromc\ and integrating much
\cdrom-related code in the 2.1-kernel.  Thanks to Scott Snyder and
Gerd Knorr, who were the first to implement this interface for SCSI
and IDE-CD drivers and added many ideas for extension of the data
structures relative to kernel~2.0.  Further thanks to Heiko Eissfeldt,
Thomas Quinot, Jon Tombs, Ken Pizzini, Eberhard M\"onkeberg and Andrew
Kroll, the \linux\ \cdrom\ device driver developers who were kind
enough to give suggestions and criticisms during the writing. Finally
of course, I want to thank Linus Torvalds for making this possible in
the first place.

\vfill
$ \version\ $
\eject
\end{document}