\documentclass{article}\def\version{$Id: cdrom-standard.tex,v 1.9 1997/12/28 15:42:49 david Exp $}\newcommand{\newsection}[1]{\newpage\section{#1}}\evensidemargin=0pt\oddsidemargin=0pt\topmargin=-\headheight \advance\topmargin by -\headsep\textwidth=15.99cm \textheight=24.62cm % normal A4, 1'' margin\def\linux{{\sc Linux}}\def\cdrom{{\sc cd-rom}}\def\UCD{{\sc Uniform cd-rom Driver}}\def\cdromc{{\tt {cdrom.c}}}\def\cdromh{{\tt {cdrom.h}}}\def\fo{\sl}                    % foreign words\def\ie{{\fo i.e.}}\def\eg{{\fo e.g.}}\everymath{\it} \everydisplay{\it}\catcode `\_=\active \def_{\_\penalty100 }\catcode`\<=\active \def<#1>{{\langle\hbox{\rm#1}\rangle}}\begin{document}\title{A \linux\ \cdrom\ standard}\author{David van Leeuwen\\{\normalsize\tt david@ElseWare.cistron.nl}\\{\footnotesize updated by Erik Andersen {\tt(andersee@debian.org)}}\\{\footnotesize updated by Jens Axboe {\tt(axboe@image.dk)}}}\date{12 March 1999}\maketitle\newsection{Introduction}\linux\ is probably the Unix-like operating system that supportsthe widest variety of hardware devices. The reasons for this arepresumably \begin{itemize} \item   The large list of hardware devices available for the many platforms  that \linux\ now supports (\ie, i386-PCs, Sparc Suns, etc.)\item   The open design of the operating system, such that anybody can write a  driver for \linux.\item   There is plenty of source code around as examples of how to write a driver.\end{itemize}The openness of \linux, and the many different types of availablehardware has allowed \linux\ to support many different hardware devices.Unfortunately, the very openness that has allowed \linux\ to supportall these different devices has also allowed the behavior of eachdevice driver to differ significantly from one device to another.This divergence of behavior has been very significant for \cdrom\devices; the way a particular drive reacts to a `standard' $ioctl()$call varies greatly from one device driver to another. To avoid makingtheir drivers totally inconsistent, the writers of \linux\ \cdrom\drivers generally created new device drivers by understanding, copying,and then changing an existing one. Unfortunately, this practice did notmaintain uniform behavior across all the \linux\ \cdrom\ drivers. This document describes an effort to establish Uniform behavior acrossall the different \cdrom\ device drivers for \linux. This document alsodefines the various $ioctl$s, and how the low-level \cdrom\ devicedrivers should implement them. Currently (as of the \linux\ 2.1.$x$development kernels) several low-level \cdrom\ device drivers, includingboth IDE/ATAPI and SCSI, now use this Uniform interface.When the \cdrom\ was developed, the interface between the \cdrom\ driveand the computer was not specified in the standards. As a result, manydifferent \cdrom\ interfaces were developed. Some of them had theirown proprietary design (Sony, Mitsumi, Panasonic, Philips), othermanufacturers adopted an existing electrical interface and changedthe functionality (CreativeLabs/SoundBlaster, Teac, Funai) or simplyadapted their drives to one or more of the already existing electricalinterfaces (Aztech, Sanyo, Funai, Vertos, Longshine, Optics Storage andmost of the `NoName' manufacturers). In cases where a new drive reallybrought its own interface or used its own command set and flow controlscheme, either a separate driver had to be written, or an existingdriver had to be enhanced. History has delivered us \cdrom\ support formany of these different interfaces. Nowadays, almost all new \cdrom\drives are either IDE/ATAPI or SCSI, and it is very unlikely that anymanufacturer will create a new interface. Even finding drives for theold proprietary interfaces is getting difficult.When (in the 1.3.70's) I looked at the existing software interface,which was expressed through \cdromh, it appeared to be a rather wildset of commands and data formats.\footnote{I cannot recollect whatkernel version I looked at, then, presumably 1.2.13 and 1.3.34---thelatest kernel that I was indirectly involved in.} It seemed that manyfeatures of the software interface had been added to accommodate thecapabilities of a particular drive, in an {\fo ad hoc\/} manner. Moreimportantly, it appeared that the behavior of the `standard' commandswas different for most of the different drivers: \eg, some driversclose the tray if an $open()$ call occurs when the tray is open, whileothers do not. Some drivers lock the door upon opening the device, toprevent an incoherent file system, but others don't, to allow softwareejection. Undoubtedly, the capabilities of the different drives vary,but even when two drives have the same capability their drivers'behavior was usually different.I decided to start a discussion on how to make all the \linux\ \cdrom\drivers behave more uniformly. I began by contacting the developers ofthe many \cdrom\ drivers found in the \linux\ kernel. Their reactionsencouraged me to write the \UCD\ which this document is intended todescribe. The implementation of the \UCD\ is in the file \cdromc. Thisdriver is intended to be an additional software layer that sits on topof the low-level device drivers for each \cdrom\ drive. By adding thisadditional layer, it is possible to have all the different \cdrom\devices behave {\em exactly\/} the same (insofar as the underlyinghardware will allow).The goal of the \UCD\ is {\em not\/} to alienate driver developers whohave not yet taken steps to support this effort. The goal of \UCD\ issimply to give people writing application programs for \cdrom\ drives{\em one\/} \linux\ \cdrom\ interface with consistent behavior for all\cdrom\ devices. In addition, this also provides a consistent interfacebetween the low-level device driver code and the \linux\ kernel. Careis taken that 100\,\% compatibility exists with the data structures andprogrammer's interface defined in \cdromh. This guide was written tohelp \cdrom\ driver developers adapt their code to use the \UCD\ codedefined in \cdromc.Personally, I think that the most important hardware interfaces arethe IDE/ATAPI drives and, of course, the SCSI drives, but as pricesof hardware drop continuously, it is also likely that people may havemore than one \cdrom\ drive, possibly of mixed types. It is importantthat these drives behave in the same way. In December 1994, one of thecheapest \cdrom\ drives was a Philips cm206, a double-speed proprietarydrive. In the months that I was busy writing a \linux\ driver for it,proprietary drives became obsolete and IDE/ATAPI drives became thestandard. At the time of the last update to this document (November1997) it is becoming difficult to even {\em find} anything less than a16 speed \cdrom\ drive, and 24 speed drives are common.\newsection{Standardizing through another software level}\label{cdrom.c}At the time this document was conceived, all drivers directlyimplemented the \cdrom\ $ioctl()$ calls through their own routines. Thisled to the danger of different drivers forgetting to do important thingslike checking that the user was giving the driver valid data. Moreimportantly, this led to the divergence of behavior, which has alreadybeen discussed.For this reason, the \UCD\ was created to enforce consistent \cdrom\drive behavior, and to provide a common set of services to the variouslow-level \cdrom\ device drivers. The \UCD\ now provides anothersoftware-level, that separates the $ioctl()$ and $open()$ implementationfrom the actual hardware implementation. Note that this effort hasmade few changes which will affect a user's application programs. Thegreatest change involved moving the contents of the various low-level\cdrom\ drivers' header files to the kernel's cdrom directory. This wasdone to help ensure that the user is only presented with only one cdrominterface, the interface defined in \cdromh.\cdrom\ drives are specific enough (\ie, different from otherblock-devices such as floppy or hard disc drives), to define a setof common {\em \cdrom\ device operations}, $<cdrom-device>_dops$.These operations are different from the classical block-device fileoperations, $<block-device>_fops$.The routines for the \UCD\ interface level are implemented in the file\cdromc. In this file, the \UCD\ interfaces with the kernel as a blockdevice by registering the following general $struct\ file_operations$:$$\halign{$#$\ \hfil&$#$\ \hfil&$/*$ \rm# $*/$\hfil\crstruct& file_operations\ cdrom_fops = \{\hidewidth\cr        &NULL,                  & lseek \cr        &block_read,            & read---general block-dev read \cr        &block_write,           & write---general block-dev write \cr        &NULL,                  & readdir \cr        &NULL,                  & select \cr        &cdrom_ioctl,           & ioctl \cr        &NULL,                  & mmap \cr        &cdrom_open,            & open \cr        &cdrom_release,         & release \cr        &NULL,                  & fsync \cr        &NULL,                  & fasync \cr        &cdrom_media_changed,   & media change \cr        &NULL                   & revalidate \cr\};\cr}$$ Every active \cdrom\ device shares this $struct$. The routinesdeclared above are all implemented in \cdromc, since this file is theplace where the behavior of all \cdrom-devices is defined andstandardized. The actual interface to the various types of \cdrom\ hardware is still performed by various low-level \cdrom-devicedrivers. These routines simply implement certain {\em capabilities\/}that are common to all \cdrom\ (and really, all removable-mediadevices).Registration of a low-level \cdrom\ device driver is now done throughthe general routines in \cdromc, not through the Virtual File System(VFS) any more. The interface implemented in \cdromc\ is carried outthrough two general structures that contain information about thecapabilities of the driver, and the specific drives on which thedriver operates. The structures are:\begin{description}\item[$cdrom_device_ops$]   This structure contains information about the low-level driver for a  \cdrom\ device. This structure is conceptually connected to the major  number of the device (although some drivers may have different  major numbers, as is the case for the IDE driver).\item[$cdrom_device_info$]   This structure contains information about a particular \cdrom\ drive,  such as its device name, speed, etc. This structure is conceptually  connected to the minor number of the device.\end{description}Registering a particular \cdrom\ drive with the \UCD\ is done by thelow-level device driver though a call to:$$register_cdrom(struct\ cdrom_device_info * <device>_info)  $$The device information structure, $<device>_info$, contains all theinformation needed for the kernel to interface with the low-level\cdrom\ device driver. One of the most important entries in thisstructure is a pointer to the $cdrom_device_ops$ structure of thelow-level driver.The device operations structure, $cdrom_device_ops$, contains a listof pointers to the functions which are implemented in the low-leveldevice driver. When \cdromc\ accesses a \cdrom\ device, it does itthrough the functions in this structure. It is impossible to know allthe capabilities of future \cdrom\ drives, so it is expected that thislist may need to be expanded from time to time as new technologies aredeveloped. For example, CD-R and CD-R/W drives are beginning to becomepopular, and support will soon need to be added for them. For now, thecurrent $struct$ is:$$\halign{$#$\ \hfil&$#$\ \hfil&\hbox to 10em{$#$\hss}&  $/*$ \rm# $*/$\hfil\crstruct& cdrom_device_ops\ \{ \hidewidth\cr  &int& (* open)(struct\ cdrom_device_info *, int)\cr  &void& (* release)(struct\ cdrom_device_info *);\cr   &int& (* drive_status)(struct\ cdrom_device_info *, int);\cr       &int& (* media_changed)(struct\ cdrom_device_info *, int);\cr   &int& (* tray_move)(struct\ cdrom_device_info *, int);\cr  &int& (* lock_door)(struct\ cdrom_device_info *, int);\cr  &int& (* select_speed)(struct\ cdrom_device_info *, int);\cr  &int& (* select_disc)(struct\ cdrom_device_info *, int);\cr  &int& (* get_last_session) (struct\ cdrom_device_info *,         struct\ cdrom_multisession *{});\cr  &int& (* get_mcn)(struct\ cdrom_device_info *, struct\ cdrom_mcn *{});\cr  &int& (* reset)(struct\ cdrom_device_info *);\cr  &int& (* audio_ioctl)(struct\ cdrom_device_info *, unsigned\ int,         void *{});\cr   &int& (* dev_ioctl)(struct\ cdrom_device_info *, unsigned\ int,         unsigned\ long);\cr\noalign{\medskip}  &const\ int& capability;& capability flags \cr  &int& n_minors;& number of active minor devices \cr\};\cr}$$When a low-level device driver implements one of these capabilities,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