1. Introduction 1.1. Project/Component Working Name: RaidCfg GUID and volume activation support 1.2. Name of Document Author/Supplier: Author: jie.cao@sun.com 1.3 Date of This Document: Jul 7th, 2008 4. Technical Description 4.1 Summary The raidctl utility is a RAID configuration tool for mpt controllers in Solaris; however, it needs to be enhanced when the mpt-mpxio feature is enabled. The reason is that the mpt controller can only deal with the target id with RAID management commands; but accessible disks are represented using GUID when mpt-mpxio is enabled. Considering that there's no 1-1 mapping method between the GUID and target id, raidctl should provide the GUID information so that user can figure out the disk target id. Meanwhile, for mpt controllers, volume can be in an inactive state and in this case no RAID config action can be conducted. The raidctl utility needs to be enhanced to detect volume inactive status and to include volume activation capability. 4.2 Proposal The GUID is a property for a physical disk. Presently raidctl utility can display detailed information for a physical disk, including the target id, but not GUID info. The solution is to add the GUID information to the disk information output so user can determine both the target id and GUID for a given disk; thus the user can use the corresponding target id for further RAID management actions. Accordingly, a new Property object (to hold GUID information) will be introduced into the RaidCfg software. Each Property object will only associate with a single disk object as a component and its attribute is defined as follows: typedef struct { uint32_t prop_id; uint32_t prop_size; property_type_t prop_type; char prop[1]; } property_attr_t; prop_id: A unique id number within a controller. It's used to address the property object. prop_size: Length of buffer specified by the 'prop' field. prop_type: Specifying what kind of information in buffer 'prop'. Currently can only be PROP_GUID. prop: Buffer used to store property information. The GUID information is generated by physical disk devices so each layer of RaidCfg software will include some adjustment to meet this requirement. All interfaces including CLI, API and SPI will be enhanced with backward compatibilities, to provide features to address the property objects and to query the corresponding attributes. And for the volume activation issue, a new flag will be introduced into the 'state' field of array object attribute (see section 3.2.3 in RaidCfg design doc version 1.1 [1]) to represent the array's activating status. When bit 31 of the 'state' field is 1, the volume is in inactive state. Bit 16 to bit 30 are reserved. Bit 0 to bit 15 remains unchanged. The API function raidcfg_set_attr() and SPI function rdcfg_set_attr() will be enhanced to provide volume-activation feature. 4.3 Interface Summary RaidCfg CLI interface: Remains as Evolving. GUID information output had been added to disk information display in a compatible format. And for a given volume, if it's in inactive state, array information display output will show this status. See accompanied diff file for the raidctl manpage. RaidCfg API interface: Remains as project-private. The following API routines will be enhanced with backward compatibility: (1) int raidcfg_get_type(int obj_handle) Constant OBJ_TYPE_PROP had been added to return value range; (2) int raidcfg_list_head(int obj_handle, raid_obj_type_id_t type) Constant OBJ_TYPE_PROP had been added to value range of parameter 'type'. (3) int raidcfg_get_attr(int obj_handle, void *attr) This function will be enhanced with the capability to query attributes for a Property object (presently only for GUID information). In this case 'attr' must point to a structure of type raidcfg_prop_t, defined as follows: typedef property_attr_t raidcfg_prop_t; Note that if 'prop_size' filed is 0, this function will fill this field with required length of buffer 'prop' to store the property information (hereby the GUID, as a string); otherwise 'prop' will be filled with the property information. (4) int raidcfg_set_attr(int obj_handle, uint32_t set_cmd, void *value, char **err_str) This function will be enhanced with the capability to activate a volume. In this case 'obj_handle' should contain the array object handle, 'set_cmd' should be SET_ACTIVATION_PLY and 'value' should point to a value of ARRAY_ACT_ACTIVATE. RaidCfg SPI interface: Remains as project-private. The following SPI routines will be enhanced with backward compatibility: (1) int rdcfg_compnum(uint32_t controller_id, uint32_t container_id, raid_obj_type_id_t container_type, raid_obj_type_id_t component_type) A new combination of parameters of 'container_type' and 'component_type' will be added, as follows: container_type component_type ====================================================== RAID_OBJ_TYPE_DISK RAID_OBJ_TYPE_PROP This combination will be used to query for the number of Property object for a given disk. (2) int rdcfg_complist(uint32_t controller_id, uint32_t container_id, raid_obj_type_id_t container_type, raid_obj_type_id_t comp_type, int comp_num, uint32_t *ids) A new combination of parameters of 'container_type' and 'component_type' is added, as follows: container_type component_type ====================================================== RAID_OBJ_TYPE_DISK RAID_OBJ_TYPE_PROP This combination will be used to query for Property object ids for a given disk. (3) int rdcfg_get_attr(uint32_t controller_id, uint32_t device_id, uint32_t index_id, raid_obj_type_id_t type, void *attr) A new combination of parameters of 'type', 'device_id' and 'index_id' will be added, as follows: type device_id index_id ======================================================== RAID_OBJ_TYPE_PROP disk_id prop_id Buffer pointed by 'attr' will contain a structure of type 'property_attr_t', which is defined as follows: typedef struct { uint32_t prop_id; uint32_t prop_size; property_type_t prop_type; char prop[1]; } property_attr_t; Since presently the Property object can only hold the GUID information, rdcfg_get_attr() should always fill 'prop_type' with constant PROP_GUID; and 'prop_size' stands for the length of 'prop'. If 'prop_size' is 0, rdcfg_get_attr() should fill it with length of the GUID information (in bytes) and return SUCCESS; otherwise rdcfg_get_attr() should put the GUID information into buffer 'prop' and return SUCCESS. (4) int rdcfg_set_attr(uint32_t controller_id, uint32_t device_id, uint32_t cmd, uint32_t *value, char **err_ptr) A new combination of parameters of 'device_id', 'cmd' and 'value' will be added, as follows: device_id cmd *value ============================================================= array_id SET_ACTIVATION_PLY ARRAY_ACT_ACTIVATE This combination will be used to activate the volume in question. 4.4 References [1] PSARC/2005/204 RaidCfg project [2] PSARC/2006/663 RaidCfg MPT adjustment [3] PSARC/2007/667 RaidCfg disk_id adjustment [4] Manpage of raidctl(1M) 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