home *** CD-ROM | disk | FTP | other *** search
/ CD Actual 2 / CD ACTUAL VOL 2.iso / docs / kernel.13 / readme.azt < prev    next >
Encoding:
Text File  |  1995-09-10  |  39.6 KB  |  782 lines
  1. $Id: README.aztcd,v 1.60 1995/08/09 12:37:46 root Exp root $
  2.                        Readme-File README.aztcd
  3.    for Aztech CD-ROM CDA268-01A, ORCHID CD-3110, OKANO/WEARNES CDD110 
  4.                           CD-ROM  Driver 
  5.                        Version 1.6 and newer
  6.                    (for other drives see 6.-8.)
  7.  
  8. NOTE: THIS DRIVER WILL WORK WITH THE CD-ROM DRIVES LISTED, WHICH HAVE
  9.       A PROPRIETARY INTERFACE (implemented on a sound card or on a
  10.       ISA-AT-bus card). 
  11.       IT WILL DEFINITELY NOT WORK WITH CD-ROM DRIVES WITH *IDE*-INTERFACE,
  12.       such as the Aztech CDA269-031SE !!! IF YOU'RE USING A CD-ROM DRIVE
  13.       WITH IDE-INTERFACE, SOMETIMES ALSO CALLED ATAPI-COMPATIBLE, PLEASE 
  14.       USE THE ide-cd.c DRIVER, WRITTEN BY MARK LORD AND SCOTT SNYDER !
  15.       THE STANDARD-KERNEL 1.2.x NOW ALSO SUPPORTS IDE-CDROM-DRIVES, SEE THE
  16.       HARDDISK (!) SECTION OF make config, WHEN COMPILING A NEW KERNEL!!!
  17. ----------------------------------------------------------------------------
  18. Contents of this file:
  19.                          1.  NOTE
  20.                          2.  INSTALLATION
  21.                          3.  CONFIGURING YOUR KERNEL
  22.                          4.  RECOMPILING YOUR KERNEL
  23.                          4.1 AZTCD AS A RUN-TIME LOADABLE MODULE
  24.                          4.2 CDROM CONNECTED TO A SOUNDCARD
  25.                          5.  KNOWN PROBLEMS, FUTURE DEVELOPMENTS
  26.              5.1 MULTISESSION SUPPORT
  27.              5.2 STATUS RECOGNITION
  28.              5.3 DOSEMU's CDROM SUPPORT
  29.                          6.  BUG REPORTS
  30.                          7.  OTHER DRIVES
  31.                          8.  IF YOU DON'T SUCCEED ... DEBUGGING  
  32.                          9.  TECHNICAL HISTORY OF THE DRIVER
  33.                         10.  ACKNOWLEDGMENTS
  34.                         11.  PROGRAMMING ADD ONS: CDPLAY.C
  35.                         APPENDIX: Source code of cdplay.c
  36. ----------------------------------------------------------------------------
  37.  
  38. 1. NOTE 
  39. This software has been successfully in alpha and beta test for quite a long
  40. time with AZTECH CDA268-01A, ORCHID CDS-3110 and ORCHID/WEARNES CDD110 
  41. and has proven to be stable with kernel versions 1.0.9 to 1.2.0. But with
  42. any software there still may be bugs in it. So if you encounter problems,
  43. you are invited to help us improve this software. Please send me a detailed
  44. bug report (see chapter BUG REPORTS). You are also invited in helping us to 
  45. increase the number of drives, which are supported.
  46.  
  47. Please read the README-files carefully and always keep a backup copy of your 
  48. old kernel, in order to reboot if something goes wrong!
  49.  
  50.  
  51. 2. INSTALLATION
  52. If you received this software as a standalone package AZTECH.CDROM.Vxx.tgz 
  53. (xx=version number) and not included in the standard Linux kernel, read the 
  54. file AZTECH.CDROM.README included in that package to install it. The 
  55. standalone package's home is 'ftp.gwdg.de : pub/linux/cdrom/drivers/aztech'.
  56. The driver consists of a header file 'aztcd.h', which normally should reside 
  57. in /usr/include/linux and the source code 'aztcd.c', which normally resides in
  58. /usr/src/linux/drivers/block. It uses /dev/aztcd0, which must be a valid block
  59. device with major number 29 and reside in directory /dev. To mount a CD-ROM,
  60. your kernel needs to have the ISO9660-filesystem support included.
  61.  
  62.  
  63. 3.  CONFIGURING YOUR KERNEL
  64. If your kernel is already configured for using the AZTECH driver you will
  65. see the following message while Linux boots:
  66.     Aztech CD-ROM Init: DriverVersion=<version number> BaseAddress=<baseaddress>
  67.     Aztech CD-ROM Init: FirmwareVersion=<firmware version id of your I/O-card>>>
  68.     Aztech CD-ROM Init: <drive type> detected
  69.     Aztech CD-ROM Init: End
  70. If the message looks different and you are sure to have a supported drive,
  71. it may have a different base address. The Aztech driver does look for the 
  72. CD-ROM drive at the base address specified in aztcd.h at compile time. This 
  73. address can be overwritten by boot parameter aztcd=....You should reboot and 
  74. start Linux with boot parameter aztcd=<base address>, e.g. aztcd=0x320. If 
  75. you do not know the base address, start your PC with DOS and look at the boot 
  76. message of your CD-ROM's DOS driver. If that still does not help, use boot
  77. parameter aztcd=<base address>,0x79 , this tells aztcd to try a little harder.
  78.  
  79. If the message looks correct, as user 'root' you should be able to mount the 
  80. drive by
  81.           mount -t iso9660 -r /dev/aztcd0 /mnt
  82. and use it as any other filesystem. (If this does not work, check if
  83.   /dev/aztcd0 and /mnt do exist and create them, if necessary by doing
  84.       mknod /dev/aztcd0 b 29 0
  85.       mkdir /mnt                       
  86.  
  87. If you still get a different message while Linux boots or when you get the 
  88. message, that the ISO9660-filesystem is not supported by your kernel, when
  89. you try to mount the CD-ROM drive, you have to recompile your kernel.
  90.  
  91. If you do *not* have an Aztech/Orchid/Okano/Wearnes drive and want to bypass
  92. drive detection during Linux boot up, start with boot parameter aztcd=0.
  93.  
  94. Joe Nardone has compiled a boot disk with the Aztech driver for installing 
  95. Slackware from CDROM. You can find the disk images at 'sunsite.unc.edu'; 
  96. see file 'aztech.gz.README' for instructions on how to use it.
  97.  
  98.  
  99. 4. RECOMPILING YOUR KERNEL
  100. If your kernel is not yet configured for the AZTECH driver and the ISO9660-
  101. filesystem, you have to recompile your kernel: 
  102.  
  103. - Edit aztcd.h to set the I/O-address to your I/O-Base address (AZT_BASE_ADDR), 
  104.   the driver does not use interrupts or DMA, so if you are using an AZTECH
  105.   CD268, an ORCHID CD-3110 or ORCHID/WEARNES CDD110 that's the only item you 
  106.   have to set up. If you have a soundcard, read chapter 4.2.
  107.   Users of other drives should read chapter OTHER DRIVES of this file.
  108.   You also can configure that address by LILO boot parameter aztcd=... 
  109. - There are some other points, which may be configured, e.g. auto-eject the
  110.   CD when umounting a drive, tray locking etc., see aztcd.h for details.
  111. - Build a new kernel, configure it for 'Aztech/Orchid/Okano/Wearnes support' 
  112.   (if you want aztcd to be part of the kernel). Do not configure it for
  113.   'Aztech... support', if you want to use aztcd as a run time loadable module. 
  114.   But in any case you must have the ISO9660-filesystem included in your
  115.   kernel.
  116. - Activate the new kernel, normally this is done by running lilo (don't for-
  117.   get to configure it before and to keep a copy of your old kernel in case
  118.   something goes wrong!).
  119. - Reboot
  120. - If you've included aztcd in your kernel, you now should see during boot 
  121.   some messages like
  122.     Aztech CD-ROM Init: DriverVersion=<version number> BaseAddress=<baseaddress>
  123.     Aztech CD-ROM Init: FirmwareVersion=<firmware version id of your I/O-card>
  124.     Aztech CD-ROM Init: <drive type> detected
  125.     Aztech CD-ROM Init: End
  126. - If you have not included aztcd in your kernel, but want to load aztcd as a 
  127.   run time loadable module see 4.1. 
  128. - If the message looks correct, as user 'root' you should be able to mount 
  129.   the drive by
  130.           mount -t iso9660 -r /dev/aztcd0 /mnt
  131.   and use it as any other filesystem. (If this does not work, check if
  132.   /dev/aztcd0 and /mnt do exist and create them, if necessary by doing
  133.       mknod /dev/aztcd0 b 29 0
  134.       mkdir /mnt                       
  135. - If this still does not help, see chapters OTHER DRIVES and DEBUGGING.
  136.  
  137. 4.1 AZTCD AS A RUN-TIME LOADABLE MODULE
  138. If you do not need aztcd permanently, you can also load and remove the driver
  139. during runtime via insmod and rmmod. To build aztcd as a loadable module you 
  140. must *not* configure your kernel for AZTECH support. Nevertheless, you may
  141. run into problems, if the version of your boot kernel is not the same than
  142. the source kernel version, from which you create the modules. So rebuild your 
  143. kernel, if necessary. 
  144.  
  145. Now edit the base address of your AZTECH interface card in
  146. /usr/src/linux/include/linux/aztcd.h to the appropriate value. There are
  147. also some special features which may be configured, e.g. auto-eject a CD
  148. when unmounting the drive etc; see aztcd.h for details. Then change
  149. to /usr/src/linux and do a 
  150.                     make modules  
  151.                 make modules_install
  152. After that you can run-time load the driver via
  153.                     insmod /lib/modules/X.X.X/misc/aztcd.o
  154. and remove it via   rmmod  aztcd.
  155. If you did not set the correct base address in aztcd.h, you can also supply the
  156. base address when loading the driver via
  157.                     insmod /lib/modules/X.X.X/misc/aztcd.o aztcd=<base address>
  158. If you do not have the iso9660-filesystem in your boot kernel, you also have
  159. to load it before you can mount the CDROM:
  160.                     insmod /lib/modules/X.X.X/fs/isofs.o
  161. The mount procedure works as described in 4. above.
  162. (In all commands 'X.X.X' is the current linux kernel version number. For details
  163. see file README.modules in /usr/src/linux.)
  164.  
  165. 4.2 CDROM CONNECTED TO A SOUNDCARD
  166. Most soundcards do have a bus interface to the CDROM-drive. In many cases
  167. this soundcard needs to be configured, before the CDROM can be used. This
  168. configuration procedure consists of writing some kind of initialization
  169. data to the soundcard registers. The AZTECH-CDROM driver in the moment does
  170. only support one type of soundcard (SoundWave32). Users of other soundcards
  171. should try to boot DOS first and let their DOS drivers initialize the
  172. soundcard and CDROM, then warm boot (or use loadlin) their PC to start
  173. Linux.
  174. Support for the CDROM-interface of SoundWave32-soundcards is directly
  175. implemented in the AZTECH driver. Please edit /usr/src/linux/include/aztdc.h,
  176. uncomment line '#define AZT_SW32' and set the appropiate value for
  177. AZT_BASE_ADDR and AZT_SW32_BASE_ADDR. This support was tested with an Orchid
  178. CDS-3110 connected to a SoundWave32.
  179. If you want your soundcard to be supported, find out, how it needs to be
  180. configured and mail me (see 6.) the appropriate information. 
  181.  
  182. 5. KNOWN PROBLEMS, FUTURE DEVELOPMENTS
  183. 5.1 MULTISESSION SUPPORT
  184. I have now (July 1995) started support of multisession CDs. Unfortunately I
  185. do only have one multisession CD and no appropriate applications, so I can
  186. program, but testing is a little too less :-(. If you'd like to help me, 
  187. please contact me. As of version 1.4 you can enable the multisession support 
  188. in aztcd.h by setting AZT_MULTISESSION to 1. 
  189.  
  190. 5.2 STATUS RECOGNITION
  191. The drive status recognition does not work correctly in all cases. Changing
  192. a disk or having the door open, when a drive is already mounted, is detected 
  193. by the Aztech driver itself, but nevertheless causes multiple read attempts
  194. by the different layers of the ISO9660-filesystem driver, which finally timeout,
  195. so you have to wait quite a little... But isn't it bad style to change a disk 
  196. in a mounted drive, anyhow ?!
  197.  
  198. The driver uses busy wait in most cases for the drive handshake (macros
  199. STEN_LOW and DTEN_LOW). I tested with a 486/DX2 at 66MHz and a Pentium at
  200. 60MHz. Whenever you use a much faster machine you are likely to get timeout 
  201. messages. In that case edit aztcd.h and increase the timeout value AZT_TIMEOUT. 
  202.  
  203. For some 'slow' drive commands I implemented waiting with a timer waitqueue
  204. (macro STEN_LOW_WAIT). If you get this timeout message, you may also edit
  205. aztcd.h and increase the timeout value AZT_STATUS_DELAY. The waitqueue has
  206. shown to be a little critical. If you get kernel panic messages, edit aztcd.c
  207. and substitute STEN_LOW_WAIT by STEN_LOW. Busy waiting with STEN_LOW is more
  208. stable, but also causes CPU overhead.
  209.  
  210. 5.3 DOSEMU's CD-ROM SUPPORT
  211. With release 1.20 aztcd was modified to allow access to CD-ROMS when running
  212. under dosemu-0.60. aztcd-versions before 1.20 are most likely to crash
  213. Linux, when a CD-ROM is accessed under dosemu. This problem has partly been
  214. fixed, but still when accessing a directory for the first time the system
  215. might hang for some 30sec. So be patient, when using dosemu's CD-ROM support
  216. in combination with aztcd :-) ! Unfortunately up to now, I could not locate
  217. the root cause of that problem. It seems to be somewhere in the interaction
  218. of the kernel with dosemu's and aztcd's buffers. I appreciate any help on
  219. this subject ! 
  220. This problem has now (July 1995) been fixed by a modification to dosemu's
  221. CD-ROM driver, but it is unclear, with which version of dosemu this modi-
  222. fication will officially be included.
  223.  
  224. 6. BUG REPORTS
  225. Please send detailed bug reports and bug fixes via EMail to
  226.  
  227.         zimmerma@rz.fht-esslingen.de
  228.  
  229. Please include a description of your CD-ROM drive type and interface card, 
  230. the exact firmware message during Linux bootup, the version number of the 
  231. AZTECH-CDROM-driver and the Linux kernel version. Also a description of your 
  232. system's other hardware could be of interest, especially microprocessor type, 
  233. clock frequency, other interface cards such as soundcards, ethernet adapter, 
  234. game cards etc..
  235.  
  236. I will try to collect the reports and make the necessary modifications from 
  237. time to time. I may also come back to you directly with some bug fixes and 
  238. ask you to do further testing and debugging.
  239.  
  240. Editors of CD-ROMs are invited to send a 'cooperation' copy of their
  241. CD-ROMs to the volunteers, who provided the CD-ROM support for Linux. My
  242. snail mail address for such 'stuff' is
  243.            Prof. Dr. W. Zimmermann
  244.            Fachhochschule fuer Technik Esslingen
  245.            Fachbereich NT
  246.            Flandernstrasse 101
  247.            D-73732 Esslingen
  248.            Germany
  249.  
  250.  
  251. 7. OTHER DRIVES
  252. The following drives ORCHID CDS3110, OKANO CDD110 and WEARNES nearly look 
  253. the same as AZTECH CDA268-01A, especially they seem to use the same command 
  254. codes. So it was quite simple to make the AZTECH driver work with these drives. 
  255.  
  256. Unfortunately I do not have any of these drives available, so I couldn't test
  257. it myself. But I've got reports, that it works with ORCHID CDS3110 and Game-
  258. Wave32 sound cards and also with WEARNES CDD110 in some different combinations. 
  259. In some installations, it seems necessary to initialize the drive with the DOS 
  260. driver before (especially if combined with a sound card) and then do a warm 
  261. boot (CTRL-ALT-RESET) or start Linux from DOS, e.g. with 'loadlin'.
  262.  
  263. If you do not succeed, read chapter DEBUGGING. Thanks in advance!
  264.  
  265. Sorry for the inconvenience, but it is difficult to develop for hardware, 
  266. which you don't have available for testing. So if you like, please help us.
  267.  
  268.  
  269. 8. DEBUGGING : IF YOU DON'T SUCCEED, TRY THE FOLLOWING
  270. -reread the complete README file
  271. -make sure, that your drive is hardware configured for 
  272.     transfer mode: polled
  273.     IRQ:           not used
  274.     DMA:           not used
  275.     Base Address:  something like 300, 320 ...
  276.  You can check this, when you start the DOS driver, which came with your
  277.  drive. By appropriately configuring the drive and the DOS driver you can
  278.  check, whether your drive does operate in this mode correctly under DOS. If
  279.  it does not operate under DOS, it won't under Linux.
  280.  Make sure the Base Address is configured correctly in aztcd.h, also make
  281.  sure, that /dev/aztcd0 exists with the correct major number (compare it with
  282.  the entry in file /usr/include/linux/major.h for the Aztech drive). 
  283. -insert a CD-ROM and close the tray
  284. -cold boot your PC (i.e. via the power on switch or the reset button)
  285. -if you start Linux via DOS, e.g. using loadlin, make sure, that the DOS
  286.  driver for the CD-ROM drive is not loaded (comment out the calling lines 
  287.  in DOS' config.sys!)
  288. -look for the aztcd: init message during Linux init and note them exactly
  289. -log in as root and do a mount -t iso9660 /dev/aztcd0 /mnt
  290. -if you don't succeed in the first time, try several times. Try also to open
  291.  and close the tray, then mount again. Please note carefully all commands
  292.  you typed in and the aztcd-messages, which you get.
  293. -if you get an 'Aztech CD-ROM init: aborted' message, read the remarks about
  294.  the version string below.
  295.  
  296. If this does not help, do the same with the following differences 
  297. -start DOS before; make now sure, that the DOS driver for the CD-ROM is 
  298.  loaded under DOS (i.e. uncomment it again in config.sys)
  299. -warm boot your PC (i.e. via CTRL-ALT-DEL)
  300.  if you have it, you can also start via loadlin (try both).
  301.  ...
  302.  Again note all commands and the aztcd-messages.
  303.  
  304. If you see STEN_LOW or STEN_LOW_WAIT error messages, increase the timeout
  305. values.
  306.  
  307. If this still does not help, 
  308. -look in aztcd.c for the lines  #if 0
  309.                                 #define AZT_TEST1
  310.                                 ...
  311.                                 #endif
  312.  and substitute '#if 0' by '#if 1'.
  313. -recompile your kernel and repeat the above two procedures. You will now get 
  314.  a bundle of debugging messages from the driver. Again note your commands
  315.  and the appropriate messages. If you have syslogd running, these messages
  316.  may also be found in syslogd's kernel log file. Nevertheless in some
  317.  installations syslogd does not yet run, when init() is called, thus look for
  318.  the aztcd-messages during init, before the login-prompt appears.
  319.  Then look in aztcd.c, to find out, what happened. The normal calling sequence 
  320.  is: aztcd_init() during Linux bootup procedure init()
  321.  after doing a 'mount -t iso9660 /dev/aztcd0 /mnt' the normal calling sequence is
  322.      aztcd_open()    -> Status 2c after cold reboot with CDROM or audio CD inserted
  323.                      -> Status 8  after warm reboot with CDROM inserted          
  324.                      -> Status 2e after cold reboot with no disk, closed tray
  325.                      -> Status 6e after cold reboot, mount with door open
  326.      aztUpdateToc()
  327.      aztGetDiskInfo()
  328.      aztGetQChannelInfo()   repeated several times
  329.      aztGetToc()
  330.      aztGetQChannelInfo()   repeated several times
  331.      a list of track informations
  332.      do_aztcd_request()  }  
  333.      azt_transfer()    } repeated several times
  334.      azt_poll          }
  335.  Check, if there is a difference in the calling sequence or the status flags!
  336.  
  337.  There are a lot of other messages, eg. the ACMD-command code (defined in
  338.  aztcd.h), status info from the getAztStatus-command and the state sequence of
  339.  the finite state machine in azt_poll(). The most important are the status
  340.  messages, look how they are defined and try to understand, if they make
  341.  sense in the context where they appear. With a CD-ROM inserted the status 
  342.  should always be 8, except in aztcd_open(). Try to open the tray, insert a
  343.  audio disk, insert no disk or reinsert the CD-ROM and check, if the status
  344.  bits change accordingly. The status bits are the most likely point, where 
  345.  the drive manufacturers may implement changes.
  346.             
  347. If you still don't succeed, a good point to start is to look in aztcd.c in 
  348. function aztcd_init, where the drive should be detected during init. Do the
  349. following:
  350. -reboot the system with boot parameter 'aztcd=<your base address>,0x79'. With
  351.  parameter 0x79 most of the drive version detection is bypassed. After that 
  352.  you should see the complete version string including leading and trailing 
  353.  blanks during init. 
  354.  Now adapt the statement
  355.       if ((result[1]=='A')&&(result[2]=='Z' ...)
  356.  in aztcd_init() to exactly match the first 3 or 4 letters you have seen.
  357. -Another point is the 'smart' card detection feature in aztcd_init(). Normally
  358.  the CD-ROM drive is ready, when aztcd_init is trying to read the version
  359.  string and a time consuming ACMD_SOFT_RESET command can be avoided. This is
  360.  detected by looking, if AFL_OP_OK can be read correctly. If the CD-ROM drive 
  361.  hangs in some unknown state, e.g. because of an error before a warm start or 
  362.  because you first operated under DOS, even the version string may be correct, 
  363.  but the following commands will not. Then change the code in such a way, 
  364.  that the ACMD_SOFT_RESET is issued in any case, by substituting the
  365.  if-statement 'if ( ...=AFL_OP_OK)' by 'if (1)'.
  366.  
  367. If you succeed, please mail may the exact version string of your drive and
  368. the code modifications, you have made together with a short explanation.
  369. If you don't succeed, you may mail me the output of the debugging messages.
  370. But remember, they are only useful, if they are exact and complete and you
  371. describe in detail your hardware setup and what you did (cold/warm reboot,
  372. with/without DOS, DOS-driver started/not started, which Linux-commands etc.)
  373.  
  374.  
  375. 9. TECHNICAL HISTORY OF THE DRIVER
  376. The AZTECH-Driver is a rework of the Mitsumi-Driver. Four major items had to
  377. be reworked:
  378.  
  379. a) The Mitsumi drive does issue complete status information acknowledging
  380. each command, the Aztech drive does only signal that the command was
  381. processed. So whenever the complete status information is needed, an extra
  382. ACMD_GET_STATUS command is issued. The handshake procedure for the drive
  383. can be found in the functions aztSendCmd(), sendAztCmd() and getAztStatus().
  384.  
  385. b) The Aztech Drive does not have a ACMD_GET_DISK_INFO command, so the
  386. necessary info about the number of tracks (firstTrack, lastTrack), disk
  387. length etc. has to be read from the TOC in the lead in track (see function
  388. aztGetDiskInfo()).
  389.  
  390. c) Whenever data is read from the drive, the Mitsumi drive is started with a
  391. command to read an indefinite (0xffffff) number of sectors. When the appropriate 
  392. number of sectors is read, the drive is stopped by a ACDM_STOP command. This
  393. does not work with the Aztech drive. I did not find a way to stop it. The
  394. stop and pause commands do only work in AUDIO mode but not in DATA mode.
  395. Therefore I had to modify the 'finite state machine' in function azt_poll to
  396. only read a certain number of sectors and then start a new read on demand. As I 
  397. have not completely understood, how the buffer/caching scheme of the Mitsumi 
  398. driver was implemented, I am not sure, if I have covered all cases correctly, 
  399. whenever you get timeout messages, the bug is most likely to be in that
  400. function azt_poll() around switch(cmd) .... case ACD_S_DATA. 
  401.  
  402. d) I did not get information about changing drive mode. So I doubt, that the
  403. code around function azt_poll() case AZT_S_MODE does work. In my test I have
  404. not been able to switch to reading in raw mode. For reading raw mode, Aztech
  405. uses a different command than for cooked mode, which I only have implemen-
  406. ted in the ioctl-section but not in the section which is used by the ISO9660- 
  407.  
  408. The driver was developed on an AST PC with Intel 486/DX2, 8MB RAM, 340MB IDE 
  409. hard disk and on an AST PC with Intel Pentium 60MHz, 16MB RAM, 520MB IDE 
  410. running Linux kernel version 1.0.9 from the LST 1.8 Distribution. The kernel 
  411. was compiled with gcc.2.5.8. My CD-ROM drive is an Aztech CDA268-01A. My
  412. drive says, that it has Firmware Version AZT26801A1.3. It came with a ISA-bus
  413. interface card and works with polled I/O without DMA and without interrupts.
  414. The code for all other drives was 'remote' tested and debugged by a number of 
  415. volunteers on the Internet.
  416.  
  417. Points, where I feel that possible problems might be and all points where I 
  418. did not completely understand the drive's behaviour or trust my own code are 
  419. marked with /*???*/ in the source code. There are also some parts in the 
  420. Mitsumi driver, where I did not completely understand their code.
  421.  
  422.  
  423. 10. ACKNOWLEDGMENTS
  424. Without the help of P.Bush, Aztech, who delivered technical information
  425. about the Aztech Drive and without the help of E.Moenkeberg, GWDG, who did a
  426. great job in analyzing the command structure of various CD-ROM drives, this
  427. work would not have been possible. E.Moenkeberg was also a great help in 
  428. making the software 'kernel ready' and in answering many of the CDROM-related 
  429. questions in the newsgroups. He really is *the* Linux CD-ROM guru. Thanks 
  430. also to all the guys on the Internet, who collected valuable technical 
  431. information about CDROMs. 
  432.  
  433. Joe Nardone (joe@access.digex.net) was a patient tester even for my first
  434. trial, which was more than slow, and made suggestions for code improvement.
  435. Especially the 'finite state machine' azt_poll() was rewritten by Joe to get
  436. clean C code and avoid the ugly 'gotos', which I copied from mcd.c.
  437.  
  438. Robby Schirmer (schirmer@fmi.uni-passau.de) tested the audio stuff (ioctls) 
  439. and suggested a lot of patches for them.
  440.  
  441. Joseph Piskor and Peter Nugent were the first users with the ORCHID CD3110
  442. and also were very patient with the problems which occurred.
  443.  
  444. Reinhard Max delivered the information for the CDROM-interface of the
  445. SoundWave32 soundcards.
  446.  
  447. Anybody, who is interested in these items should have a look at 'ftp.gwdg.de',
  448. directory 'pub/linux/cdrom' and at 'ftp.cdrom.com', directory 'pub/cdrom'.
  449.  
  450. 11. PROGRAMMING ADD ONs: cdplay.c
  451. You can use the ioctl-functions included in aztcd.c in your own programs. As
  452. an example on how to do this, you will find a tiny CD Player for audio CDs 
  453. named 'cdplay.c'. It allows you to play audio CDs. You can play a specified 
  454. track, pause and resume or skip tracks forward and backwards. If you quit the 
  455. program without stopping the  drive, playing is continued. You can also 
  456. (mis)use cdplay to read and hexdump data disks.
  457. 'cdplay.c' can be found as a separate file in package AZTECH.CDROM.Vxx.tgz.
  458. If you don't have it, you can find the code in the APPENDIX of this file,
  459. which you should cut out with an editor and store in a separate file
  460. 'cdplay.c'. To compile it and make it executable, do
  461.   gcc -s -Wall -O2 -L/usr/lib cdplay.c -o /usr/local/bin/cdplay # compiles it
  462.   chmod +755 /usr/local/bin/cdplay                              # makes it executable
  463.   ln -s /dev/aztcd0 /dev/cdrom                                  # creates a link
  464.    (for /usr/lib substitute the top level directory, where your include files 
  465.     reside,  and for /usr/local/bin the directory, where you want the executable 
  466.     binary to reside )
  467.  
  468. You have to set the correct permissions for cdplay *and* for /dev/mcd0 or
  469. /dev/aztcd0 in order to use it. Remember, that you should not have /dev/cdrom 
  470. mounted, when you're playing audio CDs. 
  471.  
  472. This program is just a hack for testing the ioctl-functions in aztcd.c, I will 
  473. not maintain it, so if you run into problems, discard it or have a look into 
  474. the source code 'cdplay.c'. The program does only contain a minimum of user 
  475. protection and input error detection. If you use the commands in the wrong 
  476. order or if you try to read a CD at wrong addresses, you may get error messages
  477. or even hang your machine. If you get STEN_LOW, STEN_LOW_WAIT or segment violation 
  478. error messages when using cdplay, after that, the system might not be stable 
  479. any more, so you'd better reboot. As the ioctl-functions run in kernel mode,
  480. most normal Linux-multitasking protection features do not work. By using
  481. uninitialized 'wild' pointers etc., it is easy to write to other users data and
  482. program areas, destroy kernel tables etc.. So if you experiment with ioctls
  483. as always when you are doing systems programming and kernel hacking, you
  484. should have a backup copy of your system in a safe place (and you also
  485. should try before, how to restore from a backup copy)!
  486.  
  487.  
  488. Werner Zimmermann
  489. Fachhochschule fuer Technik Esslingen
  490. (EMail: zimmerma@rz.fht-esslingen.de)
  491. July 26, 1995
  492.  
  493. ---------------------------------------------------------------------------
  494. APPENDIX: Source code of cdplay.c
  495.  
  496. /* Tiny Audio CD Player
  497.  
  498.    Copyright 1994, 1995 Werner Zimmermann (zimmerma@rz.fht-esslingen.de)
  499.  
  500. This program originally was written to test the audio functions of the
  501. AZTECH.CDROM-driver, but it should work with every CD-ROM drive. Before 
  502. using it, you should set a symlink from /dev/cdrom to your real CDROM
  503. device.
  504.  
  505. The GNU General Public License applies to this program.
  506.  
  507. History:  V0.1  W.Zimmermann: First release. Nov. 8, 1994
  508.           V0.2  W.Zimmermann: Enhanced functionality. Nov. 9, 1994
  509.           V0.3  W.Zimmermann: Additional functions. Nov. 28, 1994          
  510.           V0.4  W.Zimmermann: fixed some bugs. Dec. 17, 1994
  511.           V0.5  W.Zimmermann: clean 'scanf' commands without compiler warnings
  512.                               Jan. 6, 1995
  513.           V0.6  W.Zimmermann: volume control (still experimental). Jan. 24, 1995
  514.           V0.7  W.Zimmermann: read raw modified. July 26, 95
  515. */
  516.  
  517. #include <stdio.h>
  518. #include <ctype.h>
  519. #include <sys/ioctl.h>
  520. #include <sys/types.h>
  521. #include <fcntl.h>
  522. #include <unistd.h>
  523. #include <linux/cdrom.h>
  524. #include <linux/aztcd.h>
  525.  
  526. void help(void)
  527. { printf("Available Commands:  STOP         s      EJECT/CLOSE  e       QUIT         q\n");
  528.   printf("                     PLAY TRACK   t      PAUSE        p       RESUME       r\n");
  529.   printf("                     NEXT TRACK   n      REPEAT LAST  l       HELP         h\n");
  530.   printf("                     SUB CHANNEL  c      TRACK INFO   i       PLAY AT      a\n");
  531.   printf("                     READ         d      READ RAW     w       VOLUME       v\n");
  532. }
  533.  
  534. int main(void)
  535. { int handle;
  536.   unsigned char command=' ', ini=0, first=1, last=1;
  537.   unsigned int cmd, i,j,k, arg1,arg2,arg3;
  538.   struct cdrom_ti       ti;
  539.   struct cdrom_tochdr   tocHdr;
  540.   struct cdrom_subchnl  subchnl;
  541.   struct cdrom_tocentry entry;
  542.   struct cdrom_msf      msf;
  543.   union  { struct cdrom_msf msf;
  544.            unsigned char buf[CD_FRAMESIZE_RAW];
  545.          } azt;
  546.   struct cdrom_volctrl  volctrl;
  547.  
  548.   printf("\nMini-Audio CD-Player V0.71   (C) 1994,1995  W.Zimmermann\n");
  549.   handle=open("/dev/cdrom",O_RDWR);
  550.   ioctl(handle,CDROMRESUME);
  551.   
  552.   if (handle<=0) 
  553.     { printf("Drive Error: already playing, no audio disk, door open\n");
  554.       printf("             or no permission (you must be ROOT in order to use this program)\n");
  555.     }
  556.   else
  557.     { help();
  558.       while (1)
  559.         { printf("Type command (h = help):  ");
  560.           scanf("%s",&command); 
  561.           switch (command)
  562.             { case 'e':   cmd=CDROMEJECT;
  563.                           ioctl(handle,cmd);
  564.                           break;  
  565.               case 'p':   if (!ini)
  566.                              { printf("Command not allowed - play track first\n");
  567.                              }
  568.                           else
  569.                              { cmd=CDROMPAUSE;
  570.                                if (ioctl(handle,cmd)) printf("Drive Error\n");
  571.                              }
  572.                           break;
  573.               case 'r':   if (!ini)
  574.                              { printf("Command not allowed - play track first\n");
  575.                              }
  576.                           else
  577.                              { cmd=CDROMRESUME;
  578.                                if (ioctl(handle,cmd)) printf("Drive Error\n");
  579.                              }
  580.                           break;
  581.               case 's':   cmd=CDROMPAUSE;
  582.                           if (ioctl(handle,cmd)) printf("Drive error or already stopped\n");
  583.                           cmd=CDROMSTOP;
  584.                           if (ioctl(handle,cmd)) printf("Drive error\n");
  585.                           break;
  586.               case 't':   cmd=CDROMREADTOCHDR;
  587.                           if (ioctl(handle,cmd,&tocHdr)) printf("Drive Error\n");
  588.                           first=tocHdr.cdth_trk0;
  589.                           last= tocHdr.cdth_trk1;
  590.                           if ((first==0)||(first>last))
  591.                             { printf ("--could not read TOC\n");
  592.                             }
  593.                           else
  594.                             { printf("--first track: %d   --last track: %d   --enter track number: ",first,last);
  595.                               cmd=CDROMPLAYTRKIND;
  596.                               scanf("%i",&arg1);
  597.                               ti.cdti_trk0=arg1;
  598.                               if (ti.cdti_trk0<first) ti.cdti_trk0=first;
  599.                               if (ti.cdti_trk0>last)  ti.cdti_trk0=last;
  600.                               ti.cdti_ind0=0;
  601.                               ti.cdti_trk1=last;
  602.                               ti.cdti_ind1=0;
  603.                               if (ioctl(handle,cmd,&ti)) printf("Drive Error\n");
  604.                               ini=1;
  605.                             } 
  606.                           break;
  607.               case 'n':   if (!ini++) 
  608.                             { if (ioctl(handle,CDROMREADTOCHDR,&tocHdr)) printf("Drive Error\n");
  609.                               first=tocHdr.cdth_trk0;
  610.                               last= tocHdr.cdth_trk1;
  611.                               ti.cdti_trk0=first-1;
  612.                             }
  613.                           if ((first==0)||(first>last))
  614.                             { printf ("--could not read TOC\n");
  615.                             }
  616.                           else
  617.                             { cmd=CDROMPLAYTRKIND;
  618.                               if (++ti.cdti_trk0 > last)  ti.cdti_trk0=last;
  619.                               ti.cdti_ind0=0;
  620.                               ti.cdti_trk1=last;
  621.                               ti.cdti_ind1=0;
  622.                               if (ioctl(handle,cmd,&ti)) printf("Drive Error\n");
  623.                               ini=1;
  624.                             }
  625.                           break;
  626.               case 'l':   if (!ini++)
  627.                             { if (ioctl(handle,CDROMREADTOCHDR,&tocHdr)) printf("Drive Error\n");
  628.                               first=tocHdr.cdth_trk0;
  629.                               last= tocHdr.cdth_trk1;
  630.                               ti.cdti_trk0=first+1;
  631.                             }
  632.                           if ((first==0)||(first>last))
  633.                             { printf ("--could not read TOC\n");
  634.                             }
  635.                           else
  636.                             { cmd=CDROMPLAYTRKIND;
  637.                               if (--ti.cdti_trk0 < first) ti.cdti_trk0=first;
  638.                               ti.cdti_ind0=0;
  639.                               ti.cdti_trk1=last;
  640.                               ti.cdti_ind1=0;
  641.                               if (ioctl(handle,cmd,&ti)) printf("Drive Error\n");
  642.                               ini=1;
  643.                             }  
  644.                           break;
  645.               case 'c':   subchnl.cdsc_format=CDROM_MSF;
  646.                           if (ioctl(handle,CDROMSUBCHNL,&subchnl)) 
  647.                             printf("Drive Error\n");
  648.                           else
  649.                             { printf("AudioStatus:%s   Track:%d  Mode:%d   MSF=%d:%d:%d\n", \
  650.                               subchnl.cdsc_audiostatus==CDROM_AUDIO_PLAY ? "PLAYING":"NOT PLAYING",\
  651.                               subchnl.cdsc_trk,subchnl.cdsc_adr, \
  652.                               subchnl.cdsc_absaddr.msf.minute, subchnl.cdsc_absaddr.msf.second, \
  653.                               subchnl.cdsc_absaddr.msf.frame);
  654.                             }
  655.                           break;              
  656.               case 'i':   if (!ini)
  657.                             { printf("Command not allowed - play track first\n");
  658.                             }
  659.                           else
  660.                             { cmd=CDROMREADTOCENTRY;
  661.                               printf("Track No.: ");
  662.                               scanf("%d",&arg1);
  663.                               entry.cdte_track=arg1;
  664.                               if (entry.cdte_track<first) entry.cdte_track=first;
  665.                               if (entry.cdte_track>last)  entry.cdte_track=last;
  666.                   entry.cdte_format=CDROM_MSF;
  667.                               if (ioctl(handle,cmd,&entry)) 
  668.                                { printf("Drive error or invalid track no.\n");
  669.                                }
  670.                               else
  671.                                { printf("Mode %d Track, starts at %d:%d:%d\n", \
  672.                                entry.cdte_adr,entry.cdte_addr.msf.minute, \
  673.                                entry.cdte_addr.msf.second,entry.cdte_addr.msf.frame);
  674.                                }
  675.                             }
  676.                           break;
  677.               case 'a':   cmd=CDROMPLAYMSF;
  678.                           printf("Address (min:sec:frame)  ");
  679.                           scanf("%d:%d:%d",&arg1,&arg2,&arg3);
  680.                           msf.cdmsf_min0  =arg1;
  681.                           msf.cdmsf_sec0  =arg2;
  682.                           msf.cdmsf_frame0=arg3;
  683.                           if (msf.cdmsf_sec0  > 59) msf.cdmsf_sec0  =59;
  684.                           if (msf.cdmsf_frame0> 74) msf.cdmsf_frame0=74;
  685.                           msf.cdmsf_min1=60;
  686.                           msf.cdmsf_sec1=00;
  687.                           msf.cdmsf_frame1=00;
  688.                           if (ioctl(handle,cmd,&msf)) 
  689.                            { printf("Drive error or invalid address\n");
  690.                            }
  691.                           break;
  692. #ifdef AZT_PRIVATE_IOCTLS /*not supported by every CDROM driver*/
  693.               case 'd':   cmd=CDROMREADCOOKED;
  694.                           printf("Address (min:sec:frame)  ");
  695.                           scanf("%d:%d:%d",&arg1,&arg2,&arg3);
  696.                           azt.msf.cdmsf_min0  =arg1;
  697.                           azt.msf.cdmsf_sec0  =arg2;
  698.                           azt.msf.cdmsf_frame0=arg3;
  699.                           if (azt.msf.cdmsf_sec0  > 59) azt.msf.cdmsf_sec0  =59;
  700.                           if (azt.msf.cdmsf_frame0> 74) azt.msf.cdmsf_frame0=74;
  701.                           if (ioctl(handle,cmd,&azt.msf)) 
  702.                            { printf("Drive error, invalid address or unsupported command\n");
  703.                            }
  704.                           k=0;
  705.                           getchar();
  706.                           for (i=0;i<128;i++)
  707.                            { printf("%4d:",i*16);
  708.                              for (j=0;j<16;j++)
  709.                                { printf("%2x ",azt.buf[i*16+j]);
  710.                                }
  711.                              for (j=0;j<16;j++)
  712.                                { if (isalnum(azt.buf[i*16+j])) 
  713.                                    printf("%c",azt.buf[i*16+j]);
  714.                                  else
  715.                                    printf(".");
  716.                                }
  717.                              printf("\n"); 
  718.                              k++;
  719.                              if (k>=20)
  720.                               { printf("press ENTER to continue\n");
  721.                                 getchar();
  722.                                 k=0;
  723.                               }
  724.                            } 
  725.                           break;
  726.               case 'w':   cmd=CDROMREADRAW;
  727.                           printf("Address (min:sec:frame)  ");
  728.                           scanf("%d:%d:%d",&arg1,&arg2,&arg3);
  729.                           azt.msf.cdmsf_min0  =arg1;
  730.                           azt.msf.cdmsf_sec0  =arg2;
  731.                           azt.msf.cdmsf_frame0=arg3;                          
  732.                           if (azt.msf.cdmsf_sec0  > 59) azt.msf.cdmsf_sec0  =59;
  733.                           if (azt.msf.cdmsf_frame0> 74) azt.msf.cdmsf_frame0=74;
  734.                           if (ioctl(handle,cmd,&azt)) 
  735.                            { printf("Drive error, invalid address or unsupported command\n");
  736.                            }
  737.                           k=0;
  738.                           for (i=0;i<147;i++)
  739.                            { printf("%4d:",i*16);
  740.                              for (j=0;j<16;j++)
  741.                                { printf("%2x ",azt.buf[i*16+j]);
  742.                                }
  743.                              for (j=0;j<16;j++)
  744.                                { if (isalnum(azt.buf[i*16+j])) 
  745.                                    printf("%c",azt.buf[i*16+j]);
  746.                                  else
  747.                                    printf(".");
  748.                                }
  749.                              printf("\n"); 
  750.                              k++;
  751.                              if (k>=20)
  752.                               { getchar();
  753.                                 k=0;
  754.                               }
  755.                            } 
  756.                           break;
  757. #endif
  758.               case 'v':   cmd=CDROMVOLCTRL;
  759.                           printf("--Channel 0 Left  (0-255): ");
  760.                           scanf("%d",&arg1);
  761.                           printf("--Channel 1 Right (0-255): ");
  762.                           scanf("%d",&arg2);
  763.                           volctrl.channel0=arg1;
  764.                           volctrl.channel1=arg2;
  765.                           volctrl.channel2=0;
  766.                           volctrl.channel3=0;
  767.                           if (ioctl(handle,cmd,&volctrl)) 
  768.                            { printf("Drive error or unsupported command\n");
  769.                            }
  770.                           break;  
  771.               case 'q':   if (close(handle)) printf("Drive Error: CLOSE\n");
  772.                           exit(0);
  773.               case 'h':   help();
  774.                           break;
  775.               default:    printf("unknown command\n");
  776.                           break;
  777.             }
  778.        }
  779.     }
  780.   return 0;
  781. }
  782.