ia64/linux-2.6.18-xen.hg

view Documentation/ioctl/cdrom.txt @ 524:7f8b544237bf

netfront: Allow netfront in domain 0.

This is useful if your physical network device is in a utility domain.

Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
author Keir Fraser <keir.fraser@citrix.com>
date Tue Apr 15 15:18:58 2008 +0100 (2008-04-15)
parents 831230e53067
children
line source
1 Summary of CDROM ioctl calls.
2 ============================
4 Edward A. Falk <efalk@google.com>
6 November, 2004
8 This document attempts to describe the ioctl(2) calls supported by
9 the CDROM layer. These are by-and-large implemented (as of Linux 2.6)
10 in drivers/cdrom/cdrom.c and drivers/block/scsi_ioctl.c
12 ioctl values are listed in <linux/cdrom.h>. As of this writing, they
13 are as follows:
15 CDROMPAUSE Pause Audio Operation
16 CDROMRESUME Resume paused Audio Operation
17 CDROMPLAYMSF Play Audio MSF (struct cdrom_msf)
18 CDROMPLAYTRKIND Play Audio Track/index (struct cdrom_ti)
19 CDROMREADTOCHDR Read TOC header (struct cdrom_tochdr)
20 CDROMREADTOCENTRY Read TOC entry (struct cdrom_tocentry)
21 CDROMSTOP Stop the cdrom drive
22 CDROMSTART Start the cdrom drive
23 CDROMEJECT Ejects the cdrom media
24 CDROMVOLCTRL Control output volume (struct cdrom_volctrl)
25 CDROMSUBCHNL Read subchannel data (struct cdrom_subchnl)
26 CDROMREADMODE2 Read CDROM mode 2 data (2336 Bytes)
27 (struct cdrom_read)
28 CDROMREADMODE1 Read CDROM mode 1 data (2048 Bytes)
29 (struct cdrom_read)
30 CDROMREADAUDIO (struct cdrom_read_audio)
31 CDROMEJECT_SW enable(1)/disable(0) auto-ejecting
32 CDROMMULTISESSION Obtain the start-of-last-session
33 address of multi session disks
34 (struct cdrom_multisession)
35 CDROM_GET_MCN Obtain the "Universal Product Code"
36 if available (struct cdrom_mcn)
37 CDROM_GET_UPC Deprecated, use CDROM_GET_MCN instead.
38 CDROMRESET hard-reset the drive
39 CDROMVOLREAD Get the drive's volume setting
40 (struct cdrom_volctrl)
41 CDROMREADRAW read data in raw mode (2352 Bytes)
42 (struct cdrom_read)
43 CDROMREADCOOKED read data in cooked mode
44 CDROMSEEK seek msf address
45 CDROMPLAYBLK scsi-cd only, (struct cdrom_blk)
46 CDROMREADALL read all 2646 bytes
47 CDROMGETSPINDOWN return 4-bit spindown value
48 CDROMSETSPINDOWN set 4-bit spindown value
49 CDROMCLOSETRAY pendant of CDROMEJECT
50 CDROM_SET_OPTIONS Set behavior options
51 CDROM_CLEAR_OPTIONS Clear behavior options
52 CDROM_SELECT_SPEED Set the CD-ROM speed
53 CDROM_SELECT_DISC Select disc (for juke-boxes)
54 CDROM_MEDIA_CHANGED Check is media changed
55 CDROM_DRIVE_STATUS Get tray position, etc.
56 CDROM_DISC_STATUS Get disc type, etc.
57 CDROM_CHANGER_NSLOTS Get number of slots
58 CDROM_LOCKDOOR lock or unlock door
59 CDROM_DEBUG Turn debug messages on/off
60 CDROM_GET_CAPABILITY get capabilities
61 CDROMAUDIOBUFSIZ set the audio buffer size
62 DVD_READ_STRUCT Read structure
63 DVD_WRITE_STRUCT Write structure
64 DVD_AUTH Authentication
65 CDROM_SEND_PACKET send a packet to the drive
66 CDROM_NEXT_WRITABLE get next writable block
67 CDROM_LAST_WRITTEN get last block written on disc
70 The information that follows was determined from reading kernel source
71 code. It is likely that some corrections will be made over time.
79 General:
81 Unless otherwise specified, all ioctl calls return 0 on success
82 and -1 with errno set to an appropriate value on error. (Some
83 ioctls return non-negative data values.)
85 Unless otherwise specified, all ioctl calls return -1 and set
86 errno to EFAULT on a failed attempt to copy data to or from user
87 address space.
89 Individual drivers may return error codes not listed here.
91 Unless otherwise specified, all data structures and constants
92 are defined in <linux/cdrom.h>
97 CDROMPAUSE Pause Audio Operation
99 usage:
101 ioctl(fd, CDROMPAUSE, 0);
103 inputs: none
105 outputs: none
107 error return:
108 ENOSYS cd drive not audio-capable.
111 CDROMRESUME Resume paused Audio Operation
113 usage:
115 ioctl(fd, CDROMRESUME, 0);
117 inputs: none
119 outputs: none
121 error return:
122 ENOSYS cd drive not audio-capable.
125 CDROMPLAYMSF Play Audio MSF (struct cdrom_msf)
127 usage:
129 struct cdrom_msf msf;
130 ioctl(fd, CDROMPLAYMSF, &msf);
132 inputs:
133 cdrom_msf structure, describing a segment of music to play
135 outputs: none
137 error return:
138 ENOSYS cd drive not audio-capable.
140 notes:
141 MSF stands for minutes-seconds-frames
142 LBA stands for logical block address
144 Segment is described as start and end times, where each time
145 is described as minutes:seconds:frames. A frame is 1/75 of
146 a second.
149 CDROMPLAYTRKIND Play Audio Track/index (struct cdrom_ti)
151 usage:
153 struct cdrom_ti ti;
154 ioctl(fd, CDROMPLAYTRKIND, &ti);
156 inputs:
157 cdrom_ti structure, describing a segment of music to play
159 outputs: none
161 error return:
162 ENOSYS cd drive not audio-capable.
164 notes:
165 Segment is described as start and end times, where each time
166 is described as a track and an index.
170 CDROMREADTOCHDR Read TOC header (struct cdrom_tochdr)
172 usage:
174 cdrom_tochdr header;
175 ioctl(fd, CDROMREADTOCHDR, &header);
177 inputs:
178 cdrom_tochdr structure
180 outputs:
181 cdrom_tochdr structure
183 error return:
184 ENOSYS cd drive not audio-capable.
188 CDROMREADTOCENTRY Read TOC entry (struct cdrom_tocentry)
190 usage:
192 struct cdrom_tocentry entry;
193 ioctl(fd, CDROMREADTOCENTRY, &entry);
195 inputs:
196 cdrom_tocentry structure
198 outputs:
199 cdrom_tocentry structure
201 error return:
202 ENOSYS cd drive not audio-capable.
203 EINVAL entry.cdte_format not CDROM_MSF or CDROM_LBA
204 EINVAL requested track out of bounds
205 EIO I/O error reading TOC
207 notes:
208 TOC stands for Table Of Contents
209 MSF stands for minutes-seconds-frames
210 LBA stands for logical block address
214 CDROMSTOP Stop the cdrom drive
216 usage:
218 ioctl(fd, CDROMSTOP, 0);
220 inputs: none
222 outputs: none
224 error return:
225 ENOSYS cd drive not audio-capable.
227 notes:
228 Exact interpretation of this ioctl depends on the device,
229 but most seem to spin the drive down.
232 CDROMSTART Start the cdrom drive
234 usage:
236 ioctl(fd, CDROMSTART, 0);
238 inputs: none
240 outputs: none
242 error return:
243 ENOSYS cd drive not audio-capable.
245 notes:
246 Exact interpretation of this ioctl depends on the device,
247 but most seem to spin the drive up and/or close the tray.
248 Other devices ignore the ioctl completely.
251 CDROMEJECT Ejects the cdrom media
253 usage:
255 ioctl(fd, CDROMEJECT, 0);
257 inputs: none
259 outputs: none
261 error returns:
262 ENOSYS cd drive not capable of ejecting
263 EBUSY other processes are accessing drive, or door is locked
265 notes:
266 See CDROM_LOCKDOOR, below.
270 CDROMCLOSETRAY pendant of CDROMEJECT
272 usage:
274 ioctl(fd, CDROMEJECT, 0);
276 inputs: none
278 outputs: none
280 error returns:
281 ENOSYS cd drive not capable of ejecting
282 EBUSY other processes are accessing drive, or door is locked
284 notes:
285 See CDROM_LOCKDOOR, below.
289 CDROMVOLCTRL Control output volume (struct cdrom_volctrl)
291 usage:
293 struct cdrom_volctrl volume;
294 ioctl(fd, CDROMVOLCTRL, &volume);
296 inputs:
297 cdrom_volctrl structure containing volumes for up to 4
298 channels.
300 outputs: none
302 error return:
303 ENOSYS cd drive not audio-capable.
307 CDROMVOLREAD Get the drive's volume setting
308 (struct cdrom_volctrl)
310 usage:
312 struct cdrom_volctrl volume;
313 ioctl(fd, CDROMVOLREAD, &volume);
315 inputs: none
317 outputs:
318 The current volume settings.
320 error return:
321 ENOSYS cd drive not audio-capable.
325 CDROMSUBCHNL Read subchannel data (struct cdrom_subchnl)
327 usage:
329 struct cdrom_subchnl q;
330 ioctl(fd, CDROMSUBCHNL, &q);
332 inputs:
333 cdrom_subchnl structure
335 outputs:
336 cdrom_subchnl structure
338 error return:
339 ENOSYS cd drive not audio-capable.
340 EINVAL format not CDROM_MSF or CDROM_LBA
342 notes:
343 Format is converted to CDROM_MSF on return
347 CDROMREADRAW read data in raw mode (2352 Bytes)
348 (struct cdrom_read)
350 usage:
352 union {
353 struct cdrom_msf msf; /* input */
354 char buffer[CD_FRAMESIZE_RAW]; /* return */
355 } arg;
356 ioctl(fd, CDROMREADRAW, &arg);
358 inputs:
359 cdrom_msf structure indicating an address to read.
360 Only the start values are significant.
362 outputs:
363 Data written to address provided by user.
365 error return:
366 EINVAL address less than 0, or msf less than 0:2:0
367 ENOMEM out of memory
369 notes:
370 As of 2.6.8.1, comments in <linux/cdrom.h> indicate that this
371 ioctl accepts a cdrom_read structure, but actual source code
372 reads a cdrom_msf structure and writes a buffer of data to
373 the same address.
375 MSF values are converted to LBA values via this formula:
377 lba = (((m * CD_SECS) + s) * CD_FRAMES + f) - CD_MSF_OFFSET;
382 CDROMREADMODE1 Read CDROM mode 1 data (2048 Bytes)
383 (struct cdrom_read)
385 notes:
386 Identical to CDROMREADRAW except that block size is
387 CD_FRAMESIZE (2048) bytes
391 CDROMREADMODE2 Read CDROM mode 2 data (2336 Bytes)
392 (struct cdrom_read)
394 notes:
395 Identical to CDROMREADRAW except that block size is
396 CD_FRAMESIZE_RAW0 (2336) bytes
400 CDROMREADAUDIO (struct cdrom_read_audio)
402 usage:
404 struct cdrom_read_audio ra;
405 ioctl(fd, CDROMREADAUDIO, &ra);
407 inputs:
408 cdrom_read_audio structure containing read start
409 point and length
411 outputs:
412 audio data, returned to buffer indicated by ra
414 error return:
415 EINVAL format not CDROM_MSF or CDROM_LBA
416 EINVAL nframes not in range [1 75]
417 ENXIO drive has no queue (probably means invalid fd)
418 ENOMEM out of memory
421 CDROMEJECT_SW enable(1)/disable(0) auto-ejecting
423 usage:
425 int val;
426 ioctl(fd, CDROMEJECT_SW, val);
428 inputs:
429 Flag specifying auto-eject flag.
431 outputs: none
433 error return:
434 ENOSYS Drive is not capable of ejecting.
435 EBUSY Door is locked
440 CDROMMULTISESSION Obtain the start-of-last-session
441 address of multi session disks
442 (struct cdrom_multisession)
443 usage:
445 struct cdrom_multisession ms_info;
446 ioctl(fd, CDROMMULTISESSION, &ms_info);
448 inputs:
449 cdrom_multisession structure containing desired
450 format.
452 outputs:
453 cdrom_multisession structure is filled with last_session
454 information.
456 error return:
457 EINVAL format not CDROM_MSF or CDROM_LBA
460 CDROM_GET_MCN Obtain the "Universal Product Code"
461 if available (struct cdrom_mcn)
463 usage:
465 struct cdrom_mcn mcn;
466 ioctl(fd, CDROM_GET_MCN, &mcn);
468 inputs: none
470 outputs:
471 Universal Product Code
473 error return:
474 ENOSYS Drive is not capable of reading MCN data.
476 notes:
477 Source code comments state:
479 The following function is implemented, although very few
480 audio discs give Universal Product Code information, which
481 should just be the Medium Catalog Number on the box. Note,
482 that the way the code is written on the CD is /not/ uniform
483 across all discs!
488 CDROM_GET_UPC CDROM_GET_MCN (deprecated)
490 Not implemented, as of 2.6.8.1
494 CDROMRESET hard-reset the drive
496 usage:
498 ioctl(fd, CDROMRESET, 0);
500 inputs: none
502 outputs: none
504 error return:
505 EACCES Access denied: requires CAP_SYS_ADMIN
506 ENOSYS Drive is not capable of resetting.
511 CDROMREADCOOKED read data in cooked mode
513 usage:
515 u8 buffer[CD_FRAMESIZE]
516 ioctl(fd, CDROMREADCOOKED, buffer);
518 inputs: none
520 outputs:
521 2048 bytes of data, "cooked" mode.
523 notes:
524 Not implemented on all drives.
529 CDROMREADALL read all 2646 bytes
531 Same as CDROMREADCOOKED, but reads 2646 bytes.
535 CDROMSEEK seek msf address
537 usage:
539 struct cdrom_msf msf;
540 ioctl(fd, CDROMSEEK, &msf);
542 inputs:
543 MSF address to seek to.
545 outputs: none
549 CDROMPLAYBLK scsi-cd only, (struct cdrom_blk)
551 usage:
553 struct cdrom_blk blk;
554 ioctl(fd, CDROMPLAYBLK, &blk);
556 inputs:
557 Region to play
559 outputs: none
563 CDROMGETSPINDOWN
565 usage:
567 char spindown;
568 ioctl(fd, CDROMGETSPINDOWN, &spindown);
570 inputs: none
572 outputs:
573 The value of the current 4-bit spindown value.
578 CDROMSETSPINDOWN
580 usage:
582 char spindown
583 ioctl(fd, CDROMSETSPINDOWN, &spindown);
585 inputs:
586 4-bit value used to control spindown (TODO: more detail here)
588 outputs: none
594 CDROM_SET_OPTIONS Set behavior options
596 usage:
598 int options;
599 ioctl(fd, CDROM_SET_OPTIONS, options);
601 inputs:
602 New values for drive options. The logical 'or' of:
603 CDO_AUTO_CLOSE close tray on first open(2)
604 CDO_AUTO_EJECT open tray on last release
605 CDO_USE_FFLAGS use O_NONBLOCK information on open
606 CDO_LOCK lock tray on open files
607 CDO_CHECK_TYPE check type on open for data
609 outputs:
610 Returns the resulting options settings in the
611 ioctl return value. Returns -1 on error.
613 error return:
614 ENOSYS selected option(s) not supported by drive.
619 CDROM_CLEAR_OPTIONS Clear behavior options
621 Same as CDROM_SET_OPTIONS, except that selected options are
622 turned off.
626 CDROM_SELECT_SPEED Set the CD-ROM speed
628 usage:
630 int speed;
631 ioctl(fd, CDROM_SELECT_SPEED, speed);
633 inputs:
634 New drive speed.
636 outputs: none
638 error return:
639 ENOSYS speed selection not supported by drive.
643 CDROM_SELECT_DISC Select disc (for juke-boxes)
645 usage:
647 int disk;
648 ioctl(fd, CDROM_SELECT_DISC, disk);
650 inputs:
651 Disk to load into drive.
653 outputs: none
655 error return:
656 EINVAL Disk number beyond capacity of drive
660 CDROM_MEDIA_CHANGED Check is media changed
662 usage:
664 int slot;
665 ioctl(fd, CDROM_MEDIA_CHANGED, slot);
667 inputs:
668 Slot number to be tested, always zero except for jukeboxes.
669 May also be special values CDSL_NONE or CDSL_CURRENT
671 outputs:
672 Ioctl return value is 0 or 1 depending on whether the media
673 has been changed, or -1 on error.
675 error returns:
676 ENOSYS Drive can't detect media change
677 EINVAL Slot number beyond capacity of drive
678 ENOMEM Out of memory
682 CDROM_DRIVE_STATUS Get tray position, etc.
684 usage:
686 int slot;
687 ioctl(fd, CDROM_DRIVE_STATUS, slot);
689 inputs:
690 Slot number to be tested, always zero except for jukeboxes.
691 May also be special values CDSL_NONE or CDSL_CURRENT
693 outputs:
694 Ioctl return value will be one of the following values
695 from <linux/cdrom.h>:
697 CDS_NO_INFO Information not available.
698 CDS_NO_DISC
699 CDS_TRAY_OPEN
700 CDS_DRIVE_NOT_READY
701 CDS_DISC_OK
702 -1 error
704 error returns:
705 ENOSYS Drive can't detect drive status
706 EINVAL Slot number beyond capacity of drive
707 ENOMEM Out of memory
712 CDROM_DISC_STATUS Get disc type, etc.
714 usage:
716 ioctl(fd, CDROM_DISC_STATUS, 0);
718 inputs: none
720 outputs:
721 Ioctl return value will be one of the following values
722 from <linux/cdrom.h>:
723 CDS_NO_INFO
724 CDS_AUDIO
725 CDS_MIXED
726 CDS_XA_2_2
727 CDS_XA_2_1
728 CDS_DATA_1
730 error returns: none at present
732 notes:
733 Source code comments state:
735 Ok, this is where problems start. The current interface for
736 the CDROM_DISC_STATUS ioctl is flawed. It makes the false
737 assumption that CDs are all CDS_DATA_1 or all CDS_AUDIO, etc.
738 Unfortunatly, while this is often the case, it is also
739 very common for CDs to have some tracks with data, and some
740 tracks with audio. Just because I feel like it, I declare
741 the following to be the best way to cope. If the CD has
742 ANY data tracks on it, it will be returned as a data CD.
743 If it has any XA tracks, I will return it as that. Now I
744 could simplify this interface by combining these returns with
745 the above, but this more clearly demonstrates the problem
746 with the current interface. Too bad this wasn't designed
747 to use bitmasks... -Erik
749 Well, now we have the option CDS_MIXED: a mixed-type CD.
750 User level programmers might feel the ioctl is not very
751 useful.
752 ---david
757 CDROM_CHANGER_NSLOTS Get number of slots
759 usage:
761 ioctl(fd, CDROM_CHANGER_NSLOTS, 0);
763 inputs: none
765 outputs:
766 The ioctl return value will be the number of slots in a
767 CD changer. Typically 1 for non-multi-disk devices.
769 error returns: none
773 CDROM_LOCKDOOR lock or unlock door
775 usage:
777 int lock;
778 ioctl(fd, CDROM_LOCKDOOR, lock);
780 inputs:
781 Door lock flag, 1=lock, 0=unlock
783 outputs: none
785 error returns:
786 EDRIVE_CANT_DO_THIS Door lock function not supported.
787 EBUSY Attempt to unlock when multiple users
788 have the drive open and not CAP_SYS_ADMIN
790 notes:
791 As of 2.6.8.1, the lock flag is a global lock, meaning that
792 all CD drives will be locked or unlocked together. This is
793 probably a bug.
795 The EDRIVE_CANT_DO_THIS value is defined in <linux/cdrom.h>
796 and is currently (2.6.8.1) the same as EOPNOTSUPP
800 CDROM_DEBUG Turn debug messages on/off
802 usage:
804 int debug;
805 ioctl(fd, CDROM_DEBUG, debug);
807 inputs:
808 Cdrom debug flag, 0=disable, 1=enable
810 outputs:
811 The ioctl return value will be the new debug flag.
813 error return:
814 EACCES Access denied: requires CAP_SYS_ADMIN
818 CDROM_GET_CAPABILITY get capabilities
820 usage:
822 ioctl(fd, CDROM_GET_CAPABILITY, 0);
824 inputs: none
826 outputs:
827 The ioctl return value is the current device capability
828 flags. See CDC_CLOSE_TRAY, CDC_OPEN_TRAY, etc.
832 CDROMAUDIOBUFSIZ set the audio buffer size
834 usage:
836 int arg;
837 ioctl(fd, CDROMAUDIOBUFSIZ, val);
839 inputs:
840 New audio buffer size
842 outputs:
843 The ioctl return value is the new audio buffer size, or -1
844 on error.
846 error return:
847 ENOSYS Not supported by this driver.
849 notes:
850 Not supported by all drivers.
854 DVD_READ_STRUCT Read structure
856 usage:
858 dvd_struct s;
859 ioctl(fd, DVD_READ_STRUCT, &s);
861 inputs:
862 dvd_struct structure, containing:
863 type specifies the information desired, one of
864 DVD_STRUCT_PHYSICAL, DVD_STRUCT_COPYRIGHT,
865 DVD_STRUCT_DISCKEY, DVD_STRUCT_BCA,
866 DVD_STRUCT_MANUFACT
867 physical.layer_num desired layer, indexed from 0
868 copyright.layer_num desired layer, indexed from 0
869 disckey.agid
871 outputs:
872 dvd_struct structure, containing:
873 physical for type == DVD_STRUCT_PHYSICAL
874 copyright for type == DVD_STRUCT_COPYRIGHT
875 disckey.value for type == DVD_STRUCT_DISCKEY
876 bca.{len,value} for type == DVD_STRUCT_BCA
877 manufact.{len,valu} for type == DVD_STRUCT_MANUFACT
879 error returns:
880 EINVAL physical.layer_num exceeds number of layers
881 EIO Received invalid response from drive
885 DVD_WRITE_STRUCT Write structure
887 Not implemented, as of 2.6.8.1
891 DVD_AUTH Authentication
893 usage:
895 dvd_authinfo ai;
896 ioctl(fd, DVD_AUTH, &ai);
898 inputs:
899 dvd_authinfo structure. See <linux/cdrom.h>
901 outputs:
902 dvd_authinfo structure.
904 error return:
905 ENOTTY ai.type not recognized.
909 CDROM_SEND_PACKET send a packet to the drive
911 usage:
913 struct cdrom_generic_command cgc;
914 ioctl(fd, CDROM_SEND_PACKET, &cgc);
916 inputs:
917 cdrom_generic_command structure containing the packet to send.
919 outputs: none
920 cdrom_generic_command structure containing results.
922 error return:
923 EIO command failed.
924 EPERM Operation not permitted, either because a
925 write command was attempted on a drive which
926 is opened read-only, or because the command
927 requires CAP_SYS_RAWIO
928 EINVAL cgc.data_direction not set
932 CDROM_NEXT_WRITABLE get next writable block
934 usage:
936 long next;
937 ioctl(fd, CDROM_NEXT_WRITABLE, &next);
939 inputs: none
941 outputs:
942 The next writable block.
944 notes:
945 If the device does not support this ioctl directly, the
946 ioctl will return CDROM_LAST_WRITTEN + 7.
950 CDROM_LAST_WRITTEN get last block written on disc
952 usage:
954 long last;
955 ioctl(fd, CDROM_LAST_WRITTEN, &last);
957 inputs: none
959 outputs:
960 The last block written on disc
962 notes:
963 If the device does not support this ioctl directly, the
964 result is derived from the disc's table of contents. If the
965 table of contents can't be read, this ioctl returns an
966 error.