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.

