Lines Matching refs:the
34 \linux\ is probably the Unix-like operating system that supports
35 the widest variety of hardware devices. The reasons for this are
39 The large list of hardware devices available for the many platforms
42 The open design of the operating system, such that anybody can write a
47 The openness of \linux, and the many different types of available
49 Unfortunately, the very openness that has allowed \linux\ to support
50 all these different devices has also allowed the behavior of each
53 devices; the way a particular drive reacts to a `standard' $ioctl()$
55 their drivers totally inconsistent, the writers of \linux\ \cdrom\
58 maintain uniform behavior across all the \linux\ \cdrom\ drivers.
61 all the different \cdrom\ device drivers for \linux. This document also
62 defines the various $ioctl$s, and how the low-level \cdrom\ device
63 drivers should implement them. Currently (as of the \linux\ 2.1.$x$
67 When the \cdrom\ was developed, the interface between the \cdrom\ drive
68 and the computer was not specified in the standards. As a result, many
72 the functionality (CreativeLabs/SoundBlaster, Teac, Funai) or simply
73 adapted their drives to one or more of the already existing electrical
75 most of the `NoName' manufacturers). In cases where a new drive really
81 manufacturer will create a new interface. Even finding drives for the
84 When (in the 1.3.70's) I looked at the existing software interface,
87 kernel version I looked at, then, presumably 1.2.13 and 1.3.34---the
89 features of the software interface had been added to accommodate the
91 importantly, it appeared that the behavior of the `standard' commands
92 was different for most of the different drivers: \eg, some drivers
93 close the tray if an $open()$ call occurs when the tray is open, while
94 others do not. Some drivers lock the door upon opening the device, to
96 ejection. Undoubtedly, the capabilities of the different drives vary,
97 but even when two drives have the same capability their drivers'
100 I decided to start a discussion on how to make all the \linux\ \cdrom\
101 drivers behave more uniformly. I began by contacting the developers of
102 the many \cdrom\ drivers found in the \linux\ kernel. Their reactions
103 encouraged me to write the \UCD\ which this document is intended to
104 describe. The implementation of the \UCD\ is in the file \cdromc. This
106 of the low-level device drivers for each \cdrom\ drive. By adding this
107 additional layer, it is possible to have all the different \cdrom\
108 devices behave {\em exactly\/} the same (insofar as the underlying
111 The goal of the \UCD\ is {\em not\/} to alienate driver developers who
116 between the low-level device driver code and the \linux\ kernel. Care
117 is taken that 100\,\% compatibility exists with the data structures and
119 help \cdrom\ driver developers adapt their code to use the \UCD\ code
122 Personally, I think that the most important hardware interfaces are
123 the IDE/ATAPI drives and, of course, the SCSI drives, but as prices
126 that these drives behave in the same way. In December 1994, one of the
128 drive. In the months that I was busy writing a \linux\ driver for it,
129 proprietary drives became obsolete and IDE/ATAPI drives became the
130 standard. At the time of the last update to this document (November
137 At the time this document was conceived, all drivers directly
138 implemented the \cdrom\ $ioctl()$ calls through their own routines. This
139 led to the danger of different drivers forgetting to do important things
140 like checking that the user was giving the driver valid data. More
141 importantly, this led to the divergence of behavior, which has already
144 For this reason, the \UCD\ was created to enforce consistent \cdrom\
145 drive behavior, and to provide a common set of services to the various
147 software-level, that separates the $ioctl()$ and $open()$ implementation
148 from the actual hardware implementation. Note that this effort has
150 greatest change involved moving the contents of the various low-level
151 \cdrom\ drivers' header files to the kernel's cdrom directory. This was
152 done to help ensure that the user is only presented with only one cdrom
153 interface, the interface defined in \cdromh.
158 These operations are different from the classical block-device file
161 The routines for the \UCD\ interface level are implemented in the file
162 \cdromc. In this file, the \UCD\ interfaces with the kernel as a block
163 device by registering the following general $struct\ file_operations$:
185 declared above are all implemented in \cdromc, since this file is the
186 place where the behavior of all \cdrom-devices is defined and
187 standardized. The actual interface to the various types of \cdrom\
194 the general routines in \cdromc, not through the Virtual File System
196 through two general structures that contain information about the
197 capabilities of the driver, and the specific drives on which the
201 This structure contains information about the low-level driver for a
202 \cdrom\ device. This structure is conceptually connected to the major
203 number of the device (although some drivers may have different
204 major numbers, as is the case for the IDE driver).
208 connected to the minor number of the device.
211 Registering a particular \cdrom\ drive with the \UCD\ is done by the
215 The device information structure, $<device>_info$, contains all the
216 information needed for the kernel to interface with the low-level
217 \cdrom\ device driver. One of the most important entries in this
218 structure is a pointer to the $cdrom_device_ops$ structure of the
222 of pointers to the functions which are implemented in the low-level
224 through the functions in this structure. It is impossible to know all
225 the capabilities of future \cdrom\ drives, so it is expected that this
228 popular, and support will soon need to be added for them. For now, the
259 NULL instead. The $capability$ flags specify the capabilities of the
261 is registered with the \UCD. The value $n_minors$ should be a positive
262 value indicating the number of minor devices that are supported by
263 the low-level device driver, normally~1. Although these two variables
265 $cdrom_device_ops$ because they describe the capability of the {\em
266 driver\/} rather than the {\em drive}. Nomenclature has always been
270 $blkdev_fops$ counterparts. This is because very little of the
271 information in the structures $inode$ and $file$ is used. For most
272 drivers, the main parameter is the $struct$ $cdrom_device_info$, from
273 which the major and minor number can be extracted. (Most low-level
274 \cdrom\ drivers don't even look at the major and minor number though,
279 \cdromc, currently contains the following fields:
296 & char& name[20];& name of the device type\cr
299 Using this $struct$, a linked list of the registered minor devices is
300 built, using the $next$ field. The device number, the device operations
301 struct and specifications of properties of the drive are stored in this
304 The $mask$ flags can be used to mask out some of the capabilities listed
306 of the driver. The value $speed$ specifies the maximum head-rate of the
308 150\,kB/sec file system data). The value $n_discs$ should reflect the
309 number of discs the drive can hold simultaneously, if it is designed
311 because they describe properties of the drive, which don't change after
314 A few registers contain variables local to the \cdrom\ drive. The
315 flags $options$ are used to specify how the general \cdrom\ routines
317 flexibility to adapt to the different users' wishes (and {\em not\/} the
318 `arbitrary' wishes of the author of the low-level device driver, as is
319 the case in the old scheme). The register $mc_flags$ is used to buffer
320 the information from $media_changed()$ to two separate queues. Other
322 which can point to a data structure specific to the low-level driver.
327 additional bookkeeping. The use count of the device (the number of
328 processes that have the device opened) is registered in $use_count$. The
329 function $cdrom_ioctl()$ will verify the appropriate user-memory regions
330 for read and write, and in case a location on the CD is transferred,
331 it will `sanitize' the format by making requests to the low-level
332 drivers in a standard format, and translating all formats between the
333 user-software and low level drivers. This relieves much of the drivers'
334 memory checking and format checking and translation. Also, the necessary
335 structures will be declared on the program stack.
337 The implementation of the functions should be as defined in the
342 function call should return only after the command has completed, but of
343 course waiting for the device should not use processor time.
347 $Open()$ should try to open the device for a specific $purpose$, which
350 \item[0] Open for reading data, as done by {\tt {mount()}} (2), or the
356 done by the calling routine in \cdromc, so the low-level routine
358 up the disc, etc. % and device-use count
364 Device-specific actions should be taken such as spinning down the device.
365 However, strategic actions such as ejection of the tray, or unlocking
366 the door, should be left over to the general routine $cdrom_release()$.
367 This is the only function returning type $void$.
373 information on the status of the drive (not the status of the disc,
374 which may or may not be in the drive). If the drive is not a changer,
375 $slot_nr$ should be ignored. In \cdromh\ the possibilities are listed:
388 This function is very similar to the original function in $struct\
389 file_operations$. It returns 1 if the medium of the device $cdi\to
390 dev$ has changed since the last call, and 0 otherwise. The parameter
394 queues for the VFS and a new $ioctl()$ function that can report device
399 This function, if implemented, should control the tray movement. (No
401 the desired direction of movement:
407 error. Note that if the tray is already in the desired position, no
408 action need be taken, and the return value should be 0.
412 This function (and no other code) controls locking of the door, if the
413 drive allows this. The value of $lock$ controls the desired locking
420 error. Note that if the door is already in the requested state, no
421 action need be taken, and the return value should be 0.
426 are several reasons for changing the speed of a \cdrom\ drive. Badly
430 errors at these high speeds, reducing the speed can prevent data loss
433 %although the audio-low-pass filters probably aren't designed for it,
437 This function specifies the speed at which data is read or audio is
438 played back. The value of $speed$ specifies the head-speed of the
441 operate at 300\,kB/sec you would call the CDROM_SELECT_SPEED $ioctl$
443 maximum data-rate or real-time audio rate. If the drive doesn't have
444 this `auto-selection' capability, the decision should be made on the
445 current disc loaded and the return value should be positive. A negative
450 If the drive can store multiple discs (a juke-box) this function
451 will perform disc selection. It should return the number of the
453 the ide-cd driver supports this functionality.
458 This function should implement the old corresponding $ioctl()$. For
459 device $cdi\to dev$, the start of the last session of the current disc
460 should be returned in the pointer argument $ms_info$. Note that
462 format will {\em always\/} be of the type $CDROM_LBA$ (linear block
463 addressing mode), whatever the calling software requested. But
464 sanitization goes even further: the low-level implementation may
465 return the requested information in $CDROM_MSF$ format if it wishes so
466 (setting the $ms_info\rightarrow addr_format$ field appropriately, of
467 course) and the routines in \cdromc\ will make the transformation if
474 `Universal Product Code' (UPC). This number should reflect the number
475 that is generally found in the bar-code on the product. Unfortunately,
476 the few discs that carry such a number on the disc don't even use the
483 This call should perform a hard-reset on the drive (although in
485 listen to commands anymore). Preferably, control is returned to the
486 caller only after the drive has finished resetting. If the drive is no
487 longer listening, it may be wise for the underlying low-level cdrom
493 Some of the \cdrom-$ioctl$s defined in \cdromh\ can be
494 implemented by the routines described above, and hence the function
497 single function, repeating the arguments $cmd$ and $arg$. Note that
498 the latter is of type $void*{}$, rather than $unsigned\ long\
500 though. It sanitizes the address format type to $CDROM_MSF$ (Minutes,
501 Seconds, Frames) for all audio calls. It also verifies the memory
502 location of $arg$, and reserves stack-memory for the argument. This
503 makes implementation of the $audio_ioctl()$ much simpler than in the
504 old driver scheme. For example, you may look up the function
510 errors should be according to the standards, whatever they are. When
511 an error is returned by the low-level driver, the \UCD\ tries whenever
512 possible to return the error code to the calling program. (We may decide
513 to sanitize the return value in $cdrom_ioctl()$ though, in order to
514 guarantee a uniform interface to the audio-player software.)
525 supported, it should be done through the VFS and not via $ioctl$s. A
526 problem here could be the fact that audio-frames are 2352 bytes long,
527 so either the audio-file-system should ask for 75264 bytes at once
528 (the least common multiple of 512 and 2352), or the drivers should
530 opposed). Furthermore, it is very difficult for the hardware to find
531 the exact frame boundaries, since there are no synchronization headers
538 are routed through the call $dev_ioctl()$. In principle, `private'
539 $ioctl$s should be numbered after the device's major number, and not
540 the general \cdrom\ $ioctl$ number, {\tt {0x53}}. Currently the
549 Instead of just implementing some $ioctl$ calls, the interface in
550 \cdromc\ supplies the possibility to indicate the {\em capabilities\/}
552 capability-constants that are defined in \cdromh\ at the registration
553 phase. Currently, the capabilities are any of:
558 CDC_LOCK& can lock and unlock the door\cr
571 accidentally tampering with the contents. The capability fags actually
572 inform \cdromc\ of what the driver can do. If the drive found
573 by the driver does not have the capability, is can be masked out by
574 the $cdrom_device_info$ variable $mask$. For instance, the SCSI \cdrom\
575 driver has implemented the code for loading and ejecting \cdrom's, and
577 \cdrom\ drive might be a caddy system, which can't load the tray, and
578 hence for this drive the $cdrom_device_info$ struct will have set
579 the $CDC_CLOSE_TRAY$ bit in $mask$.
581 In the file \cdromc\ you will encounter many constructions of the type
586 There is no $ioctl$ to set the mask\dots The reason is that
587 I think it is better to control the {\em behavior\/} rather than the
592 A final flag register controls the {\em behavior\/} of the \cdrom\
594 independently of the ideas of the respective author who happened to
595 have made the drive's support available to the \linux\ community. The
611 new $ioctl$s implemented in \cdromc, that allow you to control the
619 One option needs some more explanation: $CDO_USE_FFLAGS$. In the next
620 newsection we explain what the need for this option is.
622 A software package {\tt setcd}, available from the Debian distribution
625 \newsection{The need to know the purpose of opening the \cdrom\ device}
628 either by reading/writing to the device file, or by issuing
629 controlling commands to the device, by the device's $ioctl()$
632 file systems, \cdrom s, the other is to play audio CD's. Audio commands
633 are implemented entirely through $ioctl$s, presumably because the
635 nothing wrong with this, but a good control of the `CD player' demands
636 that the device can {\em always\/} be opened in order to give the
637 $ioctl$ commands, regardless of the state the drive is in.
639 On the other hand, when used as a removable-media disc drive (what the
640 original purpose of \cdrom s is) we would like to make sure that the
641 disc drive is ready for operation upon opening the device. In the old
643 in a number of i/o errors reported by the VFS to the kernel when an
646 it more-or-less looks like the old IBM-PC trying to read an empty floppy
647 drive for a couple of seconds, after which the system complains it
648 can't read from it. Nowadays we can {\em sense\/} the existence of a
650 fact. An integrity check on opening of the device, that verifies the
655 secondarily for playing audio discs, have different demands for the
656 behavior of the $open()$ call. Audio use simply wants to open the
660 their {\em purpose\/} of opening the device is, is through the $flags$
663 but this is not strictly necessary if the device file has correct
668 We therefore propose to use the flag $O_NONBLOCK$ to indicate
669 that the device is opened just for issuing $ioctl$
670 commands. Strictly, the meaning of $O_NONBLOCK$ is that opening and
671 subsequent calls to the device don't cause the calling process to
673 inserted some valid data-\cdrom.'' Thus, our proposal of the
674 implementation for the $open()$ call for \cdrom s is:
676 \item If no other flags are set than $O_RDONLY$, the device is opened
677 for data transfer, and the return value will be 0 only upon successful
678 initialization of the transfer. The call may even induce some actions
679 on the \cdrom, such as closing the tray.
680 \item If the option flag $O_NONBLOCK$ is set, opening will always be
681 successful, unless the whole device doesn't exist. The drive will take
687 You might hesitate to accept this proposal as it comes from the
690 Well, these companies are in the lucky position that they generally
691 control both the hardware and software of their supported products,
698 further and have {\em every\/} \cdrom\ on the local area network be
699 mounted at the similar location, \ie, no matter in which particular
700 machine you insert a \cdrom, it will always appear at the same
701 position in the directory tree, on every system. When I wanted to
702 implement such a user-program for \linux, I came across the
703 differences in behavior of the various drivers, and the need for an
707 for $ioctl$ commands only can be easily introduced in the \linux\
708 community. All the CD-player authors will have to be informed, we can
709 even send in our own patches to the programs. The use of $O_NONBLOCK$
710 has most likely no influence on the behavior of the CD-players on
718 configuration of the behavior of \cdrom\ devices (of {\em any\/} type)
719 can be carried out, by the $CDROM_SET/CLEAR_OPTIONS$ $ioctls$. Thus, various
723 is the default setting. (With $CDO_CHECK_TYPE$ it will be better, in the
724 future.) If the device is not yet opened by any other process, and if
725 the device is being opened for data ($O_NONBLOCK$ is not set) and the
726 tray is found to be open, an attempt to close the tray is made. Then,
727 it is verified that a disc is in the drive and, if $CDO_CHECK_TYPE$ is
729 are passed is the return value zero. The door is locked to prevent file
730 system corruption. If the drive is opened for audio ($O_NONBLOCK$ is
733 mimics the behavior of the current sbpcd-driver. The option flags are
734 ignored, the tray is closed on the first open, if necessary. Similarly,
735 the tray is opened on the last release, \ie, if a \cdrom\ is unmounted,
736 it is automatically ejected, such that the user can replace it.
739 maintainers and user program developers) to adopt the new \cdrom\
744 Only a few routines in \cdromc\ are exported to the drivers. In this
745 new section we will discuss these, as well as the functions that `take
746 over' the \cdrom\ interface to the kernel. The header file belonging
747 to \cdromc\ is called \cdromh. Formerly, some of the contents of this
748 file were placed in the file {\tt {ucdrom.h}}, but this file has now been
754 A pointer to this structure is assigned to the $fops$ field
755 of the $struct gendisk$.
759 This function is used in about the same way one registers $cdrom_fops$
760 with the kernel, the device operations and information structures,
761 as described in section~\ref{cdrom.c}, should be registered with the
767 failure. The structure $<device>_info$ should have a pointer to the
783 the minor device from the list. If it was the last registered minor for
784 the low-level driver, this disconnects the registered device-operation
785 routines from the \cdrom\ interface. This function returns zero upon
790 This function is not called directly by the low-level drivers, it is
791 listed in the standard $cdrom_fops$. If the VFS opens a file, this
793 taking care of all capabilities and options that are set in the
794 $cdrom_device_ops$ connected to the device. Then, the program flow is
795 transferred to the device_dependent $open()$ call.
800 This function implements the reverse-logic of $cdrom_open()$, and then
801 calls the device-dependent $release()$ routine. When the use-count has
802 reached 0, the allocated buffers are flushed by calls to $sync_dev(dev)$
810 This function handles all the standard $ioctl$ requests for \cdrom\
813 operations, ones that are routed through the call $audio_ioctl()$, and
814 the remaining ones, that are presumable device-dependent. Generally, a
824 \item[CDROMMULTISESSION] Requests the last session on a \cdrom.
830 \item[CDROM_GET_MCN] Get the Media Catalog Number from a CD.
837 the $cdrom_fops$ function $audio_ioctl()$. Memory checks and
864 control the behavior of individual \cdrom\ devices. New $ioctl$
865 commands can be identified by the underscores in their names.
867 \item[CDROM_SET_OPTIONS] Set options specified by $arg$. Returns the
869 the current flags.
871 the option flag register after modification.
876 $arg$ is checked against the maximum head rate of the drive found in the
879 First disc is numbered 0. The number $arg$ is checked against the
880 maximum number of discs in the juke-box found in the $cdrom_dops$.
882 the last call. Note that calls to $cdrom_media_changed$ by the VFS
885 specifies the slot for which the information is given. The special
886 value $CDSL_CURRENT$ requests that information about the currently
888 \item[CDROM_DRIVE_STATUS] Returns the status of the drive by a call to
890 status}. Note that this call doesn't return information on the
891 current playing activity of the drive; this can be polled through an
893 $arg$ specifies the slot for which (possibly limited) information is
895 about the currently selected slot be returned.
896 \item[CDROM_DISC_STATUS] Returns the type of the disc currently in the
898 This $ioctl$ can provide \emph {some} information about the current
899 disc that is inserted in the drive. This functionality used to be
900 implemented in the low level drivers, but is now carried out
903 The history of development of the CD's use as a carrier medium for
905 This $ioctl$ is useful only in the case that CDs have \emph {only
906 one} type of data on them. While this is often the case, it is
909 than fixing this interface by changing the assumptions it was made
911 function, the \UCD\ implements this $ioctl$ as follows: If the CD in
915 are no audio tracks on the disc, and if the CD in question has any
917 that, if the CD in question has any XA tracks on it, it will be
918 reported as $CDS_XA_2_1$. Finally, if the CD in question has any
933 For some information concerning frame layout of the various disc
936 \item[CDROM_CHANGER_NSLOTS] Returns the number of slots in a
938 \item[CDROMRESET] Reset the drive.
939 \item[CDROM_GET_CAPABILITY] Returns the $capability$ flags for the
942 \item[CDROM_LOCKDOOR] Locks the door of the drive. $arg == \rm0$
943 unlocks the door, any other value locks it.
950 Finally, all other $ioctl$s are passed to the function $dev_ioctl()$,
957 \item Get hold of the files \cdromc\ and \cdromh, they should be in
958 the directory tree that came with this documentation.
960 \item Change the 3rd argument of $register_blkdev$ from
962 \item Just after that line, add the following to register with the \UCD:
964 Similarly, add a call to $unregister_cdrom()$ at the appropriate place.
965 \item Copy an example of the device-operations $struct$ to your
969 make the entry $NULL$. At the entry $capability$ you should list all
972 \item Copy the $cdrom_device_info$ declaration from the same example
973 driver, and modify the entries according to your needs. If your
974 driver dynamically determines the capabilities of the hardware, this
979 the code in a large part, and you will almost certainly need to adapt the
982 change the prototype a little. Remove entries listed in the first
984 just calls to the routines you adapted in the previous step.
985 \item You may remove all remaining memory checking code in the
987 listed in the second part of section~\ref{cdrom-ioctl}). There is no
988 need for memory allocation either, so most $case$s in the $switch$
995 function, $<device>_ioctl$, the device-dependent $ioctl$s. Note that
997 \item Change the prototypes of $<device>_open()$ and
1000 \item Try to recompile the drivers. We advise you to use modules, both
1007 Thanks to all the people involved. First, Erik Andersen, who has
1008 taken over the torch in maintaining \cdromc\ and integrating much
1009 \cdrom-related code in the 2.1-kernel. Thanks to Scott Snyder and
1010 Gerd Knorr, who were the first to implement this interface for SCSI
1011 and IDE-CD drivers and added many ideas for extension of the data
1014 Kroll, the \linux\ \cdrom\ device driver developers who were kind
1015 enough to give suggestions and criticisms during the writing. Finally
1017 the first place.