+1 -- mark
John Forte wrote: > 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 > > _______________________________________________ > opensolaris-arc mailing list > opensolaris-arc at opensolaris.org > -- <http://www.sun.com> * Mark A. Carlson * Sr. Architect *Systems Group* Phone x69559 / 303-223-6139 Email Mark.Carlson at Sun.COM
