I am sponsoring the following fasttrack for myself. Requested binding is
minor. Timeout is set for 9/02.
- John
Template Version: @(#)sac_nextcase 1.68 02/23/09 SMI
This information is Copyright 2009 Sun Microsystems
1. Introduction
1.1. Project/Component Working Name:
COMSTAR ALUA active/standby support
1.2. Name of Document Author/Supplier:
Author: John Forte
1.3 Date of This Document:
26 August, 2009
4. Technical Description
COMSTAR (PSARC 2007/523 [1]) supports the SCSI standard [2] for Asymmetric
Logical Unit Access (ALUA) but only supports the access state of
Active/Optimized. This set of interfaces introduces support for a logical unit
access state of Standby on a peer node. This support is provided via the
existing libstmf(3LIB) introduced in PSARC 2007/253 and is targeted towards
developers of clustered storage systems in 2 node configurations. Use of these
interfaces require a peer-to-peer communication channel be established between
the two participating nodes in the COMSTAR (STMF) ALUA configuration.
4.1 Interfaces
Minor binding.
-------------+-----------------------+-------------------------
Interface Classification Comments
-------------+-----------------------+-------------------------
libstmf | Committed | PSARC 2007/523
4.2 stmfSetAluaState
NAME
stmfSetAluaState
SYNOPSIS
cc [ flag... ] file... -lstmf [ library... ]
#include <libstmf.h>
int stmfSetAluaState(boolean_t enabled, uint8_t node)
PARAMETERS
enabled B_TRUE when enabling ALUA mode
B_FALSE when disabling ALUA mode
node Must be the value 0 or 1
DESCRIPTION
The stmfSetAluaState() function sets the Asymmetric Logical Unit Access
State (ALUA) mode for STMF. When enabled is set to B_FALSE, node is ignored,
otherwise, node must be set to 0 or 1. The node setting must be different
for each node in a paired config. This should be called only after the
STMF proxy door service has been initialized(See stmfInitProxyDoor(3STMF)).
When the ALUA state is enabled, all STMF logical units will be
registered on the peer node as standby logical units. The standby logical
units can then be exported to any SCSI initiator using the existing
mechanisms in STMF, stmfAddViewEntry(3STMF) or the add-view
subcommand of stmfadm(1M). Note: If ALUA mode is already enabled,
it is valid to call this interface again with enabled set to B_TRUE.
This action would result in a re-initialization of the ALUA mode. This
can be used during recovery of a failed peer node.
RETURN VALUES
The following values are returned:
STMF_ERROR_INVALID_ARG Either enabled or node was incorrectly set.
STMF_STATUS_SUCCESS The API call was successful
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Committed |
|_____________________________|_____________________________|
| MT-Level | Safe |
|_____________________________|_____________________________|
4.3 stmfGetAluaState
NAME
stmfGetAluaState
SYNOPSIS
cc [ flag... ] file... -lstmf [ library... ]
#include <libstmf.h>
int stmfGetAluaState(boolean_t *enabled, uint8_t *node)
PARAMETERS
enabled set to B_TRUE or B_FALSE on success
node set to 0 or 1 on success
DESCRIPTION
The stmfGetAluaState() function returns the Asymmetric Logical Unit Access
State (ALUA) mode for STMF along with the node setting.
RETURN VALUES
The following values are returned:
STMF_ERROR_INVALID_ARG Either enabled or node was NULL.
STMF_STATUS_SUCCESS The API call was successful
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Committed |
|_____________________________|_____________________________|
| MT-Level | Safe |
|_____________________________|_____________________________|
4.4 stmfLuStandby
NAME
stmfLuStandby
SYNOPSIS
cc [ flag... ] file... -lstmf [ library... ]
#include <libstmf.h>
int stmfLuStandby(stmfGuid *luGuid)
PARAMETERS
luGuid a pointer to an stmfGuid structure containing the guid
of the logical unit to set to standby
DESCRIPTION
The stmfLuStandby() function sets the access state of a logical unit to
standby mode. When successfully set, a standby logical unit switches its
asymmetric logical unit access state to a one of "Transition to
Standby" (see stmfGetLuProp(3STMF). Once moved to this state, the backing
store for the logical unit will be released by the logical unit provider
(sbd for disk devices). In order to move a logical unit out of "Standby"
or the "Transition to Standby" state, stmfImportLu(3STMF) or the import-lu
subcommand of stmfadm(1M) must be executed on the logical unit. On a
successful logical unit import, the access state of the logical unit will
move to Active in addition to sending a message to its peer that will
complete the peer's transition to Standby. The current access state for
the logical unit can be retrieved using stmfGetLuProp(3STMF) where the
property type is STMF_LU_PROP_ACCESS_STATE.
RETURN VALUES
The following values are returned:
STMF_ERROR_NOT_FOUND The guid does not exist
STMF_STATUS_SUCCESS The API call was successful
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Committed |
|_____________________________|_____________________________|
| MT-Level | Safe |
|_____________________________|_____________________________|
4.5 stmfInitProxyDoor
NAME
stmfInitProxyDoor
SYNOPSIS
cc [ flag... ] file... -lstmf [ library... ]
#include <libstmf.h>
int stmfInitProxyDoor(int *hdl, int fd);
PARAMETERS
hdl a pointer to an int. This will contain the handle for
the proxy door to be used in calls to
stmfPostProxyMsg(3STMF) and stmfDestroyProxyDoor(3STMF)
fd The door file descriptor for the established door server
DESCRIPTION
The stmfInitProxyDoor() function establishes the door server with the
STMF proxy service. The STMF proxy service is responsible for sending
SCSI commands to the peer node on behalf of a logical unit in the Standby
asymmetric logical unit access (ALUA) state. stmfInitProxyDoor(3STMF)
should be called once a peer-to-peer communication channel between the two
participating ALUA nodes has been established by the caller.
Door server interface:
The door_call from the STMF proxy service to the door server will fill in
the door_arg_t structure as follows:
door_arg_t arg;
uint32_t result;
arg.data_ptr = buf;
arg.data_size = size;
arg.desc_ptr = NULL;
arg.desc_num = 0;
arg.rbuf = (char *)&result;
arg.rsize = sizeof (result);
The tuple <data_ptr, data_size> is expected to arrive at the
peer node STMF proxy service via stmfPostProxyMsg(3STMF).
The door server is expected to complete the door call with these
arguments to door_return:
uinit32_t result;
(void) door_return((char *)&result, sizeof(result), NULL, 0);
where result is of type uint32_t and set to 0 on success, non-zero
on failure.
Non-zero values are logged as errors without further action. No file
descriptors will be exchanged by the door call or return.
RETURN VALUES
The following values are returned:
STMF_ERROR_DOOR_INSTALLED A previous door has already been
established.
STMF_STATUS_SUCCESS The API call was successful
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Committed |
|_____________________________|_____________________________|
| MT-Level | Safe |
|_____________________________|_____________________________|
4.6 stmfDestroyProxyDoor
NAME
stmfDestroyProxyDoor
SYNOPSIS
cc [ flag... ] file... -lstmf [ library... ]
#include <libstmf.h>
void stmfDestroyProxyDoor(int hdl);
PARAMETERS
hdl hdl returned from a previous call to
stmfInitProxyDoor(3STMF)
DESCRIPTION
The stmfDestroyProxyDoor() function closes the door interface
established in the call to stmfInitProxyDoor().
RETURN VALUES
None
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Committed |
|_____________________________|_____________________________|
| MT-Level | Safe |
|_____________________________|_____________________________|
4.7 stmfPostProxyMsg
NAME
stmfPostProxyMsg
SYNOPSIS
cc [ flag... ] file... -lstmf [ library... ]
#include <libstmf.h>
int stmfPostProxyMsg(int hdl, void *buf, uint32_t buflen)
PARAMETERS
hdl Returned in a previous successful call to
stmfInitProxyDoor(3STMF)
buf Pointer to buffer to received from peer node
buflen length of buf
DESCRIPTION
The stmfPostProxyMsg() function passes down to the STMF proxy service
the message received from the peer node's STMF proxy service door upcall.
RETURN VALUES
The following values are returned:
STMF_ERROR_INVALID_ARG hdl is not valid or buf is NULL
STMF_POST_MSG_FAILED Failed to post message
STMF_STATUS_SUCCESS The API call was successful
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Committed |
|_____________________________|_____________________________|
| MT-Level | Safe |
|_____________________________|_____________________________|
4.8 Changes to stmfGetLuProp(3STMF) manpage
decimal representation (that is, no leading "0x"). The prop
argument can be one of the following values:
+ STMF_LU_PROP_ACCESS_STATE
+
+ Asymmetric access state for the logical unit.
+ Set to one of:
+
+ "0" is Active
+ "1" is Transition to Active
+ "2" is Standby
+ "3" is Transition to Standby
+
STMF_LU_PROP_ALIAS
Up to 255 characters representing a user defined name
4.9 References
[1] COMSTAR: Common Multiprotocol SCSI Target
http://sac.sfbay/PSARC/2007/523
[2] SCSI Primary Commands - 3 (SPC-3) revision 23
http://www.t10.org/cgi-bin/ac.pl?t=f&f=spc3r23.pdf
6. Resources and Schedule
6.4. Steering Committee requested information
6.4.1. Consolidation C-team Name:
ON
6.5. ARC review type: FastTrack
6.6. ARC Exposure: open
