1mhd(7i) Ioctl Requests mhd(7i)
2
6 mhd - multihost disk control operations
7
9 #include <sys/mhd.h>
10
13 The mhd ioctl(2) control access rights of a multihost disk, using disk
14 reservations on the disk device.
15 The stability level of this interface (see attributes(5)) is evolving.
18 As a result, the interface is subject to change and you should limit
19 your use of it.
20 The mhd ioctls fall into two major categories: (1) ioctls for non-
23 shared multihost disks and (2) ioctls for shared multihost disks.
24 One ioctl, MHIOCENFAILFAST, is applicable to both non-shared and shared
27 multihost disks. It is described after the first two categories.
28 All the ioctls require root privilege.
31 For all of the ioctls, the caller should obtain the file descriptor for
34 the device by calling open(2) with the O_NDELAY flag; without the
35 O_NDELAY flag, the open may fail due to another host already having a
36 conflicting reservation on the device. Some of the ioctls below permit
37 the caller to forcibly clear a conflicting reservation held by another
38 host, however, in order to call the ioctl, the caller must first obtain
39 the open file descriptor.
40 Non-shared multihost disks
42 Non-shared multihost disks ioctls consist of MHIOCTKOWN, MHIOCRELEASE,
43 HIOCSTATUS, and MHIOCQRESERVE. These ioctl requests control the access
44 rights of non-shared multihost disks. A non-shared multihost disk is
45 one that supports serialized, mutually exclusive I/O mastery by the
46 connected hosts. This is in contrast to the shared-disk model, in which
47 concurrent access is allowed from more than one host (see below).
48 A non-shared multihost disk can be in one of two states:
51 o Exclusive access state, where only one connected host has
53 I/O access
54 o Non-exclusive access state, where all connected hosts have
56 I/O access. An external hardware reset can cause the disk to
57 enter the non-exclusive access state.
58 Each multihost disk driver views the machine on which it's running as
61 the "local host"; each views all other machines as "remote hosts". For
62 each I/O or ioctl request, the requesting host is the local host.
63 Note that the non-shared ioctls are designed to work with SCSI-2 disks.
66 The SCSI-2 RESERVE/RELEASE command set is the underlying hardware
67 facility in the device that supports the non-shared ioctls.
68 The function prototypes for the non-shared ioctls are:
71 ioctl(fd, MHIOCTKOWN);
73 ioctl(fd, MHIOCRELEASE);
74 ioctl(fd, MHIOCSTATUS);
75 ioctl(fd, MHIOCQRESERVE);
76 MHIOCTKOWN Forcefully acquires exclusive access rights to the
79 multihost disk for the local host. Revokes all access
80 rights to the multihost disk from remote hosts.
81 Causes the disk to enter the exclusive access state.
82 Implementation Note: Reservations (exclusive access
84 rights) broken via random resets should be reinstated
85 by the driver upon their detection, for example, in
86 the automatic probe function described below.
87 MHIOCRELEASE Relinquishes exclusive access rights to the multihost
90 disk for the local host. On success, causes the disk
91 to enter the non- exclusive access state.
92 MHIOCSTATUS Probes a multihost disk to determine whether the
95 local host has access rights to the disk. Returns 0
96 if the local host has access to the disk, 1 if it
97 doesn't, and -1 with errno set to EIO if the probe
98 failed for some other reason.
99 MHIOCQRESERVE Issues, simply and only, a SCSI-2 Reserve command. If
102 the attempt to reserve fails due to the SCSI error
103 Reservation Conflict (which implies that some other
104 host has the device reserved), then the ioctl will
105 return -1 with errno set to EACCES. The MHIOCQRE‐
106 SERVE ioctl does NOT issue a bus device reset or bus
107 reset prior to attempting the SCSI-2 reserve command.
108 It also does not take care of re-instating reserva‐
109 tions that disappear due to bus resets or bus device
110 resets; if that behavior is desired, then the caller
111 can call MHIOCTKOWN after the MHIOCQRESERVE has
112 returned success. If the device does not support the
113 SCSI-2 Reserve command, then the ioctl returns -1
114 with errno set to ENOTSUP. The MHIOCQRESERVE ioctl
115 is intended to be used by high-availability or clus‐
116 tering software for a "quorum" disk, hence, the "Q"
117 in the name of the ioctl.
118 Shared Multihost Disks
121 Shared multihost disks ioctls control access to shared multihost disks.
122 The ioctls are merely a veneer on the SCSI-3 Persistent Reservation
123 facility. Therefore, the underlying semantic model is not described in
124 detail here, see instead the SCSI-3 standard. The SCSI-3 Persistent
125 Reservations support the concept of a group of hosts all sharing access
126 to a disk.
127 The function prototypes and descriptions for the shared multihost
130 ioctls are as follows:
131 ioctl(fd, MHIOCGRP_INKEYS, (mhioc_inkeys_t) *k);
133 Issues the SCSI-3 command Persistent Reserve In Read Keys to the
135 device. On input, the field k->li should be initialized by the
136 caller with k->li.listsize reflecting how big of an array the call‐
137 er has allocated for the k->li.list field and with k->li.listlen ==
138 0. On return, the field k->li.listlen is updated to indicate the
139 number of reservation keys the device currently has: if this value
140 is larger than k->li.listsize then that indicates that the caller
141 should have passed a bigger k->li.list array with a bigger
142 k->li.listsize. The number of array elements actually written by
143 the callee into k->li.list is the minimum of k->li.listlen and
144 k->li.listsize. The field k->generation is updated with the genera‐
145 tion information returned by the SCSI-3 Read Keys query. If the
146 device does not support SCSI-3 Persistent Reservations, then this
147 ioctl returns -1 with errno set to ENOTSUP.
148 ioctl(fd, MHIOCGRP_INRESV, (mhioc_inresvs_t) *r);
151 Issues the SCSI-3 command Persistent Reserve In Read Reservations
153 to the device. Remarks similar to MHIOCGRP_INKEYS apply to the
154 array manipulation. If the device does not support SCSI-3 Persis‐
155 tent Reservations, then this ioctl returns -1 with errno set to
156 ENOTSUP.
157 ioctl(fd, MHIOCGRP_REGISTER, (mhioc_register_t) *r);
160 Issues the SCSI-3 command Persistent Reserve Out Register. The
162 fields of structure r are all inputs; none of the fields are modi‐
163 fied by the ioctl. The field r->aptpl should be set to true to
164 specify that registrations and reservations should persist across
165 device power failures, or to false to specify that registrations
166 and reservations should be cleared upon device power failure; true
167 is the recommended setting. The field r->oldkey is the key that the
168 caller believes the device may already have for this host initia‐
169 tor; if the caller believes that that this host initiator is not
170 already registered with this device, it should pass the special key
171 of all zeros. To achieve the effect of unregistering with the
172 device, the caller should pass its current key for the r->oldkey
173 field and an r->newkey field containing the special key of all
174 zeros. If the device returns the SCSI error code Reservation Con‐
175 flict, this ioctl returns -1 with errno set to EACCES.
176 ioctl(fd, MHIOCGRP_RESERVE, (mhioc_resv_desc_t) *r);
179 Issues the SCSI-3 command Persistent Reserve Out Reserve. The
181 fields of structure r are all inputs; none of the fields are modi‐
182 fied by the ioctl. If the device returns the SCSI error code Reser‐
183 vation Conflict, this ioctl returns -1 with errno set to EACCES.
184 ioctl(fd, MHIOCGRP_PREEMPTANDABORT, (mhioc_preemptandabort_t) *r);
187 Issues the SCSI-3 command Persistent Reserve Out Preempt-And-Abort.
189 The fields of structure r are all inputs; none of the fields are
190 modified by the ioctl. The key of the victim host is specified by
191 the field r->victim_key. The field r->resvdesc supplies the pre‐
192 empter's key and the reservation that it is requesting as part of
193 the SCSI-3 Preempt-And-Abort command. If the device returns the
194 SCSI error code Reservation Conflict, this ioctl returns -1 with
195 errno set to EACCES.
196 ioctl(fd, MHIOCGRP_PREEMPT, (mhioc_preemptandabort_t) *r);
199 Similar to MHIOCGRP_PREEMPTANDABORT, but instead issues the SCSI-3
201 command Persistent Reserve Out Preempt. (Note: This command is not
202 implemented).
203 ioctl(fd, MHIOCGRP_CLEAR, (mhioc_resv_key_t) *r);
206 Issues the SCSI-3 command Persistent Reserve Out Clear. The input
208 parameter r is the reservation key of the caller, which should have
209 been already registered with the device, by an earlier call to
210 MHIOCGRP_REGISTER. (Note: This command is not implemented).
211 For each device, the non-shared ioctls should not be mixed with the
215 Persistent Reserve Out shared ioctls, and vice-versa, otherwise, the
216 underlying device is likely to return errors, because SCSI does not
217 permit SCSI-2 reservations to be mixed with SCSI-3 reservations on a
218 single device. It is, however, legitimate to call the Persistent
219 Reserve In ioctls, because these are query only. Issuing the MHIOC‐
220 GRP_INKEYS ioctl is the recommended way for a caller to determine if
221 the device supports SCSI-3 Persistent Reservations (the ioctl will
222 return -1 with errno set to ENOTSUP if the device does not).
223 MHIOCENFAILFAST Ioctl
225 The MHIOCENFAILFAST ioctl is applicable for both non-shared and shared
226 disks, and may be used with either the non-shared or shared ioctls.
227 ioctl(fd, MHIOENFAILFAST, (unsigned int *) millisecs);
229 Enables or disables the failfast option in the multihost disk
231 driver and enables or disables automatic probing of a multihost
232 disk, described below. The argument is an unsigned integer speci‐
233 fying the number of milliseconds to wait between executions of the
234 automatic probe function. An argument of zero disables the fail‐
235 fast option and disables automatic probing. If the MHIOCENFAILFAST
236 ioctl is never called, the effect is defined to be that both the
237 failfast option and automatic probing are disabled.
238 Automatic Probing
241 The MHIOCENFAILFAST ioctl sets up a timeout in the driver to periodi‐
242 cally schedule automatic probes of the disk. The automatic probe
243 function works in this manner: The driver is scheduled to probe the
244 multihost disk every n milliseconds, rounded up to the next integral
245 multiple of the system clock's resolution. If
246 1. the local host no longer has access rights to the multi‐
248 host disk, and
249 2. access rights were expected to be held by the local host,
251 the driver immediately panics the machine to comply with the failfast
254 model.
255 If the driver makes this discovery outside the timeout function, espe‐
258 cially during a read or write operation, it is imperative that it panic
259 the system then as well.
260
262 Each request returns -1 on failure and sets errno to indicate the
263 error.
264 EPERM Caller is not root.
266 EACCES Access rights were denied.
269 EIO The multihost disk or controller was unable to success‐
272 fully complete the requested operation.
273 EOPNOTSUP The multihost disk does not support the operation. For
276 example, it does not support the SCSI-2 Reserve/Release
277 command set, or the SCSI-3 Persistent Reservation command
278 set.
279
282 See attributes(5) for a description of the following attributes:
283 ┌───────────────────────────────────────────────────────────┐
288 │ATTRIBUTE TYPE ATTRIBUTE VALUE │
289 │Availability SUNWhea │
290 │Stability Evolving │
291 └───────────────────────────────────────────────────────────┘
292
294 ioctl(2), open(2), attributes(5), open(2)
295SunOS 5.11 1 Sep 2005 mhd(7i)