XHDI - eXtended HardDisk Interface (Version 1.30)

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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

XHDI - eXtended HardDisk Interface (Version 1.30)

Recommended partition types

Type definitions