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
30 devices; the way a particular drive reacts to a `standard` *ioctl()*
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
52 most of the `NoName` manufacturers). In cases where a new drive really
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
61 When (in the 1.3.70's) I looked at the existing software interface,
65 capabilities of a particular drive, in an *ad hoc* manner. More
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
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
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
102 Personally, I think that the most important hardware interfaces are
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
108 drive. In the months that I was busy writing a Linux driver for it,
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 */
282 struct and specifications of properties of the drive are stored in this
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
288 drive, measured in units of normal audio speed (176kB/sec raw data or
290 because they describe properties of the drive, which don't change after
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
300 data that is specific to a minor drive, can be accessed through *handle*,
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.
356 information on the status of the drive (not the status of the disc,
357 which may or may not be in the drive). If the drive is not a changer,
375 - 0 Close tray
376 - 1 Open tray
378 This function returns 0 upon success, and a non-zero value upon
387 drive allows this. The value of *lock* controls the desired locking
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
412 drive, measured in units of standard cdrom speed (176kB/sec raw data
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,
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
458 caller only after the drive has finished resetting. If the drive is no
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,
499 reading audio tracks as data, I believe this is because of protection
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
505 bend their backs to cope with this incoherence (to which I would be
512 satisfy certain drivers [#f2]_, any non-standard *ioctl()*\ s
515 the general CD-ROM *ioctl* number, `0x53`. Currently the
516 non-supported *ioctl()'s* are:
519 	CDROMREADCOOKED, CDROMSEEK, CDROMPLAY-BLK and CDROM-READALL
523    Is there software around that actually uses these? I'd be interested!
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 */
547 	CDC_DRIVE_STATUS	/* driver implements drive status */
551 inform `cdrom.c` of what the driver can do. If the drive found
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
557 hence for this drive the *cdrom_device_info* struct will have set
562 	if (cdo->capability & ~cdi->mask & CDC _<capability>) ...
565 I think it is better to control the **behavior** rather than the
569 -------
571 A final flag register controls the **behavior** of the CD-ROM
574 have made the drive's support available to the Linux community. The
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
612 *ioctl* commands, regardless of the state the drive is in.
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
616 disc drive is ready for operation upon opening the device. In the old
617 scheme, some CD-ROM drivers don't do any integrity checking, resulting
618 in a number of i/o errors reported by the VFS to the kernel when an
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
622 drive for a couple of seconds, after which the system complains it
624 removable medium in a drive, and we believe we should exploit that
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
654   on the CD-ROM, such as closing the tray.
655 - If the option flag *O_NONBLOCK* is set, opening will always be
656   successful, unless the whole device doesn't exist. The drive will take
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
679    mounted at the similar location, i. e., no matter in which particular
680    machine you insert a CD-ROM, it will always appear at the same
681    position in the directory tree, on every system. When I wanted to
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
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)
708    it is verified that a disc is in the drive and, if *CDO_CHECK_TYPE* is
711    system corruption. If the drive is opened for audio (*O_NONBLOCK* is
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`,
886 	i. e., play audio discs at real time and data discs at maximum speed.
888 	drive found in the *cdrom_dops*.
890 	Select disc numbered *arg* from a juke-box.
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
912 	Returns the status of the drive by a call to
915 	current playing activity of the drive; this can be polled through
916 	an *ioctl* call to *CDROMSUBCHNL*. For juke-boxes, an extra argument
921 	Returns the type of the disc currently in the drive.
924 	disc that is inserted in the drive. This functionality used to be
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.
963 	Reset the drive.
965 	Returns the *capability* flags for the drive. Refer to section
968 	 Locks the door of the drive. `arg == 0` unlocks the door,
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
1029   *<device>_release()*, and remove any strategic code (i. e., tray
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
1047 of course, I want to thank Linus Torvalds for making this possible in