home *** CD-ROM | disk | FTP | other *** search
/ GEMini Atari / GEMini_Atari_CD-ROM_Walnut_Creek_December_1993.iso / files / mint / xhdi_100 / xhdispec.eng < prev    next >
Encoding:
Text File  |  1993-08-03  |  9.8 KB  |  255 lines
  1. @(#)XHDI/xhdispec.txt
  2. @(#)Julian F. Reschke, 22. März 1992
  3.  
  4. Specification of the `XHDI' cookie, March 22, 1992
  5. --------------------------------------------------
  6.  
  7. Cookie id: "XHDI". The contents of the cookie is the start address of a
  8. function, which provides procedures for dealing with block storage devices.
  9. As an additional check, the function is preceded by the long constant
  10. $27011992.
  11.  
  12. The contents of the XHDI cookie may change (because it can be used by
  13. more than one driver). Therefore, in some applications (example: DA's) the
  14. cookie contents must be inquired each time before the handler is called.
  15.  
  16. ALL FUNCTIONS HAVE TO BE CALLED FROM SUPERVISOR MODE. The effects of a call
  17. in user mode are undefined. All processor registers except d0 are
  18. preserved. EINVFN is returned for invalid opcodes.
  19.  
  20. Some of the function calls -- notably `XHReadWrite()' -- might be
  21. implemented by calls to BIOS or XBIOS functions and therefore can activate
  22. the `Critical Error Handler'. It's the responsibility of the caller to
  23. switch of the `CEH', if this is needed.
  24.  
  25. Some error codes:
  26.  
  27. TOS error codes:
  28.  
  29. 0:           OK (OK)
  30. -1:          unspecified error (ERROR)
  31. -2:          device not responding (EDRVNR)
  32. -15:         unknown device (EUNDEV)
  33. -32:         invalid function number (EINVFN)
  34. -36:         access denied, device is reserved (EACCDN)
  35. -46:         invalid drive number (EDRIVE)
  36.  
  37. SCSI error codes (ranging from -200 to -455)
  38.  
  39. (-200 - N):  SCSI error code N (the `Additional Sense Code', Byte 12 in the
  40.              `Extended Sense Format', see section 7.2.14 in `draft proposed
  41.              American National Standard for information systems - SMALL
  42.              COMPUTER SYSTEM INTERFACE - 2 (SCSI-2) March 9, 1990').
  43.  
  44. Note: obviously, you can get these (SCSI) error codes only for ACSI or
  45. SCSI devices. For other device types -- like the IDE drives in the ST Book
  46. -- you can get other error codes which have yet to be defined.
  47.  
  48. Parameters are passed the same way as to GEMDOS functions. All values are
  49. put onto the stack, with the 16 bit opcode last. The 32 bit result is
  50. returned in d0.
  51.  
  52.  
  53. Definition of data types:
  54.  
  55. UWORD:  16-Bit, unsigned
  56. LONG:   32-Bit, signed
  57. ULONG:  32-Bit, unsigned
  58. char *: 32-Bit, pointer to a zero terminated string
  59.  
  60.  
  61. Terms:
  62.  
  63. major:  Major Device Number
  64.  
  65.            0..7: Devices on the ACSI bus with ATARI-compatible command set
  66.           8..15: Devices on the SCSI bus
  67.          16..63: Extensions as defined in the pun field in the PUN_INFO
  68.                  structure.
  69.              64: Devices on the standard floppy controller
  70.         65..255: Extensions outside the scope of AHDI.
  71.  
  72. minor:  Minor Device Number (for 'major' 0..15: LUN of the ACSI or SCSI
  73.         device), maximal 255.
  74.  
  75. key:    A 16 bit key, returned by `XHReserve()', or 0, if the device is
  76.         not locked or if the key is unknown.
  77.  
  78.  
  79. The XHDI functions:
  80.  
  81. -----------------------------------------------------------------------
  82. Opcode 0: UWORD XHGetVersion (void);
  83.  
  84. Returns the current protocol version. Example: $0119 is Version 1.19 (the
  85. format is similar to that returned by `Sversion()', but high and low byte
  86. are not reversed). This version of the XHDI specification has the version
  87. number $0100.
  88.  
  89. -----------------------------------------------------------------------
  90. Opcode 1: LONG XHInqTarget (UWORD major, UWORD minor, ULONG *blocksize,
  91.                             ULONG *device_flags, char *product_name);
  92.  
  93. Returns information about the device specified by `major' and `minor'.
  94. Reservation made with `XHReserve()' are reflected in `device_flags'.
  95.  
  96. block_size:   Block size for this device (important for `XHReadWrite()').
  97.               Usually 512.
  98.  
  99. device_flags: (Bit set -> Capability available)
  100.  
  101.       Bit 0:  Device is stoppable (XH_TARGET_STOPPABLE)
  102.       Bit 1:  The medium is removable (XH_TARGET_REMOVABLE)
  103.       Bit 2:  The eject mechanism can be locked 
  104.               (XH_TARGET_LOCKABLE)
  105.       Bit 3:  The device can physically eject the medium
  106.               (XH_TARGET_EJECTABLE)
  107.       Bit 31: The device is currently reserved (XH_TARGET_RESERVED).
  108.  
  109.               All other bits are reserved, drivers should set them to zero.
  110.  
  111. product_name: Product name of the device, similar to the information
  112.               returned by the SCSI command INQUIRE (max. 33 characters
  113.               incl. terminating zero). If this information is not
  114.               available, the driver should return a zero length string.
  115.  
  116. Note: the caller may pass a zero pointer for `blocksize', `device_flags'
  117. and `product_name'.
  118.  
  119. -----------------------------------------------------------------------
  120. Opcode 2: LONG XHReserve (UWORD major, UWORD minor, UWORD do_reserve,
  121.                           UWORD key);
  122.  
  123. Reserves or releases a device. `XHLock()', `XHStop()' and `XHEject()'
  124. only work for reserved devices if the correct key parameter is passed.
  125.  
  126. Example: take a virtual memory manager which has locked a removable hard
  127. disk with the swap partition. You don't want the user to be able to unlock
  128. this device with a CPX module!
  129.  
  130. On success, a 16 bit key is returned.
  131.  
  132. do_reserve: (1) Reserve or (0) release.
  133. key:        (only used for release).
  134.  
  135. -----------------------------------------------------------------------
  136. Opcode 3: LONG XHLock (UWORD major, UWORD minor, UWORD do_lock,
  137.                        UWORD key);
  138.  
  139. Locks or unlocks the eject mechanism of the device.
  140.  
  141. do_lock: (1) Lock or (0) unlock.
  142. key:     if the device is reserved pass the key, otherwise zero.
  143.  
  144. -----------------------------------------------------------------------
  145. Opcode 4: LONG XHStop (UWORD major, UWORD minor, UWORD do_stop,
  146.                        UWORD key);
  147.  
  148. Stops (ships) or starts the device.
  149.  
  150. do_stop: (1) Stop or (0) start.
  151. key:     if the device is reserved pass the key, otherwise zero.
  152.  
  153. Note: if the drive is accessed, the driver should restart it without an
  154.       explicit restart call.
  155.  
  156. -----------------------------------------------------------------------
  157. Opcode 5: LONG XHEject (UWORD major, UWORD minor, UWORD do_eject,
  158.                         UWORD key);
  159.  
  160. Ejects or inserts the medium.
  161.  
  162. do_eject: Eject (1) or insert (0) medium.
  163. key:      if the device is reserved pass the key, otherwise zero.
  164.  
  165. -----------------------------------------------------------------------
  166. Opcode 6: ULONG XHDrvMap (void);
  167.  
  168. Returns a bit mask of BIOS devices supported by the XHDI driver(s) (as the
  169. return value from `Drvmap()').
  170.  
  171. -----------------------------------------------------------------------
  172. Opcode 7: LONG XHInqDev (UWORD bios_device, UWORD *major, UWORD *minor,
  173.                          ULONG *start_sector, BPB *bpb);
  174.  
  175. Returns major device number, minor device number, starting sector and BPB
  176. of a given BIOS device (Note: getting the BPB this way will NOT reset the
  177. internal media change state).
  178.  
  179. Note: the caller provides a pointer to the BPB structure, which is filled
  180. by the driver.
  181.  
  182. Return values: OK, EDRNVR (device not responding, eg. medium not inserted),
  183. EDRIVE (wrong BIOS device number) or some other applicable error code. Ff
  184. the error code is EDRVNR, `major', `minor' and `start_sector' contain the
  185. correct values anyway.
  186.  
  187. If `start_sector' is $FFFFFFFF, the device is only temporarily inaccessible
  188. (example: you have inserted a cartridge with two partitions, but three
  189. drive bits have been reserved for the device).
  190.  
  191. The BPB is invalid, if the structure element `recsiz' is zero.
  192.  
  193. Note: a file system is fully described by major and minor device number and
  194. the starting block number. This does NOT mean, that it is necessarely a FAT
  195. file system.
  196.  
  197. Note: the caller may pass a zero pointer for `major', `minor',
  198. `start_sector' and `bpb'.
  199.  
  200. -----------------------------------------------------------------------
  201. Opcode 8: LONG XHInqDriver (UWORD bios_device, char *name, char *version,
  202.                             char *company, UWORD *ahdi_version,
  203.                             UWORD *maxIPL);
  204.  
  205. Gets information about the driver for the bios_device.
  206.  
  207. name:         Name of driver (max. 17 characters).
  208. version:      String with version number (max. 7 characters).
  209. company:      Name of company/programmer (max. 17 characters).
  210. ahdi_version: AHDI version level (as defined in the PUN_INFO structure).
  211. maxIPL:       Highest IPL, under which the driver can work (usually 5 for
  212.               drivers which use _hz_200 for timing loops).
  213.  
  214. Note: the caller may pass a zero pointer for `name', `version', `company',
  215. `ahdi_version' and `maxIPL'.
  216.  
  217. -----------------------------------------------------------------------
  218. Opcode 9: LONG XHNewCookie (ULONG newcookie);
  219.  
  220. - OPTIONAL function, may return EINVFN -
  221.  
  222. /* send translations to julian@math.uni-muenster.de */
  223.  
  224.  
  225. ------------------------------------------------------------------------
  226. Opcode 10: LONG XHReadWrite (UWORD major, UWORD minor, UWORD rwflag,
  227.                              ULONG recno, UWORD count, void *buf);
  228.  
  229. Read or write physical blocks.
  230.  
  231. rwflag:       Bits 0..2: as defined in the AHDI Release Notes (3.00, April
  232.               18, 1990). Bit 3 (physical mode) is ignored. All other bits
  233.               are reserved and should be set to zero.
  234. recno:        block number
  235. count:        block count
  236. buf:          pointer to buffer
  237.  
  238.  
  239. ------------------------------------------------------------------------
  240.  
  241.  
  242. How to install more than one XHDI driver
  243. ----------------------------------------
  244.  
  245. (1) During the installation, check if the cookie is alreay set. If so:
  246.     
  247. (2) For `XHGetVersion()' first jump through the old vector and return the
  248.     minimum of this and your own version number.
  249.     
  250. (3) For `XHDrvmap()' first jump through the old vector and then or-in the
  251.     drive bits for the devices supported by you.
  252.     
  253. (4) For all other functions: check, if one of `your' devices. If not, jump
  254.     through the old vector.
  255.