Home XHDI - eXtended HardDisk Interface (Version 1.30)XHDI - eXtended HardDisk Interface (Version 1.30) Recommended partition typesRecommended partition types Type definitionsType definitions

H.5 XHDI functions

All functions have to be called from supervisor-mode. The effects of a call in user-mode are undefined. All processor registers except d0 are preserved. EINVFN is returned for invalid opcodes.

Some of the function calls - notably `XHReadWrite' - might be implemented by calls to BIOS or XBIOS functions and therefore can activate the `Critical Error Handler'. It's the responsibility of the caller to switch of the `CEH', if this is needed.

The following return values are defined for all functions:

TOS error-codes:

0: OK (OK)
-1: Unspecified error (ERROR)
-2: Device not responding (EDRVNR)
-15: Unknown device (EUNDEV)
-32: Invalid function number (EINVFN)
-36: Access denied, device is reserved (EACCDN)
-46: Invalid drive number (EDRIVE)

SCSI error-codes (ranging from -200 to -455)

(-200 - N): SCSI error-code N (the `Additional Sense Code', byte 12 in the `Extended Sense Format', see Appendix B in `Draft proposed American National Standard for information systems - Revision 11a - SCSI-3 Primary Commands, 28 March 1997)
 

IDE error-codes (ranging from -456 to -711)

(-456 - N): IDE error-code N (value of the IDE error register)
 

Note: Obviously, you can get SCSI error-codes only for ACSI or SCSI devices. For other device types like IDE drives the following assignments may be used:

Bit in IDE-      
error register Meaning SCSI error XHDI error
1 Track 0 not found $06 -206
0 DAM not found $13 -219
4 ID-Field not found $12 -218
7 Bad block mark $10 -216
6 Uncorrectable error $11 -217
2 Command aborted $20 -232
5 Media Change $28 -240
3 Media Change requested $5A -290

(It is recommended to test the bits in the above order).

For other devices (like disk drives connected to the floppy controller) there may be other, not yet defined, error-codes.

Parameters are passed the same way as to GEMDOS functions. All values are put onto the stack, with the 16-bit opcode last, i.e. at the lowest address. The 32-bit result is returned in d0.

Wherever it is specified that `the caller may pass a zero pointer' for a pointer parameter, then passing such a zero pointer indicates that the caller is not interested in the value to be returned. Drivers must always check pointers for zero before dereferencing them.

See also: XHDI specification   SCSI specification   About the BIOS

H.5.1 XHGetVersion

Name: »XHGetVersion« - Inquire protocol version.
 
Opcode: 0
 
Syntax: UWORD XHGetVersion ( VOID );
 
Description: XHGetVersion returns the current protocol version. Example: 0x0119 is Version 1.19 (the format is similar to that returned by Sversion but high and low bytes are not reversed). This version of the XHDI specification has the version number 0x0130.
 
Return value: The return value describes the version number of the XHDI protocol, with the high byte containing the version number and the low byte the revision.
 
Group: XHDI functions
 
See also: Arbitration   _drvbits   Partition types   System variables   XHDI cookie   XHDI terminology
 

H.5.2 XHInqTarget

Name: »XHInqTarget« - Return information about a device.
 
Opcode: 1
 
Syntax: LONG XHInqTarget ( UWORD major, UWORD minor, ULONG *block_size, ULONG *device_flags, BYTE *product_name );
 
Description: XHInqTarget returns information about the device specified by major and minor. Reservations made with XHReserve are reflected in device_flags.
 
Return value:
 
Bit Meaning
   
block_size Block size for this device (important for `XHReadWrite'); usually 512
device_flags (Bit set -> Capability available):
0 Device is stoppable (XH_TARGET_STOPPABLE (0x00000001L))
1 The medium is removable (XH_TARGET_REMOVABLE (0x00000002L))
2 The eject mechanism can be locked (XH_TARGET_LOCKABLE (0x00000004L))
3 The device can physically eject the medium (XH_TARGET_EJECTABLE (0x00000008L))
29 Eject mechanism has been locked by the driver (XH_TARGET_LOCKED (0x20000000L), from XHDI 1.25 up).
30 Device has been stopped by the driver (XH_TARGET_STOPPED (0x40000000L), from XHDI 1.25 up ).
31 The device is currently reserved (XH_TARGET_RESERVED (0x80000000L)).

All other bits are reserved, drivers should set them to zero.
product_name Product name of the device, similar to the information returned by the SCSI command INQUIRE (max. 33 characters incl. terminating zero). If this information is not available, the driver should return a zero-length string.
Note:
- The caller may pass a zero pointer for block_size, device_flags and product_name.
- For IDE devices, product name information might have to be truncated to fit into 32 characters. (See XHInqTarget2)
Group: XHDI functions
 
See also: Arbitration   _drvbits   Partition types   System variables   XHDI cookie   XHDI terminology
 

H.5.3 XHReserve

Name: »XHReserve« - Reserve a device, or release it again.
 
Opcode: 2
 
Syntax: LONG XHReserve ( UWORD major, UWORD minor, UWORD do_reserve, UWORD key );
 
Description: XHReserve reserves or releases a device. XHLock, XHStop and XHEject only work for reserved devices if the correct key parameter is passed.
 
Example: Take a virtual memory manager which has locked a removable hard disk with the swap partition. You don't want the user to be able to unlock this device with a CPX module!
 
Parameter Meaning
   
do_reserve
(1) Reserve
(0) Release
key Only used for release
Return value: On success, a 16-bit key different from 0 is returned. This key must be specified for all further accesses to the device, as well as for releasing it again.
 
Group: XHDI functions
 
See also: Arbitration   _drvbits   Partition types   System variables   XHDI cookie   XHDI terminology
 

H.5.4 XHLock

Name: »XHLock« - Lock or unlock eject button.
 
Opcode: 3
 
Syntax: LONG XHLock ( UWORD major, UWORD minor, UWORD do_lock, UWORD key );
 
Description: XHLock locks or unlocks the eject mechanism of the device.
 
The driver has to attend to whether this command is passed on to the device or not (in case the medium is not capable of being locked).
 
Parameter Meaning
   
do_lock
(1) Lock
(0) Unlock
key If the device is reserved pass the key, otherwise zero.
Return value: The code returned in case of errors is undefined. But more information is not really required, since one can make a targeted test for this capability beforehand with XHInqTarget.
 
Group: XHDI functions
 
See also: Arbitration   _drvbits   Partition types   System variables   XHDI cookie   XHDI terminology
 

H.5.5 XHStop

Name: »XHStop« - Stop device, or restart it again.
 
Opcode: 4
 
Syntax: LONG XHStop ( UWORD major, UWORD minor, UWORD do_stop, UWORD key );
 
Description: XHStop stops (ships) or starts the device.
 
Parameter Meaning
   
do_stop
(1) Stop
(0) Start
key If the device is reserved pass the key, otherwise zero.

Note: if the drive is accessed, the driver should restart it without an explicit restart call.
 
Return value: The code returned in case of errors is undefined. But more information is not really required, since one can make a targeted test for this capability beforehand with XHInqTarget.
 
Group: XHDI functions
 
See also: Arbitration   _drvbits   Partition types   System variables   XHDI cookie   XHDI terminology
 

H.5.6 XHEject

Name: »XHEject« - Eject medium or reinsert it again.
 
Opcode: 5
 
Syntax: LONG XHEject ( UWORD major, UWORD minor, UWORD do_eject, UWORD key );
 
Description: XHEject ejects or inserts the medium.
 
Parameter Meaning
   
do_eject
(1) Ejects medium
(0) Inserts medium
key If the device is reserved pass the key, otherwise zero.
Return value: The code returned in case of errors is undefined. But more information is not really required, since one can make a targeted test for this capability beforehand with XHInqTarget.
 
Group: XHDI functions
 
See also: Arbitration   _drvbits   Partition types   System variables   XHDI cookie   XHDI terminology
 

H.5.7 XHDrvMap

Name: »XHDrvMap« - Return bit-vector with BIOS XHDI device numbers.
 
Opcode: 6
 
Syntax: ULONG XHDrvMap ( VOID );
 
Description: XHDrvMap returns a bit-mask of BIOS devices supported by the XHDI driver(s) (like the return value from Drvmap).
 
Return value: The return value is the corresponding bit-vector.
 
Group: XHDI functions
 
See also: Arbitration   _drvbits   Partition types   System variables   XHDI cookie   XHDI terminology
 

H.5.8 XHInqDev

Name: »XHInqDev« - Obtain major and minor device number, start sector and Bios parameter block (BPB of a BIOS device.
 
Opcode: 7
 
Syntax: LONG XHInqDev ( UWORD bios_device, UWORD *major, UWORD *minor, ULONG *start_sector, BPB *bpb );
 
Description: XHInqDev returns major device number, minor device number, starting sector and BPB of a given BIOS device. (Note: Getting the BPB this way will not reset the internal media-change state).
 
Note 2: The caller provides a pointer to the BPB structure, which is filled by the driver.
 
Return value: E_OK, EDRNVR (device not responding, e.g. medium not inserted), EDRIVE (wrong BIOS device number) or some other applicable error-code. If the error-code is EDRVNR, major and minor contain the correct values anyway.
 
If start_sector is 0xFFFFFFFF, the device is only temporarily inaccessible (example: you have inserted a cartridge with two partitions, but three drive bits have been reserved for the device).
 
The BPB is invalid if the structure element recsiz is zero.
 
Note: A filesystem is fully described by major and minor device number and the starting block number. This does not mean that it is necessarily a FAT filesystem.
 
The caller may pass a zero pointer for major, minor, start_sector and bpb.
 
Group: XHDI functions
 
See also: Arbitration   _drvbits   Partition types   System variables   XHDI cookie   XHDI terminology
 

H.5.9 XHInqDriver

Name: »XHInqDriver« - Obtain information about the driver.
 
Opcode: 8
 
Syntax: LONG XHInqDriver ( UWORD bios_device, BYTE *name, BYTE *version, BYTE *company, UWORD *ahdi_version, UWORD *maxIPL );
 
Description: XHInqDriver gets information about the driver for the bios_device.
 
Return value:
 
Parameter Meaning
   
name Name of driver (max. 17 characters)
version String with version number (max. 7 characters)
company Name of company/programmer (max. 17 characters).
ahdi_version AHDI version level (as defined in the PUN_INFO structure).
maxIPL: Highest IPL under which the driver can work (usually 5 for drivers which use _hz_200 for timing loops).

Note: The caller may pass a zero pointer for name, version, company, ahdi_version and maxIPL.
 
Group: XHDI functions
 
See also: Arbitration   _drvbits   Partition types   System variables   XHDI cookie   XHDI terminology
 

H.5.10 XHNewCookie

Name: »XHNewCookie« - Install additional XHDI handler.
 
Opcode: 9
 
Syntax: LONG XHNewCookie ( ULONG newcookie );
 
Description: XHNewCookie installs an additional XHDI handler. Advantage: The XHDI cookie continues to point to the same address. Those who want to support this function must do the following:
 
1. If this is the first call of this kind: Proceed subsequently as if the XHDI cookie had already pointed to newcookie at the time of installation.
2. If not: Pass function on to 'next' handler.

Those who would like to perform a multiple installation should proceed as follows:
 
1. Test whether XHNewCookie leads to success.
2. Otherways displace the cookie `by hand'.

Note: This function is optional and may return EINVFN.
 
Return value: XHDI error-codes
 
Group: XHDI functions
 
See also: Arbitration   _drvbits   Partition types   System variables   XHDI cookie   XHDI terminology
 

H.5.11 XHReadWrite

Name: »XHReadWrite« - Read/write physical block numbers.
 
Opcode: 10
 
Syntax: LONG XHReadWrite ( UWORD major, UWORD minor, UWORD rwflag, ULONG recno, UWORD count, VOID *buf );
 
Description: XHReadWrite reads or writes physical blocks, like the BIOS function Rwabs.
 
Parameter Meaning
   
rwflag
Bits 0..2: As defined in the AHDI Release Notes (3.00, April 18, 1990)
Bit 3: (physical mode) is ignored

All other bits are reserved and should be set to zero.
recno Block number
count Block count
buf Pointer to buffer
Return value: XHDI error-codes
 
Group: XHDI functions
 
See also: Arbitration   _drvbits   Partition types   System variables   XHDI cookie   XHDI terminology
 

H.5.12 XHInqTarget2

Name: »XHInqTarget2« - Obtain information about a device.
 
Opcode: 11
 
Syntax: LONG XHInqTarget2 ( UWORD major, UWORD minor, ULONG *block_size, ULONG *device_flags, BYTE *product_name, UWORD stringlen );
 
Description: XHInqTarget2 returns information about the device specified by major and minor (in device_flags: an attribute vector, in product_name: optionally the product descriptin of the device). Reservations made with XHReserve are respected.
 
This function is available only with XHDI version 1.01 and above.
 
Return value:
 
Parameter Meaning
   
block_size Block size for this device (important for XHReadWrite); usually 512.
device_flags (Bit set -> Capability available):
Bit 0: Device is stoppable (XH_TARGET_STOPPABLE)
Bit 1: The medium is removable (XH_TARGET_REMOVABLE)
Bit 2: The eject mechanism can be locked (XH_TARGET_LOCKABLE)
Bit 3: The device can physically eject the medium (XH_TARGET_EJECTABLE)
Bit 29: Eject mechanism has been locked by the driver (XH_TARGET_LOCKED, from XHDI 1.25 up)
Bit 30: Device has been stopped by the driver (XH_TARGET_STOPPED, from XHDI 1.25 up)
Bit 31: The device is currently reserved (XH_TARGET_RESERVED)

All other bits are reserved, drivers should set them to zero.
product_name Product name of the device, similar to the information returned by the SCSI command INQUIRE (maximum stringlen characters incl. terminating zero); if this information is not available, the driver should return a zero-length string
stringlen Length of string buffer passed in product_name
Note: The caller may pass a zero pointer for blocksize, device_flags and product_name.
Group: XHDI functions
 
See also: Arbitration   _drvbits   Partition types   System variables   XHDI cookie   XHDI terminology
 

H.5.13 XHInqDev2

Name: »XHInqDev2« - Inquire major and minor device number, start sector and Bios parameter block (BPB) of a device.
 
Opcode: 12
 
Syntax: LONG XHInqDev2 ( UWORD bios_device, UWORD *major, UWORD *minor, ULONG *start_sector, BPB *bpb, ULONG *blocks, BYTE *partid );
 
Description: XHInqDev2 returns major device number, minor device number, starting sector, BPB, size and partition ID of a given BIOS device (Note: Getting the BPB this way will not reset the internal media-change state).
 
Note 2: The caller provides a pointer to the BPB structure, which is filled by the driver.
 
The function is available only with XHDI version 1.10 and above.
 
Return value: E_OK, EDRNVR (device not responding, e,g. medium not inserted), EDRIVE (wrong BIOS device number) or some other applicable error-code. If the error-code is EDRVNR, major and minor start_sector contain the correct values anyway.
 
If start_sector is 0xFFFFFFFF, the device is only temporarily inaccessible (example: you have inserted a cartridge with two partitions, but three drive bits have been reserved for the device).
 
The BPB is invalid if the structure element recsiz is zero.
 
If the partition ID isn't available (possible reason: no standard Atari root sector or no root sector at all), an empty string is returned.
 
Starting with XHDI 1.20 for MSDOS-compatible media the one byte partition code is returned as:
partid[0] = '\0' (zero byte)
partid[1] = 'D' (for 'DOS')
partid[2] = Partition code
 
Note: A filesystem is fully described by major and minor device number and the starting block number. This does not mean that it is necessarily a FAT filesystem.
 
Note 2: The caller may pass a zero pointer for major, minor, start_sector, bpb, blocks and partid.
 
Group: XHDI functions
 
See also: Arbitration   _drvbits   Partition types   System variables   XHDI cookie   XHDI terminology
 

H.5.14 XHDriverSpecial

Name: »XHDriverSpecial« - Use driver-specific extensions.
 
Opcode: 13
 
Syntax: LONG XHDriverSpecial ( ULONG key1, ULONG key2, UWORD subopcode, VOID *data );
 
Description: This opcode may be used for driver-specific extensions. It's up to the driver how to interpret the arguments in subopcode and data. key1 and key2 are used to specify for which driver the call is intended:
 
key1 should contain four printable ASCII characters, key2 a random ULONG value (example: date of definition in BCD format).
 
Note: OPTIONAL function, may return EINVFN.
 
Return value: XHDI error-codes.
 
Group: XHDI functions
 
See also: Arbitration   _drvbits   Partition types   System variables   XHDI cookie   XHDI terminology
 

H.5.15 XHGetCapacity

Name: »XHGetCapacity« - Obtain number of addressable sectors and their size. ermitteln
 
Opcode: 14
 
Syntax: LONG XHGetCapacity ( UWORD major, UWORD minor, ULONG *blocks, ULONG *blocksize );
 
Description: The XHGetCapacity functions returns the number of adressable sectors in blocks and their size in blocksize. Note that - depending of the device used - this function may need several seconds to complete.
 
Note: This function is optional, may return EINVFN.
 
Return value: XHDI error-codes
 
Group: XHDI functions
 
See also: Arbitration   _drvbits   Partition types   System variables   XHDI cookie   XHDI terminology
 

H.5.16 XHMediumChanged

Name: »XHMediumChanged« - Informs the driver about mediachange
 
Opcode: 15
 
Syntax: LONG XHMediumChanged ( UWORD major, UWORD minor );
 
Description: XHMediumChanged informs the driver that the medium in the given device has been changed. Upon receiving this notice, the driver should do the same things as if the device itself had returned a media-change status.
 
Note: This function is optional and may return EINVFN.
 
Return value: The return value is E_OK if, and only if, this information has been correctly interpreted (this means: all logical drives on the device are either disabled or ready to use).
 
Group: XHDI functions
 
See also: Arbitration   _drvbits   Partition types   System variables   XHDI cookie   XHDI terminology
 

H.5.17 XHMiNTInfo

Name: »XHMiNTInfo« - Set or inquire MiNT-specific information.
 
Opcode: 16
 
Syntax: LONG XHMiNTInfo ( UWORD opcode, VOID *data );
 
Description: XHMiNTInfo is a function for setting/inquiring MiNT-related information.
 
The following opcodes are defined (for unknown opcodes EINVFN is returned; E_OK is returned if, and only if, the call has been executed correctly).
 
XH_MI_SETKERINFO (0) [struct kerinfo *data]
 
Sends (through data) a pointer to the MiNT kernel info structure to the driver. The driver can use it for direct calls of kernel functions.
 
XH_MI_GETKERINFO (1) [struct kerinfo **data]
 
Inquires for a previously set MiNT kernel info pointer. The pointer is returned in the struct kerinfo * pointed to by data. If the adress of the MiNT kernel info structure is unknown, data is filled with a NULL pointer.
 
Note: This function is optional and may return EINVFN.
 
Return value: XHDI error-codes
 
Group: XHDI functions
 
See also: Arbitration   _drvbits   Partition types   System variables   XHDI cookie   XHDI terminology
 

H.5.18 XHDOSLimits

Name: »XHDOSLimits« - Set/get internal limits of DOS.
 
Opcode: 17
 
Syntax: LONG XHDOSLimits ( UWORD which, ULONG limit );
 
Description: The function XHDOSLimits asks the driver for the internal limits of the currently running DOS (or sets the driver's limits). Example: it can be used by a FAT filesystem driver to inform the driver about the change of some of the limits. which describes the type of limit, limit is the new value (with zero meaning that the value shouldn't be changed). The function returns the previous value for the limit.
 
As a required functionality starting with XHDI release 1.30 a driver shall retrieve limit values from previously started XHDI drivers, if these exist. When a limit is changed, this information then shall be passed through to other XHDI drivers.
 

which Meaning
XH_DL_SECSIZ (0) Maximum sector size (BIOS level)
XH_DL_MINFAT (1) Minimum number of FATs
XH_DL_MAXFAT (2) Maximal number of FATs
XH_DL_MINSPC (3) Minimum sectors per cluster
XH_DL_MAXSPC (4) Maximum sectors per cluster
XH_DL_CLUSTS (5) Maximum number of clusters of a 16-bit FAT
XH_DL_MAXSEC (6) Maximum number of sectors
XH_DL_DRIVES (7) Maximum number of BIOS drives supported by the DOS
XH_DL_CLSIZB (8) Maximum cluster size

- With XHDI version 1.30 and above:
 
XH_DL_RDLEN (9) Max. (bpb->rdlen * bpb->recsiz/32)
XH_DL_CLUSTS12 (12) Max. number of clusters of a 12-bit FAT
XH_DL_CLUSTS32 (13) Max. number of clusters of a 32 bit FAT
XH_DL_BFLAGS (14) Supported bits in bpb->bflags

Note: This function is optional, hence a call may be answered with EINVFN.
 
Return value: The function returns the value of the previous limit.
 
Group: XHDI functions
 
See also: Arbitration   _drvbits   Partition types   System variables   XHDI cookie   XHDI terminology
 

H.5.19 XHLastAccess

Name: »XHLastAccess« - Obtain number of milliseconds since the last access.
 
Opcode: 18
 
Syntax: LONG XHLastAccess ( UWORD major, UWORD minor, ULONG *ms );
 
Description: XHLastAccess returns in ms the amount of milliseconds since the last successfull read or write operation on the device.
 
This function is available only with XHDI version 1.25 and above.
 
Return value: XHDI error-codes
 
Group: XHDI functions
 
See also: Arbitration   _drvbits   Partition types   System variables   XHDI cookie   XHDI terminology
 

H.5.20 XHReaccess

Name: »XHReaccess« - Check device for media-change.
 
Opcode: 19
 
Syntax: LONG XHReaccess ( UWORD major, UWORD minor );
 
Description: Calling the XHReaccess function causes the driver to check the device for a possible media-change and to update the partition information if needed (like XHMediumChange, but the driver checks for the media- change status before continuing).
 
This function is available only with XHDI version 1.25 and above.
 
Return value: XHDI error-codes
 
Group: XHDI functions
 
See also: Arbitration   _drvbits   Partition types   System variables   XHDI cookie   XHDI terminology
 

Home XHDI - eXtended HardDisk Interface (Version 1.30)XHDI - eXtended HardDisk Interface (Version 1.30) Recommended partition typesRecommended partition types Type definitionsType definitions