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
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
112 16 speed CD-ROM drive, and 24 speed drives are common.
116 Standardizing through another software level
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
233 When a low-level device driver implements one of these capabilities,
237 CD-ROM hardware and/or low-level CD-ROM driver when a CD-ROM drive
238 is registered with the Uniform CD-ROM Driver.
244 which the major and minor number can be extracted. (Most low-level
245 CD-ROM drivers don't even look at the major and minor number though,
249 The drive-specific, minor-like information that is registered with
256 	void *  handle;				/* driver-dependent data */
263 	unsigned mc_flags:2;			/*  media-change buffer flags */
269 	__u8 sanyo_slot : 2;			/*  Sanyo 3-CD changer support */
287 in *ops->capability*, if a specific drive doesn't support a feature
288 of the driver. The value *speed* specifies the maximum head-rate of the
294 A few registers contain variables local to the CD-ROM drive. The
295 flags *options* are used to specify how the general CD-ROM routines
298 `arbitrary` wishes of the author of the low-level device driver, as is
302 which can point to a data structure specific to the low-level driver.
309 function *cdrom_ioctl()* will verify the appropriate user-memory regions
311 it will `sanitize` the format by making requests to the low-level
313 user-software and low level drivers. This relieves much of the drivers'
332 - Open for reading data, as done by `mount()` (2), or the
334 - Open for *ioctl* commands, as done by audio-CD playing programs.
337 done by the calling routine in `cdrom.c`, so the low-level routine
345 Device-specific actions should be taken such as spinning down the device.
376 - 0 Close tray
377 - 1 Open tray
379 This function returns 0 upon success, and a non-zero value upon
391 - 0 Unlock door, manual opening is allowed
392 - 1 Lock door, tray cannot be ejected manually
394 This function returns 0 upon success, and a non-zero value upon
402 Some CD-ROM drives are capable of changing their head-speed. There
403 are several reasons for changing the speed of a CD-ROM drive. Badly
404 pressed CD-ROM s may benefit from less-than-maximum head rate. Modern
405 CD-ROM drives can obtain very high head rates (up to *24x* is
412 played back. The value of *speed* specifies the head-speed of the
414 or 150kB/sec file system data). So to request that a CD-ROM drive
416 with *speed=2*. The special value `0` means `auto-selection`, i. e.,
417 maximum data-rate or real-time audio rate. If the drive doesn't have
418 this `auto-selection` capability, the decision should be made on the
426 If the drive can store multiple discs (a juke-box) this function
429 the ide-cd driver supports this functionality.
437 device *cdi->dev*, the start of the last session of the current disc
442 sanitization goes even further: the low-level implementation may
444 (setting the *ms_info->addr_format* field appropriately, of
455 that is generally found in the bar-code on the product. Unfortunately,
458 pre-declared memory region of type *struct cdrom_mcn*. The MCN is
459 expected as a 13-character string, terminated by a null-character.
465 This call should perform a hard-reset on the drive (although in
466 circumstances that a hard-reset is necessary, a drive may very well not
469 longer listening, it may be wise for the underlying low-level cdrom
477 Some of the CD-ROM-\ *ioctl()*\ 's defined in `cdrom.h` can be
480 audio-control. We have decided to leave these to be accessed through a
486 location of *arg*, and reserves stack-memory for the argument. This
492 An unimplemented ioctl should return *-ENOSYS*, but a harmless request
495 an error is returned by the low-level driver, the Uniform CD-ROM Driver
498 order to guarantee a uniform interface to the audio-player software.)
505 Some *ioctl()'s* seem to be specific to certain CD-ROM drives. That is,
510 of copyrights of artists. Moreover, I think that if audio-tracks are
512 problem here could be the fact that audio-frames are 2352 bytes long,
513 so either the audio-file-system should ask for 75264 bytes at once
522 satisfy certain drivers [#f2]_, any non-standard *ioctl()*\ s
525 the general CD-ROM *ioctl* number, `0x53`. Currently the
526 non-supported *ioctl()'s* are:
529 	CDROMREADCOOKED, CDROMSEEK, CDROMPLAY-BLK and CDROM-READALL
537 CD-ROM capabilities
538 -------------------
542 of a CD-ROM drive. This can be done by ORing any number of
543 capability-constants that are defined in `cdrom.h` at the registration
550 	CDC_SELECT_DISC		/* drive is juke-box */
554 	CDC_PLAY_AUDIO		/* can perform audio-functions (play, pause, etc) */
556 	CDC_IOCTLS		/* driver has non-standard ioctls */
563 the *cdrom_device_info* variable *mask*. For instance, the SCSI CD-ROM
564 driver has implemented the code for loading and ejecting CD-ROM's, and
566 CD-ROM drive might be a caddy system, which can't load the tray, and
572 	if (cdo->capability & ∼cdi->mask & CDC _⟨capability⟩) ...
579 -------
581 A final flag register controls the **behavior** of the CD-ROM
589 	CDO_USE_FFLAGS	/* use file_pointer->f_flags to indicate purpose for open() */
606 and `sunsite.unc.edu`, allows user level control of these flags.
609 The need to know the purpose of opening the CD-ROM device
615 call. The problem with CD-ROM drives, is that they can be used for
617 file systems, CD-ROM's, the other is to play audio CD's. Audio commands
624 On the other hand, when used as a removable-media disc drive (what the
625 original purpose of CD-ROM s is) we would like to make sure that the
627 scheme, some CD-ROM drivers don't do any integrity checking, resulting
629 attempt for mounting a CD-ROM on an empty drive occurs. This is not a
630 particularly elegant way to find out that there is no CD-ROM inserted;
631 it more-or-less looks like the old IBM-PC trying to read an empty floppy
636 availability of a CD-ROM and its correct type (data), would be
639 These two ways of using a CD-ROM drive, principally for data and
646 parameter (see `open(2)`). For CD-ROM devices, these flags aren't
647 implemented (some drivers implement checking for write-related flags,
650 CD-ROM devices: *O_CREAT*, *O_NOCTTY*, *O_TRUNC*, *O_APPEND*, and
651 *O_SYNC* have no meaning to a CD-ROM.
658 inserted some valid data-CD-ROM. Thus, our proposal of the
659 implementation for the *open()* call for CD-ROM s is:
661 - If no other flags are set than *O_RDONLY*, the device is opened
664   on the CD-ROM, such as closing the tray.
665 - If the option flag *O_NONBLOCK* is set, opening will always be
670 -------------------------
683    Incidentally, I think that SUN's approach to mounting CD-ROM s is very
684    good in origin: under Solaris a volume-daemon automatically mounts a
685    newly inserted CD-ROM under `/cdrom/*<volume-name>*`.
688    further and have **every** CD-ROM on the local area network be
690    machine you insert a CD-ROM, it will always appear at the same
692    implement such a user-program for Linux, I came across the
698 community. All the CD-player authors will have to be informed, we can
700 has most likely no influence on the behavior of the CD-players on
706 ----------------------------------
708 The routines in `cdrom.c` are designed in such a way that run-time
709 configuration of the behavior of CD-ROM devices (of **any** type)
725    This mimics the behavior of the current sbpcd-driver. The option flags are
727    the tray is opened on the last release, i. e., if a CD-ROM is unmounted,
731 maintainers and user program developers) to adopt the new CD-ROM
739 over` the CD-ROM interface to the kernel. The header file belonging
759 Uniform CD-ROM Driver::
764 This function returns zero upon success, and non-zero upon
782 Unregistering device *cdi* with minor number *MINOR(cdi->dev)* removes
784 the low-level driver, this disconnects the registered device-operation
785 routines from the CD-ROM interface. This function returns zero upon
786 success, and non-zero upon failure.
792 This function is not called directly by the low-level drivers, it is
803 This function implements the reverse-logic of *cdrom_open()*, and then
804 calls the device-dependent *release()* routine. When the use-count has
816 This function handles all the standard *ioctl* requests for CD-ROM
820 the remaining ones, that are presumable device-dependent. Generally, a
824 --------------------------------
826 The following `old` CD-ROM *ioctl()*\ 's are implemented by directly
827 calling device-operations in *cdrom_device_ops*, if implemented and
831 	Requests the last session on a CD-ROM.
837 	If *arg\not=0*, set behavior to auto-close (close
838 	tray on first open) and auto-eject (eject on last release), otherwise
839 	set behavior to non-moving on *open()* and *release()* calls.
844 ---------------------------------------
852 	Get sub-channel data in argument *arg* of type
864 	Play audio fragment in track-index format delimited by *arg*
880 ----------------------------
883 control the behavior of individual CD-ROM devices. New *ioctl*
893 	Select head-rate speed of disc specified as by *arg* in units
895 	150kB/sec file system data). The value 0 means `auto-select`,
900 	Select disc numbered *arg* from a juke-box.
903 	maximum number of discs in the juke-box found in the *cdrom_dops*.
906 	For juke-boxes, an extra argument *arg*
915 	an *ioctl* call to *CDROMSUBCHNL*. For juke-boxes, an extra argument
924 	implemented in the low level drivers, but is now carried out
925 	entirely in Uniform CD-ROM Driver.
935 	function, the Uniform CD-ROM Driver implements this *ioctl* as
937 	absolutely no CD-I, XA, or data tracks on it, it will be reported
940 	if the CD in question has any CD-I tracks on it, it will be
960 	Returns the number of slots in a juke-box.
975 ----------------------------
983 - Make a backup of your current driver.
984 - Get hold of the files `cdrom.c` and `cdrom.h`, they should be in
986 - Make sure you include `cdrom.h`.
987 - Change the 3rd argument of *register_blkdev* from `&<your-drive>_fops`
989 - Just after that line, add the following to register with the Uniform
990   CD-ROM Driver::
992 	register_cdrom(&<your-drive>_info);*
995 - Copy an example of the device-operations *struct* to your
1002 - Copy the *cdrom_device_info* declaration from the same example
1006 - Implement all functions in your `<device>_dops` structure,
1011 - Rename your `<device>_ioctl()` function to *audio_ioctl* and
1015 - You may remove all remaining memory checking code in the
1024 - All remaining *ioctl* cases must be moved to a separate
1025   function, *<device>_ioctl*, the device-dependent *ioctl()'s*. Note that
1027 - Change the prototypes of *<device>_open()* and
1030 - Try to recompile the drivers. We advise you to use modules, both
1039 CD-ROM-related code in the 2.1-kernel. Thanks to Scott Snyder and
1041 and IDE-CD drivers and added many ideas for extension of the data
1044 the Linux CD-ROM device driver developers who were kind