Commit | Line | Data |
---|---|---|
1da177e4 LT |
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 | ||
0a0c4114 | 780 | \subsection{$Void\ unregister_cdrom(struct\ cdrom_device_info * cdi)$} |
1da177e4 LT |
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 | |
96de0e25 | 1012 | structures relative to kernel~2.0. Further thanks to Heiko Ei{\sz}feldt, |
1da177e4 LT |
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} |