LSI cfg1030 Command-Line Utility Version 1.00.00 CONTENTS --------- 1.0 Overview 2.0 Change History 3.0 Functionality 4.0 Command-line Parameters 5.0 Commands 1.0 Overview: This file provides the information needed to use the linux version of the cfg1030 command-line program. 1.1 Overview about this code The cfg1030 command-line program is a utility that can configure and manage LSI53C1020/1030 integrated SCSI controllers. 1.2 Limitations - The mptctl driver must be loaded to use this program. If the program complains about it not being loaded, type "modprobe mptctl" at a shell prompt. You can then type "lsmod" and check the information displayed to verify mptctl was loaded. - The user must be careful when specifying hot spare drives. Hot spare drives must have a capacity greater than the capacity of the smallest disk in the logical drive. - If you create a hot spare disk before creating a logical drive, the hot spare will not be identified as such by the getconfig command. Once the logical drive has been created, getconfig will identify the hot spare disk correctly. This is a limitation of the controller firmware. To avoid problems, create the logical drive first and then the hot spare. - If a disk that is part of a logical drive is pulled or fails, the getconfig command will fail when trying to display the physical hard disk information for the logical drive. When this happens you can display the physical device information by using the "pd" option. Which physical devices make up the logical drive can be inferred from this information. - If you migrate a logical drive from one controller to a controller that has an existing logical drive, cfg1030 does not have a means of displaying the fact that the controller has deactivated one of the logical drives. The best workaround is to avoid migrating logical drives to a controller that already has a logical drive. 1.3 Enhancements None 1.4 Level of Recommendations and Prerequisites for the Update: None 1.5 Dependencies: - The mptctl driver must be loaded to use this program. If the program complains about it not being loaded, type "modprobe mptctl" at a shell prompt. You can then type "lsmod" and check the information displayed to verify mptctl was loaded. 2.0 Change History -------------------- 1.00.00 - Initial Release 3.0 Functionality ------------------- You configure the program by entering a command word followed by command specific parameters on the command line. The following commands shall be implemented by the program: · BACKUP · CREATE LOGICALDRIVE · GETCONFIG · GETSTATUS · LLFORMAT · RESTORE · SETCONFIG · SETSTATE When typing in a command line, commands and parameters may be uppercase, lowercase, or a mixture of the two. The program shall be case insensitive. The following conventions are used in the command descriptions: · Text in italics is entered exactly as shown on the command line. · Text surrounded by <> must be replaced with a required parameter. · Text surrounded by [] may be replaced by an optional parameter. · Parameters surrounded by {} must be entered one or more times as is appropriate for the command being executed. 4.0 Command-line Parameters ----------------------------- This section describes command line parameters that are common to more than one command. 4.1 Description A unique controller number is assigned by the program to each PCI function found in the system. Only PCI functions on controller chips recognized by this program are assigned numbers (see section 4.1). Because of the current design of LSI Logic’s MPT firmware for SCSI controllers, there is a one-to-one mapping between PCI functions and SCSI busses. Therefore this number can be used to address a particular SCSI bus in the system. For example: an LSI53C1030 dual SCSI bus chip will have two controller numbers assigned to it, an LSI53C1020 single SCSI bus chip will have one controller number assigned to it. The following algorithm shall be used to assign controller numbers: 1. Create a list of all supported controllers found in the system. 2. Sort the list based on PCI bus, device, and function numbers; the list shall be sorted in ascending order. 3. The first controller in the list will be assigned controller number 1; the next shall be assigned controller number 2; and so on and so forth until all controllers have had numbers assigned. Valid Values Decimal 1 to 255. 4.2 Description The channel number is the same as the SCSI bus number. The LSI53C1020/1030 controllers only have one channel. Therefore this number is always the same. Valid Values Decimal 1. 4.3 Description The identification number on the SCSI bus to which the disk drive will respond to when the host attempts a target selection. Valid Values Decimal 0 to 15. 5.0 Commands -------------- 5.1 BACKUP Command Description This command saves the configuration settings for the controller in a file. These settings can be restored to the same or an identically configured controller using the restore command. Only the backup configuration and settings variant of this command are implemented. The backup BIOS and firmware variants can be performed using the LSI Logic flsh1030 utility. Command Line cfg1030 backup [noprompt] Parameters Number of controller targeted by this command. Path and filename of file to store configuration data in; path is optional. noprompt Option ignored. Program Return Value 0x00 SUCCESS: command completed successfully. 0x01 FAILURE: command failed. 0xFE FILE_ERROR: error occurred while writing the configuration file. 0xFF BAD_PATH: path name was bad. 5.2 CREATE LOGICALDRIVE Command Description This command allows the user to create logical drives or RAID volumes on the LSI53C1020/1030 controllers. Firmware and hardware limitations for this family of controllers limit the number of configurations that are possible. Once a disk has been added to a logical drive, all of its storage capacity may or may not be used depending on drive capacity and logical drive capacity. For example, if you add a 36GB disk drive to a logical drive that only uses 9GB of capacity on each disk drive, the remaining 27GB of capacity on the disk drive is unusable. The disk identified by the first channel #/SCSI ID pair on the command line will be assigned as the primary disk drive when creating a RAID 1 logical drive. If the controller is allowed to resync the disk drives, the data on the primary disk drive will be accessible by accessing the newly created logical drive. The following rules must be observed when creating logical drives and hot spare disks: 1. all disks that are part of a logical drive or a hot spares for a logical drive must be on the same channel or SCSI bus, 2. only RAID level 1 is supported, 3. only one logical drive per controller can be created, 4. the total number of disks in logical drives and hot spares disks cannot exceed six, 5. a RAID level 1 volume must have exactly two disks, Command Line cfg1030 create logicaldrive newarray { } [qsync] Parameters Number of SCSI bus targeted by this command. logicaldrive Required command line parameter. newarray Required command line parameter. Size of the RAID volume in Mbytes or "MAX" for the maximum size available. RAID level for the volume to be created. Valid values is 1. This parameter must be one (1). SCSI ID of a hard disk drive to be included in the RAID volume. qsync An optional parameter, if specified means that the volume created will be quick synchronized as opposed to long synchronized, and applies for 2 drive volumes. The first 32K of the drives in the volume will be cleared to 0. Program Return Value 0x00 SUCCESS: command completed successfully. 0x01 FAILURE: bad command line arguments or operational failure. 5.3 GETCONFIG Command Description The getconfig command displays information about LSI53C1020/1030 controller configurations. The information displayed includes controller type, firmware version, BIOS version, logical drive/RAID volume information, and physical drive information. An example of the information that will be output by this command is provided below. One MB is 1024 * 1024 bytes. All sizes that are displayed in MB are rounded down to the nearest MB. Logical drive status values are as follows: · Okay (OKY) - Drives are functioning properly and user data is protected if the current RAID level provides data protection. · Degraded (DGD) - The user’s data is not fully protected due to a configuration change or drive failure; a data resync or rebuild may be in progress. Physical device status values are as follows: · Online (ONL) - The drive is operational and is part of a logical drive. · Hot Spare (HSP) - The drive is a hot spare that is available for replacing a failed drive in an array. · Ready (RDY) - The drive is ready for use as a normal disk drive or it can be but has not been assigned to a disk array or hot spare pool. · Available (AVL) - The hard disk drive may or may not be ready, and it is not suitable for inclusion in an array or hot spare pool (i.e., it is not spun up, its block size is incorrect, or its media is removable). · Failed (FLD) - Drive was part of a logical drive or was a hot spare drive, and it failed. It has been taken offline. · Standby (SBY) - This status is used to tag all non-hard disk devices. Command Line cfg1030 getconfig [] Parameters Number of SCSI bus targeted by this command. Option that indicates what information is to be returned. See options below. Program Return Value 0x00 SUCCESS: command completed successfully. 0x01 FAILURE: bad command line arguments or operational failure. Options AD Controller information only. LD Logical drive (RAID volume) information only. PD Physical drive information only. AL All information (default). Sample Output: Read configuration has been initiated for controller 1 -------------------------------------------------------------------------- Controller information -------------------------------------------------------------------------- Controller type : LSI53C1020/1030 BIOS version : 5.02.03.00 Firmware version : 0.01.00.12 SCSI channel description : 1 parallel SCSI wide Initiator IDs (Channel/SCSI ID) : 1/7 Maximum physical devices : 15 Concurrent commands supported : 222 -------------------------------------------------------------------------- Logical drive information -------------------------------------------------------------------------- Logical drive number 1 Status of logical drive : Okay (OKY) RAID level : 1 Size (in MB) : 9015 Physical hard disks (Channel/SCSI ID) : 1/8 1/9 -------------------------------------------------------------------------- Physical device information -------------------------------------------------------------------------- Channel #1 Initiator at SCSI ID 7 Target on SCSI ID 0 Device is a Hard disk SCSI ID : 0 State : Ready (RDY) Size (in MB)/(in sectors) : 9015/18462720 Device ID : QUANTUM ATLAS 10K 9WLS UCH0 Target on SCSI ID 8 Device is a Hard disk SCSI ID : 8 State : Online (ONL) Size (in MB)/(in sectors) : 9015/18462720 Device ID : QUANTUM ATLAS 10K 9WLS UCH0 Target on SCSI ID 9 Device is a Hard disk SCSI ID : 9 State : Online (ONL) Size (in MB)/(in sectors) : 9015/18462720 Device ID : QUANTUM ATLAS 10K 9WLS UCH0 Target on SCSI ID 10 Device is a Hard disk SCSI ID : 10 State : Available (AVL) Size (in MB)/(in sectors) : 9015/18462720 Device ID : QUANTUM ATLAS 10K 9WLS UCH0 Target on SCSI ID 15 Device is a Processor device SCSI ID : 15 State : Standby (SBY) Device ID : LSI 53C040 0400 5.4 GETSTATUS Command Description The GETSTATUS command displays the status of any logical drive synchronization operation that is currently in progress on the controller. If none is in progress, cfg1030 will print a message indicating so before exiting. Command Line cfg1030 getstatus Parameters Number of controller targeted by this command. Program Return Value 0x00 SUCCESS: command completed successfully. 0x01 FAILURE: command failed. Sample Output Example of the status information returned when a drive resynchronization is in progress: Background command progress status for controller 1... Current operation : Synchronize Logical drive in progress : 1 Volume status : Enabled Volume state : Degraded Physical disk I/Os : Not quiesced Logical drive size (in sectors) : 370642 Number of remaining sectors : 188326 Percentage complete : 49.19% Example of the status information returned when no background logical drive operation is in progress: Background command progress status for controller 1... Current operation : None Logical drive in progress : 1 Volume status : Enabled Volume state : Optimal Physical disk I/Os : Not quiesced The status fields in the data displayed can take on the following values: Current operation - Synchronize or None Volume status - Enabled or Disabled Volume state - Optimal, Degraded or Failed Physical disk I/Os - Quiesced or Not quiesced 5.5 LLFORMAT Command Description The llformat command allows the user to perform a low-level format of a disk drive. This operation can only be performed on a hard disk drive. The drive cannot be a logical drive or a hot spare drive. Performing a low-level format on a hard disk drive will result in the destruction of all data stored on that disk drive. The operation cannot and should not be interrupted; doing so may result in irreparable damage to the hard disk drive. Unlike other commands supported by this utility, the noprompt option is not only tolerated but it is also honored. Unless the noprompt option is included on the command line, warning messages will be displayed. The user will be required to properly answer a series of prompts or the command will be aborted. The answers are case sensitive and must be entered in upper case. This command will not complete and return to a shell prompt until the format operation is complete. Depending on the capacity and model of disk drive, this can take a considerable amount of time. Command Line cfg1030 llformat [noprompt] Parameters Number of controller targeted by this command. This parameter must be one (1). SCSI ID of a hard disk drive to be included in the RAID volume [noprompt] If this optional parameter is entered the program will forgo displaying warning messages and user prompts. Program Return Value 0x00 SUCCESS: command completed successfully. 0x01 FAILURE: command failed. 5.6 RESTORE Command Description The restore command allows the user to configure a controller using configuration data and settings stored in a file. This file must be created using the backup command (see section 7.6.1). The hardware configuration including disk drives must be identical to the configuration on which the backup command was run. The following configuration items will be verified before the restoration of the configuration is performed: · Firmware version · Product ID as reported by the firmware · Port type (i.e., parallel SCSI) · Number of controller I/O ports (i.e., SCSI buses) · Maximum devices supported · PCI vendor ID of the controller · PCI device ID of the controller · Drive configuration Drive configuration verification rules are fairly relaxed. Only those drives that are part of a logical drive are checked. The drives must have the same SCSI Ids and their capacity must be exactly as indicated in the configuration file. WARNING: Different versions of drive firmware may return a different capacities for a given disk drive. In this case, the configuration check will fail and the restore cannot be performed. Command Line cfg1030 restore [noprompt] [qsync] Parameters Number of controller chip targeted by this command. Path and filename of file to store configuration data in; path is optional. noprompt Option ignored. qsync If the restore operation creates a RAID level 1 volume you can prevent resyncing using this option. Program Return Value 0x00 SUCCESS: command completed successfully. 0x01 FAILURE: command failed. 0xFE FILE_ERROR: error occurred while writing the configuration file. 0xFF BAD_PATH: path name was bad. 5.7 SETCONFIG Command Description This command will delete any logical drives and hot spare drives created by the create and setstate commands. No other controller configuration parameters will be changed. This will prevent configuration changes that might prevent the controller from functioning properly in the host system. Only the DEFAULT variant of this command is implemented in this program. You must include the DEFAULT option on the command line or the program will exit with a return value of FAILURE. The NOPROMPT option may be specified but it is ignored. Command Line cfg1030 setconfig default [noprompt] Parameters Number of SCSI bus targeted by this command. default Set the factory default settings. noprompt Do not alert user to potential risk of using this command. Program Return Value 0x00 SUCCESS: command completed successfully. 0x01 FAILURE: bad command line arguments or operational failure. 5.8 SETSTATE Command Description This command will set the drive state to the parameter value. The hot spare option is the only supported state. The hot spare drive will be added to hot spare pool 0. The number of disk drives in a logical drive plus the hot spare disk cannot exceed six. Only one hot spare disk can be created. The user must make sure the capacity of the hot spare disk is greater than or equal to the capacity of the smallest disk in the logical drive. An easy way to verify this is to use the getconfig command. Command Line cfg1030 setstate Parameters Number of SCSI bus targeted by this command. Must be set to one (1). SCSI target ID of drive targeted by this command. State to which the target device is to transition. See the state values below. Program Return Value 0x00 SUCCESS: command completed successfully. 0x01 FAILURE: bad command line arguments or operational failure. State Values HSP Hot spare