it should add a function pointer to this $struct$. When a particularfunction is not implemented, however, this $struct$ should contain aNULL instead. The $capability$ flags specify the capabilities of the\cdrom\ hardware and/or low-level \cdrom\ driver when a \cdrom\ driveis registered with the \UCD. The value $n_minors$ should be a positivevalue indicating the number of minor devices that are supported bythe low-level device driver, normally~1. Although these two variablesare `informative' rather than `operational,' they are included in$cdrom_device_ops$ because they describe the capability of the {\emdriver\/} rather than the {\em drive}. Nomenclature has always beendifficult in computer programming.Note that most functions have fewer parameters than their$blkdev_fops$ counterparts. This is because very little of theinformation in the structures $inode$ and $file$ is used. For mostdrivers, the main parameter is the $struct$ $cdrom_device_info$, fromwhich the major and minor number can be extracted. (Most low-level\cdrom\ drivers don't even look at the major and minor number though,since many of them only support one device.) This will be availablethrough $dev$ in $cdrom_device_info$ described below.The drive-specific, minor-like information that is registered with\cdromc, currently contains the following fields:$$\halign{$#$\ \hfil&$#$\ \hfil&\hbox to 10em{$#$\hss}&  $/*$ \rm# $*/$\hfil\crstruct& cdrom_device_info\ \{ \hidewidth\cr  & struct\ cdrom_device_ops *& ops;& device operations for this major\cr  & struct\ cdrom_device_info *& next;& next device_info for this major\cr  & void *&  handle;& driver-dependent data\cr\noalign{\medskip}  & kdev_t&  dev;& device number (incorporates minor)\cr  & int& mask;& mask of capability: disables them \cr  & int& speed;& maximum speed for reading data \cr  & int& capacity;& number of discs in a jukebox \cr\noalign{\medskip}  &int& options : 30;& options flags \cr  &unsigned& mc_flags : 2;& media-change buffer flags \cr  & int& use_count;& number of times device is opened\cr  & char& name[20];& name of the device type\cr\}\cr}$$Using this $struct$, a linked list of the registered minor devices isbuilt, using the $next$ field. The device number, the device operationsstruct and specifications of properties of the drive are stored in thisstructure.The $mask$ flags can be used to mask out some of the capabilities listedin $ops\to capability$, if a specific drive doesn't support a featureof the driver. The value $speed$ specifies the maximum head-rate of thedrive, measured in units of normal audio speed (176\,kB/sec raw data or150\,kB/sec file system data). The value $n_discs$ should reflect thenumber of discs the drive can hold simultaneously, if it is designedas a juke-box, or otherwise~1. The parameters are declared $const$because they describe properties of the drive, which don't change afterregistration.A few registers contain variables local to the \cdrom\ drive. Theflags $options$ are used to specify how the general \cdrom\ routinesshould behave. These various flags registers should provide enoughflexibility to adapt to the different users' wishes (and {\em not\/} the`arbitrary' wishes of the author of the low-level device driver, as isthe case in the old scheme). The register $mc_flags$ is used to bufferthe information from $media_changed()$ to two separate queues. Otherdata that is specific to a minor drive, can be accessed through $handle$,which can point to a data structure specific to the low-level driver.The fields $use_count$, $next$, $options$ and $mc_flags$ need not beinitialized.The intermediate software layer that \cdromc\ forms will perform someadditional bookkeeping. The use count of the device (the number ofprocesses that have the device opened) is registered in $use_count$. Thefunction $cdrom_ioctl()$ will verify the appropriate user-memory regionsfor read and write, and in case a location on the CD is transferred,it will `sanitize' the format by making requests to the low-leveldrivers in a standard format, and translating all formats between theuser-software and low level drivers. This relieves much of the drivers'memory checking and format checking and translation. Also, the necessarystructures will be declared on the program stack.The implementation of the functions should be as defined in thefollowing sections. Two functions {\em must\/} be implemented, namely$open()$ and $release()$. Other functions may be omitted, theircorresponding capability flags will be cleared upon registration.Generally, a function returns zero on success and negative on error. Afunction call should return only after the command has completed, but ofcourse waiting for the device should not use processor time.\subsection{$Int\ open(struct\ cdrom_device_info * cdi, int\ purpose)$}$Open()$ should try to open the device for a specific $purpose$, whichcan be either:\begin{itemize}\item[0] Open for reading data, as done by {\tt {mount()}} (2), or theuser commands {\tt {dd}} or {\tt {cat}}.  \item[1] Open for $ioctl$ commands, as done by audio-CD playingprograms.\end{itemize}Notice that any strategic code (closing tray upon $open()$, etc.)\ isdone by the calling routine in \cdromc, so the low-level routineshould only be concerned with proper initialization, such as spinningup the disc, etc. % and device-use count\subsection{$Void\ release(struct\ cdrom_device_info * cdi)$}Device-specific actions should be taken such as spinning down the device.However, strategic actions such as ejection of the tray, or unlockingthe door, should be left over to the general routine $cdrom_release()$.This is the only function returning type $void$.\subsection{$Int\ drive_status(struct\ cdrom_device_info * cdi, int\ slot_nr)$}\label{drive status}The function $drive_status$, if implemented, should provideinformation on the status of the drive (not the status of the disc,which may or may not be in the drive). If the drive is not a changer,$slot_nr$ should be ignored. In \cdromh\ the possibilities are listed: $$\halign{$#$\ \hfil&$/*$ \rm# $*/$\hfil\crCDS_NO_INFO& no information available\crCDS_NO_DISC& no disc is inserted, tray is closed\crCDS_TRAY_OPEN& tray is opened\crCDS_DRIVE_NOT_READY& something is wrong, tray is moving?\crCDS_DISC_OK& a disc is loaded and everything is fine\cr}$$\subsection{$Int\ media_changed(struct\ cdrom_device_info * cdi, int\ disc_nr)$}This function is very similar to the original function in $struct\ file_operations$. It returns 1 if the medium of the device $cdi\todev$ has changed since the last call, and 0 otherwise. The parameter$disc_nr$ identifies a specific slot in a juke-box, it should beignored for single-disc drives.  Note that by `re-routing' thisfunction through $cdrom_media_changed()$, we can implement separatequeues for the VFS and a new $ioctl()$ function that can report devicechanges to software (\eg, an auto-mounting daemon).\subsection{$Int\ tray_move(struct\ cdrom_device_info * cdi, int\ position)$}This function, if implemented, should control the tray movement. (Noother function should control this.) The parameter $position$ controlsthe desired direction of movement:\begin{itemize}\item[0] Close tray\item[1] Open tray\end{itemize}This function returns 0 upon success, and a non-zero value uponerror. Note that if the tray is already in the desired position, noaction need be taken, and the return value should be 0. \subsection{$Int\ lock_door(struct\ cdrom_device_info * cdi, int\ lock)$}This function (and no other code) controls locking of the door, if thedrive allows this. The value of $lock$ controls the desired lockingstate:\begin{itemize}\item[0] Unlock door, manual opening is allowed\item[1] Lock door, tray cannot be ejected manually\end{itemize}This function returns 0 upon success, and a non-zero value uponerror. Note that if the door is already in the requested state, noaction need be taken, and the return value should be 0. \subsection{$Int\ select_speed(struct\ cdrom_device_info * cdi, int\ speed)$}Some \cdrom\ drives are capable of changing their head-speed. Thereare several reasons for changing the speed of a \cdrom\ drive. Badlypressed \cdrom s may benefit from less-than-maximum head rate. Modern\cdrom\ drives can obtain very high head rates (up to $24\times$ iscommon).  It has been reported that these drives can make readingerrors at these high speeds, reducing the speed can prevent data lossin these circumstances.  Finally, some of these drives canmake an annoyingly loud noise, which a lower speed may reduce. %Finally,%although the audio-low-pass filters probably aren't designed for it,%more than real-time playback of audio might be used for high-speed%copying of audio tracks.This function specifies the speed at which data is read or audio isplayed back. The value of $speed$ specifies the head-speed of thedrive, measured in units of standard cdrom speed (176\,kB/sec raw dataor 150\,kB/sec file system data). So to request that a \cdrom\ driveoperate at 300\,kB/sec you would call the CDROM_SELECT_SPEED $ioctl$with $speed=2$. The special value `0' means `auto-selection', \ie,maximum data-rate or real-time audio rate. If the drive doesn't havethis `auto-selection' capability, the decision should be made on thecurrent disc loaded and the return value should be positive. A negativereturn value indicates an error.\subsection{$Int\ select_disc(struct\ cdrom_device_info * cdi, int\ number)$}If the drive can store multiple discs (a juke-box) this functionwill perform disc selection. It should return the number of theselected disc on success, a negative value on error. Currently, onlythe ide-cd driver supports this functionality.\subsection{$Int\ get_last_session(struct\ cdrom_device_info * cdi, struct\  cdrom_multisession * ms_info)$}This function should implement the old corresponding $ioctl()$. Fordevice $cdi\to dev$, the start of the last session of the current discshould be returned in the pointer argument $ms_info$. Note thatroutines in \cdromc\ have sanitized this argument: its requestedformat will {\em always\/} be of the type $CDROM_LBA$ (linear blockaddressing mode), whatever the calling software requested. Butsanitization goes even further: the low-level implementation mayreturn the requested information in $CDROM_MSF$ format if it wishes so(setting the $ms_info\rightarrow addr_format$ field appropriately, ofcourse) and the routines in \cdromc\ will make the transformation ifnecessary. The return value is 0 upon success.\subsection{$Int\ get_mcn(struct\ cdrom_device_info * cdi, struct\  cdrom_mcn * mcn)$}Some discs carry a `Media Catalog Number' (MCN), also called`Universal Product Code' (UPC). This number should reflect the numberthat is generally found in the bar-code on the product. Unfortunately,the few discs that carry such a number on the disc don't even use thesame format. The return argument to this function is a pointer to apre-declared memory region of type $struct\ cdrom_mcn$. The MCN isexpected as a 13-character string, terminated by a null-character.\subsection{$Int\ reset(struct\ cdrom_device_info * cdi)$}This call should perform a hard-reset on the drive (although incircumstances that a hard-reset is necessary, a drive may very well notlisten to commands anymore). Preferably, control is returned to thecaller only after the drive has finished resetting. If the drive is nolonger listening, it may be wise for the underlying low-level cdromdriver to time out.\subsection{$Int\ audio_ioctl(struct\ cdrom_device_info * cdi, unsigned\  int\ cmd, void * arg)$}Some of the \cdrom-$ioctl$s defined in \cdromh\ can beimplemented by the routines described above, and hence the function$cdrom_ioctl$ will use those. However, most $ioctl$s deal withaudio-control. We have decided to leave these to be accessed through asingle function, repeating the arguments $cmd$ and $arg$. Note thatthe latter is of type $void*{}$, rather than $unsigned\ long\int$. The routine $cdrom_ioctl()$ does do some useful things,though. It sanitizes the address format type to $CDROM_MSF$ (Minutes,Seconds, Frames) for all audio calls. It also verifies the memorylocation of $arg$, and reserves stack-memory for the argument. Thismakes implementation of the $audio_ioctl()$ much simpler than in theold driver scheme. For example, you may look up the function$cm206_audio_ioctl()$ in {\tt {cm206.c}} that should be updated withthis documentation. An unimplemented ioctl should return $-ENOSYS$, but a harmless request(\eg, $CDROMSTART$) may be ignored by returning 0 (success). Othererrors should be according to the standards, whatever they are. Whenan error is returned by the low-level driver, the \UCD\ tries wheneverpossible to return the error code to the calling program. (We may decide