diff options
| author | Linus Torvalds <torvalds@ppc970.osdl.org> | 2005-04-16 15:20:36 -0700 |
|---|---|---|
| committer | Linus Torvalds <torvalds@ppc970.osdl.org> | 2005-04-16 15:20:36 -0700 |
| commit | 1da177e4c3f41524e886b7f1b8a0c1fc7321cac2 (patch) | |
| tree | 0bba044c4ce775e45a88a51686b5d9f90697ea9d /Documentation/cdrom | |
| download | linux-stable-1da177e4c3f41524e886b7f1b8a0c1fc7321cac2.tar.gz linux-stable-1da177e4c3f41524e886b7f1b8a0c1fc7321cac2.tar.bz2 linux-stable-1da177e4c3f41524e886b7f1b8a0c1fc7321cac2.zip | |
Linux-2.6.12-rc2v2.6.12-rc2
Initial git repository build. I'm not bothering with the full history,
even though we have it. We can create a separate "historical" git
archive of that later if we want to, and in the meantime it's about
3.2GB when imported into git - space that would just make the early
git days unnecessarily complicated, when we don't have a lot of good
infrastructure for it.
Let it rip!
Diffstat (limited to 'Documentation/cdrom')
| -rw-r--r-- | Documentation/cdrom/00-INDEX | 33 | ||||
| -rw-r--r-- | Documentation/cdrom/Makefile | 21 | ||||
| -rw-r--r-- | Documentation/cdrom/aztcd | 822 | ||||
| -rw-r--r-- | Documentation/cdrom/cdrom-standard.tex | 1022 | ||||
| -rw-r--r-- | Documentation/cdrom/cdu31a | 196 | ||||
| -rw-r--r-- | Documentation/cdrom/cm206 | 185 | ||||
| -rw-r--r-- | Documentation/cdrom/gscd | 60 | ||||
| -rw-r--r-- | Documentation/cdrom/ide-cd | 574 | ||||
| -rw-r--r-- | Documentation/cdrom/isp16 | 100 | ||||
| -rw-r--r-- | Documentation/cdrom/mcdx | 29 | ||||
| -rw-r--r-- | Documentation/cdrom/optcd | 57 | ||||
| -rw-r--r-- | Documentation/cdrom/packet-writing.txt | 97 | ||||
| -rw-r--r-- | Documentation/cdrom/sbpcd | 1057 | ||||
| -rw-r--r-- | Documentation/cdrom/sjcd | 60 | ||||
| -rw-r--r-- | Documentation/cdrom/sonycd535 | 121 |
15 files changed, 4434 insertions, 0 deletions
diff --git a/Documentation/cdrom/00-INDEX b/Documentation/cdrom/00-INDEX new file mode 100644 index 000000000000..916dafe29d3f --- /dev/null +++ b/Documentation/cdrom/00-INDEX @@ -0,0 +1,33 @@ +00-INDEX + - this file (info on CD-ROMs and Linux) +Makefile + - only used to generate TeX output from the documentation. +aztcd + - info on Aztech/Orchid/Okano/Wearnes/Conrad/CyCDROM driver. +cdrom-standard.tex + - LaTeX document on standardizing the CD-ROM programming interface. +cdu31a + - info on the Sony CDU31A/CDU33A CD-ROM driver. +cm206 + - info on the Philips/LMS cm206/cm260 CD-ROM driver. +gscd + - info on the Goldstar R420 CD-ROM driver. +ide-cd + - info on setting up and using ATAPI (aka IDE) CD-ROMs. +isp16 + - info on the CD-ROM interface on ISP16, MAD16 or Mozart sound card. +mcd + - info on limitations of standard Mitsumi CD-ROM driver. +mcdx + - info on improved Mitsumi CD-ROM driver. +optcd + - info on the Optics Storage 8000 AT CD-ROM driver +packet-writing.txt + - Info on the CDRW packet writing module +sbpcd + - info on the SoundBlaster/Panasonic CD-ROM interface driver. +sjcd + - info on the SANYO CDR-H94A CD-ROM interface driver. +sonycd535 + - info on the Sony CDU-535 (and 531) CD-ROM driver. + diff --git a/Documentation/cdrom/Makefile b/Documentation/cdrom/Makefile new file mode 100644 index 000000000000..a19e321928e1 --- /dev/null +++ b/Documentation/cdrom/Makefile @@ -0,0 +1,21 @@ +LATEXFILE = cdrom-standard + +all: + make clean + latex $(LATEXFILE) + latex $(LATEXFILE) + @if [ -x `which gv` ]; then \ + `dvips -q -t letter -o $(LATEXFILE).ps $(LATEXFILE).dvi` ;\ + `gv -antialias -media letter -nocenter $(LATEXFILE).ps` ;\ + else \ + `xdvi $(LATEXFILE).dvi &` ;\ + fi + make sortofclean + +clean: + rm -f $(LATEXFILE).ps $(LATEXFILE).dvi $(LATEXFILE).aux $(LATEXFILE).log + +sortofclean: + rm -f $(LATEXFILE).aux $(LATEXFILE).log + + diff --git a/Documentation/cdrom/aztcd b/Documentation/cdrom/aztcd new file mode 100644 index 000000000000..6bf0290ef7ce --- /dev/null +++ b/Documentation/cdrom/aztcd @@ -0,0 +1,822 @@ +$Id: README.aztcd,v 2.60 1997/11/29 09:51:25 root Exp root $ + Readme-File Documentation/cdrom/aztcd + for + AZTECH CD-ROM CDA268-01A, ORCHID CD-3110, + OKANO/WEARNES CDD110, CONRAD TXC, CyCDROM CR520, CR540 + CD-ROM Drives + Version 2.6 and newer + (for other drives see 6.-8.) + +NOTE: THIS DRIVER WILL WORK WITH THE CD-ROM DRIVES LISTED, WHICH HAVE + A PROPRIETARY INTERFACE (implemented on a sound card or on an + ISA-AT-bus card). + IT WILL DEFINITELY NOT WORK WITH CD-ROM DRIVES WITH *IDE*-INTERFACE, + such as the Aztech CDA269-031SE !!! (The only known exceptions are + 'faked' IDE drives like the CyCDROM CR520ie which work with aztcd + under certain conditions, see 7.). IF YOU'RE USING A CD-ROM DRIVE + WITH IDE-INTERFACE, SOMETIMES ALSO CALLED ATAPI-COMPATIBLE, PLEASE + USE THE ide-cd.c DRIVER, WRITTEN BY MARK LORD AND SCOTT SNYDER ! + THE STANDARD-KERNEL 1.2.x NOW ALSO SUPPORTS IDE-CDROM-DRIVES, SEE THE + HARDDISK (!) SECTION OF make config, WHEN COMPILING A NEW KERNEL!!! +---------------------------------------------------------------------------- + +Contents of this file: + 1. NOTE + 2. INSTALLATION + 3. CONFIGURING YOUR KERNEL + 4. RECOMPILING YOUR KERNEL + 4.1 AZTCD AS A RUN-TIME LOADABLE MODULE + 4.2 CDROM CONNECTED TO A SOUNDCARD + 5. KNOWN PROBLEMS, FUTURE DEVELOPMENTS + 5.1 MULTISESSION SUPPORT + 5.2 STATUS RECOGNITION + 5.3 DOSEMU's CDROM SUPPORT + 6. BUG REPORTS + 7. OTHER DRIVES + 8. IF YOU DON'T SUCCEED ... DEBUGGING + 9. TECHNICAL HISTORY OF THE DRIVER + 10. ACKNOWLEDGMENTS + 11. PROGRAMMING ADD ONS: CDPLAY.C + APPENDIX: Source code of cdplay.c +---------------------------------------------------------------------------- + +1. NOTE +This software has been successfully in alpha and beta test and is part of +the standard kernel since kernel 1.1.8x since December 1994. It works with +AZTECH CDA268-01A, ORCHID CDS-3110, ORCHID/WEARNES CDD110 and CONRAD TXC +(Nr.99 31 23 -series 04) and has proven to be stable with kernel +versions 1.0.9 and newer. But with any software there still may be bugs in it. +So if you encounter problems, you are invited to help us improve this software. +Please send me a detailed bug report (see chapter BUG REPORTS). You are also +invited in helping us to increase the number of drives, which are supported. + +Please read the README-files carefully and always keep a backup copy of your +old kernel, in order to reboot if something goes wrong! + +2. INSTALLATION +The driver consists of a header file 'aztcd.h', which normally should reside +in /usr/src/linux/drivers/cdrom and the source code 'aztcd.c', which normally +resides in the same place. It uses /dev/aztcd (/dev/aztcd0 in some distri- +butions), which must be a valid block device with major number 29 and reside +in directory /dev. To mount a CD-ROM, your kernel needs to have the ISO9660- +filesystem support included. + +PLEASE NOTE: aztcd.c has been developed in parallel to the linux kernel, +which had and is having many major and minor changes which are not backward +compatible. Quite definitely aztcd.c version 1.80 and newer will NOT work +in kernels older than 1.3.33. So please always use the most recent version +of aztcd.c with the appropriate linux-kernel. + +3. CONFIGURING YOUR KERNEL +If your kernel is already configured for using the AZTECH driver you will +see the following message while Linux boots: + Aztech CD-ROM Init: DriverVersion=<version number> BaseAddress=<baseaddress> + Aztech CD-ROM Init: FirmwareVersion=<firmware version id of your I/O-card>>> + Aztech CD-ROM Init: <drive type> detected + Aztech CD-ROM Init: End +If the message looks different and you are sure to have a supported drive, +it may have a different base address. The Aztech driver does look for the +CD-ROM drive at the base address specified in aztcd.h at compile time. This +address can be overwritten by boot parameter aztcd=....You should reboot and +start Linux with boot parameter aztcd=<base address>, e.g. aztcd=0x320. If +you do not know the base address, start your PC with DOS and look at the boot +message of your CD-ROM's DOS driver. If that still does not help, use boot +parameter aztcd=<base address>,0x79 , this tells aztcd to try a little harder. +aztcd may be configured to use autoprobing the base address by recompiling +it (see chapter 4.). + +If the message looks correct, as user 'root' you should be able to mount the +drive by + mount -t iso9660 -r /dev/aztcd0 /mnt +and use it as any other filesystem. (If this does not work, check if +/dev/aztcd0 and /mnt do exist and create them, if necessary by doing + mknod /dev/aztcd0 b 29 0 + mkdir /mnt + +If you still get a different message while Linux boots or when you get the +message, that the ISO9660-filesystem is not supported by your kernel, when +you try to mount the CD-ROM drive, you have to recompile your kernel. + +If you do *not* have an Aztech/Orchid/Okano/Wearnes/TXC drive and want to +bypass drive detection during Linux boot up, start with boot parameter aztcd=0. + +Most distributions nowadays do contain a boot disk image containing aztcd. +Please note, that this driver will not work with IDE/ATAPI drives! With these +you must use ide-cd.c instead. + +4. RECOMPILING YOUR KERNEL +If your kernel is not yet configured for the AZTECH driver and the ISO9660- +filesystem, you have to recompile your kernel: + +- Edit aztcd.h to set the I/O-address to your I/O-Base address (AZT_BASE_ADDR), + the driver does not use interrupts or DMA, so if you are using an AZTECH + CD268, an ORCHID CD-3110 or ORCHID/WEARNES CDD110 that's the only item you + have to set up. If you have a soundcard, read chapter 4.2. + Users of other drives should read chapter OTHER DRIVES of this file. + You also can configure that address by kernel boot parameter aztcd=... +- aztcd may be configured to use autoprobing the base address by setting + AZT_BASE_ADDR to '-1'. In that case aztcd probes the addresses listed + under AZT_BASE_AUTO. But please remember, that autoprobing always may + incorrectly influence other hardware components too! +- There are some other points, which may be configured, e.g. auto-eject the + CD when unmounting a drive, tray locking etc., see aztcd.h for details. +- If you're using a linux kernel version prior to 2.1.0, in aztcd.h + uncomment the line '#define AZT_KERNEL_PRIOR_2_1' +- Build a new kernel, configure it for 'Aztech/Orchid/Okano/Wearnes support' + (if you want aztcd to be part of the kernel). Do not configure it for + 'Aztech... support', if you want to use aztcd as a run time loadable module. + But in any case you must have the ISO9660-filesystem included in your + kernel. +- Activate the new kernel, normally this is done by running LILO (don't for- + get to configure it before and to keep a copy of your old kernel in case + something goes wrong!). +- Reboot +- If you've included aztcd in your kernel, you now should see during boot + some messages like + Aztech CD-ROM Init: DriverVersion=<version number> BaseAddress=<baseaddress> + Aztech CD-ROM Init: FirmwareVersion=<firmware version id of your I/O-card> + Aztech CD-ROM Init: <drive type> detected + Aztech CD-ROM Init: End +- If you have not included aztcd in your kernel, but want to load aztcd as a + run time loadable module see 4.1. +- If the message looks correct, as user 'root' you should be able to mount + the drive by + mount -t iso9660 -r /dev/aztcd0 /mnt + and use it as any other filesystem. (If this does not work, check if + /dev/aztcd0 and /mnt do exist and create them, if necessary by doing + mknod /dev/aztcd0 b 29 0 + mkdir /mnt +- If this still does not help, see chapters OTHER DRIVES and DEBUGGING. + +4.1 AZTCD AS A RUN-TIME LOADABLE MODULE +If you do not need aztcd permanently, you can also load and remove the driver +during runtime via insmod and rmmod. To build aztcd as a loadable module you +must configure your kernel for AZTECH module support (answer 'm' when con- +figuring the kernel). Anyhow, you may run into problems, if the version of +your boot kernel is not the same than the source kernel version, from which +you create the modules. So rebuild your kernel, if necessary. + +Now edit the base address of your AZTECH interface card in +/usr/src/linux/drivers/cdrom/aztcd.h to the appropriate value. +aztcd may be configured to use autoprobing the base address by setting +AZT_BASE_ADDR to '-1'. In that case aztcd probes the addresses listed +under AZT_BASE_AUTO. But please remember, that autoprobing always may +incorrectly influence other hardware components too! +There are also some special features which may be configured, e.g. +auto-eject a CD when unmounting the drive etc; see aztcd.h for details. +Then change to /usr/src/linux and do a + make modules + make modules_install +After that you can run-time load the driver via + insmod /lib/modules/X.X.X/misc/aztcd.o +and remove it via rmmod aztcd. +If you did not set the correct base address in aztcd.h, you can also supply the +base address when loading the driver via + insmod /lib/modules/X.X.X/misc/aztcd.o aztcd=<base address> +Again specifying aztcd=-1 will cause autoprobing. +If you do not have the iso9660-filesystem in your boot kernel, you also have +to load it before you can mount the CDROM: + insmod /lib/modules/X.X.X/fs/isofs.o +The mount procedure works as described in 4. above. +(In all commands 'X.X.X' is the current linux kernel version number) + +4.2 CDROM CONNECTED TO A SOUNDCARD +Most soundcards do have a bus interface to the CDROM-drive. In many cases +this soundcard needs to be configured, before the CDROM can be used. This +configuration procedure consists of writing some kind of initialization +data to the soundcard registers. The AZTECH-CDROM driver in the moment does +only support one type of soundcard (SoundWave32). Users of other soundcards +should try to boot DOS first and let their DOS drivers initialize the +soundcard and CDROM, then warm boot (or use loadlin) their PC to start +Linux. +Support for the CDROM-interface of SoundWave32-soundcards is directly +implemented in the AZTECH driver. Please edit linux/drivers/cdrom/aztdc.h, +uncomment line '#define AZT_SW32' and set the appropriate value for +AZT_BASE_ADDR and AZT_SW32_BASE_ADDR. This support was tested with an Orchid +CDS-3110 connected to a SoundWave32. +If you want your soundcard to be supported, find out, how it needs to be +configured and mail me (see 6.) the appropriate information. + +5. KNOWN PROBLEMS, FUTURE DEVELOPMENTS +5.1 MULTISESSION SUPPORT +Multisession support for CD's still is a myth. I implemented and tested a basic +support for multisession and XA CDs, but I still have not enough CDs and appli- +cations to test it rigorously. So if you'd like to help me, please contact me +(Email address see below). As of version 1.4 and newer you can enable the +multisession support in aztcd.h by setting AZT_MULTISESSION to 1. Doing so +will cause the ISO9660-filesystem to deal with multisession CDs, ie. redirect +requests to the Table of Contents (TOC) information from the last session, +which contains the info of all previous sessions etc.. If you do set +AZT_MULTISESSION to 0, you can use multisession CDs anyway. In that case the +drive's firmware will do automatic redirection. For the ISO9660-filesystem any +multisession CD will then look like a 'normal' single session CD. But never- +theless the data of all sessions are viewable and accessible. So with practical- +ly all real world applications you won't notice the difference. But as future +applications may make use of advanced multisession features, I've started to +implement the interface for the ISO9660 multisession interface via ioctl +CDROMMULTISESSION. + +5.2 STATUS RECOGNITION +The drive status recognition does not work correctly in all cases. Changing +a disk or having the door open, when a drive is already mounted, is detected +by the Aztech driver itself, but nevertheless causes multiple read attempts +by the different layers of the ISO9660-filesystem driver, which finally timeout, +so you have to wait quite a little... But isn't it bad style to change a disk +in a mounted drive, anyhow ?! + +The driver uses busy wait in most cases for the drive handshake (macros +STEN_LOW and DTEN_LOW). I tested with a 486/DX2 at 66MHz and a Pentium at +60MHz and 90MHz. Whenever you use a much faster machine you are likely to get +timeout messages. In that case edit aztcd.h and increase the timeout value +AZT_TIMEOUT. + +For some 'slow' drive commands I implemented waiting with a timer waitqueue +(macro STEN_LOW_WAIT). If you get this timeout message, you may also edit +aztcd.h and increase the timeout value AZT_STATUS_DELAY. The waitqueue has +shown to be a little critical. If you get kernel panic messages, edit aztcd.c +and substitute STEN_LOW_WAIT by STEN_LOW. Busy waiting with STEN_LOW is more +stable, but also causes CPU overhead. + +5.3 DOSEMU's CD-ROM SUPPORT +With release 1.20 aztcd was modified to allow access to CD-ROMS when running +under dosemu-0.60.0 aztcd-versions before 1.20 are most likely to crash +Linux, when a CD-ROM is accessed under dosemu. This problem has partly been +fixed, but still when accessing a directory for the first time the system +might hang for some 30sec. So be patient, when using dosemu's CD-ROM support +in combination with aztcd :-) ! +This problem has now (July 1995) been fixed by a modification to dosemu's +CD-ROM driver. The new version came with dosemu-0.60.2, see dosemu's +README.CDROM. + +6. BUG REPORTS +Please send detailed bug reports and bug fixes via EMail to + + Werner.Zimmermann@fht-esslingen.de + +Please include a description of your CD-ROM drive type and interface card, +the exact firmware message during Linux bootup, the version number of the +AZTECH-CDROM-driver and the Linux kernel version. Also a description of your +system's other hardware could be of interest, especially microprocessor type, +clock frequency, other interface cards such as soundcards, ethernet adapter, +game cards etc.. + +I will try to collect the reports and make the necessary modifications from +time to time. I may also come back to you directly with some bug fixes and +ask you to do further testing and debugging. + +Editors of CD-ROMs are invited to send a 'cooperation' copy of their +CD-ROMs to the volunteers, who provided the CD-ROM support for Linux. My +snail mail address for such 'stuff' is + Prof. Dr. W. Zimmermann + Fachhochschule fuer Technik Esslingen + Fachbereich IT + Flandernstrasse 101 + D-73732 Esslingen + Germany + + +7. OTHER DRIVES +The following drives ORCHID CDS3110, OKANO CDD110, WEARNES CDD110 and Conrad +TXC Nr. 993123-series 04 nearly look the same as AZTECH CDA268-01A, especially +they seem to use the same command codes. So it was quite simple to make the +AZTECH driver work with these drives. + +Unfortunately I do not have any of these drives available, so I couldn't test +it myself. In some installations, it seems necessary to initialize the drive +with the DOS driver before (especially if combined with a sound card) and then +do a warm boot (CTRL-ALT-RESET) or start Linux from DOS, e.g. with 'loadlin'. + +If you do not succeed, read chapter DEBUGGING. Thanks in advance! + +Sorry for the inconvenience, but it is difficult to develop for hardware, +which you don't have available for testing. So if you like, please help us. + +If you do have a CyCDROM CR520ie thanks to Hilmar Berger's help your chances +are good, that it will work with aztcd. The CR520ie is sold as an IDE-drive +and really is connected to the IDE interface (primary at 0x1F0 or secondary +at 0x170, configured as slave, not as master). Nevertheless it is not ATAPI +compatible but still uses Aztech's command codes. + + +8. DEBUGGING : IF YOU DON'T SUCCEED, TRY THE FOLLOWING +-reread the complete README file +-make sure, that your drive is hardware configured for + transfer mode: polled + IRQ: not used + DMA: not used + Base Address: something like 300, 320 ... + You can check this, when you start the DOS driver, which came with your + drive. By appropriately configuring the drive and the DOS driver you can + check, whether your drive does operate in this mode correctly under DOS. If + it does not operate under DOS, it won't under Linux. + If your drive's base address is something like 0x170 or 0x1F0 (and it is + not a CyCDROM CR520ie or CR 940ie) you most likely are having an IDE/ATAPI- + compatible drive, which is not supported by aztcd.c, use ide-cd.c instead. + Make sure the Base Address is configured correctly in aztcd.h, also make + sure, that /dev/aztcd0 exists with the correct major number (compare it with + the entry in file /usr/include/linux/major.h for the Aztech drive). +-insert a CD-ROM and close the tray +-cold boot your PC (i.e. via the power on switch or the reset button) +-if you start Linux via DOS, e.g. using loadlin, make sure, that the DOS + driver for the CD-ROM drive is not loaded (comment out the calling lines + in DOS' config.sys!) +-look for the aztcd: init message during Linux init and note them exactly +-log in as root and do a mount -t iso9660 /dev/aztcd0 /mnt +-if you don't succeed in the first time, try several times. Try also to open + and close the tray, then mount again. Please note carefully all commands + you typed in and the aztcd-messages, which you get. +-if you get an 'Aztech CD-ROM init: aborted' message, read the remarks about + the version string below. + +If this does not help, do the same with the following differences +-start DOS before; make now sure, that the DOS driver for the CD-ROM is + loaded under DOS (i.e. uncomment it again in config.sys) +-warm boot your PC (i.e. via CTRL-ALT-DEL) + if you have it, you can also start via loadlin (try both). + ... + Again note all commands and the aztcd-messages. + +If you see STEN_LOW or STEN_LOW_WAIT error messages, increase the timeout +values. + +If this still does not help, +-look in aztcd.c for the lines #if 0 + #define AZT_TEST1 + ... + #endif + and substitute '#if 0' by '#if 1'. +-recompile your kernel and repeat the above two procedures. You will now get + a bundle of debugging messages from the driver. Again note your commands + and the appropriate messages. If you have syslogd running, these messages + may also be found in syslogd's kernel log file. Nevertheless in some + installations syslogd does not yet run, when init() is called, thus look for + the aztcd-messages during init, before the login-prompt appears. + Then look in aztcd.c, to find out, what happened. The normal calling sequence + is: aztcd_init() during Linux bootup procedure init() + after doing a 'mount -t iso9660 /dev/aztcd0 /mnt' the normal calling sequence is + aztcd_open() -> Status 2c after cold reboot with CDROM or audio CD inserted + -> Status 8 after warm reboot with CDROM inserted + -> Status 2e after cold reboot with no disk, closed tray + -> Status 6e after cold reboot, mount with door open + aztUpdateToc() + aztGetDiskInfo() + aztGetQChannelInfo() repeated several times + aztGetToc() + aztGetQChannelInfo() repeated several times + a list of track information + do_aztcd_request() } + azt_transfer() } repeated several times + azt_poll } + Check, if there is a difference in the calling sequence or the status flags! + + There are a lot of other messages, eg. the ACMD-command code (defined in + aztcd.h), status info from the getAztStatus-command and the state sequence of + the finite state machine in azt_poll(). The most important are the status + messages, look how they are defined and try to understand, if they make + sense in the context where they appear. With a CD-ROM inserted the status + should always be 8, except in aztcd_open(). Try to open the tray, insert an + audio disk, insert no disk or reinsert the CD-ROM and check, if the status + bits change accordingly. The status bits are the most likely point, where + the drive manufacturers may implement changes. + +If you still don't succeed, a good point to start is to look in aztcd.c in +function aztcd_init, where the drive should be detected during init. Do the +following: +-reboot the system with boot parameter 'aztcd=<your base address>,0x79'. With + parameter 0x79 most of the drive version detection is bypassed. After that + you should see the complete version string including leading and trailing + blanks during init. + Now adapt the statement + if ((result[1]=='A')&&(result[2]=='Z' ...) + in aztcd_init() to exactly match the first 3 or 4 letters you have seen. +-Another point is the 'smart' card detection feature in aztcd_init(). Normally + the CD-ROM drive is ready, when aztcd_init is trying to read the version + string and a time consuming ACMD_SOFT_RESET command can be avoided. This is + detected by looking, if AFL_OP_OK can be read correctly. If the CD-ROM drive + hangs in some unknown state, e.g. because of an error before a warm start or + because you first operated under DOS, even the version string may be correct, + but the following commands will not. Then change the code in such a way, + that the ACMD_SOFT_RESET is issued in any case, by substituting the + if-statement 'if ( ...=AFL_OP_OK)' by 'if (1)'. + +If you succeed, please mail me the exact version string of your drive and +the code modifications, you have made together with a short explanation. +If you don't succeed, you may mail me the output of the debugging messages. +But remember, they are only useful, if they are exact and complete and you +describe in detail your hardware setup and what you did (cold/warm reboot, +with/without DOS, DOS-driver started/not started, which Linux-commands etc.) + + +9. TECHNICAL HISTORY OF THE DRIVER +The AZTECH-Driver is a rework of the Mitsumi-Driver. Four major items had to +be reworked: + +a) The Mitsumi drive does issue complete status information acknowledging +each command, the Aztech drive does only signal that the command was +processed. So whenever the complete status information is needed, an extra +ACMD_GET_STATUS command is issued. The handshake procedure for the drive +can be found in the functions aztSendCmd(), sendAztCmd() and getAztStatus(). + +b) The Aztech Drive does not have a ACMD_GET_DISK_INFO command, so the +necessary info about the number of tracks (firstTrack, lastTrack), disk +length etc. has to be read from the TOC in the lead in track (see function +aztGetDiskInfo()). + +c) Whenever data is read from the drive, the Mitsumi drive is started with a +command to read an indefinite (0xffffff) number of sectors. When the appropriate +number of sectors is read, the drive is stopped by a ACDM_STOP command. This +does not work with the Aztech drive. I did not find a way to stop it. The +stop and pause commands do only work in AUDIO mode but not in DATA mode. +Therefore I had to modify the 'finite state machine' in function azt_poll to +only read a certain number of sectors and then start a new read on demand. As I +have not completely understood, how the buffer/caching scheme of the Mitsumi +driver was implemented, I am not sure, if I have covered all cases correctly, +whenever you get timeout messages, the bug is most likely to be in that +function azt_poll() around switch(cmd) .... case ACD_S_DATA. + +d) I did not get information about changing drive mode. So I doubt, that the +code around function azt_poll() case AZT_S_MODE does work. In my test I have +not been able to switch to reading in raw mode. For reading raw mode, Aztech +uses a different command than for cooked mode, which I only have implemen- +ted in the ioctl-section but not in the section which is used by the ISO9660. + +The driver was developed on an AST PC with Intel 486/DX2, 8MB RAM, 340MB IDE +hard disk and on an AST PC with Intel Pentium 60MHz, 16MB RAM, 520MB IDE +running Linux kernel version 1.0.9 from the LST 1.8 Distribution. The kernel +was compiled with gcc.2.5.8. My CD-ROM drive is an Aztech CDA268-01A. My +drive says, that it has Firmware Version AZT26801A1.3. It came with an ISA-bus +interface card and works with polled I/O without DMA and without interrupts. +The code for all other drives was 'remote' tested and debugged by a number of +volunteers on the Internet. + +Points, where I feel that possible problems might be and all points where I +did not completely understand the drive's behaviour or trust my own code are +marked with /*???*/ in the source code. There are also some parts in the +Mitsumi driver, where I did not completely understand their code. + + +10. ACKNOWLEDGMENTS +Without the help of P.Bush, Aztech, who delivered technical information +about the Aztech Drive and without the help of E.Moenkeberg, GWDG, who did a +great job in analyzing the command structure of various CD-ROM drives, this +work would not have been possible. E.Moenkeberg was also a great help in +making the software 'kernel ready' and in answering many of the CDROM-related +questions in the newsgroups. He really is *the* Linux CD-ROM guru. Thanks +also to all the guys on the Internet, who collected valuable technical +information about CDROMs. + +Joe Nardone (joe@access.digex.net) was a patient tester even for my first +trial, which was more than slow, and made suggestions for code improvement. +Especially the 'finite state machine' azt_poll() was rewritten by Joe to get +clean C code and avoid the ugly 'gotos', which I copied from mcd.c. + +Robby Schirmer (schirmer@fmi.uni-passau.de) tested the audio stuff (ioctls) +and suggested a lot of patches for them. + +Joseph Piskor and Peter Nugent were the first users with the ORCHID CD3110 +and also were very patient with the problems which occurred. + +Reinhard Max delivered the information for the CDROM-interface of the +SoundWave32 soundcards. + +Jochen Kunz and Olaf Kaluza delivered the information for supporting Conrad's +TXC drive. + +Hilmar Berger delivered the patches for supporting CyCDROM CR520ie. + +Anybody, who is interested in these items should have a look at 'ftp.gwdg.de', +directory 'pub/linux/cdrom' and at 'ftp.cdrom.com', directory 'pub/cdrom'. + +11. PROGRAMMING ADD ONs: cdplay.c +You can use the ioctl-functions included in aztcd.c in your own programs. As +an example on how to do this, you will find a tiny CD Player for audio CDs +named 'cdplay.c'. It allows you to play audio CDs. You can play a specified +track, pause and resume or skip tracks forward and backwards. If you quit the +program without stopping the drive, playing is continued. You can also +(mis)use cdplay to read and hexdump data disks. You can find the code in the +APPENDIX of this file, which you should cut out with an editor and store in a +separate file 'cdplay.c'. To compile it and make it executable, do + gcc -s -Wall -O2 -L/usr/lib cdplay.c -o /usr/local/bin/cdplay # compiles it + chmod +755 /usr/local/bin/cdplay # makes it executable + ln -s /dev/aztcd0 /dev/cdrom # creates a link + (for /usr/lib substitute the top level directory, where your include files + reside, and for /usr/local/bin the directory, where you want the executable + binary to reside ) + +You have to set the correct permissions for cdplay *and* for /dev/mcd0 or +/dev/aztcd0 in order to use it. Remember, that you should not have /dev/cdrom +mounted, when you're playing audio CDs. + +This program is just a hack for testing the ioctl-functions in aztcd.c. I will +not maintain it, so if you run into problems, discard it or have a look into +the source code 'cdplay.c'. The program does only contain a minimum of user +protection and input error detection. If you use the commands in the wrong +order or if you try to read a CD at wrong addresses, you may get error messages +or even hang your machine. If you get STEN_LOW, STEN_LOW_WAIT or segment violation +error messages when using cdplay, after that, the system might not be stable +any more, so you'd better reboot. As the ioctl-functions run in kernel mode, +most normal Linux-multitasking protection features do not work. By using +uninitialized 'wild' pointers etc., it is easy to write to other users' data +and program areas, destroy kernel tables etc.. So if you experiment with ioctls +as always when you are doing systems programming and kernel hacking, you +should have a backup copy of your system in a safe place (and you also +should try restoring from a backup copy first)! + +A reworked and improved version called 'cdtester.c', which has yet more +features for testing CDROM-drives can be found in +Documentation/cdrom/sbpcd, written by E.Moenkeberg. + +Werner Zimmermann +Fachhochschule fuer Technik Esslingen +(EMail: Werner.Zimmermann@fht-esslingen.de) +October, 1997 + +--------------------------------------------------------------------------- +APPENDIX: Source code of cdplay.c + +/* Tiny Audio CD Player + + Copyright 1994, 1995, 1996 Werner Zimmermann (Werner.Zimmermann@fht-esslingen.de) + +This program originally was written to test the audio functions of the +AZTECH.CDROM-driver, but it should work with every CD-ROM drive. Before +using it, you should set a symlink from /dev/cdrom to your real CDROM +device. + +The GNU General Public License applies to this program. + +History: V0.1 W.Zimmermann: First release. Nov. 8, 1994 + V0.2 W.Zimmermann: Enhanced functionality. Nov. 9, 1994 + V0.3 W.Zimmermann: Additional functions. Nov. 28, 1994 + V0.4 W.Zimmermann: fixed some bugs. Dec. 17, 1994 + V0.5 W.Zimmermann: clean 'scanf' commands without compiler warnings + Jan. 6, 1995 + V0.6 W.Zimmermann: volume control (still experimental). Jan. 24, 1995 + V0.7 W.Zimmermann: read raw modified. July 26, 95 +*/ + +#include <stdio.h> +#include <ctype.h> +#include <sys/ioctl.h> +#include <sys/types.h> +#include <fcntl.h> +#include <unistd.h> +#include <linux/cdrom.h> +#include <linux/../../drivers/cdrom/aztcd.h> + +void help(void) +{ printf("Available Commands: STOP s EJECT/CLOSE e QUIT q\n"); + printf(" PLAY TRACK t PAUSE p RESUME r\n"); + printf(" NEXT TRACK n REPEAT LAST l HELP h\n"); + printf(" SUB CHANNEL c TRACK INFO i PLAY AT a\n"); + printf(" READ d READ RAW w VOLUME v\n"); +} + +int main(void) +{ int handle; + unsigned char command=' ', ini=0, first=1, last=1; + unsigned int cmd, i,j,k, arg1,arg2,arg3; + struct cdrom_ti ti; + struct cdrom_tochdr tocHdr; + struct cdrom_subchnl subchnl; + struct cdrom_tocentry entry; + struct cdrom_msf msf; + union { struct cdrom_msf msf; + unsigned char buf[CD_FRAMESIZE_RAW]; + } azt; + struct cdrom_volctrl volctrl; + + printf("\nMini-Audio CD-Player V0.72 (C) 1994,1995,1996 W.Zimmermann\n"); + handle=open("/dev/cdrom",O_RDWR); + ioctl(handle,CDROMRESUME); + + if (handle<=0) + { printf("Drive Error: already playing, no audio disk, door open\n"); + printf(" or no permission (you must be ROOT in order to use this program)\n"); + } + else + { help(); + while (1) + { printf("Type command (h = help): "); + scanf("%s",&command); + switch (command) + { case 'e': cmd=CDROMEJECT; + ioctl(handle,cmd); + break; + case 'p': if (!ini) + { printf("Command not allowed - play track first\n"); + } + else + { cmd=CDROMPAUSE; + if (ioctl(handle,cmd)) printf("Drive Error\n"); + } + break; + case 'r': if (!ini) + { printf("Command not allowed - play track first\n"); + } + else + { cmd=CDROMRESUME; + if (ioctl(handle,cmd)) printf("Drive Error\n"); + } + break; + case 's': cmd=CDROMPAUSE; + if (ioctl(handle,cmd)) printf("Drive error or already stopped\n"); + cmd=CDROMSTOP; + if (ioctl(handle,cmd)) printf("Drive error\n"); + break; + case 't': cmd=CDROMREADTOCHDR; + if (ioctl(handle,cmd,&tocHdr)) printf("Drive Error\n"); + first=tocHdr.cdth_trk0; + last= tocHdr.cdth_trk1; + if ((first==0)||(first>last)) + { printf ("--could not read TOC\n"); + } + else + { printf("--first track: %d --last track: %d --enter track number: ",first,last); + cmd=CDROMPLAYTRKIND; + scanf("%i",&arg1); + ti.cdti_trk0=arg1; + if (ti.cdti_trk0<first) ti.cdti_trk0=first; + if (ti.cdti_trk0>last) ti.cdti_trk0=last; + ti.cdti_ind0=0; + ti.cdti_trk1=last; + ti.cdti_ind1=0; + if (ioctl(handle,cmd,&ti)) printf("Drive Error\n"); + ini=1; + } + break; + case 'n': if (!ini++) + { if (ioctl(handle,CDROMREADTOCHDR,&tocHdr)) printf("Drive Error\n"); + first=tocHdr.cdth_trk0; + last= tocHdr.cdth_trk1; + ti.cdti_trk0=first-1; + } + if ((first==0)||(first>last)) + { printf ("--could not read TOC\n"); + } + else + { cmd=CDROMPLAYTRKIND; + if (++ti.cdti_trk0 > last) ti.cdti_trk0=last; + ti.cdti_ind0=0; + ti.cdti_trk1=last; + ti.cdti_ind1=0; + if (ioctl(handle,cmd,&ti)) printf("Drive Error\n"); + ini=1; + } + break; + case 'l': if (!ini++) + { if (ioctl(handle,CDROMREADTOCHDR,&tocHdr)) printf("Drive Error\n"); + first=tocHdr.cdth_trk0; + last= tocHdr.cdth_trk1; + ti.cdti_trk0=first+1; + } + if ((first==0)||(first>last)) + { printf ("--could not read TOC\n"); + } + else + { cmd=CDROMPLAYTRKIND; + if (--ti.cdti_trk0 < first) ti.cdti_trk0=first; + ti.cdti_ind0=0; + ti.cdti_trk1=last; + ti.cdti_ind1=0; + if (ioctl(handle,cmd,&ti)) printf("Drive Error\n"); + ini=1; + } + break; + case 'c': subchnl.cdsc_format=CDROM_MSF; + if (ioctl(handle,CDROMSUBCHNL,&subchnl)) + printf("Drive Error\n"); + else + { printf("AudioStatus:%s Track:%d Mode:%d MSF=%d:%d:%d\n", \ + subchnl.cdsc_audiostatus==CDROM_AUDIO_PLAY ? "PLAYING":"NOT PLAYING",\ + subchnl.cdsc_trk,subchnl.cdsc_adr, \ + subchnl.cdsc_absaddr.msf.minute, subchnl.cdsc_absaddr.msf.second, \ + subchnl.cdsc_absaddr.msf.frame); + } + break; + case 'i': if (!ini) + { printf("Command not allowed - play track first\n"); + } + else + { cmd=CDROMREADTOCENTRY; + printf("Track No.: "); + scanf("%d",&arg1); + entry.cdte_track=arg1; + if (entry.cdte_track<first) entry.cdte_track=first; + if (entry.cdte_track>last) entry.cdte_track=last; + entry.cdte_format=CDROM_MSF; + if (ioctl(handle,cmd,&entry)) + { printf("Drive error or invalid track no.\n"); + } + else + { printf("Mode %d Track, starts at %d:%d:%d\n", \ + entry.cdte_adr,entry.cdte_addr.msf.minute, \ + entry.cdte_addr.msf.second,entry.cdte_addr.msf.frame); + } + } + break; + case 'a': cmd=CDROMPLAYMSF; + printf("Address (min:sec:frame) "); + scanf("%d:%d:%d",&arg1,&arg2,&arg3); + msf.cdmsf_min0 =arg1; + msf.cdmsf_sec0 =arg2; + msf.cdmsf_frame0=arg3; + if (msf.cdmsf_sec0 > 59) msf.cdmsf_sec0 =59; + if (msf.cdmsf_frame0> 74) msf.cdmsf_frame0=74; + msf.cdmsf_min1=60; + msf.cdmsf_sec1=00; + msf.cdmsf_frame1=00; + if (ioctl(handle,cmd,&msf)) + { printf("Drive error or invalid address\n"); + } + break; +#ifdef AZT_PRIVATE_IOCTLS /*not supported by every CDROM driver*/ + case 'd': cmd=CDROMREADCOOKED; + printf("Address (min:sec:frame) "); + scanf("%d:%d:%d",&arg1,&arg2,&arg3); + azt.msf.cdmsf_min0 =arg1; + azt.msf.cdmsf_sec0 =arg2; + azt.msf.cdmsf_frame0=arg3; + if (azt.msf.cdmsf_sec0 > 59) azt.msf.cdmsf_sec0 =59; + if (azt.msf.cdmsf_frame0> 74) azt.msf.cdmsf_frame0=74; + if (ioctl(handle,cmd,&azt.msf)) + { printf("Drive error, invalid address or unsupported command\n"); + } + k=0; + getchar(); + for (i=0;i<128;i++) + { printf("%4d:",i*16); + for (j=0;j<16;j++) + { printf("%2x ",azt.buf[i*16+j]); + } + for (j=0;j<16;j++) + { if (isalnum(azt.buf[i*16+j])) + printf("%c",azt.buf[i*16+j]); + else + printf("."); + } + printf("\n"); + k++; + if (k>=20) + { printf("press ENTER to continue\n"); + getchar(); + k=0; + } + } + break; + case 'w': cmd=CDROMREADRAW; + printf("Address (min:sec:frame) "); + scanf("%d:%d:%d",&arg1,&arg2,&arg3); + azt.msf.cdmsf_min0 =arg1; + azt.msf.cdmsf_sec0 =arg2; + azt.msf.cdmsf_frame0=arg3; + if (azt.msf.cdmsf_sec0 > 59) azt.msf.cdmsf_sec0 =59; + if (azt.msf.cdmsf_frame0> 74) azt.msf.cdmsf_frame0=74; + if (ioctl(handle,cmd,&azt)) + { printf("Drive error, invalid address or unsupported command\n"); + } + k=0; + for (i=0;i<147;i++) + { printf("%4d:",i*16); + for (j=0;j<16;j++) + { printf("%2x ",azt.buf[i*16+j]); + } + for (j=0;j<16;j++) + { if (isalnum(azt.buf[i*16+j])) + printf("%c",azt.buf[i*16+j]); + else + printf("."); + } + printf("\n"); + k++; + if (k>=20) + { getchar(); + k=0; + } + } + break; +#endif + case 'v': cmd=CDROMVOLCTRL; + printf("--Channel 0 Left (0-255): "); + scanf("%d",&arg1); + printf("--Channel 1 Right (0-255): "); + scanf("%d",&arg2); + volctrl.channel0=arg1; + volctrl.channel1=arg2; + volctrl.channel2=0; + volctrl.channel3=0; + if (ioctl(handle,cmd,&volctrl)) + { printf("Drive error or unsupported command\n"); + } + break; + case 'q': if (close(handle)) printf("Drive Error: CLOSE\n"); + exit(0); + case 'h': help(); + break; + default: printf("unknown command\n"); + break; + } + } + } + return 0; +} diff --git a/Documentation/cdrom/cdrom-standard.tex b/Documentation/cdrom/cdrom-standard.tex new file mode 100644 index 000000000000..92f94e597582 --- /dev/null +++ b/Documentation/cdrom/cdrom-standard.tex @@ -0,0 +1,1022 @@ +\documentclass{article} +\def\version{$Id: cdrom-standard.tex,v 1.9 1997/12/28 15:42:49 david Exp $} +\newcommand{\newsection}[1]{\newpage\section{#1}} + +\evensidemargin=0pt +\oddsidemargin=0pt +\topmargin=-\headheight \advance\topmargin by -\headsep +\textwidth=15.99cm \textheight=24.62cm % normal A4, 1'' margin + +\def\linux{{\sc Linux}} +\def\cdrom{{\sc cd-rom}} +\def\UCD{{\sc Uniform cd-rom Driver}} +\def\cdromc{{\tt {cdrom.c}}} +\def\cdromh{{\tt {cdrom.h}}} +\def\fo{\sl} % foreign words +\def\ie{{\fo i.e.}} +\def\eg{{\fo e.g.}} + +\everymath{\it} \everydisplay{\it} +\catcode `\_=\active \def_{\_\penalty100 } +\catcode`\<=\active \def<#1>{{\langle\hbox{\rm#1}\rangle}} + +\begin{document} +\title{A \linux\ \cdrom\ standard} +\author{David van Leeuwen\\{\normalsize\tt david@ElseWare.cistron.nl} +\\{\footnotesize updated by Erik Andersen {\tt(andersee@debian.org)}} +\\{\footnotesize updated by Jens Axboe {\tt(axboe@image.dk)}}} +\date{12 March 1999} + +\maketitle + +\newsection{Introduction} + +\linux\ is probably the Unix-like operating system that supports +the widest variety of hardware devices. The reasons for this are +presumably +\begin{itemize} +\item + The large list of hardware devices available for the many platforms + that \linux\ now supports (\ie, i386-PCs, Sparc Suns, etc.) +\item + The open design of the operating system, such that anybody can write a + driver for \linux. +\item + There is plenty of source code around as examples of how to write a driver. +\end{itemize} +The openness of \linux, and the many different types of available +hardware has allowed \linux\ to support many different hardware devices. +Unfortunately, the very openness that has allowed \linux\ to support +all these different devices has also allowed the behavior of each +device driver to differ significantly from one device to another. +This divergence of behavior has been very significant for \cdrom\ +devices; the way a particular drive reacts to a `standard' $ioctl()$ +call varies greatly from one device driver to another. To avoid making +their drivers totally inconsistent, the writers of \linux\ \cdrom\ +drivers generally created new device drivers by understanding, copying, +and then changing an existing one. Unfortunately, this practice did not +maintain uniform behavior across all the \linux\ \cdrom\ drivers. + +This document describes an effort to establish Uniform behavior across +all the different \cdrom\ device drivers for \linux. This document also +defines the various $ioctl$s, and how the low-level \cdrom\ device +drivers should implement them. Currently (as of the \linux\ 2.1.$x$ +development kernels) several low-level \cdrom\ device drivers, including +both IDE/ATAPI and SCSI, now use this Uniform interface. + +When the \cdrom\ was developed, the interface between the \cdrom\ drive +and the computer was not specified in the standards. As a result, many +different \cdrom\ interfaces were developed. Some of them had their +own proprietary design (Sony, Mitsumi, Panasonic, Philips), other +manufacturers adopted an existing electrical interface and changed +the functionality (CreativeLabs/SoundBlaster, Teac, Funai) or simply +adapted their drives to one or more of the already existing electrical +interfaces (Aztech, Sanyo, Funai, Vertos, Longshine, Optics Storage and +most of the `NoName' manufacturers). In cases where a new drive really +brought its own interface or used its own command set and flow control +scheme, either a separate driver had to be written, or an existing +driver had to be enhanced. History has delivered us \cdrom\ support for +many of these different interfaces. Nowadays, almost all new \cdrom\ +drives are either IDE/ATAPI or SCSI, and it is very unlikely that any +manufacturer will create a new interface. Even finding drives for the +old proprietary interfaces is getting difficult. + +When (in the 1.3.70's) I looked at the existing software interface, +which was expressed through \cdromh, it appeared to be a rather wild +set of commands and data formats.\footnote{I cannot recollect what +kernel version I looked at, then, presumably 1.2.13 and 1.3.34---the +latest kernel that I was indirectly involved in.} It seemed that many +features of the software interface had been added to accommodate the +capabilities of a particular drive, in an {\fo ad hoc\/} manner. More +importantly, it appeared that the behavior of the `standard' commands +was different for most of the different drivers: \eg, some drivers +close the tray if an $open()$ call occurs when the tray is open, while +others do not. Some drivers lock the door upon opening the device, to +prevent an incoherent file system, but others don't, to allow software +ejection. Undoubtedly, the capabilities of the different drives vary, +but even when two drives have the same capability their drivers' +behavior was usually different. + +I decided to start a discussion on how to make all the \linux\ \cdrom\ +drivers behave more uniformly. I began by contacting the developers of +the many \cdrom\ drivers found in the \linux\ kernel. Their reactions +encouraged me to write the \UCD\ which this document is intended to +describe. The implementation of the \UCD\ is in the file \cdromc. This +driver is intended to be an additional software layer that sits on top +of the low-level device drivers for each \cdrom\ drive. By adding this +additional layer, it is possible to have all the different \cdrom\ +devices behave {\em exactly\/} the same (insofar as the underlying +hardware will allow). + +The goal of the \UCD\ is {\em not\/} to alienate driver developers who +have not yet taken steps to support this effort. The goal of \UCD\ is +simply to give people writing application programs for \cdrom\ drives +{\em one\/} \linux\ \cdrom\ interface with consistent behavior for all +\cdrom\ devices. In addition, this also provides a consistent interface +between the low-level device driver code and the \linux\ kernel. Care +is taken that 100\,\% compatibility exists with the data structures and +programmer's interface defined in \cdromh. This guide was written to +help \cdrom\ driver developers adapt their code to use the \UCD\ code +defined in \cdromc. + +Personally, I think that the most important hardware interfaces are +the IDE/ATAPI drives and, of course, the SCSI drives, but as prices +of hardware drop continuously, it is also likely that people may have +more than one \cdrom\ drive, possibly of mixed types. It is important +that these drives behave in the same way. In December 1994, one of the +cheapest \cdrom\ drives was a Philips cm206, a double-speed proprietary +drive. In the months that I was busy writing a \linux\ driver for it, +proprietary drives became obsolete and IDE/ATAPI drives became the +standard. At the time of the last update to this document (November +1997) it is becoming difficult to even {\em find} anything less than a +16 speed \cdrom\ drive, and 24 speed drives are common. + +\newsection{Standardizing through another software level} +\label{cdrom.c} + +At the time this document was conceived, all drivers directly +implemented the \cdrom\ $ioctl()$ calls through their own routines. This +led to the danger of different drivers forgetting to do important things +like checking that the user was giving the driver valid data. More +importantly, this led to the divergence of behavior, which has already +been discussed. + +For this reason, the \UCD\ was created to enforce consistent \cdrom\ +drive behavior, and to provide a common set of services to the various +low-level \cdrom\ device drivers. The \UCD\ now provides another +software-level, that separates the $ioctl()$ and $open()$ implementation +from the actual hardware implementation. Note that this effort has +made few changes which will affect a user's application programs. The +greatest change involved moving the contents of the various low-level +\cdrom\ drivers' header files to the kernel's cdrom directory. This was +done to help ensure that the user is only presented with only one cdrom +interface, the interface defined in \cdromh. + +\cdrom\ drives are specific enough (\ie, different from other +block-devices such as floppy or hard disc drives), to define a set +of common {\em \cdrom\ device operations}, $<cdrom-device>_dops$. +These operations are different from the classical block-device file +operations, $<block-device>_fops$. + +The routines for the \UCD\ interface level are implemented in the file +\cdromc. In this file, the \UCD\ interfaces with the kernel as a block +device by registering the following general $struct\ file_operations$: +$$ +\halign{$#$\ \hfil&$#$\ \hfil&$/*$ \rm# $*/$\hfil\cr +struct& file_operations\ cdrom_fops = \{\hidewidth\cr + &NULL, & lseek \cr + &block_read, & read---general block-dev read \cr + &block_write, & write---general block-dev write \cr + &NULL, & readdir \cr + &NULL, & select \cr + &cdrom_ioctl, & ioctl \cr + &NULL, & mmap \cr + &cdrom_open, & open \cr + &cdrom_release, & release \cr + &NULL, & fsync \cr + &NULL, & fasync \cr + &cdrom_media_changed, & media change \cr + &NULL & revalidate \cr +\};\cr +} +$$ + +Every active \cdrom\ device shares this $struct$. The routines +declared above are all implemented in \cdromc, since this file is the +place where the behavior of all \cdrom-devices is defined and +standardized. The actual interface to the various types of \cdrom\ +hardware is still performed by various low-level \cdrom-device +drivers. These routines simply implement certain {\em capabilities\/} +that are common to all \cdrom\ (and really, all removable-media +devices). + +Registration of a low-level \cdrom\ device driver is now done through +the general routines in \cdromc, not through the Virtual File System +(VFS) any more. The interface implemented in \cdromc\ is carried out +through two general structures that contain information about the +capabilities of the driver, and the specific drives on which the +driver operates. The structures are: +\begin{description} +\item[$cdrom_device_ops$] + This structure contains information about the low-level driver for a + \cdrom\ device. This structure is conceptually connected to the major + number of the device (although some drivers may have different + major numbers, as is the case for the IDE driver). +\item[$cdrom_device_info$] + This structure contains information about a particular \cdrom\ drive, + such as its device name, speed, etc. This structure is conceptually + connected to the minor number of the device. +\end{description} + +Registering a particular \cdrom\ drive with the \UCD\ is done by the +low-level device driver though a call to: +$$register_cdrom(struct\ cdrom_device_info * <device>_info) +$$ +The device information structure, $<device>_info$, contains all the +information needed for the kernel to interface with the low-level +\cdrom\ device driver. One of the most important entries in this +structure is a pointer to the $cdrom_device_ops$ structure of the +low-level driver. + +The device operations structure, $cdrom_device_ops$, contains a list +of pointers to the functions which are implemented in the low-level +device driver. When \cdromc\ accesses a \cdrom\ device, it does it +through the functions in this structure. It is impossible to know all +the capabilities of future \cdrom\ drives, so it is expected that this +list may need to be expanded from time to time as new technologies are +developed. For example, CD-R and CD-R/W drives are beginning to become +popular, and support will soon need to be added for them. For now, the +current $struct$ is: +$$ +\halign{$#$\ \hfil&$#$\ \hfil&\hbox to 10em{$#$\hss}& + $/*$ \rm# $*/$\hfil\cr +struct& cdrom_device_ops\ \{ \hidewidth\cr + &int& (* open)(struct\ cdrom_device_info *, int)\cr + &void& (* release)(struct\ cdrom_device_info *);\cr + &int& (* drive_status)(struct\ cdrom_device_info *, int);\cr + &int& (* media_changed)(struct\ cdrom_device_info *, int);\cr + &int& (* tray_move)(struct\ cdrom_device_info *, int);\cr + &int& (* lock_door)(struct\ cdrom_device_info *, int);\cr + &int& (* select_speed)(struct\ cdrom_device_info *, int);\cr + &int& (* select_disc)(struct\ cdrom_device_info *, int);\cr + &int& (* get_last_session) (struct\ cdrom_device_info *, + struct\ cdrom_multisession *{});\cr + &int& (* get_mcn)(struct\ cdrom_device_info *, struct\ cdrom_mcn *{});\cr + &int& (* reset)(struct\ cdrom_device_info *);\cr + &int& (* audio_ioctl)(struct\ cdrom_device_info *, unsigned\ int, + void *{});\cr + &int& (* dev_ioctl)(struct\ cdrom_device_info *, unsigned\ int, + unsigned\ long);\cr +\noalign{\medskip} + &const\ int& capability;& capability flags \cr + &int& n_minors;& number of active minor devices \cr +\};\cr +} +$$ +When a low-level device driver implements one of these capabilities, +it should add a function pointer to this $struct$. When a particular +function is not implemented, however, this $struct$ should contain a +NULL instead. The $capability$ flags specify the capabilities of the +\cdrom\ hardware and/or low-level \cdrom\ driver when a \cdrom\ drive +is registered with the \UCD. The value $n_minors$ should be a positive +value indicating the number of minor devices that are supported by +the low-level device driver, normally~1. Although these two variables +are `informative' rather than `operational,' they are included in +$cdrom_device_ops$ because they describe the capability of the {\em +driver\/} rather than the {\em drive}. Nomenclature has always been +difficult in computer programming. + +Note that most functions have fewer parameters than their +$blkdev_fops$ counterparts. This is because very little of the +information in the structures $inode$ and $file$ is used. For most +drivers, the main parameter is the $struct$ $cdrom_device_info$, from +which the major and minor number can be extracted. (Most low-level +\cdrom\ drivers don't even look at the major and minor number though, +since many of them only support one device.) This will be available +through $dev$ in $cdrom_device_info$ described below. + +The drive-specific, minor-like information that is registered with +\cdromc, currently contains the following fields: +$$ +\halign{$#$\ \hfil&$#$\ \hfil&\hbox to 10em{$#$\hss}& + $/*$ \rm# $*/$\hfil\cr +struct& cdrom_device_info\ \{ \hidewidth\cr + & struct\ cdrom_device_ops *& ops;& device operations for this major\cr + & struct\ cdrom_device_info *& next;& next device_info for this major\cr + & void *& handle;& driver-dependent data\cr +\noalign{\medskip} + & kdev_t& dev;& device number (incorporates minor)\cr + & int& mask;& mask of capability: disables them \cr + & int& speed;& maximum speed for reading data \cr + & int& capacity;& number of discs in a jukebox \cr +\noalign{\medskip} + &int& options : 30;& options flags \cr + &unsigned& mc_flags : 2;& media-change buffer flags \cr + & int& use_count;& number of times device is opened\cr + & char& name[20];& name of the device type\cr +\}\cr +}$$ +Using this $struct$, a linked list of the registered minor devices is +built, using the $next$ field. The device number, the device operations +struct and specifications of properties of the drive are stored in this +structure. + +The $mask$ flags can be used to mask out some of the capabilities listed +in $ops\to capability$, if a specific drive doesn't support a feature +of the driver. The value $speed$ specifies the maximum head-rate of the +drive, measured in units of normal audio speed (176\,kB/sec raw data or +150\,kB/sec file system data). The value $n_discs$ should reflect the +number of discs the drive can hold simultaneously, if it is designed +as a juke-box, or otherwise~1. The parameters are declared $const$ +because they describe properties of the drive, which don't change after +registration. + +A few registers contain variables local to the \cdrom\ drive. The +flags $options$ are used to specify how the general \cdrom\ routines +should behave. These various flags registers should provide enough +flexibility to adapt to the different users' wishes (and {\em not\/} the +`arbitrary' wishes of the author of the low-level device driver, as is +the case in the old scheme). The register $mc_flags$ is used to buffer +the information from $media_changed()$ to two separate queues. Other +data that is specific to a minor drive, can be accessed through $handle$, +which can point to a data structure specific to the low-level driver. +The fields $use_count$, $next$, $options$ and $mc_flags$ need not be +initialized. + +The intermediate software layer that \cdromc\ forms will perform some +additional bookkeeping. The use count of the device (the number of +processes that have the device opened) is registered in $use_count$. The +function $cdrom_ioctl()$ will verify the appropriate user-memory regions +for read and write, and in case a location on the CD is transferred, +it will `sanitize' the format by making requests to the low-level +drivers in a standard format, and translating all formats between the +user-software and low level drivers. This relieves much of the drivers' +memory checking and format checking and translation. Also, the necessary +structures will be declared on the program stack. + +The implementation of the functions should be as defined in the +following sections. Two functions {\em must\/} be implemented, namely +$open()$ and $release()$. Other functions may be omitted, their +corresponding capability flags will be cleared upon registration. +Generally, a function returns zero on success and negative on error. A +function call should return only after the command has completed, but of +course waiting for the device should not use processor time. + +\subsection{$Int\ open(struct\ cdrom_device_info * cdi, int\ purpose)$} + +$Open()$ should try to open the device for a specific $purpose$, which +can be either: +\begin{itemize} +\item[0] Open for reading data, as done by {\tt {mount()}} (2), or the +user commands {\tt {dd}} or {\tt {cat}}. +\item[1] Open for $ioctl$ commands, as done by audio-CD playing +programs. +\end{itemize} +Notice that any strategic code (closing tray upon $open()$, etc.)\ is +done by the calling routine in \cdromc, so the low-level routine +should only be concerned with proper initialization, such as spinning +up the disc, etc. % and device-use count + + +\subsection{$Void\ release(struct\ cdrom_device_info * cdi)$} + + +Device-specific actions should be taken such as spinning down the device. +However, strategic actions such as ejection of the tray, or unlocking +the door, should be left over to the general routine $cdrom_release()$. +This is the only function returning type $void$. + +\subsection{$Int\ drive_status(struct\ cdrom_device_info * cdi, int\ slot_nr)$} +\label{drive status} + +The function $drive_status$, if implemented, should provide +information on the status of the drive (not the status of the disc, +which may or may not be in the drive). If the drive is not a changer, +$slot_nr$ should be ignored. In \cdromh\ the possibilities are listed: +$$ +\halign{$#$\ \hfil&$/*$ \rm# $*/$\hfil\cr +CDS_NO_INFO& no information available\cr +CDS_NO_DISC& no disc is inserted, tray is closed\cr +CDS_TRAY_OPEN& tray is opened\cr +CDS_DRIVE_NOT_READY& something is wrong, tray is moving?\cr +CDS_DISC_OK& a disc is loaded and everything is fine\cr +} +$$ + +\subsection{$Int\ media_changed(struct\ cdrom_device_info * cdi, int\ disc_nr)$} + +This function is very similar to the original function in $struct\ +file_operations$. It returns 1 if the medium of the device $cdi\to +dev$ has changed since the last call, and 0 otherwise. The parameter +$disc_nr$ identifies a specific slot in a juke-box, it should be +ignored for single-disc drives. Note that by `re-routing' this +function through $cdrom_media_changed()$, we can implement separate +queues for the VFS and a new $ioctl()$ function that can report device +changes to software (\eg, an auto-mounting daemon). + +\subsection{$Int\ tray_move(struct\ cdrom_device_info * cdi, int\ position)$} + +This function, if implemented, should control the tray movement. (No +other function should control this.) The parameter $position$ controls +the desired direction of movement: +\begin{itemize} +\item[0] Close tray +\item[1] Open tray +\end{itemize} +This function returns 0 upon success, and a non-zero value upon +error. Note that if the tray is already in the desired position, no +action need be taken, and the return value should be 0. + +\subsection{$Int\ lock_door(struct\ cdrom_device_info * cdi, int\ lock)$} + +This function (and no other code) controls locking of the door, if the +drive allows this. The value of $lock$ controls the desired locking +state: +\begin{itemize} +\item[0] Unlock door, manual opening is allowed +\item[1] Lock door, tray cannot be ejected manually +\end{itemize} +This function returns 0 upon success, and a non-zero value upon +error. Note that if the door is already in the requested state, no +action need be taken, and the return value should be 0. + +\subsection{$Int\ select_speed(struct\ cdrom_device_info * cdi, int\ speed)$} + +Some \cdrom\ drives are capable of changing their head-speed. There +are several reasons for changing the speed of a \cdrom\ drive. Badly +pressed \cdrom s may benefit from less-than-maximum head rate. Modern +\cdrom\ drives can obtain very high head rates (up to $24\times$ is +common). It has been reported that these drives can make reading +errors at these high speeds, reducing the speed can prevent data loss +in these circumstances. Finally, some of these drives can +make an annoyingly loud noise, which a lower speed may reduce. %Finally, +%although the audio-low-pass filters probably aren't designed for it, +%more than real-time playback of audio might be used for high-speed +%copying of audio tracks. + +This function specifies the speed at which data is read or audio is +played back. The value of $speed$ specifies the head-speed of the +drive, measured in units of standard cdrom speed (176\,kB/sec raw data +or 150\,kB/sec file system data). So to request that a \cdrom\ drive +operate at 300\,kB/sec you would call the CDROM_SELECT_SPEED $ioctl$ +with $speed=2$. The special value `0' means `auto-selection', \ie, +maximum data-rate or real-time audio rate. If the drive doesn't have +this `auto-selection' capability, the decision should be made on the +current disc loaded and the return value should be positive. A negative +return value indicates an error. + +\subsection{$Int\ select_disc(struct\ cdrom_device_info * cdi, int\ number)$} + +If the drive can store multiple discs (a juke-box) this function +will perform disc selection. It should return the number of the +selected disc on success, a negative value on error. Currently, only +the ide-cd driver supports this functionality. + +\subsection{$Int\ get_last_session(struct\ cdrom_device_info * cdi, struct\ + cdrom_multisession * ms_info)$} + +This function should implement the old corresponding $ioctl()$. For +device $cdi\to dev$, the start of the last session of the current disc +should be returned in the pointer argument $ms_info$. Note that +routines in \cdromc\ have sanitized this argument: its requested +format will {\em always\/} be of the type $CDROM_LBA$ (linear block +addressing mode), whatever the calling software requested. But +sanitization goes even further: the low-level implementation may +return the requested information in $CDROM_MSF$ format if it wishes so +(setting the $ms_info\rightarrow addr_format$ field appropriately, of +course) and the routines in \cdromc\ will make the transformation if +necessary. The return value is 0 upon success. + +\subsection{$Int\ get_mcn(struct\ cdrom_device_info * cdi, struct\ + cdrom_mcn * mcn)$} + +Some discs carry a `Media Catalog Number' (MCN), also called +`Universal Product Code' (UPC). This number should reflect the number +that is generally found in the bar-code on the product. Unfortunately, +the few discs that carry such a number on the disc don't even use the +same format. The return argument to this function is a pointer to a +pre-declared memory region of type $struct\ cdrom_mcn$. The MCN is +expected as a 13-character string, terminated by a null-character. + +\subsection{$Int\ reset(struct\ cdrom_device_info * cdi)$} + +This call should perform a hard-reset on the drive (although in +circumstances that a hard-reset is necessary, a drive may very well not +listen to commands anymore). Preferably, control is returned to the +caller only after the drive has finished resetting. If the drive is no +longer listening, it may be wise for the underlying low-level cdrom +driver to time out. + +\subsection{$Int\ audio_ioctl(struct\ cdrom_device_info * cdi, unsigned\ + int\ cmd, void * arg)$} + +Some of the \cdrom-$ioctl$s defined in \cdromh\ can be +implemented by the routines described above, and hence the function +$cdrom_ioctl$ will use those. However, most $ioctl$s deal with +audio-control. We have decided to leave these to be accessed through a +single function, repeating the arguments $cmd$ and $arg$. Note that +the latter is of type $void*{}$, rather than $unsigned\ long\ +int$. The routine $cdrom_ioctl()$ does do some useful things, +though. It sanitizes the address format type to $CDROM_MSF$ (Minutes, +Seconds, Frames) for all audio calls. It also verifies the memory +location of $arg$, and reserves stack-memory for the argument. This +makes implementation of the $audio_ioctl()$ much simpler than in the +old driver scheme. For example, you may look up the function +$cm206_audio_ioctl()$ in {\tt {cm206.c}} that should be updated with +this documentation. + +An unimplemented ioctl should return $-ENOSYS$, but a harmless request +(\eg, $CDROMSTART$) may be ignored by returning 0 (success). Other +errors should be according to the standards, whatever they are. When +an error is returned by the low-level driver, the \UCD\ tries whenever +possible to return the error code to the calling program. (We may decide +to sanitize the return value in $cdrom_ioctl()$ though, in order to +guarantee a uniform interface to the audio-player software.) + +\subsection{$Int\ dev_ioctl(struct\ cdrom_device_info * cdi, unsigned\ int\ + cmd, unsigned\ long\ arg)$} + +Some $ioctl$s seem to be specific to certain \cdrom\ drives. That is, +they are introduced to service some capabilities of certain drives. In +fact, there are 6 different $ioctl$s for reading data, either in some +particular kind of format, or audio data. Not many drives support +reading audio tracks as data, I believe this is because of protection +of copyrights of artists. Moreover, I think that if audio-tracks are +supported, it should be done through the VFS and not via $ioctl$s. A +problem here could be the fact that audio-frames are 2352 bytes long, +so either the audio-file-system should ask for 75264 bytes at once +(the least common multiple of 512 and 2352), or the drivers should +bend their backs to cope with this incoherence (to which I would be +opposed). Furthermore, it is very difficult for the hardware to find +the exact frame boundaries, since there are no synchronization headers +in audio frames. Once these issues are resolved, this code should be +standardized in \cdromc. + +Because there are so many $ioctl$s that seem to be introduced to +satisfy certain drivers,\footnote{Is there software around that + actually uses these? I'd be interested!} any `non-standard' $ioctl$s +are routed through the call $dev_ioctl()$. In principle, `private' +$ioctl$s should be numbered after the device's major number, and not +the general \cdrom\ $ioctl$ number, {\tt {0x53}}. Currently the +non-supported $ioctl$s are: {\it CDROMREADMODE1, CDROMREADMODE2, + CDROMREADAUDIO, CDROMREADRAW, CDROMREADCOOKED, CDROMSEEK, + CDROMPLAY\-BLK and CDROM\-READALL}. + + +\subsection{\cdrom\ capabilities} +\label{capability} + +Instead of just implementing some $ioctl$ calls, the interface in +\cdromc\ supplies the possibility to indicate the {\em capabilities\/} +of a \cdrom\ drive. This can be done by ORing any number of +capability-constants that are defined in \cdromh\ at the registration +phase. Currently, the capabilities are any of: +$$ +\halign{$#$\ \hfil&$/*$ \rm# $*/$\hfil\cr +CDC_CLOSE_TRAY& can close tray by software control\cr +CDC_OPEN_TRAY& can open tray\cr +CDC_LOCK& can lock and unlock the door\cr +CDC_SELECT_SPEED& can select speed, in units of $\sim$150\,kB/s\cr +CDC_SELECT_DISC& drive is juke-box\cr +CDC_MULTI_SESSION& can read sessions $>\rm1$\cr +CDC_MCN& can read Media Catalog Number\cr +CDC_MEDIA_CHANGED& can report if disc has changed\cr +CDC_PLAY_AUDIO& can perform audio-functions (play, pause, etc)\cr +CDC_RESET& hard reset device\cr +CDC_IOCTLS& driver has non-standard ioctls\cr +CDC_DRIVE_STATUS& driver implements drive status\cr +} +$$ +The capability flag is declared $const$, to prevent drivers from +accidentally tampering with the contents. The capability fags actually +inform \cdromc\ of what the driver can do. If the drive found +by the driver does not have the capability, is can be masked out by +the $cdrom_device_info$ variable $mask$. For instance, the SCSI \cdrom\ +driver has implemented the code for loading and ejecting \cdrom's, and +hence its corresponding flags in $capability$ will be set. But a SCSI +\cdrom\ drive might be a caddy system, which can't load the tray, and +hence for this drive the $cdrom_device_info$ struct will have set +the $CDC_CLOSE_TRAY$ bit in $mask$. + +In the file \cdromc\ you will encounter many constructions of the type +$$\it +if\ (cdo\rightarrow capability \mathrel\& \mathord{\sim} cdi\rightarrow mask + \mathrel{\&} CDC_<capability>) \ldots +$$ +There is no $ioctl$ to set the mask\dots The reason is that +I think it is better to control the {\em behavior\/} rather than the +{\em capabilities}. + +\subsection{Options} + +A final flag register controls the {\em behavior\/} of the \cdrom\ +drives, in order to satisfy different users' wishes, hopefully +independently of the ideas of the respective author who happened to +have made the drive's support available to the \linux\ community. The +current behavior options are: +$$ +\halign{$#$\ \hfil&$/*$ \rm# $*/$\hfil\cr +CDO_AUTO_CLOSE& try to close tray upon device $open()$\cr +CDO_AUTO_EJECT& try to open tray on last device $close()$\cr +CDO_USE_FFLAGS& use $file_pointer\rightarrow f_flags$ to indicate + purpose for $open()$\cr +CDO_LOCK& try to lock door if device is opened\cr +CDO_CHECK_TYPE& ensure disc type is data if opened for data\cr +} +$$ + +The initial value of this register is $CDO_AUTO_CLOSE \mathrel| +CDO_USE_FFLAGS \mathrel| CDO_LOCK$, reflecting my own view on user +interface and software standards. Before you protest, there are two +new $ioctl$s implemented in \cdromc, that allow you to control the +behavior by software. These are: +$$ +\halign{$#$\ \hfil&$/*$ \rm# $*/$\hfil\cr +CDROM_SET_OPTIONS& set options specified in $(int)\ arg$\cr +CDROM_CLEAR_OPTIONS& clear options specified in $(int)\ arg$\cr +} +$$ +One option needs some more explanation: $CDO_USE_FFLAGS$. In the next +newsection we explain what the need for this option is. + +A software package {\tt setcd}, available from the Debian distribution +and {\tt sunsite.unc.edu}, allows user level control of these flags. + +\newsection{The need to know the purpose of opening the \cdrom\ device} + +Traditionally, Unix devices can be used in two different `modes', +either by reading/writing to the device file, or by issuing +controlling commands to the device, by the device's $ioctl()$ +call. The problem with \cdrom\ drives, is that they can be used for +two entirely different purposes. One is to mount removable +file systems, \cdrom s, the other is to play audio CD's. Audio commands +are implemented entirely through $ioctl$s, presumably because the +first implementation (SUN?) has been such. In principle there is +nothing wrong with this, but a good control of the `CD player' demands +that the device can {\em always\/} be opened in order to give the +$ioctl$ commands, regardless of the state the drive is in. + +On the other hand, when used as a removable-media disc drive (what the +original purpose of \cdrom s is) we would like to make sure that the +disc drive is ready for operation upon opening the device. In the old +scheme, some \cdrom\ drivers don't do any integrity checking, resulting +in a number of i/o errors reported by the VFS to the kernel when an +attempt for mounting a \cdrom\ on an empty drive occurs. This is not a +particularly elegant way to find out that there is no \cdrom\ inserted; +it more-or-less looks like the old IBM-PC trying to read an empty floppy +drive for a couple of seconds, after which the system complains it +can't read from it. Nowadays we can {\em sense\/} the existence of a +removable medium in a drive, and we believe we should exploit that +fact. An integrity check on opening of the device, that verifies the +availability of a \cdrom\ and its correct type (data), would be +desirable. + +These two ways of using a \cdrom\ drive, principally for data and +secondarily for playing audio discs, have different demands for the +behavior of the $open()$ call. Audio use simply wants to open the +device in order to get a file handle which is needed for issuing +$ioctl$ commands, while data use wants to open for correct and +reliable data transfer. The only way user programs can indicate what +their {\em purpose\/} of opening the device is, is through the $flags$ +parameter (see {\tt {open(2)}}). For \cdrom\ devices, these flags aren't +implemented (some drivers implement checking for write-related flags, +but this is not strictly necessary if the device file has correct +permission flags). Most option flags simply don't make sense to +\cdrom\ devices: $O_CREAT$, $O_NOCTTY$, $O_TRUNC$, $O_APPEND$, and +$O_SYNC$ have no meaning to a \cdrom. + +We therefore propose to use the flag $O_NONBLOCK$ to indicate +that the device is opened just for issuing $ioctl$ +commands. Strictly, the meaning of $O_NONBLOCK$ is that opening and +subsequent calls to the device don't cause the calling process to +wait. We could interpret this as ``don't wait until someone has +inserted some valid data-\cdrom.'' Thus, our proposal of the +implementation for the $open()$ call for \cdrom s is: +\begin{itemize} +\item If no other flags are set than $O_RDONLY$, the device is opened +for data transfer, and the return value will be 0 only upon successful +initialization of the transfer. The call may even induce some actions +on the \cdrom, such as closing the tray. +\item If the option flag $O_NONBLOCK$ is set, opening will always be +successful, unless the whole device doesn't exist. The drive will take +no actions whatsoever. +\end{itemize} + +\subsection{And what about standards?} + +You might hesitate to accept this proposal as it comes from the +\linux\ community, and not from some standardizing institute. What +about SUN, SGI, HP and all those other Unix and hardware vendors? +Well, these companies are in the lucky position that they generally +control both the hardware and software of their supported products, +and are large enough to set their own standard. They do not have to +deal with a dozen or more different, competing hardware +configurations.\footnote{Incidentally, I think that SUN's approach to +mounting \cdrom s is very good in origin: under Solaris a +volume-daemon automatically mounts a newly inserted \cdrom\ under {\tt +{/cdrom/$<volume-name>$/}}. In my opinion they should have pushed this +further and have {\em every\/} \cdrom\ on the local area network be +mounted at the similar location, \ie, no matter in which particular +machine you insert a \cdrom, it will always appear at the same +position in the directory tree, on every system. When I wanted to +implement such a user-program for \linux, I came across the +differences in behavior of the various drivers, and the need for an +$ioctl$ informing about media changes.} + +We believe that using $O_NONBLOCK$ to indicate that a device is being opened +for $ioctl$ commands only can be easily introduced in the \linux\ +community. All the CD-player authors will have to be informed, we can +even send in our own patches to the programs. The use of $O_NONBLOCK$ +has most likely no influence on the behavior of the CD-players on +other operating systems than \linux. Finally, a user can always revert +to old behavior by a call to $ioctl(file_descriptor, CDROM_CLEAR_OPTIONS, +CDO_USE_FFLAGS)$. + +\subsection{The preferred strategy of $open()$} + +The routines in \cdromc\ are designed in such a way that run-time +configuration of the behavior of \cdrom\ devices (of {\em any\/} type) +can be carried out, by the $CDROM_SET/CLEAR_OPTIONS$ $ioctls$. Thus, various +modes of operation can be set: +\begin{description} +\item[$CDO_AUTO_CLOSE \mathrel| CDO_USE_FFLAGS \mathrel| CDO_LOCK$] This +is the default setting. (With $CDO_CHECK_TYPE$ it will be better, in the +future.) If the device is not yet opened by any other process, and if +the device is being opened for data ($O_NONBLOCK$ is not set) and the +tray is found to be open, an attempt to close the tray is made. Then, +it is verified that a disc is in the drive and, if $CDO_CHECK_TYPE$ is +set, that it contains tracks of type `data mode 1.' Only if all tests +are passed is the return value zero. The door is locked to prevent file +system corruption. If the drive is opened for audio ($O_NONBLOCK$ is +set), no actions are taken and a value of 0 will be returned. +\item[$CDO_AUTO_CLOSE \mathrel| CDO_AUTO_EJECT \mathrel| CDO_LOCK$] This +mimics the behavior of the current sbpcd-driver. The option flags are +ignored, the tray is closed on the first open, if necessary. Similarly, +the tray is opened on the last release, \ie, if a \cdrom\ is unmounted, +it is automatically ejected, such that the user can replace it. +\end{description} +We hope that these option can convince everybody (both driver +maintainers and user program developers) to adopt the new \cdrom\ +driver scheme and option flag interpretation. + +\newsection{Description of routines in \cdromc} + +Only a few routines in \cdromc\ are exported to the drivers. In this +new section we will discuss these, as well as the functions that `take +over' the \cdrom\ interface to the kernel. The header file belonging +to \cdromc\ is called \cdromh. Formerly, some of the contents of this +file were placed in the file {\tt {ucdrom.h}}, but this file has now been +merged back into \cdromh. + +\subsection{$Struct\ file_operations\ cdrom_fops$} + +The contents of this structure were described in section~\ref{cdrom.c}. +A pointer to this structure is assigned to the $fops$ field +of the $struct gendisk$. + +\subsection{$Int\ register_cdrom( struct\ cdrom_device_info\ * cdi)$} + +This function is used in about the same way one registers $cdrom_fops$ +with the kernel, the device operations and information structures, +as described in section~\ref{cdrom.c}, should be registered with the +\UCD: +$$ +register_cdrom(\&<device>_info)); +$$ +This function returns zero upon success, and non-zero upon +failure. The structure $<device>_info$ should have a pointer to the +driver's $<device>_dops$, as in +$$ +\vbox{\halign{&$#$\hfil\cr +struct\ &cdrom_device_info\ <device>_info = \{\cr +& <device>_dops;\cr +&\ldots\cr +\}\cr +}}$$ +Note that a driver must have one static structure, $<device>_dops$, while +it may have as many structures $<device>_info$ as there are minor devices +active. $Register_cdrom()$ builds a linked list from these. + +\subsection{$Int\ unregister_cdrom(struct\ cdrom_device_info * cdi)$} + +Unregistering device $cdi$ with minor number $MINOR(cdi\to dev)$ removes +the minor device from the list. If it was the last registered minor for +the low-level driver, this disconnects the registered device-operation +routines from the \cdrom\ interface. This function returns zero upon +success, and non-zero upon failure. + +\subsection{$Int\ cdrom_open(struct\ inode * ip, struct\ file * fp)$} + +This function is not called directly by the low-level drivers, it is +listed in the standard $cdrom_fops$. If the VFS opens a file, this +function becomes active. A strategy is implemented in this routine, +taking care of all capabilities and options that are set in the +$cdrom_device_ops$ connected to the device. Then, the program flow is +transferred to the device_dependent $open()$ call. + +\subsection{$Void\ cdrom_release(struct\ inode *ip, struct\ file +*fp)$} + +This function implements the reverse-logic of $cdrom_open()$, and then +calls the device-dependent $release()$ routine. When the use-count has +reached 0, the allocated buffers are flushed by calls to $sync_dev(dev)$ +and $invalidate_buffers(dev)$. + + +\subsection{$Int\ cdrom_ioctl(struct\ inode *ip, struct\ file *fp, +unsigned\ int\ cmd, unsigned\ long\ arg)$} +\label{cdrom-ioctl} + +This function handles all the standard $ioctl$ requests for \cdrom\ +devices in a uniform way. The different calls fall into three +categories: $ioctl$s that can be directly implemented by device +operations, ones that are routed through the call $audio_ioctl()$, and +the remaining ones, that are presumable device-dependent. Generally, a +negative return value indicates an error. + +\subsubsection{Directly implemented $ioctl$s} +\label{ioctl-direct} + +The following `old' \cdrom-$ioctl$s are implemented by directly +calling device-operations in $cdrom_device_ops$, if implemented and +not masked: +\begin{description} +\item[CDROMMULTISESSION] Requests the last session on a \cdrom. +\item[CDROMEJECT] Open tray. +\item[CDROMCLOSETRAY] Close tray. +\item[CDROMEJECT_SW] If $arg\not=0$, set behavior to auto-close (close +tray on first open) and auto-eject (eject on last release), otherwise +set behavior to non-moving on $open()$ and $release()$ calls. +\item[CDROM_GET_MCN] Get the Media Catalog Number from a CD. +\end{description} + +\subsubsection{$Ioctl$s routed through $audio_ioctl()$} +\label{ioctl-audio} + +The following set of $ioctl$s are all implemented through a call to +the $cdrom_fops$ function $audio_ioctl()$. Memory checks and +allocation are performed in $cdrom_ioctl()$, and also sanitization of +address format ($CDROM_LBA$/$CDROM_MSF$) is done. +\begin{description} +\item[CDROMSUBCHNL] Get sub-channel data in argument $arg$ of type $struct\ +cdrom_subchnl *{}$. +\item[CDROMREADTOCHDR] Read Table of Contents header, in $arg$ of type +$struct\ cdrom_tochdr *{}$. +\item[CDROMREADTOCENTRY] Read a Table of Contents entry in $arg$ and +specified by $arg$ of type $struct\ cdrom_tocentry *{}$. +\item[CDROMPLAYMSF] Play audio fragment specified in Minute, Second, +Frame format, delimited by $arg$ of type $struct\ cdrom_msf *{}$. +\item[CDROMPLAYTRKIND] Play audio fragment in track-index format +delimited by $arg$ of type $struct\ \penalty-1000 cdrom_ti *{}$. +\item[CDROMVOLCTRL] Set volume specified by $arg$ of type $struct\ +cdrom_volctrl *{}$. +\item[CDROMVOLREAD] Read volume into by $arg$ of type $struct\ +cdrom_volctrl *{}$. +\item[CDROMSTART] Spin up disc. +\item[CDROMSTOP] Stop playback of audio fragment. +\item[CDROMPAUSE] Pause playback of audio fragment. +\item[CDROMRESUME] Resume playing. +\end{description} + +\subsubsection{New $ioctl$s in \cdromc} + +The following $ioctl$s have been introduced to allow user programs to +control the behavior of individual \cdrom\ devices. New $ioctl$ +commands can be identified by the underscores in their names. +\begin{description} +\item[CDROM_SET_OPTIONS] Set options specified by $arg$. Returns the +option flag register after modification. Use $arg = \rm0$ for reading +the current flags. +\item[CDROM_CLEAR_OPTIONS] Clear options specified by $arg$. Returns + the option flag register after modification. +\item[CDROM_SELECT_SPEED] Select head-rate speed of disc specified as + by $arg$ in units of standard cdrom speed (176\,kB/sec raw data or + 150\,kB/sec file system data). The value 0 means `auto-select', \ie, + play audio discs at real time and data discs at maximum speed. The value + $arg$ is checked against the maximum head rate of the drive found in the + $cdrom_dops$. +\item[CDROM_SELECT_DISC] Select disc numbered $arg$ from a juke-box. + First disc is numbered 0. The number $arg$ is checked against the + maximum number of discs in the juke-box found in the $cdrom_dops$. +\item[CDROM_MEDIA_CHANGED] Returns 1 if a disc has been changed since + the last call. Note that calls to $cdrom_media_changed$ by the VFS + are treated by an independent queue, so both mechanisms will detect + a media change once. For juke-boxes, an extra argument $arg$ + specifies the slot for which the information is given. The special + value $CDSL_CURRENT$ requests that information about the currently + selected slot be returned. +\item[CDROM_DRIVE_STATUS] Returns the status of the drive by a call to + $drive_status()$. Return values are defined in section~\ref{drive + status}. Note that this call doesn't return information on the + current playing activity of the drive; this can be polled through an + $ioctl$ call to $CDROMSUBCHNL$. For juke-boxes, an extra argument + $arg$ specifies the slot for which (possibly limited) information is + given. The special value $CDSL_CURRENT$ requests that information + about the currently selected slot be returned. +\item[CDROM_DISC_STATUS] Returns the type of the disc currently in the + drive. It should be viewed as a complement to $CDROM_DRIVE_STATUS$. + This $ioctl$ can provide \emph {some} information about the current + disc that is inserted in the drive. This functionality used to be + implemented in the low level drivers, but is now carried out + entirely in \UCD. + + The history of development of the CD's use as a carrier medium for + various digital information has lead to many different disc types. + This $ioctl$ is useful only in the case that CDs have \emph {only + one} type of data on them. While this is often the case, it is + also very common for CDs to have some tracks with data, and some + tracks with audio. Because this is an existing interface, rather + than fixing this interface by changing the assumptions it was made + under, thereby breaking all user applications that use this + function, the \UCD\ implements this $ioctl$ as follows: If the CD in + question has audio tracks on it, and it has absolutely no CD-I, XA, + or data tracks on it, it will be reported as $CDS_AUDIO$. If it has + both audio and data tracks, it will return $CDS_MIXED$. If there + are no audio tracks on the disc, and if the CD in question has any + CD-I tracks on it, it will be reported as $CDS_XA_2_2$. Failing + that, if the CD in question has any XA tracks on it, it will be + reported as $CDS_XA_2_1$. Finally, if the CD in question has any + data tracks on it, it will be reported as a data CD ($CDS_DATA_1$). + + This $ioctl$ can return: + $$ + \halign{$#$\ \hfil&$/*$ \rm# $*/$\hfil\cr + CDS_NO_INFO& no information available\cr + CDS_NO_DISC& no disc is inserted, or tray is opened\cr + CDS_AUDIO& Audio disc (2352 audio bytes/frame)\cr + CDS_DATA_1& data disc, mode 1 (2048 user bytes/frame)\cr + CDS_XA_2_1& mixed data (XA), mode 2, form 1 (2048 user bytes)\cr + CDS_XA_2_2& mixed data (XA), mode 2, form 1 (2324 user bytes)\cr + CDS_MIXED& mixed audio/data disc\cr + } + $$ + For some information concerning frame layout of the various disc + types, see a recent version of \cdromh. + +\item[CDROM_CHANGER_NSLOTS] Returns the number of slots in a + juke-box. +\item[CDROMRESET] Reset the drive. +\item[CDROM_GET_CAPABILITY] Returns the $capability$ flags for the + drive. Refer to section \ref{capability} for more information on + these flags. +\item[CDROM_LOCKDOOR] Locks the door of the drive. $arg == \rm0$ + unlocks the door, any other value locks it. +\item[CDROM_DEBUG] Turns on debugging info. Only root is allowed + to do this. Same semantics as CDROM_LOCKDOOR. +\end{description} + +\subsubsection{Device dependent $ioctl$s} + +Finally, all other $ioctl$s are passed to the function $dev_ioctl()$, +if implemented. No memory allocation or verification is carried out. + +\newsection{How to update your driver} + +\begin{enumerate} +\item Make a backup of your current driver. +\item Get hold of the files \cdromc\ and \cdromh, they should be in + the directory tree that came with this documentation. +\item Make sure you include \cdromh. +\item Change the 3rd argument of $register_blkdev$ from +$\&<your-drive>_fops$ to $\&cdrom_fops$. +\item Just after that line, add the following to register with the \UCD: + $$register_cdrom(\&<your-drive>_info);$$ + Similarly, add a call to $unregister_cdrom()$ at the appropriate place. +\item Copy an example of the device-operations $struct$ to your + source, \eg, from {\tt {cm206.c}} $cm206_dops$, and change all + entries to names corresponding to your driver, or names you just + happen to like. If your driver doesn't support a certain function, + make the entry $NULL$. At the entry $capability$ you should list all + capabilities your driver currently supports. If your driver + has a capability that is not listed, please send me a message. +\item Copy the $cdrom_device_info$ declaration from the same example + driver, and modify the entries according to your needs. If your + driver dynamically determines the capabilities of the hardware, this + structure should also be declared dynamically. +\item Implement all functions in your $<device>_dops$ structure, + according to prototypes listed in \cdromh, and specifications given + in section~\ref{cdrom.c}. Most likely you have already implemented + the code in a large part, and you will almost certainly need to adapt the + prototype and return values. +\item Rename your $<device>_ioctl()$ function to $audio_ioctl$ and + change the prototype a little. Remove entries listed in the first + part in section~\ref{cdrom-ioctl}, if your code was OK, these are + just calls to the routines you adapted in the previous step. +\item You may remove all remaining memory checking code in the + $audio_ioctl()$ function that deals with audio commands (these are + listed in the second part of section~\ref{cdrom-ioctl}). There is no + need for memory allocation either, so most $case$s in the $switch$ + statement look similar to: + $$ + case\ CDROMREADTOCENTRY\colon get_toc_entry\bigl((struct\ + cdrom_tocentry *{})\ arg\bigr); + $$ +\item All remaining $ioctl$ cases must be moved to a separate + function, $<device>_ioctl$, the device-dependent $ioctl$s. Note that + memory checking and allocation must be kept in this code! +\item Change the prototypes of $<device>_open()$ and + $<device>_release()$, and remove any strategic code (\ie, tray + movement, door locking, etc.). +\item Try to recompile the drivers. We advise you to use modules, both + for {\tt {cdrom.o}} and your driver, as debugging is much easier this + way. +\end{enumerate} + +\newsection{Thanks} + +Thanks to all the people involved. First, Erik Andersen, who has +taken over the torch in maintaining \cdromc\ and integrating much +\cdrom-related code in the 2.1-kernel. Thanks to Scott Snyder and +Gerd Knorr, who were the first to implement this interface for SCSI +and IDE-CD drivers and added many ideas for extension of the data +structures relative to kernel~2.0. Further thanks to Heiko Eissfeldt, +Thomas Quinot, Jon Tombs, Ken Pizzini, Eberhard M\"onkeberg and Andrew +Kroll, the \linux\ \cdrom\ device driver developers who were kind +enough to give suggestions and criticisms during the writing. Finally +of course, I want to thank Linus Torvalds for making this possible in +the first place. + +\vfill +$ \version\ $ +\eject +\end{document} diff --git a/Documentation/cdrom/cdu31a b/Documentation/cdrom/cdu31a new file mode 100644 index 000000000000..c0667da09c00 --- /dev/null +++ b/Documentation/cdrom/cdu31a @@ -0,0 +1,196 @@ + + CDU31A/CDU33A Driver Info + ------------------------- + +Information on the Sony CDU31A/CDU33A CDROM driver for the Linux +kernel. + + Corey Minyard (minyard@metronet.com) + + Colossians 3:17 + +Crude Table of Contents +----------------------- + + Setting Up the Hardware + Configuring the Kernel + Configuring as a Module + Driver Special Features + + +This device driver handles Sony CDU31A/CDU33A CDROM drives and +provides a complete block-level interface as well as an ioctl() +interface as specified in include/linux/cdrom.h). With this +interface, CDROMs can be accessed, standard audio CDs can be played +back normally, and CD audio information can be read off the drive. + +Note that this will only work for CDU31A/CDU33A drives. Some vendors +market their drives as CDU31A compatible. They lie. Their drives are +really CDU31A hardware interface compatible (they can plug into the +same card). They are not software compatible. + +Setting Up the Hardware +----------------------- + +The CDU31A driver is unable to safely tell if an interface card is +present that it can use because the interface card does not announce +its presence in any way besides placing 4 I/O locations in memory. It +used to just probe memory and attempt commands, but Linus wisely asked +me to remove that because it could really screw up other hardware in +the system. + +Because of this, you must tell the kernel where the drive interface +is, what interrupts are used, and possibly if you are on a PAS-16 +soundcard. + +If you have the Sony CDU31A/CDU33A drive interface card, the following +diagram will help you set it up. If you have another card, you are on +your own. You need to make sure that the I/O address and interrupt is +not used by another card in the system. You will need to know the I/O +address and interrupt you have set. Note that use of interrupts is +highly recommended, if possible, it really cuts down on CPU used. +Unfortunately, most soundcards do not support interrupts for their +CDROM interfaces. By default, the Sony interface card comes with +interrupts disabled. + + +----------+-----------------+----------------------+ + | JP1 | 34 Pin Conn | | + | JP2 +-----------------+ | + | JP3 | + | JP4 | + | +--+ + | | +-+ + | | | | External + | | | | Connector + | | | | + | | +-+ + | +--+ + | | + | +--------+ + | | + +------------------------------------------+ + + JP1 sets the Base Address, using the following settings: + + Address Pin 1 Pin 2 + ------- ----- ----- + 0x320 Short Short + 0x330 Short Open + 0x340 Open Short + 0x360 Open Open + + JP2 and JP3 configure the DMA channel; they must be set the same. + + DMA Pin 1 Pin 2 Pin 3 + --- ----- ----- ----- + 1 On Off On + 2 Off On Off + 3 Off Off On + + JP4 Configures the IRQ: + + IRQ Pin 1 Pin 2 Pin 3 Pin 4 + --- ----- ----- ----- ----- + 3 Off Off On Off + 4 Off Off* Off On + 5 On Off Off Off + 6 Off On Off Off + + The documentation states to set this for interrupt + 4, but I think that is a mistake. + +Note that if you have another interface card, you will need to look at +the documentation to find the I/O base address. This is specified to +the SLCD.SYS driver for DOS with the /B: parameter, so you can look at +you DOS driver setup to find the address, if necessary. + +Configuring the Kernel +---------------------- + +You must tell the kernel where the drive is at boot time. This can be +done at the Linux boot prompt, by using LILO, or by using Bootlin. +Note that this is no substitute for HOWTOs and LILO documentation, if +you are confused please read those for info on bootline configuration +and LILO. + +At the linux boot prompt, press the ALT key and add the following line +after the boot name (you can let the kernel boot, it will tell you the +default boot name while booting): + + cdu31a=<base address>,<interrupt>[,PAS] + +The base address needs to have "0x" in front of it, since it is in +hex. For instance, to configure a drive at address 320 on interrupt 5, +use the following: + + cdu31a=0x320,5 + +I use the following boot line: + + cdu31a=0x1f88,0,PAS + +because I have a PAS-16 which does not support interrupt for the +CDU31A interface. + +Adding this as an append line at the beginning of the /etc/lilo.conf +file will set it for lilo configurations. I have the following as the +first line in my lilo.conf file: + + append="cdu31a=0x1f88,0" + +I'm not sure how to set up Bootlin (I have never used it), if someone +would like to fill in this section please do. + + +Configuring as a Module +----------------------- + +The driver supports loading as a module. However, you must specify +the boot address and interrupt on the boot line to insmod. You can't +use modprobe to load it, since modprobe doesn't support setting +variables. + +Anyway, I use the following line to load my driver as a module + + /sbin/insmod /lib/modules/`uname -r`/misc/cdu31a.o cdu31a_port=0x1f88 + +You can set the following variables in the driver: + + cdu31a_port=<I/O address> - sets the base I/O. If hex, put 0x in + front of it. This must be specified. + + cdu31a_irq=<interrupt> - Sets the interrupt number. Leaving this + off will turn interrupts off. + + +Driver Special Features +----------------------- + +This section describes features beyond the normal audio and CD-ROM +functions of the drive. + +2048 byte buffer mode + +If a disk is mounted with -o block=2048, data is copied straight from +the drive data port to the buffer. Otherwise, the readahead buffer +must be involved to hold the other 1K of data when a 1K block +operation is done. Note that with 2048 byte blocks you cannot execute +files from the CD. + +XA compatibility + +The driver should support XA disks for both the CDU31A and CDU33A. It +does this transparently, the using program doesn't need to set it. + +Multi-Session + +A multi-session disk looks just like a normal disk to the user. Just +mount one normally, and all the data should be there. A special +thanks to Koen for help with this! + +Raw sector I/O + +Using the CDROMREADAUDIO it is possible to read raw audio and data +tracks. Both operations return 2352 bytes per sector. On the data +tracks, the first 12 bytes is not returned by the drive and the value +of that data is indeterminate. diff --git a/Documentation/cdrom/cm206 b/Documentation/cdrom/cm206 new file mode 100644 index 000000000000..810368f4f7c4 --- /dev/null +++ b/Documentation/cdrom/cm206 @@ -0,0 +1,185 @@ +This is the readme file for the driver for the Philips/LMS cdrom drive +cm206 in combination with the cm260 host adapter card. + + (c) 1995 David A. van Leeuwen + +Changes since version 0.99 +-------------------------- +- Interfacing to the kernel is routed though an extra interface layer, + cdrom.c. This allows runtime-configurable `behavior' of the cdrom-drive, + independent of the driver. + +Features since version 0.33 +--------------------------- +- Full audio support, that is, both workman, workbone and cdp work + now reasonably. Reading TOC still takes some time. xmcd has been + reported to run successfully. +- Made auto-probe code a little better, I hope + +Features since version 0.28 +--------------------------- +- Full speed transfer rate (300 kB/s). +- Minimum kernel memory usage for buffering (less than 3 kB). +- Multisession support. +- Tray locking. +- Statistics of driver accessible to the user. +- Module support. +- Auto-probing of adapter card's base port and irq line, + also configurable at boot time or module load time. + + +Decide how you are going to use the driver. There are two +options: + + (a) installing the driver as a resident part of the kernel + (b) compiling the driver as a loadable module + + Further, you must decide if you are going to specify the base port + address and the interrupt request line of the adapter card cm260 as + boot options for (a), module parameters for (b), use automatic + probing of these values, or hard-wire your adaptor card's settings + into the source code. If you don't care, you can choose + autoprobing, which is the default. In that case you can move on to + the next step. + +Compiling the kernel +-------------------- +1) move to /usr/src/linux and do a + + make config + + If you have chosen option (a), answer yes to CONFIG_CM206 and + CONFIG_ISO9660_FS. + + If you have chosen option (b), answer yes to CONFIG_MODVERSIONS + and no (!) to CONFIG_CM206 and CONFIG_ISO9660_FS. + +2) then do a + + make clean; make zImage; make modules + +3) do the usual things to install a new image (backup the old one, run + `rdev -R zImage 1', copy the new image in place, run lilo). Might + be `make zlilo'. + +Using the driver as a module +---------------------------- +If you will only occasionally use the cd-rom driver, you can choose +option (b), install as a loadable module. You may have to re-compile +the module when you upgrade the kernel to a new version. + +Since version 0.96, much of the functionality has been transferred to +a generic cdrom interface in the file cdrom.c. The module cm206.o +depends on cdrom.o. If the latter is not compiled into the kernel, +you must explicitly load it before cm206.o: + + insmod /usr/src/linux/modules/cdrom.o + +To install the module, you use the command, as root + + insmod /usr/src/linux/modules/cm206.o + +You can specify the base address on the command line as well as the irq +line to be used, e.g. + + insmod /usr/src/linux/modules/cm206.o cm206=0x300,11 + +The order of base port and irq line doesn't matter; if you specify only +one, the other will have the value of the compiled-in default. You +may also have to install the file-system module `iso9660.o', if you +didn't compile that into the kernel. + + +Using the driver as part of the kernel +-------------------------------------- +If you have chosen option (a), you can specify the base-port +address and irq on the lilo boot command line, e.g.: + + LILO: linux cm206=0x340,11 + +This assumes that your linux kernel image keyword is `linux'. +If you specify either IRQ (3--11) or base port (0x300--0x370), +auto probing is turned off for both settings, thus setting the +other value to the compiled-in default. + +Note that you can also put these parameters in the lilo configuration file: + +# linux config +image = /vmlinuz + root = /dev/hda1 + label = Linux + append = "cm206=0x340,11" + read-only + + +If module parameters and LILO config options don't work +------------------------------------------------------- +If autoprobing does not work, you can hard-wire the default values +of the base port address (CM206_BASE) and interrupt request line +(CM206_IRQ) into the file /usr/src/linux/drivers/cdrom/cm206.h. Change +the defines of CM206_IRQ and CM206_BASE. + + +Mounting the cdrom +------------------ +1) Make sure that the right device is installed in /dev. + + mknod /dev/cm206cd b 32 0 + +2) Make sure there is a mount point, e.g., /cdrom + + mkdir /cdrom + +3) mount using a command like this (run as root): + + mount -rt iso9660 /dev/cm206cd /cdrom + +4) For user-mounts, add a line in /etc/fstab + + /dev/cm206cd /cdrom iso9660 ro,noauto,user + + This will allow users to give the commands + + mount /cdrom + umount /cdrom + +If things don't work +-------------------- + +- Try to do a `dmesg' to find out if the driver said anything about + what is going wrong during the initialization. + +- Try to do a `dd if=/dev/cm206cd | od -tc | less' to read from the + CD. + +- Look in the /proc directory to see if `cm206' shows up under one of + `interrupts', `ioports', `devices' or `modules' (if applicable). + + +DISCLAIMER +---------- +I cannot guarantee that this driver works, or that the hardware will +not be harmed, although I consider it most unlikely. + +I hope that you'll find this driver in some way useful. + + David van Leeuwen + david@tm.tno.nl + +Note for Linux CDROM vendors +----------------------------- +You are encouraged to include this driver on your Linux CDROM. If +you do, you might consider sending me a free copy of that cd-rom. +You can contact me through my e-mail address, david@tm.tno.nl. +If this driver is compiled into a kernel to boot off a cdrom, +you should actually send me a free copy of that cd-rom. + +Copyright +--------- +The copyright of the cm206 driver for Linux is + + (c) 1995 David A. van Leeuwen + +The driver is released under the conditions of the GNU general public +license, which can be found in the file COPYING in the root of this +source tree. diff --git a/Documentation/cdrom/gscd b/Documentation/cdrom/gscd new file mode 100644 index 000000000000..d01ca36b5c43 --- /dev/null +++ b/Documentation/cdrom/gscd @@ -0,0 +1,60 @@ + Goldstar R420 CD-Rom device driver README + +For all kind of other information about the GoldStar R420 CDROM +and this Linux device driver see the WWW page: + + http://linux.rz.fh-hannover.de/~raupach + + + If you are the editor of a Linux CD, you should + enable gscd.c within your boot floppy kernel. Please, + send me one of your CDs for free. + + +This current driver version 0.4a only supports reading data from the disk. +Currently we have no audio and no multisession or XA support. +The polling interface is used, no DMA. + + +Sometimes the GoldStar R420 is sold in a 'Reveal Multimedia Kit'. This kit's +drive interface is compatible, too. + + +Installation +------------ + +Change to '/usr/src/linux/drivers/cdrom' and edit the file 'gscd.h'. Insert +the i/o address of your interface card. + +The default base address is 0x340. This will work for most applications. +Address selection is accomplished by jumpers PN801-1 to PN801-4 on the +GoldStar Interface Card. +Appropriate settings are: 0x300, 0x310, 0x320, 0x330, 0x340, 0x350, 0x360 +0x370, 0x380, 0x390, 0x3A0, 0x3B0, 0x3C0, 0x3D0, 0x3E0, 0x3F0 + +Then go back to '/usr/src/linux/' and 'make config' to build the new +configuration for your kernel. If you want to use the GoldStar driver +like a module, don't select 'GoldStar CDROM support'. By the way, you +have to include the iso9660 filesystem. + +Now start compiling the kernel with 'make zImage'. +If you want to use the driver as a module, you have to do 'make modules' +and 'make modules_install', additionally. +Install your new kernel as usual - maybe you do it with 'make zlilo'. + +Before you can use the driver, you have to + mknod /dev/gscd0 b 16 0 +to create the appropriate device file (you only need to do this once). + +If you use modules, you can try to insert the driver. +Say: 'insmod /usr/src/linux/modules/gscd.o' +or: 'insmod /usr/src/linux/modules/gscd.o gscd=<address>' +The driver should report its results. + +That's it! Mount a disk, i.e. 'mount -rt iso9660 /dev/gscd0 /cdrom' + +Feel free to report errors and suggestions to the following address. +Be sure, I'm very happy to receive your comments! + + Oliver Raupach Hannover, Juni 1995 +(raupach@nwfs1.rz.fh-hannover.de) diff --git a/Documentation/cdrom/ide-cd b/Documentation/cdrom/ide-cd new file mode 100644 index 000000000000..29721bfcde12 --- /dev/null +++ b/Documentation/cdrom/ide-cd @@ -0,0 +1,574 @@ +IDE-CD driver documentation +Originally by scott snyder <snyder@fnald0.fnal.gov> (19 May 1996) +Carrying on the torch is: Erik Andersen <andersee@debian.org> +New maintainers (19 Oct 1998): Jens Axboe <axboe@image.dk> + +1. Introduction +--------------- + +The ide-cd driver should work with all ATAPI ver 1.2 to ATAPI 2.6 compliant +CDROM drives which attach to an IDE interface. Note that some CDROM vendors +(including Mitsumi, Sony, Creative, Aztech, and Goldstar) have made +both ATAPI-compliant drives and drives which use a proprietary +interface. If your drive uses one of those proprietary interfaces, +this driver will not work with it (but one of the other CDROM drivers +probably will). This driver will not work with `ATAPI' drives which +attach to the parallel port. In addition, there is at least one drive +(CyCDROM CR520ie) which attaches to the IDE port but is not ATAPI; +this driver will not work with drives like that either (but see the +aztcd driver). + +This driver provides the following features: + + - Reading from data tracks, and mounting ISO 9660 filesystems. + + - Playing audio tracks. Most of the CDROM player programs floating + around should work; I usually use Workman. + + - Multisession support. + + - On drives which support it, reading digital audio data directly + from audio tracks. The program cdda2wav can be used for this. + Note, however, that only some drives actually support this. + + - There is now support for CDROM changers which comply with the + ATAPI 2.6 draft standard (such as the NEC CDR-251). This additional + functionality includes a function call to query which slot is the + currently selected slot, a function call to query which slots contain + CDs, etc. A sample program which demonstrates this functionality is + appended to the end of this file. The Sanyo 3-disc changer + (which does not conform to the standard) is also now supported. + Please note the driver refers to the first CD as slot # 0. + + +2. Installation +--------------- + +0. The ide-cd relies on the ide disk driver. See + Documentation/ide.txt for up-to-date information on the ide + driver. + +1. Make sure that the ide and ide-cd drivers are compiled into the + kernel you're using. When configuring the kernel, in the section + entitled "Floppy, IDE, and other block devices", say either `Y' + (which will compile the support directly into the kernel) or `M' + (to compile support as a module which can be loaded and unloaded) + to the options: + + Enhanced IDE/MFM/RLL disk/cdrom/tape/floppy support + Include IDE/ATAPI CDROM support + + and `no' to + + Use old disk-only driver on primary interface + + Depending on what type of IDE interface you have, you may need to + specify additional configuration options. See + Documentation/ide.txt. + +2. You should also ensure that the iso9660 filesystem is either + compiled into the kernel or available as a loadable module. You + can see if a filesystem is known to the kernel by catting + /proc/filesystems. + +3. The CDROM drive should be connected to the host on an IDE + interface. Each interface on a system is defined by an I/O port + address and an IRQ number, the standard assignments being + 0x1f0 and 14 for the primary interface and 0x170 and 15 for the + secondary interface. Each interface can control up to two devices, + where each device can be a hard drive, a CDROM drive, a floppy drive, + or a tape drive. The two devices on an interface are called `master' + and `slave'; this is usually selectable via a jumper on the drive. + + Linux names these devices as follows. The master and slave devices + on the primary IDE interface are called `hda' and `hdb', + respectively. The drives on the secondary interface are called + `hdc' and `hdd'. (Interfaces at other locations get other letters + in the third position; see Documentation/ide.txt.) + + If you want your CDROM drive to be found automatically by the + driver, you should make sure your IDE interface uses either the + primary or secondary addresses mentioned above. In addition, if + the CDROM drive is the only device on the IDE interface, it should + be jumpered as `master'. (If for some reason you cannot configure + your system in this manner, you can probably still use the driver. + You may have to pass extra configuration information to the kernel + when you boot, however. See Documentation/ide.txt for more + information.) + +4. Boot the system. If the drive is recognized, you should see a + message which looks like + + hdb: NEC CD-ROM DRIVE:260, ATAPI CDROM drive + + If you do not see this, see section 5 below. + +5. You may want to create a symbolic link /dev/cdrom pointing to the + actual device. You can do this with the command + + ln -s /dev/hdX /dev/cdrom + + where X should be replaced by the letter indicating where your + drive is installed. + +6. You should be able to see any error messages from the driver with + the `dmesg' command. + + +3. Basic usage +-------------- + +An ISO 9660 CDROM can be mounted by putting the disc in the drive and +typing (as root) + + mount -t iso9660 /dev/cdrom /mnt/cdrom + +where it is assumed that /dev/cdrom is a link pointing to the actual +device (as described in step 5 of the last section) and /mnt/cdrom is +an empty directory. You should now be able to see the contents of the +CDROM under the /mnt/cdrom directory. If you want to eject the CDROM, +you must first dismount it with a command like + + umount /mnt/cdrom + +Note that audio CDs cannot be mounted. + +Some distributions set up /etc/fstab to always try to mount a CDROM +filesystem on bootup. It is not required to mount the CDROM in this +manner, though, and it may be a nuisance if you change CDROMs often. +You should feel free to remove the cdrom line from /etc/fstab and +mount CDROMs manually if that suits you better. + +Multisession and photocd discs should work with no special handling. +The hpcdtoppm package (ftp.gwdg.de:/pub/linux/hpcdtoppm/) may be +useful for reading photocds. + +To play an audio CD, you should first unmount and remove any data +CDROM. Any of the CDROM player programs should then work (workman, +workbone, cdplayer, etc.). Lacking anything else, you could use the +cdtester program in Documentation/cdrom/sbpcd. + +On a few drives, you can read digital audio directly using a program +such as cdda2wav. The only types of drive which I've heard support +this are Sony and Toshiba drives. You will get errors if you try to +use this function on a drive which does not support it. + +For supported changers, you can use the `cdchange' program (appended to +the end of this file) to switch between changer slots. Note that the +drive should be unmounted before attempting this. The program takes +two arguments: the CDROM device, and the slot number to which you wish +to change. If the slot number is -1, the drive is unloaded. + + +4. Compilation options +---------------------- + +There are a few additional options which can be set when compiling the +driver. Most people should not need to mess with any of these; they +are listed here simply for completeness. A compilation option can be +enabled by adding a line of the form `#define <option> 1' to the top +of ide-cd.c. All these options are disabled by default. + +VERBOSE_IDE_CD_ERRORS + If this is set, ATAPI error codes will be translated into textual + descriptions. In addition, a dump is made of the command which + provoked the error. This is off by default to save the memory used + by the (somewhat long) table of error descriptions. + +STANDARD_ATAPI + If this is set, the code needed to deal with certain drives which do + not properly implement the ATAPI spec will be disabled. If you know + your drive implements ATAPI properly, you can turn this on to get a + slightly smaller kernel. + +NO_DOOR_LOCKING + If this is set, the driver will never attempt to lock the door of + the drive. + +CDROM_NBLOCKS_BUFFER + This sets the size of the buffer to be used for a CDROMREADAUDIO + ioctl. The default is 8. + +TEST + This currently enables an additional ioctl which enables a user-mode + program to execute an arbitrary packet command. See the source for + details. This should be left off unless you know what you're doing. + + +5. Common problems +------------------ + +This section discusses some common problems encountered when trying to +use the driver, and some possible solutions. Note that if you are +experiencing problems, you should probably also review +Documentation/ide.txt for current information about the underlying +IDE support code. Some of these items apply only to earlier versions +of the driver, but are mentioned here for completeness. + +In most cases, you should probably check with `dmesg' for any errors +from the driver. + +a. Drive is not detected during booting. + + - Review the configuration instructions above and in + Documentation/ide.txt, and check how your hardware is + configured. + + - If your drive is the only device on an IDE interface, it should + be jumpered as master, if at all possible. + + - If your IDE interface is not at the standard addresses of 0x170 + or 0x1f0, you'll need to explicitly inform the driver using a + lilo option. See Documentation/ide.txt. (This feature was + added around kernel version 1.3.30.) + + - If the autoprobing is not finding your drive, you can tell the + driver to assume that one exists by using a lilo option of the + form `hdX=cdrom', where X is the drive letter corresponding to + where your drive is installed. Note that if you do this and you + see a boot message like + + hdX: ATAPI cdrom (?) + + this does _not_ mean that the driver has successfully detected + the drive; rather, it means that the driver has not detected a + drive, but is assuming there's one there anyway because you told + it so. If you actually try to do I/O to a drive defined at a + nonexistent or nonresponding I/O address, you'll probably get + errors with a status value of 0xff. + + - Some IDE adapters require a nonstandard initialization sequence + before they'll function properly. (If this is the case, there + will often be a separate MS-DOS driver just for the controller.) + IDE interfaces on sound cards often fall into this category. + + Support for some interfaces needing extra initialization is + provided in later 1.3.x kernels. You may need to turn on + additional kernel configuration options to get them to work; + see Documentation/ide.txt. + + Even if support is not available for your interface, you may be + able to get it to work with the following procedure. First boot + MS-DOS and load the appropriate drivers. Then warm-boot linux + (i.e., without powering off). If this works, it can be automated + by running loadlin from the MS-DOS autoexec. + + +b. Timeout/IRQ errors. + + - If you always get timeout errors, interrupts from the drive are + probably not making it to the host. + + - IRQ problems may also be indicated by the message + `IRQ probe failed (<n>)' while booting. If <n> is zero, that + means that the system did not see an interrupt from the drive when + it was expecting one (on any feasible IRQ). If <n> is negative, + that means the system saw interrupts on multiple IRQ lines, when + it was expecting to receive just one from the CDROM drive. + + - Double-check your hardware configuration to make sure that the IRQ + number of your IDE interface matches what the driver expects. + (The usual assignments are 14 for the primary (0x1f0) interface + and 15 for the secondary (0x170) interface.) Also be sure that + you don't have some other hardware which might be conflicting with + the IRQ you're using. Also check the BIOS setup for your system; + some have the ability to disable individual IRQ levels, and I've + had one report of a system which was shipped with IRQ 15 disabled + by default. + + - Note that many MS-DOS CDROM drivers will still function even if + there are hardware problems with the interrupt setup; they + apparently don't use interrupts. + + - If you own a Pioneer DR-A24X, you _will_ get nasty error messages + on boot such as "irq timeout: status=0x50 { DriveReady SeekComplete }" + The Pioneer DR-A24X CDROM drives are fairly popular these days. + Unfortunately, these drives seem to become very confused when we perform + the standard Linux ATA disk drive probe. If you own one of these drives, + you can bypass the ATA probing which confuses these CDROM drives, by + adding `append="hdX=noprobe hdX=cdrom"' to your lilo.conf file and running + lilo (again where X is the drive letter corresponding to where your drive + is installed.) + +c. System hangups. + + - If the system locks up when you try to access the CDROM, the most + likely cause is that you have a buggy IDE adapter which doesn't + properly handle simultaneous transactions on multiple interfaces. + The most notorious of these is the CMD640B chip. This problem can + be worked around by specifying the `serialize' option when + booting. Recent kernels should be able to detect the need for + this automatically in most cases, but the detection is not + foolproof. See Documentation/ide.txt for more information + about the `serialize' option and the CMD640B. + + - Note that many MS-DOS CDROM drivers will work with such buggy + hardware, apparently because they never attempt to overlap CDROM + operations with other disk activity. + + +d. Can't mount a CDROM. + + - If you get errors from mount, it may help to check `dmesg' to see + if there are any more specific errors from the driver or from the + filesystem. + + - Make sure there's a CDROM loaded in the drive, and that's it's an + ISO 9660 disc. You can't mount an audio CD. + + - With the CDROM in the drive and unmounted, try something like + + cat /dev/cdrom | od | more + + If you see a dump, then the drive and driver are probably working + OK, and the problem is at the filesystem level (i.e., the CDROM is + not ISO 9660 or has errors in the filesystem structure). + + - If you see `not a block device' errors, check that the definitions + of the device special files are correct. They should be as + follows: + + brw-rw---- 1 root disk 3, 0 Nov 11 18:48 /dev/hda + brw-rw---- 1 root disk 3, 64 Nov 11 18:48 /dev/hdb + brw-rw---- 1 root disk 22, 0 Nov 11 18:48 /dev/hdc + brw-rw---- 1 root disk 22, 64 Nov 11 18:48 /dev/hdd + + Some early Slackware releases had these defined incorrectly. If + these are wrong, you can remake them by running the script + scripts/MAKEDEV.ide. (You may have to make it executable + with chmod first.) + + If you have a /dev/cdrom symbolic link, check that it is pointing + to the correct device file. + + If you hear people talking of the devices `hd1a' and `hd1b', these + were old names for what are now called hdc and hdd. Those names + should be considered obsolete. + + - If mount is complaining that the iso9660 filesystem is not + available, but you know it is (check /proc/filesystems), you + probably need a newer version of mount. Early versions would not + always give meaningful error messages. + + +e. Directory listings are unpredictably truncated, and `dmesg' shows + `buffer botch' error messages from the driver. + + - There was a bug in the version of the driver in 1.2.x kernels + which could cause this. It was fixed in 1.3.0. If you can't + upgrade, you can probably work around the problem by specifying a + blocksize of 2048 when mounting. (Note that you won't be able to + directly execute binaries off the CDROM in that case.) + + If you see this in kernels later than 1.3.0, please report it as a + bug. + + +f. Data corruption. + + - Random data corruption was occasionally observed with the Hitachi + CDR-7730 CDROM. If you experience data corruption, using "hdx=slow" + as a command line parameter may work around the problem, at the + expense of low system performance. + + +6. cdchange.c +------------- + +/* + * cdchange.c [-v] <device> [<slot>] + * + * This loads a CDROM from a specified slot in a changer, and displays + * information about the changer status. The drive should be unmounted before + * using this program. + * + * Changer information is displayed if either the -v flag is specified + * or no slot was specified. + * + * Based on code originally from Gerhard Zuber <zuber@berlin.snafu.de>. + * Changer status information, and rewrite for the new Uniform CDROM driver + * interface by Erik Andersen <andersee@debian.org>. + */ + +#include <stdio.h> +#include <stdlib.h> +#include <errno.h> +#include <string.h> +#include <unistd.h> +#include <fcntl.h> +#include <sys/ioctl.h> +#include <linux/cdrom.h> + + +int +main (int argc, char **argv) +{ + char *program; + char *device; + int fd; /* file descriptor for CD-ROM device */ + int status; /* return status for system calls */ + int verbose = 0; + int slot=-1, x_slot; + int total_slots_available; + + program = argv[0]; + + ++argv; + --argc; + + if (argc < 1 || argc > 3) { + fprintf (stderr, "usage: %s [-v] <device> [<slot>]\n", + program); + fprintf (stderr, " Slots are numbered 1 -- n.\n"); + exit (1); + } + + if (strcmp (argv[0], "-v") == 0) { + verbose = 1; + ++argv; + --argc; + } + + device = argv[0]; + + if (argc == 2) + slot = atoi (argv[1]) - 1; + + /* open device */ + fd = open(device, O_RDONLY | O_NONBLOCK); + if (fd < 0) { + fprintf (stderr, "%s: open failed for `%s': %s\n", + program, device, strerror (errno)); + exit (1); + } + + /* Check CD player status */ + total_slots_available = ioctl (fd, CDROM_CHANGER_NSLOTS); + if (total_slots_available <= 1 ) { + fprintf (stderr, "%s: Device `%s' is not an ATAPI " + "compliant CD changer.\n", program, device); + exit (1); + } + + if (slot >= 0) { + if (slot >= total_slots_available) { + fprintf (stderr, "Bad slot number. " + "Should be 1 -- %d.\n", + total_slots_available); + exit (1); + } + + /* load */ + slot=ioctl (fd, CDROM_SELECT_DISC, slot); + if (slot<0) { + fflush(stdout); + perror ("CDROM_SELECT_DISC "); + exit(1); + } + } + + if (slot < 0 || verbose) { + + status=ioctl (fd, CDROM_SELECT_DISC, CDSL_CURRENT); + if (status<0) { + fflush(stdout); + perror (" CDROM_SELECT_DISC"); + exit(1); + } + slot=status; + + printf ("Current slot: %d\n", slot+1); + printf ("Total slots available: %d\n", + total_slots_available); + + printf ("Drive status: "); + status = ioctl (fd, CDROM_DRIVE_STATUS, CDSL_CURRENT); + if (status<0) { + perror(" CDROM_DRIVE_STATUS"); + } else switch(status) { + case CDS_DISC_OK: + printf ("Ready.\n"); + break; + case CDS_TRAY_OPEN: + printf ("Tray Open.\n"); + break; + case CDS_DRIVE_NOT_READY: + printf ("Drive Not Ready.\n"); + break; + default: + printf ("This Should not happen!\n"); + break; + } + + for (x_slot=0; x_slot<total_slots_available; x_slot++) { + printf ("Slot %2d: ", x_slot+1); + status = ioctl (fd, CDROM_DRIVE_STATUS, x_slot); + if (status<0) { + perror(" CDROM_DRIVE_STATUS"); + } else switch(status) { + case CDS_DISC_OK: + printf ("Disc present."); + break; + case CDS_NO_DISC: + printf ("Empty slot."); + break; + case CDS_TRAY_OPEN: + printf ("CD-ROM tray open.\n"); + break; + case CDS_DRIVE_NOT_READY: + printf ("CD-ROM drive not ready.\n"); + break; + case CDS_NO_INFO: + printf ("No Information available."); + break; + default: + printf ("This Should not happen!\n"); + break; + } + if (slot == x_slot) { + status = ioctl (fd, CDROM_DISC_STATUS); + if (status<0) { + perror(" CDROM_DISC_STATUS"); + } + switch (status) { + case CDS_AUDIO: + printf ("\tAudio disc.\t"); + break; + case CDS_DATA_1: + case CDS_DATA_2: + printf ("\tData disc type %d.\t", status-CDS_DATA_1+1); + break; + case CDS_XA_2_1: + case CDS_XA_2_2: + printf ("\tXA data disc type %d.\t", status-CDS_XA_2_1+1); + break; + default: + printf ("\tUnknown disc type 0x%x!\t", status); + break; + } + } + status = ioctl (fd, CDROM_MEDIA_CHANGED, x_slot); + if (status<0) { + perror(" CDROM_MEDIA_CHANGED"); + } + switch (status) { + case 1: + printf ("Changed.\n"); + break; + default: + printf ("\n"); + break; + } + } + } + + /* close device */ + status = close (fd); + if (status != 0) { + fprintf (stderr, "%s: close failed for `%s': %s\n", + program, device, strerror (errno)); + exit (1); + } + + exit (0); +} diff --git a/Documentation/cdrom/isp16 b/Documentation/cdrom/isp16 new file mode 100644 index 000000000000..cc86533ac9f3 --- /dev/null +++ b/Documentation/cdrom/isp16 @@ -0,0 +1,100 @@ + -- Documentation/cdrom/isp16 + +Docs by Eric van der Maarel <H.T.M.v.d.Maarel@marin.nl> + +This is the README for version 0.6 of the cdrom interface on an +ISP16, MAD16 or Mozart sound card. + +The detection and configuration of this interface used to be included +in both the sjcd and optcd cdrom driver. Drives supported by these +drivers came packed with Media Magic's multi media kit, which also +included the ISP16 card. The idea (thanks Leo Spiekman) +to move it from these drivers into a separate module and moreover, not to +rely on the MAD16 sound driver, are as follows: +-duplication of code in the kernel is a waste of resources and should + be avoided; +-however, kernels and notably those included with Linux distributions + (cf Slackware 3.0 included version 0.5 of the isp16 configuration + code included in the drivers) don't always come with sound support + included. Especially when they already include a bunch of cdrom drivers. + Hence, the cdrom interface should be configurable _independently_ of + sound support. + +The ISP16, MAD16 and Mozart sound cards have an OPTi 82C928 or an +OPTi 82C929 chip. The interface on these cards should work with +any cdrom attached to the card, which is 'electrically' compatible +with Sanyo/Panasonic, Sony or Mitsumi non-ide drives. However, the +command sets for any proprietary drives may differ +(and hence may not be supported in the kernel) from these four types. +For a fact I know the interface works and the way of configuration +as described in this documentation works in combination with the +sjcd (in Sanyo/Panasonic compatibility mode) cdrom drivers +(probably with the optcd (in Sony compatibility mode) as well). +If you have such an OPTi based sound card and you want to use the +cdrom interface with a cdrom drive supported by any of the other cdrom +drivers, it will probably work. Please let me know any experience you +might have). +I understand that cards based on the OPTi 82C929 chips may be configured +(hardware jumpers that is) as an IDE interface. Initialisation of such a +card in this mode is not supported (yet?). + +The suggestion to configure the ISP16 etc. sound card by booting DOS and +do a warm reboot to boot Linux somehow doesn't work, at least not +on my machine (IPC P90), with the OPTi 82C928 based card. + +Booting the kernel through the boot manager LILO allows the use +of some command line options on the 'LILO boot:' prompt. At boot time +press Alt or Shift while the LILO prompt is written on the screen and enter +any kernel options. Alternatively these options may be used in +the appropriate section in /etc/lilo.conf. Adding 'append="<cmd_line_options>"' +will do the trick as well. +The syntax of 'cmd_line_options' is + + isp16=[<port>[,<irq>[,<dma>]]][[,]<drive_type>] + +If there is no ISP16 or compatibles detected, there's probably no harm done. +These options indicate the values that your cdrom drive has been (or will be) +configured to use. +Valid values for the base i/o address are: + port=0x340,0x320,0x330,0x360 +for the interrupt request number + irq=0,3,5,7,9,10,11 +for the direct memory access line + dma=0,3,5,6,7 +and for the type of drive + drive_type=noisp16,Sanyo,Panasonic,Sony,Mitsumi. +Note that these options are case sensitive. +The values 0 for irq and dma indicate that they are not used, and +the drive will be used in 'polling' mode. The values 5 and 7 for irq +should be avoided in order to avoid any conflicts with optional +sound card configuration. +The syntax of the command line does not allow the specification of +irq when there's nothing specified for the base address and no +specification of dma when there is no specification of irq. +The value 'noisp16' for drive_type, which may be used as the first +non-integer option value (e.g. 'isp16=noisp16'), makes sure that probing +for and subsequent configuration of an ISP16-compatible card is skipped +all together. This can be useful to overcome possible conflicts which +may arise while the kernel is probing your hardware. +The default values are + port=0x340 + irq=0 + dma=0 + drive_type=Sanyo +reflecting my own configuration. The defaults can be changed in +the file linux/drivers/cdrom/ips16.h. + +The cdrom interface can be configured at run time by loading the +initialisation driver as a module. In that case, the interface +parameters can be set by giving appropriate values on the command +line. Configuring the driver can then be done by the following +command (assuming you have iso16.o installed in a proper place): + + insmod isp16.o isp16_cdrom_base=<port> isp16_cdrom_irq=<irq> \ + isp16_cdrom_dma=<dma> isp16_cdrom_type=<drive_type> + +where port, irq, dma and drive_type can have any of the values mentioned +above. + + +Have fun! diff --git a/Documentation/cdrom/mcdx b/Documentation/cdrom/mcdx new file mode 100644 index 000000000000..2bac4b7ff6da --- /dev/null +++ b/Documentation/cdrom/mcdx @@ -0,0 +1,29 @@ +If you are using the driver as a module, you can specify your ports and IRQs +like + + # insmod mcdx.o mcdx=0x300,11,0x304,5 + +and so on ("address,IRQ" pairs). +This will override the configuration in mcdx.h. + +This driver: + + o handles XA and (hopefully) multi session CDs as well as + ordinary CDs; + o supports up to 5 drives (of course, you'll need free + IRQs, i/o ports and slots); + o plays audio + +This version doesn't support yet: + + o shared IRQs (but it seems to be possible - I've successfully + connected two drives to the same irq. So it's `only' a + problem of the driver.) + +This driver never will: + + o Read digital audio (i.e. copy directly), due to missing + hardware features. + + +heiko@lotte.sax.de diff --git a/Documentation/cdrom/optcd b/Documentation/cdrom/optcd new file mode 100644 index 000000000000..6f46c7adb243 --- /dev/null +++ b/Documentation/cdrom/optcd @@ -0,0 +1,57 @@ +This is the README file for the Optics Storage 8000 AT CDROM device driver. + +This is the driver for the so-called 'DOLPHIN' drive, with the 34-pin +Sony-compatible interface. For the IDE-compatible Optics Storage 8001 +drive, you will want the ATAPI CDROM driver. The driver also seems to +work with the Lasermate CR328A. If you have a drive that works with +this driver, and that doesn't report itself as DOLPHIN, please drop me +a mail. + +The support for multisession CDs is in ALPHA stage. If you use it, +please mail me your experiences. Multisession support can be disabled +at compile time. + +You can find some older versions of the driver at + dutette.et.tudelft.nl:/pub/linux/ +and at Eberhard's mirror + ftp.gwdg.de:/pub/linux/cdrom/drivers/optics/ + +Before you can use the driver, you have to create the device file once: + # mknod /dev/optcd0 b 17 0 + +To specify the base address if the driver is "compiled-in" to your kernel, +you can use the kernel command line item (LILO option) + optcd=0x340 +with the right address. + +If you have compiled optcd as a module, you can load it with + # insmod /usr/src/linux/modules/optcd.o +or + # insmod /usr/src/linux/modules/optcd.o optcd=0x340 +with the matching address value of your interface card. + +The driver employs a number of buffers to do read-ahead and block size +conversion. The number of buffers is configurable in optcd.h, and has +influence on the driver performance. For my machine (a P75), 6 buffers +seems optimal, as can be seen from this table: + +#bufs kb/s %cpu +1 97 0.1 +2 191 0.3 +3 188 0.2 +4 246 0.3 +5 189 19 +6 280 0.4 +7 281 7.0 +8 246 2.8 +16 281 3.4 + +If you get a throughput significantly below 300 kb/s, try tweaking +N_BUFS, and don't forget to mail me your results! + +I'd appreciate success/failure reports. If you find a bug, try +recompiling the driver with some strategically chosen debug options +(these can be found in optcd.h) and include the messages generated in +your bug report. Good luck. + +Leo Spiekman (spiekman@dutette.et.tudelft.nl) diff --git a/Documentation/cdrom/packet-writing.txt b/Documentation/cdrom/packet-writing.txt new file mode 100644 index 000000000000..3d44c561fe6d --- /dev/null +++ b/Documentation/cdrom/packet-writing.txt @@ -0,0 +1,97 @@ +Getting started quick +--------------------- + +- Select packet support in the block device section and UDF support in + the file system section. + +- Compile and install kernel and modules, reboot. + +- You need the udftools package (pktsetup, mkudffs, cdrwtool). + Download from http://sourceforge.net/projects/linux-udf/ + +- Grab a new CD-RW disc and format it (assuming CD-RW is hdc, substitute + as appropriate): + # cdrwtool -d /dev/hdc -q + +- Setup your writer + # pktsetup dev_name /dev/hdc + +- Now you can mount /dev/pktcdvd/dev_name and copy files to it. Enjoy! + # mount /dev/pktcdvd/dev_name /cdrom -t udf -o rw,noatime + + +Packet writing for DVD-RW media +------------------------------- + +DVD-RW discs can be written to much like CD-RW discs if they are in +the so called "restricted overwrite" mode. To put a disc in restricted +overwrite mode, run: + + # dvd+rw-format /dev/hdc + +You can then use the disc the same way you would use a CD-RW disc: + + # pktsetup dev_name /dev/hdc + # mount /dev/pktcdvd/dev_name /cdrom -t udf -o rw,noatime + + +Packet writing for DVD+RW media +------------------------------- + +According to the DVD+RW specification, a drive supporting DVD+RW discs +shall implement "true random writes with 2KB granularity", which means +that it should be possible to put any filesystem with a block size >= +2KB on such a disc. For example, it should be possible to do: + + # dvd+rw-format /dev/hdc (only needed if the disc has never + been formatted) + # mkudffs /dev/hdc + # mount /dev/hdc /cdrom -t udf -o rw,noatime + +However, some drives don't follow the specification and expect the +host to perform aligned writes at 32KB boundaries. Other drives do +follow the specification, but suffer bad performance problems if the +writes are not 32KB aligned. + +Both problems can be solved by using the pktcdvd driver, which always +generates aligned writes. + + # dvd+rw-format /dev/hdc + # pktsetup dev_name /dev/hdc + # mkudffs /dev/pktcdvd/dev_name + # mount /dev/pktcdvd/dev_name /cdrom -t udf -o rw,noatime + + +Packet writing for DVD-RAM media +-------------------------------- + +DVD-RAM discs are random writable, so using the pktcdvd driver is not +necessary. However, using the pktcdvd driver can improve performance +in the same way it does for DVD+RW media. + + +Notes +----- + +- CD-RW media can usually not be overwritten more than about 1000 + times, so to avoid unnecessary wear on the media, you should always + use the noatime mount option. + +- Defect management (ie automatic remapping of bad sectors) has not + been implemented yet, so you are likely to get at least some + filesystem corruption if the disc wears out. + +- Since the pktcdvd driver makes the disc appear as a regular block + device with a 2KB block size, you can put any filesystem you like on + the disc. For example, run: + + # /sbin/mke2fs /dev/pktcdvd/dev_name + + to create an ext2 filesystem on the disc. + + +Links +----- + +See http://fy.chalmers.se/~appro/linux/DVD+RW/ for more information +about DVD writing. diff --git a/Documentation/cdrom/sbpcd b/Documentation/cdrom/sbpcd new file mode 100644 index 000000000000..d1825dffca34 --- /dev/null +++ b/Documentation/cdrom/sbpcd @@ -0,0 +1,1057 @@ +This README belongs to release 4.2 or newer of the SoundBlaster Pro +(Matsushita, Kotobuki, Panasonic, CreativeLabs, Longshine and Teac) +CD-ROM driver for Linux. + +sbpcd really, really is NOT for ANY IDE/ATAPI drive! +Not even if you have an "original" SoundBlaster card with an IDE interface! +So, you'd better have a look into README.ide if your port address is 0x1F0, +0x170, 0x1E8, 0x168 or similar. +I get tons of mails from IDE/ATAPI drive users - I really can't continue +any more to answer them all. So, if your drive/interface information sheets +mention "IDE" (primary, secondary, tertiary, quaternary) and the DOS driver +invoking line within your CONFIG.SYS is using an address below 0x230: +DON'T ROB MY LAST NERVE - jumper your interface to address 0x170 and IRQ 15 +(that is the "secondary IDE" configuration), set your drive to "master" and +use ide-cd as your driver. If you do not have a second IDE hard disk, use the +LILO commands + hdb=noprobe hdc=cdrom +and get lucky. +To make it fully clear to you: if you mail me about IDE/ATAPI drive problems, +my answer is above, and I simply will discard your mail, hoping to stop the +flood and to find time to lead my 12-year old son towards happy computing. + +The driver is able to drive the whole family of "traditional" AT-style (that +is NOT the new "Enhanced IDE" or "ATAPI" drive standard) Matsushita, +Kotobuki, Panasonic drives, sometimes labelled as "CreativeLabs". The +well-known drives are CR-521, CR-522, CR-523, CR-562, CR-563. +CR-574 is an IDE/ATAPI drive. + +The Longshine LCS-7260 is a double-speed drive which uses the "old" +Matsushita command set. It is supported - with help by Serge Robyns. +Vertos ("Elitegroup Computer Systems", ECS) has a similar drive - support +has started; get in contact if you have such a "Vertos 100" or "ECS-AT" +drive. + +There exists an "IBM External ISA CD-ROM Drive" which in fact is a CR-563 +with a special controller board. This drive is supported (the interface is +of the "LaserMate" type), and it is possibly the best buy today (cheaper than +an internal drive, and you can use it as an internal, too - e.g. plug it into +a soundcard). + +CreativeLabs has a new drive "CD200" and a similar drive "CD200F". The latter +is made by Funai and sometimes named "E2550UA", newer models may be named +"MK4015". The CD200F drives should fully work. +CD200 drives without "F" are still giving problems: drive detection and +playing audio should work, data access will result in errors. I need qualified +feedback about the bugs within the data functions or a drive (I never saw a +CD200). + +The quad-speed Teac CD-55A drive is supported, but still does not reach "full +speed". The data rate already reaches 500 kB/sec if you set SBP_BUFFER_FRAMES +to 64 (it is not recommended to do that for normal "file access" usage, but it +can speed up things a lot if you use something like "dd" to read from the +drive; I use it for verifying self-written CDs this way). +The drive itself is able to deliver 600 kB/sec, so this needs +work; with the normal setup, the performance currently is not even as good as +double-speed. + +This driver is NOT for Mitsumi or Sony or Aztech or Philips or XXX drives, +and again: this driver is in no way usable for any IDE/ATAPI drive. If you +think your drive should work and it doesn't: send me the DOS driver for your +beast (gzipped + uuencoded) and your CONFIG.SYS if you want to ask me for help, +and include an original log message excerpt, and try to give all information +a complete idiot needs to understand your hassle already with your first +mail. And if you want to say "as I have mailed you before", be sure that I +don't remember your "case" by such remarks; at the moment, I have some +hundreds of open correspondences about Linux CDROM questions (hope to reduce if +the IDE/ATAPI user questions disappear). + + +This driver will work with the soundcard interfaces (SB Pro, SB 16, Galaxy, +SoundFX, Mozart, MAD16 ...) and with the "no-sound" cards (Panasonic CI-101P, +LaserMate, WDH-7001C, Longshine LCS-6853, Teac ...). + +It works with the "configurable" interface "Sequoia S-1000", too, which is +used on the Spea Media FX and Ensonic Soundscape sound cards. You have to +specify the type "SBPRO 2" and the true CDROM port address with it, not the +"configuration port" address. + +If you have a sound card which needs a "configuration driver" instead of +jumpers for interface types and addresses (like Mozart cards) - those +drivers get invoked before the DOS CDROM driver in your CONFIG.SYS, typical +names are "cdsetup.sys" and "mztinit.sys" - let the sound driver do the +CDROM port configuration (the leading comments in linux/drivers/sound/mad16.c +are just for you!). Hannu Savolainen's mad16.c code is able to set up my +Mozart card - I simply had to add + #define MAD16_CONF 0x06 + #define MAD16_CDSEL 0x03 +to configure the CDROM interface for type "Panasonic" (LaserMate) and address +0x340. + +The interface type has to get configured in linux/drivers/cdrom/sbpcd.h, +because the register layout is different between the "SoundBlaster" and the +"LaserMate" type. + +I got a report that the Teac interface card "I/F E117098" is of type +"SoundBlaster" (i.e. you have to set SBPRO to 1) even with the addresses +0x300 and above. This is unusual, and it can't get covered by the auto +probing scheme. +The Teac 16-bit interface cards (like P/N E950228-00A, default address 0x2C0) +need the SBPRO 3 setup. + +If auto-probing found the drive, the address is correct. The reported type +may be wrong. A "mount" will give success only if the interface type is set +right. Playing audio should work with a wrong set interface type, too. + +With some Teac and some CD200 drives I have seen interface cards which seem +to lack the "drive select" lines; always drive 0 gets addressed. To avoid +"mirror drives" (four drives detected where you only have one) with such +interface cards, set MAX_DRIVES to 1 and jumper your drive to ID 0 (if +possible). + + +Up to 4 drives per interface card, and up to 4 interface cards are supported. +All supported drive families can be mixed, but the CR-521 drives are +hard-wired to drive ID 0. The drives have to use different drive IDs, and each +drive has to get a unique minor number (0...3), corresponding indirectly to +its drive ID. +The drive IDs may be selected freely from 0 to 3 - they do not have to be in +consecutive order. + +As Don Carroll, don@ds9.us.dell.com or FIDO 1:382/14, told me, it is possible +to change old drives to any ID, too. He writes in this sense: + "In order to be able to use more than one single speed drive + (they do not have the ID jumpers) you must add a DIP switch + and two resistors. The pads are already on the board next to + the power connector. You will see the silkscreen for the + switch if you remove the top cover. + 1 2 3 4 + ID 0 = x F F x O = "on" + ID 1 = x O F x F = "off" + ID 2 = x F O x x = "don't care" + ID 3 = x O O x + Next to the switch are the positions for R76 (7k) and R78 + (12k). I had to play around with the resistor values - ID 3 + did not work with other values. If the values are not good, + ID 3 behaves like ID 0." + +To use more than 4 drives, you simply need a second controller card at a +different address and a second cable. + +The driver supports reading of data from the CD and playing of audio tracks. +The audio part should run with WorkMan, xcdplayer, with the "non-X11" products +CDplayer and WorkBone - tell me if it is not compatible with other software. +The only accepted measure for correctness with the audio functions is the +"cdtester" utility (appended) - most audio player programmers seem to be +better musicians than programmers. ;-) + +With the CR-56x and the CD200 drives, the reading of audio frames is possible. +This is implemented by an IOCTL function which reads READ_AUDIO frames of +2352 bytes at once (configurable with the "READ_AUDIO" define, default is 0). +Reading the same frame a second time gives different data; the frame data +start at a different position, but all read bytes are valid, and we always +read 98 consecutive chunks (of 24 Bytes) as a frame. Reading more than 1 frame +at once possibly misses some chunks at each frame boundary. This lack has to +get corrected by external, "higher level" software which reads the same frame +again and tries to find and eliminate overlapping chunks (24-byte-pieces). + +The transfer rate with reading audio (1-frame-pieces) currently is very slow. +This can be better reading bigger chunks, but the "missing" chunks possibly +occur at the beginning of each single frame. +The software interface possibly may change a bit the day the SCSI driver +supports it too. + +With all but the CR-52x drives, MultiSession is supported. +Photo CDs work (the "old" drives like CR-521 can access only the first +session of a photoCD). +At ftp.gwdg.de:/pub/linux/hpcdtoppm/ you will find Hadmut Danisch's package to +convert photo CD image files and Gerd Knorr's viewing utility. + +The transfer rate will reach 150 kB/sec with CR-52x drives, 300 kB/sec with +CR-56x drives, and currently not more than 500 kB/sec (usually less than +250 kB/sec) with the Teac quad speed drives. +XA (PhotoCD) disks with "old" drives give only 50 kB/sec. + +This release consists of +- this README file +- the driver file linux/drivers/cdrom/sbpcd.c +- the stub files linux/drivers/cdrom/sbpcd[234].c +- the header file linux/drivers/cdrom/sbpcd.h. + + +To install: +----------- + +1. Setup your hardware parameters. Though the driver does "auto-probing" at a + lot of (not all possible!) addresses, this step is recommended for + everyday use. You should let sbpcd auto-probe once and use the reported + address if a drive got found. The reported type may be incorrect; it is + correct if you can mount a data CD. There is no choice for you with the + type; only one is right, the others are deadly wrong. + + a. Go into /usr/src/linux/drivers/cdrom/sbpcd.h and configure it for your + hardware (near the beginning): + a1. Set it up for the appropriate type of interface board. + "Original" CreativeLabs sound cards need "SBPRO 1". + Most "compatible" sound cards (almost all "non-CreativeLabs" cards) + need "SBPRO 0". + The "no-sound" board from OmniCd needs the "SBPRO 1" setup. + The Teac 8-bit "no-sound" boards need the "SBPRO 1" setup. + The Teac 16-bit "no-sound" boards need the "SBPRO 3" setup. + All other "no-sound" boards need the "SBPRO 0" setup. + The Spea Media FX and Ensoniq SoundScape cards need "SBPRO 2". + sbpcd.c holds some examples in its auto-probe list. + If you configure "SBPRO" wrong, the playing of audio CDs will work, + but you will not be able to mount a data CD. + a2. Tell the address of your CDROM_PORT (not of the sound port). + a3. If 4 drives get found, but you have only one, set MAX_DRIVES to 1. + a4. Set DISTRIBUTION to 0. + b. Additionally for 2.a1 and 2.a2, the setup may be done during + boot time (via the "kernel command line" or "LILO option"): + sbpcd=0x320,LaserMate + or + sbpcd=0x230,SoundBlaster + or + sbpcd=0x338,SoundScape + or + sbpcd=0x2C0,Teac16bit + This is especially useful if you install a fresh distribution. + If the second parameter is a number, it gets taken as the type + setting; 0 is "LaserMate", 1 is "SoundBlaster", 2 is "SoundScape", + 3 is "Teac16bit". + So, for example + sbpcd=0x230,1 + is equivalent to + sbpcd=0x230,SoundBlaster + +2. "cd /usr/src/linux" and do a "make config" and select "y" for Matsushita + CD-ROM support and for ISO9660 FileSystem support. If you do not have a + second, third, or fourth controller installed, do not say "y" to the + secondary Matsushita CD-ROM questions. + +3. Then make the kernel image ("make zlilo" or similar). + +4. Make the device file(s). This step usually already has been done by the + MAKEDEV script. + The driver uses MAJOR 25, so, if necessary, do + mknod /dev/sbpcd b 25 0 (if you have only one drive) + and/or + mknod /dev/sbpcd0 b 25 0 + mknod /dev/sbpcd1 b 25 1 + mknod /dev/sbpcd2 b 25 2 + mknod /dev/sbpcd3 b 25 3 + to make the node(s). + + The "first found" drive gets MINOR 0 (regardless of its jumpered ID), the + "next found" (at the same cable) gets MINOR 1, ... + + For a second interface board, you have to make nodes like + mknod /dev/sbpcd4 b 26 0 + mknod /dev/sbpcd5 b 26 1 + and so on. Use the MAJORs 26, 27, 28. + + If you further make a link like + ln -s sbpcd /dev/cdrom + you can use the name /dev/cdrom, too. + +5. Reboot with the new kernel. + +You should now be able to do + mkdir /CD +and + mount -rt iso9660 /dev/sbpcd /CD +or + mount -rt iso9660 -o block=2048 /dev/sbpcd /CD +and see the contents of your CD in the /CD directory. +To use audio CDs, a mounting is not recommended (and it would fail if the +first track is not a data track). + + +Using sbpcd as a "loadable module": +----------------------------------- + +If you do NOT select "Matsushita/Panasonic CDROM driver support" during the +"make config" of your kernel, you can build the "loadable module" sbpcd.o. + +If sbpcd gets used as a module, the support of more than one interface +card (i.e. drives 4...15) is disabled. + +You can specify interface address and type with the "insmod" command like: + # insmod /usr/src/linux/modules/sbpcd.o sbpcd=0x340,0 +or + # insmod /usr/src/linux/modules/sbpcd.o sbpcd=0x230,1 +or + # insmod /usr/src/linux/modules/sbpcd.o sbpcd=0x338,2 +where the last number represents the SBPRO setting (no strings allowed here). + + +Things of interest: +------------------- + +The driver is configured to try the LaserMate type of interface at I/O port +0x0340 first. If this is not appropriate, sbpcd.h should get changed +(you will find the right place - just at the beginning). + +No DMA and no IRQ is used. + +To reduce or increase the amount of kernel messages, edit sbpcd.c and play +with the "DBG_xxx" switches (initialization of the variable "sbpcd_debug"). +Don't forget to reflect on what you do; enabling all DBG_xxx switches at once +may crash your system, and each message line is accompanied by a delay. + +The driver uses the "variable BLOCK_SIZE" feature. To use it, you have to +specify "block=2048" as a mount option. Doing this will disable the direct +execution of a binary from the CD; you have to copy it to a device with the +standard BLOCK_SIZE (1024) first. So, do not use this if your system is +directly "running from the CDROM" (like some of Yggdrasil's installation +variants). There are CDs on the market (like the German "unifix" Linux +distribution) which MUST get handled with a block_size of 1024. Generally, +one can say all the CDs which hold files of the name YMTRANS.TBL are defective; +do not use block=2048 with those. + +Within sbpcd.h, you will find some "#define"s (e.g. EJECT and JUKEBOX). With +these, you can configure the driver for some special things. +You can use the appended program "cdtester" to set the auto-eject feature +during runtime. Jeff Tranter's "eject" utility can do this, too (and more) +for you. + +There is an ioctl CDROMMULTISESSION to obtain with a user program if +the CD is an XA disk and - if it is - where the last session starts. The +"cdtester" program illustrates how to call it. + + +Auto-probing at boot time: +-------------------------- + +The driver does auto-probing at many well-known interface card addresses, +but not all: +Some probings can cause a hang if an NE2000 ethernet card gets touched, because +SBPCD's auto-probing happens before the initialization of the net drivers. +Those "hazardous" addresses are excluded from auto-probing; the "kernel +command line" feature has to be used during installation if you have your +drive at those addresses. The "module" version is allowed to probe at those +addresses, too. + +The auto-probing looks first at the configured address resp. the address +submitted by the kernel command line. With this, it is possible to use this +driver within installation boot floppies, and for any non-standard address, +too. + +Auto-probing will make an assumption about the interface type ("SBPRO" or not), +based upon the address. That assumption may be wrong (initialization will be +o.k., but you will get I/O errors during mount). In that case, use the "kernel +command line" feature and specify address & type at boot time to find out the +right setup. + +For everyday use, address and type should get configured within sbpcd.h. That +will stop the auto-probing due to success with the first try. + +The kernel command "sbpcd=0" suppresses each auto-probing and causes +the driver not to find any drive; it is meant for people who love sbpcd +so much that they do not want to miss it, even if they miss the drives. ;-) + +If you configure "#define CDROM_PORT 0" in sbpcd.h, the auto-probing is +initially disabled and needs an explicit kernel command to get activated. +Once activated, it does not stop before success or end-of-list. This may be +useful within "universal" CDROM installation boot floppies (but using the +loadable module would be better because it allows an "extended" auto-probing +without fearing NE2000 cards). + +To shorten the auto-probing list to a single entry, set DISTRIBUTION 0 within +sbpcd.h. + + +Setting up address and interface type: +-------------------------------------- + +If your I/O port address is not 0x340, you have to look for the #defines near +the beginning of sbpcd.h and configure them: set SBPRO to 0 or 1 or 2, and +change CDROM_PORT to the address of your CDROM I/O port. + +Almost all of the "SoundBlaster compatible" cards behave like the no-sound +interfaces, i.e. need SBPRO 0! + +With "original" SB Pro cards, an initial setting of CD_volume through the +sound card's MIXER register gets done. +If you are using a "compatible" sound card of types "LaserMate" or "SPEA", +you can set SOUND_BASE (in sbpcd.h) to get it done with your card, too... + + +Using audio CDs: +---------------- + +Workman, WorkBone, xcdplayer, cdplayer and the nice little tool "cdplay" (see +README.aztcd from the Aztech driver package) should work. + +The program CDplayer likes to talk to "/dev/mcd" only, xcdplayer wants +"/dev/rsr0", workman loves "/dev/sr0" or "/dev/cdrom" - so, make the +appropriate links to use them without the need to supply parameters. + + +Copying audio tracks: +--------------------- + +The following program will copy track 1 (or a piece of it) from an audio CD +into the file "track01": + +/*=================== begin program ========================================*/ +/* + * read an audio track from a CD + * + * (c) 1994 Eberhard Moenkeberg <emoenke@gwdg.de> + * may be used & enhanced freely + * + * Due to non-existent sync bytes at the beginning of each audio frame (or due + * to a firmware bug within all known drives?), it is currently a kind of + * fortune if two consecutive frames fit together. + * Usually, they overlap, or a little piece is missing. This happens in units + * of 24-byte chunks. It has to get fixed by higher-level software (reading + * until an overlap occurs, and then eliminate the overlapping chunks). + * ftp.gwdg.de:/pub/linux/misc/cdda2wav-sbpcd.*.tar.gz holds an example of + * such an algorithm. + * This example program further is missing to obtain the SubChannel data + * which belong to each frame. + * + * This is only an example of the low-level access routine. The read data are + * pure 16-bit CDDA values; they have to get converted to make sound out of + * them. + * It is no fun to listen to it without prior overlap/underlap correction! + */ +#include <stdio.h> +#include <sys/ioctl.h> +#include <linux/cdrom.h> + +static struct cdrom_tochdr hdr; +static struct cdrom_tocentry entry[101]; +static struct cdrom_read_audio arg; +static u_char buffer[CD_FRAMESIZE_RAW]; +static int datafile, drive; +static int i, j, limit, track, err; +static char filename[32]; + +main(int argc, char *argv[]) +{ +/* + * open /dev/cdrom + */ + drive=open("/dev/cdrom", 0); + if (drive<0) + { + fprintf(stderr, "can't open drive.\n"); + exit (-1); + } +/* + * get TocHeader + */ + fprintf(stdout, "getting TocHeader...\n"); + err=ioctl(drive, CDROMREADTOCHDR, &hdr); + if (err!=0) + { + fprintf(stderr, "can't get TocHeader (error %d).\n", err); + exit (-1); + } + else + fprintf(stdout, "TocHeader: %d %d\n", hdr.cdth_trk0, hdr.cdth_trk1); +/* + * get and display all TocEntries + */ + fprintf(stdout, "getting TocEntries...\n"); + for (i=1;i<=hdr.cdth_trk1+1;i++) + { + if (i!=hdr.cdth_trk1+1) entry[i].cdte_track = i; + else entry[i].cdte_track = CDROM_LEADOUT; + entry[i].cdte_format = CDROM_LBA; + err=ioctl(drive, CDROMREADTOCENTRY, &entry[i]); + if (err!=0) + { + fprintf(stderr, "can't get TocEntry #%d (error %d).\n", i, err); + exit (-1); + } + else + { + fprintf(stdout, "TocEntry #%d: %1X %1X %06X %02X\n", + entry[i].cdte_track, + entry[i].cdte_adr, + entry[i].cdte_ctrl, + entry[i].cdte_addr.lba, + entry[i].cdte_datamode); + } + } + fprintf(stdout, "got all TocEntries.\n"); +/* + * ask for track number (not implemented here) + */ +track=1; +#if 0 /* just read a little piece (4 seconds) */ +entry[track+1].cdte_addr.lba=entry[track].cdte_addr.lba+300; +#endif +/* + * read track into file + */ + sprintf(filename, "track%02d\0", track); + datafile=creat(filename, 0755); + if (datafile<0) + { + fprintf(stderr, "can't open datafile %s.\n", filename); + exit (-1); + } + arg.addr.lba=entry[track].cdte_addr.lba; + arg.addr_format=CDROM_LBA; /* CDROM_MSF would be possible here, too. */ + arg.nframes=1; + arg.buf=&buffer[0]; + limit=entry[track+1].cdte_addr.lba; + for (;arg.addr.lba<limit;arg.addr.lba++) + { + err=ioctl(drive, CDROMREADAUDIO, &arg); + if (err!=0) + { + fprintf(stderr, "can't read abs. frame #%d (error %d).\n", + arg.addr.lba, err); + } + j=write(datafile, &buffer[0], CD_FRAMESIZE_RAW); + if (j!=CD_FRAMESIZE_RAW) + { + fprintf(stderr,"I/O error (datafile) at rel. frame %d\n", + arg.addr.lba-entry[track].cdte_addr.lba); + } + arg.addr.lba++; + } +} +/*===================== end program ========================================*/ + +At ftp.gwdg.de:/pub/linux/misc/cdda2wav-sbpcd.*.tar.gz is an adapted version of +Heiko Eissfeldt's digital-audio to .WAV converter (the original is there, too). +This is preliminary, as Heiko himself will care about it. + + +Known problems: +--------------- + +Currently, the detection of disk change or removal is actively disabled. + +Most attempts to read the UPC/EAN code result in a stream of zeroes. All my +drives are mostly telling there is no UPC/EAN code on disk or there is, but it +is an all-zero number. I guess now almost no CD holds such a number. + +Bug reports, comments, wishes, donations (technical information is a donation, +too :-) etc. to emoenke@gwdg.de. + +SnailMail address, preferable for CD editors if they want to submit a free +"cooperation" copy: + Eberhard Moenkeberg + Reinholdstr. 14 + D-37083 Goettingen + Germany +--- + + +Appendix -- the "cdtester" utility: + +/* + * cdtester.c -- test the audio functions of a CD driver + * + * (c) 1995 Eberhard Moenkeberg <emoenke@gwdg.de> + * published under the GPL + * + * made under heavy use of the "Tiny Audio CD Player" + * from Werner Zimmermann <zimmerma@rz.fht-esslingen.de> + * (see linux/drivers/block/README.aztcd) + */ +#undef AZT_PRIVATE_IOCTLS /* not supported by every CDROM driver */ +#define SBP_PRIVATE_IOCTLS /* not supported by every CDROM driver */ + +#include <stdio.h> +#include <stdio.h> +#include <malloc.h> +#include <sys/ioctl.h> +#include <linux/cdrom.h> + +#ifdef AZT_PRIVATE_IOCTLS +#include <linux/../../drivers/cdrom/aztcd.h> +#endif AZT_PRIVATE_IOCTLS +#ifdef SBP_PRIVATE_IOCTLS +#include <linux/../../drivers/cdrom/sbpcd.h> +#include <linux/fs.h> +#endif SBP_PRIVATE_IOCTLS + +struct cdrom_tochdr hdr; +struct cdrom_tochdr tocHdr; +struct cdrom_tocentry TocEntry[101]; +struct cdrom_tocentry entry; +struct cdrom_multisession ms_info; +struct cdrom_read_audio read_audio; +struct cdrom_ti ti; +struct cdrom_subchnl subchnl; +struct cdrom_msf msf; +struct cdrom_volctrl volctrl; +#ifdef AZT_PRIVATE_IOCTLS +union +{ + struct cdrom_msf msf; + unsigned char buf[CD_FRAMESIZE_RAW]; +} azt; +#endif AZT_PRIVATE_IOCTLS +int i, i1, i2, i3, j, k; +unsigned char sequence=0; +unsigned char command[80]; +unsigned char first=1, last=1; +char *default_device="/dev/cdrom"; +char dev[20]; +char filename[20]; +int drive; +int datafile; +int rc; + +void help(void) +{ + printf("Available Commands:\n"); + printf("STOP s EJECT e QUIT q\n"); + printf("PLAY TRACK t PAUSE p RESUME r\n"); + printf("NEXT TRACK n REPEAT LAST l HELP h\n"); + printf("SUBCHANNEL_Q c TRACK INFO i PLAY AT a\n"); + printf("READ d READ RAW w READ AUDIO A\n"); + printf("MS-INFO M TOC T START S\n"); + printf("SET EJECTSW X DEVICE D DEBUG Y\n"); + printf("AUDIO_BUFSIZ Z RESET R SET VOLUME v\n"); + printf("GET VOLUME V\n"); +} + +/* + * convert MSF number (3 bytes only) to Logical_Block_Address + */ +int msf2lba(u_char *msf) +{ + int i; + + i=(msf[0] * CD_SECS + msf[1]) * CD_FRAMES + msf[2] - CD_BLOCK_OFFSET; + if (i<0) return (0); + return (i); +} +/* + * convert logical_block_address to m-s-f_number (3 bytes only) + */ +void lba2msf(int lba, unsigned char *msf) +{ + lba += CD_BLOCK_OFFSET; + msf[0] = lba / (CD_SECS*CD_FRAMES); + lba %= CD_SECS*CD_FRAMES; + msf[1] = lba / CD_FRAMES; + msf[2] = lba % CD_FRAMES; +} + +int init_drive(char *dev) +{ + unsigned char msf_ent[3]; + + /* + * open the device + */ + drive=open(dev,0); + if (drive<0) return (-1); + /* + * get TocHeader + */ + printf("getting TocHeader...\n"); + rc=ioctl(drive,CDROMREADTOCHDR,&hdr); + if (rc!=0) + { + printf("can't get TocHeader (error %d).\n",rc); + return (-2); + } + else + first=hdr.cdth_trk0; + last=hdr.cdth_trk1; + printf("TocHeader: %d %d\n",hdr.cdth_trk0,hdr.cdth_trk1); + /* + * get and display all TocEntries + */ + printf("getting TocEntries...\n"); + for (i=1;i<=hdr.cdth_trk1+1;i++) + { + if (i!=hdr.cdth_trk1+1) TocEntry[i].cdte_track = i; + else TocEntry[i].cdte_track = CDROM_LEADOUT; + TocEntry[i].cdte_format = CDROM_LBA; + rc=ioctl(drive,CDROMREADTOCENTRY,&TocEntry[i]); + if (rc!=0) + { + printf("can't get TocEntry #%d (error %d).\n",i,rc); + } + else + { + lba2msf(TocEntry[i].cdte_addr.lba,&msf_ent[0]); + if (TocEntry[i].cdte_track==CDROM_LEADOUT) + { + printf("TocEntry #%02X: %1X %1X %02d:%02d:%02d (lba: 0x%06X) %02X\n", + TocEntry[i].cdte_track, + TocEntry[i].cdte_adr, + TocEntry[i].cdte_ctrl, + msf_ent[0], + msf_ent[1], + msf_ent[2], + TocEntry[i].cdte_addr.lba, + TocEntry[i].cdte_datamode); + } + else + { + printf("TocEntry #%02d: %1X %1X %02d:%02d:%02d (lba: 0x%06X) %02X\n", + TocEntry[i].cdte_track, + TocEntry[i].cdte_adr, + TocEntry[i].cdte_ctrl, + msf_ent[0], + msf_ent[1], + msf_ent[2], + TocEntry[i].cdte_addr.lba, + TocEntry[i].cdte_datamode); + } + } + } + return (hdr.cdth_trk1); /* number of tracks */ +} + +void display(int size,unsigned char *buffer) +{ + k=0; + getchar(); + for (i=0;i<(size+1)/16;i++) + { + printf("%4d:",i*16); + for (j=0;j<16;j++) + { + printf(" %02X",buffer[i*16+j]); + } + printf(" "); + for (j=0;j<16;j++) + { + if (isalnum(buffer[i*16+j])) + printf("%c",buffer[i*16+j]); + else + printf("."); + } + printf("\n"); + k++; + if (k>=20) + { + printf("press ENTER to continue\n"); + getchar(); + k=0; + } + } +} + +main(int argc, char *argv[]) +{ + printf("\nTesting tool for a CDROM driver's audio functions V0.1\n"); + printf("(C) 1995 Eberhard Moenkeberg <emoenke@gwdg.de>\n"); + printf("initializing...\n"); + + rc=init_drive(default_device); + if (rc<0) printf("could not open %s (rc=%d).\n",default_device,rc); + help(); + while (1) + { + printf("Give a one-letter command (h = help): "); + scanf("%s",command); + command[1]=0; + switch (command[0]) + { + case 'D': + printf("device name (f.e. /dev/sbpcd3): ? "); + scanf("%s",&dev); + close(drive); + rc=init_drive(dev); + if (rc<0) printf("could not open %s (rc %d).\n",dev,rc); + break; + case 'e': + rc=ioctl(drive,CDROMEJECT); + if (rc<0) printf("CDROMEJECT: rc=%d.\n",rc); + break; + case 'p': + rc=ioctl(drive,CDROMPAUSE); + if (rc<0) printf("CDROMPAUSE: rc=%d.\n",rc); + break; + case 'r': + rc=ioctl(drive,CDROMRESUME); + if (rc<0) printf("CDROMRESUME: rc=%d.\n",rc); + break; + case 's': + rc=ioctl(drive,CDROMSTOP); + if (rc<0) printf("CDROMSTOP: rc=%d.\n",rc); + break; + case 'S': + rc=ioctl(drive,CDROMSTART); + if (rc<0) printf("CDROMSTART: rc=%d.\n",rc); + break; + case 't': + rc=ioctl(drive,CDROMREADTOCHDR,&tocHdr); + if (rc<0) + { + printf("CDROMREADTOCHDR: rc=%d.\n",rc); + break; + } + first=tocHdr.cdth_trk0; + last= tocHdr.cdth_trk1; + if ((first==0)||(first>last)) + { + printf ("--got invalid TOC data.\n"); + } + else + { + printf("--enter track number(first=%d, last=%d): ",first,last); + scanf("%d",&i1); + ti.cdti_trk0=i1; + if (ti.cdti_trk0<first) ti.cdti_trk0=first; + if (ti.cdti_trk0>last) ti.cdti_trk0=last; + ti.cdti_ind0=0; + ti.cdti_trk1=last; + ti.cdti_ind1=0; + rc=ioctl(drive,CDROMSTOP); + rc=ioctl(drive,CDROMPLAYTRKIND,&ti); + if (rc<0) printf("CDROMPLAYTRKIND: rc=%d.\n",rc); + } + break; + case 'n': + rc=ioctl(drive,CDROMSTOP); + if (++ti.cdti_trk0>last) ti.cdti_trk0=last; + ti.cdti_ind0=0; + ti.cdti_trk1=last; + ti.cdti_ind1=0; + rc=ioctl(drive,CDROMPLAYTRKIND,&ti); + if (rc<0) printf("CDROMPLAYTRKIND: rc=%d.\n",rc); + break; + case 'l': + rc=ioctl(drive,CDROMSTOP); + if (--ti.cdti_trk0<first) ti.cdti_trk0=first; + ti.cdti_ind0=0; + ti.cdti_trk1=last; + ti.cdti_ind1=0; + rc=ioctl(drive,CDROMPLAYTRKIND,&ti); + if (rc<0) printf("CDROMPLAYTRKIND: rc=%d.\n",rc); + break; + case 'c': + subchnl.cdsc_format=CDROM_MSF; + rc=ioctl(drive,CDROMSUBCHNL,&subchnl); + if (rc<0) printf("CDROMSUBCHNL: rc=%d.\n",rc); + else + { + printf("AudioStatus:%s Track:%d Mode:%d MSF=%02d:%02d:%02d\n", + subchnl.cdsc_audiostatus==CDROM_AUDIO_PLAY ? "PLAYING":"NOT PLAYING", + subchnl.cdsc_trk,subchnl.cdsc_adr, + subchnl.cdsc_absaddr.msf.minute, + subchnl.cdsc_absaddr.msf.second, + subchnl.cdsc_absaddr.msf.frame); + } + break; + case 'i': + printf("Track No.: "); + scanf("%d",&i1); + entry.cdte_track=i1; + if (entry.cdte_track<first) entry.cdte_track=first; + if (entry.cdte_track>last) entry.cdte_track=last; + entry.cdte_format=CDROM_MSF; + rc=ioctl(drive,CDROMREADTOCENTRY,&entry); + if (rc<0) printf("CDROMREADTOCENTRY: rc=%d.\n",rc); + else + { + printf("Mode %d Track, starts at %02d:%02d:%02d\n", + entry.cdte_adr, + entry.cdte_addr.msf.minute, + entry.cdte_addr.msf.second, + entry.cdte_addr.msf.frame); + } + break; + case 'a': + printf("Address (min:sec:frm) "); + scanf("%d:%d:%d",&i1,&i2,&i3); + msf.cdmsf_min0=i1; + msf.cdmsf_sec0=i2; + msf.cdmsf_frame0=i3; + if (msf.cdmsf_sec0>59) msf.cdmsf_sec0=59; + if (msf.cdmsf_frame0>74) msf.cdmsf_frame0=74; + lba2msf(TocEntry[last+1].cdte_addr.lba-1,&msf.cdmsf_min1); + rc=ioctl(drive,CDROMSTOP); + rc=ioctl(drive,CDROMPLAYMSF,&msf); + if (rc<0) printf("CDROMPLAYMSF: rc=%d.\n",rc); + break; + case 'V': + rc=ioctl(drive,CDROMVOLREAD,&volctrl); + if (rc<0) printf("CDROMVOLCTRL: rc=%d.\n",rc); + printf("Volume: channel 0 (left) %d, channel 1 (right) %d\n",volctrl.channel0,volctrl.channel1); + break; + case 'R': + rc=ioctl(drive,CDROMRESET); + if (rc<0) printf("CDROMRESET: rc=%d.\n",rc); + break; +#ifdef AZT_PRIVATE_IOCTLS /*not supported by every CDROM driver*/ + case 'd': + printf("Address (min:sec:frm) "); + scanf("%d:%d:%d",&i1,&i2,&i3); + azt.msf.cdmsf_min0=i1; + azt.msf.cdmsf_sec0=i2; + azt.msf.cdmsf_frame0=i3; + if (azt.msf.cdmsf_sec0>59) azt.msf.cdmsf_sec0=59; + if (azt.msf.cdmsf_frame0>74) azt.msf.cdmsf_frame0=74; + rc=ioctl(drive,CDROMREADMODE1,&azt.msf); + if (rc<0) printf("CDROMREADMODE1: rc=%d.\n",rc); + else display(CD_FRAMESIZE,azt.buf); + break; + case 'w': + printf("Address (min:sec:frame) "); + scanf("%d:%d:%d",&i1,&i2,&i3); + azt.msf.cdmsf_min0=i1; + azt.msf.cdmsf_sec0=i2; + azt.msf.cdmsf_frame0=i3; + if (azt.msf.cdmsf_sec0>59) azt.msf.cdmsf_sec0=59; + if (azt.msf.cdmsf_frame0>74) azt.msf.cdmsf_frame0=74; + rc=ioctl(drive,CDROMREADMODE2,&azt.msf); + if (rc<0) printf("CDROMREADMODE2: rc=%d.\n",rc); + else display(CD_FRAMESIZE_RAW,azt.buf); /* currently only 2336 */ + break; +#endif + case 'v': + printf("--Channel 0 (Left) (0-255): "); + scanf("%d",&i1); + volctrl.channel0=i1; + printf("--Channel 1 (Right) (0-255): "); + scanf("%d",&i1); + volctrl.channel1=i1; + volctrl.channel2=0; + volctrl.channel3=0; + rc=ioctl(drive,CDROMVOLCTRL,&volctrl); + if (rc<0) printf("CDROMVOLCTRL: rc=%d.\n",rc); + break; + case 'q': + close(drive); + exit(0); + case 'h': + help(); + break; + case 'T': /* display TOC entry - without involving the driver */ + scanf("%d",&i); + if ((i<hdr.cdth_trk0)||(i>hdr.cdth_trk1)) + printf("invalid track number.\n"); + else + printf("TocEntry %02d: adr=%01X ctrl=%01X msf=%02d:%02d:%02d mode=%02X\n", + TocEntry[i].cdte_track, + TocEntry[i].cdte_adr, + TocEntry[i].cdte_ctrl, + TocEntry[i].cdte_addr.msf.minute, + TocEntry[i].cdte_addr.msf.second, + TocEntry[i].cdte_addr.msf.frame, + TocEntry[i].cdte_datamode); + break; + case 'A': /* read audio data into file */ + printf("Address (min:sec:frm) ? "); + scanf("%d:%d:%d",&i1,&i2,&i3); + read_audio.addr.msf.minute=i1; + read_audio.addr.msf.second=i2; + read_audio.addr.msf.frame=i3; + read_audio.addr_format=CDROM_MSF; + printf("# of frames ? "); + scanf("%d",&i1); + read_audio.nframes=i1; + k=read_audio.nframes*CD_FRAMESIZE_RAW; + read_audio.buf=malloc(k); + if (read_audio.buf==NULL) + { + printf("can't malloc %d bytes.\n",k); + break; + } + sprintf(filename,"audio_%02d%02d%02d_%02d.%02d\0", + read_audio.addr.msf.minute, + read_audio.addr.msf.second, + read_audio.addr.msf.frame, + read_audio.nframes, + ++sequence); + datafile=creat(filename, 0755); + if (datafile<0) + { + printf("can't open datafile %s.\n",filename); + break; + } + rc=ioctl(drive,CDROMREADAUDIO,&read_audio); + if (rc!=0) + { + printf("CDROMREADAUDIO: rc=%d.\n",rc); + } + else + { + rc=write(datafile,&read_audio.buf,k); + if (rc!=k) printf("datafile I/O error (%d).\n",rc); + } + close(datafile); + break; + case 'X': /* set EJECT_SW (0: disable, 1: enable auto-ejecting) */ + scanf("%d",&i); + rc=ioctl(drive,CDROMEJECT_SW,i); + if (rc!=0) + printf("CDROMEJECT_SW: rc=%d.\n",rc); + else + printf("EJECT_SW set to %d\n",i); + break; + case 'M': /* get the multisession redirection info */ + ms_info.addr_format=CDROM_LBA; + rc=ioctl(drive,CDROMMULTISESSION,&ms_info); + if (rc!=0) + { + printf("CDROMMULTISESSION(lba): rc=%d.\n",rc); + } + else + { + if (ms_info.xa_flag) printf("MultiSession offset (lba): %d (0x%06X)\n",ms_info.addr.lba,ms_info.addr.lba); + else + { + printf("this CD is not an XA disk.\n"); + break; + } + } + ms_info.addr_format=CDROM_MSF; + rc=ioctl(drive,CDROMMULTISESSION,&ms_info); + if (rc!=0) + { + printf("CDROMMULTISESSION(msf): rc=%d.\n",rc); + } + else + { + if (ms_info.xa_flag) + printf("MultiSession offset (msf): %02d:%02d:%02d (0x%02X%02X%02X)\n", + ms_info.addr.msf.minute, + ms_info.addr.msf.second, + ms_info.addr.msf.frame, + ms_info.addr.msf.minute, + ms_info.addr.msf.second, + ms_info.addr.msf.frame); + else printf("this CD is not an XA disk.\n"); + } + break; +#ifdef SBP_PRIVATE_IOCTLS + case 'Y': /* set the driver's message level */ +#if 0 /* not implemented yet */ + printf("enter switch name (f.e. DBG_CMD): "); + scanf("%s",&dbg_switch); + j=get_dbg_num(dbg_switch); +#else + printf("enter DDIOCSDBG switch number: "); + scanf("%d",&j); +#endif + printf("enter 0 for \"off\", 1 for \"on\": "); + scanf("%d",&i); + if (i==0) j|=0x80; + printf("calling \"ioctl(drive,DDIOCSDBG,%d)\"\n",j); + rc=ioctl(drive,DDIOCSDBG,j); + printf("DDIOCSDBG: rc=%d.\n",rc); + break; + case 'Z': /* set the audio buffer size */ + printf("# frames wanted: ? "); + scanf("%d",&j); + rc=ioctl(drive,CDROMAUDIOBUFSIZ,j); + printf("%d frames granted.\n",rc); + break; +#endif SBP_PRIVATE_IOCTLS + default: + printf("unknown command: \"%s\".\n",command); + break; + } + } +} +/*==========================================================================*/ + diff --git a/Documentation/cdrom/sjcd b/Documentation/cdrom/sjcd new file mode 100644 index 000000000000..74a14847b93a --- /dev/null +++ b/Documentation/cdrom/sjcd @@ -0,0 +1,60 @@ + -- Documentation/cdrom/sjcd + 80% of the work takes 20% of the time, + 20% of the work takes 80% of the time... + (Murphy's law) + + Once started, training can not be stopped... + (Star Wars) + +This is the README for the sjcd cdrom driver, version 1.6. + +This file is meant as a tips & tricks edge for the usage of the SANYO CDR-H94A +cdrom drive. It will grow as the questions arise. ;-) +For info on configuring the ISP16 sound card look at Documentation/cdrom/isp16. + +The driver should work with any of the Panasonic, Sony or Mitsumi style +CDROM interfaces. +The cdrom interface on Media Magic's soft configurable sound card ISP16, +which used to be included in the driver, is now supported in a separate module. +This initialisation module will probably also work with other interfaces +based on an OPTi 82C928 or 82C929 chip (like MAD16 and Mozart): see the +documentation Documentation/cdrom/isp16. + +The device major for sjcd is 18, and minor is 0. Create a block special +file in your /dev directory (e.g., /dev/sjcd) with these numbers. +(For those who don't know, being root and doing the following should do +the trick: + mknod -m 644 /dev/sjcd b 18 0 +and mount the cdrom by /dev/sjcd). + +The default configuration parameters are: + base address 0x340 + no irq + no dma +(Actually the CDR-H94A doesn't know how to use irq and dma.) +As of version 1.2, setting base address at boot time is supported +through the use of command line options: type at the "boot:" prompt: + linux sjcd=<base_address> +(where you would use the kernel labeled "linux" in lilo's configuration +file /etc/lilo.conf). You could also use 'append="sjcd=<configuration_info>"' +in the appropriate section of /etc/lilo.conf +If you're building a kernel yourself you can set your default base +i/o address with SJCD_BASE_ADDR in /usr/src/linux/drivers/cdrom/sjcd.h. + +The sjcd driver supports being loaded as a module. The following +command will set the base i/o address on the fly (assuming you +have installed the module in an appropriate place). + insmod sjcd.o sjcd_base=<base_address> + + +Have fun! + +If something is wrong, please email to vadim@rbrf.ru + or vadim@ipsun.ras.ru + or model@cecmow.enet.dec.com + or H.T.M.v.d.Maarel@marin.nl + +It happens sometimes that Vadim is not reachable by mail. For these +instances, Eric van der Maarel will help too. + + Vadim V. Model, Eric van der Maarel, Eberhard Moenkeberg diff --git a/Documentation/cdrom/sonycd535 b/Documentation/cdrom/sonycd535 new file mode 100644 index 000000000000..59581a4b302a --- /dev/null +++ b/Documentation/cdrom/sonycd535 @@ -0,0 +1,121 @@ + README FOR LINUX SONY CDU-535/531 DRIVER + ======================================== + +This is the Sony CDU-535 (and 531) driver version 0.7 for Linux. +I do not think I have the documentation to add features like DMA support +so if anyone else wants to pursue it or help me with it, please do. +(I need to see what was done for the CDU-31A driver -- perhaps I can +steal some of that code.) + +This is a Linux device driver for the Sony CDU-535 CDROM drive. This is +one of the older Sony drives with its own interface card (Sony bus). +The DOS driver for this drive is named SONY_CDU.SYS - when you boot DOS +your drive should be identified as a SONY CDU-535. The driver works +with a CDU-531 also. One user reported that the driver worked on drives +OEM'ed by Procomm, drive and interface board were labelled Procomm. + +The Linux driver is based on Corey Minyard's sonycd 0.3 driver for +the CDU-31A. Ron Jeppesen just changed the commands that were sent +to the drive to correspond to the CDU-535 commands and registers. +There were enough changes to let bugs creep in but it seems to be stable. +Ron was able to tar an entire CDROM (should read all blocks) and built +ghostview and xfig off Walnut Creek's X11R5/GNU CDROM. xcdplayer and +workman work with the driver. Others have used the driver without +problems except those dealing with wait loops (fixed in third release). +Like Minyard's original driver this one uses a polled interface (this +is also the default setup for the DOS driver). It has not been tried +with interrupts or DMA enabled on the board. + +REQUIREMENTS +============ + + - Sony CDU-535 drive, preferably without interrupts and DMA + enabled on the card. + + - Drive must be set up as unit 1. Only the first unit will be + recognized + + - You must enter your interface address into + /usr/src/linux/drivers/cdrom/sonycd535.h and build the + appropriate kernel or use the "kernel command line" parameter + sonycd535=0x320 + with the correct interface address. + +NOTES: +====== + +1) The drive MUST be turned on when booting or it will not be recognized! + (but see comments on modularized version below) + +2) when the cdrom device is opened the eject button is disabled to keep the + user from ejecting a mounted disk and replacing it with another. + Unfortunately xcdplayer and workman also open the cdrom device so you + have to use the eject button in the software. Keep this in mind if your + cdrom player refuses to give up its disk -- exit workman or xcdplayer, or + umount the drive if it has been mounted. + +THANKS +====== + +Many thanks to Ron Jeppesen (ronj.an@site007.saic.com) for getting +this project off the ground. He wrote the initial release +and the first two patches to this driver (0.1, 0.2, and 0.3). +Thanks also to Eberhard Moenkeberg (emoenke@gwdg.de) for prodding +me to place this code into the mainstream Linux source tree +(as of Linux version 1.1.91), as well as some patches to make +it a better device citizen. Further thanks to Joel Katz +<joelkatz@webchat.org> for his MODULE patches (see details below), +Porfiri Claudio <C.Porfiri@nisms.tei.ericsson.se> for patches +to make the driver work with the older CDU-510/515 series, and +Heiko Eissfeldt <heiko@colossus.escape.de> for pointing out that +the verify_area() checks were ignoring the results of said checks. + +(Acknowledgments from Ron Jeppesen in the 0.3 release:) +Thanks to Corey Minyard who wrote the original CDU-31A driver on which +this driver is based. Thanks to Ken Pizzini and Bob Blair who provided +patches and feedback on the first release of this driver. + +Ken Pizzini +ken@halcyon.com + +------------------------------------------------------------------------------ +(The following is from Joel Katz <joelkatz@webchat.org>.) + + To build a version of sony535.o that can be installed as a module, +use the following command: + +gcc -c -D__KERNEL__ -DMODULE -O2 sonycd535.c -o sonycd535.o + + To install the module, simply type: + +insmod sony535.o + or +insmod sony535.o sonycd535=<address> + + And to remove it: + +rmmod sony535 + + The code checks to see if MODULE is defined and behaves as it used +to if MODULE is not defined. That means your patched file should behave +exactly as it used to if compiled into the kernel. + + I have an external drive, and I usually leave it powered off. I used +to have to reboot if I needed to use the CDROM drive. Now I don't. + + Even if you have an internal drive, why waste the 96K of memory +(unswappable) that the driver uses if you use your CD-ROM drive infrequently? + + This driver will not install (whether compiled in or loaded as a +module) if the CDROM drive is not available during its initialization. This +means that you can have the driver compiled into the kernel and still load +the module later (assuming the driver doesn't install itself during +power-on). This only wastes 12K when you boot with the CDROM drive off. + + This is what I usually do; I leave the driver compiled into the +kernel, but load it as a module if I powered the system up with the drive +off and then later decided to use the CDROM drive. + + Since the driver only uses a single page to point to the chunks, +attempting to set the buffer cache to more than 2 Megabytes would be very +bad; don't do that. |