^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) =======================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) A Linux CD-ROM standard
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) =======================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) :Author: David van Leeuwen <david@ElseWare.cistron.nl>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) :Date: 12 March 1999
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) :Updated by: Erik Andersen (andersee@debian.org)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) :Updated by: Jens Axboe (axboe@image.dk)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) Introduction
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) Linux is probably the Unix-like operating system that supports
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) the widest variety of hardware devices. The reasons for this are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) presumably
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) - The large list of hardware devices available for the many platforms
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) that Linux now supports (i.e., i386-PCs, Sparc Suns, etc.)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) - The open design of the operating system, such that anybody can write a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) driver for Linux.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) - There is plenty of source code around as examples of how to write a driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) The openness of Linux, and the many different types of available
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) hardware has allowed Linux to support many different hardware devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) Unfortunately, the very openness that has allowed Linux to support
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) all these different devices has also allowed the behavior of each
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) device driver to differ significantly from one device to another.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) This divergence of behavior has been very significant for CD-ROM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) devices; the way a particular drive reacts to a `standard` *ioctl()*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) call varies greatly from one device driver to another. To avoid making
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) their drivers totally inconsistent, the writers of Linux CD-ROM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) drivers generally created new device drivers by understanding, copying,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) and then changing an existing one. Unfortunately, this practice did not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) maintain uniform behavior across all the Linux CD-ROM drivers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) This document describes an effort to establish Uniform behavior across
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) all the different CD-ROM device drivers for Linux. This document also
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) defines the various *ioctl()'s*, and how the low-level CD-ROM device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) drivers should implement them. Currently (as of the Linux 2.1.\ *x*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) development kernels) several low-level CD-ROM device drivers, including
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) both IDE/ATAPI and SCSI, now use this Uniform interface.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) When the CD-ROM was developed, the interface between the CD-ROM drive
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) and the computer was not specified in the standards. As a result, many
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) different CD-ROM interfaces were developed. Some of them had their
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) own proprietary design (Sony, Mitsumi, Panasonic, Philips), other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) manufacturers adopted an existing electrical interface and changed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) the functionality (CreativeLabs/SoundBlaster, Teac, Funai) or simply
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) adapted their drives to one or more of the already existing electrical
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) interfaces (Aztech, Sanyo, Funai, Vertos, Longshine, Optics Storage and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) most of the `NoName` manufacturers). In cases where a new drive really
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) brought its own interface or used its own command set and flow control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) scheme, either a separate driver had to be written, or an existing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) driver had to be enhanced. History has delivered us CD-ROM support for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) many of these different interfaces. Nowadays, almost all new CD-ROM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) drives are either IDE/ATAPI or SCSI, and it is very unlikely that any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) manufacturer will create a new interface. Even finding drives for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) old proprietary interfaces is getting difficult.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) When (in the 1.3.70's) I looked at the existing software interface,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) which was expressed through `cdrom.h`, it appeared to be a rather wild
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) set of commands and data formats [#f1]_. It seemed that many
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) features of the software interface had been added to accommodate the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) capabilities of a particular drive, in an *ad hoc* manner. More
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) importantly, it appeared that the behavior of the `standard` commands
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) was different for most of the different drivers: e. g., some drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) close the tray if an *open()* call occurs when the tray is open, while
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) others do not. Some drivers lock the door upon opening the device, to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) prevent an incoherent file system, but others don't, to allow software
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) ejection. Undoubtedly, the capabilities of the different drives vary,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) but even when two drives have the same capability their drivers'
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) behavior was usually different.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) .. [#f1]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) I cannot recollect what kernel version I looked at, then,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) presumably 1.2.13 and 1.3.34 --- the latest kernel that I was
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) indirectly involved in.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) I decided to start a discussion on how to make all the Linux CD-ROM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) drivers behave more uniformly. I began by contacting the developers of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) the many CD-ROM drivers found in the Linux kernel. Their reactions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) encouraged me to write the Uniform CD-ROM Driver which this document is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) intended to describe. The implementation of the Uniform CD-ROM Driver is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) in the file `cdrom.c`. This driver is intended to be an additional software
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) layer that sits on top of the low-level device drivers for each CD-ROM drive.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) By adding this additional layer, it is possible to have all the different
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) CD-ROM devices behave **exactly** the same (insofar as the underlying
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) hardware will allow).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) The goal of the Uniform CD-ROM Driver is **not** to alienate driver developers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) whohave not yet taken steps to support this effort. The goal of Uniform CD-ROM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) Driver is simply to give people writing application programs for CD-ROM drives
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) **one** Linux CD-ROM interface with consistent behavior for all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) CD-ROM devices. In addition, this also provides a consistent interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) between the low-level device driver code and the Linux kernel. Care
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) is taken that 100% compatibility exists with the data structures and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) programmer's interface defined in `cdrom.h`. This guide was written to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) help CD-ROM driver developers adapt their code to use the Uniform CD-ROM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) Driver code defined in `cdrom.c`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) Personally, I think that the most important hardware interfaces are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) the IDE/ATAPI drives and, of course, the SCSI drives, but as prices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) of hardware drop continuously, it is also likely that people may have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) more than one CD-ROM drive, possibly of mixed types. It is important
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) that these drives behave in the same way. In December 1994, one of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) cheapest CD-ROM drives was a Philips cm206, a double-speed proprietary
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) drive. In the months that I was busy writing a Linux driver for it,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) proprietary drives became obsolete and IDE/ATAPI drives became the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) standard. At the time of the last update to this document (November
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) 1997) it is becoming difficult to even **find** anything less than a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) 16 speed CD-ROM drive, and 24 speed drives are common.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) .. _cdrom_api:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) Standardizing through another software level
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) ============================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) At the time this document was conceived, all drivers directly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) implemented the CD-ROM *ioctl()* calls through their own routines. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) led to the danger of different drivers forgetting to do important things
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) like checking that the user was giving the driver valid data. More
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) importantly, this led to the divergence of behavior, which has already
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) been discussed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) For this reason, the Uniform CD-ROM Driver was created to enforce consistent
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) CD-ROM drive behavior, and to provide a common set of services to the various
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) low-level CD-ROM device drivers. The Uniform CD-ROM Driver now provides another
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) software-level, that separates the *ioctl()* and *open()* implementation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) from the actual hardware implementation. Note that this effort has
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) made few changes which will affect a user's application programs. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) greatest change involved moving the contents of the various low-level
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) CD-ROM drivers\' header files to the kernel's cdrom directory. This was
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) done to help ensure that the user is only presented with only one cdrom
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) interface, the interface defined in `cdrom.h`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) CD-ROM drives are specific enough (i. e., different from other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) block-devices such as floppy or hard disc drives), to define a set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) of common **CD-ROM device operations**, *<cdrom-device>_dops*.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) These operations are different from the classical block-device file
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) operations, *<block-device>_fops*.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) The routines for the Uniform CD-ROM Driver interface level are implemented
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) in the file `cdrom.c`. In this file, the Uniform CD-ROM Driver interfaces
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) with the kernel as a block device by registering the following general
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) *struct file_operations*::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) struct file_operations cdrom_fops = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) NULL, /∗ lseek ∗/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) block _read , /∗ read—general block-dev read ∗/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) block _write, /∗ write—general block-dev write ∗/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) NULL, /∗ readdir ∗/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) NULL, /∗ select ∗/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) cdrom_ioctl, /∗ ioctl ∗/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) NULL, /∗ mmap ∗/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) cdrom_open, /∗ open ∗/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) cdrom_release, /∗ release ∗/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) NULL, /∗ fsync ∗/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) NULL, /∗ fasync ∗/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) NULL /∗ revalidate ∗/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) Every active CD-ROM device shares this *struct*. The routines
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) declared above are all implemented in `cdrom.c`, since this file is the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) place where the behavior of all CD-ROM-devices is defined and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) standardized. The actual interface to the various types of CD-ROM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) hardware is still performed by various low-level CD-ROM-device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) drivers. These routines simply implement certain **capabilities**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) that are common to all CD-ROM (and really, all removable-media
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) devices).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) Registration of a low-level CD-ROM device driver is now done through
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) the general routines in `cdrom.c`, not through the Virtual File System
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) (VFS) any more. The interface implemented in `cdrom.c` is carried out
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) through two general structures that contain information about the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) capabilities of the driver, and the specific drives on which the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) driver operates. The structures are:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) cdrom_device_ops
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) This structure contains information about the low-level driver for a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) CD-ROM device. This structure is conceptually connected to the major
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) number of the device (although some drivers may have different
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) major numbers, as is the case for the IDE driver).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) cdrom_device_info
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) This structure contains information about a particular CD-ROM drive,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) such as its device name, speed, etc. This structure is conceptually
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) connected to the minor number of the device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) Registering a particular CD-ROM drive with the Uniform CD-ROM Driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) is done by the low-level device driver though a call to::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) register_cdrom(struct cdrom_device_info * <device>_info)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) The device information structure, *<device>_info*, contains all the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) information needed for the kernel to interface with the low-level
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) CD-ROM device driver. One of the most important entries in this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) structure is a pointer to the *cdrom_device_ops* structure of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) low-level driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) The device operations structure, *cdrom_device_ops*, contains a list
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) of pointers to the functions which are implemented in the low-level
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) device driver. When `cdrom.c` accesses a CD-ROM device, it does it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) through the functions in this structure. It is impossible to know all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) the capabilities of future CD-ROM drives, so it is expected that this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) list may need to be expanded from time to time as new technologies are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) developed. For example, CD-R and CD-R/W drives are beginning to become
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) popular, and support will soon need to be added for them. For now, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) current *struct* is::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) struct cdrom_device_ops {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) int (*open)(struct cdrom_device_info *, int)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) void (*release)(struct cdrom_device_info *);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) int (*drive_status)(struct cdrom_device_info *, int);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) unsigned int (*check_events)(struct cdrom_device_info *,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) unsigned int, int);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) int (*media_changed)(struct cdrom_device_info *, int);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) int (*tray_move)(struct cdrom_device_info *, int);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) int (*lock_door)(struct cdrom_device_info *, int);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) int (*select_speed)(struct cdrom_device_info *, int);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) int (*select_disc)(struct cdrom_device_info *, int);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) int (*get_last_session) (struct cdrom_device_info *,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) struct cdrom_multisession *);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) int (*get_mcn)(struct cdrom_device_info *, struct cdrom_mcn *);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) int (*reset)(struct cdrom_device_info *);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) int (*audio_ioctl)(struct cdrom_device_info *,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) unsigned int, void *);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) const int capability; /* capability flags */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) int (*generic_packet)(struct cdrom_device_info *,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) struct packet_command *);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) When a low-level device driver implements one of these capabilities,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) it should add a function pointer to this *struct*. When a particular
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) function is not implemented, however, this *struct* should contain a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) NULL instead. The *capability* flags specify the capabilities of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) CD-ROM hardware and/or low-level CD-ROM driver when a CD-ROM drive
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) is registered with the Uniform CD-ROM Driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) Note that most functions have fewer parameters than their
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) *blkdev_fops* counterparts. This is because very little of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) information in the structures *inode* and *file* is used. For most
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) drivers, the main parameter is the *struct* *cdrom_device_info*, from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) which the major and minor number can be extracted. (Most low-level
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) CD-ROM drivers don't even look at the major and minor number though,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) since many of them only support one device.) This will be available
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) through *dev* in *cdrom_device_info* described below.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) The drive-specific, minor-like information that is registered with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) `cdrom.c`, currently contains the following fields::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) struct cdrom_device_info {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) const struct cdrom_device_ops * ops; /* device operations for this major */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) struct list_head list; /* linked list of all device_info */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) struct gendisk * disk; /* matching block layer disk */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) void * handle; /* driver-dependent data */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) int mask; /* mask of capability: disables them */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) int speed; /* maximum speed for reading data */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) int capacity; /* number of discs in a jukebox */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) unsigned int options:30; /* options flags */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) unsigned mc_flags:2; /* media-change buffer flags */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) unsigned int vfs_events; /* cached events for vfs path */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) unsigned int ioctl_events; /* cached events for ioctl path */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) int use_count; /* number of times device is opened */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) char name[20]; /* name of the device type */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) __u8 sanyo_slot : 2; /* Sanyo 3-CD changer support */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) __u8 keeplocked : 1; /* CDROM_LOCKDOOR status */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) __u8 reserved : 5; /* not used yet */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) int cdda_method; /* see CDDA_* flags */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) __u8 last_sense; /* saves last sense key */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) __u8 media_written; /* dirty flag, DVD+RW bookkeeping */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) unsigned short mmc3_profile; /* current MMC3 profile */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) int for_data; /* unknown:TBD */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) int (*exit)(struct cdrom_device_info *);/* unknown:TBD */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) int mrw_mode_page; /* which MRW mode page is in use */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) Using this *struct*, a linked list of the registered minor devices is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) built, using the *next* field. The device number, the device operations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) struct and specifications of properties of the drive are stored in this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) structure.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) The *mask* flags can be used to mask out some of the capabilities listed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) in *ops->capability*, if a specific drive doesn't support a feature
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) of the driver. The value *speed* specifies the maximum head-rate of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) drive, measured in units of normal audio speed (176kB/sec raw data or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) 150kB/sec file system data). The parameters are declared *const*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) because they describe properties of the drive, which don't change after
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) registration.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) A few registers contain variables local to the CD-ROM drive. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) flags *options* are used to specify how the general CD-ROM routines
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) should behave. These various flags registers should provide enough
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) flexibility to adapt to the different users' wishes (and **not** the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) `arbitrary` wishes of the author of the low-level device driver, as is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) the case in the old scheme). The register *mc_flags* is used to buffer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) the information from *media_changed()* to two separate queues. Other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) data that is specific to a minor drive, can be accessed through *handle*,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) which can point to a data structure specific to the low-level driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) The fields *use_count*, *next*, *options* and *mc_flags* need not be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) initialized.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) The intermediate software layer that `cdrom.c` forms will perform some
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) additional bookkeeping. The use count of the device (the number of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) processes that have the device opened) is registered in *use_count*. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) function *cdrom_ioctl()* will verify the appropriate user-memory regions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) for read and write, and in case a location on the CD is transferred,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) it will `sanitize` the format by making requests to the low-level
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) drivers in a standard format, and translating all formats between the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) user-software and low level drivers. This relieves much of the drivers'
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) memory checking and format checking and translation. Also, the necessary
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) structures will be declared on the program stack.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) The implementation of the functions should be as defined in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) following sections. Two functions **must** be implemented, namely
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) *open()* and *release()*. Other functions may be omitted, their
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) corresponding capability flags will be cleared upon registration.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) Generally, a function returns zero on success and negative on error. A
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) function call should return only after the command has completed, but of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) course waiting for the device should not use processor time.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) int open(struct cdrom_device_info *cdi, int purpose)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) *Open()* should try to open the device for a specific *purpose*, which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) can be either:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) - Open for reading data, as done by `mount()` (2), or the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) user commands `dd` or `cat`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) - Open for *ioctl* commands, as done by audio-CD playing programs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) Notice that any strategic code (closing tray upon *open()*, etc.) is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) done by the calling routine in `cdrom.c`, so the low-level routine
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) should only be concerned with proper initialization, such as spinning
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) up the disc, etc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) void release(struct cdrom_device_info *cdi)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345) Device-specific actions should be taken such as spinning down the device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) However, strategic actions such as ejection of the tray, or unlocking
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347) the door, should be left over to the general routine *cdrom_release()*.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) This is the only function returning type *void*.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) .. _cdrom_drive_status:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) int drive_status(struct cdrom_device_info *cdi, int slot_nr)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356) The function *drive_status*, if implemented, should provide
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357) information on the status of the drive (not the status of the disc,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358) which may or may not be in the drive). If the drive is not a changer,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359) *slot_nr* should be ignored. In `cdrom.h` the possibilities are listed::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362) CDS_NO_INFO /* no information available */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363) CDS_NO_DISC /* no disc is inserted, tray is closed */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) CDS_TRAY_OPEN /* tray is opened */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) CDS_DRIVE_NOT_READY /* something is wrong, tray is moving? */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366) CDS_DISC_OK /* a disc is loaded and everything is fine */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370) int tray_move(struct cdrom_device_info *cdi, int position)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372) This function, if implemented, should control the tray movement. (No
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373) other function should control this.) The parameter *position* controls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374) the desired direction of movement:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) - 0 Close tray
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377) - 1 Open tray
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379) This function returns 0 upon success, and a non-zero value upon
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380) error. Note that if the tray is already in the desired position, no
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381) action need be taken, and the return value should be 0.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385) int lock_door(struct cdrom_device_info *cdi, int lock)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387) This function (and no other code) controls locking of the door, if the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388) drive allows this. The value of *lock* controls the desired locking
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389) state:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391) - 0 Unlock door, manual opening is allowed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392) - 1 Lock door, tray cannot be ejected manually
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394) This function returns 0 upon success, and a non-zero value upon
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395) error. Note that if the door is already in the requested state, no
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396) action need be taken, and the return value should be 0.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400) int select_speed(struct cdrom_device_info *cdi, int speed)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402) Some CD-ROM drives are capable of changing their head-speed. There
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403) are several reasons for changing the speed of a CD-ROM drive. Badly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404) pressed CD-ROM s may benefit from less-than-maximum head rate. Modern
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405) CD-ROM drives can obtain very high head rates (up to *24x* is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406) common). It has been reported that these drives can make reading
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407) errors at these high speeds, reducing the speed can prevent data loss
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408) in these circumstances. Finally, some of these drives can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409) make an annoyingly loud noise, which a lower speed may reduce.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 411) This function specifies the speed at which data is read or audio is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 412) played back. The value of *speed* specifies the head-speed of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 413) drive, measured in units of standard cdrom speed (176kB/sec raw data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 414) or 150kB/sec file system data). So to request that a CD-ROM drive
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 415) operate at 300kB/sec you would call the CDROM_SELECT_SPEED *ioctl*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 416) with *speed=2*. The special value `0` means `auto-selection`, i. e.,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 417) maximum data-rate or real-time audio rate. If the drive doesn't have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 418) this `auto-selection` capability, the decision should be made on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 419) current disc loaded and the return value should be positive. A negative
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 420) return value indicates an error.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 421)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 422) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 423)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 424) int select_disc(struct cdrom_device_info *cdi, int number)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 425)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 426) If the drive can store multiple discs (a juke-box) this function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 427) will perform disc selection. It should return the number of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 428) selected disc on success, a negative value on error. Currently, only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 429) the ide-cd driver supports this functionality.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 430)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 431) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 432)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 433) int get_last_session(struct cdrom_device_info *cdi,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 434) struct cdrom_multisession *ms_info)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 435)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 436) This function should implement the old corresponding *ioctl()*. For
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 437) device *cdi->dev*, the start of the last session of the current disc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 438) should be returned in the pointer argument *ms_info*. Note that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 439) routines in `cdrom.c` have sanitized this argument: its requested
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 440) format will **always** be of the type *CDROM_LBA* (linear block
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 441) addressing mode), whatever the calling software requested. But
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 442) sanitization goes even further: the low-level implementation may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 443) return the requested information in *CDROM_MSF* format if it wishes so
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 444) (setting the *ms_info->addr_format* field appropriately, of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 445) course) and the routines in `cdrom.c` will make the transformation if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 446) necessary. The return value is 0 upon success.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 447)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 448) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 449)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 450) int get_mcn(struct cdrom_device_info *cdi,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 451) struct cdrom_mcn *mcn)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 452)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 453) Some discs carry a `Media Catalog Number` (MCN), also called
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 454) `Universal Product Code` (UPC). This number should reflect the number
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 455) that is generally found in the bar-code on the product. Unfortunately,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 456) the few discs that carry such a number on the disc don't even use the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 457) same format. The return argument to this function is a pointer to a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 458) pre-declared memory region of type *struct cdrom_mcn*. The MCN is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 459) expected as a 13-character string, terminated by a null-character.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 460)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 461) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 462)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 463) int reset(struct cdrom_device_info *cdi)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 464)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 465) This call should perform a hard-reset on the drive (although in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 466) circumstances that a hard-reset is necessary, a drive may very well not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 467) listen to commands anymore). Preferably, control is returned to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 468) caller only after the drive has finished resetting. If the drive is no
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 469) longer listening, it may be wise for the underlying low-level cdrom
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 470) driver to time out.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 471)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 472) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 473)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 474) int audio_ioctl(struct cdrom_device_info *cdi,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 475) unsigned int cmd, void *arg)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 476)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 477) Some of the CD-ROM-\ *ioctl()*\ 's defined in `cdrom.h` can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 478) implemented by the routines described above, and hence the function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 479) *cdrom_ioctl* will use those. However, most *ioctl()*\ 's deal with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 480) audio-control. We have decided to leave these to be accessed through a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 481) single function, repeating the arguments *cmd* and *arg*. Note that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 482) the latter is of type *void*, rather than *unsigned long int*.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 483) The routine *cdrom_ioctl()* does do some useful things,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 484) though. It sanitizes the address format type to *CDROM_MSF* (Minutes,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 485) Seconds, Frames) for all audio calls. It also verifies the memory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 486) location of *arg*, and reserves stack-memory for the argument. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 487) makes implementation of the *audio_ioctl()* much simpler than in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 488) old driver scheme. For example, you may look up the function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 489) *cm206_audio_ioctl()* `cm206.c` that should be updated with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 490) this documentation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 491)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 492) An unimplemented ioctl should return *-ENOSYS*, but a harmless request
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 493) (e. g., *CDROMSTART*) may be ignored by returning 0 (success). Other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 494) errors should be according to the standards, whatever they are. When
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 495) an error is returned by the low-level driver, the Uniform CD-ROM Driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 496) tries whenever possible to return the error code to the calling program.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 497) (We may decide to sanitize the return value in *cdrom_ioctl()* though, in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 498) order to guarantee a uniform interface to the audio-player software.)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 499)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 500) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 501)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 502) int dev_ioctl(struct cdrom_device_info *cdi,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 503) unsigned int cmd, unsigned long arg)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 504)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 505) Some *ioctl()'s* seem to be specific to certain CD-ROM drives. That is,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 506) they are introduced to service some capabilities of certain drives. In
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 507) fact, there are 6 different *ioctl()'s* for reading data, either in some
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 508) particular kind of format, or audio data. Not many drives support
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 509) reading audio tracks as data, I believe this is because of protection
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 510) of copyrights of artists. Moreover, I think that if audio-tracks are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 511) supported, it should be done through the VFS and not via *ioctl()'s*. A
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 512) problem here could be the fact that audio-frames are 2352 bytes long,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 513) so either the audio-file-system should ask for 75264 bytes at once
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 514) (the least common multiple of 512 and 2352), or the drivers should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 515) bend their backs to cope with this incoherence (to which I would be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 516) opposed). Furthermore, it is very difficult for the hardware to find
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 517) the exact frame boundaries, since there are no synchronization headers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 518) in audio frames. Once these issues are resolved, this code should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 519) standardized in `cdrom.c`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 520)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 521) Because there are so many *ioctl()'s* that seem to be introduced to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 522) satisfy certain drivers [#f2]_, any non-standard *ioctl()*\ s
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 523) are routed through the call *dev_ioctl()*. In principle, `private`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 524) *ioctl()*\ 's should be numbered after the device's major number, and not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 525) the general CD-ROM *ioctl* number, `0x53`. Currently the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 526) non-supported *ioctl()'s* are:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 527)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 528) CDROMREADMODE1, CDROMREADMODE2, CDROMREADAUDIO, CDROMREADRAW,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 529) CDROMREADCOOKED, CDROMSEEK, CDROMPLAY-BLK and CDROM-READALL
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 530)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 531) .. [#f2]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 532)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 533) Is there software around that actually uses these? I'd be interested!
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 534)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 535) .. _cdrom_capabilities:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 536)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 537) CD-ROM capabilities
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 538) -------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 539)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 540) Instead of just implementing some *ioctl* calls, the interface in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 541) `cdrom.c` supplies the possibility to indicate the **capabilities**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 542) of a CD-ROM drive. This can be done by ORing any number of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 543) capability-constants that are defined in `cdrom.h` at the registration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 544) phase. Currently, the capabilities are any of::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 545)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 546) CDC_CLOSE_TRAY /* can close tray by software control */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 547) CDC_OPEN_TRAY /* can open tray */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 548) CDC_LOCK /* can lock and unlock the door */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 549) CDC_SELECT_SPEED /* can select speed, in units of * sim*150 ,kB/s */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 550) CDC_SELECT_DISC /* drive is juke-box */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 551) CDC_MULTI_SESSION /* can read sessions *> rm1* */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 552) CDC_MCN /* can read Media Catalog Number */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 553) CDC_MEDIA_CHANGED /* can report if disc has changed */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 554) CDC_PLAY_AUDIO /* can perform audio-functions (play, pause, etc) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 555) CDC_RESET /* hard reset device */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 556) CDC_IOCTLS /* driver has non-standard ioctls */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 557) CDC_DRIVE_STATUS /* driver implements drive status */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 558)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 559) The capability flag is declared *const*, to prevent drivers from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 560) accidentally tampering with the contents. The capability flags actually
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 561) inform `cdrom.c` of what the driver can do. If the drive found
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 562) by the driver does not have the capability, is can be masked out by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 563) the *cdrom_device_info* variable *mask*. For instance, the SCSI CD-ROM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 564) driver has implemented the code for loading and ejecting CD-ROM's, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 565) hence its corresponding flags in *capability* will be set. But a SCSI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 566) CD-ROM drive might be a caddy system, which can't load the tray, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 567) hence for this drive the *cdrom_device_info* struct will have set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 568) the *CDC_CLOSE_TRAY* bit in *mask*.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 569)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 570) In the file `cdrom.c` you will encounter many constructions of the type::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 571)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 572) if (cdo->capability & ∼cdi->mask & CDC _⟨capability⟩) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 573)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 574) There is no *ioctl* to set the mask... The reason is that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 575) I think it is better to control the **behavior** rather than the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 576) **capabilities**.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 577)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 578) Options
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 579) -------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 580)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 581) A final flag register controls the **behavior** of the CD-ROM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 582) drives, in order to satisfy different users' wishes, hopefully
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 583) independently of the ideas of the respective author who happened to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 584) have made the drive's support available to the Linux community. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 585) current behavior options are::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 586)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 587) CDO_AUTO_CLOSE /* try to close tray upon device open() */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 588) CDO_AUTO_EJECT /* try to open tray on last device close() */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 589) CDO_USE_FFLAGS /* use file_pointer->f_flags to indicate purpose for open() */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 590) CDO_LOCK /* try to lock door if device is opened */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 591) CDO_CHECK_TYPE /* ensure disc type is data if opened for data */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 592)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 593) The initial value of this register is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 594) `CDO_AUTO_CLOSE | CDO_USE_FFLAGS | CDO_LOCK`, reflecting my own view on user
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 595) interface and software standards. Before you protest, there are two
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 596) new *ioctl()'s* implemented in `cdrom.c`, that allow you to control the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 597) behavior by software. These are::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 598)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 599) CDROM_SET_OPTIONS /* set options specified in (int)arg */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 600) CDROM_CLEAR_OPTIONS /* clear options specified in (int)arg */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 601)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 602) One option needs some more explanation: *CDO_USE_FFLAGS*. In the next
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 603) newsection we explain what the need for this option is.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 604)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 605) A software package `setcd`, available from the Debian distribution
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 606) and `sunsite.unc.edu`, allows user level control of these flags.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 607)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 608)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 609) The need to know the purpose of opening the CD-ROM device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 610) =========================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 611)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 612) Traditionally, Unix devices can be used in two different `modes`,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 613) either by reading/writing to the device file, or by issuing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 614) controlling commands to the device, by the device's *ioctl()*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 615) call. The problem with CD-ROM drives, is that they can be used for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 616) two entirely different purposes. One is to mount removable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 617) file systems, CD-ROM's, the other is to play audio CD's. Audio commands
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 618) are implemented entirely through *ioctl()\'s*, presumably because the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 619) first implementation (SUN?) has been such. In principle there is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 620) nothing wrong with this, but a good control of the `CD player` demands
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 621) that the device can **always** be opened in order to give the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 622) *ioctl* commands, regardless of the state the drive is in.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 623)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 624) On the other hand, when used as a removable-media disc drive (what the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 625) original purpose of CD-ROM s is) we would like to make sure that the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 626) disc drive is ready for operation upon opening the device. In the old
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 627) scheme, some CD-ROM drivers don't do any integrity checking, resulting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 628) in a number of i/o errors reported by the VFS to the kernel when an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 629) attempt for mounting a CD-ROM on an empty drive occurs. This is not a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 630) particularly elegant way to find out that there is no CD-ROM inserted;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 631) it more-or-less looks like the old IBM-PC trying to read an empty floppy
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 632) drive for a couple of seconds, after which the system complains it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 633) can't read from it. Nowadays we can **sense** the existence of a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 634) removable medium in a drive, and we believe we should exploit that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 635) fact. An integrity check on opening of the device, that verifies the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 636) availability of a CD-ROM and its correct type (data), would be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 637) desirable.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 638)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 639) These two ways of using a CD-ROM drive, principally for data and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 640) secondarily for playing audio discs, have different demands for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 641) behavior of the *open()* call. Audio use simply wants to open the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 642) device in order to get a file handle which is needed for issuing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 643) *ioctl* commands, while data use wants to open for correct and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 644) reliable data transfer. The only way user programs can indicate what
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 645) their *purpose* of opening the device is, is through the *flags*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 646) parameter (see `open(2)`). For CD-ROM devices, these flags aren't
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 647) implemented (some drivers implement checking for write-related flags,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 648) but this is not strictly necessary if the device file has correct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 649) permission flags). Most option flags simply don't make sense to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 650) CD-ROM devices: *O_CREAT*, *O_NOCTTY*, *O_TRUNC*, *O_APPEND*, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 651) *O_SYNC* have no meaning to a CD-ROM.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 652)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 653) We therefore propose to use the flag *O_NONBLOCK* to indicate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 654) that the device is opened just for issuing *ioctl*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 655) commands. Strictly, the meaning of *O_NONBLOCK* is that opening and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 656) subsequent calls to the device don't cause the calling process to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 657) wait. We could interpret this as don't wait until someone has
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 658) inserted some valid data-CD-ROM. Thus, our proposal of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 659) implementation for the *open()* call for CD-ROM s is:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 660)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 661) - If no other flags are set than *O_RDONLY*, the device is opened
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 662) for data transfer, and the return value will be 0 only upon successful
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 663) initialization of the transfer. The call may even induce some actions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 664) on the CD-ROM, such as closing the tray.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 665) - If the option flag *O_NONBLOCK* is set, opening will always be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 666) successful, unless the whole device doesn't exist. The drive will take
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 667) no actions whatsoever.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 668)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 669) And what about standards?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 670) -------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 671)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 672) You might hesitate to accept this proposal as it comes from the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 673) Linux community, and not from some standardizing institute. What
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 674) about SUN, SGI, HP and all those other Unix and hardware vendors?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 675) Well, these companies are in the lucky position that they generally
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 676) control both the hardware and software of their supported products,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 677) and are large enough to set their own standard. They do not have to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 678) deal with a dozen or more different, competing hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 679) configurations\ [#f3]_.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 680)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 681) .. [#f3]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 682)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 683) Incidentally, I think that SUN's approach to mounting CD-ROM s is very
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 684) good in origin: under Solaris a volume-daemon automatically mounts a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 685) newly inserted CD-ROM under `/cdrom/*<volume-name>*`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 686)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 687) In my opinion they should have pushed this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 688) further and have **every** CD-ROM on the local area network be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 689) mounted at the similar location, i. e., no matter in which particular
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 690) machine you insert a CD-ROM, it will always appear at the same
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 691) position in the directory tree, on every system. When I wanted to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 692) implement such a user-program for Linux, I came across the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 693) differences in behavior of the various drivers, and the need for an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 694) *ioctl* informing about media changes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 695)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 696) We believe that using *O_NONBLOCK* to indicate that a device is being opened
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 697) for *ioctl* commands only can be easily introduced in the Linux
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 698) community. All the CD-player authors will have to be informed, we can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 699) even send in our own patches to the programs. The use of *O_NONBLOCK*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 700) has most likely no influence on the behavior of the CD-players on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 701) other operating systems than Linux. Finally, a user can always revert
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 702) to old behavior by a call to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 703) *ioctl(file_descriptor, CDROM_CLEAR_OPTIONS, CDO_USE_FFLAGS)*.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 704)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 705) The preferred strategy of *open()*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 706) ----------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 707)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 708) The routines in `cdrom.c` are designed in such a way that run-time
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 709) configuration of the behavior of CD-ROM devices (of **any** type)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 710) can be carried out, by the *CDROM_SET/CLEAR_OPTIONS* *ioctls*. Thus, various
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 711) modes of operation can be set:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 712)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 713) `CDO_AUTO_CLOSE | CDO_USE_FFLAGS | CDO_LOCK`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 714) This is the default setting. (With *CDO_CHECK_TYPE* it will be better, in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 715) the future.) If the device is not yet opened by any other process, and if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 716) the device is being opened for data (*O_NONBLOCK* is not set) and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 717) tray is found to be open, an attempt to close the tray is made. Then,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 718) it is verified that a disc is in the drive and, if *CDO_CHECK_TYPE* is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 719) set, that it contains tracks of type `data mode 1`. Only if all tests
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 720) are passed is the return value zero. The door is locked to prevent file
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 721) system corruption. If the drive is opened for audio (*O_NONBLOCK* is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 722) set), no actions are taken and a value of 0 will be returned.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 723)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 724) `CDO_AUTO_CLOSE | CDO_AUTO_EJECT | CDO_LOCK`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 725) This mimics the behavior of the current sbpcd-driver. The option flags are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 726) ignored, the tray is closed on the first open, if necessary. Similarly,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 727) the tray is opened on the last release, i. e., if a CD-ROM is unmounted,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 728) it is automatically ejected, such that the user can replace it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 729)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 730) We hope that these option can convince everybody (both driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 731) maintainers and user program developers) to adopt the new CD-ROM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 732) driver scheme and option flag interpretation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 733)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 734) Description of routines in `cdrom.c`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 735) ====================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 736)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 737) Only a few routines in `cdrom.c` are exported to the drivers. In this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 738) new section we will discuss these, as well as the functions that `take
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 739) over` the CD-ROM interface to the kernel. The header file belonging
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 740) to `cdrom.c` is called `cdrom.h`. Formerly, some of the contents of this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 741) file were placed in the file `ucdrom.h`, but this file has now been
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 742) merged back into `cdrom.h`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 743)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 744) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 745)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 746) struct file_operations cdrom_fops
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 747)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 748) The contents of this structure were described in cdrom_api_.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 749) A pointer to this structure is assigned to the *fops* field
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 750) of the *struct gendisk*.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 751)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 752) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 753)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 754) int register_cdrom(struct cdrom_device_info *cdi)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 755)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 756) This function is used in about the same way one registers *cdrom_fops*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 757) with the kernel, the device operations and information structures,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 758) as described in cdrom_api_, should be registered with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 759) Uniform CD-ROM Driver::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 760)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 761) register_cdrom(&<device>_info);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 762)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 763)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 764) This function returns zero upon success, and non-zero upon
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 765) failure. The structure *<device>_info* should have a pointer to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 766) driver's *<device>_dops*, as in::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 767)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 768) struct cdrom_device_info <device>_info = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 769) <device>_dops;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 770) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 771) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 772)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 773) Note that a driver must have one static structure, *<device>_dops*, while
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 774) it may have as many structures *<device>_info* as there are minor devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 775) active. *Register_cdrom()* builds a linked list from these.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 776)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 777)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 778) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 779)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 780) void unregister_cdrom(struct cdrom_device_info *cdi)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 781)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 782) Unregistering device *cdi* with minor number *MINOR(cdi->dev)* removes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 783) the minor device from the list. If it was the last registered minor for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 784) the low-level driver, this disconnects the registered device-operation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 785) routines from the CD-ROM interface. This function returns zero upon
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 786) success, and non-zero upon failure.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 787)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 788) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 789)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 790) int cdrom_open(struct inode * ip, struct file * fp)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 791)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 792) This function is not called directly by the low-level drivers, it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 793) listed in the standard *cdrom_fops*. If the VFS opens a file, this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 794) function becomes active. A strategy is implemented in this routine,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 795) taking care of all capabilities and options that are set in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 796) *cdrom_device_ops* connected to the device. Then, the program flow is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 797) transferred to the device_dependent *open()* call.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 798)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 799) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 800)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 801) void cdrom_release(struct inode *ip, struct file *fp)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 802)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 803) This function implements the reverse-logic of *cdrom_open()*, and then
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 804) calls the device-dependent *release()* routine. When the use-count has
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 805) reached 0, the allocated buffers are flushed by calls to *sync_dev(dev)*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 806) and *invalidate_buffers(dev)*.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 807)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 808)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 809) .. _cdrom_ioctl:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 810)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 811) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 812)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 813) int cdrom_ioctl(struct inode *ip, struct file *fp,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 814) unsigned int cmd, unsigned long arg)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 815)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 816) This function handles all the standard *ioctl* requests for CD-ROM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 817) devices in a uniform way. The different calls fall into three
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 818) categories: *ioctl()'s* that can be directly implemented by device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 819) operations, ones that are routed through the call *audio_ioctl()*, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 820) the remaining ones, that are presumable device-dependent. Generally, a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 821) negative return value indicates an error.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 822)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 823) Directly implemented *ioctl()'s*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 824) --------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 825)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 826) The following `old` CD-ROM *ioctl()*\ 's are implemented by directly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 827) calling device-operations in *cdrom_device_ops*, if implemented and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 828) not masked:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 829)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 830) `CDROMMULTISESSION`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 831) Requests the last session on a CD-ROM.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 832) `CDROMEJECT`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 833) Open tray.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 834) `CDROMCLOSETRAY`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 835) Close tray.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 836) `CDROMEJECT_SW`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 837) If *arg\not=0*, set behavior to auto-close (close
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 838) tray on first open) and auto-eject (eject on last release), otherwise
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 839) set behavior to non-moving on *open()* and *release()* calls.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 840) `CDROM_GET_MCN`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 841) Get the Media Catalog Number from a CD.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 842)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 843) *Ioctl*s routed through *audio_ioctl()*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 844) ---------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 845)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 846) The following set of *ioctl()'s* are all implemented through a call to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 847) the *cdrom_fops* function *audio_ioctl()*. Memory checks and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 848) allocation are performed in *cdrom_ioctl()*, and also sanitization of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 849) address format (*CDROM_LBA*/*CDROM_MSF*) is done.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 850)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 851) `CDROMSUBCHNL`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 852) Get sub-channel data in argument *arg* of type
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 853) `struct cdrom_subchnl *`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 854) `CDROMREADTOCHDR`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 855) Read Table of Contents header, in *arg* of type
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 856) `struct cdrom_tochdr *`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 857) `CDROMREADTOCENTRY`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 858) Read a Table of Contents entry in *arg* and specified by *arg*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 859) of type `struct cdrom_tocentry *`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 860) `CDROMPLAYMSF`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 861) Play audio fragment specified in Minute, Second, Frame format,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 862) delimited by *arg* of type `struct cdrom_msf *`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 863) `CDROMPLAYTRKIND`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 864) Play audio fragment in track-index format delimited by *arg*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 865) of type `struct cdrom_ti *`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 866) `CDROMVOLCTRL`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 867) Set volume specified by *arg* of type `struct cdrom_volctrl *`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 868) `CDROMVOLREAD`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 869) Read volume into by *arg* of type `struct cdrom_volctrl *`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 870) `CDROMSTART`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 871) Spin up disc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 872) `CDROMSTOP`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 873) Stop playback of audio fragment.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 874) `CDROMPAUSE`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 875) Pause playback of audio fragment.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 876) `CDROMRESUME`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 877) Resume playing.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 878)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 879) New *ioctl()'s* in `cdrom.c`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 880) ----------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 881)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 882) The following *ioctl()'s* have been introduced to allow user programs to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 883) control the behavior of individual CD-ROM devices. New *ioctl*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 884) commands can be identified by the underscores in their names.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 885)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 886) `CDROM_SET_OPTIONS`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 887) Set options specified by *arg*. Returns the option flag register
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 888) after modification. Use *arg = \rm0* for reading the current flags.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 889) `CDROM_CLEAR_OPTIONS`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 890) Clear options specified by *arg*. Returns the option flag register
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 891) after modification.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 892) `CDROM_SELECT_SPEED`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 893) Select head-rate speed of disc specified as by *arg* in units
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 894) of standard cdrom speed (176\,kB/sec raw data or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 895) 150kB/sec file system data). The value 0 means `auto-select`,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 896) i. e., play audio discs at real time and data discs at maximum speed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 897) The value *arg* is checked against the maximum head rate of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 898) drive found in the *cdrom_dops*.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 899) `CDROM_SELECT_DISC`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 900) Select disc numbered *arg* from a juke-box.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 901)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 902) First disc is numbered 0. The number *arg* is checked against the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 903) maximum number of discs in the juke-box found in the *cdrom_dops*.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 904) `CDROM_MEDIA_CHANGED`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 905) Returns 1 if a disc has been changed since the last call.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 906) For juke-boxes, an extra argument *arg*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 907) specifies the slot for which the information is given. The special
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 908) value *CDSL_CURRENT* requests that information about the currently
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 909) selected slot be returned.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 910) `CDROM_DRIVE_STATUS`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 911) Returns the status of the drive by a call to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 912) *drive_status()*. Return values are defined in cdrom_drive_status_.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 913) Note that this call doesn't return information on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 914) current playing activity of the drive; this can be polled through
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 915) an *ioctl* call to *CDROMSUBCHNL*. For juke-boxes, an extra argument
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 916) *arg* specifies the slot for which (possibly limited) information is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 917) given. The special value *CDSL_CURRENT* requests that information
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 918) about the currently selected slot be returned.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 919) `CDROM_DISC_STATUS`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 920) Returns the type of the disc currently in the drive.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 921) It should be viewed as a complement to *CDROM_DRIVE_STATUS*.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 922) This *ioctl* can provide *some* information about the current
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 923) disc that is inserted in the drive. This functionality used to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 924) implemented in the low level drivers, but is now carried out
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 925) entirely in Uniform CD-ROM Driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 926)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 927) The history of development of the CD's use as a carrier medium for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 928) various digital information has lead to many different disc types.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 929) This *ioctl* is useful only in the case that CDs have \emph {only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 930) one} type of data on them. While this is often the case, it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 931) also very common for CDs to have some tracks with data, and some
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 932) tracks with audio. Because this is an existing interface, rather
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 933) than fixing this interface by changing the assumptions it was made
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 934) under, thereby breaking all user applications that use this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 935) function, the Uniform CD-ROM Driver implements this *ioctl* as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 936) follows: If the CD in question has audio tracks on it, and it has
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 937) absolutely no CD-I, XA, or data tracks on it, it will be reported
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 938) as *CDS_AUDIO*. If it has both audio and data tracks, it will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 939) return *CDS_MIXED*. If there are no audio tracks on the disc, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 940) if the CD in question has any CD-I tracks on it, it will be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 941) reported as *CDS_XA_2_2*. Failing that, if the CD in question
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 942) has any XA tracks on it, it will be reported as *CDS_XA_2_1*.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 943) Finally, if the CD in question has any data tracks on it,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 944) it will be reported as a data CD (*CDS_DATA_1*).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 945)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 946) This *ioctl* can return::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 947)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 948) CDS_NO_INFO /* no information available */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 949) CDS_NO_DISC /* no disc is inserted, or tray is opened */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 950) CDS_AUDIO /* Audio disc (2352 audio bytes/frame) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 951) CDS_DATA_1 /* data disc, mode 1 (2048 user bytes/frame) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 952) CDS_XA_2_1 /* mixed data (XA), mode 2, form 1 (2048 user bytes) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 953) CDS_XA_2_2 /* mixed data (XA), mode 2, form 1 (2324 user bytes) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 954) CDS_MIXED /* mixed audio/data disc */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 955)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 956) For some information concerning frame layout of the various disc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 957) types, see a recent version of `cdrom.h`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 958)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 959) `CDROM_CHANGER_NSLOTS`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 960) Returns the number of slots in a juke-box.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 961) `CDROMRESET`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 962) Reset the drive.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 963) `CDROM_GET_CAPABILITY`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 964) Returns the *capability* flags for the drive. Refer to section
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 965) cdrom_capabilities_ for more information on these flags.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 966) `CDROM_LOCKDOOR`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 967) Locks the door of the drive. `arg == 0` unlocks the door,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 968) any other value locks it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 969) `CDROM_DEBUG`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 970) Turns on debugging info. Only root is allowed to do this.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 971) Same semantics as CDROM_LOCKDOOR.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 972)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 973)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 974) Device dependent *ioctl()'s*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 975) ----------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 976)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 977) Finally, all other *ioctl()'s* are passed to the function *dev_ioctl()*,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 978) if implemented. No memory allocation or verification is carried out.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 979)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 980) How to update your driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 981) =========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 982)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 983) - Make a backup of your current driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 984) - Get hold of the files `cdrom.c` and `cdrom.h`, they should be in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 985) the directory tree that came with this documentation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 986) - Make sure you include `cdrom.h`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 987) - Change the 3rd argument of *register_blkdev* from `&<your-drive>_fops`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 988) to `&cdrom_fops`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 989) - Just after that line, add the following to register with the Uniform
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 990) CD-ROM Driver::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 991)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 992) register_cdrom(&<your-drive>_info);*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 993)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 994) Similarly, add a call to *unregister_cdrom()* at the appropriate place.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 995) - Copy an example of the device-operations *struct* to your
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 996) source, e. g., from `cm206.c` *cm206_dops*, and change all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 997) entries to names corresponding to your driver, or names you just
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 998) happen to like. If your driver doesn't support a certain function,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 999) make the entry *NULL*. At the entry *capability* you should list all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1000) capabilities your driver currently supports. If your driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1001) has a capability that is not listed, please send me a message.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1002) - Copy the *cdrom_device_info* declaration from the same example
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1003) driver, and modify the entries according to your needs. If your
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1004) driver dynamically determines the capabilities of the hardware, this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1005) structure should also be declared dynamically.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1006) - Implement all functions in your `<device>_dops` structure,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1007) according to prototypes listed in `cdrom.h`, and specifications given
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1008) in cdrom_api_. Most likely you have already implemented
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1009) the code in a large part, and you will almost certainly need to adapt the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1010) prototype and return values.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1011) - Rename your `<device>_ioctl()` function to *audio_ioctl* and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1012) change the prototype a little. Remove entries listed in the first
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1013) part in cdrom_ioctl_, if your code was OK, these are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1014) just calls to the routines you adapted in the previous step.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1015) - You may remove all remaining memory checking code in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1016) *audio_ioctl()* function that deals with audio commands (these are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1017) listed in the second part of cdrom_ioctl_. There is no
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1018) need for memory allocation either, so most *case*s in the *switch*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1019) statement look similar to::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1020)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1021) case CDROMREADTOCENTRY:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1022) get_toc_entry\bigl((struct cdrom_tocentry *) arg);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1023)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1024) - All remaining *ioctl* cases must be moved to a separate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1025) function, *<device>_ioctl*, the device-dependent *ioctl()'s*. Note that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1026) memory checking and allocation must be kept in this code!
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1027) - Change the prototypes of *<device>_open()* and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1028) *<device>_release()*, and remove any strategic code (i. e., tray
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1029) movement, door locking, etc.).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1030) - Try to recompile the drivers. We advise you to use modules, both
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1031) for `cdrom.o` and your driver, as debugging is much easier this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1032) way.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1033)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1034) Thanks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1035) ======
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1036)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1037) Thanks to all the people involved. First, Erik Andersen, who has
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1038) taken over the torch in maintaining `cdrom.c` and integrating much
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1039) CD-ROM-related code in the 2.1-kernel. Thanks to Scott Snyder and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1040) Gerd Knorr, who were the first to implement this interface for SCSI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1041) and IDE-CD drivers and added many ideas for extension of the data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1042) structures relative to kernel~2.0. Further thanks to Heiko Eißfeldt,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1043) Thomas Quinot, Jon Tombs, Ken Pizzini, Eberhard Mönkeberg and Andrew Kroll,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1044) the Linux CD-ROM device driver developers who were kind
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1045) enough to give suggestions and criticisms during the writing. Finally
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1046) of course, I want to thank Linus Torvalds for making this possible in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1047) the first place.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags