home *** CD-ROM | disk | FTP | other *** search
/ World of A1200 / World_Of_A1200.iso / programs / disk / misc / scsiutil / scsiutil.doc < prev    next >
Text File  |  1995-02-27  |  13KB  |  347 lines
  1. SCSIUtil V2.0 - an utility for doing SCSI low level operations
  2.  
  3.  
  4. SCSIUtil (c) 1991,92,93,94 by Gary Duncan and Heiko Rath
  5.  
  6.  
  7.     Gary Duncan
  8.     Philips PTS
  9.     23 Lakeside Dr
  10.     Tally-Ho Technology Park
  11.     Burwood East Vic 3151
  12.     Australia
  13.  
  14.     EMail: gduncan@philips.oz.au
  15.  
  16.  
  17.     The Software Brewery
  18.     Dipl. Inform. (FH) Heiko Rath
  19.     Raiffeisenstr.10a
  20.     D-64331 Weiterstadt
  21.     Germany
  22.  
  23.     EMail: hr@brewhr.swb.de
  24.  
  25.  
  26.  BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
  27.  FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT
  28.  WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
  29.  PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND,
  30.  EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
  31.  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  32.  PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
  33.  PROGRAM IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME
  34.  THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
  35.  
  36.  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
  37.  WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
  38.  REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR
  39.  DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL
  40.  DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM
  41.  (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED
  42.  INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE
  43.  OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH
  44.  HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
  45.  DAMAGES.
  46.  
  47.  When redistributing this program ALWAYS redistribute the WHOLE
  48.  archive consisting of:
  49.  
  50.  - DMakefile
  51.  - HISTORY
  52.  - o/SCSIutil.o
  53.  - SCSI_priv.h
  54.  - SCSIutil.c
  55.  - TODO
  56.  - SCSIutil.doc
  57.  - smakefile
  58.  
  59.  The source is provided, therefore you can make changes yourself. The
  60.  only thing I'm asking is that if you do make changes, please get in
  61.  touch with me (hr@brewhr.swb.de), so that we can coordinate any
  62.  further development.
  63.  
  64.  
  65. What is SCSIUtil?
  66. =================
  67.  
  68.  It is a little utility to do some low level stuff with SCSI devices.
  69.  As I currently don't have too much time to work on it (I finished my
  70.  thesis and am now wasting most of my time with a full time job)
  71.  I release it to the public as it is. It is far from being perfect,
  72.  but it is useful to me. In it's current incarnation it has
  73.  the following features:
  74.  
  75.   - read the capacity of a SCSI device
  76.   - read 16 bit raw digital audio off an audio CD (works with Sony CDU
  77.     561 & 8003 & Toshiba 3401) (left/right channel and stereo
  78.     reading supported)
  79.   - read 16 bit raw digital audio off an audio CD and convert to 8 bit
  80.     (left/right channel supported)
  81.   - eject/insert a medium via software control
  82.   - display the Inquiry data of a SCSI device
  83.   - read & interpret a CD-ROM data block address header
  84.   - start/stop the motor on a device
  85.   - read pages via MODE SENSE
  86.   - play audio on a CD-ROM drive (tested with Sony CDU 561 = Apple CD-300
  87.     and Tosiba 3401)
  88.   - read sectors
  89.   - seek to a specified sector
  90.   - display table of contents (TOC) of a CD
  91.   - read subchannel information of a CD (tested with Sony CDU 561)
  92.   - allow/prevent medium removal
  93.   - change the output channel volume of a CD-ROM drive
  94.  
  95.  
  96. Why SCSIUtil?
  97. =============
  98.  
  99.  I needed some software to explore my new CD-ROM drive.
  100.  
  101.  Here is what SCSIUtil displays, if you invoke it without parameters:
  102.  
  103. SCSIutil V2.0 [Jan  4 1994 : 16:59:03] - written by Gary Duncan
  104.          (gduncan@philips.oz.au) and Heiko Rath (hr@brewhr.swb.de)
  105. Usage: SCSIutil [-dscsi_dev] <scsi_id> <command>
  106.  -c[r]                 : Read capacity [raw]
  107.  -d<l|r|s> sec blks sc : Read 16 bit digital audio(start sector/# blocks)(2)
  108.  -D<l|r> sec blks      : Read  8 bit digital audio(left or right channel)(3)
  109.  -e <0|1>              : Change medium (0=eject, 1=load)
  110.  -i[r]                 : Inquiry [raw]
  111.  -h[r] blk             : Read CD-ROM data block address header
  112.  -l <0|1>              : Allow/Prevent medium removal
  113.  -m <0|1>              : Stop/Start motor {0=stop, 1=start}
  114.  -o[r] contr page      : Mode sense (contr = 0-3))
  115.  -p st si et ei        : Play audio CD track (1-99), index (1-99)
  116.  -r[t] sec_no          : Read sectors [use trackdisk.device]
  117.  -s sec_no             : Seek to sector (5)
  118.  -t[r|l]               : Display TOC of an audio CD [raw|long]
  119.  -u[r] chan fmt track  : Read CD sub-channel information [raw] (6)
  120.  -v [vl0 vl1 vl2 vl3]  : Set output volume channels 0-3 (7)
  121.  
  122. Note 1: usually scsi_id = (BOARD * 100) + (LUN * 10) + SCSI_TARGET_ID
  123.      2: with 's' returns LRLRLR pairs of stereo audio, 2352 bytes per block
  124.         sc = Apple subcode (0=2352, 1=2368, 2=2448, 3=96 byte/block)
  125.      3: converted to 8 bit audio (-d and -D work with Sony CDU 561 & 8003)
  126.      4: contr 0: current, 1: changeable, 2: default, 3: saved values
  127.      5: to park heads, try sec_no of -1
  128.      6: Q-channel = 64, fmt: 0=Sub-Q Channel data,1=current CD-ROM pos.,
  129.         2=Media Catalog Number (UPC/Bar Code),3=Track ISRC
  130.      7: use -1 to leave volume of channel as it is, without argument shows
  131.         current volume settings
  132.  
  133. Documentation on the options of SCSIUtil:
  134. =========================================
  135.  
  136.  -c[r]               : Read capacity [raw]
  137.  
  138.     This will issue a READ CAPACITY to the device to get the
  139.     highest sector available, the sector size and the capacity
  140.     (= sector size * max sector). With the 'r' option SCSIUtil
  141.     will not try to interpret the returned data.
  142.  
  143.     BTW, the Apple CD-300 returns different sector sizes,
  144.     depending on the last read size (that means sometimes it is
  145.     96, 2048 or 2352).
  146.  
  147.  -d<l|r|s> sec blks sc : Read 16 bit digital audio(start sector/# blocks)(2)
  148.  
  149.     This will read data directly from the specified CD-ROM drive,
  150.     interpreting the information as raw digital input. A value for
  151.     the sector to start reading from is required as well as the
  152.     number of sectors to read. The data will be in 16-bit format
  153.     e.g.  SCSIutil 2 -ds 2 100 0 reads the first 100 blocks
  154.     starting from sector 2 as Stereo 16 bit data. One sector
  155.     corresponds to 1/75 of a second.  The data will be output to
  156.     stdout.  This works with the Sony CDU-8003/541/561 (Apple uses
  157.     the CDU-561 in their Apple CD-300).
  158.  
  159.     The sc parameter was tested with the Apple CD-300 and tells
  160.     the drive to return 2352/2368/2448/96 bytes/block. If you're
  161.     only interested in digital audio use sc=0 which just delivers
  162.     588 * 16 bit stereo samples per block = 2352 bytes. If you use
  163.     sc=1 the last 16 bytes contain information about the current
  164.     track/index and timeposition of the sample. Sc = 2 adds 96
  165.     bytes to the raw samples which supposedly contain all the
  166.     subchannels except the Q-subchannel. Usually there won't be
  167.     any useful data in these 96 bytes, but on CD+Graphics and
  168.     CD+Midi CDs (pretty rare) the graphics/midi information is
  169.     encoded. If anybody has some information regarding the
  170.     encoding of CD+G / CD+Midi please get in touch with me!
  171.  
  172.     The digital audio data sent to stdout looks like this (in case
  173.     of sc = 0):
  174.  
  175.     struct cdda_sector {
  176.       struct cdda_sample {
  177.         char left_channel_lsb;
  178.         char left_channel_msb;
  179.         char right_channel_lsb;
  180.         char right_channel_msb;
  181.       } samples[588];
  182.     };
  183.  
  184.     With mono, either the left or right channel is skipped.
  185.  
  186.     BEWARE: sometimes I get SCSI bus lockups while using this
  187.     command. I'm pretty sure that it's not SCSIUtil's fault, but
  188.     either a problem of the WD SCSI chip 33C93A 00-04-PROTO in my
  189.     Amiga 3000 or a firmware bug in the Apple CD-300 (my firmware
  190.     is release 1.8d). The lockups usually occur only if I read
  191.     more than about 150 sectors. When a lockup occurs, don't
  192.     panic! I usually power cycle the Apple CD-300 and everything
  193.     reverts to normal.  BTW, the Apple CD-300 sometimes returns
  194.     the following MODE SENSE errors for no obvious reason:
  195.  
  196.     SENSE_DATA: 70 00 00 00 00 00 00 0a 00 00 00 00 00 00 00 00 00 00
  197.     Error : err=45 , No error
  198.  
  199.     Since V1.905b SCSIUtil reschedules the failed SCSI command and
  200.     tries to reread the missing sectors, thus you shouldn't lose
  201.     any data. (When this happens you might notice a little glitch
  202.     in the digital data, this is caused by the CD-ROM drive's
  203.     inability to access a certain block directly - it might start
  204.     reading +- n sectors before/after the requested block).
  205.  
  206.  -D<l|r> sec blks    : Read  8 bit raw digital audio(left or right channel)(*3*)
  207.  
  208.     Does basically the same as the '-d' option, only divides every
  209.     16 bit word by 256 before sending it to stdout, which makes
  210.     for a cheap (and suboptimal) conversion to 8 bit. The warning
  211.     about SCSI bus lockups applies also to this command. A better way
  212.     to scale to 8 bit would be to find the min/max values in the
  213.     digital data and scale accordingly. Obviously you'd need another
  214.     program to do this job, as otherwise you'd have to keep the
  215.     whole sample in memory to perform this operation.
  216.  
  217.  -e <0|1>            : Change medium (0=eject, 1=load)
  218.  
  219.     By using this command you can eject a removable medium via
  220.     software, e.g. SCSIutil 2 -e 0 ejects the CD-ROM currently in
  221.     the drive with SCSI id 2.
  222.  
  223.  -i[r]               : Inquiry [raw]
  224.  
  225.     This command sends the INQUIRY command to the specified
  226.     device. This can be used to get all kinds of information about
  227.     the device. With the 'r' parameter SCSIUtil will not try to
  228.     interpret the information returned.
  229.  
  230.  -h[r] blk           : Read CD-ROM data block address header
  231.  
  232.     This will read the address header information of a particular
  233.     CD-ROM block, e.g. SCSIutil 2 -h 100 reads block 100 from SCSI
  234.     device 2 and returns the header information.
  235.  
  236.  -l <0|1>            : Allow/Prevent medium removal
  237.  
  238.     This command sends a PREVENT ALLOW MEDIUM REMOVAL to the SCSI
  239.     device.
  240.  
  241.  -m <0|1>            : Stop/Start motor {0=stop, 1=start}
  242.  
  243.     Start or stop the device motor of the specified device.
  244.     SCSIutil 2 -m 0 stops a CD that is playing in SCSI device 2.
  245.  
  246.  -o[r] contr page    : Mode sense (contr = 0-3)) (*4*)
  247.  
  248.     Reads MODE SENSE control pages from a SCSI device. The contr
  249.     parameter decides what pages to return:
  250.  
  251.     contr 0: current values
  252.               1: changeable values (not interpreted correctly by SCSIUtil)
  253.               2: default values
  254.               3: saved values
  255.  
  256.     The page value must be in the range of 0-63. Page 63 usually
  257.     returns all the available MODE SENSE pages.  With the 'r'
  258.     option SCSIUtil will not interpret the returned data.
  259.  
  260.  -p st si et ei      : Play audio CD track (1-99), index (1-99)
  261.  
  262.     Allows the playing of a series of audio tracks. Can use index
  263.     marks as well e.g. SCSIutil 2 -p 1 1 8 1 plays an Audio CD in
  264.     SCSI device 5 from Track 1 to Track 8.
  265.     Track and Index should be in the range of 1-99 (according to
  266.     the ANSI SCSI 2 specs). The Apple CD-300 accepts an index of 0
  267.     as play whole track, therefore I allowed the selection of 0 as
  268.     an index, even though the online help states otherwise. To
  269.     play a whole CD type: scsiutil 2 -p 1 0 99 0. To play only
  270.     track 3: scsiutil 2 -p 3 1 3 1.
  271.  
  272.  -r[t] sec_no        : Read sectors [use trackdisk.device]
  273.  
  274.     Read data sector off a SCSI device. In case of an audio CD use
  275.     the -d or -D commands to read digital audio data.
  276.  
  277.  -s sec_no           : Seek to sector (*5*)
  278.  
  279.     Seek the head of a device to the specified sector.
  280.  
  281.  -t[r|l]             : Display TOC of an audio CD [raw|long]
  282.  
  283.     Reads the table of contents of a CD. The TOC can contain
  284.     entries for data/audio tracks.  With the 'r' option SCSIUtil
  285.     won't interpret the returned data. With the 'l' option
  286.     SCSIUtil will display the TOC in a longer form.
  287.  
  288.  -u[r] chan fmt track: Read CD sub-channel information [raw] (*6*)
  289.  
  290.     Reads information from the specified sub-channel of a CD.
  291.  
  292.     Chan = 64 = Q-Sub-channel
  293.     Fmt 0: read Q-sub-channel
  294.      Doesn't work with the Apple CD-300 drive
  295.     Fmt 1: read current position data
  296.      Track must be 0
  297.     Fmt 2: read media catalog number (UPC/Bar Code)
  298.      Track must be 0
  299.     Fmt 3: read track international standard recording code (ISRC)
  300.      Track must be a valid track
  301.  
  302.     With the 'r' option SCSIUtil doesn't try to interpret the
  303.     returned data.
  304.  
  305.  -v [vl0 vl1 vl2 vl3]  : Set output volume channels 0-3 (7)
  306.  
  307.     Allows you to set the volume of the CD-ROM audio channels.
  308.     Values in the range of 0-255 are allowed. If you use -1 this
  309.     channel won't be affected. If -v is issued without additional
  310.     parameter, SCSIUtil will display the current volume settings.
  311.  
  312. The future:
  313. ===========
  314.  
  315.  There are several things that I'd like to implement, take a look at
  316.  the TODO file. If you have a need for some additional features you
  317.  can always try to talk me into implementing them (hint: I can be
  318.  bribed ;-)
  319.  
  320.  
  321. Acknowledgements:
  322. =================
  323.  
  324.  Fred Fish for his work for the Amiga community
  325.  
  326.  Gary Duncan (gduncan@philips.oz.au) for having written the original
  327.     version and releasing the source to the public
  328.  
  329.  Dave Hassal (dave@ainfo.equinox.gen.nz) for bugging me with questions
  330.     and pushing me into finishing SCSIUtil.
  331.  
  332.  Stefan Becker (stefanb@yello.adsp.sub.org) for supplying patches to allow
  333.     reading of digital audio with the Toshiba XM3401 and DICE-support.
  334.  
  335.  Ralph Babel for some _very useful_ hints/tips/tricks.
  336.  
  337.  Franz-Josef Reichert for his Jukebox.
  338.  
  339.  Frank Munkert (ln_fmu@pki-nbg.philips.de) for AmiCDROM, PlayCDDA
  340.     and some good suggestions.
  341.  
  342.  Free Software Foundation, Inc. for the no warranty text and use at
  343.     your own risk texts. Also thanks for some high quality SW.
  344.  
  345.  My fellow Software Brewers (Christian Balzer & Armin Sparr) for
  346.     support.
  347.