ATASPI for XL/XE computers "Atari (Advanced) SCSI Programming Interface" Document version: 0.9 [English] Date: Mai 1st 2001 Author: Matthias Belitz [matthias.belitz@gmx.net] Table of contents 0. Disclaimer 1. Introduction 2. Software interface 2.1. parameter 2.2. status Codes 3. ATASPI manager 3.1. Black Box 3.2. Other devices 4. drivers and tools 4.1. SCSI Monitor 4.2. Audio CD-Player A. sources of SCSI information material B. list of sense keys 0. Disclaimer This information is being presented for informational purposes only. The author can't be held accountable for damage to your equipment as a result of using this software or procedures. The fact, that information is given without refences, does not mean, that all contained procedures are commonly usable. All trademarks are copyrighted by their respective owners. 1. Introduction What is this programming interface good for ? There are a few number of SCSI interfaces for the XL/XE computers out now, f.e. BlackBox, MIO ... and the ATAPI devices for the IDE-interface are accessed by a similar commandset. At the moment every developer has to write his own drivers for basic access along with any tool that could be useful for his interface. This might be the reason, why only one interface ( I know) supports CD-ROM access at the moment even at least two further interfaces have the hardware interface to do so. So it would be a better solution to split the tools in abstract high level drivers and hardware specific low level drivers with a well documented software interface. A developer of a new IDE or SCSI interface only has to write the low level drivers and all of the already existing tools could be used. Here are some examples for such high level drivers or tools: - ISO 9660 FS driver to have read access to common CD-ROM - MS-DOS FS for access of Dos HD / medias (f.e. Zip 100) - CD-player Tool - even scanner tool may be possible 2. documentation of the software interface As SCSI devices are blockdevices, a reuse of the SIO-control interface would be a nice idea. 2.1. parameters I suggest the following implementation. DDEVIC $70 for ATASPI manager DUNIT $01 ..(number of ATASPI manager, could be more than one f.e. SCSI, IDE) DCOMND $XX ..(command code) DSTATS $ ..before execution data direction $80 write, $40 read, after execution error code DBUFR word ..adress of the databuffer DTIMO byte ..timeout value DBYTE word ..expected number of bytes to transfer DAUX word ..adress of the SRB (SCSI request block) command codes for ATASPI - manager (as suggested by original definition for ASPI from Adaptec) $00 host adapter inquiry $01 get device type $02 execute SCSI command $03 abort SCSI command $04 RESET SCSI device $05 set host adapter parameters $06 get disk drive information SCSI request block SRB byte TID target id byte CMDLEN command length (number of bytes follow; 6, 10, 12 byte SCSI commands possible) 6-12 bytes SCSI command The main goal should be to include the ASPI routines in device ROM, so that tools with any DOS could use it. Until there is a clear solution, a JMP ($0002) instruction will call the manager. This is the init vector for RESET when booted from tape. Because I guess, when using an ATASPI driver you had started up from disk or harddisk, this vector is free at the moment. JMP ($0002)+3 will reinitialize the manager. 2.2. status codes After command execution the command status and the number of bytes transferred by the manager are returned in DSTATS resp. DBYTE Note that this is the current state to get an error with number > $80 and be informed about the reason a little bit. They may still change to better fit into the common returned status code from Atari disk drives. 01 o.k. 8x by Software $82 wrong data direction -> the target wants to transmit data in other direction as you defined with DSTATS value $83 target wants to send message larger then 1 byte (could not handle yet) $84 unexpected busfree condition during command execution -> target had terminated command, maybe this command is not supported by the target $85 target requests more data to be transferred then you expected, maybe blocksize is larger as you thought $8A timeout -> maybe no target connected at the ID $8E no bus-free after Reset -> serious error $92 command not supported by ASPI manager (currently only $02 and $04) Cx remapped SCSI command status (status | %11000000) C0 GOOD -> redirectet to 01 C2 Check condition -> next command should be "request sense" C4 condition met C8 busy D0 intermediate (GOOD for command chains) E2 command terminated 3. Implementations of ATASPI manager 3.1. Black Box current version V 0.40 Important note: I would set the ATASPI manager now "Beta". It works with my configuration but may cause data loss (or even could damage your devices, who knows). Use it at your own risk. ATTENTION !!! This will be the first version, allowing execution of SCSI commands requesting data transfer from host to target (also including write commands). This may cause data-loss, if you dont know, what you are doing ! The manager will be located from $8000 to $8800 in RAM. After being loaded the ATASPI manager scans the bus Ids 0..6 LUN 0 for targets. When a target is found, some basic information is displayed: Idx Manufacturer Name of the target Cxxy Sxy with Idx x.. number of target Id Cxxy xx..target class: 00-> harddisk, 05-> CD-ROM y.. "r" when medium is removable Sxy x..ANSI SCSI revision, y.."c" when SCSI1 with CCS (common command set) support At the moment there are only the commands $02 (execute SCSI command) and $04 (RESET SCSI device) implemented yet. Command $04 supports only bus RESET. (I think this have to stay for BB, cause there is no possibility to initiate a message sequence by the BB without hardware modification.) 3.2. other devices The Black Box is the only supported device at the moment. I am currently working on a driver for the msc-IDE-interface, which could be used as a master for other interfaces. Note that the implementation of the ATASPI-interface for IDE-controllers is only useful, if the device supports full 16 bit (8+8 bit) access. Otherwise half the information from the device gets lost and other devices than harddisks could not be used. 4. Programs Note: These are not stand-alone programs. You have to load the ATASPI manager first ! These tools I would still call "Alpha"-state, which means that they are useable yet, but some functionality is missing and some little misfunctions and errors may occur. 4.1. SCSI mon (monitor) current V0.12 First basic version, which will allow to the execution of 10 different commands. At this time you are not able to set up own commands, but could play around with the ATASPI a little bit. You should use that to test your configuration. This also gives you examples, how the different SCSI command blocks look like and how different targets react, if you want to write own applications. screen: C1 Id3 L06 D40 #00FF S01 #0082 12 00 00 00 FF 00 00 00 00 00 00 00 00: 00 00 00 00 00 00 00 00 00 00 00 description line 1 Cx number of command buffer (x 0..9) Idx number of target Id (x 0..6; first byte of SRB) Lxx length of SCSI command in bytes (6, 0a, 0c; second byte of SRB) Dxx expected direction of data transfer (read..40, write..80; will be written to $0303 before command execution) #xxxx expected number of bytes to be transfered (will be written to $0308 before command execution) Sxx status of last command ($0303 after execution) #xxxx number of bytes transfered with last command ($0308 after execution) description line 2 the SCSI command descriptor block (byte 3-14 of SRB) description line 3-18 contents of data buffer commands 1..0 select command buffer 1..0 SHIFT 0..6 select taget Id0..Id6 ESCape leave program RETURN execute current SCSI command buffer M change display mod of data buffer ( 8 bytes hex/asc; 16 bytes hex; 32 bytes asc) C clear data buffer R bus reset; resets the SCSI bus < previous (logical block for read command; track for play audio) > next (logical block for read command; track for play audio) predifined commands 1 inquiry 2 mode sense 3 read10 4 read capacity 5 6 read toc (audio CD only) 7 play track 1 (audio CD only) 8 PAUSE/RESUME (audio CD only, toggles function with execution) 9 OPEN/LOAD (removeable media only, toggles function with execution) 0 request sense Note: A "request sense" command should be executed immediatly after the last command, when a status higher than $C0 was returned to check the reason of the error. That is why it is a good idea to set the Id of the request sense command (0) to the Id you are currently playing with. This gives you fast access to request sense if an error occurs. The sense key are the lower 4 bits of byte number 2 (start counting with zero as common in assembly language). Refer Appendix B for an explanation. Please try, if the commands are working with your devices. Unfotunatly there is no saving possibility yet, so you have to write down the data, sorry. I am especially interested in getting to know, how Zip drives handle POWER ON state and OPEN/LOAD. Here are some little hints: Be sure to send the command to the right target ! Have a look to the status code after the execution of a command. A value of $01 indicates, that everything worked fine from the point of the ATASPI manager. A code of $8x indicates a software problem, where $8A is a simple timeout (maybe target not connected). A $84 indicates an "unexpected bus free", maybe the target will not support the command (f.e. play for harddisks). A code of $Cx indicates a bus-problem, you should send a "request sense" command ("0") to the same target directly now. If this was well performed (status $01), it gives the reason for the last problem. 4.2. Audio CD player current V 0.20 It scans for the first CD-ROM connected. Then scans the CD (if one is inserted) The numbers printed are the tracks keyboard functions: P ... play/pause O ... open/load tray > ... play next track < ... play previus track ESC . leave programm It is not very complete yet, some basic features are still missing. But I have really no time left, to do that 8-(. A. sources of SCSI information material Here is a list, where you may find information about SCSI2 standard (physical interface, commandset ...) This information was taken from: ------------------------------------------ WELCOME TO ALT.COMP.HARDWARE.HOMEBUILT(v.20 Modified 6/18/97) This file contains frequently asked questions (FAQ) and general information pertaining to the newsgroup alt.comp.hardware.homebuilt. It is maintained by Mark Sokos (msokos1@gl.umbc.edu). It is posted every two weeks to the newsgroup alt.comp.hardware.homebuilt. The latest version may also be obtained by sending an e-mail request to the above address. This file is available via FTP from * ftp://rtfm.mit.edu/pub/usenet/alt.comp.hardware.homebuilt A DOS text version is available from: * ftp://ftp.netcom.com/pub/di/dibald/FAQS Dave Baldwin's FTP site * ftp://ftp.psyber.com/tcj/faqs The Computer Journal (TCJ FTP) An HTML version is available online at: * http://www.gl.umbc.edu/~msokos1 This file is (C) copyright 1996, 1997 by Mark Sokos. It may be freely copied and distributed as long as this notice remains intact and the file is not modified, and no fee is charged for its duplication. * SCSI: o http://www.symbios.com/ftp/pub/standards/io/scsi2 o http://www.abekrd.co.uk/SCSI2/SCSI2-index.html o ftp://ftp.compusult.nf.ca:/pub/sunos/scsi-doc/scsi1.17b.gz o ftp://ftp.loria.fr:/pub7/obi/Standards/scsi/ o ftp://unix.hensa.ac.uk:/mirrors/yggdrasil.fall95/disk1/usr/doc/scsi-1/ o ftp://ftp.funet.fi:/pub/doc/SCSI/SCSI1-docs.tar.gz o ftp://romeo-klive.nvg.unit.no:/pub/hardware/scsi-3/x3t10/drafts/scsi1 o ftp://ftp.nau.edu:/pub/info/hardware/scsi/ o ftp://relay.cs.toronto.edu:/doc/scsi/ o ftp://sunsite.unc.edu:/pub/academic/computer-science/history/pdp-8/fromnichols/scsi1-17b.zip o ftp://ftp.compusult.nf.ca:/pub/sunos/scsi-doc/scsi1.17b.gz o ftp://ftp.tu-clausthal.de:/docs/comp-allg/scsi2doc.zip o ftp://ftp.uni-kl.de:/pub3/docs+papers/scsi2 o ftp://ftp.funet.fi:/pub/doc/SCSI/SCSI2-docs.tar.gz o ftp://romeo-klive.nvg.unit.no:/pub/hardware/scsi-3/x3t10/drafts/scsi2 ----------------------------------------------------- B. SCSI2 sense keys ============================================================================== Sense Key Description -- ------------------------------------------------------------------- 0h NO SENSE. Indicates that there is no specific sense key information to be reported for the designated logical unit. This would be the case for a successful command or a command that received CHECK CONDITION or COMMAND TERMINATED status because one of the filemark, EOM, or ILI bits is set to one. 1h RECOVERED ERROR. Indicates that the last command completed successfully with some recovery action performed by the target. Details may be determinable by examining the additional sense bytes and the information field. When multiple recovered errors occur during one command, the choice of which error to report (first, last, most severe, etc.) is device specific. 2h NOT READY. Indicates that the logical unit addressed cannot be accessed. Operator intervention may be required to correct this condition. 3h MEDIUM ERROR. Indicates that the command terminated with a non- recovered error condition that was probably caused by a flaw in the medium or an error in the recorded data. This sense key may also be returned if the target is unable to distinguish between a flaw in the medium and a specific hardware failure (sense key 4h). 4h HARDWARE ERROR. Indicates that the target detected a non- recoverable hardware failure (for example, controller failure, device failure, parity error, etc.) while performing the command or during a self test. 5h ILLEGAL REQUEST. Indicates that there was an illegal parameter in the command descriptor block or in the additional parameters supplied as data for some commands (FORMAT UNIT, SEARCH DATA, etc.). If the target detects an invalid parameter in the command descriptor block, then it shall terminate the command without altering the medium. If the target detects an invalid parameter in the additional parameters supplied as data, then the target may have already altered the medium. This sense key may also indicate that an invalid IDENTIFY message was received (5.6.7). 6h UNIT ATTENTION. Indicates that the removable medium may have been changed or the target has been reset. See 6.9 for more detailed information about the unit attention condition. 7h DATA PROTECT. Indicates that a command that reads or writes the medium was attempted on a block that is protected from this operation. The read or write operation is not performed. ============================================================================== Sense Key Description -- ------------------------------------------------------------------- 8h BLANK CHECK. Indicates that a write-once device or a sequential- access device encountered blank medium or format-defined end-of- data indication while reading or a write-once device encountered a non-blank medium while writing. 9h Vendor Specific. This sense key is available for reporting vendor specific conditions. Ah COPY ABORTED. Indicates a COPY, COMPARE, or COPY AND VERIFY command was aborted due to an error condition on the source device, the destination device, or both. (See 7.2.3.2 for additional information about this sense key.) Bh ABORTED COMMAND. Indicates that the target aborted the command. The initiator may be able to recover by trying the command again. Ch EQUAL. Indicates a SEARCH DATA command has satisfied an equal comparison. Dh VOLUME OVERFLOW. Indicates that a buffered peripheral device has reached the end-of-partition and data may remain in the buffer that has not been written to the medium. A RECOVER BUFFERED DATA command(s) may be issued to read the unwritten data from the buffer. Eh MISCOMPARE. Indicates that the source data did not match the data read from the medium. Fh RESERVED. = The fields 12($0c) and 13($0d) give additional information (sense code). Note that f.e. CDROM drives will reject every first command after POWER ON, bus reset or media change to inform the host, that the media may have changed.