Lines Matching +full:drive +full:- +full:open +full:- +full:source
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
65 capabilities of a particular drive, in an *ad hoc* manner. More
68 close the tray if an *open()* call occurs when the tray is open, while
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
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 ∗/
156 cdrom_open, /∗ open ∗/
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
212 int (*open)(struct cdrom_device_info *, int)
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 */
283 struct and specifications of properties of the drive are stored in this
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
289 drive, measured in units of normal audio speed (176kB/sec raw data or
291 because they describe properties of the drive, which don't change after
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
301 data that is specific to a minor drive, can be accessed through *handle*,
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'
319 *open()* and *release()*. Other functions may be omitted, their
327 int open(struct cdrom_device_info *cdi, int purpose)
329 *Open()* should try to open the device for a specific *purpose*, which
332 - Open for reading data, as done by `mount()` (2), or the
334 - Open for *ioctl* commands, as done by audio-CD playing programs.
336 Notice that any strategic code (closing tray upon *open()*, etc.) is
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.
357 information on the status of the drive (not the status of the disc,
358 which may or may not be in the drive). If the drive is not a changer,
376 - 0 Close tray
377 - 1 Open tray
379 This function returns 0 upon success, and a non-zero value upon
388 drive allows this. The value of *lock* controls the desired locking
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
413 drive, measured in units of standard cdrom speed (176kB/sec raw data
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
468 caller only after the drive has finished resetting. If the drive is no
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
547 CDC_OPEN_TRAY /* can open tray */
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 */
557 CDC_DRIVE_STATUS /* driver implements drive status */
561 inform `cdrom.c` of what the driver can do. If the drive found
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
567 hence for this drive the *cdrom_device_info* struct will have set
572 if (cdo->capability & ∼cdi->mask & CDC _⟨capability⟩) ...
579 -------
581 A final flag register controls the **behavior** of the CD-ROM
584 have made the drive's support available to the Linux community. The
587 CDO_AUTO_CLOSE /* try to close tray upon device open() */
588 CDO_AUTO_EJECT /* try to open tray on last device close() */
589 CDO_USE_FFLAGS /* use file_pointer->f_flags to indicate purpose for open() */
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
622 *ioctl* commands, regardless of the state the drive is in.
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
626 disc drive is ready for operation upon opening the device. In the old
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
632 drive for a couple of seconds, after which the system complains it
634 removable medium in a drive, and we believe we should exploit that
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
641 behavior of the *open()* call. Audio use simply wants to open the
643 *ioctl* commands, while data use wants to open for correct 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
666 successful, unless the whole device doesn't exist. The drive will take
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
705 The preferred strategy of *open()*
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)
717 tray is found to be open, an attempt to close the tray is made. Then,
718 it is verified that a disc is in the drive and, if *CDO_CHECK_TYPE* is
721 system corruption. If the drive is opened for audio (*O_NONBLOCK* is
725 This mimics the behavior of the current sbpcd-driver. The option flags are
726 ignored, the tray is closed on the first open, if necessary. Similarly,
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
797 transferred to the device_dependent *open()* call.
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.
833 Open tray.
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`,
898 drive found in the *cdrom_dops*.
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*
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
996 source, e. g., from `cm206.c` *cm206_dops*, and change all
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