John Forte wrote: > Don Cragun wrote: >> On Wed, 26 Aug 2009 16:21:02 -0700 (PDT), John Forte wrote: >> ... ... ... >>> 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 >> >> I'm having trouble understanding what is going on here. Should "mode" >> in the above two lines be "node"? > No, but the word "mode" could easily be replaced by "state" and perhaps > should.
Ok. The way it is seems ambiguous to me. It seems like you're trying to set the state of the specified "node" to be enabled or disabled depending on the value of "enabled" and if the value of "enabled" is B_TRUE, you're also enabling ALUA. >> >>> >>> 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. >> >> According to the Note above, it is not an error to call >> stmfSetAluaState(B_TRUE, node) to reinitialize node if had it previously >> been enabled. > Correct. OK. Good. >> >>> >>> 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 >> >> According to the above two lines, stmfSetAluaState() is supposed to >> return STMF_ERROR_INVALID_ARG (because it was enabled) and >> STMF_STATUS_SUCCESS (if it successfully reinitializes node)??? > I don't think it says that. STMF_ERROR_INVALID_ARG would be returned if > node was neither 0 or 1. OK. I see what you're trying to do now. By not having italics to indicate that "enabled" was the function call argument as opposed to the state of the node, I misread what the error was. If you changed to argument name from "enabled" to "enable" it might be less confusing. On most systems, an argument of type boolean_t can only assume two values; false (== 0) and true (!= 0) and in that case it is hard to get an incorrectly set boolean value. If you're really checking for B_FALSE and B_TRUE instead of 0 and non-zero, it is OK. > > Perhaps it would be clearer if it was: > > RETURN VALUES > > The following values are returned: > > STMF_ERROR_INVALID_ARG Either "enabled" or "node" was > incorrectly set. > ? > > >> >> ... ... ... >>> >>> 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 >> >> So, if I call stmfSetAluaState(B_TRUE, 0) and stmfSetAluaState(B_TRUE, >> 1) and then call stmfGetAluaState(&state, &node) what is it supposed to >> do? > Return the last node id set, which in this case would be 1 along with a > state of B_TRUE. I understand what you're doing now, but I still find "disabled" in this presentation mode ambiguous. I read it as "Either the node (or the ALUA) is enabled, or the value of node is a null pointer." Obviously, if either argument is a pointer to any correctly aligned valid address this will write over whatever is there. Is there any error reserved for a pointer to unallocated space (other than a null pointer), or is the expected result in that case memory fault - core dumped? - Don >> On which node is it going to report? Since both nodes have been >> enabled, it says that it is going to return STMF_ERROR_INVALID_ARG. > STMF_ERROR_INVALID_ARG is only returned when the arguments are invalid. > As long as "enabled" is B_TRUE or B_FALSE and "node" is either 0 or 1, > that error would not be returned. > > To make this clear, "node" is just an identifier for the stmf instance > on which the set ALUA state is executed. It isn't a target for the > execution of the set ALUA state, i.e. the set is not setting the state > for node 0 or node 1, it's setting the state AND setting the node > identifier to 0 or 1. >> But if it successfully sets state and node, it also says it will return >> STMF_STATUS_SUCCESS??? > Yes, it's just another state change. > > - John
