$$\vbox{\halign{&$#$\hfil\crstruct\ &cdrom_device_info\ <device>_info = \{\cr& <device>_dops;\cr&\ldots\cr\}\cr}}$$Note that a driver must have one static structure, $<device>_dops$, whileit may have as many structures $<device>_info$ as there are minor devicesactive. $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)$ removesthe minor device from the list. If it was the last registered minor forthe low-level driver, this disconnects the registered device-operationroutines from the \cdrom\ interface. This function returns zero uponsuccess, 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 islisted in the standard $cdrom_fops$. If the VFS opens a file, thisfunction 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 istransferred 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 thencalls the device-dependent $release()$ routine. When the use-count hasreached 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 threecategories: $ioctl$s that can be directly implemented by deviceoperations, ones that are routed through the call $audio_ioctl()$, andthe remaining ones, that are presumable device-dependent. Generally, anegative return value indicates an error.\subsubsection{Directly implemented $ioctl$s}\label{ioctl-direct}The following `old' \cdrom-$ioctl$s are implemented by directlycalling device-operations in $cdrom_device_ops$, if implemented andnot 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 (closetray on first open) and auto-eject (eject on last release), otherwiseset 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 tothe $cdrom_fops$ function $audio_ioctl()$. Memory checks andallocation are performed in $cdrom_ioctl()$, and also sanitization ofaddress 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$ andspecified 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 formatdelimited 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 tocontrol 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 theoption flag register after modification. Use  $arg = \rm0$ for readingthe 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 hastaken over the torch in maintaining \cdromc\ and integrating much\cdrom-related code in the 2.1-kernel.  Thanks to Scott Snyder andGerd Knorr, who were the first to implement this interface for SCSIand IDE-CD drivers and added many ideas for extension of the datastructures relative to kernel~2.0.  Further thanks to Heiko Eissfeldt,Thomas Quinot, Jon Tombs, Ken Pizzini, Eberhard M\"onkeberg and AndrewKroll, the \linux\ \cdrom\ device driver developers who were kindenough to give suggestions and criticisms during the writing. Finallyof course, I want to thank Linus Torvalds for making this possible inthe first place.\vfill$ \version\ $\eject\end{document}