home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / misc / tracker_1 / Tracker / !Tracker / !TestTrack / DemoText < prev   
Text File  |  1989-10-20  |  32KB  |  956 lines
  1. RISC OS SCSIdriver
  2. ==================
  3.  
  4. Author: Nick Reeves, Richard Manby, BC
  5. Version: 0.18
  6.  
  7. History
  8.  
  9. 1) 24-Nov-88 NR:        Initial draft
  10. 2) 02-Dec-88 NR:        Added a) timeout parameter for SCSI_Op
  11.                               b) SCSI_Op to return operation id number, which
  12.                                  can be used to abort operation.
  13.                               c) parameter for number of bytes of extended
  14.                                  sense
  15. 0.03: 31-Jan-89 RCM:    Copy placed in Arf:doc
  16. 0.04:  1-Mar-89 RCM:    Defined data returned by 'Determine Device'
  17. 0.05: 15-Mar-89 RCM:    Removed 'Establish Device' and 'Remove Device'
  18.                         reason codes from SWI SCSI_Initialise.
  19.                         Changed reason codes for 'Determine Device' in
  20.                         SWI SCSI_Initialise from 4 to 2.
  21.                         Removed 'Return error statistics' from
  22.                         SWI SCSI_Status.
  23.                         SWI SCSI_Op; Moved transfer direction, Scatter,
  24.                         Poll, Retry & Background Bits in R0 into MSByte to
  25.                         leave room for its device ID field to grow.
  26.                         Added 'Set Error Response','Set Queue Behaviour' &
  27.                         'Disconnect' to SWI SCSI_Control.
  28. 0.06: 17-Apr-89 RCM:    Removed the scatter list Bit from SWI SCSI_Op, this
  29.                         Bit is now reserved.
  30.                         Commands execute totaly in the foreground or in the
  31.                         background. The 'return-after-some-of-the-data-has-
  32.                         been-transfered' cannot be supported by SCSI.
  33.                         Added section on error messages.
  34. 0.07: 25-Apr-89 RCM:    Tidied up some of the error messages
  35.                         Full definition of Host ID and Device ID
  36. 0.08: 16-May-89 RCM:    Reordered reason codes for
  37.                         SCSI_Control-SetErrorResponse.
  38.                         SetErrorResponse, SetTimeout & ControlDisconnect
  39.                         now return their previous settings.
  40. 0.09: 08-Jun-89 BC+RCM: Changed spec of SCSI_Version to indicate the
  41.                         hardware and software types as a Bitset.  Added all
  42.                         the error messages and their numbers,
  43.                         documented *Devices.  Admitted to total reentrancy
  44.                         and interrupt kosherness.
  45.                         Scatter list reimplemented.
  46.  
  47. 0.10: 26-Jun-89 RCM:    Removed restrictions on device having to be idle
  48.                         before issuing SWI SCSI_Control (eg on SetTimeout).
  49.                         Defined bit value for 'supports scatterlist' and for 
  50.                         'supports device reservation'.
  51.                         Added SWI SCSI_Reserve.
  52.                         Added R8 (access key) to any dangerous operations.
  53. 0.11: 30-Jun-89 RCM:    Reordered the error message section, so it made
  54.                         more sense.
  55.                         Added recommendations to SCSI_Control about the use
  56.                         of the control_disconnect reason code.
  57. 0.12: 04-Jul-89 RCM:    Changed "Device reserved" to "Reservation error"
  58. 0.13: 12-Jul-89 RCM:    Added SWI SCSI_List, *ScsiBlock
  59. 0.14: 23-Aug-89 RCM:    Added accesskey to *ScsiBlock
  60. 0.15: 29-Aug-89 RCM:    Added reason code 3 to SWI SCSI_Initialise.
  61. 0.16: 04-Sep-89 RCM:    Changed "Reservation error" to
  62.                         "SCSI driver reservation error" 
  63. 0.17: 19-Oct-89 RCM:    Reset Bus restores various defaults.
  64. 0.18: 20-Oct-89 RCM:    Added SBIC bug warning.
  65.  
  66.                 ============================================
  67.                 INTERFACE FOR THE RISC OS SCSI DEVICE DRIVER
  68.                 ============================================ 
  69.  
  70.  
  71.                                 Introduction
  72.                                 ============
  73. The SCSI device driver for RISC OS is a relocatable module whose
  74. interface consists of the following SWIs:
  75.  
  76. SCSI_Version              403C0    603C0
  77. SCSI_Initialise           403C1    603C1
  78. SCSI_Control              403C2    603C2
  79. SCSI_Op                   403C3    603C3
  80. SCSI_Status               403C4    603C4
  81. SCSI_ReadControlLines     403C5    603C5
  82. SCSI_EEProm               403C6    603C6
  83. SCSI_Reserve              403C7    603C7
  84. SCSI_List                 403C8    603C8
  85.  
  86. and the following * commands:
  87.  
  88. *Devices
  89. *ScsiBlock   (N.B. NOT IMPLEMENTED BY ACORN SCSIdriver)
  90.  
  91.  
  92.  
  93.  
  94. Note on Device ID and Host ID
  95. -----------------------------
  96.  
  97. The device ID is a composite of the SCSI id number, the logical unit number
  98. (LUN) within the device and the logical slot number of the SCSI card.
  99. They are packed into 8 bits as follows:
  100.  
  101.   Bits 2..0  SCSI device id (0..7)
  102.   Bits 4..3  Logical SCSI card number (0..3)
  103.   Bits 7..5  Logical unit number      (0..7)
  104.  
  105.  
  106. The SCSI card numbering is based on the relative slot positions of any SCSI
  107. cards in the machine, thus in a machine with 2 cards, in physical slots 2
  108. and 4 they are refered to as logical SCSI card numbers 0 and 1. In a machine
  109. with 1 card it may be placed in any slot refered to as logical SCSI card
  110. number 0.
  111.  
  112. The host ID is a similar composite, but of SCSI id number and logical slot
  113. number, with no LUN field.
  114.  
  115.   Bits 2..0  Host device id (0..7) - Usually 7
  116.   Bits 4..3  Logical SCSI card number (0..3)
  117.  
  118.  
  119. The Host device id is usually 7 and there must be no other devices on the
  120. bus with the same id.
  121.  
  122.  
  123.                                 The SWIs
  124.                                 ========
  125.  
  126. All SWIs conform to the RISC OS standard that is
  127. a) Any registers not explicitly defined as result parameters are preserved
  128. b) The processor flags N,Z and C are preserved.
  129. c) Errors are indicated by setting V and returning with R0 pointing at an
  130.    error block (If the Bit 17 clear version is called control passes to
  131.    the error handler instead).
  132. d) All SWIs preserve the interrupt state unless stated otherwise, and so
  133.    they may be called from interrupt or event routines.
  134. e) All SWIs are reentrant.
  135.  
  136.  
  137. ----------------------------------------------------------------------------
  138.  
  139.  
  140. SCSI_Version (403C0 & 603C0)
  141. ============
  142. This SWI is used to determine the version number of the drivers, whether it
  143. supports any particular later extension, and what particular hardware
  144. implementation is present.
  145.  
  146. entry: no parameters
  147.  
  148. exit:
  149.  R0 Bits 0..7 software minor version number, 0 for any release
  150.     Bits 8..31 software major version number eg 100 for 1.00
  151.  R1 Bitset of software features
  152.  R2 Bits 0..7 hardware minor version number, 0 for any release
  153.     Bits 8..31 hardware major version number eg 100 for 1.00
  154.  R3 Bitset of hardware features
  155.  
  156. The Bitset of software features is defined as follows;
  157.     Bit  31     Supports target mode
  158.     Bit  30     Supports configuration
  159.     Bit  29     Supports reading control lines
  160.     Bit  28     Supports device reservation
  161.     Bit  27     Supports multiple SCSI cards (and hence SWI SCSI_List)
  162.     Bit  26     Supports *ScsiBlock
  163.     Bits 25..16 Reserved must be 0
  164.     Bits 15..7  Reserved must be 1
  165.     Bit  6      Supports *Devices
  166.     Bit  5      Supports scatter list for SWI SCSI_Op
  167.     Bit  4      Supports messaging
  168.     Bit  3      Supports automatic "Request Sense"
  169.     Bit  2      Supports command queueing
  170.     Bit  1      Supports background data transfer
  171.     Bit  0      Supports target disconnect/reconnect
  172.  
  173. The Bitset of hardware features is defined as follows;
  174.     Bit  31     Supports configuration
  175.     Bits 30..16 Reserved must be 0
  176.     Bits 15..1  Reserved must be 1
  177.     Bit  0      Supports target mode
  178.  
  179. errors: none
  180.  
  181.  
  182. ---------------------------------------------------------------------------
  183.  
  184.  
  185. SCSI_Initialise (403C1 & 603C1)
  186. ===============
  187. This SWI performs various initialisations determined by a reason code in R0.
  188. Any additional parameters are given in subsequent registers.
  189.  
  190.  
  191. 'Reset Bus'
  192. -----------
  193. entry:
  194.  R0 0
  195.  R1 host ID
  196.  
  197. This call resets all options set by SCSI_Control to their default states and
  198. removes any device reservations. In addition it sets a new host ID and
  199. causes a full reset of the SCSI bus by driving the SCSI bus RESET line.
  200.  
  201. The default states set for each device are
  202.   Reservation     - none
  203.   Timeout=0       - no timeout
  204.   Error response  - report check condition as an error
  205.   Queue behaviour - wait until slot becomes free
  206.   Disconnect      - allow disconnect/reselect
  207.  
  208.  
  209. success exit: no results
  210.  
  211. errors:
  212.   &00020100 - No room for SCSI driver workspace
  213.   &00020103 - SCSI bus failed to reset
  214.   &00020104 - Invalid SCSI host ID
  215.  
  216.  
  217. 'Reset Device' - initiates the reset operation and returns immediately.
  218. --------------
  219. entry:
  220.  R0 1
  221.  R1 device ID
  222.  R8 access key
  223.  
  224. success exit: no results
  225.  
  226. errors:
  227.   &00020105 - Invalid SCSI device ID
  228.   &0002010E - SCSI driver reservation error
  229.  
  230.  
  231. 'Determine Device' - performs an Inquiry command to see what type the device
  232. ------------------   is and then performs the appropriate Read-Capacity
  233.                      command depending on the device type.
  234. entry:
  235.  R0 2
  236.  R1 device ID
  237.  R2 pointer to buffer for description, (16 bytes, word aligned).
  238.  
  239. success exit: buffer filled in
  240.  
  241.         Offset
  242.  R2 -->   0    Type = &00    Direct-access            (eg magnetic disk)
  243.                       &01    Sequential-access        (eg magnetic tape)
  244.                       &02    Printer device
  245.                       &03    Processor device
  246.                       &04    Write-once read-multiple (eg some optical discs)
  247.                       &05    Read-only                (eg some optical discs)
  248.                       &06-7E Reserved
  249.                       &7F    Logical unit not present
  250.                       &80-FF Vendor unique
  251.  
  252.           1    Removable medium Bit (Bit7)/Device-Type Qualifier (Bits 0..6)
  253.           2    ISO (b7..6)/ECMA (b5..3)/ANSI (b2..0) version
  254.           3    Reserved (reserved field returned by inquiry command)
  255.  
  256.           4   Additional length, extra data that could be obtained by an
  257.                inquiry command
  258.           5   }
  259.           6   } Reserved (by device driver - currently zero) 
  260.           7   }
  261.  
  262.         8..11  word highest logical block number  (converted to normal)
  263.        12..15  word block length                  ( ARM byte sex)
  264.  
  265.  
  266. errors:
  267.   &00020105 - Invalid SCSI device ID
  268.   &0002010A - Timeout
  269.  
  270.  
  271. Bytes 0..4 are the first 5 bytes returned by an inquiry command, byte 5 is
  272. provided to indicate how much additional data (vendor ID,product ID etc)
  273. could be obtained by an Inquiry command Bytes 5..7 are reserved by the
  274. device driver
  275.  
  276. Bytes 8..11 (word 2) & 12..15 (word 3) are the highest block count and block
  277. size returned by a Read Capacity command but have had the byte sex reversed
  278. to suit ARM's LDR instruction.
  279.  
  280.  
  281. 'Enumerate Device' - performs an Inquiry command to see what type the device
  282. ------------------   is and then performs the appropriate Read-Capacity
  283.                      Data returned as formatted text.
  284. entry:
  285.  R0 3
  286.  R1 device ID
  287.  R2 pointer to buffer for description, word aligned).
  288.  R3 buffer size
  289.  
  290. The data returned is a zero terminated string of the same form as that
  291. printed by *devices, ie
  292.  
  293. "ddd    ttttttttttttttttt cccc Mbytes vvvvvvvv pppppppppppppppp rrrr"
  294.  
  295. where the fields are device number, type, capacity, vendor, product and
  296. revision number.
  297.  
  298. If a device doesn't respond, a string containing just the device number is
  299. returned, if the device responds, but the 'read-capacity' call fails, the
  300. capacity field will be set to unknown.
  301.  
  302.  
  303. ----------------------------------------------------------------------------
  304.  
  305.  
  306. SCSI_Control (403C2 & 603C2)
  307. ============
  308. This SWI issuess various control commands determined by a reason code in R0.
  309. Any additional parameters are given in subsequent registers.
  310.  
  311.  
  312. 'Abort device' - cancels all outstanding operations on a device. 'Abort op'
  313. --------------   should normally be used instead wherever possible.
  314. entry:
  315.  R0 0
  316.  R1 device ID
  317.  R8 access key
  318.  
  319. success exit: no results
  320.  
  321. errors:
  322.   &00020105 - Invalid SCSI device ID
  323.   &0002010E - SCSI driver reservation error
  324.  
  325.  
  326. 'Abort op' - cancels a particular operation on a device.
  327. ----------
  328. entry:
  329.  R0 1
  330.  R1 device ID
  331.  R2 operation id as returned by SCSI_Op
  332.  R8 access key
  333.  
  334. success exit: no results
  335.  
  336. errors:
  337.   &00020105 - Invalid SCSI device ID
  338.   &0002010E - SCSI driver reservation error
  339.  
  340.  
  341. Reserved
  342. --------
  343. entry:
  344.  R0 2
  345.  R8 access key
  346.  
  347.  
  348. 'Set Timeout' - sets the default timeout for a device.
  349. -------------   
  350. entry:
  351.  R0 3
  352.  R1 device ID
  353.  R2 timeout value in centi-seconds or zero for no timeout
  354.  R8 access key
  355.  
  356. exit:
  357.  R2 previous timeout setting
  358.  
  359. errors:
  360.   &00020105 - Invalid SCSI device ID
  361.   &0002010E - SCSI driver reservation error
  362.  
  363.  
  364. 'Set Error Response' - controls the behaviour of CHECK CONDITION status.
  365. --------------------
  366. entry:
  367.  R0 4
  368.  R1 device ID
  369.  R2 0  If device returns 'check condition', return that as an error message.
  370.        This is for badly behaved devices with non-standard request sense
  371.        return blocks.
  372.     1  If device returns 'check condition' do a request sense automaticaly,
  373.        report the error.
  374.     2  If device returns 'check condition' do a request sense automaticaly, 
  375.        if 'unit attention', ignore it and reissue the command else report
  376.        the error.
  377.    -1 no action, return previous setting.
  378.  R8 access key
  379.  
  380. exit:
  381.  R2 previous setting
  382.  
  383. errors:
  384.   &00020105 - Invalid SCSI device ID
  385.   &0002010E - SCSI driver reservation error
  386.  
  387.  
  388. 'Set Queue Behaviour'
  389. ---------------------
  390.  
  391.   The driver supports disconnection/reselection and queueing of commands,
  392. this implies that when a command is issued, the podule hardware may be in
  393. use servicing another command, a command maybe queued/running for the target
  394. device or the queue may be full.
  395.  
  396. entry:
  397.  R0 5
  398.  R1 device ID
  399.  R2 0                       ie if queue full loop until a slot becomes free
  400.                                if command operates totally in the background
  401.                                control returns to the caller as soon as the
  402.                                command is queued
  403.                                if the command operates in the forground,
  404.                                portion, control returns when the command
  405.                                completes.
  406.     1 Reject if queue full  ie command accepted only if it can be queued/run
  407.                                without waiting.
  408.                                if command operates totally in background,
  409.                                control returns to the caller as soon as the
  410.                                command is queued
  411.                                if the command operates in the forground,
  412.                                portion, control returns when the command
  413.                                completes.
  414.     2 Reject if device busy ie command accepted only there are no other
  415.        (or queue full)         queued/running for this device.
  416.     3 Reject if podule busy ie accept command only if it will run immediatly
  417.    -1 no action, return previous setting.
  418.  R8 access key
  419.  
  420. exit:
  421.  R2 previous setting
  422.  
  423. errors:
  424.   &00020105 - Invalid SCSI device ID
  425.   &0002010E - SCSI driver reservation error
  426.  
  427.  
  428. 'Disconnect' - Allow/Inhibit disconnect/reselect
  429. ------------
  430.  
  431. entry:
  432.  R0 6
  433.  R1 device ID
  434.  R2 0 allow disconnect/reselect
  435.       (ie when the bus selection phase is complete, the driver will attempt
  436.           to send an IDENTIFY message with bit6 set, this tells the target that
  437.           it may disconnect if it wants to).
  438.     1 inhibit disconnect/reselect, so that once started, a command will proceed
  439.       to completion without allowing any other command to start/reconnect.
  440.       (ie when the bus selection phase is complete the driver will attempt
  441.           to send an IDENTIFY message with bit6 clear).
  442.     2 inhibit disconnect/reselect by not sending an identify message
  443.    -1 no action, return previous setting.
  444.  R8 access key
  445.  
  446. exit:
  447.  R2 previous setting
  448.  
  449. errors:
  450.   &00020105 - Invalid SCSI device ID
  451.   &0002010E - SCSI driver reservation error
  452.  
  453.  
  454. Note codes 0/1 cause SWI SCSI_Op to attempt to send an identify message once
  455.      the bus selection phase is complete. The target may choose not to take the
  456.      message (Not an error), in which case the driver proceedes to the command
  457.      phase. The target may reply to the message with a message reject.
  458.      These two cases do not produce an error from SCSI_Op, as the command may
  459.      still complete successfully, it will however remain connected all the
  460.      time.
  461.  
  462. Note Applications/filing systems are NOT expected to issue this call, as
  463.      all software/hardware should work happily regardless of any disconnections
  464.      that occur.
  465.  
  466.      It should only be issued by:
  467.  
  468.      1) The user (in his boot file) if his/her particular device mis-behaves
  469.         when sent messages.
  470.  
  471.      2) Application/filing system software specific to one vendors product that
  472.         is known to mis-behave when sent messages.
  473.  
  474.  
  475. ----------------------------------------------------------------------------
  476.  
  477.  
  478. SCSI_Op (403C3 & 603C3) - issues a SCSI command to a device.
  479. =======                   Can be called in the background.
  480.  
  481.  R0 Bits 0..7    Device ID
  482.     Bits 24..25  00 => no data transfer, 01 => read, 10=>write, 11=>reserved
  483.     Bit 26       Scatter Bit, if set, R3 is a pointer to a scatter list.
  484.     Bit 27       If clear, poll escape during transfer and abort if escape
  485.                  pressed
  486.     Bit 28       If set, repeatedly retry on timeout
  487.     Bit 29       Set if a background transfer (possibly 0 length).
  488.  R1 Length of SCSI control block
  489.  R2 Ptr to SCSI control block
  490.  R3 RAM ptr for start of transfer or pointer to scatter list of address length
  491.     pairs if Bit 26 of R0 is set. After each chunk in the scatter list is
  492.     transferred the address should be incremented and the length set to 0.
  493.  R4 Length of transfer (in bytes).
  494.  R5 Timeout in centiseconds or 0 for default timeout
  495.  R6 Address to call back when transfer is complete if background Bit set.
  496.     The call is made in IRQ mode with IRQs disabled.
  497.     If an error has occurred, V is set, R0 points to a non-dynamic error
  498.     block, (ie a pointer to a fixed block in the module rather than built
  499.     up in a buffer), R1 indicates the cause of the error and R2 the logical
  500.     address on the device of where the error occured.
  501.  R7 Workspace pointer to pass in R12 for background call back.
  502.  R8 access key
  503.  
  504. exit (V clear)
  505.  R0 returns a 32 Bit id incremented for each operation. Used to cancel op.
  506.  R3 updated to indicate how much of transfer was successful (if scatter
  507.     list, pointer to first unused/partially used entry).
  508.  R4 updated to the amount untransferred
  509.  
  510. exit (V set)
  511.  R0 points to an error block
  512.  R1 indicates the cause of the error
  513.  R2 hold the logical address on the device of where the error occured.
  514.  R3 updated to indicate how much of transfer was successful (if scatter
  515.     list, points to first unused entry, entry is updated to indicate amount
  516.     transfered).
  517.  R4 updated to the amount untransferred
  518.  
  519. errors:
  520.  many
  521.  
  522. Interrupts may be enabled by the call, this does not affect it's reentrancy.
  523.  
  524. N.B. See below for detailed description of errors
  525.  
  526.  
  527. ----------------------------------------------------------------------------
  528.  
  529.  
  530. SCSI_Status (403C4 & 603C4)
  531. ===========
  532. This SWI issues various control commands determined by a reason code in R0.
  533. Any additional parameters are given in subsequent registers.
  534.  
  535.  
  536. 'Check Device Status' - returns the status of the selected device
  537. ---------------------
  538. entry:
  539.  R0 0
  540.  R1 device ID
  541.  
  542. success exit:
  543.  R0 status
  544.     1 => Idle
  545.     2 => Busy
  546.     4 => Error
  547.    16 => not available
  548.  
  549. errors:
  550.   &00020105 - Invalid SCSI device ID
  551.  
  552.  
  553.  
  554. ----------------------------------------------------------------------------
  555.  
  556.  
  557. SCSI_ReadControlLines (403C5 & 603C5)  N.B. NOT IMPLEMENTED BY ACORN SCSIdriver
  558. =====================
  559.  
  560. Returns current state of SCSI bus lines 
  561.  
  562. entry:
  563.  R0 host ID
  564.  
  565. success exit: 
  566.  R0 SCSI data bus
  567.  R1 Control lines, 1 = asserted :
  568.     Bit  7   6   5   4   3   2   1   0
  569.         RST BSY REQ MSG C/D I/O SEL DBP                    
  570.  
  571.  R2 Control lines, 1 = asserted : 
  572.     Bit   7   6   5   4   3   2   1   0 
  573.                                  ATN ACK       
  574.     (Bits 7..2 are Bits of 5380 bus & status register)
  575.  
  576. errors:
  577.   &00020104 - Invalid SCSI host ID
  578.  
  579.  
  580. ----------------------------------------------------------------------------
  581.  
  582.  
  583. SCSI_EEProm (403C6 & 603C6)            N.B. NOT IMPLEMENTED BY ACORN SCSIdriver
  584. ===========
  585.  
  586. Reads/writes EEProm on SCSI podule 
  587.  
  588. entry: 
  589.  R0 Bits 0..3 address of 16 Bit word
  590.     Bit 10 set for write, clear for read
  591.  R1 Bits 0..15 write data (if R0 Bit 10 set)
  592.  
  593. success exit: 
  594.  R0 data read if R0 Bit 10 was set on entry
  595.  R0 preserved if R0 Bit 10 was clear on entry
  596.  
  597. errors:
  598.  
  599.  
  600. ----------------------------------------------------------------------------
  601.  
  602.  
  603. SCSI_Reserve (403C7 & 603C7)
  604. ============
  605.  
  606. This SWI allows the caller to claim exclusive use of a device and may prevent
  607. data corruption problems that may arise if a program (by accident or on
  608. purpose) issues a Write/Format/ModeSelect command to a device currently mounted
  609. by SCSIFS.
  610.  
  611. It also provides for a clean change of device ownership from one user to
  612. another, as SCSIdm for example is entitled to modify your disc, (to map out
  613. defects/format/partition it etc) but must only do so once SCSIFS has closed
  614. down all open files and dismounted the disc.
  615.  
  616.  
  617. 'Claim' - Claim exclusive use of a device
  618. -------
  619.  
  620. This call attempts to claim exclusive use of the given device.
  621. If the call is successful, the caller will be granted sole use of the
  622. 'dangerous' SCSIdriver calls for that device and may use them itself, only
  623. by supplying the access key registered at 'Claim' time. Other callers
  624. may only use safe calls such as SCSI_Initialise-DetermineDevice.
  625.  
  626. If the device has already been claimed, an error message
  627. 'SCSI driver reservation error' will be returned.
  628.  
  629. entry
  630.   R0 0
  631.   R1 device ID
  632.   R2 release address
  633.   R3 workspace pointer, to be passed in R12 when release address is called
  634.   R8 access key
  635.  
  636. exit
  637.   VC
  638.   VS & R0-> error
  639.  
  640. errors:
  641.   &00020105 - Invalid SCSI device ID
  642.   &0002010E - SCSI driver reservation error
  643.  
  644.  
  645. 'ForceClaim'
  646. ------------
  647.  
  648. This call is similar to 'Claim' above, however, if the device is already
  649. claimed, it will ask the current claimant to release it, by calling the
  650. release address registered for that device.
  651. The current owner should try to tidy up, and call 'Release' but may refuse
  652. by returning VS and R0 pointing to an error message
  653.  
  654. Aside: This call is used by SCSIdm to ask SCSIfs to close files and dismount
  655.        etc
  656.  
  657. entry
  658.   R0 1
  659.   R1 device ID
  660.   R2 release address
  661.   R3 workspace pointer, to be passed in R12 when release address is called
  662.   R8 access key
  663.  
  664. exit
  665.   VC
  666.   VS & R0-> error
  667.  
  668. errors:
  669.   &00020105 - Invalid SCSI device ID
  670.   &0002010E - SCSI driver reservation error
  671.   OR an error message passed back by the current claimant.
  672.  
  673. When the current claimant is called R0 will hold a reason code indicating:
  674.   R0 = 1 called from ForceClaim
  675.  
  676.  
  677. 'Release'
  678. ---------
  679. This call will remove the reservation of a device.
  680.  
  681. entry
  682.   R0 2
  683.   R1 device ID
  684.   R8 access key  (to prove you actually claimed it)
  685.  
  686. exit
  687.   VC
  688.   VS -> error
  689.  
  690. errors:
  691.   &00020105 - Invalid SCSI device ID
  692.   &0002010E - SCSI driver reservation error
  693.  
  694.  
  695. Passing access key value to SCSI SWI's
  696. ======================================
  697. The access key (probably WorkSpacePointer) should be passed in R8
  698. and is only checked if the specified device is claimed and the call/reason
  699. code is 'dangerous'.
  700.  
  701.  
  702. ----------------------------------------------------------------------------
  703.  
  704.  
  705. SCSI_List (403C8 & 603C8)
  706. =========
  707.  
  708. This is used by the ScsiLog module as part of the multiple SCSI card
  709. initialisation sequence (see separate SCSILog documentation).
  710.  
  711. exit:
  712.  R0 -> Null terminated list of podule addresses
  713.  
  714. This SWI returns a pointer to a null terminated list of SCSI podules
  715. available to SCSIdriver. The addresses are those of the 'slow access' space
  716. for the podule, ie, 
  717.  &03240000, &03244000, &03248000 or &0324C000 for podule slot 0,1,2 or 3.
  718.  
  719.  
  720. ----------------------------------------------------------------------------
  721.  
  722. SCSI messages & error codes
  723. ===========================
  724.  
  725. Errors reported by the SCSIdriver fall into 3 classes:
  726. 1) Those generated/detected by the driver
  727. 2) Interpretations of the SCSI status byte returned on command completion.
  728. 3) Interpretation of the sense data (collected on CHECK CONDITION status if
  729.    the error response is set to 0 or 1).
  730.  
  731.  
  732. Device driver errors
  733. ====================
  734.  
  735. &00020100 = "No room for SCSI driver workspace"
  736. &00020101 = "Unknown SCSI SWI number"
  737. &00020102 = "Unknown reason code for SCSI SWI"
  738. &00020103 = "SCSI bus failed to reset
  739. &00020104 = "Invalid SCSI host ID"
  740. &00020105 = "Invalid SCSI device ID
  741. &00020109 = "Device not idle"
  742. &0002010A = "Timeout" ; During selection phase
  743. &0002010B = "Timeout" ; During any other phase
  744. &0002010C = "Command queue not empty"
  745. &0002010D = "Command queue full"
  746. &0002010E = "SCSI driver reservation error"
  747. &0002010F = "Invalid parameters"
  748. &00020110 = "Parameter error"
  749. &00020111 = "Not callable from IRQ routine"  (reported by podule loader)
  750. &00020112 = "Operation aborted"
  751. &00020113 = "Unexpected disconnection"
  752.  
  753. Interpretation of the returned SCSI status byte
  754. ===============================================
  755.  
  756. On completion of the command, the target returns a status byte.
  757. The Vendor unique Bits are masked out and the following interpretations
  758. placed on the result.  If the returned status is GOOD then that is not an
  759. error so there will not be an error returned.  If the status retured is not
  760. GOOD then it will be translated into one of the following three errors;
  761.  
  762. &00020180 = "Target status - Check condition"
  763. &00020181 = "Target status - Busy"
  764. &00020182 = "Target status - Unknown"
  765.  
  766. Any other value, including GOOD/CHECK CONDITION/BUSY with reserved Bit 7
  767. set, is reported as an error "Target status - Unknown"
  768.  
  769. If the error response level is 1 or 2, then on 'CHECK CONDITION', the driver
  770. will automatically perform a request sense.
  771.  
  772.  
  773. Interpretation of the Sense data
  774. ================================
  775.  
  776. The first byte of returned sense data is masked to leave the
  777. Error-class/error-code code Bits these are interpreted as:
  778.  
  779. 0x..6x vendor unique error (non extended sense) } Reported as
  780. 71..7E reserved error      (extended sense)     } "Target error - Unknown"
  781. 7F     vendor unique error (extended sense)     }
  782.  
  783. 70                         (extended sense), the error is given by examination
  784.                            of the 'sense key' in byte 2 of the sense data
  785.  
  786.  
  787. &000201C0 = "Target error - No sense"
  788. &000201C1 = "Target error - Recovered error"
  789. &000201C2 = "Target error - Not ready"
  790. &000201C3 = "Target error - Medium error"
  791. &000201C4 = "Target error - Hardware error"
  792. &000201C5 = "Target error - Illegal request"
  793. &000201C6 = "Target error - Unit attention"
  794. &000201C7 = "Target error - Data protect"
  795. &000201C8 = "Target error - Blank check"
  796. &000201C9 = "Target error - Vendor unique"
  797. &000201CA = "Target error - Copy aborted"
  798. &000201CB = "Target error - Aborted command"
  799. &000201CC = "Target error - Equal"
  800. &000201CD = "Target error - Volume overflow"
  801. &000201CE = "Target error - Miscompare"
  802. &000201CF = "Target error - Reserved sense key"
  803.  
  804. &000201D0 = "Target error - Unknown"
  805.  
  806.  
  807. Errors produced by calling SWI SCSI_Op
  808. ======================================
  809.  
  810. When an error is returned by a call of SWI SCSI_Op, in addition to the normal
  811. error pointer in R0, R1 and R2 provide extra information:
  812.  
  813. R0 -> error message     - a standard RISC OS error block, consisting of a 1
  814.                           word error number, followed by an error message
  815. R1  = error indication  - this is a composite of the LSB of the above error
  816.                           number and the status/sense-errorclass/sense key
  817.                           that produced the error.
  818. R2  = logical address on the device of where the error occured.
  819.  
  820.  
  821.  
  822. Device driver detected errors
  823. =============================
  824.  
  825. R1 MSB = the LSB of the RISC OS error number. ie 0..127
  826. R1     = 0 (see note below)
  827. R1     = TBA } If error was due to an unexpected bus phase, the phase could
  828. R1 LSB = TBA } be indicated here - assume undefined for now.
  829.  
  830. R2     = undefined
  831. R3     = undefined
  832. R4     = undefined
  833.  
  834.  
  835. Status byte errors
  836. ==================
  837.  
  838. R1 MSB = the LSB of the RISC OS error number. ie 128..195
  839. R1     = 0 (see note below)
  840. R1     = 0
  841. R1 LSB = returned status byte (unmasked)
  842.  
  843. R2     = undefined
  844. R3     = indicates amount of data transfered
  845. R4     = amount of data not transfered
  846.  
  847.  
  848.  
  849. Returned Sense data
  850. ===================
  851.  
  852. Non-extended sense data returned
  853. --------------------------------
  854. R1 MSB = the LSB of the RISC OS error number. ie 196..255
  855. R1 UMB =   Bits 23..16 holds byte 0 of the returned sense data
  856.            Bit  23     is the 'Valid' Bit and is set if the 'Logical block
  857.                        address' in the returned sense data (in R2) is valid.
  858.            Bits 22..20 are the 'error class'
  859.            Bits 19..16 are the 'error code'
  860. R1 LMB =   Bits 15..13 are the 'vendor unique' Bits from byte 1
  861.            Bits 12..8  are zero
  862. R1 LSB =   Bits 7..0
  863.  
  864. R2     = 'Logical block address' returned in bytes 1..3 of the returnrd sense
  865.           data (the vendor unique Bits masked out).
  866. R3     = indicates amount of data transfered
  867. R4     = amount of data not transfered
  868.  
  869.  
  870. Extended sense data returned
  871. ----------------------------
  872. R1 MSB = the LSB of the RISC OS error number. ie 196..255
  873. R1     = byte 0 of the returned sense data
  874.            Bit 23 is the 'Valid' Bit and is set if the 'Information bytes'
  875.                   in the returned sense data (now in R2) are valid.
  876.            Bits 22..20 are the 'error class'
  877.            Bits 19..16 are the 'error code'
  878. R1     = 'segment number' ie byte 1 of the returned sense data
  879. R1        byte 2 of the returned sense data
  880.             Bit7      is 'Filemark'
  881.             Bit6      is 'EOM'
  882.             Bit5      is 'ILI'
  883.             Bit4      is 'reserved'
  884.             Bits 3..0 hold the 'sense key'
  885. R2     = the 'information bytes' returned as bytes 3..6 of the sense data,
  886.          (byte sex reversed to suit ARM).
  887. R3     = indicates amount of data transfered
  888. R4     = amount of data not transfered
  889.  
  890.  
  891. NOTE Bit 23 of R1 always indicates data-in-R2-is-valid, as it is either the
  892.      'valid' Bit returned by the request sense command, or zero.
  893.  
  894.  
  895.  
  896. ----------------------------------------------------------------------------
  897.  
  898.                                 The * commands
  899.                                 ==============
  900.  
  901. *Devices
  902. ========
  903.  
  904.   *Devices displays information on the devices attached to the SCSI
  905.  bus(es).  The resulting display shows the type of each device this can be
  906. either "Direct-access", "Sequential-access", "Printer", "Processor", "WORM",
  907. "Read-only", "Scanner", "Optical memory", "Changer", Communications",
  908. "Unknown", and "Host".  The capacity is calculated by multiplying the
  909. highest block number by the block size, as returned by a Read Capacity
  910. command.  The Vendor, Product and Revision fields are provided by the
  911. Inquiry command, and are displayed with mimimal formating.  An example of
  912. the output of this command is shown below;
  913.  
  914. Device Type              Capacity    Vendor   Product          Revision
  915. 0      Direct-access       18 Mbytes RODIME   RO652            5.02
  916. 1      
  917. 2      Direct-access      100 Mbytes CONNER   Cp3100-100mb-3.5 0.0C      
  918. 3      Read-only           27 Mbytes HITACHI  CDR              0004
  919. 4
  920. 5      Direct-access       43 Mbytes RODIME   RO3000S          1.24
  921. 6
  922. 7      Host                          ACORN    SCSI expansion   0000
  923.  
  924.  
  925. *ScsiBlock                       N.B. NOT IMPLEMENTED BY ACORN SCSIdriver
  926. ==========
  927.  
  928.  
  929.  
  930. *ScsiBlock  adr accesskey  devID  cdb0 cdb1 cdb2...
  931.  
  932.  
  933.  
  934. *ScsiBlock issues a SCSI command to the target device.
  935.   adr   is the address data transfer address
  936.   devID is the SCSI deviceID
  937.   cbd0  onwards (maximum of 12 parameters) are the bytes of the SCSI command
  938.         block to be sent.
  939.  
  940. errors unique to this command
  941. &0002010F - "Invalid parameters"
  942. &00020110 - "Parameter error"
  943.  
  944.  
  945.  
  946. Warning
  947. =======
  948. The use of SWI SCSI_Control with R0=1 (Abort Op), or the use of command
  949. timeouts may prove unreliable with certain versions of the WD33C93A SCSI bus
  950. interface controller. The current version of the chip, revision C, is known
  951. to exhibit problems, it is expected that later revisions will not.
  952.  
  953. The SBIC has a tendancy to hang if a RaiseATN command (issued by the device
  954. driver abort command code) is issued during a data-out phase.
  955.  
  956.