Lines Matching +full:many +full:- +full:to +full:- +full:one
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.
24 The openness of Linux, and the many different types of available
25 hardware has allowed Linux to support many different hardware devices.
26 Unfortunately, the very openness that has allowed Linux to support
28 device driver to differ significantly from one device to another.
29 This divergence of behavior has been very significant for CD-ROM
30 devices; the way a particular drive reacts to a `standard` *ioctl()*
31 call varies greatly from one device driver to another. To avoid making
32 their drivers totally inconsistent, the writers of Linux CD-ROM
34 and then changing an existing one. Unfortunately, this practice did not
35 maintain uniform behavior across all the Linux CD-ROM drivers.
37 This document describes an effort to establish Uniform behavior across
38 all the different CD-ROM device drivers for Linux. This document also
39 defines the various *ioctl()'s*, and how the low-level CD-ROM device
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
45 and the computer was not specified in the standards. As a result, many
46 different CD-ROM interfaces were developed. Some of them had their
50 adapted their drives to one or more of the already existing electrical
54 scheme, either a separate driver had to be written, or an existing
55 driver had to be enhanced. History has delivered us CD-ROM support for
56 many of these different interfaces. Nowadays, almost all new CD-ROM
62 which was expressed through `cdrom.h`, it appeared to be a rather wild
63 set of commands and data formats [#f1]_. It seemed that many
64 features of the software interface had been added to accommodate the
69 others do not. Some drivers lock the door upon opening the device, to
70 prevent an incoherent file system, but others don't, to allow software
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
85 in the file `cdrom.c`. This driver is intended to be an additional software
86 layer that sits on top of the low-level device drivers for each CD-ROM drive.
87 By adding this additional layer, it is possible to have all the different
88 CD-ROM devices behave **exactly** the same (insofar as the underlying
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
98 programmer's interface defined in `cdrom.h`. This guide was written to
99 help CD-ROM driver developers adapt their code to use the Uniform CD-ROM
105 more than one CD-ROM drive, possibly of mixed types. It is important
106 that these drives behave in the same way. In December 1994, one of the
107 cheapest CD-ROM drives was a Philips cm206, a double-speed proprietary
110 standard. At the time of the last update to this document (November
111 1997) it is becoming difficult to even **find** anything less than a
112 16 speed CD-ROM drive, and 24 speed drives are common.
120 implemented the CD-ROM *ioctl()* calls through their own routines. This
121 led to the danger of different drivers forgetting to do important things
123 importantly, this led to the divergence of behavior, which has already
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
134 done to help ensure that the user is only presented with only one cdrom
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,
188 connected to the minor number of the device.
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
198 structure is a pointer to the *cdrom_device_ops* structure of the
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
204 through the functions in this structure. It is impossible to know all
205 the capabilities of future CD-ROM drives, so it is expected that this
206 list may need to be expanded from time to time as new technologies are
207 developed. For example, CD-R and CD-R/W drives are beginning to become
208 popular, and support will soon need to be added for them. For now, the
232 When a low-level device driver implements one of these capabilities,
233 it should add a function pointer to this *struct*. When a particular
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,
245 since many of them only support one device.) This will be available
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 */
284 The *mask* flags can be used to mask out some of the capabilities listed
285 in *ops->capability*, if a specific drive doesn't support a feature
286 of the driver. The value *speed* specifies the maximum head-rate of the
292 A few registers contain variables local to the CD-ROM drive. The
293 flags *options* are used to specify how the general CD-ROM routines
295 flexibility to adapt to the different users' wishes (and **not** the
296 `arbitrary` wishes of the author of the low-level device driver, as is
297 the case in the old scheme). The register *mc_flags* is used to buffer
298 the information from *media_changed()* to two separate queues. Other
299 data that is specific to a minor drive, can be accessed through *handle*,
300 which can point to a data structure specific to the low-level driver.
307 function *cdrom_ioctl()* will verify the appropriate user-memory regions
309 it will `sanitize` the format by making requests to the low-level
311 user-software and low level drivers. This relieves much of the drivers'
327 *Open()* should try to open the device for a specific *purpose*, which
330 - Open for reading data, as done by `mount()` (2), or the
332 - Open for *ioctl* commands, as done by audio-CD playing programs.
335 done by the calling routine in `cdrom.c`, so the low-level routine
343 Device-specific actions should be taken such as spinning down the device.
345 the door, should be left over to the general routine *cdrom_release()*.
374 - 0 Close tray
375 - 1 Open tray
377 This function returns 0 upon success, and a non-zero value upon
389 - 0 Unlock door, manual opening is allowed
390 - 1 Lock door, tray cannot be ejected manually
392 This function returns 0 upon success, and a non-zero value upon
400 Some CD-ROM drives are capable of changing their head-speed. There
401 are several reasons for changing the speed of a CD-ROM drive. Badly
402 pressed CD-ROM s may benefit from less-than-maximum head rate. Modern
403 CD-ROM drives can obtain very high head rates (up to *24x* is
410 played back. The value of *speed* specifies the head-speed of the
412 or 150kB/sec file system data). So to request that a CD-ROM drive
414 with *speed=2*. The special value `0` means `auto-selection`, i. e.,
415 maximum data-rate or real-time audio rate. If the drive doesn't have
416 this `auto-selection` capability, the decision should be made on the
426 device *cdi->dev*, the start of the last session of the current disc
431 sanitization goes even further: the low-level implementation may
433 (setting the *ms_info->addr_format* field appropriately, of
444 that is generally found in the bar-code on the product. Unfortunately,
446 same format. The return argument to this function is a pointer to a
447 pre-declared memory region of type *struct cdrom_mcn*. The MCN is
448 expected as a 13-character string, terminated by a null-character.
454 This call should perform a hard-reset on the drive (although in
455 circumstances that a hard-reset is necessary, a drive may very well not
456 listen to commands anymore). Preferably, control is returned to the
458 longer listening, it may be wise for the underlying low-level cdrom
459 driver to time out.
466 Some of the CD-ROM-\ *ioctl()*\ 's defined in `cdrom.h` can be
469 audio-control. We have decided to leave these to be accessed through a
473 though. It sanitizes the address format type to *CDROM_MSF* (Minutes,
475 location of *arg*, and reserves stack-memory for the argument. This
481 An unimplemented ioctl should return *-ENOSYS*, but a harmless request
483 errors should be according to the standards, whatever they are. When
484 an error is returned by the low-level driver, the Uniform CD-ROM Driver
485 tries whenever possible to return the error code to the calling program.
486 (We may decide to sanitize the return value in *cdrom_ioctl()* though, in
487 order to guarantee a uniform interface to the audio-player software.)
494 Some *ioctl()'s* seem to be specific to certain CD-ROM drives. That is,
495 they are introduced to service some capabilities of certain drives. In
497 particular kind of format, or audio data. Not many drives support
499 of copyrights of artists. Moreover, I think that if audio-tracks are
501 problem here could be the fact that audio-frames are 2352 bytes long,
502 so either the audio-file-system should ask for 75264 bytes at once
504 bend their backs to cope with this incoherence (to which I would be
505 opposed). Furthermore, it is very difficult for the hardware to find
510 Because there are so many *ioctl()'s* that seem to be introduced to
511 satisfy certain drivers [#f2]_, any non-standard *ioctl()*\ s
514 the general CD-ROM *ioctl* number, `0x53`. Currently the
515 non-supported *ioctl()'s* are:
518 CDROMREADCOOKED, CDROMSEEK, CDROMPLAY-BLK and CDROM-READALL
526 CD-ROM capabilities
527 -------------------
530 `cdrom.c` supplies the possibility to indicate the **capabilities**
531 of a CD-ROM drive. This can be done by ORing any number of
532 capability-constants that are defined in `cdrom.h` at the registration
539 CDC_SELECT_DISC /* drive is juke-box */
543 CDC_PLAY_AUDIO /* can perform audio-functions (play, pause, etc) */
545 CDC_IOCTLS /* driver has non-standard ioctls */
548 The capability flag is declared *const*, to prevent drivers from
552 the *cdrom_device_info* variable *mask*. For instance, the SCSI CD-ROM
553 driver has implemented the code for loading and ejecting CD-ROM's, and
555 CD-ROM drive might be a caddy system, which can't load the tray, and
559 In the file `cdrom.c` you will encounter many constructions of the type::
561 if (cdo->capability & ~cdi->mask & CDC _<capability>) ...
563 There is no *ioctl* to set the mask... The reason is that
564 I think it is better to control the **behavior** rather than the
568 -------
570 A final flag register controls the **behavior** of the CD-ROM
571 drives, in order to satisfy different users' wishes, hopefully
572 independently of the ideas of the respective author who happened to
573 have made the drive's support available to the Linux community. The
576 CDO_AUTO_CLOSE /* try to close tray upon device open() */
577 CDO_AUTO_EJECT /* try to open tray on last device close() */
578 CDO_USE_FFLAGS /* use file_pointer->f_flags to indicate purpose for open() */
579 CDO_LOCK /* try to lock door if device is opened */
585 new *ioctl()'s* implemented in `cdrom.c`, that allow you to control the
591 One option needs some more explanation: *CDO_USE_FFLAGS*. In the next
598 The need to know the purpose of opening the CD-ROM device
602 either by reading/writing to the device file, or by issuing
603 controlling commands to the device, by the device's *ioctl()*
604 call. The problem with CD-ROM drives, is that they can be used for
605 two entirely different purposes. One is to mount removable
606 file systems, CD-ROM's, the other is to play audio CD's. Audio commands
610 that the device can **always** be opened in order to give the
613 On the other hand, when used as a removable-media disc drive (what the
614 original purpose of CD-ROM s is) we would like to make sure that the
616 scheme, some CD-ROM drivers don't do any integrity checking, resulting
617 in a number of i/o errors reported by the VFS to the kernel when an
618 attempt for mounting a CD-ROM on an empty drive occurs. This is not a
619 particularly elegant way to find out that there is no CD-ROM inserted;
620 it more-or-less looks like the old IBM-PC trying to read an empty floppy
625 availability of a CD-ROM and its correct type (data), would be
628 These two ways of using a CD-ROM drive, principally for data and
630 behavior of the *open()* call. Audio use simply wants to open the
631 device in order to get a file handle which is needed for issuing
632 *ioctl* commands, while data use wants to open for correct and
635 parameter (see `open(2)`). For CD-ROM devices, these flags aren't
636 implemented (some drivers implement checking for write-related flags,
638 permission flags). Most option flags simply don't make sense to
639 CD-ROM devices: *O_CREAT*, *O_NOCTTY*, *O_TRUNC*, *O_APPEND*, and
640 *O_SYNC* have no meaning to a CD-ROM.
642 We therefore propose to use the flag *O_NONBLOCK* to indicate
645 subsequent calls to the device don't cause the calling process to
647 inserted some valid data-CD-ROM. Thus, our proposal of the
648 implementation for the *open()* call for CD-ROM s is:
650 - If no other flags are set than *O_RDONLY*, the device is opened
653 on the CD-ROM, such as closing the tray.
654 - If the option flag *O_NONBLOCK* is set, opening will always be
659 -------------------------
661 You might hesitate to accept this proposal as it comes from the
666 and are large enough to set their own standard. They do not have to
672 Incidentally, I think that SUN's approach to mounting CD-ROM s is very
673 good in origin: under Solaris a volume-daemon automatically mounts a
674 newly inserted CD-ROM under `/cdrom/*<volume-name>*`.
677 further and have **every** CD-ROM on the local area network be
679 machine you insert a CD-ROM, it will always appear at the same
680 position in the directory tree, on every system. When I wanted to
681 implement such a user-program for Linux, I came across the
685 We believe that using *O_NONBLOCK* to indicate that a device is being opened
687 community. All the CD-player authors will have to be informed, we can
688 even send in our own patches to the programs. The use of *O_NONBLOCK*
689 has most likely no influence on the behavior of the CD-players on
691 to old behavior by a call to
695 ----------------------------------
697 The routines in `cdrom.c` are designed in such a way that run-time
698 configuration of the behavior of CD-ROM devices (of **any** type)
706 tray is found to be open, an attempt to close the tray is made. Then,
709 are passed is the return value zero. The door is locked to prevent file
714 This mimics the behavior of the current sbpcd-driver. The option flags are
716 the tray is opened on the last release, i. e., if a CD-ROM is unmounted,
720 maintainers and user program developers) to adopt the new CD-ROM
726 Only a few routines in `cdrom.c` are exported to the drivers. In this
728 over` the CD-ROM interface to the kernel. The header file belonging
729 to `cdrom.c` is called `cdrom.h`. Formerly, some of the contents of this
738 A pointer to this structure is assigned to the *fops* field
745 This function is used in about the same way one registers *cdrom_fops*
748 Uniform CD-ROM Driver::
753 This function returns zero upon success, and non-zero upon
754 failure. The structure *<device>_info* should have a pointer to the
762 Note that a driver must have one static structure, *<device>_dops*, while
763 it may have as many structures *<device>_info* as there are minor devices
771 Unregistering device *cdi* with minor number *MINOR(cdi->dev)* removes
773 the low-level driver, this disconnects the registered device-operation
774 routines from the CD-ROM interface. This function returns zero upon
775 success, and non-zero upon failure.
781 This function is not called directly by the low-level drivers, it is
785 *cdrom_device_ops* connected to the device. Then, the program flow is
786 transferred to the device_dependent *open()* call.
792 This function implements the reverse-logic of *cdrom_open()*, and then
793 calls the device-dependent *release()* routine. When the use-count has
794 reached 0, the allocated buffers are flushed by calls to *sync_dev(dev)*
805 This function handles all the standard *ioctl* requests for CD-ROM
809 the remaining ones, that are presumable device-dependent. Generally, a
813 --------------------------------
815 The following `old` CD-ROM *ioctl()*\ 's are implemented by directly
816 calling device-operations in *cdrom_device_ops*, if implemented and
820 Requests the last session on a CD-ROM.
826 If *arg\not=0*, set behavior to auto-close (close
827 tray on first open) and auto-eject (eject on last release), otherwise
828 set behavior to non-moving on *open()* and *release()* calls.
833 ---------------------------------------
835 The following set of *ioctl()'s* are all implemented through a call to
841 Get sub-channel data in argument *arg* of type
853 Play audio fragment in track-index format delimited by *arg*
869 ----------------------------
871 The following *ioctl()'s* have been introduced to allow user programs to
872 control the behavior of individual CD-ROM devices. New *ioctl*
882 Select head-rate speed of disc specified as by *arg* in units
884 150kB/sec file system data). The value 0 means `auto-select`,
889 Select disc numbered *arg* from a juke-box.
892 maximum number of discs in the juke-box found in the *cdrom_dops*.
895 For juke-boxes, an extra argument *arg*
903 *arg* is a pointer to a *cdrom_timed_media_change_info* struct.
904 *arg->last_media_change* may be set by calling code to signal
907 *arg->last_media_change* to the latest media change timestamp (in ms)
908 known by the kernel/driver and set *arg->has_changed* to 1 if
911 Returns the status of the drive by a call to
915 an *ioctl* call to *CDROMSUBCHNL*. For juke-boxes, an extra argument
921 It should be viewed as a complement to *CDROM_DRIVE_STATUS*.
923 disc that is inserted in the drive. This functionality used to be
925 entirely in Uniform CD-ROM Driver.
928 various digital information has lead to many different disc types.
930 one} type of data on them. While this is often the case, it is
931 also very common for CDs to have some tracks with data, and some
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.
964 Returns the *capability* flags for the drive. Refer to section
970 Turns on debugging info. Only root is allowed to do this.
975 ----------------------------
977 Finally, all other *ioctl()'s* are passed to the function *dev_ioctl()*,
980 How to update your driver
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`
988 to `&cdrom_fops`.
989 - Just after that line, add the following to register with the Uniform
990 CD-ROM Driver::
992 register_cdrom(&<your-drive>_info);*
994 Similarly, add a call to *unregister_cdrom()* at the appropriate place.
995 - Copy an example of the device-operations *struct* to your
997 entries to names corresponding to your driver, or names you just
998 happen to like. If your driver doesn't support a certain function,
1002 - Copy the *cdrom_device_info* declaration from the same example
1003 driver, and modify the entries according to your needs. If your
1006 - Implement all functions in your `<device>_dops` structure,
1007 according to prototypes listed in `cdrom.h`, and specifications given
1009 the code in a large part, and you will almost certainly need to adapt the
1011 - Rename your `<device>_ioctl()` function to *audio_ioctl* and
1014 just calls to the routines you adapted in the previous step.
1015 - You may remove all remaining memory checking code in the
1019 statement look similar to::
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
1037 Thanks to all the people involved. First, Erik Andersen, who has
1039 CD-ROM-related code in the 2.1-kernel. Thanks to Scott Snyder and
1040 Gerd Knorr, who were the first to implement this interface for SCSI
1041 and IDE-CD drivers and added many ideas for extension of the data
1042 structures relative to kernel~2.0. Further thanks to Heiko Eißfeldt,
1044 the Linux CD-ROM device driver developers who were kind
1045 enough to give suggestions and criticisms during the writing. Finally
1046 of course, I want to thank Linus Torvalds for making this possible in