From John.Forte@sun.com Tue Apr 21 11:34:09 2009 Received: from sunmail4.singapore.sun.com (sunmail4.Singapore.Sun.COM [129.158.71.19]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n3LIY7gH008895 for ; Tue, 21 Apr 2009 11:34:08 -0700 (PDT) Received: from nwk-avmta-2.sfbay.sun.com (nwk-avmta-2.SFBay.Sun.COM [129.145.155.6]) by sunmail4.singapore.sun.com (8.13.4+Sun/8.13.3/ENSMAIL,v2.2) with ESMTP id n3LIY1lN006286 for <@sunmail2sca.sfbay.sun.com:PSARC-ext@sun.com>; Wed, 22 Apr 2009 02:34:07 +0800 (SGT) Received: from pmxchannel-daemon.nwk-avmta-2.sfbay.sun.com by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KIG00105RKUJW00@nwk-avmta-2.sfbay.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@Sun.Com); Tue, 21 Apr 2009 11:34:06 -0700 (PDT) Received: from brmea-mail-2.sun.com ([192.18.98.43]) by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KIG00IMORKUSX80@nwk-avmta-2.sfbay.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@Sun.Com); Tue, 21 Apr 2009 11:34:06 -0700 (PDT) Received: from fe-amer-10.sun.com ([192.18.109.80]) by brmea-mail-2.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n3LIY6dF024339 for ; Tue, 21 Apr 2009 18:34:06 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7.0-5.01 64bit (built Feb 19 2009)) id <0KIG00L00PB01700@mail-amer.sun.com>; Tue, 21 Apr 2009 12:34:06 -0600 (MDT) Received: from [129.146.56.52] ([unknown] [129.146.56.52]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7.0-5.01 64bit (built Feb 19 2009)) with ESMTPSA id <0KIG00M3IRKGS450@mail-amer.sun.com>; Tue, 21 Apr 2009 12:33:53 -0600 (MDT) Date: Tue, 21 Apr 2009 11:28:35 -0700 From: John Forte Subject: libstmf/stmfadm enhancements for COMSTAR [PSARC/2009/251 FastTrack timeout 04/29/2009] Sender: John.Forte@sun.com To: PSARC-ext@sun.com Message-id: <49EE1053.6070102@sun.com> MIME-version: 1.0 Content-type: text/plain; format=flowed; charset=ISO-8859-1 Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 User-Agent: Thunderbird 2.0.0.17 (X11/20081014) Status: RO Content-Length: 28591 I am sponsoring the following fasttrack for myself. Requested binding is minor. Timeout is set for 4/29. - 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: libstmf/stmfadm enhancements for COMSTAR 1.2. Name of Document Author/Supplier: Author: John Forte 1.3 Date of This Document: 21 April, 2009 4. Technical Description libstmf/stmfadm enhancements for COMSTAR 4.1 Description libstmf(3LIB) was introduced in PSARC 2007/523 but lacked any C interfaces for managing create/delete/modify of sbd (PSARC 2008/235) logical units. sbdadm(1M) is currently the only interface available for managing logical units. This case introduces new library interfaces for managing logical units and introduces new subcommands to stmfadm(1M) to provide CLI support. The new stmfadm(1M) subcommands will be the preferred approach and this case will make sbdadm's stability classification "obsolete committed". This does not introduce any backward incompatibility with the existing sbdadm functionality. All existing sbdadm functionality will be carried forward to stmfadm(1M). This case also introduces two library interfaces for managing configuration persistence allowing a developer to provide their own means of persisting configuration data for the stmf service. 4.2 Interfaces Minor binding. -------------+-----------------------+------------------------- Interface Classification Comments -------------+-----------------------+------------------------- libstmf | Committed | PSARC 2007/523 | | stmfadm | Committed | PSARC 2007/523 output of | Not an interface | stmfadm | | | | sbdadm | Obsolete Committed | PSARC 2008/235 4.2.1 stmfadm subcommands create-lu [-p, --lu-prop logical-unit-property=val -s, --size size] lu-file delete-lu lu-name... import-lu lu-file modify-lu [-p, --lu-prop logical-unit-property=val -s, --size size, -f, --file] lu-name|lu-file The command man pages are in Appendix A 4.2.2 sbdadm man page change: _____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Availability | SUNWstmfu | |_____________________________|_____________________________| ! | Interface Stability | Obsolete Committed | |_____________________________|_____________________________| + NOTES + This command is obsolete and may be removed in a future release. + Please use stmfadm(1M) for equivalent functionality. 4.2.3 Library interfaces Note: All library interfaces are committed as per libstmf's current interface classification. int stmfCreateLu(luResource hdl, stmfGuid *luGuid); int stmfCreateLuResource(uint16_t type, luResource *hdl); int stmfDeleteLu(stmfGuid *luGuid); int stmfFreeLuResource(luResource hdl); int stmfGetLuProp(luResource hdl, uint32_t prop, char *propVal, size_t *propLen); int stmfGetLuResource(stmfGuid *luGuid, luResource *hdl) int stmfGetPersistMethod(uint8_t *persistType, boolean_t serviceState); int stmfModifyLu(stmfGuid *luGuid, uint32_t prop, const char *propVal); int stmfSetLuProp(luResource hdl, uint32_t prop, const char *propVal); int stmfSetPersistMethod(uint8_t persistType, boolean_t serviceSet); The interface man pages are in Appendix B. 6. Resources and Schedule 6.4. Steering Committee requested information 6.4.1. Consolidation C-team Name: OS/Net 6.5. ARC review type: FastTrack 6.6. ARC Exposure: open Appendix A ========== create-lu [-p, --lu-prop logical-unit-property=val -s, --size size] lu-file Create a logical unit that can be registered with STMF. For the -p option, logical-unit-property can be one of the following properties: alias Up to 255 characters representing a user defined name for the device Default: set to file name of backing store blk Block size. Specifies the block size for the device. Default: 512 guid 32 hexadecimal ascii characters representing a valid NAA Registered Extended Identifier Default: set by framework to a generated value meta Metadata file name. When specified, will be used to hold the SCSI metadata for the logical unit. Default: None oui Organizational Unique Identifier. 6 hexadecimal ascii characters representing the IEEE OUI company id assignment. This will be used to generate the device identifier (GUID). Default: 00144F pid 16 characters of product identification SCSI SPC-3 and will be reflected in the Standard INQUIRY data returned for the device. Default: set to COMSTAR serial Serial Number. Specifies the SCSI Vital Product Data Serial Number (page 80h). It is a character value up to 252 bytes in length. Default: none vid 8 characters of vendor identification per SCSI SPC-3 and will be reflected in the Standard INQUIRY data returned for the device. Default: set to SUN wcd Write back cache disable. When specified as "true" or "false", specifies write back cache disable behavior Default: Writeback cache setting of the backing store device specified by . wp Write protect bit. When specified as "true" or "false", specifies whether the device reports as write protected. Default: "false" For the -s option, size is an integer followed by one of the following letters, to indicate a unit of size: k kilobyte m megabyte g gigabyte t terabyte p petabyte e exabyte lu-file is the file to be used as the backing store for the logical unit. If the -s option is not specified, the size of the specified lu-file will be used as the size of the logical unit. Logical units registered with stmf require space for the metadata to be stored. When a zvol is specified as the backing store device, the default will be to use a special property of the zvol to contain the metadata. For all other devices, the default behavior will be to use the first 64k of the device. An alternative approach would be to use the 'meta' property on create-lu to specify an alternate file to contain the metadata. It is advisable to use a file that can provide sufficient storage of the logical unit metadata, preferably 64k or greater. delete-lu lu_name Deletes an existing logical unit that was created using stmfadm create-lu. This effectively unloads the logical unit from the STMF framework. Any existing data on the logical unit remains intact. import-lu lu_file Imports and loads a logical unit into the STMF that was previously created using stmfadm create-lu and was since deleted from the STMF using stmfadm delete-lu. On success, the logical unit is again made available to the STMF. lu_file is the filename used in the stmfadm create-lu command. If this logical unit is using a separate metadata file, the filename in the 'meta' property value that was used in the stmfadm create-lu command must be used here. modify-lu [-p, --lu-prop logical-unit-property=val -s, --size size, -f, --file] lu-name|lu-file Modifies attributes of a logical unit created using the stmfadm create-lu command. For the -p option, logical-unit-property can be one of the following properties: alias Up to 255 characters representing a user defined name for the device Default: set to file name of backing store wcd Write back cache disable. When specified as "true" or "false", specifies write back cache disable behavior Default: Writeback cache setting of the backing store device specified by . wp Write protect bit. When specified as "true" or "false", specifies whether the device reports as write protected. Default: "false" For the -s option, size is an integer followed by one of the following letters, to indicate a unit of size: k kilobyte m megabyte g gigabyte t terabyte p petabyte e exabyte lu-name is the guid of the logical unit to be modified. If the -f option is specified, the operand is interpreted as a filename. This provides the ability to modify a logical unit that is not currently imported into STMF. Appendix B ========== stmfCreateLuResource -------------------- NAME stmfCreateLuResource - create new logical unit resource SYNOPSIS cc [ flag... ] file... -lstmf [ library... ] #include int stmfCreateLuResource(uint16_t dType, luResource *hdl); PARAMETERS dType The device type of the logical unit resource. Note: Only STMF_DISK is currently supported. hdl The luResource hdl to create. DESCRIPTION The stmfCreateLuResource() function creates a resource for setting properties of a logical unit for purposes of creating a logical unit in STMF. RETURN VALUES The following values are returned: STMF_ERROR_INVALID_ARG Either type is unrecognized or hdl 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 | |_____________________________|_____________________________| stmfSetLuProp, stmfGetLuProp ---------------------------- NAME stmfSetLuProp - set a logical unit property stmfGetLuProp - get a logical unit property SYNOPSIS cc [ flag... ] file... -lstmf [ library... ] #include int stmfSetLuProp(luResource hdl, uint32_t prop, const char *propVal); int stmfGetLuProp(luResource hdl, uint32_t prop, char *propVal, size_t *propLen); PARAMETERS hdl A previously allocated luResource either via stmfCreateLuResource or stmfGetLuResource. prop A property type value. See DESCRIPTION for valid values. propVal A property value. propLen The length of the specified property value. If propLen was of an insufficient size to hold the returned property value, propLen will contain the required size of the buffer and STMF_ERROR_INVALID_ARG will be returned. DESCRIPTION Set or get property values. All property values are expressed in human-readable form. Boolean properties are expressed in case insensitive form of "true" or "false". Properties that are represented by ASCII hexadecimal are done so without any leading characters to indicate a base hexadecimal representation (i.e. no leading "0x"). prop can be one of the following values: STMF_LU_PROP_ALIAS Up to 255 characters representing a user defined name for the device. Default: set to file name of backing store STMF_LU_PROP_BLOCK_SIZE Numeric value for block size in bytes in 2^n. Default: 512 STMF_LU_PROP_COMPANY_ID Organizational Unique Identifier. 6 hexadecimal ASCII characters representing the IEEE OUI company id assignment. This will be used to generate the device identifier (GUID). Default: 00144F STMF_LU_PROP_DATA_FILENAME Character value representing the file name of the backing store device. Default: None STMF_LU_PROP_GUID ASCII hexadecimal string of 32 characters representing the unique identifier for the device. This must be of valid 32 hexadecimal ascii characters representing a valid NAA Registered Extended Identifier. Default: set by framework to a generated value STMF_LU_PROP_META_FILENAME Metadata file name. When specified, will be used to hold the metadata for the logical unit. Default: None. If this value is not specified, value specified in STMF_LU_PROP_DATA_FILENAME will be used. STMF_LU_PROP_PID Up to 16 characters of product identification that will be reflected in the Standard INQUIRY data returned for the device. Default: set to COMSTAR STMF_LU_PROP_PRODUCT_REV Up to 4 characters of revision information that will be reflected in the Standard INQUIRY data returned for the device. Default: set to 1.0 STMF_LU_PROP_SERIAL_NUM Serial Number. Specifies the SCSI Vital Product Data Serial Number (page 80h). It is a character value up to 252 bytes in length. Default: None STMF_LU_PROP_SIZE Numeric value w/optional suffix, e.g. 100G, 1T, to specify unit of size. Default: Size of device specified in the STMF_LU_PROP_DATA_FILENAME property value. STMF_LU_PROP_VID 8 characters of vendor identification per SCSI SPC-3 and will be reflected in the Standard INQUIRY data returned for the device. Default: set to SUN STMF_LU_PROP_WRITE_CACHE_DISABLE Write back cache disable. When specified as "true" or "false", specifies write back cache disable behavior Default: Writeback cache setting of the backing store device specified by STMF_LU_PROP_DATA_FILENAME. STMF_LU_PROP_WRITE_PROTECT Write protect bit. When specified as "true" or "false", specifies whether the device behaves as a write protected device. Default: "false" Any properties that are not specified assume default values. At a minimum, STMF_LU_PROP_DATA_FILENAME must be specified in order to use this hdl in a call to stmfCreateLu(). RETURN VALUES STMF_STATUS_SUCCESS The API call was successful. STMF_ERROR_INVALID_ARG Either prop or propVal is unrecognized. STMF_ERROR_INVALID_PROPSIZE The size of propVal is invalid. STMF_ERROR_NO_PROP The value of prop is unknown for this resource type. ATTRIBUTES See attributes(5) for descriptions of the following attributes: ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Interface Stability | Committed | |_____________________________|_____________________________| | MT-Level | Safe | |_____________________________|_____________________________| stmfCreateLu ------------ NAME stmfCreateLu - create a logical unit SYNOPSIS cc [ flag... ] file... -lstmf [ library... ] #include int stmfCreateLu(luResource hdl, stmfGuid *luGuid); PARAMETERS hdl The luResource hdl returned from a previous call to stmfCreateLuResource(). luGuid If non-NULL, it must contain a pointer to an stmfGuid structure allocated by the caller. On successful return from this API, it will contain the guid of the newly created logical unit. If luGuid is NULL, this argument is ignored. DESCRIPTION Create a logical unit in stmf using the properties of hdl. Please see stmfSetLuProp() for a complete description of properties and their possible values. RETURN VALUES STMF_STATUS_SUCCESS The API call was successful. STMF_ERROR_FILE_IN_USE The filename specified by the STMF_LU_PROP_DATA_FILENAME or STMF_LU_PROP_META_FILENAME was in use. STMF_ERROR_GUID_IN_USE The guid specified by the STMF_LU_PROP_GUID property is already being used. STMF_ERROR_INVALID_BLKSIZE The blocksize specified by STMF_LU_PROP_BLOCK_SIZE is invalid. STMF_ERROR_WRITE_CACHE_SET The requested write cache setting could not be provided. STMF_ERROR_SIZE_OUT_OF_RANGE The specified logical unit size is not supported. STMF_ERROR_META_FILE_NAME The specified meta file could not be accessed. STMF_ERROR_DATA_FILE_NAME The specified data file could not be accessed. ATTRIBUTES See attributes(5) for descriptions of the following attributes: ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Interface Stability | Committed | |_____________________________|_____________________________| | MT-Level | Safe | |_____________________________|_____________________________| stmfDeleteLu ------------ NAME stmfDeleteLu - delete a logical unit SYNOPSIS cc [ flag... ] file... -lstmf [ library... ] #include int stmfDeleteLu(stmfGuid *luGuid); PARAMETERS luGuid pointer to an stmfGuid structure containing the guid of the logical unit to delete. DESCRIPTION Delete the logical unit from the system. Note: any view entries that may exist for this logical unit will be retained in the system and must be removed using stmfRemoveViewEntry if so desired. RETURN VALUES STMF_STATUS_SUCCESS The API call was successful. STMF_ERROR_NOT_FOUND The guid does not exist. ATTRIBUTES See attributes(5) for descriptions of the following attributes: ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Interface Stability | Committed | |_____________________________|_____________________________| | MT-Level | Safe | |_____________________________|_____________________________| stmfModifyLu ------------ NAME stmfModifyLu - modify a logical unit stmfModifyLuByFname - modify a logical unit by filename SYNOPSIS cc [ flag... ] file... -lstmf [ library... ] #include int stmfModifyLu(stmfGuid *luGuid, uint32_t prop, const char *propVal) int stmfModifyLu(uint16_t dType, const char *fname, uint32_t prop, const char *propVal) PARAMETERS luGuid guid of logical unit to modify fname filename of logical unit to modify dType Type of logical unit. See stmfCreateLuResource(3STMF). prop A property type value. See DESCRIPTION for valid values. propVal A property value. DESCRIPTION Modify the properties of a logical unit device. Valid properties for modify STMF_DISK: STMF_LU_PROP_ALIAS Up to 255 characters representing a user defined name for the device. Default: set to file name of backing store STMF_LU_PROP_SIZE Numeric value w/optional suffix, e.g. 100G, 1T, to specify unit of size. Default: Size of device specified in the STMF_LU_PROP_DATA_FILENAME property value. STMF_LU_PROP_WRITE_CACHE_DISABLE Write back cache disable. When specified as "true" or "false", specifies write back cache disable behavior. Default: Writeback cache setting of the backing store device specified by STMF_LU_PROP_DATA_FILENAME. STMF_LU_PROP_WRITE_PROTECT Write protect bit. When specified as "true" or "false", specifies whether the device behaves as a write protected device. Default: "false" RETURN VALUES STMF_STATUS_SUCCESS The API call was successful. STMF_ERROR_INVALID_ARG Either prop or propVal is unrecognized. STMF_ERROR_INVALID_PROPSIZE The size of propVal is invalid. STMF_ERROR_NO_PROP The value of prop is unknown for this resource type. ATTRIBUTES See attributes(5) for descriptions of the following attributes: ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Interface Stability | Committed | |_____________________________|_____________________________| | MT-Level | Safe | |_____________________________|_____________________________| stmfGetLuResource ----------------- NAME stmfGetLuResource - get a logical unit resource for a currently registered logical unit. SYNOPSIS cc [ flag... ] file... -lstmf [ library... ] #include int stmfGetLuResource(stmfGuid *luGuid, luResource *hdl) PARAMETERS luGuid guid of logical unit to retrieve hdl The luResource hdl to create. DESCRIPTION Retrieve a logical unit resource hdl for a given logical unit. luGuid must represent a currently registered stmf logical unit. This retrieved resource is a set of device specific properties for a logical unit device. This allocates an luResource hdl of device type matching luGuid. stmfFreeLuResource should be used when hdl is no longer needed. RETURN VALUES STMF_STATUS_SUCCESS The API call was successful. STMF_ERROR_NOT_FOUND The guid does not exist. ATTRIBUTES See attributes(5) for descriptions of the following attributes: ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Interface Stability | Committed | |_____________________________|_____________________________| | MT-Level | Safe | |_____________________________|_____________________________| stmfFreeLuResource ------------------ NAME stmfFreeLuResource SYNOPSIS cc [ flag... ] file... -lstmf [ library... ] #include int stmfFreeLuResource(luResource hdl) PARAMETERS hdl An luResource previously allocated in a call to stmfLuCreateResource or stmfLuGetResource. DESCRIPTION This frees an allocated luResource that was allocated via stmfCreateLuResource or stmfGetLuResource. RETURN VALUES STMF_STATUS_SUCCESS The API call was successful. STMF_ERROR_INVALID_ARG hdl is not a valid luResource hdl ATTRIBUTES See attributes(5) for descriptions of the following attributes: ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Interface Stability | Committed | |_____________________________|_____________________________| | MT-Level | Safe | |_____________________________|_____________________________| stmfSetPersistMethod ------------------- NAME stmfSetPersistMethod - set persistence method for the stmf service SYNOPSIS cc [ flag... ] file... -lstmf [ library... ] #include int stmfSetPersistMethod(uint8_t persistType, boolean_t serviceSet) PARAMETERS persistType The requested persistence setting. Can be one of: STMF_PERSIST_SMF STMF_PERSIST_NONE serviceSet Set to indicate whether the setting should persist on the stmf service. When set to B_FALSE, this setting is only applicable for the duration of the current library open or until a subsequent call is made to change the setting. DESCRIPTION This sets the persistence method for stmf. RETURN VALUES STMF_STATUS_SUCCESS The API call was successful. STMF_ERROR_PERSIST_TYPE persistType is invalid. ATTRIBUTES See attributes(5) for descriptions of the following attributes: ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Interface Stability | Committed | |_____________________________|_____________________________| | MT-Level | Safe | |_____________________________|_____________________________| stmfGetPersistMethod -------------------- NAME stmfGetPersistMethod - get the current persistence method for stmf SYNOPSIS cc [ flag... ] file... -lstmf [ library... ] #include int stmfGetPersistMethod(uint8_t *persistType, boolean_t serviceState) PARAMETERS persistType On success, contains the current persistence setting based on serviceState. serviceState When set to B_TRUE, persistType will contain the persist method currently set for the service. When set to B_FALSE, persistType will contain the persist method for the current library open. DESCRIPTION Retrieves the current persistent method setting for the service or for a given library open. When set to B_TRUE, retrieves the setting from the service. RETURN VALUES STMF_STATUS_SUCCESS The API call was successful. STMF_ERROR_PERSIST_TYPE Unable to retrieve persist type from service. ATTRIBUTES See attributes(5) for descriptions of the following attributes: ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Interface Stability | Committed | |_____________________________|_____________________________| | MT-Level | Safe | |_____________________________|_____________________________| From mark.carlson@sun.com Tue Apr 21 11:39:37 2009 Received: from sunmail3mpk.sfbay.sun.com (sunmail3mpk.SFBay.Sun.COM [129.146.11.52]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n3LIdaup008916 for ; Tue, 21 Apr 2009 11:39:37 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail3mpk.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n3LIda0M010486 for <@sunmail2sca.sfbay.sun.com:PSARC-ext@sun.com>; Tue, 21 Apr 2009 11:39:36 -0700 (PDT) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KIG00H09RTZ1D00@nwk-avmta-1.sfbay.Sun.COM> for PSARC-ext@sun.com (ORCPT PSARC-ext@Sun.COM); Tue, 21 Apr 2009 11:39:35 -0700 (PDT) Received: from brmea-mail-4.sun.com ([192.18.98.36]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KIG00A7ERTYNY60@nwk-avmta-1.sfbay.Sun.COM> for PSARC-ext@sun.com (ORCPT PSARC-ext@Sun.COM); Tue, 21 Apr 2009 11:39:34 -0700 (PDT) Received: from fe-amer-09.sun.com ([192.18.109.79]) by brmea-mail-4.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n3LIdYlE023829 for ; Tue, 21 Apr 2009 18:39:34 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7.0-5.01 64bit (built Feb 19 2009)) id <0KIG00300R7N8P00@mail-amer.sun.com> for PSARC-ext@Sun.COM (ORCPT PSARC-ext@Sun.COM); Tue, 21 Apr 2009 12:39:34 -0600 (MDT) Received: from Macintosh-335.local ([unknown] [129.150.35.120]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7.0-5.01 64bit (built Feb 19 2009)) with ESMTPSA id <0KIG00608RTVRL00@mail-amer.sun.com> for PSARC-ext@Sun.COM (ORCPT PSARC-ext@Sun.COM); Tue, 21 Apr 2009 12:39:32 -0600 (MDT) Date: Tue, 21 Apr 2009 12:39:31 -0600 From: "Mark A. Carlson" Subject: Re: libstmf/stmfadm enhancements for COMSTAR [PSARC/2009/251 FastTrack timeout 04/29/2009] In-reply-to: <49EE1053.6070102@sun.com> Sender: mark.carlson@sun.com To: John Forte Cc: PSARC-ext@sun.com Message-id: <49EE12E3.1000901@sun.com> MIME-version: 1.0 Content-type: multipart/alternative; boundary="Boundary_(ID_sRvSXiYfQMyguGAaO2Nwug)" X-PMX-Version: 5.4.1.325704 References: <49EE1053.6070102@sun.com> User-Agent: Thunderbird 2.0.0.21 (Macintosh/20090302) Status: RO Content-Length: 88156 This is a multi-part message in MIME format. --Boundary_(ID_sRvSXiYfQMyguGAaO2Nwug) Content-type: text/plain; format=flowed; charset=ISO-8859-1 Content-transfer-encoding: 7BIT +1 -- mark John Forte wrote: > I am sponsoring the following fasttrack for myself. Requested binding is > minor. Timeout is set for 4/29. > > - 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: > libstmf/stmfadm enhancements for COMSTAR > 1.2. Name of Document Author/Supplier: > Author: John Forte > 1.3 Date of This Document: > 21 April, 2009 > 4. Technical Description > libstmf/stmfadm enhancements for COMSTAR > > 4.1 Description > > libstmf(3LIB) was introduced in PSARC 2007/523 but lacked any C > interfaces for managing create/delete/modify of sbd (PSARC 2008/235) > logical units. sbdadm(1M) is currently the only interface available for > managing logical units. This case introduces new library interfaces for > managing logical units and introduces new subcommands to stmfadm(1M) to > provide CLI support. The new stmfadm(1M) subcommands will be the > preferred approach and this case will make sbdadm's stability > classification "obsolete committed". This does not introduce any > backward incompatibility with the existing sbdadm functionality. All > existing sbdadm functionality will be carried forward to stmfadm(1M). > This case also introduces two library interfaces for managing > configuration persistence allowing a developer to provide their own > means of persisting configuration data for the stmf service. > > > 4.2 Interfaces > > Minor binding. > > -------------+-----------------------+------------------------- > Interface Classification Comments > -------------+-----------------------+------------------------- > libstmf | Committed | PSARC 2007/523 > | | > stmfadm | Committed | PSARC 2007/523 > output of | Not an interface | > stmfadm | | > | | > sbdadm | Obsolete Committed | PSARC 2008/235 > > > 4.2.1 stmfadm subcommands > > create-lu [-p, --lu-prop logical-unit-property=val > -s, --size size] lu-file > > delete-lu lu-name... > > import-lu lu-file > > modify-lu [-p, --lu-prop logical-unit-property=val > -s, --size size, -f, --file] lu-name|lu-file > > The command man pages are in Appendix A > > > 4.2.2 sbdadm man page change: > > _____________________________________________________________ > | ATTRIBUTE TYPE | ATTRIBUTE VALUE | > |_____________________________|_____________________________| > | Availability | SUNWstmfu | > |_____________________________|_____________________________| > ! | Interface Stability | Obsolete Committed | > |_____________________________|_____________________________| > > + NOTES > + This command is obsolete and may be removed in a future release. > + Please use stmfadm(1M) for equivalent functionality. > > > 4.2.3 Library interfaces > > Note: All library interfaces are committed as per libstmf's current > interface classification. > > > int stmfCreateLu(luResource hdl, stmfGuid *luGuid); > int stmfCreateLuResource(uint16_t type, luResource *hdl); > int stmfDeleteLu(stmfGuid *luGuid); > int stmfFreeLuResource(luResource hdl); > int stmfGetLuProp(luResource hdl, uint32_t prop, char *propVal, > size_t *propLen); > int stmfGetLuResource(stmfGuid *luGuid, luResource *hdl) > int stmfGetPersistMethod(uint8_t *persistType, boolean_t > serviceState); > int stmfModifyLu(stmfGuid *luGuid, uint32_t prop, const char > *propVal); > int stmfSetLuProp(luResource hdl, uint32_t prop, const char *propVal); > int stmfSetPersistMethod(uint8_t persistType, boolean_t serviceSet); > > The interface man pages are in Appendix B. > > > 6. Resources and Schedule > 6.4. Steering Committee requested information > 6.4.1. Consolidation C-team Name: > OS/Net > 6.5. ARC review type: FastTrack > 6.6. ARC Exposure: open > > Appendix A > ========== > > create-lu [-p, --lu-prop logical-unit-property=val > -s, --size size] lu-file > > Create a logical unit that can be registered with STMF. For the > -p option, logical-unit-property can be one of the following > properties: > > alias > Up to 255 characters representing a user defined > name for the device > > Default: set to file name of backing store > > blk > Block size. Specifies the block size for the > device. > > Default: 512 > > guid > 32 hexadecimal ascii characters representing a > valid NAA Registered Extended Identifier > > Default: set by framework to a generated value > > meta > Metadata file name. When specified, will be used > to hold the SCSI metadata for the logical unit. > > Default: None > > oui > Organizational Unique Identifier. 6 hexadecimal > ascii characters representing the IEEE OUI company > id assignment. This will be used to generate the > device identifier (GUID). > > Default: 00144F > > pid > 16 characters of product identification > SCSI SPC-3 and will be reflected in the Standard > INQUIRY data returned for the device. > > Default: set to COMSTAR > > serial > Serial Number. Specifies the SCSI Vital Product > Data Serial Number (page 80h). It is a character > value up to 252 bytes in length. > > Default: none > > vid > 8 characters of vendor identification per > SCSI SPC-3 and will be reflected in the Standard > INQUIRY data returned for the device. > > Default: set to SUN > > wcd > Write back cache disable. When specified as "true" or > "false", specifies write back cache disable behavior > > Default: Writeback cache setting of the backing > store device specified by . > > wp > Write protect bit. When specified as "true" or > "false", specifies whether the device reports as > write protected. > > Default: "false" > > > For the -s option, size is an integer followed by one of the > following letters, to indicate a unit of size: > > k kilobyte > > m megabyte > > g gigabyte > > t terabyte > > p petabyte > > e exabyte > > lu-file is the file to be used as the backing store for the > logical unit. If the -s option is not specified, the size of the > specified lu-file will be used as the size of the logical unit. > Logical units registered with stmf require space for the > metadata to be stored. When a zvol is specified as the backing > store device, the default will be to use a special property of > the zvol to contain the metadata. For all other devices, the > default behavior will be to use the first 64k of the > device. An alternative approach would be to use the 'meta' > property on create-lu to specify an alternate file to contain > the metadata. It is advisable to use a file that can provide > sufficient storage of the logical unit metadata, preferably 64k > or greater. > > delete-lu lu_name > > Deletes an existing logical unit that was created using > stmfadm create-lu. This effectively unloads the logical > unit from the STMF framework. Any existing data > on the logical unit remains intact. > > import-lu lu_file > > Imports and loads a logical unit into the STMF that was > previously created using stmfadm create-lu and was since deleted > from the STMF using stmfadm delete-lu. On success, the logical > unit is again made available to the STMF. lu_file is the > filename used in the stmfadm create-lu command. If this logical > unit is using a separate metadata file, the filename in the > 'meta' property value that was used in the stmfadm create-lu > > command must be used here. > > modify-lu [-p, --lu-prop logical-unit-property=val > -s, --size size, -f, --file] lu-name|lu-file > > Modifies attributes of a logical unit created using the stmfadm > create-lu command. For the -p option, logical-unit-property can > be one of the following properties: > > alias > Up to 255 characters representing a user defined > name for the device > > Default: set to file name of backing store > > wcd > Write back cache disable. When specified as "true" or > "false", specifies write back cache disable behavior > > Default: Writeback cache setting of the backing > store device specified by . > > wp > Write protect bit. When specified as "true" or > "false", specifies whether the device reports as > write protected. > > Default: "false" > > For the -s option, size is an integer followed by one of the > following letters, to indicate a unit of size: > > k kilobyte > > m megabyte > > g gigabyte > > t terabyte > > p petabyte > > e exabyte > > lu-name is the guid of the logical unit to be modified. If the > -f option is specified, the operand is interpreted as a > filename. This provides the ability to modify a logical unit > that is not currently imported into STMF. > > Appendix B > ========== > > stmfCreateLuResource > -------------------- > > NAME > stmfCreateLuResource - create new logical unit resource > > SYNOPSIS > cc [ flag... ] file... -lstmf [ library... ] > #include > > int stmfCreateLuResource(uint16_t dType, luResource *hdl); > > PARAMETERS > dType The device type of the logical unit resource. > Note: Only STMF_DISK is currently supported. > > hdl The luResource hdl to create. > > > DESCRIPTION > The stmfCreateLuResource() function creates a resource for setting > properties of a logical unit for purposes of creating a logical unit > in STMF. > > RETURN VALUES > The following values are returned: > > STMF_ERROR_INVALID_ARG Either type is unrecognized or hdl 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 | > |_____________________________|_____________________________| > > > > stmfSetLuProp, stmfGetLuProp > ---------------------------- > > NAME > stmfSetLuProp - set a logical unit property > stmfGetLuProp - get a logical unit property > > SYNOPSIS > cc [ flag... ] file... -lstmf [ library... ] > #include > > int stmfSetLuProp(luResource hdl, uint32_t prop, const char > *propVal); > int stmfGetLuProp(luResource hdl, uint32_t prop, char *propVal, > size_t *propLen); > > PARAMETERS > hdl A previously allocated luResource either via > stmfCreateLuResource or stmfGetLuResource. > > prop A property type value. See DESCRIPTION for valid values. > > propVal A property value. > > propLen The length of the specified property value. If propLen was > of an insufficient size to hold the returned property value, > propLen will contain the required size of the buffer and > STMF_ERROR_INVALID_ARG will be returned. > > DESCRIPTION > Set or get property values. All property values are expressed in > human-readable form. Boolean properties are expressed in case > insensitive form of "true" or "false". Properties that are represented > by ASCII hexadecimal are done so without any leading characters to > indicate a base hexadecimal representation (i.e. no leading "0x"). > prop can be one of the following values: > > STMF_LU_PROP_ALIAS > Up to 255 characters representing a user defined name for the > device. > > Default: set to file name of backing store > > STMF_LU_PROP_BLOCK_SIZE > Numeric value for block size in bytes in 2^n. > > Default: 512 > > STMF_LU_PROP_COMPANY_ID > Organizational Unique Identifier. 6 hexadecimal ASCII > characters representing the IEEE OUI company id assignment. > This will be used to generate the device identifier (GUID). > > Default: 00144F > > STMF_LU_PROP_DATA_FILENAME > Character value representing the file name of the backing > store device. > > Default: None > > STMF_LU_PROP_GUID > ASCII hexadecimal string of 32 characters representing the > unique identifier for the device. This must be of valid > 32 hexadecimal ascii characters representing a valid NAA > Registered Extended Identifier. > > Default: set by framework to a generated value > > STMF_LU_PROP_META_FILENAME > Metadata file name. When specified, will be used to hold the > metadata for the logical unit. > > Default: None. If this value is not specified, value > specified in STMF_LU_PROP_DATA_FILENAME will > be used. > > STMF_LU_PROP_PID > Up to 16 characters of product identification that will be > reflected in the Standard INQUIRY data returned for the > device. > > Default: set to COMSTAR > > STMF_LU_PROP_PRODUCT_REV > Up to 4 characters of revision information that will be > reflected in the Standard INQUIRY data returned for the > device. > > Default: set to 1.0 > > STMF_LU_PROP_SERIAL_NUM > Serial Number. Specifies the SCSI Vital Product Data Serial > Number (page 80h). It is a character value up to 252 bytes in > length. > > Default: None > > STMF_LU_PROP_SIZE > Numeric value w/optional suffix, e.g. 100G, 1T, to specify > unit of size. > > Default: Size of device specified in the > STMF_LU_PROP_DATA_FILENAME property value. > > STMF_LU_PROP_VID > 8 characters of vendor identification per SCSI SPC-3 and will > be reflected in the Standard INQUIRY data returned for the > device. > > Default: set to SUN > > STMF_LU_PROP_WRITE_CACHE_DISABLE > Write back cache disable. When specified as "true" or > "false", specifies write back cache disable behavior > > Default: Writeback cache setting of the backing > store device specified by > STMF_LU_PROP_DATA_FILENAME. > > STMF_LU_PROP_WRITE_PROTECT > Write protect bit. When specified as "true" or "false", > specifies whether the device behaves as a write protected > device. > > Default: "false" > > Any properties that are not specified assume default values. At a > minimum, STMF_LU_PROP_DATA_FILENAME must be specified in order to > use this hdl in a call to stmfCreateLu(). > > RETURN VALUES > STMF_STATUS_SUCCESS The API call was successful. > > STMF_ERROR_INVALID_ARG Either prop or propVal is unrecognized. > > STMF_ERROR_INVALID_PROPSIZE The size of propVal is invalid. > > STMF_ERROR_NO_PROP The value of prop is unknown for this > resource type. > > ATTRIBUTES > See attributes(5) for descriptions of the following attributes: > > ____________________________________________________________ > | ATTRIBUTE TYPE | ATTRIBUTE VALUE | > |_____________________________|_____________________________| > | Interface Stability | Committed | > |_____________________________|_____________________________| > | MT-Level | Safe | > |_____________________________|_____________________________| > > > stmfCreateLu > ------------ > > NAME > stmfCreateLu - create a logical unit > > SYNOPSIS > cc [ flag... ] file... -lstmf [ library... ] > #include > > int stmfCreateLu(luResource hdl, stmfGuid *luGuid); > > PARAMETERS > > hdl The luResource hdl returned from a previous call to > stmfCreateLuResource(). > > luGuid If non-NULL, it must contain a pointer to an stmfGuid > structure allocated by the caller. On successful return from > this API, it will contain the guid of the newly created > logical unit. If luGuid is NULL, this argument is ignored. > > DESCRIPTION > Create a logical unit in stmf using the properties of hdl. Please see > stmfSetLuProp() for a complete description of properties and their > possible values. > > RETURN VALUES > > STMF_STATUS_SUCCESS The API call was successful. > > STMF_ERROR_FILE_IN_USE The filename specified by the > STMF_LU_PROP_DATA_FILENAME or > STMF_LU_PROP_META_FILENAME was in use. > > STMF_ERROR_GUID_IN_USE The guid specified by the > STMF_LU_PROP_GUID property is already > being used. > > STMF_ERROR_INVALID_BLKSIZE The blocksize specified by > STMF_LU_PROP_BLOCK_SIZE is invalid. > > STMF_ERROR_WRITE_CACHE_SET The requested write cache setting could > not be provided. > > STMF_ERROR_SIZE_OUT_OF_RANGE The specified logical unit size is > not supported. > > STMF_ERROR_META_FILE_NAME The specified meta file could not be > accessed. > > STMF_ERROR_DATA_FILE_NAME The specified data file could not be > accessed. > > ATTRIBUTES > See attributes(5) for descriptions of the following attributes: > > ____________________________________________________________ > | ATTRIBUTE TYPE | ATTRIBUTE VALUE | > |_____________________________|_____________________________| > | Interface Stability | Committed | > |_____________________________|_____________________________| > | MT-Level | Safe | > |_____________________________|_____________________________| > > > stmfDeleteLu > ------------ > NAME > stmfDeleteLu - delete a logical unit > > SYNOPSIS > cc [ flag... ] file... -lstmf [ library... ] > #include > > int stmfDeleteLu(stmfGuid *luGuid); > > PARAMETERS > luGuid pointer to an stmfGuid structure containing the guid > of the logical unit to delete. > > DESCRIPTION > Delete the logical unit from the system. Note: any view entries that > may exist for this logical unit will be retained in the system and > must > be removed using stmfRemoveViewEntry if so desired. > > RETURN VALUES > > STMF_STATUS_SUCCESS The API call was successful. > > STMF_ERROR_NOT_FOUND The guid does not exist. > > ATTRIBUTES > See attributes(5) for descriptions of the following attributes: > > ____________________________________________________________ > | ATTRIBUTE TYPE | ATTRIBUTE VALUE | > |_____________________________|_____________________________| > | Interface Stability | Committed | > |_____________________________|_____________________________| > | MT-Level | Safe | > |_____________________________|_____________________________| > > > stmfModifyLu > ------------ > NAME > stmfModifyLu - modify a logical unit > stmfModifyLuByFname - modify a logical unit by filename > > SYNOPSIS > cc [ flag... ] file... -lstmf [ library... ] > #include > > int stmfModifyLu(stmfGuid *luGuid, uint32_t prop, const char > *propVal) > int stmfModifyLu(uint16_t dType, const char *fname, uint32_t prop, > const char *propVal) > > PARAMETERS > luGuid guid of logical unit to modify > > fname filename of logical unit to modify > > dType Type of logical unit. See stmfCreateLuResource(3STMF). > > prop A property type value. See DESCRIPTION for valid values. > > propVal A property value. > > DESCRIPTION > Modify the properties of a logical unit device. > > Valid properties for modify STMF_DISK: > STMF_LU_PROP_ALIAS > Up to 255 characters representing a user defined name for the > device. > > Default: set to file name of backing store > > STMF_LU_PROP_SIZE > Numeric value w/optional suffix, e.g. 100G, 1T, to specify > unit of size. > > Default: Size of device specified in the > STMF_LU_PROP_DATA_FILENAME property value. > > STMF_LU_PROP_WRITE_CACHE_DISABLE > Write back cache disable. When specified as "true" or > "false", specifies write back cache disable behavior. > > Default: Writeback cache setting of the backing > store device specified by > STMF_LU_PROP_DATA_FILENAME. > > STMF_LU_PROP_WRITE_PROTECT > Write protect bit. When specified as "true" or "false", > specifies whether the device behaves as a write protected > device. > > Default: "false" > > RETURN VALUES > STMF_STATUS_SUCCESS The API call was successful. > > STMF_ERROR_INVALID_ARG Either prop or propVal is unrecognized. > > STMF_ERROR_INVALID_PROPSIZE The size of propVal is invalid. > > STMF_ERROR_NO_PROP The value of prop is unknown for this > resource type. > > ATTRIBUTES > See attributes(5) for descriptions of the following attributes: > > ____________________________________________________________ > | ATTRIBUTE TYPE | ATTRIBUTE VALUE | > |_____________________________|_____________________________| > | Interface Stability | Committed | > |_____________________________|_____________________________| > | MT-Level | Safe | > |_____________________________|_____________________________| > > > stmfGetLuResource > ----------------- > NAME > stmfGetLuResource - get a logical unit resource for a currently > registered logical unit. > > SYNOPSIS > cc [ flag... ] file... -lstmf [ library... ] > #include > > int stmfGetLuResource(stmfGuid *luGuid, luResource *hdl) > > PARAMETERS > luGuid guid of logical unit to retrieve > > hdl The luResource hdl to create. > > DESCRIPTION > Retrieve a logical unit resource hdl for a given logical unit. luGuid > must represent a currently registered stmf logical unit. This > retrieved resource is a set of device specific properties for a > logical unit device. This allocates an luResource hdl of device type > matching luGuid. stmfFreeLuResource should be used when hdl is no > longer needed. > > RETURN VALUES > STMF_STATUS_SUCCESS The API call was successful. > > STMF_ERROR_NOT_FOUND The guid does not exist. > > ATTRIBUTES > See attributes(5) for descriptions of the following attributes: > > ____________________________________________________________ > | ATTRIBUTE TYPE | ATTRIBUTE VALUE | > |_____________________________|_____________________________| > | Interface Stability | Committed | > |_____________________________|_____________________________| > | MT-Level | Safe | > |_____________________________|_____________________________| > > > stmfFreeLuResource > ------------------ > NAME > stmfFreeLuResource > > SYNOPSIS > cc [ flag... ] file... -lstmf [ library... ] > #include > > int stmfFreeLuResource(luResource hdl) > > PARAMETERS > hdl An luResource previously allocated in a call to > stmfLuCreateResource or stmfLuGetResource. > > DESCRIPTION > This frees an allocated luResource that was allocated via > stmfCreateLuResource or stmfGetLuResource. > > RETURN VALUES > STMF_STATUS_SUCCESS The API call was successful. > > STMF_ERROR_INVALID_ARG hdl is not a valid luResource hdl > > ATTRIBUTES > See attributes(5) for descriptions of the following attributes: > > ____________________________________________________________ > | ATTRIBUTE TYPE | ATTRIBUTE VALUE | > |_____________________________|_____________________________| > | Interface Stability | Committed | > |_____________________________|_____________________________| > | MT-Level | Safe | > |_____________________________|_____________________________| > > > stmfSetPersistMethod > ------------------- > NAME > stmfSetPersistMethod - set persistence method for the stmf service > > SYNOPSIS > cc [ flag... ] file... -lstmf [ library... ] > #include > > int stmfSetPersistMethod(uint8_t persistType, boolean_t serviceSet) > > PARAMETERS > persistType The requested persistence setting. Can be one of: > STMF_PERSIST_SMF > STMF_PERSIST_NONE > > serviceSet Set to indicate whether the setting should persist > on the stmf service. When set to B_FALSE, this > setting is only applicable for the duration of the > current library open or until a subsequent call is > made to change the setting. > > DESCRIPTION > This sets the persistence method for stmf. > > RETURN VALUES > STMF_STATUS_SUCCESS The API call was successful. > > STMF_ERROR_PERSIST_TYPE persistType is invalid. > > ATTRIBUTES > See attributes(5) for descriptions of the following attributes: > > ____________________________________________________________ > | ATTRIBUTE TYPE | ATTRIBUTE VALUE | > |_____________________________|_____________________________| > | Interface Stability | Committed | > |_____________________________|_____________________________| > | MT-Level | Safe | > |_____________________________|_____________________________| > > > stmfGetPersistMethod > -------------------- > NAME > stmfGetPersistMethod - get the current persistence method for stmf > > SYNOPSIS > cc [ flag... ] file... -lstmf [ library... ] > #include > > int stmfGetPersistMethod(uint8_t *persistType, boolean_t serviceState) > > PARAMETERS > persistType On success, contains the current persistence setting > based on serviceState. > > serviceState When set to B_TRUE, persistType will contain the > persist method currently set for the service. When > set to B_FALSE, persistType will contain the persist > method for the current library open. > > DESCRIPTION > Retrieves the current persistent method setting for the service or > for a given library open. When set to B_TRUE, retrieves the setting > from the service. > > RETURN VALUES > STMF_STATUS_SUCCESS The API call was successful. > > STMF_ERROR_PERSIST_TYPE Unable to retrieve persist type from > service. > > ATTRIBUTES > See attributes(5) for descriptions of the following attributes: > > ____________________________________________________________ > | ATTRIBUTE TYPE | ATTRIBUTE VALUE | > |_____________________________|_____________________________| > | Interface Stability | Committed | > |_____________________________|_____________________________| > | MT-Level | Safe | > |_____________________________|_____________________________| > > > -- * Mark A. Carlson * Sr. Architect *Systems Group* Phone x69559 / 303-223-6139 Email Mark.Carlson@Sun.COM --Boundary_(ID_sRvSXiYfQMyguGAaO2Nwug) Content-type: text/html; charset=ISO-8859-1 Content-transfer-encoding: 7BIT +1

-- mark

John Forte wrote:
I am sponsoring the following fasttrack for myself. Requested binding is
minor. Timeout is set for 4/29.

- 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:
        libstmf/stmfadm enhancements for COMSTAR
   1.2. Name of Document Author/Supplier:
        Author:  John Forte
   1.3  Date of This Document:
       21 April, 2009
4. Technical Description
libstmf/stmfadm enhancements for COMSTAR

4.1  Description

libstmf(3LIB) was introduced in PSARC 2007/523 but lacked any C
interfaces for managing create/delete/modify of sbd (PSARC 2008/235)
logical units. sbdadm(1M) is currently the only interface available for
managing logical units. This case introduces new library interfaces for
managing logical units and introduces new subcommands to stmfadm(1M) to
provide CLI support. The new stmfadm(1M) subcommands will be the
preferred approach and this case will make sbdadm's stability
classification "obsolete committed". This does not introduce any
backward incompatibility with the existing sbdadm functionality. All
existing sbdadm functionality will be carried forward to stmfadm(1M).
This case also introduces two library interfaces for managing
configuration persistence allowing a developer to provide their own
means of persisting configuration data for the stmf service.


4.2  Interfaces

   Minor binding.

   -------------+-----------------------+-------------------------
   Interface        Classification         Comments
   -------------+-----------------------+-------------------------
   libstmf      |   Committed           |  PSARC 2007/523
                |                       |
   stmfadm      |   Committed           |  PSARC 2007/523
   output of    |   Not an interface    |
     stmfadm    |                       |
                |                       |
   sbdadm       |   Obsolete Committed  |  PSARC 2008/235


4.2.1 stmfadm subcommands

   create-lu [-p, --lu-prop logical-unit-property=val
       -s, --size size] lu-file

   delete-lu lu-name...

   import-lu lu-file

   modify-lu [-p, --lu-prop logical-unit-property=val
       -s, --size size, -f, --file] lu-name|lu-file

The command man pages are in Appendix A


4.2.2 sbdadm man page change:

   _____________________________________________________________
   |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
   |_____________________________|_____________________________|
   | Availability                | SUNWstmfu                   |
   |_____________________________|_____________________________|
!  | Interface Stability         | Obsolete Committed          |
   |_____________________________|_____________________________|

+ NOTES
+     This command is obsolete and may be removed in a future release.
+     Please use stmfadm(1M) for equivalent functionality.


4.2.3 Library interfaces

Note: All library interfaces are committed as per libstmf's current
interface classification.


  int stmfCreateLu(luResource hdl, stmfGuid *luGuid);
  int stmfCreateLuResource(uint16_t type, luResource *hdl);
  int stmfDeleteLu(stmfGuid *luGuid);
  int stmfFreeLuResource(luResource hdl);
  int stmfGetLuProp(luResource hdl, uint32_t prop, char *propVal,
      size_t *propLen);
  int stmfGetLuResource(stmfGuid *luGuid, luResource *hdl)
  int stmfGetPersistMethod(uint8_t *persistType, boolean_t    
      serviceState);
  int stmfModifyLu(stmfGuid *luGuid, uint32_t prop, const char
      *propVal);
  int stmfSetLuProp(luResource hdl, uint32_t prop, const char *propVal);
  int stmfSetPersistMethod(uint8_t persistType, boolean_t serviceSet);

The interface man pages are in Appendix B.


6. Resources and Schedule
   6.4. Steering Committee requested information
       6.4.1. Consolidation C-team Name:
               OS/Net
   6.5. ARC review type: FastTrack
   6.6. ARC Exposure: open

Appendix A
==========

    create-lu [-p, --lu-prop logical-unit-property=val
       -s, --size size] lu-file

        Create a logical unit that can be  registered with STMF. For the
        -p option, logical-unit-property can be one of the following
        properties:

        alias
               Up to 255 characters representing a user defined
               name for the device

               Default: set to file name of backing store

        blk
               Block size. Specifies the block size for the
               device.

               Default: 512

        guid
               32 hexadecimal ascii characters representing a
               valid NAA Registered Extended Identifier

               Default: set by framework to a generated value

        meta
               Metadata file name. When specified, will be used
               to hold the SCSI metadata for the logical unit.

               Default: None

        oui
               Organizational Unique Identifier. 6 hexadecimal
               ascii characters representing the IEEE OUI company
               id assignment. This will be used to generate the
               device identifier (GUID).

               Default: 00144F

        pid
               16 characters of product identification
               SCSI SPC-3 and will be reflected in the Standard
               INQUIRY data returned for the device.

               Default: set to COMSTAR

        serial
               Serial Number. Specifies the SCSI Vital Product
               Data Serial Number (page 80h). It is a character
               value up to 252 bytes in length.

               Default: none

        vid
               8 characters of vendor identification per
               SCSI SPC-3 and will be reflected in the Standard
               INQUIRY data returned for the device.

               Default: set to SUN

        wcd
               Write back cache disable. When specified as "true" or
               "false", specifies write back cache disable behavior

               Default: Writeback cache setting of the backing
               store device specified by <lu file>.

        wp
               Write protect bit. When specified as "true" or
               "false", specifies whether the device reports as
               write protected.

               Default: "false"


        For the -s option, size is an integer followed by one of the
        following letters, to indicate a unit of size:

        k    kilobyte

        m    megabyte

        g    gigabyte

        t    terabyte

        p    petabyte

        e    exabyte

        lu-file is the file to be used as the backing store for the
        logical unit. If the -s option is not specified, the size of the
        specified lu-file will be used as the size of the logical unit.
        Logical units registered with stmf require space for the
        metadata to be stored. When a zvol is specified as the backing
        store device, the default will be to use a special property of
        the zvol to contain the metadata. For all other devices, the
        default behavior will be to use the first 64k of the
        device. An alternative approach would be to use the 'meta'
        property on create-lu to specify an alternate file to contain
        the metadata. It is advisable to use a file that can provide
        sufficient storage of the logical unit metadata, preferably 64k
        or greater.

    delete-lu lu_name

        Deletes an existing logical unit that was created  using
        stmfadm  create-lu.  This effectively unloads the logical
        unit from the STMF framework. Any existing data
        on the logical unit remains intact.

    import-lu lu_file

        Imports and loads a logical unit into the STMF that  was
        previously created using stmfadm create-lu and was since deleted
        from the STMF using stmfadm delete-lu.  On success, the logical
        unit is again made available to the STMF. lu_file is the
        filename used in the stmfadm create-lu command. If this logical
        unit is using a separate metadata file, the filename in the
        'meta' property value that was used in the stmfadm create-lu

        command must be used here.

    modify-lu [-p, --lu-prop logical-unit-property=val
            -s, --size size, -f, --file] lu-name|lu-file

        Modifies attributes of a logical unit created using the stmfadm
        create-lu command. For the -p option, logical-unit-property can
        be one of the following properties:

        alias
               Up to 255 characters representing a user defined
               name for the device

               Default: set to file name of backing store

        wcd
               Write back cache disable. When specified as "true" or
               "false", specifies write back cache disable behavior

               Default: Writeback cache setting of the backing
               store device specified by <lu file>.

        wp
               Write protect bit. When specified as "true" or
               "false", specifies whether the device reports as
               write protected.

               Default: "false"

        For the -s option, size is an integer followed by one of the
        following letters, to indicate a unit of size:

        k    kilobyte

        m    megabyte

        g    gigabyte

        t    terabyte

        p    petabyte

        e    exabyte

        lu-name is the guid of the logical unit to be modified. If the
        -f option is specified, the operand is interpreted as a
        filename. This provides the ability to modify a logical unit
        that is not currently imported into STMF.

Appendix B
==========

stmfCreateLuResource
--------------------

NAME
   stmfCreateLuResource - create new logical unit resource

SYNOPSIS
   cc [ flag... ] file... -lstmf [ library... ]
   #include <libstmf.h>

   int stmfCreateLuResource(uint16_t dType, luResource *hdl);

PARAMETERS
   dType   The device type of the logical unit resource.
           Note: Only STMF_DISK is currently supported.

   hdl     The luResource hdl to create.


DESCRIPTION
   The stmfCreateLuResource() function creates a resource for setting
   properties of a logical unit for purposes of creating a logical unit
   in STMF.

RETURN VALUES
   The following values are returned:

   STMF_ERROR_INVALID_ARG      Either type is unrecognized or hdl 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                        |
   |_____________________________|_____________________________|



stmfSetLuProp, stmfGetLuProp
----------------------------

NAME
   stmfSetLuProp - set a logical unit property
   stmfGetLuProp - get a logical unit property

SYNOPSIS
   cc [ flag... ] file... -lstmf [ library... ]
   #include <libstmf.h>

   int stmfSetLuProp(luResource hdl, uint32_t prop, const char
       *propVal);
   int stmfGetLuProp(luResource hdl, uint32_t prop, char *propVal,
       size_t *propLen);

PARAMETERS
   hdl      A previously allocated luResource either via
            stmfCreateLuResource or stmfGetLuResource.

   prop     A property type value. See DESCRIPTION for valid values.

   propVal  A property value.

   propLen  The length of the specified property value. If propLen was
            of an insufficient size to hold the returned property value,
            propLen will contain the required size of the buffer and
            STMF_ERROR_INVALID_ARG will be returned.

DESCRIPTION
  Set or get property values. All property values are expressed in
  human-readable form. Boolean properties are expressed in case
  insensitive form of "true" or "false". Properties that are represented
  by ASCII hexadecimal are done so without any leading characters to
  indicate a base hexadecimal representation (i.e. no leading "0x").
  prop can be one of the following values:

       STMF_LU_PROP_ALIAS
           Up to 255 characters representing a user defined name for the
           device.

           Default: set to file name of backing store

       STMF_LU_PROP_BLOCK_SIZE
           Numeric value for block size in bytes in 2^n.

           Default: 512

       STMF_LU_PROP_COMPANY_ID
           Organizational Unique Identifier. 6 hexadecimal ASCII
           characters representing the IEEE OUI company id assignment.
           This will be used to generate the device identifier (GUID).

           Default: 00144F

       STMF_LU_PROP_DATA_FILENAME
           Character value representing the file name of the backing
           store device.

           Default: None

       STMF_LU_PROP_GUID
           ASCII hexadecimal string of 32 characters representing the
           unique identifier for the device. This must be of valid
           32 hexadecimal ascii characters representing a valid NAA
           Registered Extended Identifier.

           Default: set by framework to a generated value

       STMF_LU_PROP_META_FILENAME
           Metadata file name. When specified, will be used to hold the
           metadata for the logical unit.

           Default: None. If this value is not specified, value
                    specified in STMF_LU_PROP_DATA_FILENAME will
                    be used.

       STMF_LU_PROP_PID
           Up to 16 characters of product identification that will be
           reflected in the Standard INQUIRY data returned for the
           device.

           Default: set to COMSTAR

       STMF_LU_PROP_PRODUCT_REV
           Up to 4 characters of revision information that will be
           reflected in the Standard INQUIRY data returned for the
           device.

           Default: set to 1.0

       STMF_LU_PROP_SERIAL_NUM
           Serial Number. Specifies the SCSI Vital Product Data Serial
           Number (page 80h). It is a character value up to 252 bytes in
           length.

           Default: None

       STMF_LU_PROP_SIZE
           Numeric value w/optional suffix, e.g. 100G, 1T, to specify
           unit of size.

           Default: Size of device specified in the
                    STMF_LU_PROP_DATA_FILENAME property value.

       STMF_LU_PROP_VID
           8 characters of vendor identification per SCSI SPC-3 and will
           be reflected in the Standard INQUIRY data returned for the
           device.

           Default: set to SUN

       STMF_LU_PROP_WRITE_CACHE_DISABLE
           Write back cache disable. When specified as "true" or
           "false", specifies write back cache disable behavior

           Default: Writeback cache setting of the backing
                    store device specified by
                    STMF_LU_PROP_DATA_FILENAME.

       STMF_LU_PROP_WRITE_PROTECT
           Write protect bit. When specified as "true" or "false",
           specifies whether the device behaves as a write protected
           device.

           Default: "false"

   Any properties that are not specified assume default values. At a
   minimum, STMF_LU_PROP_DATA_FILENAME must be specified in order to
   use this hdl in a call to stmfCreateLu().

RETURN VALUES
   STMF_STATUS_SUCCESS         The API call was successful.

   STMF_ERROR_INVALID_ARG      Either prop or propVal is unrecognized.

   STMF_ERROR_INVALID_PROPSIZE The size of propVal is invalid.

   STMF_ERROR_NO_PROP          The value of prop is unknown for this
                               resource type.

ATTRIBUTES
   See attributes(5) for descriptions of the  following  attributes:

    ____________________________________________________________
   |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
   |_____________________________|_____________________________|
   | Interface Stability         | Committed                   |
   |_____________________________|_____________________________|
   | MT-Level                    | Safe                        |
   |_____________________________|_____________________________|


stmfCreateLu
------------

NAME
   stmfCreateLu - create a logical unit

SYNOPSIS
   cc [ flag... ] file... -lstmf [ library... ]
   #include <libstmf.h>

   int stmfCreateLu(luResource hdl, stmfGuid *luGuid);

PARAMETERS

   hdl     The luResource hdl returned from a previous call to
           stmfCreateLuResource().

   luGuid  If non-NULL, it must contain a pointer to an stmfGuid
           structure allocated by the caller. On successful return from
           this API, it will contain the guid of the newly created
           logical unit. If luGuid is NULL, this argument is ignored.

DESCRIPTION
   Create a logical unit in stmf using the properties of hdl. Please see
   stmfSetLuProp() for a complete description of properties and their
   possible values.

RETURN VALUES

   STMF_STATUS_SUCCESS         The API call was successful.

   STMF_ERROR_FILE_IN_USE      The filename specified by the
                               STMF_LU_PROP_DATA_FILENAME or
                               STMF_LU_PROP_META_FILENAME was in use.

   STMF_ERROR_GUID_IN_USE      The guid specified by the
                               STMF_LU_PROP_GUID property is already
                               being used.

   STMF_ERROR_INVALID_BLKSIZE  The blocksize specified by
                               STMF_LU_PROP_BLOCK_SIZE is invalid.

   STMF_ERROR_WRITE_CACHE_SET  The requested write cache setting could
                               not be provided.

   STMF_ERROR_SIZE_OUT_OF_RANGE The specified logical unit size is
                                not supported.

   STMF_ERROR_META_FILE_NAME   The specified meta file could not be
                               accessed.

   STMF_ERROR_DATA_FILE_NAME   The specified data file could not be
                               accessed.

ATTRIBUTES
   See attributes(5) for descriptions of the  following  attributes:

    ____________________________________________________________
   |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
   |_____________________________|_____________________________|
   | Interface Stability         | Committed                   |
   |_____________________________|_____________________________|
   | MT-Level                    | Safe                        |
   |_____________________________|_____________________________|


stmfDeleteLu
------------
NAME
   stmfDeleteLu - delete a logical unit

SYNOPSIS
   cc [ flag... ] file... -lstmf [ library... ]
   #include <libstmf.h>

   int stmfDeleteLu(stmfGuid *luGuid);

PARAMETERS
   luGuid  pointer to an stmfGuid structure containing the guid
           of the logical unit to delete.

DESCRIPTION
   Delete the logical unit from the system. Note: any view entries that
   may exist for this logical unit will be retained in the system and must
   be removed using stmfRemoveViewEntry if so desired.

RETURN VALUES

   STMF_STATUS_SUCCESS         The API call was successful.

   STMF_ERROR_NOT_FOUND        The guid does not exist.

ATTRIBUTES
   See attributes(5) for descriptions of the  following  attributes:

    ____________________________________________________________
   |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
   |_____________________________|_____________________________|
   | Interface Stability         | Committed                   |
   |_____________________________|_____________________________|
   | MT-Level                    | Safe                        |
   |_____________________________|_____________________________|


stmfModifyLu
------------
NAME
   stmfModifyLu - modify a logical unit
   stmfModifyLuByFname - modify a logical unit by filename

SYNOPSIS
   cc [ flag... ] file... -lstmf [ library... ]
   #include <libstmf.h>

   int stmfModifyLu(stmfGuid *luGuid, uint32_t prop, const char
       *propVal)
   int stmfModifyLu(uint16_t dType, const char *fname, uint32_t prop,
       const char *propVal)

PARAMETERS
   luGuid  guid of logical unit to modify

   fname   filename of logical unit to modify

   dType   Type of logical unit. See stmfCreateLuResource(3STMF).

   prop    A property type value. See DESCRIPTION for valid values.

   propVal A property value.

DESCRIPTION
  Modify the properties of a logical unit device.

  Valid properties for modify STMF_DISK:
       STMF_LU_PROP_ALIAS
           Up to 255 characters representing a user defined name for the
           device.

           Default: set to file name of backing store

       STMF_LU_PROP_SIZE
           Numeric value w/optional suffix, e.g. 100G, 1T, to specify
           unit of size.

           Default: Size of device specified in the
                    STMF_LU_PROP_DATA_FILENAME property value.

       STMF_LU_PROP_WRITE_CACHE_DISABLE
           Write back cache disable. When specified as "true" or
           "false", specifies write back cache disable behavior.

           Default: Writeback cache setting of the backing
                    store device specified by
                    STMF_LU_PROP_DATA_FILENAME.

       STMF_LU_PROP_WRITE_PROTECT
           Write protect bit. When specified as "true" or "false",
           specifies whether the device behaves as a write protected
           device.

           Default: "false"

RETURN VALUES
   STMF_STATUS_SUCCESS         The API call was successful.

   STMF_ERROR_INVALID_ARG      Either prop or propVal is unrecognized.

   STMF_ERROR_INVALID_PROPSIZE The size of propVal is invalid.

   STMF_ERROR_NO_PROP          The value of prop is unknown for this
                               resource type.

ATTRIBUTES
   See attributes(5) for descriptions of the  following  attributes:

    ____________________________________________________________
   |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
   |_____________________________|_____________________________|
   | Interface Stability         | Committed                   |
   |_____________________________|_____________________________|
   | MT-Level                    | Safe                        |
   |_____________________________|_____________________________|


stmfGetLuResource
-----------------
NAME
   stmfGetLuResource - get a logical unit resource for a currently
                       registered logical unit.

SYNOPSIS
   cc [ flag... ] file... -lstmf [ library... ]
   #include <libstmf.h>

   int stmfGetLuResource(stmfGuid *luGuid, luResource *hdl)

PARAMETERS
   luGuid  guid of logical unit to retrieve

   hdl     The luResource hdl to create.

DESCRIPTION
   Retrieve a logical unit resource hdl for a given logical unit. luGuid
   must represent a currently registered stmf logical unit. This
   retrieved resource is a set of device specific properties for a
   logical unit device. This allocates an luResource hdl of device type
   matching luGuid. stmfFreeLuResource should be used when hdl is no
   longer needed.

RETURN VALUES
   STMF_STATUS_SUCCESS         The API call was successful.

   STMF_ERROR_NOT_FOUND        The guid does not exist.

ATTRIBUTES
   See attributes(5) for descriptions of the  following  attributes:

    ____________________________________________________________
   |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
   |_____________________________|_____________________________|
   | Interface Stability         | Committed                   |
   |_____________________________|_____________________________|
   | MT-Level                    | Safe                        |
   |_____________________________|_____________________________|


stmfFreeLuResource
------------------
NAME
   stmfFreeLuResource

SYNOPSIS
   cc [ flag... ] file... -lstmf [ library... ]
   #include <libstmf.h>

   int stmfFreeLuResource(luResource hdl)

PARAMETERS
   hdl     An luResource previously allocated in a call to
           stmfLuCreateResource or stmfLuGetResource.

DESCRIPTION
   This frees an allocated luResource that was allocated via
   stmfCreateLuResource or stmfGetLuResource.

RETURN VALUES
   STMF_STATUS_SUCCESS         The API call was successful.

   STMF_ERROR_INVALID_ARG      hdl is not a valid luResource hdl

ATTRIBUTES
   See attributes(5) for descriptions of the  following  attributes:

    ____________________________________________________________
   |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
   |_____________________________|_____________________________|
   | Interface Stability         | Committed                   |
   |_____________________________|_____________________________|
   | MT-Level                    | Safe                        |
   |_____________________________|_____________________________|


stmfSetPersistMethod
-------------------
NAME
   stmfSetPersistMethod - set persistence method for the stmf service

SYNOPSIS
   cc [ flag... ] file... -lstmf [ library... ]
   #include <libstmf.h>

   int stmfSetPersistMethod(uint8_t persistType, boolean_t serviceSet)

PARAMETERS
   persistType     The requested persistence setting. Can be one of:
                       STMF_PERSIST_SMF
                       STMF_PERSIST_NONE

   serviceSet      Set to indicate whether the setting should persist
                   on the stmf service. When set to B_FALSE, this
                   setting is only applicable for the duration of the
                   current library open or until a subsequent call is
                   made to change the setting.

DESCRIPTION
   This sets the persistence method for stmf.

RETURN VALUES
   STMF_STATUS_SUCCESS         The API call was successful.

   STMF_ERROR_PERSIST_TYPE     persistType is invalid.

ATTRIBUTES
   See attributes(5) for descriptions of the  following  attributes:

    ____________________________________________________________
   |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
   |_____________________________|_____________________________|
   | Interface Stability         | Committed                   |
   |_____________________________|_____________________________|
   | MT-Level                    | Safe                        |
   |_____________________________|_____________________________|


stmfGetPersistMethod
--------------------
NAME
   stmfGetPersistMethod - get the current persistence method for stmf

SYNOPSIS
   cc [ flag... ] file... -lstmf [ library... ]
   #include <libstmf.h>

   int stmfGetPersistMethod(uint8_t *persistType, boolean_t serviceState)

PARAMETERS
   persistType     On success, contains the current persistence setting
                   based on serviceState.

   serviceState    When set to B_TRUE, persistType will contain the
                   persist method currently set for the service. When
                   set to B_FALSE, persistType will contain the persist
                   method for the current library open.

DESCRIPTION
   Retrieves the current persistent method setting for the service or
   for a given library open. When set to B_TRUE, retrieves the setting
   from the service.

RETURN VALUES
   STMF_STATUS_SUCCESS         The API call was successful.

   STMF_ERROR_PERSIST_TYPE     Unable to retrieve persist type from
                               service.

ATTRIBUTES
   See attributes(5) for descriptions of the  following  attributes:

    ____________________________________________________________
   |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
   |_____________________________|_____________________________|
   | Interface Stability         | Committed                   |
   |_____________________________|_____________________________|
   | MT-Level                    | Safe                        |
   |_____________________________|_____________________________|




--
Mark A. Carlson
Sr. Architect

Systems Group
Phone x69559 / 303-223-6139
Email Mark.Carlson@Sun.COM

--Boundary_(ID_sRvSXiYfQMyguGAaO2Nwug)--