Lines Matching +full:loss +full:- +full:of +full:- +full:signal
2 A Linux CD-ROM standard
14 Linux is probably the Unix-like operating system that supports
15 the widest variety of hardware devices. The reasons for this are
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
27 all these different devices has also allowed the behavior of each
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
40 drivers should implement them. Currently (as of the Linux 2.1.\ *x*
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
50 adapted their drives to one or more of the already existing electrical
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
63 set of commands and data formats [#f1]_. It seemed that many
64 features of the software interface had been added to accommodate the
65 capabilities of a particular drive, in an *ad hoc* manner. More
66 importantly, it appeared that the behavior of the `standard` commands
67 was different for most of the different drivers: e. g., some drivers
71 ejection. Undoubtedly, the capabilities of the different drives vary,
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
103 the IDE/ATAPI drives and, of course, the SCSI drives, but as prices
104 of hardware drop continuously, it is also likely that people may have
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
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
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
176 capabilities of the driver, and the specific drives on which the
180 This structure contains information about the low-level driver for a
181 CD-ROM device. This structure is conceptually connected to the major
182 number of the device (although some drivers may have different
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
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,
235 NULL instead. The *capability* flags specify the capabilities of the
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.
240 *blkdev_fops* counterparts. This is because very little of the
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
253 struct list_head list; /* linked list of all device_info */
255 void * handle; /* driver-dependent data */
257 int mask; /* mask of capability: disables them */
259 int capacity; /* number of discs in a jukebox */
262 unsigned mc_flags:2; /* media-change buffer flags */
265 int use_count; /* number of times device is opened */
266 char name[20]; /* name of the device type */
268 __u8 sanyo_slot : 2; /* Sanyo 3-CD changer support */
280 Using this *struct*, a linked list of the registered minor devices is
282 struct and specifications of properties of the drive are stored in this
285 The *mask* flags can be used to mask out some of the capabilities listed
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
301 which can point to a data structure specific to the low-level driver.
306 additional bookkeeping. The use count of the device (the number of
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'
316 The implementation of the functions should be as defined in the
321 function call should return only after the command has completed, but of
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.
345 However, strategic actions such as ejection of the tray, or unlocking
356 information on the status of the drive (not the status of the disc,
373 the desired direction of movement:
375 - 0 Close tray
376 - 1 Open tray
378 This function returns 0 upon success, and a non-zero value upon
386 This function (and no other code) controls locking of the door, if the
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
406 errors at these high speeds, reducing the speed can prevent data loss
407 in these circumstances. Finally, some of these drives can
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
430 format will **always** be of the type *CDROM_LBA* (linear block
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
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
472 the latter is of type *void*, rather than *unsigned long int*.
476 location of *arg*, and reserves stack-memory for the argument. This
477 makes implementation of the *audio_ioctl()* much simpler than in the
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,
496 they are introduced to service some capabilities of certain drives. In
498 particular kind of format, or audio data. Not many drives support
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
504 (the least common multiple of 512 and 2352), or the drivers should
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
527 CD-ROM capabilities
528 -------------------
530 Instead of just implementing some *ioctl* calls, the interface in
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
534 phase. Currently, the capabilities are any of::
539 CDC_SELECT_SPEED /* can select speed, in units of * sim*150 ,kB/s */
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 */
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
560 In the file `cdrom.c` you will encounter many constructions of the type::
562 if (cdo->capability & ~cdi->mask & CDC _<capability>) ...
569 -------
571 A final flag register controls the **behavior** of the CD-ROM
573 independently of the ideas of the respective author who happened to
579 CDO_USE_FFLAGS /* use file_pointer->f_flags to indicate purpose for open() */
583 The initial value of this register is
596 and `sunsite.unc.edu`, allows user level control of these flags.
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
610 nothing wrong with this, but a good control of the `CD player` demands
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
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
623 can't read from it. Nowadays we can **sense** the existence of a
625 fact. An integrity check on opening of the device, that verifies the
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
631 behavior of the *open()* call. Audio use simply wants to open the
635 their *purpose* of opening the device is, is through the *flags*
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.
645 commands. Strictly, the meaning of *O_NONBLOCK* is that opening and
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 -------------------------
666 control both the hardware and software of their supported products,
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
683 differences in behavior of the various drivers, and the need for an
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
695 The preferred strategy of *open()*
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)
701 modes of operation can be set:
709 set, that it contains tracks of type `data mode 1`. Only if all tests
712 set), no actions are taken and a value of 0 will be returned.
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
724 Description of routines in `cdrom.c`
729 over` the CD-ROM interface to the kernel. The header file belonging
730 to `cdrom.c` is called `cdrom.h`. Formerly, some of the contents of this
738 The contents of this structure were described in cdrom_api_.
740 of the *struct gendisk*.
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
785 taking care of all capabilities and options that are set in the
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 ---------------------------------------
836 The following set of *ioctl()'s* are all implemented through a call to
838 allocation are performed in *cdrom_ioctl()*, and also sanitization of
842 Get sub-channel data in argument *arg* of type
845 Read Table of Contents header, in *arg* of type
848 Read a Table of Contents entry in *arg* and specified by *arg*
849 of type `struct cdrom_tocentry *`.
852 delimited by *arg* of type `struct cdrom_msf *`.
854 Play audio fragment in track-index format delimited by *arg*
855 of type `struct cdrom_ti *`.
857 Set volume specified by *arg* of type `struct cdrom_volctrl *`.
859 Read volume into by *arg* of type `struct cdrom_volctrl *`.
863 Stop playback of audio fragment.
865 Pause playback of audio fragment.
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
884 of standard cdrom speed (176\,kB/sec raw data or
885 150kB/sec file system data). The value 0 means `auto-select`,
887 The value *arg* is checked against the maximum head rate of the
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*
902 and returns the time of the last disc change.
905 *arg->last_media_change* may be set by calling code to signal
906 the timestamp of the last known media change (by the caller).
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.
926 entirely in Uniform CD-ROM Driver.
928 The history of development of the CD's use as a carrier medium for
931 one} type of data on them. While this is often the case, it is
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
957 For some information concerning frame layout of the various disc
958 types, see a recent version of `cdrom.h`.
961 Returns the number of slots in a juke-box.
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
1005 driver dynamically determines the capabilities of the hardware, this
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
1018 listed in the second part of cdrom_ioctl_. There is no
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
1047 of course, I want to thank Linus Torvalds for making this possible in