1=======================
2A 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
11Introduction
12============
13
14Linux is probably the Unix-like operating system that supports
15the widest variety of hardware devices. The reasons for this are
16presumably
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
24The openness of Linux, and the many different types of available
25hardware has allowed Linux to support many different hardware devices.
26Unfortunately, the very openness that has allowed Linux to support
27all these different devices has also allowed the behavior of each
28device driver to differ significantly from one device to another.
29This divergence of behavior has been very significant for CD-ROM
30devices; the way a particular drive reacts to a `standard` *ioctl()*
31call varies greatly from one device driver to another. To avoid making
32their drivers totally inconsistent, the writers of Linux CD-ROM
33drivers generally created new device drivers by understanding, copying,
34and then changing an existing one. Unfortunately, this practice did not
35maintain uniform behavior across all the Linux CD-ROM drivers.
36
37This document describes an effort to establish Uniform behavior across
38all the different CD-ROM device drivers for Linux. This document also
39defines the various *ioctl()'s*, and how the low-level CD-ROM device
40drivers should implement them. Currently (as of the Linux 2.1.\ *x*
41development kernels) several low-level CD-ROM device drivers, including
42both IDE/ATAPI and SCSI, now use this Uniform interface.
43
44When the CD-ROM was developed, the interface between the CD-ROM drive
45and the computer was not specified in the standards. As a result, many
46different CD-ROM interfaces were developed. Some of them had their
47own proprietary design (Sony, Mitsumi, Panasonic, Philips), other
48manufacturers adopted an existing electrical interface and changed
49the functionality (CreativeLabs/SoundBlaster, Teac, Funai) or simply
50adapted their drives to one or more of the already existing electrical
51interfaces (Aztech, Sanyo, Funai, Vertos, Longshine, Optics Storage and
52most of the `NoName` manufacturers). In cases where a new drive really
53brought its own interface or used its own command set and flow control
54scheme, either a separate driver had to be written, or an existing
55driver had to be enhanced. History has delivered us CD-ROM support for
56many of these different interfaces. Nowadays, almost all new CD-ROM
57drives are either IDE/ATAPI or SCSI, and it is very unlikely that any
58manufacturer will create a new interface. Even finding drives for the
59old proprietary interfaces is getting difficult.
60
61When (in the 1.3.70's) I looked at the existing software interface,
62which was expressed through `cdrom.h`, it appeared to be a rather wild
63set of commands and data formats [#f1]_. It seemed that many
64features of the software interface had been added to accommodate the
65capabilities of a particular drive, in an *ad hoc* manner. More
66importantly, it appeared that the behavior of the `standard` commands
67was different for most of the different drivers: e. g., some drivers
68close the tray if an *open()* call occurs when the tray is open, while
69others do not. Some drivers lock the door upon opening the device, to
70prevent an incoherent file system, but others don't, to allow software
71ejection. Undoubtedly, the capabilities of the different drives vary,
72but even when two drives have the same capability their drivers'
73behavior 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
80I decided to start a discussion on how to make all the Linux CD-ROM
81drivers behave more uniformly. I began by contacting the developers of
82the many CD-ROM drivers found in the Linux kernel. Their reactions
83encouraged me to write the Uniform CD-ROM Driver which this document is
84intended to describe. The implementation of the Uniform CD-ROM Driver is
85in the file `cdrom.c`. This driver is intended to be an additional software
86layer that sits on top of the low-level device drivers for each CD-ROM drive.
87By adding this additional layer, it is possible to have all the different
88CD-ROM devices behave **exactly** the same (insofar as the underlying
89hardware will allow).
90
91The goal of the Uniform CD-ROM Driver is **not** to alienate driver developers
92whohave not yet taken steps to support this effort. The goal of Uniform CD-ROM
93Driver is simply to give people writing application programs for CD-ROM drives
94**one** Linux CD-ROM interface with consistent behavior for all
95CD-ROM devices. In addition, this also provides a consistent interface
96between the low-level device driver code and the Linux kernel. Care
97is taken that 100% compatibility exists with the data structures and
98programmer's interface defined in `cdrom.h`. This guide was written to
99help CD-ROM driver developers adapt their code to use the Uniform CD-ROM
100Driver code defined in `cdrom.c`.
101
102Personally, I think that the most important hardware interfaces are
103the IDE/ATAPI drives and, of course, the SCSI drives, but as prices
104of hardware drop continuously, it is also likely that people may have
105more than one CD-ROM drive, possibly of mixed types. It is important
106that these drives behave in the same way. In December 1994, one of the
107cheapest CD-ROM drives was a Philips cm206, a double-speed proprietary
108drive. In the months that I was busy writing a Linux driver for it,
109proprietary drives became obsolete and IDE/ATAPI drives became the
110standard. At the time of the last update to this document (November
1111997) it is becoming difficult to even **find** anything less than a
11216 speed CD-ROM drive, and 24 speed drives are common.
113
114.. _cdrom_api:
115
116Standardizing through another software level
117============================================
118
119At the time this document was conceived, all drivers directly
120implemented the CD-ROM *ioctl()* calls through their own routines. This
121led to the danger of different drivers forgetting to do important things
122like checking that the user was giving the driver valid data. More
123importantly, this led to the divergence of behavior, which has already
124been discussed.
125
126For this reason, the Uniform CD-ROM Driver was created to enforce consistent
127CD-ROM drive behavior, and to provide a common set of services to the various
128low-level CD-ROM device drivers. The Uniform CD-ROM Driver now provides another
129software-level, that separates the *ioctl()* and *open()* implementation
130from the actual hardware implementation. Note that this effort has
131made few changes which will affect a user's application programs. The
132greatest change involved moving the contents of the various low-level
133CD-ROM drivers\' header files to the kernel's cdrom directory. This was
134done to help ensure that the user is only presented with only one cdrom
135interface, the interface defined in `cdrom.h`.
136
137CD-ROM drives are specific enough (i. e., different from other
138block-devices such as floppy or hard disc drives), to define a set
139of common **CD-ROM device operations**, *<cdrom-device>_dops*.
140These operations are different from the classical block-device file
141operations, *<block-device>_fops*.
142
143The routines for the Uniform CD-ROM Driver interface level are implemented
144in the file `cdrom.c`. In this file, the Uniform CD-ROM Driver interfaces
145with 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
164Every active CD-ROM device shares this *struct*. The routines
165declared above are all implemented in `cdrom.c`, since this file is the
166place where the behavior of all CD-ROM-devices is defined and
167standardized. The actual interface to the various types of CD-ROM
168hardware is still performed by various low-level CD-ROM-device
169drivers. These routines simply implement certain **capabilities**
170that are common to all CD-ROM (and really, all removable-media
171devices).
172
173Registration of a low-level CD-ROM device driver is now done through
174the general routines in `cdrom.c`, not through the Virtual File System
175(VFS) any more. The interface implemented in `cdrom.c` is carried out
176through two general structures that contain information about the
177capabilities of the driver, and the specific drives on which the
178driver operates. The structures are:
179
180cdrom_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
186cdrom_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
191Registering a particular CD-ROM drive with the Uniform CD-ROM Driver
192is done by the low-level device driver though a call to::
193
194	register_cdrom(struct cdrom_device_info * <device>_info)
195
196The device information structure, *<device>_info*, contains all the
197information needed for the kernel to interface with the low-level
198CD-ROM device driver. One of the most important entries in this
199structure is a pointer to the *cdrom_device_ops* structure of the
200low-level driver.
201
202The device operations structure, *cdrom_device_ops*, contains a list
203of pointers to the functions which are implemented in the low-level
204device driver. When `cdrom.c` accesses a CD-ROM device, it does it
205through the functions in this structure. It is impossible to know all
206the capabilities of future CD-ROM drives, so it is expected that this
207list may need to be expanded from time to time as new technologies are
208developed. For example, CD-R and CD-R/W drives are beginning to become
209popular, and support will soon need to be added for them. For now, the
210current *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
234When a low-level device driver implements one of these capabilities,
235it should add a function pointer to this *struct*. When a particular
236function is not implemented, however, this *struct* should contain a
237NULL instead. The *capability* flags specify the capabilities of the
238CD-ROM hardware and/or low-level CD-ROM driver when a CD-ROM drive
239is registered with the Uniform CD-ROM Driver.
240
241Note that most functions have fewer parameters than their
242*blkdev_fops* counterparts. This is because very little of the
243information in the structures *inode* and *file* is used. For most
244drivers, the main parameter is the *struct* *cdrom_device_info*, from
245which the major and minor number can be extracted. (Most low-level
246CD-ROM drivers don't even look at the major and minor number though,
247since many of them only support one device.) This will be available
248through *dev* in *cdrom_device_info* described below.
249
250The 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
282Using this *struct*, a linked list of the registered minor devices is
283built, using the *next* field. The device number, the device operations
284struct and specifications of properties of the drive are stored in this
285structure.
286
287The *mask* flags can be used to mask out some of the capabilities listed
288in *ops->capability*, if a specific drive doesn't support a feature
289of the driver. The value *speed* specifies the maximum head-rate of the
290drive, measured in units of normal audio speed (176kB/sec raw data or
291150kB/sec file system data). The parameters are declared *const*
292because they describe properties of the drive, which don't change after
293registration.
294
295A few registers contain variables local to the CD-ROM drive. The
296flags *options* are used to specify how the general CD-ROM routines
297should behave. These various flags registers should provide enough
298flexibility to adapt to the different users' wishes (and **not** the
299`arbitrary` wishes of the author of the low-level device driver, as is
300the case in the old scheme). The register *mc_flags* is used to buffer
301the information from *media_changed()* to two separate queues. Other
302data that is specific to a minor drive, can be accessed through *handle*,
303which can point to a data structure specific to the low-level driver.
304The fields *use_count*, *next*, *options* and *mc_flags* need not be
305initialized.
306
307The intermediate software layer that `cdrom.c` forms will perform some
308additional bookkeeping. The use count of the device (the number of
309processes that have the device opened) is registered in *use_count*. The
310function *cdrom_ioctl()* will verify the appropriate user-memory regions
311for read and write, and in case a location on the CD is transferred,
312it will `sanitize` the format by making requests to the low-level
313drivers in a standard format, and translating all formats between the
314user-software and low level drivers. This relieves much of the drivers'
315memory checking and format checking and translation. Also, the necessary
316structures will be declared on the program stack.
317
318The implementation of the functions should be as defined in the
319following sections. Two functions **must** be implemented, namely
320*open()* and *release()*. Other functions may be omitted, their
321corresponding capability flags will be cleared upon registration.
322Generally, a function returns zero on success and negative on error. A
323function call should return only after the command has completed, but of
324course 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
331can 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
337Notice that any strategic code (closing tray upon *open()*, etc.) is
338done by the calling routine in `cdrom.c`, so the low-level routine
339should only be concerned with proper initialization, such as spinning
340up the disc, etc.
341
342::
343
344	void release(struct cdrom_device_info *cdi)
345
346Device-specific actions should be taken such as spinning down the device.
347However, strategic actions such as ejection of the tray, or unlocking
348the door, should be left over to the general routine *cdrom_release()*.
349This 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
357The function *drive_status*, if implemented, should provide
358information on the status of the drive (not the status of the disc,
359which 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
373This function is very similar to the original function in $struct
374file_operations*. It returns 1 if the medium of the device *cdi->dev*
375has changed since the last call, and 0 otherwise. The parameter
376*disc_nr* identifies a specific slot in a juke-box, it should be
377ignored for single-disc drives. Note that by `re-routing` this
378function through *cdrom_media_changed()*, we can implement separate
379queues for the VFS and a new *ioctl()* function that can report device
380changes to software (e. g., an auto-mounting daemon).
381
382::
383
384	int tray_move(struct cdrom_device_info *cdi, int position)
385
386This function, if implemented, should control the tray movement. (No
387other function should control this.) The parameter *position* controls
388the desired direction of movement:
389
390- 0 Close tray
391- 1 Open tray
392
393This function returns 0 upon success, and a non-zero value upon
394error. Note that if the tray is already in the desired position, no
395action 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
401This function (and no other code) controls locking of the door, if the
402drive allows this. The value of *lock* controls the desired locking
403state:
404
405- 0 Unlock door, manual opening is allowed
406- 1 Lock door, tray cannot be ejected manually
407
408This function returns 0 upon success, and a non-zero value upon
409error. Note that if the door is already in the requested state, no
410action 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
416Some CD-ROM drives are capable of changing their head-speed. There
417are several reasons for changing the speed of a CD-ROM drive. Badly
418pressed CD-ROM s may benefit from less-than-maximum head rate. Modern
419CD-ROM drives can obtain very high head rates (up to *24x* is
420common). It has been reported that these drives can make reading
421errors at these high speeds, reducing the speed can prevent data loss
422in these circumstances. Finally, some of these drives can
423make an annoyingly loud noise, which a lower speed may reduce.
424
425This function specifies the speed at which data is read or audio is
426played back. The value of *speed* specifies the head-speed of the
427drive, measured in units of standard cdrom speed (176kB/sec raw data
428or 150kB/sec file system data). So to request that a CD-ROM drive
429operate at 300kB/sec you would call the CDROM_SELECT_SPEED *ioctl*
430with *speed=2*. The special value `0` means `auto-selection`, i. e.,
431maximum data-rate or real-time audio rate. If the drive doesn't have
432this `auto-selection` capability, the decision should be made on the
433current disc loaded and the return value should be positive. A negative
434return value indicates an error.
435
436::
437
438	int select_disc(struct cdrom_device_info *cdi, int number)
439
440If the drive can store multiple discs (a juke-box) this function
441will perform disc selection. It should return the number of the
442selected disc on success, a negative value on error. Currently, only
443the 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
450This function should implement the old corresponding *ioctl()*. For
451device *cdi->dev*, the start of the last session of the current disc
452should be returned in the pointer argument *ms_info*. Note that
453routines in `cdrom.c` have sanitized this argument: its requested
454format will **always** be of the type *CDROM_LBA* (linear block
455addressing mode), whatever the calling software requested. But
456sanitization goes even further: the low-level implementation may
457return the requested information in *CDROM_MSF* format if it wishes so
458(setting the *ms_info->addr_format* field appropriately, of
459course) and the routines in `cdrom.c` will make the transformation if
460necessary. 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
467Some discs carry a `Media Catalog Number` (MCN), also called
468`Universal Product Code` (UPC). This number should reflect the number
469that is generally found in the bar-code on the product. Unfortunately,
470the few discs that carry such a number on the disc don't even use the
471same format. The return argument to this function is a pointer to a
472pre-declared memory region of type *struct cdrom_mcn*. The MCN is
473expected as a 13-character string, terminated by a null-character.
474
475::
476
477	int reset(struct cdrom_device_info *cdi)
478
479This call should perform a hard-reset on the drive (although in
480circumstances that a hard-reset is necessary, a drive may very well not
481listen to commands anymore). Preferably, control is returned to the
482caller only after the drive has finished resetting. If the drive is no
483longer listening, it may be wise for the underlying low-level cdrom
484driver to time out.
485
486::
487
488	int audio_ioctl(struct cdrom_device_info *cdi,
489			unsigned int cmd, void *arg)
490
491Some of the CD-ROM-\ *ioctl()*\ 's defined in `cdrom.h` can be
492implemented by the routines described above, and hence the function
493*cdrom_ioctl* will use those. However, most *ioctl()*\ 's deal with
494audio-control. We have decided to leave these to be accessed through a
495single function, repeating the arguments *cmd* and *arg*. Note that
496the latter is of type *void*, rather than *unsigned long int*.
497The routine *cdrom_ioctl()* does do some useful things,
498though. It sanitizes the address format type to *CDROM_MSF* (Minutes,
499Seconds, Frames) for all audio calls. It also verifies the memory
500location of *arg*, and reserves stack-memory for the argument. This
501makes implementation of the *audio_ioctl()* much simpler than in the
502old driver scheme. For example, you may look up the function
503*cm206_audio_ioctl()* `cm206.c` that should be updated with
504this documentation.
505
506An unimplemented ioctl should return *-ENOSYS*, but a harmless request
507(e. g., *CDROMSTART*) may be ignored by returning 0 (success). Other
508errors should be according to the standards, whatever they are. When
509an error is returned by the low-level driver, the Uniform CD-ROM Driver
510tries 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
512order 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
519Some *ioctl()'s* seem to be specific to certain CD-ROM drives. That is,
520they are introduced to service some capabilities of certain drives. In
521fact, there are 6 different *ioctl()'s* for reading data, either in some
522particular kind of format, or audio data. Not many drives support
523reading audio tracks as data, I believe this is because of protection
524of copyrights of artists. Moreover, I think that if audio-tracks are
525supported, it should be done through the VFS and not via *ioctl()'s*. A
526problem here could be the fact that audio-frames are 2352 bytes long,
527so 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
529bend their backs to cope with this incoherence (to which I would be
530opposed). Furthermore, it is very difficult for the hardware to find
531the exact frame boundaries, since there are no synchronization headers
532in audio frames. Once these issues are resolved, this code should be
533standardized in `cdrom.c`.
534
535Because there are so many *ioctl()'s* that seem to be introduced to
536satisfy certain drivers [#f2]_, any non-standard *ioctl()*\ s
537are routed through the call *dev_ioctl()*. In principle, `private`
538*ioctl()*\ 's should be numbered after the device's major number, and not
539the general CD-ROM *ioctl* number, `0x53`. Currently the
540non-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
551CD-ROM capabilities
552-------------------
553
554Instead of just implementing some *ioctl* calls, the interface in
555`cdrom.c` supplies the possibility to indicate the **capabilities**
556of a CD-ROM drive. This can be done by ORing any number of
557capability-constants that are defined in `cdrom.h` at the registration
558phase. 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
573The capability flag is declared *const*, to prevent drivers from
574accidentally tampering with the contents. The capability fags actually
575inform `cdrom.c` of what the driver can do. If the drive found
576by the driver does not have the capability, is can be masked out by
577the *cdrom_device_info* variable *mask*. For instance, the SCSI CD-ROM
578driver has implemented the code for loading and ejecting CD-ROM's, and
579hence its corresponding flags in *capability* will be set. But a SCSI
580CD-ROM drive might be a caddy system, which can't load the tray, and
581hence for this drive the *cdrom_device_info* struct will have set
582the *CDC_CLOSE_TRAY* bit in *mask*.
583
584In the file `cdrom.c` you will encounter many constructions of the type::
585
586	if (cdo->capability & ∼cdi->mask & CDC _⟨capability⟩) ...
587
588There is no *ioctl* to set the mask... The reason is that
589I think it is better to control the **behavior** rather than the
590**capabilities**.
591
592Options
593-------
594
595A final flag register controls the **behavior** of the CD-ROM
596drives, in order to satisfy different users' wishes, hopefully
597independently of the ideas of the respective author who happened to
598have made the drive's support available to the Linux community. The
599current 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
607The initial value of this register is
608`CDO_AUTO_CLOSE | CDO_USE_FFLAGS | CDO_LOCK`, reflecting my own view on user
609interface and software standards. Before you protest, there are two
610new *ioctl()'s* implemented in `cdrom.c`, that allow you to control the
611behavior 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
616One option needs some more explanation: *CDO_USE_FFLAGS*. In the next
617newsection we explain what the need for this option is.
618
619A software package `setcd`, available from the Debian distribution
620and `sunsite.unc.edu`, allows user level control of these flags.
621
622
623The need to know the purpose of opening the CD-ROM device
624=========================================================
625
626Traditionally, Unix devices can be used in two different `modes`,
627either by reading/writing to the device file, or by issuing
628controlling commands to the device, by the device's *ioctl()*
629call. The problem with CD-ROM drives, is that they can be used for
630two entirely different purposes. One is to mount removable
631file systems, CD-ROM's, the other is to play audio CD's. Audio commands
632are implemented entirely through *ioctl()\'s*, presumably because the
633first implementation (SUN?) has been such. In principle there is
634nothing wrong with this, but a good control of the `CD player` demands
635that the device can **always** be opened in order to give the
636*ioctl* commands, regardless of the state the drive is in.
637
638On the other hand, when used as a removable-media disc drive (what the
639original purpose of CD-ROM s is) we would like to make sure that the
640disc drive is ready for operation upon opening the device. In the old
641scheme, some CD-ROM drivers don't do any integrity checking, resulting
642in a number of i/o errors reported by the VFS to the kernel when an
643attempt for mounting a CD-ROM on an empty drive occurs. This is not a
644particularly elegant way to find out that there is no CD-ROM inserted;
645it more-or-less looks like the old IBM-PC trying to read an empty floppy
646drive for a couple of seconds, after which the system complains it
647can't read from it. Nowadays we can **sense** the existence of a
648removable medium in a drive, and we believe we should exploit that
649fact. An integrity check on opening of the device, that verifies the
650availability of a CD-ROM and its correct type (data), would be
651desirable.
652
653These two ways of using a CD-ROM drive, principally for data and
654secondarily for playing audio discs, have different demands for the
655behavior of the *open()* call. Audio use simply wants to open the
656device in order to get a file handle which is needed for issuing
657*ioctl* commands, while data use wants to open for correct and
658reliable data transfer. The only way user programs can indicate what
659their *purpose* of opening the device is, is through the *flags*
660parameter (see `open(2)`). For CD-ROM devices, these flags aren't
661implemented (some drivers implement checking for write-related flags,
662but this is not strictly necessary if the device file has correct
663permission flags). Most option flags simply don't make sense to
664CD-ROM devices: *O_CREAT*, *O_NOCTTY*, *O_TRUNC*, *O_APPEND*, and
665*O_SYNC* have no meaning to a CD-ROM.
666
667We therefore propose to use the flag *O_NONBLOCK* to indicate
668that the device is opened just for issuing *ioctl*
669commands. Strictly, the meaning of *O_NONBLOCK* is that opening and
670subsequent calls to the device don't cause the calling process to
671wait. We could interpret this as don't wait until someone has
672inserted some valid data-CD-ROM. Thus, our proposal of the
673implementation 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
683And what about standards?
684-------------------------
685
686You might hesitate to accept this proposal as it comes from the
687Linux community, and not from some standardizing institute. What
688about SUN, SGI, HP and all those other Unix and hardware vendors?
689Well, these companies are in the lucky position that they generally
690control both the hardware and software of their supported products,
691and are large enough to set their own standard. They do not have to
692deal with a dozen or more different, competing hardware
693configurations\ [#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
710We believe that using *O_NONBLOCK* to indicate that a device is being opened
711for *ioctl* commands only can be easily introduced in the Linux
712community. All the CD-player authors will have to be informed, we can
713even send in our own patches to the programs. The use of *O_NONBLOCK*
714has most likely no influence on the behavior of the CD-players on
715other operating systems than Linux. Finally, a user can always revert
716to old behavior by a call to
717*ioctl(file_descriptor, CDROM_CLEAR_OPTIONS, CDO_USE_FFLAGS)*.
718
719The preferred strategy of *open()*
720----------------------------------
721
722The routines in `cdrom.c` are designed in such a way that run-time
723configuration of the behavior of CD-ROM devices (of **any** type)
724can be carried out, by the *CDROM_SET/CLEAR_OPTIONS* *ioctls*. Thus, various
725modes 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
744We hope that these option can convince everybody (both driver
745maintainers and user program developers) to adopt the new CD-ROM
746driver scheme and option flag interpretation.
747
748Description of routines in `cdrom.c`
749====================================
750
751Only a few routines in `cdrom.c` are exported to the drivers. In this
752new section we will discuss these, as well as the functions that `take
753over' the CD-ROM interface to the kernel. The header file belonging
754to `cdrom.c` is called `cdrom.h`. Formerly, some of the contents of this
755file were placed in the file `ucdrom.h`, but this file has now been
756merged back into `cdrom.h`.
757
758::
759
760	struct file_operations cdrom_fops
761
762The contents of this structure were described in cdrom_api_.
763A pointer to this structure is assigned to the *fops* field
764of the *struct gendisk*.
765
766::
767
768	int register_cdrom(struct cdrom_device_info *cdi)
769
770This function is used in about the same way one registers *cdrom_fops*
771with the kernel, the device operations and information structures,
772as described in cdrom_api_, should be registered with the
773Uniform CD-ROM Driver::
774
775	register_cdrom(&<device>_info);
776
777
778This function returns zero upon success, and non-zero upon
779failure. The structure *<device>_info* should have a pointer to the
780driver's *<device>_dops*, as in::
781
782	struct cdrom_device_info <device>_info = {
783		<device>_dops;
784		...
785	}
786
787Note that a driver must have one static structure, *<device>_dops*, while
788it may have as many structures *<device>_info* as there are minor devices
789active. *Register_cdrom()* builds a linked list from these.
790
791
792::
793
794	void unregister_cdrom(struct cdrom_device_info *cdi)
795
796Unregistering device *cdi* with minor number *MINOR(cdi->dev)* removes
797the minor device from the list. If it was the last registered minor for
798the low-level driver, this disconnects the registered device-operation
799routines from the CD-ROM interface. This function returns zero upon
800success, and non-zero upon failure.
801
802::
803
804	int cdrom_open(struct inode * ip, struct file * fp)
805
806This function is not called directly by the low-level drivers, it is
807listed in the standard *cdrom_fops*. If the VFS opens a file, this
808function becomes active. A strategy is implemented in this routine,
809taking care of all capabilities and options that are set in the
810*cdrom_device_ops* connected to the device. Then, the program flow is
811transferred to the device_dependent *open()* call.
812
813::
814
815	void cdrom_release(struct inode *ip, struct file *fp)
816
817This function implements the reverse-logic of *cdrom_open()*, and then
818calls the device-dependent *release()* routine. When the use-count has
819reached 0, the allocated buffers are flushed by calls to *sync_dev(dev)*
820and *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
830This function handles all the standard *ioctl* requests for CD-ROM
831devices in a uniform way. The different calls fall into three
832categories: *ioctl()'s* that can be directly implemented by device
833operations, ones that are routed through the call *audio_ioctl()*, and
834the remaining ones, that are presumable device-dependent. Generally, a
835negative return value indicates an error.
836
837Directly implemented *ioctl()'s*
838--------------------------------
839
840The following `old` CD-ROM *ioctl()*\ 's are implemented by directly
841calling device-operations in *cdrom_device_ops*, if implemented and
842not 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
860The following set of *ioctl()'s* are all implemented through a call to
861the *cdrom_fops* function *audio_ioctl()*. Memory checks and
862allocation are performed in *cdrom_ioctl()*, and also sanitization of
863address 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
893New *ioctl()'s* in `cdrom.c`
894----------------------------
895
896The following *ioctl()'s* have been introduced to allow user programs to
897control the behavior of individual CD-ROM devices. New *ioctl*
898commands 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
990Device dependent *ioctl()'s*
991----------------------------
992
993Finally, all other *ioctl()'s* are passed to the function *dev_ioctl()*,
994if implemented. No memory allocation or verification is carried out.
995
996How 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
1050Thanks
1051======
1052
1053Thanks to all the people involved. First, Erik Andersen, who has
1054taken over the torch in maintaining `cdrom.c` and integrating much
1055CD-ROM-related code in the 2.1-kernel. Thanks to Scott Snyder and
1056Gerd Knorr, who were the first to implement this interface for SCSI
1057and IDE-CD drivers and added many ideas for extension of the data
1058structures relative to kernel~2.0. Further thanks to Heiko Eißfeldt,
1059Thomas Quinot, Jon Tombs, Ken Pizzini, Eberhard Mönkeberg and Andrew Kroll,
1060the Linux CD-ROM device driver developers who were kind
1061enough to give suggestions and criticisms during the writing. Finally
1062of course, I want to thank Linus Torvalds for making this possible in
1063the first place.
1064