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