man Pages(7):Device and Network Interfaces

mhd(7I)

NAME

mhd- multihost disk control operations

SYNOPSIS

#include <sys/mhd.h>

DESCRIPTION

These ioctl(2) requests control the access rights of non-shared multihost disks. A non-shared multihost disk is one that supports serialized, mutually exclusive I/O mastery by the connected hosts. This is in contrast to the shared-disk model, in which concurrent access is allowed from more than one host.

A non-shared multihost disk can be in one of two states:

: 1) Exclusive access state, where only one connected host has I/O access, or
: 2) Non-exclusive access state, where all connected hosts have I/O access.

An external hardware reset can cause the disk to enter the non-exclusive access state.

Each multihost disk driver views the machine on which it is running as the ``local host,'' and views all other machines as ``remote hosts.'' For each I/O or ioctl request, the requesting host is the local host.

Each request requires root privilege.

Note that these ioctls were originally designed to work with SCSI disks.

IOCTLS

MHIOCTKOWN: Forcefully acquires exclusive access rights to the multihost disk for the local host. Revokes all access rights to the multihost disk from remote hosts. Causes the disk to enter the exclusive access state. Implementation Note: Reservations (exclusive access rights) broken via random resets should be reinstated by the driver upon their detection, for example, through the use of the automatic probe function described below.
MHIOCRELEASE: Relinquishes exclusive access rights to the multihost disk for the local host. On success, causes the disk to enter the non-exclusive access state.
MHIOCSTATUS: Probes a multihost disk to determine whether the local host has access rights to the disk. Returns 0 if the local host has access to the disk, 1 if it doesn't, and -1 with errno set to EIO if the probe failed for some other reason.
MHIOCENFAILFAST: Enables or disables the failfast option in the multihost disk driver and enables or disables automatic probing of a multihost disk, as described below. The argument is an unsigned integer specifying the number of milliseconds to wait between executions of the automatic probe function. An argument of zero disables the failfast option and disables automatic probing.

Automatic Probe Function

The MHIOCENFAILFAST ioctl sets up a timeout in the driver to continuously schedule automatic probes of a disk. The automatic probe function works by scheduling the driver to execute the MHIOCSTATUS operation every n milliseconds, rounded up to the next integral multiple of the system clock's resolution.

If access rights to the multihost disk were expected to be held by the local host, but the local host no longer has access rights, then the driver immediately panics the machine in order to comply with the failfast model.

Implementation Note: If the driver makes this discovery outside the timeout function, especially during a read or write operation, it is imperative that it panic the system then as well.

Failfast

A technique generally used in fault-tolerant systems to diagnose a malfunctioning component is to externally detect a deviation from that component's expected behavior. The recovery model is fault containment through failfast: the halting, isolation, and removal from service of the bad component before its potentially incorrect operation can spread the damage any further.

RETURN VALUES

Each request returns -1 on failure and sets errno to indicate the error.

EACCES: Access rights were denied.

EIO: The multihost disk or controller was unable to successfully complete the requested operation.

USAGE

#include <sys/mhd.h>
ioctl(fd, MHIOCTKOWN, (struct mhioctkown *)tkown);
ioctl(fd, MHIOCRELEASE);
ioctl(fd, MHIOCSTATUS);
ioctl(fd, MHIOCENFAILFAST, (unsigned int)millisecs);

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWhea