Documentation/cdrom/cdrom-standard.rst

2 A Linux CD-ROM standard
14 Linux is probably the Unix-like operating system that supports
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
22 - There is plenty of source code around as examples of how to write a driver.
29 This divergence of behavior has been very significant for CD-ROM
32 their drivers totally inconsistent, the writers of Linux CD-ROM
35 maintain uniform behavior across all the Linux CD-ROM drivers.
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
41 development kernels) several low-level CD-ROM device drivers, including
44 When the CD-ROM was developed, the interface between the CD-ROM drive
46 different CD-ROM interfaces were developed. Some of them had their
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
58 manufacturer will create a new interface. Even finding drives for the
72 but even when two drives have the same capability their drivers'
77    presumably 1.2.13 and 1.3.34 --- the latest kernel that I was
80 I decided to start a discussion on how to make all the Linux CD-ROM
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
86 layer that sits on top of the low-level device drivers for each CD-ROM drive.
88 CD-ROM devices behave **exactly** the same (insofar as the underlying
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
99 help CD-ROM driver developers adapt their code to use the Uniform CD-ROM
105 more than one CD-ROM drive, possibly of mixed types. It is important
107 cheapest CD-ROM drives was a Philips cm206, a double-speed proprietary
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.
120 implemented the CD-ROM *ioctl()* calls through their own routines. This
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
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
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*.
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
150 		block _read ,		/* read--general block-dev read */
151 		block _write,		/* write--general block-dev write */
163 Every active CD-ROM device shares this *struct*. The routines
165 place where the behavior of all CD-ROM-devices is defined and
166 standardized. The actual interface to the various types of CD-ROM
167 hardware is still performed by various low-level CD-ROM-device
169 that are common to all CD-ROM (and really, all removable-media
172 Registration of a low-level CD-ROM device driver is now done through
180   This structure contains information about the low-level driver for a
181   CD-ROM device. This structure is conceptually connected to the major
186   This structure contains information about a particular CD-ROM drive,
190 Registering a particular CD-ROM drive with the Uniform CD-ROM Driver
191 is done by the low-level device driver though a call to::
196 information needed for the kernel to interface with the low-level
197 CD-ROM device driver. One of the most important entries in this
199 low-level driver.
202 of pointers to the functions which are implemented in the low-level
203 device driver. When `cdrom.c` accesses a CD-ROM device, it does it
205 the capabilities of future CD-ROM drives, so it is expected that this
207 developed. For example, CD-R and CD-R/W drives are beginning to become
232 When a low-level device driver implements one of these capabilities,
236 CD-ROM hardware and/or low-level CD-ROM driver when a CD-ROM drive
237 is registered with the Uniform CD-ROM Driver.
243 which the major and minor number can be extracted. (Most low-level
244 CD-ROM drivers don't even look at the major and minor number though,
248 The drive-specific, minor-like information that is registered with
255 	void *  handle;				/* driver-dependent data */
262 	unsigned mc_flags:2;			/*  media-change buffer flags */
268 	__u8 sanyo_slot : 2;			/*  Sanyo 3-CD changer support */
286 in *ops->capability*, if a specific drive doesn't support a feature
287 of the driver. The value *speed* specifies the maximum head-rate of the
293 A few registers contain variables local to the CD-ROM drive. The
294 flags *options* are used to specify how the general CD-ROM routines
297 `arbitrary` wishes of the author of the low-level device driver, as is
301 which can point to a data structure specific to the low-level driver.
308 function *cdrom_ioctl()* will verify the appropriate user-memory regions
310 it will `sanitize` the format by making requests to the low-level
312 user-software and low level drivers. This relieves much of the drivers'
331 - Open for reading data, as done by `mount()` (2), or the
333 - Open for *ioctl* commands, as done by audio-CD playing programs.
336 done by the calling routine in `cdrom.c`, so the low-level routine
344 Device-specific actions should be taken such as spinning down the device.
375 - 0 Close tray
376 - 1 Open tray
378 This function returns 0 upon success, and a non-zero value upon
390 - 0 Unlock door, manual opening is allowed
391 - 1 Lock door, tray cannot be ejected manually
393 This function returns 0 upon success, and a non-zero value upon
401 Some CD-ROM drives are capable of changing their head-speed. There
402 are several reasons for changing the speed of a CD-ROM drive. Badly
403 pressed CD-ROM s may benefit from less-than-maximum head rate. Modern
404 CD-ROM drives can obtain very high head rates (up to *24x* is
411 played back. The value of *speed* specifies the head-speed of the
413 or 150kB/sec file system data). So to request that a CD-ROM drive
415 with *speed=2*. The special value `0` means `auto-selection`, i. e.,
416 maximum data-rate or real-time audio rate. If the drive doesn't have
417 this `auto-selection` capability, the decision should be made on the
427 device *cdi->dev*, the start of the last session of the current disc
432 sanitization goes even further: the low-level implementation may
434 (setting the *ms_info->addr_format* field appropriately, of
445 that is generally found in the bar-code on the product. Unfortunately,
446 the few discs that carry such a number on the disc don't even use the
448 pre-declared memory region of type *struct cdrom_mcn*. The MCN is
449 expected as a 13-character string, terminated by a null-character.
455 This call should perform a hard-reset on the drive (although in
456 circumstances that a hard-reset is necessary, a drive may very well not
459 longer listening, it may be wise for the underlying low-level cdrom
467 Some of the CD-ROM-\ *ioctl()*\ 's defined in `cdrom.h` can be
470 audio-control. We have decided to leave these to be accessed through a
476 location of *arg*, and reserves stack-memory for the argument. This
482 An unimplemented ioctl should return *-ENOSYS*, but a harmless request
485 an error is returned by the low-level driver, the Uniform CD-ROM Driver
488 order to guarantee a uniform interface to the audio-player software.)
495 Some *ioctl()'s* seem to be specific to certain CD-ROM drives. That is,
500 of copyrights of artists. Moreover, I think that if audio-tracks are
502 problem here could be the fact that audio-frames are 2352 bytes long,
503 so either the audio-file-system should ask for 75264 bytes at once
512 satisfy certain drivers [#f2]_, any non-standard *ioctl()*\ s
514 *ioctl()*\ 's should be numbered after the device's major number, and not
515 the general CD-ROM *ioctl* number, `0x53`. Currently the
516 non-supported *ioctl()'s* are:
519 	CDROMREADCOOKED, CDROMSEEK, CDROMPLAY-BLK and CDROM-READALL
527 CD-ROM capabilities
528 -------------------
532 of a CD-ROM drive. This can be done by ORing any number of
533 capability-constants that are defined in `cdrom.h` at the registration
540 	CDC_SELECT_DISC		/* drive is juke-box */
544 	CDC_PLAY_AUDIO		/* can perform audio-functions (play, pause, etc) */
546 	CDC_IOCTLS		/* driver has non-standard ioctls */
553 the *cdrom_device_info* variable *mask*. For instance, the SCSI CD-ROM
554 driver has implemented the code for loading and ejecting CD-ROM's, and
556 CD-ROM drive might be a caddy system, which can't load the tray, and
562 	if (cdo->capability & ~cdi->mask & CDC _<capability>) ...
569 -------
571 A final flag register controls the **behavior** of the CD-ROM
579 	CDO_USE_FFLAGS	/* use file_pointer->f_flags to indicate purpose for open() */
599 The need to know the purpose of opening the CD-ROM device
605 call. The problem with CD-ROM drives, is that they can be used for
607 file systems, CD-ROM's, the other is to play audio CD's. Audio commands
614 On the other hand, when used as a removable-media disc drive (what the
615 original purpose of CD-ROM s is) we would like to make sure that the
617 scheme, some CD-ROM drivers don't do any integrity checking, resulting
619 attempt for mounting a CD-ROM on an empty drive occurs. This is not a
620 particularly elegant way to find out that there is no CD-ROM inserted;
621 it more-or-less looks like the old IBM-PC trying to read an empty floppy
626 availability of a CD-ROM and its correct type (data), would be
629 These two ways of using a CD-ROM drive, principally for data and
636 parameter (see `open(2)`). For CD-ROM devices, these flags aren't
637 implemented (some drivers implement checking for write-related flags,
640 CD-ROM devices: *O_CREAT*, *O_NOCTTY*, *O_TRUNC*, *O_APPEND*, and
641 *O_SYNC* have no meaning to a CD-ROM.
648 inserted some valid data-CD-ROM. Thus, our proposal of the
649 implementation for the *open()* call for CD-ROM s is:
651 - If no other flags are set than *O_RDONLY*, the device is opened
653   initialization of the transfer. The call may even induce some actions
654   on the CD-ROM, such as closing the tray.
655 - If the option flag *O_NONBLOCK* is set, opening will always be
660 -------------------------
673    Incidentally, I think that SUN's approach to mounting CD-ROM s is very
674    good in origin: under Solaris a volume-daemon automatically mounts a
675    newly inserted CD-ROM under `/cdrom/*<volume-name>*`.
678    further and have **every** CD-ROM on the local area network be
680    machine you insert a CD-ROM, it will always appear at the same
682    implement such a user-program for Linux, I came across the
688 community. All the CD-player authors will have to be informed, we can
689 even send in our own patches to the programs. The use of *O_NONBLOCK*
690 has most likely no influence on the behavior of the CD-players on
696 ----------------------------------
698 The routines in `cdrom.c` are designed in such a way that run-time
699 configuration of the behavior of CD-ROM devices (of **any** type)
715    This mimics the behavior of the current sbpcd-driver. The option flags are
717    the tray is opened on the last release, i. e., if a CD-ROM is unmounted,
721 maintainers and user program developers) to adopt the new CD-ROM
729 over` the CD-ROM interface to the kernel. The header file belonging
749 Uniform CD-ROM Driver::
754 This function returns zero upon success, and non-zero upon
772 Unregistering device *cdi* with minor number *MINOR(cdi->dev)* removes
774 the low-level driver, this disconnects the registered device-operation
775 routines from the CD-ROM interface. This function returns zero upon
776 success, and non-zero upon failure.
782 This function is not called directly by the low-level drivers, it is
793 This function implements the reverse-logic of *cdrom_open()*, and then
794 calls the device-dependent *release()* routine. When the use-count has
806 This function handles all the standard *ioctl* requests for CD-ROM
810 the remaining ones, that are presumable device-dependent. Generally, a
814 --------------------------------
816 The following `old` CD-ROM *ioctl()*\ 's are implemented by directly
817 calling device-operations in *cdrom_device_ops*, if implemented and
821 	Requests the last session on a CD-ROM.
827 	If *arg\not=0*, set behavior to auto-close (close
828 	tray on first open) and auto-eject (eject on last release), otherwise
829 	set behavior to non-moving on *open()* and *release()* calls.
834 ---------------------------------------
842 	Get sub-channel data in argument *arg* of type
854 	Play audio fragment in track-index format delimited by *arg*
870 ----------------------------
873 control the behavior of individual CD-ROM devices. New *ioctl*
883 	Select head-rate speed of disc specified as by *arg* in units
885 	150kB/sec file system data). The value 0 means `auto-select`,
890 	Select disc numbered *arg* from a juke-box.
892 	First disc is numbered 0. The number *arg* is checked against the
893 	maximum number of discs in the juke-box found in the *cdrom_dops*.
896 	For juke-boxes, an extra argument *arg*
905 	*arg->last_media_change* may be set by calling code to signal
908 	*arg->last_media_change* to the latest media change timestamp (in ms)
909 	known by the kernel/driver and set *arg->has_changed* to 1 if
916 	an *ioctl* call to *CDROMSUBCHNL*. For juke-boxes, an extra argument
926 	entirely in Uniform CD-ROM Driver.
936 	function, the Uniform CD-ROM Driver implements this *ioctl* as
938 	absolutely no CD-I, XA, or data tracks on it, it will be reported
941 	if the CD in question has any CD-I tracks on it, it will be
961 	Returns the number of slots in a juke-box.
976 ----------------------------
984 - Make a backup of your current driver.
985 - Get hold of the files `cdrom.c` and `cdrom.h`, they should be in
987 - Make sure you include `cdrom.h`.
988 - Change the 3rd argument of *register_blkdev* from `&<your-drive>_fops`
990 - Just after that line, add the following to register with the Uniform
991   CD-ROM Driver::
993 	register_cdrom(&<your-drive>_info);*
996 - Copy an example of the device-operations *struct* to your
1003 - Copy the *cdrom_device_info* declaration from the same example
1007 - Implement all functions in your `<device>_dops` structure,
1012 - Rename your `<device>_ioctl()` function to *audio_ioctl* and
1016 - You may remove all remaining memory checking code in the
1025 - All remaining *ioctl* cases must be moved to a separate
1026   function, *<device>_ioctl*, the device-dependent *ioctl()'s*. Note that
1028 - Change the prototypes of *<device>_open()* and
1031 - Try to recompile the drivers. We advise you to use modules, both
1040 CD-ROM-related code in the 2.1-kernel. Thanks to Scott Snyder and
1042 and IDE-CD drivers and added many ideas for extension of the data
1045 the Linux CD-ROM device driver developers who were kind