Managing Shared Disks

fence subroutine

Purpose

fence - Allows you to request and change the virtual shared disk fence map. The fence map controls whether virtual shared disks can send or satisfy requests from virtual shared disks at remote nodes.

Syntax

#include <vsd_ioctl.h>
int ioctl(FileDescriptor, Command, Argument)
int FileDescriptor, Command;
void *Argument;

Parameters

FileDescriptor

Specifies the open file descriptor for which the control operation is to be performed.

Command

Specifies the control function to be performed. The value of this parameter is always GIOCFENCE.

Argument

Specifies a pointer to a vsd_fence_map structure.

The flags field of the vsd_fence_map structure determines the type of operation that is performed. The flags could be set with one or more options using the OR operator. These options are as follows:

VSD_FENCE_COMPARE

Indicates that all the bits in the node_FenceMask bitmap represent the current status for a given VSD minor, and the node_FenceMask bitmap is the new status to be applied by this request. The request will succeed only if the current status depicted in the node_FenceMask is valid.

VSD_FENCE_FORCE

If this option is specified, a node can unfence itself.

VSD_FENCE_GET

Denotes a query request.

VSD_FENCE_SET

Denotes a fence request.

VSD_FENCE_SWAP

Indicates that the node_FenceMask bitmap denotes which bits in the node_FenceMap the request applies to. Only nodes whose bit is turned on in the node_FenceMask bitmap may change status.

Description

The fence-map is an array with the following definition:

typedef struct
unsigned int   nvsds; /* number of elements in the vsd_Fence
                         array */
ulong          flags; /* specifies the type of request */
vsd_Fence_t    *Map;  /* array of vsd_Fence structures */
} vsd_FenceMap_t;

nvsds represents the number of elements in the vsd_Fence array. The flags specify the type of request. The map is an array of the following structure:

typedef struct
{
    unsigned int      vsd_minor;       /* The bitmap is associated
                                          with this minor */
    vsd_Fence_Bitmap  node_FenceMap;   /* Nodes status - fenced or
                                          unfenced */
    vsd_Fence_Bitmap  node_FenceMask;  /* Determine how node_FenceMap
                                          is used */
} vsd_Fence_t;

The vsd_minor represents the virtual shared disk device's minor number. The node_FenceMap bitmap denotes which nodes are fenced (bit turned on) or unfenced (bit turned off) from the virtual shared disk. You could use the MAP_SET and MAP_CLR macros defined in vsd_ioctl.h to turn a given bit in the map on or off. The node_FenceMask is used to interpret the node_FenceMap bitmap, depending on the flags field.

You can submit a fence map that changes the current virtual shared disk map (maintained by the IBM Virtual Shared Disk subsystem) according to the flags set in the vsd_fence_map structure. The request is considered a delta to the current virtual shared disk map. You can also utilize this ioctl to query the current virtual shared disk map.

Return values

If the request succeeds, the ioctl returns 0. In the case of an error, a value of -1 is returned with the global variable errno set to identify the error.

Error values

The fence ioctl subroutine can return the following error codes:

EACCES

Indicates that an unfence was requested from a fenced node without the VSD_FENCE_FORCE option.

EINVAL

Indicates an invalid request (ambiguous flags or unidentified virtual shared disks).

ENOCONNECT

Indicates that either the primary or the secondary node for a virtual shared disk to be fenced is not a member of the virtual shared disk group, or the virtual shared disk in question is in the stopped state.

ENOMEM

Indicates, in the case of a query request, that the current virtual shared disk fence map is larger than the one specified in the query request. The query fails and the nvsds field in the request is changed to reflect the current size of the fence map.

ENOTREADY

Indicates that the group is not active or IBM Recoverable Virtual Shared Disk is not available.

ENXIO

Indicates that the IBM Virtual Shared Disk driver is being unloaded.

Examples

The following is an example of how to fence a virtual shared disk with a minor number of 7 from node 4 and 5, and to unfence a virtual shared disk with a minor number of 5 from node 1:

int fd;
vsd_FenceMap_t FenceMap;
 
/* two VSDs to work with */
FenceMap.Map=(vsd_Fence *) malloc (2*sizeof(vsd_Fence));
FenceMap.nvsds = 2;
 
/* Clear the Map and Mask*/
MAP_ZERO(FenceMap.Map[0].node_FenceMap);
MAP_ZERO(FenceMap.Map[0].node_FenceMask);
MAP_ZERO(FenceMap.Map[1].node_FenceMap);
MAP_ZERO(FenceMap.Map[1].node_FenceMask);
FenceMap.flags = VSD_FENCE_SET | VSD_FENCE_FORCE | VSD_FENCE_SWAP;
 
/* fence nodes 4,5 from minor 7 */
FenceMap.Map[0].vsd_minor = 7;
MAP_SET(4, FenceMap.Map[0]node_FenceMap);
MAP_SET(4, FenceMap.Map[0].node_FenceMask);
MAP_SET(5, FenceMap.Map[0].node_FenceMap);
MAP_SET(5, FenceMap.Map[0].node_FenceMask)
 
/* Unfence node 1 from minor 5*/
FenceMap.Map[1].vsd_minor = 5;
MAP_SET(1, FenceMap.Map[1].node_FenceMask);
 
/* Issue the fence request */
ioctl(fd,GIOCFENCE,&FenceMap);