home *** CD-ROM | disk | FTP | other *** search
/ Vectronix 2 / VECTRONIX2.iso / FILES_01 / HDDRV_40.LZH / HDDRIVER / XHDI-125.ZOO / xhdispec.eng < prev    next >
Text File  |  1994-10-09  |  22KB  |  557 lines
  1. @(#)XHDI/xhdispec.eng
  2. @(#)Julian F. Reschke, 9. Oktober 1994
  3.  
  4. Specification of the `XHDI' cookie, October 9, 1994
  5. ---------------------------------------------------
  6.  
  7. Cookie id: "XHDI". The contents of the cookie points to the start address 
  8. of a function, which provides procedures for dealing with block storage 
  9. devices. As an additional check, the function is preceded by the long 
  10. constant $27011992.
  11.  
  12. The contents of the XHDI cookie may change (because it can be used by more 
  13. 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 
  17. call 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. IDE error codes (ranging from -456 to -711)
  45.  
  46. (-456 - N):  IDE error code N (value of the IDE error register)
  47.  
  48. Note: obviously, you can get SCSI error codes only for ACSI or SCSI 
  49. devices. For other device types -- like the IDE drives in the `ST Book' 
  50. or `Falcon 030' (or machines with a third-party IDE interface) -- the 
  51. following assignments may be used:
  52.  
  53. Bit in IDE
  54. error register  meaning                 SCSI error   XHDI error
  55.  
  56. 1               Track 0 not found       $06          -206
  57. 0               DAM not found           $13          -219
  58. 4               ID-Field not found      $12          -218
  59. 7               Bad block mark          $10          -216
  60. 6               Uncorrectable error     $11          -217
  61. 2               Command aborted         $20          -232
  62. 5               Media Change            $28          -240
  63. 3               Media Change requested  $5A          -290
  64.  
  65. (it is recommended to test the bits in the above order).
  66.  
  67. For other devices (like disk drives connected to the floppy controller) 
  68. there may be other, not yet defined, error codes.
  69.  
  70. Parameters are passed the same way as to GEMDOS functions. All values 
  71. are put onto the stack, with the 16 bit opcode last, i.e. at the lowest 
  72. address. The 32 bit result is returned in d0.
  73.  
  74. Wherever it is specified that `the caller may pass a zero pointer' for a 
  75. pointer parameter, then passing such a zero pointer indicates that the 
  76. caller is not interested in the value to be returned. Drivers must always 
  77. check pointers for zero before dereferencing them.
  78.  
  79.  
  80. Definition of data types:
  81.  
  82. UWORD:  16-Bit, unsigned
  83. LONG:   32-Bit, signed
  84. ULONG:  32-Bit, unsigned
  85. char *: 32-Bit, pointer to a zero terminated string
  86.  
  87.  
  88. Terms:
  89.  
  90. major:  Major Device Number
  91.  
  92.            0..7: Devices on the ACSI bus with ATARI-compatible command set
  93.           8..15: Devices on the SCSI bus
  94.          16..17: Devices connected to the IDE interface
  95.          18..63: Extensions as defined in the pun field in the PUN_INFO
  96.                  structure.
  97.              64: Devices on the standard floppy controller
  98.         65..255: Extensions outside the scope of AHDI.
  99.  
  100. minor:  Minor Device Number (for 'major' 0..15: LUN of the ACSI or SCSI
  101.         device), maximal 255.
  102.  
  103. key:    A 16 bit key, returned by `XHReserve()', or 0, if the device is
  104.         not locked or if the key is unknown.
  105.  
  106.  
  107. The XHDI functions:
  108.  
  109. -----------------------------------------------------------------------
  110. Opcode 0: UWORD XHGetVersion (void);
  111.  
  112. Returns the current protocol version. Example: $0119 is Version 1.19 
  113. (the format is similar to that returned by `Sversion()', but high and low 
  114. byte are not reversed). This version of the XHDI specification has the 
  115. version number $0120.
  116.  
  117. -----------------------------------------------------------------------
  118. Opcode 1: LONG XHInqTarget (UWORD major, UWORD minor, ULONG *blocksize,
  119.                             ULONG *device_flags, char *product_name);
  120.  
  121. Returns information about the device specified by `major' and `minor'. 
  122. Reservation made with `XHReserve()' are reflected in `device_flags'.
  123.  
  124. block_size:   Block size for this device (important for `XHReadWrite()').
  125.               Usually 512.
  126.  
  127. device_flags: (Bit set -> Capability available)
  128.  
  129.       Bit 0:  Device is stoppable (XH_TARGET_STOPPABLE)
  130.       Bit 1:  The medium is removable (XH_TARGET_REMOVABLE)
  131.       Bit 2:  The eject mechanism can be locked 
  132.               (XH_TARGET_LOCKABLE)
  133.       Bit 3:  The device can physically eject the medium
  134.               (XH_TARGET_EJECTABLE)
  135.       Bit 29: Eject mechanism has been locked by the driver
  136.               (XH_TARGET_LOCKED, from XHDI 1.25 up)
  137.       Bit 30: Device has been stopped by the driver (XH_TARGET_STOPPED,
  138.               from XHDI 1.25 up)
  139.       Bit 31: The device is currently reserved (XH_TARGET_RESERVED)
  140.  
  141.               All other bits are reserved, drivers should set them to zero.
  142.  
  143. product_name: Product name of the device, similar to the information
  144.               returned by the SCSI command INQUIRE (max. 33 characters
  145.               incl. terminating zero). If this information is not
  146.               available, the driver should return a zero length string.
  147.  
  148. Note: the caller may pass a zero pointer for `blocksize', `device_flags' 
  149. and `product_name'.
  150.  
  151. Note: for IDE devices, product name information might have to be truncated 
  152. to fit into 32 characters. See `XHInqTarget2'.
  153.  
  154. -----------------------------------------------------------------------
  155. Opcode 2: LONG XHReserve (UWORD major, UWORD minor, UWORD do_reserve,
  156.                           UWORD key);
  157.  
  158. Reserves or releases a device. `XHLock()', `XHStop()' and `XHEject()' only 
  159. work for reserved devices if the correct key parameter is passed.
  160.  
  161. Example: take a virtual memory manager which has locked a removable hard 
  162. disk with the swap partition. You don't want the user to be able to unlock 
  163. this device with a CPX module!
  164.  
  165. On success, a 16 bit key is returned.
  166.  
  167. do_reserve: (1) Reserve or (0) release.
  168. key:        (only used for release).
  169.  
  170. -----------------------------------------------------------------------
  171. Opcode 3: LONG XHLock (UWORD major, UWORD minor, UWORD do_lock,
  172.                        UWORD key);
  173.  
  174. Locks or unlocks the eject mechanism of the device.
  175.  
  176. do_lock: (1) Lock or (0) unlock.
  177. key:     if the device is reserved pass the key, otherwise zero.
  178.  
  179. -----------------------------------------------------------------------
  180. Opcode 4: LONG XHStop (UWORD major, UWORD minor, UWORD do_stop,
  181.                        UWORD key);
  182.  
  183. Stops (ships) or starts the device.
  184.  
  185. do_stop: (1) Stop or (0) start.
  186. key:     if the device is reserved pass the key, otherwise zero.
  187.  
  188. Note: if the drive is accessed, the driver should restart it without an 
  189. explicit restart call.
  190.  
  191. -----------------------------------------------------------------------
  192. Opcode 5: LONG XHEject (UWORD major, UWORD minor, UWORD do_eject,
  193.                         UWORD key);
  194.  
  195. Ejects or inserts the medium.
  196.  
  197. do_eject: Eject (1) or insert (0) medium.
  198. key:      if the device is reserved pass the key, otherwise zero.
  199.  
  200. -----------------------------------------------------------------------
  201. Opcode 6: ULONG XHDrvMap (void);
  202.  
  203. Returns a bit mask of BIOS devices supported by the XHDI driver(s) (as the 
  204. return value from `Drvmap()').
  205.  
  206. -----------------------------------------------------------------------
  207. Opcode 7: LONG XHInqDev (UWORD bios_device, UWORD *major, UWORD *minor,
  208.                          ULONG *start_sector, BPB *bpb);
  209.  
  210. Returns major device number, minor device number, starting sector and BPB 
  211. of a given BIOS device (Note: getting the BPB this way will NOT reset the 
  212. internal media change state).
  213.  
  214. Note: the caller provides a pointer to the BPB structure, which is filled 
  215. by the driver.
  216.  
  217. Return values: OK, EDRNVR (device not responding, eg. medium not 
  218. inserted), EDRIVE (wrong BIOS device number) or some other applicable 
  219. error code. If the error code is EDRVNR, `major' and `minor' contain the 
  220. correct values anyway.
  221.  
  222. If `start_sector' is $FFFFFFFF, the device is only temporarily 
  223. inaccessible (example: you have inserted a cartridge with two partitions, 
  224. but three drive bits have been reserved for the device).
  225.  
  226. The BPB is invalid if the structure element `recsiz' is zero.
  227.  
  228. Note: a file system is fully described by major and minor device number 
  229. and the starting block number. This does NOT mean, that it is necessarely 
  230. a FAT file system.
  231.  
  232. Note: the caller may pass a zero pointer for `major', `minor', 
  233. `start_sector' and `bpb'.
  234.  
  235. -----------------------------------------------------------------------
  236. Opcode 8: LONG XHInqDriver (UWORD bios_device, char *name, char *version,
  237.                             char *company, UWORD *ahdi_version,
  238.                             UWORD *maxIPL);
  239.  
  240. Gets information about the driver for the bios_device.
  241.  
  242. name:         Name of driver (max. 17 characters).
  243. version:      String with version number (max. 7 characters).
  244. company:      Name of company/programmer (max. 17 characters).
  245. ahdi_version: AHDI version level (as defined in the PUN_INFO structure).
  246. maxIPL:       Highest IPL under which the driver can work (usually 5 for
  247.               drivers which use _hz_200 for timing loops).
  248.  
  249. Note: the caller may pass a zero pointer for `name', `version', 
  250. `company', `ahdi_version' and `maxIPL'.
  251.  
  252. -----------------------------------------------------------------------
  253. Opcode 9: LONG XHNewCookie (ULONG newcookie);
  254.  
  255. - OPTIONAL function, may return EINVFN -
  256.  
  257. /* send translations to reschke@math.uni-muenster.de */
  258.  
  259.  
  260. ------------------------------------------------------------------------
  261. Opcode 10: LONG XHReadWrite (UWORD major, UWORD minor, UWORD rwflag,
  262.                              ULONG recno, UWORD count, void *buf);
  263.  
  264. Read or write physical blocks.
  265.  
  266. rwflag:       Bits 0..2: as defined in the AHDI Release Notes (3.00, April
  267.               18, 1990). Bit 3 (physical mode) is ignored. All other bits
  268.               are reserved and should be set to zero.
  269. recno:        block number
  270. count:        block count
  271. buf:          pointer to buffer
  272.  
  273. -----------------------------------------------------------------------
  274. Opcode 11: LONG XHInqTarget2 (UWORD major, UWORD minor, ULONG *blocksize,
  275.                               ULONG *device_flags, char *product_name,
  276.                               UWORD stringlen);
  277.  
  278. - only with XHDI version 1.01 and above -
  279.  
  280. Returns information about the device specified by `major' and `minor'. 
  281. Reservations made with `XHReserve()' are reflected in `device_flags'.
  282.  
  283. block_size:   Block size for this device (important for `XHReadWrite()').
  284.               Usually 512.
  285.  
  286. device_flags: (Bit set -> Capability available)
  287.  
  288.       Bit 0:  Device is stoppable (XH_TARGET_STOPPABLE)
  289.       Bit 1:  The medium is removable (XH_TARGET_REMOVABLE)
  290.       Bit 2:  The eject mechanism can be locked 
  291.               (XH_TARGET_LOCKABLE)
  292.       Bit 3:  The device can physically eject the medium
  293.               (XH_TARGET_EJECTABLE)
  294.       Bit 29: Eject mechanism has been locked by the driver
  295.               (XH_TARGET_LOCKED, from XHDI 1.25 up)
  296.       Bit 30: Device has been stopped by the driver (XH_TARGET_STOPPED,
  297.               from XHDI 1.25 up)
  298.       Bit 31: The device is currently reserved (XH_TARGET_RESERVED).
  299.  
  300.               All other bits are reserved, drivers should set them to zero.
  301.  
  302. product_name: Product name of the device, similar to the information
  303.               returned by the SCSI command INQUIRE (max. `stringlen'    
  304.               characters incl. terminating zero). If this information is 
  305.               not available, the driver should return a zero length string.
  306.  
  307. stringlen:    Length of string buffer passed in `product_name'.
  308.  
  309. Note: the caller may pass a zero pointer for `blocksize', `device_flags' 
  310. and `product_name'. Product names of IDE devices may contain up to 40 
  311. characters.
  312.  
  313.  
  314. -----------------------------------------------------------------------
  315. Opcode 12: LONG XHInqDev2 (UWORD bios_device, UWORD *major, UWORD *minor,
  316.                            ULONG *start_sector, BPB *bpb, ULONG *blocks,
  317.                            char *partid);
  318.  
  319. - only with XHDI version 1.10 and above -
  320.  
  321. Returns major device number, minor device number, starting sector, BPB, 
  322. size and partition ID of a given BIOS device (Note: getting the BPB this 
  323. way will NOT reset the internal media change state).
  324.  
  325. Note: the caller provides a pointer to the BPB structure, which is 
  326. filled by the driver.
  327.  
  328. Return values: OK, EDRNVR (device not responding, eg. medium not 
  329. inserted), EDRIVE (wrong BIOS device number) or some other applicable 
  330. error code. If the error code is EDRVNR, `major' and `minor' 
  331. `start_sector' contain the correct values anyway.
  332.  
  333. If `start_sector' is $FFFFFFFF, the device is only temporarily 
  334. inaccessible (example: you have inserted a cartridge with two partitions, 
  335. but three drive bits have been reserved for the device).
  336.  
  337. The BPB is invalid if the structure element `recsiz' is zero.
  338.  
  339. If the partition ID isn't available (possible reason: no standard Atari 
  340. root sector or no root sector at all), an empty string is returned.
  341.  
  342. Starting with XHDI 1.20 for MSDOS compatible media the one byte partition 
  343. code is returned as: partid[0] = '\0' (zero byte), partid[1] = 'D' (for 
  344. 'DOS'), partid[2] = partition code.
  345.  
  346. Note: a file system is fully described by major and minor device number 
  347. and the starting block number. This does NOT mean, that it is necessarely 
  348. a FAT file system.
  349.  
  350. Note: the caller may pass a zero pointer for `major', `minor', 
  351. `start_sector', `bpb', `blocks' and `partid'.
  352.  
  353.  
  354. -----------------------------------------------------------------------
  355. Opcode 13: LONG XHDriverSpecial (ULONG key1, ULONG key2,
  356.                                  UWORD subopcode, void *data);
  357.  
  358. - OPTIONAL function, may return EINVFN -
  359.  
  360. This opcode may be used for driver specific extensions. It's up to the 
  361. driver how to interpret the arguments in `subopcode' and `data'. `key1' 
  362. and `key2' are used to specify for which driver the call is: `key1' should 
  363. contain four printable ASCII characters, `key2' a `random' ULONG value 
  364. (example: date of definition in BCD format).
  365.  
  366.  
  367. -----------------------------------------------------------------------
  368. Opcode 14: LONG XHGetCapacity (UWORD major, UWORD minor, ULONG *blocks,
  369.                                ULONG *blocksize);
  370.  
  371. - OPTIONAL function, may return EINVFN -
  372.  
  373. This functions returns the number of adressable sectors in `blocks' 
  374. and their size in `blocksize'. Note that -- depending of the device used 
  375. -- this function may need several seconds to complete.
  376.  
  377.  
  378. -----------------------------------------------------------------------
  379. Opcode 15: LONG XHMediumChanged (UWORD major, UWORD minor);
  380.  
  381. - OPTIONAL function, may return EINVFN -
  382.  
  383. Informs the driver that the medium in the given device has been changed. 
  384. Upon this notice, the driver should do the same things as if the device 
  385. itself would have returned a media change status. The return value is OK 
  386. if and only if this information has been correctly interpreted (this 
  387. means: all logical drives on the device are either disabled or ready to 
  388. use).
  389.  
  390.  
  391. -----------------------------------------------------------------------
  392. Opcode 16: LONG XHMiNTInfo (UWORD opcode, void *data);
  393.  
  394. - OPTIONAL function, may return EINVFN -
  395.  
  396. A function for setting/inquiring MiNT related information.
  397.  
  398. The following opcodes are defined (for unknown opcodes EINVFN is returned, 
  399. OK is returned if and only if the call has been executed correctly).
  400.  
  401. XH_MI_SETKERINFO (0) [struct kerinfo *data]
  402.  
  403. Sends (through `data') a pointer to the MiNT kernel info structure to the 
  404. driver. The driver can use it for direct calls of kernel functions.
  405.  
  406. XH_MI_GETKERINFO (1) [struct kerinfo **data]
  407.  
  408. Inquires for a previously set MiNT kernel info pointer. The pointer is 
  409. returned in the struct kerinfo * pointed by `data'. If the adress of the 
  410. MiNT kernel info structure is unknown, `data' is filled with a NULL 
  411. pointer.
  412.  
  413.  
  414. -----------------------------------------------------------------------
  415. Opcode 17: LONG XHDOSLimits (UWORD which, ULONG limit);
  416.  
  417. - OPTIONAL function, may return EINVFN -
  418.  
  419. This functions aks the driver for the internal limits of the currently 
  420. running DOS (or sets the driver's limits). Example: it can be used by a 
  421. FAT file system driver to inform the driver about the change of some of 
  422. the limits. `which' describes the type of limit, `limit' is the new value 
  423. (with zero meaning that the value shouldn't be changed). The function 
  424. returns the previous value for the limit:
  425.  
  426. Constants for `which':
  427.  
  428. XH_DL_SECSIZ (0): maximal sector size (BIOS level)
  429. XH_DL_MINFAT (1): minimal number of FATs
  430. XH_DL_MAXFAT (2): maximal number of FATs
  431. XH_DL_MINSPC (3): sectors per cluster minimal
  432. XH_DL_MAXSPC (4): sectors per cluster maximal
  433. XH_DL_CLUSTS (5): maximal number of clusters
  434. XH_DL_MAXSEC (6): maximal number of sectors
  435. XH_DL_DRIVES (7): maximal number of BIOS drives supported by the DOS
  436.  
  437.  
  438. -----------------------------------------------------------------------
  439. Opcode 18: LONG XHLastAccess (UWORD major, UWORD minor, ULONG *ms);
  440.  
  441. - only with XHDI version 1.25 and above -
  442.  
  443. Returns in `ms' the amount of milliseconds since the last successfull read 
  444. or write operation on the device.
  445.  
  446.  
  447. -----------------------------------------------------------------------
  448. Opcode 19: LONG XHReaccess (UWORD major, UWORD minor);
  449.  
  450. - only with XHDI version 1.25 and above -
  451.  
  452. Calling this function causes the driver to check the device for a possible 
  453. media change and to actualize partition informations if needed (like 
  454. `XHMediumChange()', but the driver checks for the media change status 
  455. before continuing).
  456.  
  457.  
  458. ------------------------------------------------------------------------
  459.  
  460.  
  461. How to install more than one XHDI driver
  462. ----------------------------------------
  463.  
  464. (1) During the installation, check if the cookie is alreay set. If so:
  465.     
  466. (2) For `XHGetVersion()' first jump through the old vector and return the
  467.     minimum of this and your own version number.
  468.     
  469. (3) For `XHDrvmap()' first jump through the old vector and then or-in the
  470.     drive bits for the devices supported by you.
  471.     
  472. (4) For all other functions: check, if one of `your' devices. If not, jump
  473.     through the old vector.
  474.  
  475.  
  476. ------------------------------------------------------------------------
  477.  
  478. Partition type `RAW'
  479. --------------------
  480.  
  481. XHDI-1.10 compliant drivers shall support the third partition type `RAW' 
  482. (in addition to `GEM' and `BGM'). For these partitions, the following 
  483. should be true:
  484.  
  485. (1) The partition size is `arbitrary' (32 bit sector numbers).
  486.  
  487. (2) The partition can be accessed as BIOS device; Getbpb() returns a
  488.     NULL pointer (so that GEMDOS won't access it; however, calling
  489.     Getbpb() resets the driver internal media change state).
  490.  
  491. (3) `Rwabs()' (in physical or logical mode) and `XHReadWrite()' may be
  492.     used to access the partition. The physical block size of the medium
  493.     is used (see `XHInqTarget()').
  494.  
  495. (4) `XHInqDev2()' (as compared to `XHInqDev()') returns size and type of
  496.     the partition.
  497.  
  498. These extensions have been made to make it easier to create drivers
  499. for new filesystems for MiNT (like the Minix file system).
  500.  
  501.  
  502. ------------------------------------------------------------------------
  503.  
  504. Recommended partition types
  505. ---------------------------
  506.  
  507. BGM     GEMDOS partition > 16MB
  508. GEM     GEMDOS partition < 16MB
  509. RAW     see above
  510.  
  511. The following types can be supported optionally (for example with a 
  512. configurable list of partition ID's in the driver).
  513.  
  514. MAC     MAC HFS partition, should be handled like `RAW'
  515. MIX     Minix partition, should be handled like `RAW'
  516. QWA     QDOS partition, should be handled like `RAW'
  517. SWP     Swap partition, should be handled like `RAW'
  518. UNX     ASV (Atari System V) partition, should be handled like `RAW'
  519.  
  520.  
  521. -------------------------------------------------------------------------
  522.  
  523. Arbitration
  524. -----------
  525.  
  526. For device drivers which support SCSI arbitration, the machine needs an 
  527. own SCSI device number which must be unique and shouldn't be stored on 
  528. disk. Atari has reserved byte 16 in the Non Volatile Memory of the Atari 
  529. TT and Falcon computers. Bit assignments:
  530.  
  531. Bit 0..2:   device number
  532.    Bit 7:   arbitration on (1) or off (0)
  533.  
  534. The current arbitration number could be inquired this way:
  535.  
  536. int
  537. arbitration_id (void)
  538. {
  539.     long ret = EINVFN;
  540.     unsigned char nvmdata = 0;
  541.     OSHEADER *Sys;
  542.     long oldstack = Super (0L);
  543.     Sys = *_sysbase;
  544.     Super ((void *)oldstack);
  545.  
  546.     host_id = -1;   /* no arbitration by default */
  547.  
  548.     if (Sys->os_version >= 0x300)
  549.         ret = NVMaccess (0, 16, (int) sizeof (nvmdata), &nvmdata);
  550.  
  551.     if (ret == E_OK && (nvmdata & 0x80))
  552.         host_id = nvmdata & 7;
  553.  
  554.     return host_id;
  555. }
  556.  
  557.