Lines Matching +full:i +full:- +full:drive
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 */
281 struct and specifications of properties of the drive are stored in this
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
287 drive, measured in units of normal audio speed (176kB/sec raw data or
289 because they describe properties of the drive, which don't change after
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
296 `arbitrary` wishes of the author of the low-level device driver, as is
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'
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.
355 information on the status of the drive (not the status of the disc,
356 which may or may not be in the drive). If the drive is not a changer,
374 - 0 Close tray
375 - 1 Open tray
377 This function returns 0 upon success, and a non-zero value upon
386 drive allows this. The value of *lock* controls the desired locking
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
411 drive, measured in units of standard cdrom speed (176kB/sec raw data
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,
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
457 caller only after the drive has finished resetting. If the drive is no
458 longer listening, it may be wise for the underlying low-level cdrom
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
475 location of *arg*, and reserves stack-memory for the argument. This
481 An unimplemented ioctl should return *-ENOSYS*, but a harmless request
484 an error is returned by the low-level driver, the Uniform CD-ROM Driver
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,
498 reading audio tracks as data, I believe this is because of protection
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
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
522 Is there software around that actually uses these? I'd be interested!
526 CD-ROM capabilities
527 -------------------
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 */
546 CDC_DRIVE_STATUS /* driver implements drive status */
550 inform `cdrom.c` of what the driver can do. If the drive found
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
556 hence for this drive the *cdrom_device_info* struct will have set
561 if (cdo->capability & ~cdi->mask & CDC _<capability>) ...
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
573 have made the drive's support available to the Linux community. The
578 CDO_USE_FFLAGS /* use file_pointer->f_flags to indicate purpose for open() */
598 The need to know the purpose of opening the CD-ROM device
604 call. The problem with CD-ROM drives, is that they can be used for
606 file systems, CD-ROM's, the other is to play audio CD's. Audio commands
611 *ioctl* commands, regardless of the state the drive is in.
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
615 disc drive is ready for operation upon opening the device. In the old
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
621 drive for a couple of seconds, after which the system complains it
623 removable medium in a drive, and we believe we should exploit that
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
635 parameter (see `open(2)`). For CD-ROM devices, these flags aren't
636 implemented (some drivers implement checking for write-related flags,
639 CD-ROM devices: *O_CREAT*, *O_NOCTTY*, *O_TRUNC*, *O_APPEND*, and
640 *O_SYNC* have no meaning to a CD-ROM.
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
655 successful, unless the whole device doesn't exist. The drive will take
659 -------------------------
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
678 mounted at the similar location, i. e., no matter in which particular
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
687 community. All the CD-player authors will have to be informed, we can
689 has most likely no influence on the behavior of the CD-players on
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)
707 it is verified that a disc is in the drive and, if *CDO_CHECK_TYPE* is
710 system corruption. If the drive is opened for audio (*O_NONBLOCK* is
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
728 over` the CD-ROM interface to the kernel. The header file belonging
748 Uniform CD-ROM Driver::
753 This function returns zero upon success, and non-zero upon
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
792 This function implements the reverse-logic of *cdrom_open()*, and then
793 calls the device-dependent *release()* routine. When the use-count has
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 ---------------------------------------
841 Get sub-channel data in argument *arg* of type
853 Play audio fragment in track-index format delimited by *arg*
869 ----------------------------
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`,
885 i. e., play audio discs at real time and data discs at maximum speed.
887 drive found in the *cdrom_dops*.
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*
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
914 current playing activity of the drive; this can be polled through
915 an *ioctl* call to *CDROMSUBCHNL*. For juke-boxes, an extra argument
920 Returns the type of the disc currently in the drive.
923 disc that is inserted in the drive. This functionality used to be
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.
962 Reset the drive.
964 Returns the *capability* flags for the drive. Refer to section
967 Locks the door of the drive. `arg == 0` unlocks the door,
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
1028 *<device>_release()*, and remove any strategic code (i. e., tray
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
1046 of course, I want to thank Linus Torvalds for making this possible in