Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 1 | \documentclass{article} |
| 2 | \def\version{$Id: cdrom-standard.tex,v 1.9 1997/12/28 15:42:49 david Exp $} |
| 3 | \newcommand{\newsection}[1]{\newpage\section{#1}} |
| 4 | |
| 5 | \evensidemargin=0pt |
| 6 | \oddsidemargin=0pt |
| 7 | \topmargin=-\headheight \advance\topmargin by -\headsep |
| 8 | \textwidth=15.99cm \textheight=24.62cm % normal A4, 1'' margin |
| 9 | |
| 10 | \def\linux{{\sc Linux}} |
| 11 | \def\cdrom{{\sc cd-rom}} |
| 12 | \def\UCD{{\sc Uniform cd-rom Driver}} |
| 13 | \def\cdromc{{\tt {cdrom.c}}} |
| 14 | \def\cdromh{{\tt {cdrom.h}}} |
| 15 | \def\fo{\sl} % foreign words |
| 16 | \def\ie{{\fo i.e.}} |
| 17 | \def\eg{{\fo e.g.}} |
| 18 | |
| 19 | \everymath{\it} \everydisplay{\it} |
| 20 | \catcode `\_=\active \def_{\_\penalty100 } |
| 21 | \catcode`\<=\active \def<#1>{{\langle\hbox{\rm#1}\rangle}} |
| 22 | |
| 23 | \begin{document} |
| 24 | \title{A \linux\ \cdrom\ standard} |
| 25 | \author{David van Leeuwen\\{\normalsize\tt david@ElseWare.cistron.nl} |
| 26 | \\{\footnotesize updated by Erik Andersen {\tt(andersee@debian.org)}} |
| 27 | \\{\footnotesize updated by Jens Axboe {\tt(axboe@image.dk)}}} |
| 28 | \date{12 March 1999} |
| 29 | |
| 30 | \maketitle |
| 31 | |
| 32 | \newsection{Introduction} |
| 33 | |
| 34 | \linux\ is probably the Unix-like operating system that supports |
| 35 | the widest variety of hardware devices. The reasons for this are |
| 36 | presumably |
| 37 | \begin{itemize} |
| 38 | \item |
| 39 | The large list of hardware devices available for the many platforms |
| 40 | that \linux\ now supports (\ie, i386-PCs, Sparc Suns, etc.) |
| 41 | \item |
| 42 | The open design of the operating system, such that anybody can write a |
| 43 | driver for \linux. |
| 44 | \item |
| 45 | There is plenty of source code around as examples of how to write a driver. |
| 46 | \end{itemize} |
| 47 | The openness of \linux, and the many different types of available |
| 48 | hardware has allowed \linux\ to support many different hardware devices. |
| 49 | Unfortunately, the very openness that has allowed \linux\ to support |
| 50 | all these different devices has also allowed the behavior of each |
| 51 | device driver to differ significantly from one device to another. |
| 52 | This divergence of behavior has been very significant for \cdrom\ |
| 53 | devices; the way a particular drive reacts to a `standard' $ioctl()$ |
| 54 | call varies greatly from one device driver to another. To avoid making |
| 55 | their drivers totally inconsistent, the writers of \linux\ \cdrom\ |
| 56 | drivers generally created new device drivers by understanding, copying, |
| 57 | and then changing an existing one. Unfortunately, this practice did not |
| 58 | maintain uniform behavior across all the \linux\ \cdrom\ drivers. |
| 59 | |
| 60 | This document describes an effort to establish Uniform behavior across |
| 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 |
| 63 | drivers should implement them. Currently (as of the \linux\ 2.1.$x$ |
| 64 | development kernels) several low-level \cdrom\ device drivers, including |
| 65 | both IDE/ATAPI and SCSI, now use this Uniform interface. |
| 66 | |
| 67 | When the \cdrom\ was developed, the interface between the \cdrom\ drive |
| 68 | and the computer was not specified in the standards. As a result, many |
| 69 | different \cdrom\ interfaces were developed. Some of them had their |
| 70 | own proprietary design (Sony, Mitsumi, Panasonic, Philips), other |
| 71 | manufacturers adopted an existing electrical interface and changed |
| 72 | the functionality (CreativeLabs/SoundBlaster, Teac, Funai) or simply |
| 73 | adapted their drives to one or more of the already existing electrical |
| 74 | interfaces (Aztech, Sanyo, Funai, Vertos, Longshine, Optics Storage and |
| 75 | most of the `NoName' manufacturers). In cases where a new drive really |
| 76 | brought its own interface or used its own command set and flow control |
| 77 | scheme, either a separate driver had to be written, or an existing |
| 78 | driver had to be enhanced. History has delivered us \cdrom\ support for |
| 79 | many of these different interfaces. Nowadays, almost all new \cdrom\ |
| 80 | drives are either IDE/ATAPI or SCSI, and it is very unlikely that any |
| 81 | manufacturer will create a new interface. Even finding drives for the |
| 82 | old proprietary interfaces is getting difficult. |
| 83 | |
| 84 | When (in the 1.3.70's) I looked at the existing software interface, |
| 85 | which was expressed through \cdromh, it appeared to be a rather wild |
| 86 | set of commands and data formats.\footnote{I cannot recollect what |
| 87 | kernel version I looked at, then, presumably 1.2.13 and 1.3.34---the |
| 88 | latest kernel that I was indirectly involved in.} It seemed that many |
| 89 | features of the software interface had been added to accommodate the |
| 90 | capabilities of a particular drive, in an {\fo ad hoc\/} manner. More |
| 91 | importantly, it appeared that the behavior of the `standard' commands |
| 92 | was different for most of the different drivers: \eg, some drivers |
| 93 | close the tray if an $open()$ call occurs when the tray is open, while |
| 94 | others do not. Some drivers lock the door upon opening the device, to |
| 95 | prevent an incoherent file system, but others don't, to allow software |
| 96 | ejection. Undoubtedly, the capabilities of the different drives vary, |
| 97 | but even when two drives have the same capability their drivers' |
| 98 | behavior was usually different. |
| 99 | |
| 100 | I decided to start a discussion on how to make all the \linux\ \cdrom\ |
| 101 | drivers behave more uniformly. I began by contacting the developers of |
| 102 | the many \cdrom\ drivers found in the \linux\ kernel. Their reactions |
| 103 | encouraged me to write the \UCD\ which this document is intended to |
| 104 | describe. The implementation of the \UCD\ is in the file \cdromc. This |
| 105 | driver is intended to be an additional software layer that sits on top |
| 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\ |
| 108 | devices behave {\em exactly\/} the same (insofar as the underlying |
| 109 | hardware will allow). |
| 110 | |
| 111 | The goal of the \UCD\ is {\em not\/} to alienate driver developers who |
| 112 | have not yet taken steps to support this effort. The goal of \UCD\ is |
| 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 |
| 116 | between the low-level device driver code and the \linux\ kernel. Care |
| 117 | is taken that 100\,\% compatibility exists with the data structures and |
| 118 | programmer's interface defined in \cdromh. This guide was written to |
| 119 | help \cdrom\ driver developers adapt their code to use the \UCD\ code |
| 120 | defined in \cdromc. |
| 121 | |
| 122 | Personally, I think that the most important hardware interfaces are |
| 123 | the IDE/ATAPI drives and, of course, the SCSI drives, but as prices |
| 124 | of hardware drop continuously, it is also likely that people may have |
| 125 | more than one \cdrom\ drive, possibly of mixed types. It is important |
| 126 | that these drives behave in the same way. In December 1994, one of the |
| 127 | cheapest \cdrom\ drives was a Philips cm206, a double-speed proprietary |
| 128 | drive. In the months that I was busy writing a \linux\ driver for it, |
| 129 | proprietary drives became obsolete and IDE/ATAPI drives became the |
| 130 | standard. At the time of the last update to this document (November |
| 131 | 1997) it is becoming difficult to even {\em find} anything less than a |
| 132 | 16 speed \cdrom\ drive, and 24 speed drives are common. |
| 133 | |
| 134 | \newsection{Standardizing through another software level} |
| 135 | \label{cdrom.c} |
| 136 | |
| 137 | At the time this document was conceived, all drivers directly |
| 138 | implemented the \cdrom\ $ioctl()$ calls through their own routines. This |
| 139 | led to the danger of different drivers forgetting to do important things |
| 140 | like checking that the user was giving the driver valid data. More |
| 141 | importantly, this led to the divergence of behavior, which has already |
| 142 | been discussed. |
| 143 | |
| 144 | For this reason, the \UCD\ was created to enforce consistent \cdrom\ |
| 145 | drive behavior, and to provide a common set of services to the various |
| 146 | low-level \cdrom\ device drivers. The \UCD\ now provides another |
| 147 | software-level, that separates the $ioctl()$ and $open()$ implementation |
| 148 | from the actual hardware implementation. Note that this effort has |
| 149 | made few changes which will affect a user's application programs. The |
| 150 | greatest change involved moving the contents of the various low-level |
| 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 |
| 153 | interface, the interface defined in \cdromh. |
| 154 | |
| 155 | \cdrom\ drives are specific enough (\ie, different from other |
| 156 | block-devices such as floppy or hard disc drives), to define a set |
| 157 | of common {\em \cdrom\ device operations}, $<cdrom-device>_dops$. |
| 158 | These operations are different from the classical block-device file |
| 159 | operations, $<block-device>_fops$. |
| 160 | |
| 161 | The routines for the \UCD\ interface level are implemented in the file |
| 162 | \cdromc. In this file, the \UCD\ interfaces with the kernel as a block |
| 163 | device by registering the following general $struct\ file_operations$: |
| 164 | $$ |
| 165 | \halign{$#$\ \hfil&$#$\ \hfil&$/*$ \rm# $*/$\hfil\cr |
| 166 | struct& file_operations\ cdrom_fops = \{\hidewidth\cr |
| 167 | &NULL, & lseek \cr |
| 168 | &block_read, & read---general block-dev read \cr |
| 169 | &block_write, & write---general block-dev write \cr |
| 170 | &NULL, & readdir \cr |
| 171 | &NULL, & select \cr |
| 172 | &cdrom_ioctl, & ioctl \cr |
| 173 | &NULL, & mmap \cr |
| 174 | &cdrom_open, & open \cr |
| 175 | &cdrom_release, & release \cr |
| 176 | &NULL, & fsync \cr |
| 177 | &NULL, & fasync \cr |
| 178 | &cdrom_media_changed, & media change \cr |
| 179 | &NULL & revalidate \cr |
| 180 | \};\cr |
| 181 | } |
| 182 | $$ |
| 183 | |
| 184 | Every active \cdrom\ device shares this $struct$. The routines |
| 185 | declared above are all implemented in \cdromc, since this file is the |
| 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 |
| 189 | drivers. These routines simply implement certain {\em capabilities\/} |
| 190 | that are common to all \cdrom\ (and really, all removable-media |
| 191 | devices). |
| 192 | |
| 193 | Registration of a low-level \cdrom\ device driver is now done through |
| 194 | the general routines in \cdromc, not through the Virtual File System |
| 195 | (VFS) any more. The interface implemented in \cdromc\ is carried out |
| 196 | through two general structures that contain information about the |
| 197 | capabilities of the driver, and the specific drives on which the |
| 198 | driver operates. The structures are: |
| 199 | \begin{description} |
| 200 | \item[$cdrom_device_ops$] |
| 201 | This structure contains information about the low-level driver for a |
| 202 | \cdrom\ device. This structure is conceptually connected to the major |
| 203 | number of the device (although some drivers may have different |
| 204 | major numbers, as is the case for the IDE driver). |
| 205 | \item[$cdrom_device_info$] |
| 206 | This structure contains information about a particular \cdrom\ drive, |
| 207 | such as its device name, speed, etc. This structure is conceptually |
| 208 | connected to the minor number of the device. |
| 209 | \end{description} |
| 210 | |
| 211 | Registering a particular \cdrom\ drive with the \UCD\ is done by the |
| 212 | low-level device driver though a call to: |
| 213 | $$register_cdrom(struct\ cdrom_device_info * <device>_info) |
| 214 | $$ |
| 215 | The device information structure, $<device>_info$, contains all the |
| 216 | information needed for the kernel to interface with the low-level |
| 217 | \cdrom\ device driver. One of the most important entries in this |
| 218 | structure is a pointer to the $cdrom_device_ops$ structure of the |
| 219 | low-level driver. |
| 220 | |
| 221 | The device operations structure, $cdrom_device_ops$, contains a list |
| 222 | of pointers to the functions which are implemented in the low-level |
| 223 | device driver. When \cdromc\ accesses a \cdrom\ device, it does it |
| 224 | through the functions in this structure. It is impossible to know all |
| 225 | the capabilities of future \cdrom\ drives, so it is expected that this |
| 226 | list may need to be expanded from time to time as new technologies are |
| 227 | developed. For example, CD-R and CD-R/W drives are beginning to become |
| 228 | popular, and support will soon need to be added for them. For now, the |
| 229 | current $struct$ is: |
| 230 | $$ |
| 231 | \halign{$#$\ \hfil&$#$\ \hfil&\hbox to 10em{$#$\hss}& |
| 232 | $/*$ \rm# $*/$\hfil\cr |
| 233 | struct& cdrom_device_ops\ \{ \hidewidth\cr |
| 234 | &int& (* open)(struct\ cdrom_device_info *, int)\cr |
| 235 | &void& (* release)(struct\ cdrom_device_info *);\cr |
| 236 | &int& (* drive_status)(struct\ cdrom_device_info *, int);\cr |
| 237 | &int& (* media_changed)(struct\ cdrom_device_info *, int);\cr |
| 238 | &int& (* tray_move)(struct\ cdrom_device_info *, int);\cr |
| 239 | &int& (* lock_door)(struct\ cdrom_device_info *, int);\cr |
| 240 | &int& (* select_speed)(struct\ cdrom_device_info *, int);\cr |
| 241 | &int& (* select_disc)(struct\ cdrom_device_info *, int);\cr |
| 242 | &int& (* get_last_session) (struct\ cdrom_device_info *, |
| 243 | struct\ cdrom_multisession *{});\cr |
| 244 | &int& (* get_mcn)(struct\ cdrom_device_info *, struct\ cdrom_mcn *{});\cr |
| 245 | &int& (* reset)(struct\ cdrom_device_info *);\cr |
| 246 | &int& (* audio_ioctl)(struct\ cdrom_device_info *, unsigned\ int, |
| 247 | void *{});\cr |
| 248 | &int& (* dev_ioctl)(struct\ cdrom_device_info *, unsigned\ int, |
| 249 | unsigned\ long);\cr |
| 250 | \noalign{\medskip} |
| 251 | &const\ int& capability;& capability flags \cr |
| 252 | &int& n_minors;& number of active minor devices \cr |
| 253 | \};\cr |
| 254 | } |
| 255 | $$ |
| 256 | When a low-level device driver implements one of these capabilities, |
| 257 | it should add a function pointer to this $struct$. When a particular |
| 258 | function is not implemented, however, this $struct$ should contain a |
| 259 | NULL instead. The $capability$ flags specify the capabilities of the |
| 260 | \cdrom\ hardware and/or low-level \cdrom\ driver when a \cdrom\ drive |
| 261 | is registered with the \UCD. The value $n_minors$ should be a positive |
| 262 | value indicating the number of minor devices that are supported by |
| 263 | the low-level device driver, normally~1. Although these two variables |
| 264 | are `informative' rather than `operational,' they are included in |
| 265 | $cdrom_device_ops$ because they describe the capability of the {\em |
| 266 | driver\/} rather than the {\em drive}. Nomenclature has always been |
| 267 | difficult in computer programming. |
| 268 | |
| 269 | Note that most functions have fewer parameters than their |
| 270 | $blkdev_fops$ counterparts. This is because very little of the |
| 271 | information in the structures $inode$ and $file$ is used. For most |
| 272 | drivers, the main parameter is the $struct$ $cdrom_device_info$, from |
| 273 | which the major and minor number can be extracted. (Most low-level |
| 274 | \cdrom\ drivers don't even look at the major and minor number though, |
| 275 | since many of them only support one device.) This will be available |
| 276 | through $dev$ in $cdrom_device_info$ described below. |
| 277 | |
| 278 | The drive-specific, minor-like information that is registered with |
| 279 | \cdromc, currently contains the following fields: |
| 280 | $$ |
| 281 | \halign{$#$\ \hfil&$#$\ \hfil&\hbox to 10em{$#$\hss}& |
| 282 | $/*$ \rm# $*/$\hfil\cr |
| 283 | struct& cdrom_device_info\ \{ \hidewidth\cr |
| 284 | & struct\ cdrom_device_ops *& ops;& device operations for this major\cr |
| 285 | & struct\ cdrom_device_info *& next;& next device_info for this major\cr |
| 286 | & void *& handle;& driver-dependent data\cr |
| 287 | \noalign{\medskip} |
| 288 | & kdev_t& dev;& device number (incorporates minor)\cr |
| 289 | & int& mask;& mask of capability: disables them \cr |
| 290 | & int& speed;& maximum speed for reading data \cr |
| 291 | & int& capacity;& number of discs in a jukebox \cr |
| 292 | \noalign{\medskip} |
| 293 | &int& options : 30;& options flags \cr |
| 294 | &unsigned& mc_flags : 2;& media-change buffer flags \cr |
| 295 | & int& use_count;& number of times device is opened\cr |
| 296 | & char& name[20];& name of the device type\cr |
| 297 | \}\cr |
| 298 | }$$ |
| 299 | Using this $struct$, a linked list of the registered minor devices is |
| 300 | built, using the $next$ field. The device number, the device operations |
| 301 | struct and specifications of properties of the drive are stored in this |
| 302 | structure. |
| 303 | |
| 304 | The $mask$ flags can be used to mask out some of the capabilities listed |
| 305 | in $ops\to capability$, if a specific drive doesn't support a feature |
| 306 | of the driver. The value $speed$ specifies the maximum head-rate of the |
| 307 | drive, measured in units of normal audio speed (176\,kB/sec raw data or |
| 308 | 150\,kB/sec file system data). The value $n_discs$ should reflect the |
| 309 | number of discs the drive can hold simultaneously, if it is designed |
| 310 | as a juke-box, or otherwise~1. The parameters are declared $const$ |
| 311 | because they describe properties of the drive, which don't change after |
| 312 | registration. |
| 313 | |
| 314 | A few registers contain variables local to the \cdrom\ drive. The |
| 315 | flags $options$ are used to specify how the general \cdrom\ routines |
| 316 | should behave. These various flags registers should provide enough |
| 317 | flexibility to adapt to the different users' wishes (and {\em not\/} the |
| 318 | `arbitrary' wishes of the author of the low-level device driver, as is |
| 319 | the case in the old scheme). The register $mc_flags$ is used to buffer |
| 320 | the information from $media_changed()$ to two separate queues. Other |
| 321 | data that is specific to a minor drive, can be accessed through $handle$, |
| 322 | which can point to a data structure specific to the low-level driver. |
| 323 | The fields $use_count$, $next$, $options$ and $mc_flags$ need not be |
| 324 | initialized. |
| 325 | |
| 326 | The intermediate software layer that \cdromc\ forms will perform some |
| 327 | additional bookkeeping. The use count of the device (the number of |
| 328 | processes that have the device opened) is registered in $use_count$. The |
| 329 | function $cdrom_ioctl()$ will verify the appropriate user-memory regions |
| 330 | for read and write, and in case a location on the CD is transferred, |
| 331 | it will `sanitize' the format by making requests to the low-level |
| 332 | drivers in a standard format, and translating all formats between the |
| 333 | user-software and low level drivers. This relieves much of the drivers' |
| 334 | memory checking and format checking and translation. Also, the necessary |
| 335 | structures will be declared on the program stack. |
| 336 | |
| 337 | The implementation of the functions should be as defined in the |
| 338 | following sections. Two functions {\em must\/} be implemented, namely |
| 339 | $open()$ and $release()$. Other functions may be omitted, their |
| 340 | corresponding capability flags will be cleared upon registration. |
| 341 | Generally, a function returns zero on success and negative on error. A |
| 342 | function call should return only after the command has completed, but of |
| 343 | course waiting for the device should not use processor time. |
| 344 | |
| 345 | \subsection{$Int\ open(struct\ cdrom_device_info * cdi, int\ purpose)$} |
| 346 | |
| 347 | $Open()$ should try to open the device for a specific $purpose$, which |
| 348 | can be either: |
| 349 | \begin{itemize} |
| 350 | \item[0] Open for reading data, as done by {\tt {mount()}} (2), or the |
| 351 | user commands {\tt {dd}} or {\tt {cat}}. |
| 352 | \item[1] Open for $ioctl$ commands, as done by audio-CD playing |
| 353 | programs. |
| 354 | \end{itemize} |
| 355 | Notice that any strategic code (closing tray upon $open()$, etc.)\ is |
| 356 | done by the calling routine in \cdromc, so the low-level routine |
| 357 | should only be concerned with proper initialization, such as spinning |
| 358 | up the disc, etc. % and device-use count |
| 359 | |
| 360 | |
| 361 | \subsection{$Void\ release(struct\ cdrom_device_info * cdi)$} |
| 362 | |
| 363 | |
| 364 | Device-specific actions should be taken such as spinning down the device. |
| 365 | However, strategic actions such as ejection of the tray, or unlocking |
| 366 | the door, should be left over to the general routine $cdrom_release()$. |
| 367 | This is the only function returning type $void$. |
| 368 | |
| 369 | \subsection{$Int\ drive_status(struct\ cdrom_device_info * cdi, int\ slot_nr)$} |
| 370 | \label{drive status} |
| 371 | |
| 372 | The function $drive_status$, if implemented, should provide |
| 373 | information on the status of the drive (not the status of the disc, |
| 374 | which may or may not be in the drive). If the drive is not a changer, |
| 375 | $slot_nr$ should be ignored. In \cdromh\ the possibilities are listed: |
| 376 | $$ |
| 377 | \halign{$#$\ \hfil&$/*$ \rm# $*/$\hfil\cr |
| 378 | CDS_NO_INFO& no information available\cr |
| 379 | CDS_NO_DISC& no disc is inserted, tray is closed\cr |
| 380 | CDS_TRAY_OPEN& tray is opened\cr |
| 381 | CDS_DRIVE_NOT_READY& something is wrong, tray is moving?\cr |
| 382 | CDS_DISC_OK& a disc is loaded and everything is fine\cr |
| 383 | } |
| 384 | $$ |
| 385 | |
| 386 | \subsection{$Int\ media_changed(struct\ cdrom_device_info * cdi, int\ disc_nr)$} |
| 387 | |
| 388 | This function is very similar to the original function in $struct\ |
| 389 | file_operations$. It returns 1 if the medium of the device $cdi\to |
| 390 | dev$ has changed since the last call, and 0 otherwise. The parameter |
| 391 | $disc_nr$ identifies a specific slot in a juke-box, it should be |
| 392 | ignored for single-disc drives. Note that by `re-routing' this |
| 393 | function through $cdrom_media_changed()$, we can implement separate |
| 394 | queues for the VFS and a new $ioctl()$ function that can report device |
| 395 | changes to software (\eg, an auto-mounting daemon). |
| 396 | |
| 397 | \subsection{$Int\ tray_move(struct\ cdrom_device_info * cdi, int\ position)$} |
| 398 | |
| 399 | This function, if implemented, should control the tray movement. (No |
| 400 | other function should control this.) The parameter $position$ controls |
| 401 | the desired direction of movement: |
| 402 | \begin{itemize} |
| 403 | \item[0] Close tray |
| 404 | \item[1] Open tray |
| 405 | \end{itemize} |
| 406 | This function returns 0 upon success, and a non-zero value upon |
| 407 | error. Note that if the tray is already in the desired position, no |
| 408 | action need be taken, and the return value should be 0. |
| 409 | |
| 410 | \subsection{$Int\ lock_door(struct\ cdrom_device_info * cdi, int\ lock)$} |
| 411 | |
| 412 | This function (and no other code) controls locking of the door, if the |
| 413 | drive allows this. The value of $lock$ controls the desired locking |
| 414 | state: |
| 415 | \begin{itemize} |
| 416 | \item[0] Unlock door, manual opening is allowed |
| 417 | \item[1] Lock door, tray cannot be ejected manually |
| 418 | \end{itemize} |
| 419 | This function returns 0 upon success, and a non-zero value upon |
| 420 | error. Note that if the door is already in the requested state, no |
| 421 | action need be taken, and the return value should be 0. |
| 422 | |
| 423 | \subsection{$Int\ select_speed(struct\ cdrom_device_info * cdi, int\ speed)$} |
| 424 | |
| 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 |
| 429 | common). It has been reported that these drives can make reading |
| 430 | errors at these high speeds, reducing the speed can prevent data loss |
| 431 | in these circumstances. Finally, some of these drives can |
| 432 | make an annoyingly loud noise, which a lower speed may reduce. %Finally, |
| 433 | %although the audio-low-pass filters probably aren't designed for it, |
| 434 | %more than real-time playback of audio might be used for high-speed |
| 435 | %copying of audio tracks. |
| 436 | |
| 437 | This function specifies the speed at which data is read or audio is |
| 438 | played back. The value of $speed$ specifies the head-speed of the |
| 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 |
| 441 | operate at 300\,kB/sec you would call the CDROM_SELECT_SPEED $ioctl$ |
| 442 | with $speed=2$. The special value `0' means `auto-selection', \ie, |
| 443 | maximum data-rate or real-time audio rate. If the drive doesn't have |
| 444 | this `auto-selection' capability, the decision should be made on the |
| 445 | current disc loaded and the return value should be positive. A negative |
| 446 | return value indicates an error. |
| 447 | |
| 448 | \subsection{$Int\ select_disc(struct\ cdrom_device_info * cdi, int\ number)$} |
| 449 | |
| 450 | If the drive can store multiple discs (a juke-box) this function |
| 451 | will perform disc selection. It should return the number of the |
| 452 | selected disc on success, a negative value on error. Currently, only |
| 453 | the ide-cd driver supports this functionality. |
| 454 | |
| 455 | \subsection{$Int\ get_last_session(struct\ cdrom_device_info * cdi, struct\ |
| 456 | cdrom_multisession * ms_info)$} |
| 457 | |
| 458 | This function should implement the old corresponding $ioctl()$. For |
| 459 | device $cdi\to dev$, the start of the last session of the current disc |
| 460 | should be returned in the pointer argument $ms_info$. Note that |
| 461 | routines in \cdromc\ have sanitized this argument: its requested |
| 462 | format will {\em always\/} be of the type $CDROM_LBA$ (linear block |
| 463 | addressing mode), whatever the calling software requested. But |
| 464 | sanitization goes even further: the low-level implementation may |
| 465 | return the requested information in $CDROM_MSF$ format if it wishes so |
| 466 | (setting the $ms_info\rightarrow addr_format$ field appropriately, of |
| 467 | course) and the routines in \cdromc\ will make the transformation if |
| 468 | necessary. The return value is 0 upon success. |
| 469 | |
| 470 | \subsection{$Int\ get_mcn(struct\ cdrom_device_info * cdi, struct\ |
| 471 | cdrom_mcn * mcn)$} |
| 472 | |
| 473 | Some discs carry a `Media Catalog Number' (MCN), also called |
| 474 | `Universal Product Code' (UPC). This number should reflect the number |
| 475 | that is generally found in the bar-code on the product. Unfortunately, |
| 476 | the few discs that carry such a number on the disc don't even use the |
| 477 | same format. The return argument to this function is a pointer to a |
| 478 | pre-declared memory region of type $struct\ cdrom_mcn$. The MCN is |
| 479 | expected as a 13-character string, terminated by a null-character. |
| 480 | |
| 481 | \subsection{$Int\ reset(struct\ cdrom_device_info * cdi)$} |
| 482 | |
| 483 | This call should perform a hard-reset on the drive (although in |
| 484 | circumstances that a hard-reset is necessary, a drive may very well not |
| 485 | listen to commands anymore). Preferably, control is returned to the |
| 486 | caller only after the drive has finished resetting. If the drive is no |
| 487 | longer listening, it may be wise for the underlying low-level cdrom |
| 488 | driver to time out. |
| 489 | |
| 490 | \subsection{$Int\ audio_ioctl(struct\ cdrom_device_info * cdi, unsigned\ |
| 491 | int\ cmd, void * arg)$} |
| 492 | |
| 493 | Some of the \cdrom-$ioctl$s defined in \cdromh\ can be |
| 494 | implemented by the routines described above, and hence the function |
| 495 | $cdrom_ioctl$ will use those. However, most $ioctl$s deal with |
| 496 | audio-control. We have decided to leave these to be accessed through a |
| 497 | single function, repeating the arguments $cmd$ and $arg$. Note that |
| 498 | the latter is of type $void*{}$, rather than $unsigned\ long\ |
| 499 | int$. The routine $cdrom_ioctl()$ does do some useful things, |
| 500 | though. It sanitizes the address format type to $CDROM_MSF$ (Minutes, |
| 501 | Seconds, Frames) for all audio calls. It also verifies the memory |
| 502 | location of $arg$, and reserves stack-memory for the argument. This |
| 503 | makes implementation of the $audio_ioctl()$ much simpler than in the |
| 504 | old driver scheme. For example, you may look up the function |
| 505 | $cm206_audio_ioctl()$ in {\tt {cm206.c}} that should be updated with |
| 506 | this documentation. |
| 507 | |
| 508 | An unimplemented ioctl should return $-ENOSYS$, but a harmless request |
| 509 | (\eg, $CDROMSTART$) may be ignored by returning 0 (success). Other |
| 510 | errors should be according to the standards, whatever they are. When |
| 511 | an error is returned by the low-level driver, the \UCD\ tries whenever |
| 512 | possible to return the error code to the calling program. (We may decide |
| 513 | to sanitize the return value in $cdrom_ioctl()$ though, in order to |
| 514 | guarantee a uniform interface to the audio-player software.) |
| 515 | |
| 516 | \subsection{$Int\ dev_ioctl(struct\ cdrom_device_info * cdi, unsigned\ int\ |
| 517 | cmd, unsigned\ long\ arg)$} |
| 518 | |
| 519 | Some $ioctl$s seem to be specific to certain \cdrom\ drives. That is, |
| 520 | they are introduced to service some capabilities of certain drives. In |
| 521 | fact, there are 6 different $ioctl$s for reading data, either in some |
| 522 | particular kind of format, or audio data. Not many drives support |
| 523 | reading audio tracks as data, I believe this is because of protection |
| 524 | of copyrights of artists. Moreover, I think that if audio-tracks are |
| 525 | supported, it should be done through the VFS and not via $ioctl$s. A |
| 526 | problem here could be the fact that audio-frames are 2352 bytes long, |
| 527 | so either the audio-file-system should ask for 75264 bytes at once |
| 528 | (the least common multiple of 512 and 2352), or the drivers should |
| 529 | bend their backs to cope with this incoherence (to which I would be |
| 530 | opposed). Furthermore, it is very difficult for the hardware to find |
| 531 | the exact frame boundaries, since there are no synchronization headers |
| 532 | in audio frames. Once these issues are resolved, this code should be |
| 533 | standardized in \cdromc. |
| 534 | |
| 535 | Because there are so many $ioctl$s that seem to be introduced to |
| 536 | satisfy certain drivers,\footnote{Is there software around that |
| 537 | actually uses these? I'd be interested!} any `non-standard' $ioctl$s |
| 538 | are routed through the call $dev_ioctl()$. In principle, `private' |
| 539 | $ioctl$s should be numbered after the device's major number, and not |
| 540 | the general \cdrom\ $ioctl$ number, {\tt {0x53}}. Currently the |
| 541 | non-supported $ioctl$s are: {\it CDROMREADMODE1, CDROMREADMODE2, |
| 542 | CDROMREADAUDIO, CDROMREADRAW, CDROMREADCOOKED, CDROMSEEK, |
| 543 | CDROMPLAY\-BLK and CDROM\-READALL}. |
| 544 | |
| 545 | |
| 546 | \subsection{\cdrom\ capabilities} |
| 547 | \label{capability} |
| 548 | |
| 549 | Instead of just implementing some $ioctl$ calls, the interface in |
| 550 | \cdromc\ supplies the possibility to indicate the {\em capabilities\/} |
| 551 | of a \cdrom\ drive. This can be done by ORing any number of |
| 552 | capability-constants that are defined in \cdromh\ at the registration |
| 553 | phase. Currently, the capabilities are any of: |
| 554 | $$ |
| 555 | \halign{$#$\ \hfil&$/*$ \rm# $*/$\hfil\cr |
| 556 | CDC_CLOSE_TRAY& can close tray by software control\cr |
| 557 | CDC_OPEN_TRAY& can open tray\cr |
| 558 | CDC_LOCK& can lock and unlock the door\cr |
| 559 | CDC_SELECT_SPEED& can select speed, in units of $\sim$150\,kB/s\cr |
| 560 | CDC_SELECT_DISC& drive is juke-box\cr |
| 561 | CDC_MULTI_SESSION& can read sessions $>\rm1$\cr |
| 562 | CDC_MCN& can read Media Catalog Number\cr |
| 563 | CDC_MEDIA_CHANGED& can report if disc has changed\cr |
| 564 | CDC_PLAY_AUDIO& can perform audio-functions (play, pause, etc)\cr |
| 565 | CDC_RESET& hard reset device\cr |
| 566 | CDC_IOCTLS& driver has non-standard ioctls\cr |
| 567 | CDC_DRIVE_STATUS& driver implements drive status\cr |
| 568 | } |
| 569 | $$ |
| 570 | The capability flag is declared $const$, to prevent drivers from |
| 571 | accidentally tampering with the contents. The capability fags actually |
| 572 | inform \cdromc\ of what the driver can do. If the drive found |
| 573 | by the driver does not have the capability, is can be masked out by |
| 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 |
| 576 | hence its corresponding flags in $capability$ will be set. But a SCSI |
| 577 | \cdrom\ drive might be a caddy system, which can't load the tray, and |
| 578 | hence for this drive the $cdrom_device_info$ struct will have set |
| 579 | the $CDC_CLOSE_TRAY$ bit in $mask$. |
| 580 | |
| 581 | In the file \cdromc\ you will encounter many constructions of the type |
| 582 | $$\it |
| 583 | if\ (cdo\rightarrow capability \mathrel\& \mathord{\sim} cdi\rightarrow mask |
| 584 | \mathrel{\&} CDC_<capability>) \ldots |
| 585 | $$ |
| 586 | There is no $ioctl$ to set the mask\dots The reason is that |
| 587 | I think it is better to control the {\em behavior\/} rather than the |
| 588 | {\em capabilities}. |
| 589 | |
| 590 | \subsection{Options} |
| 591 | |
| 592 | A final flag register controls the {\em behavior\/} of the \cdrom\ |
| 593 | drives, in order to satisfy different users' wishes, hopefully |
| 594 | independently of the ideas of the respective author who happened to |
| 595 | have made the drive's support available to the \linux\ community. The |
| 596 | current behavior options are: |
| 597 | $$ |
| 598 | \halign{$#$\ \hfil&$/*$ \rm# $*/$\hfil\cr |
| 599 | CDO_AUTO_CLOSE& try to close tray upon device $open()$\cr |
| 600 | CDO_AUTO_EJECT& try to open tray on last device $close()$\cr |
| 601 | CDO_USE_FFLAGS& use $file_pointer\rightarrow f_flags$ to indicate |
| 602 | purpose for $open()$\cr |
| 603 | CDO_LOCK& try to lock door if device is opened\cr |
| 604 | CDO_CHECK_TYPE& ensure disc type is data if opened for data\cr |
| 605 | } |
| 606 | $$ |
| 607 | |
| 608 | The initial value of this register is $CDO_AUTO_CLOSE \mathrel| |
| 609 | CDO_USE_FFLAGS \mathrel| CDO_LOCK$, reflecting my own view on user |
| 610 | interface and software standards. Before you protest, there are two |
| 611 | new $ioctl$s implemented in \cdromc, that allow you to control the |
| 612 | behavior by software. These are: |
| 613 | $$ |
| 614 | \halign{$#$\ \hfil&$/*$ \rm# $*/$\hfil\cr |
| 615 | CDROM_SET_OPTIONS& set options specified in $(int)\ arg$\cr |
| 616 | CDROM_CLEAR_OPTIONS& clear options specified in $(int)\ arg$\cr |
| 617 | } |
| 618 | $$ |
| 619 | One option needs some more explanation: $CDO_USE_FFLAGS$. In the next |
| 620 | newsection we explain what the need for this option is. |
| 621 | |
| 622 | A software package {\tt setcd}, available from the Debian distribution |
| 623 | and {\tt sunsite.unc.edu}, allows user level control of these flags. |
| 624 | |
| 625 | \newsection{The need to know the purpose of opening the \cdrom\ device} |
| 626 | |
| 627 | Traditionally, Unix devices can be used in two different `modes', |
| 628 | either by reading/writing to the device file, or by issuing |
| 629 | controlling commands to the device, by the device's $ioctl()$ |
| 630 | call. The problem with \cdrom\ drives, is that they can be used for |
| 631 | two entirely different purposes. One is to mount removable |
| 632 | file systems, \cdrom s, the other is to play audio CD's. Audio commands |
| 633 | are implemented entirely through $ioctl$s, presumably because the |
| 634 | first implementation (SUN?) has been such. In principle there is |
| 635 | nothing wrong with this, but a good control of the `CD player' demands |
| 636 | that the device can {\em always\/} be opened in order to give the |
| 637 | $ioctl$ commands, regardless of the state the drive is in. |
| 638 | |
| 639 | On the other hand, when used as a removable-media disc drive (what the |
| 640 | original purpose of \cdrom s is) we would like to make sure that the |
| 641 | disc drive is ready for operation upon opening the device. In the old |
| 642 | scheme, some \cdrom\ drivers don't do any integrity checking, resulting |
| 643 | in a number of i/o errors reported by the VFS to the kernel when an |
| 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; |
| 646 | it more-or-less looks like the old IBM-PC trying to read an empty floppy |
| 647 | drive for a couple of seconds, after which the system complains it |
| 648 | can't read from it. Nowadays we can {\em sense\/} the existence of a |
| 649 | removable medium in a drive, and we believe we should exploit that |
| 650 | fact. An integrity check on opening of the device, that verifies the |
| 651 | availability of a \cdrom\ and its correct type (data), would be |
| 652 | desirable. |
| 653 | |
| 654 | These two ways of using a \cdrom\ drive, principally for data and |
| 655 | secondarily for playing audio discs, have different demands for the |
| 656 | behavior of the $open()$ call. Audio use simply wants to open the |
| 657 | device in order to get a file handle which is needed for issuing |
| 658 | $ioctl$ commands, while data use wants to open for correct and |
| 659 | reliable data transfer. The only way user programs can indicate what |
| 660 | their {\em purpose\/} of opening the device is, is through the $flags$ |
| 661 | parameter (see {\tt {open(2)}}). For \cdrom\ devices, these flags aren't |
| 662 | implemented (some drivers implement checking for write-related flags, |
| 663 | but this is not strictly necessary if the device file has correct |
| 664 | permission flags). Most option flags simply don't make sense to |
| 665 | \cdrom\ devices: $O_CREAT$, $O_NOCTTY$, $O_TRUNC$, $O_APPEND$, and |
| 666 | $O_SYNC$ have no meaning to a \cdrom. |
| 667 | |
| 668 | We therefore propose to use the flag $O_NONBLOCK$ to indicate |
| 669 | that the device is opened just for issuing $ioctl$ |
| 670 | commands. Strictly, the meaning of $O_NONBLOCK$ is that opening and |
| 671 | subsequent calls to the device don't cause the calling process to |
| 672 | wait. We could interpret this as ``don't wait until someone has |
| 673 | inserted some valid data-\cdrom.'' Thus, our proposal of the |
| 674 | implementation for the $open()$ call for \cdrom s is: |
| 675 | \begin{itemize} |
| 676 | \item If no other flags are set than $O_RDONLY$, the device is opened |
| 677 | for data transfer, and the return value will be 0 only upon successful |
| 678 | initialization of the transfer. The call may even induce some actions |
| 679 | on the \cdrom, such as closing the tray. |
| 680 | \item If the option flag $O_NONBLOCK$ is set, opening will always be |
| 681 | successful, unless the whole device doesn't exist. The drive will take |
| 682 | no actions whatsoever. |
| 683 | \end{itemize} |
| 684 | |
| 685 | \subsection{And what about standards?} |
| 686 | |
| 687 | You might hesitate to accept this proposal as it comes from the |
| 688 | \linux\ community, and not from some standardizing institute. What |
| 689 | about SUN, SGI, HP and all those other Unix and hardware vendors? |
| 690 | Well, these companies are in the lucky position that they generally |
| 691 | control both the hardware and software of their supported products, |
| 692 | and are large enough to set their own standard. They do not have to |
| 693 | deal with a dozen or more different, competing hardware |
| 694 | configurations.\footnote{Incidentally, I think that SUN's approach to |
| 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 |
| 699 | mounted at the similar location, \ie, no matter in which particular |
| 700 | machine you insert a \cdrom, it will always appear at the same |
| 701 | position in the directory tree, on every system. When I wanted to |
| 702 | implement such a user-program for \linux, I came across the |
| 703 | differences in behavior of the various drivers, and the need for an |
| 704 | $ioctl$ informing about media changes.} |
| 705 | |
| 706 | We believe that using $O_NONBLOCK$ to indicate that a device is being opened |
| 707 | for $ioctl$ commands only can be easily introduced in the \linux\ |
| 708 | community. All the CD-player authors will have to be informed, we can |
| 709 | even send in our own patches to the programs. The use of $O_NONBLOCK$ |
| 710 | has most likely no influence on the behavior of the CD-players on |
| 711 | other operating systems than \linux. Finally, a user can always revert |
| 712 | to old behavior by a call to $ioctl(file_descriptor, CDROM_CLEAR_OPTIONS, |
| 713 | CDO_USE_FFLAGS)$. |
| 714 | |
| 715 | \subsection{The preferred strategy of $open()$} |
| 716 | |
| 717 | The routines in \cdromc\ are designed in such a way that run-time |
| 718 | configuration of the behavior of \cdrom\ devices (of {\em any\/} type) |
| 719 | can be carried out, by the $CDROM_SET/CLEAR_OPTIONS$ $ioctls$. Thus, various |
| 720 | modes of operation can be set: |
| 721 | \begin{description} |
| 722 | \item[$CDO_AUTO_CLOSE \mathrel| CDO_USE_FFLAGS \mathrel| CDO_LOCK$] This |
| 723 | is the default setting. (With $CDO_CHECK_TYPE$ it will be better, in the |
| 724 | future.) If the device is not yet opened by any other process, and if |
| 725 | the device is being opened for data ($O_NONBLOCK$ is not set) and the |
| 726 | tray is found to be open, an attempt to close the tray is made. Then, |
| 727 | it is verified that a disc is in the drive and, if $CDO_CHECK_TYPE$ is |
| 728 | set, that it contains tracks of type `data mode 1.' Only if all tests |
| 729 | are passed is the return value zero. The door is locked to prevent file |
| 730 | system corruption. If the drive is opened for audio ($O_NONBLOCK$ is |
| 731 | set), no actions are taken and a value of 0 will be returned. |
| 732 | \item[$CDO_AUTO_CLOSE \mathrel| CDO_AUTO_EJECT \mathrel| CDO_LOCK$] This |
| 733 | mimics the behavior of the current sbpcd-driver. The option flags are |
| 734 | ignored, the tray is closed on the first open, if necessary. Similarly, |
| 735 | the tray is opened on the last release, \ie, if a \cdrom\ is unmounted, |
| 736 | it is automatically ejected, such that the user can replace it. |
| 737 | \end{description} |
| 738 | We hope that these option can convince everybody (both driver |
| 739 | maintainers and user program developers) to adopt the new \cdrom\ |
| 740 | driver scheme and option flag interpretation. |
| 741 | |
| 742 | \newsection{Description of routines in \cdromc} |
| 743 | |
| 744 | Only a few routines in \cdromc\ are exported to the drivers. In this |
| 745 | new section we will discuss these, as well as the functions that `take |
| 746 | over' the \cdrom\ interface to the kernel. The header file belonging |
| 747 | to \cdromc\ is called \cdromh. Formerly, some of the contents of this |
| 748 | file were placed in the file {\tt {ucdrom.h}}, but this file has now been |
| 749 | merged back into \cdromh. |
| 750 | |
| 751 | \subsection{$Struct\ file_operations\ cdrom_fops$} |
| 752 | |
| 753 | The contents of this structure were described in section~\ref{cdrom.c}. |
| 754 | A pointer to this structure is assigned to the $fops$ field |
| 755 | of the $struct gendisk$. |
| 756 | |
| 757 | \subsection{$Int\ register_cdrom( struct\ cdrom_device_info\ * cdi)$} |
| 758 | |
| 759 | This function is used in about the same way one registers $cdrom_fops$ |
| 760 | with the kernel, the device operations and information structures, |
| 761 | as described in section~\ref{cdrom.c}, should be registered with the |
| 762 | \UCD: |
| 763 | $$ |
| 764 | register_cdrom(\&<device>_info)); |
| 765 | $$ |
| 766 | This function returns zero upon success, and non-zero upon |
| 767 | failure. The structure $<device>_info$ should have a pointer to the |
| 768 | driver's $<device>_dops$, as in |
| 769 | $$ |
| 770 | \vbox{\halign{&$#$\hfil\cr |
| 771 | struct\ &cdrom_device_info\ <device>_info = \{\cr |
| 772 | & <device>_dops;\cr |
| 773 | &\ldots\cr |
| 774 | \}\cr |
| 775 | }}$$ |
| 776 | Note that a driver must have one static structure, $<device>_dops$, while |
| 777 | it may have as many structures $<device>_info$ as there are minor devices |
| 778 | active. $Register_cdrom()$ builds a linked list from these. |
| 779 | |
| 780 | \subsection{$Int\ unregister_cdrom(struct\ cdrom_device_info * cdi)$} |
| 781 | |
| 782 | Unregistering device $cdi$ with minor number $MINOR(cdi\to dev)$ removes |
| 783 | the minor device from the list. If it was the last registered minor for |
| 784 | the low-level driver, this disconnects the registered device-operation |
| 785 | routines from the \cdrom\ interface. This function returns zero upon |
| 786 | success, and non-zero upon failure. |
| 787 | |
| 788 | \subsection{$Int\ cdrom_open(struct\ inode * ip, struct\ file * fp)$} |
| 789 | |
| 790 | This function is not called directly by the low-level drivers, it is |
| 791 | listed in the standard $cdrom_fops$. If the VFS opens a file, this |
| 792 | function becomes active. A strategy is implemented in this routine, |
| 793 | taking care of all capabilities and options that are set in the |
| 794 | $cdrom_device_ops$ connected to the device. Then, the program flow is |
| 795 | transferred to the device_dependent $open()$ call. |
| 796 | |
| 797 | \subsection{$Void\ cdrom_release(struct\ inode *ip, struct\ file |
| 798 | *fp)$} |
| 799 | |
| 800 | This function implements the reverse-logic of $cdrom_open()$, and then |
| 801 | calls the device-dependent $release()$ routine. When the use-count has |
| 802 | reached 0, the allocated buffers are flushed by calls to $sync_dev(dev)$ |
| 803 | and $invalidate_buffers(dev)$. |
| 804 | |
| 805 | |
| 806 | \subsection{$Int\ cdrom_ioctl(struct\ inode *ip, struct\ file *fp, |
| 807 | unsigned\ int\ cmd, unsigned\ long\ arg)$} |
| 808 | \label{cdrom-ioctl} |
| 809 | |
| 810 | This function handles all the standard $ioctl$ requests for \cdrom\ |
| 811 | devices in a uniform way. The different calls fall into three |
| 812 | categories: $ioctl$s that can be directly implemented by device |
| 813 | operations, ones that are routed through the call $audio_ioctl()$, and |
| 814 | the remaining ones, that are presumable device-dependent. Generally, a |
| 815 | negative return value indicates an error. |
| 816 | |
| 817 | \subsubsection{Directly implemented $ioctl$s} |
| 818 | \label{ioctl-direct} |
| 819 | |
| 820 | The following `old' \cdrom-$ioctl$s are implemented by directly |
| 821 | calling device-operations in $cdrom_device_ops$, if implemented and |
| 822 | not masked: |
| 823 | \begin{description} |
| 824 | \item[CDROMMULTISESSION] Requests the last session on a \cdrom. |
| 825 | \item[CDROMEJECT] Open tray. |
| 826 | \item[CDROMCLOSETRAY] Close tray. |
| 827 | \item[CDROMEJECT_SW] If $arg\not=0$, set behavior to auto-close (close |
| 828 | tray on first open) and auto-eject (eject on last release), otherwise |
| 829 | set behavior to non-moving on $open()$ and $release()$ calls. |
| 830 | \item[CDROM_GET_MCN] Get the Media Catalog Number from a CD. |
| 831 | \end{description} |
| 832 | |
| 833 | \subsubsection{$Ioctl$s routed through $audio_ioctl()$} |
| 834 | \label{ioctl-audio} |
| 835 | |
| 836 | The following set of $ioctl$s are all implemented through a call to |
| 837 | the $cdrom_fops$ function $audio_ioctl()$. Memory checks and |
| 838 | allocation are performed in $cdrom_ioctl()$, and also sanitization of |
| 839 | address format ($CDROM_LBA$/$CDROM_MSF$) is done. |
| 840 | \begin{description} |
| 841 | \item[CDROMSUBCHNL] Get sub-channel data in argument $arg$ of type $struct\ |
| 842 | cdrom_subchnl *{}$. |
| 843 | \item[CDROMREADTOCHDR] Read Table of Contents header, in $arg$ of type |
| 844 | $struct\ cdrom_tochdr *{}$. |
| 845 | \item[CDROMREADTOCENTRY] Read a Table of Contents entry in $arg$ and |
| 846 | specified by $arg$ of type $struct\ cdrom_tocentry *{}$. |
| 847 | \item[CDROMPLAYMSF] Play audio fragment specified in Minute, Second, |
| 848 | Frame format, delimited by $arg$ of type $struct\ cdrom_msf *{}$. |
| 849 | \item[CDROMPLAYTRKIND] Play audio fragment in track-index format |
| 850 | delimited by $arg$ of type $struct\ \penalty-1000 cdrom_ti *{}$. |
| 851 | \item[CDROMVOLCTRL] Set volume specified by $arg$ of type $struct\ |
| 852 | cdrom_volctrl *{}$. |
| 853 | \item[CDROMVOLREAD] Read volume into by $arg$ of type $struct\ |
| 854 | cdrom_volctrl *{}$. |
| 855 | \item[CDROMSTART] Spin up disc. |
| 856 | \item[CDROMSTOP] Stop playback of audio fragment. |
| 857 | \item[CDROMPAUSE] Pause playback of audio fragment. |
| 858 | \item[CDROMRESUME] Resume playing. |
| 859 | \end{description} |
| 860 | |
| 861 | \subsubsection{New $ioctl$s in \cdromc} |
| 862 | |
| 863 | The following $ioctl$s have been introduced to allow user programs to |
| 864 | control the behavior of individual \cdrom\ devices. New $ioctl$ |
| 865 | commands can be identified by the underscores in their names. |
| 866 | \begin{description} |
| 867 | \item[CDROM_SET_OPTIONS] Set options specified by $arg$. Returns the |
| 868 | option flag register after modification. Use $arg = \rm0$ for reading |
| 869 | the current flags. |
| 870 | \item[CDROM_CLEAR_OPTIONS] Clear options specified by $arg$. Returns |
| 871 | the option flag register after modification. |
| 872 | \item[CDROM_SELECT_SPEED] Select head-rate speed of disc specified as |
| 873 | by $arg$ in units of standard cdrom speed (176\,kB/sec raw data or |
| 874 | 150\,kB/sec file system data). The value 0 means `auto-select', \ie, |
| 875 | play audio discs at real time and data discs at maximum speed. The value |
| 876 | $arg$ is checked against the maximum head rate of the drive found in the |
| 877 | $cdrom_dops$. |
| 878 | \item[CDROM_SELECT_DISC] Select disc numbered $arg$ from a juke-box. |
| 879 | First disc is numbered 0. The number $arg$ is checked against the |
| 880 | maximum number of discs in the juke-box found in the $cdrom_dops$. |
| 881 | \item[CDROM_MEDIA_CHANGED] Returns 1 if a disc has been changed since |
| 882 | the last call. Note that calls to $cdrom_media_changed$ by the VFS |
| 883 | are treated by an independent queue, so both mechanisms will detect |
| 884 | a media change once. For juke-boxes, an extra argument $arg$ |
| 885 | specifies the slot for which the information is given. The special |
| 886 | value $CDSL_CURRENT$ requests that information about the currently |
| 887 | selected slot be returned. |
| 888 | \item[CDROM_DRIVE_STATUS] Returns the status of the drive by a call to |
| 889 | $drive_status()$. Return values are defined in section~\ref{drive |
| 890 | status}. Note that this call doesn't return information on the |
| 891 | current playing activity of the drive; this can be polled through an |
| 892 | $ioctl$ call to $CDROMSUBCHNL$. For juke-boxes, an extra argument |
| 893 | $arg$ specifies the slot for which (possibly limited) information is |
| 894 | given. The special value $CDSL_CURRENT$ requests that information |
| 895 | about the currently selected slot be returned. |
| 896 | \item[CDROM_DISC_STATUS] Returns the type of the disc currently in the |
| 897 | drive. It should be viewed as a complement to $CDROM_DRIVE_STATUS$. |
| 898 | This $ioctl$ can provide \emph {some} information about the current |
| 899 | disc that is inserted in the drive. This functionality used to be |
| 900 | implemented in the low level drivers, but is now carried out |
| 901 | entirely in \UCD. |
| 902 | |
| 903 | The history of development of the CD's use as a carrier medium for |
| 904 | various digital information has lead to many different disc types. |
| 905 | This $ioctl$ is useful only in the case that CDs have \emph {only |
| 906 | one} type of data on them. While this is often the case, it is |
| 907 | also very common for CDs to have some tracks with data, and some |
| 908 | tracks with audio. Because this is an existing interface, rather |
| 909 | than fixing this interface by changing the assumptions it was made |
| 910 | under, thereby breaking all user applications that use this |
| 911 | function, the \UCD\ implements this $ioctl$ as follows: If the CD in |
| 912 | question has audio tracks on it, and it has absolutely no CD-I, XA, |
| 913 | or data tracks on it, it will be reported as $CDS_AUDIO$. If it has |
| 914 | both audio and data tracks, it will return $CDS_MIXED$. If there |
| 915 | are no audio tracks on the disc, and if the CD in question has any |
| 916 | CD-I tracks on it, it will be reported as $CDS_XA_2_2$. Failing |
| 917 | that, if the CD in question has any XA tracks on it, it will be |
| 918 | reported as $CDS_XA_2_1$. Finally, if the CD in question has any |
| 919 | data tracks on it, it will be reported as a data CD ($CDS_DATA_1$). |
| 920 | |
| 921 | This $ioctl$ can return: |
| 922 | $$ |
| 923 | \halign{$#$\ \hfil&$/*$ \rm# $*/$\hfil\cr |
| 924 | CDS_NO_INFO& no information available\cr |
| 925 | CDS_NO_DISC& no disc is inserted, or tray is opened\cr |
| 926 | CDS_AUDIO& Audio disc (2352 audio bytes/frame)\cr |
| 927 | CDS_DATA_1& data disc, mode 1 (2048 user bytes/frame)\cr |
| 928 | CDS_XA_2_1& mixed data (XA), mode 2, form 1 (2048 user bytes)\cr |
| 929 | CDS_XA_2_2& mixed data (XA), mode 2, form 1 (2324 user bytes)\cr |
| 930 | CDS_MIXED& mixed audio/data disc\cr |
| 931 | } |
| 932 | $$ |
| 933 | For some information concerning frame layout of the various disc |
| 934 | types, see a recent version of \cdromh. |
| 935 | |
| 936 | \item[CDROM_CHANGER_NSLOTS] Returns the number of slots in a |
| 937 | juke-box. |
| 938 | \item[CDROMRESET] Reset the drive. |
| 939 | \item[CDROM_GET_CAPABILITY] Returns the $capability$ flags for the |
| 940 | drive. Refer to section \ref{capability} for more information on |
| 941 | these flags. |
| 942 | \item[CDROM_LOCKDOOR] Locks the door of the drive. $arg == \rm0$ |
| 943 | unlocks the door, any other value locks it. |
| 944 | \item[CDROM_DEBUG] Turns on debugging info. Only root is allowed |
| 945 | to do this. Same semantics as CDROM_LOCKDOOR. |
| 946 | \end{description} |
| 947 | |
| 948 | \subsubsection{Device dependent $ioctl$s} |
| 949 | |
| 950 | Finally, all other $ioctl$s are passed to the function $dev_ioctl()$, |
| 951 | if implemented. No memory allocation or verification is carried out. |
| 952 | |
| 953 | \newsection{How to update your driver} |
| 954 | |
| 955 | \begin{enumerate} |
| 956 | \item Make a backup of your current driver. |
| 957 | \item Get hold of the files \cdromc\ and \cdromh, they should be in |
| 958 | the directory tree that came with this documentation. |
| 959 | \item Make sure you include \cdromh. |
| 960 | \item Change the 3rd argument of $register_blkdev$ from |
| 961 | $\&<your-drive>_fops$ to $\&cdrom_fops$. |
| 962 | \item Just after that line, add the following to register with the \UCD: |
| 963 | $$register_cdrom(\&<your-drive>_info);$$ |
| 964 | Similarly, add a call to $unregister_cdrom()$ at the appropriate place. |
| 965 | \item Copy an example of the device-operations $struct$ to your |
| 966 | source, \eg, from {\tt {cm206.c}} $cm206_dops$, and change all |
| 967 | entries to names corresponding to your driver, or names you just |
| 968 | happen to like. If your driver doesn't support a certain function, |
| 969 | make the entry $NULL$. At the entry $capability$ you should list all |
| 970 | capabilities your driver currently supports. If your driver |
| 971 | has a capability that is not listed, please send me a message. |
| 972 | \item Copy the $cdrom_device_info$ declaration from the same example |
| 973 | driver, and modify the entries according to your needs. If your |
| 974 | driver dynamically determines the capabilities of the hardware, this |
| 975 | structure should also be declared dynamically. |
| 976 | \item Implement all functions in your $<device>_dops$ structure, |
| 977 | according to prototypes listed in \cdromh, and specifications given |
| 978 | in section~\ref{cdrom.c}. Most likely you have already implemented |
| 979 | the code in a large part, and you will almost certainly need to adapt the |
| 980 | prototype and return values. |
| 981 | \item Rename your $<device>_ioctl()$ function to $audio_ioctl$ and |
| 982 | change the prototype a little. Remove entries listed in the first |
| 983 | part in section~\ref{cdrom-ioctl}, if your code was OK, these are |
| 984 | just calls to the routines you adapted in the previous step. |
| 985 | \item You may remove all remaining memory checking code in the |
| 986 | $audio_ioctl()$ function that deals with audio commands (these are |
| 987 | listed in the second part of section~\ref{cdrom-ioctl}). There is no |
| 988 | need for memory allocation either, so most $case$s in the $switch$ |
| 989 | statement look similar to: |
| 990 | $$ |
| 991 | case\ CDROMREADTOCENTRY\colon get_toc_entry\bigl((struct\ |
| 992 | cdrom_tocentry *{})\ arg\bigr); |
| 993 | $$ |
| 994 | \item All remaining $ioctl$ cases must be moved to a separate |
| 995 | function, $<device>_ioctl$, the device-dependent $ioctl$s. Note that |
| 996 | memory checking and allocation must be kept in this code! |
| 997 | \item Change the prototypes of $<device>_open()$ and |
| 998 | $<device>_release()$, and remove any strategic code (\ie, tray |
| 999 | movement, door locking, etc.). |
| 1000 | \item Try to recompile the drivers. We advise you to use modules, both |
| 1001 | for {\tt {cdrom.o}} and your driver, as debugging is much easier this |
| 1002 | way. |
| 1003 | \end{enumerate} |
| 1004 | |
| 1005 | \newsection{Thanks} |
| 1006 | |
| 1007 | Thanks to all the people involved. First, Erik Andersen, who has |
| 1008 | taken over the torch in maintaining \cdromc\ and integrating much |
| 1009 | \cdrom-related code in the 2.1-kernel. Thanks to Scott Snyder and |
| 1010 | Gerd Knorr, who were the first to implement this interface for SCSI |
| 1011 | and IDE-CD drivers and added many ideas for extension of the data |
Jan Engelhardt | 96de0e2 | 2007-10-19 23:21:04 +0200 | [diff] [blame] | 1012 | structures relative to kernel~2.0. Further thanks to Heiko Ei{\sz}feldt, |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 1013 | Thomas Quinot, Jon Tombs, Ken Pizzini, Eberhard M\"onkeberg and Andrew |
| 1014 | Kroll, the \linux\ \cdrom\ device driver developers who were kind |
| 1015 | enough to give suggestions and criticisms during the writing. Finally |
| 1016 | of course, I want to thank Linus Torvalds for making this possible in |
| 1017 | the first place. |
| 1018 | |
| 1019 | \vfill |
| 1020 | $ \version\ $ |
| 1021 | \eject |
| 1022 | \end{document} |