page 1 of 14 Date: March 8, 1988 X3T9.2/88-006R2 Revised: May 16, 1988 Revised: July 11, 1988 To: X3T9.2 Committee (SCSI) From: James McGrath (Quantum) Subject: LOG SELECT and LOG SENSE commands FIRST REVISION: This is the first revision of the LOG SELECT/SENSE proposal. It incorporates the input of the May working group session. This proposal does not cover the form of counters, or their content (this is an issue Bill Spence will be addressing). SECOND REVISION: This is the second revision of the LOG SELECT/SENSE proposal. It incorporates the input of the June plennary group session. Specifically, more attention is paid to the issue of non-savable parameters and the form of parameters (counters and lists). The architecture of the proposal does not differ from that of the first revision. Some additional clarifications, drawn from the MODE SELECT/SENSE sections, in introduced. Note that old wording that has been dropped is enclosed in "[[", "]]", while new wording that has been added is enclosed in "<<", ">>". X.Y LOG SELECT Command <> page 2 of 14 Table X.Y-1: LOG SELECT CDB ====================================================================== Bit| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | Byte | | | | | | | | | ====================================================================== 0 | Operation Code (TBD) | -----|---------------------------------------------------------------| 1 | Logical Unit Number | Reserved | SP | -----|---------------------------------------------------------------| 2 | PC | Reserved | -----|---------------------------------------------------------------| 3 | Reserved | -----|---------------------------------------------------------------| 4 | Reserved | -----|---------------------------------------------------------------| 5 | Reserved | -----|---------------------------------------------------------------| 6 | Reserved | -----|---------------------------------------------------------------| 7 | (MSB) | -----|--- Parameter List Length ---| 8 | (LSB) | -----|---------------------------------------------------------------| 9 | Control Byte | ====================================================================== The LOG SELECT command provides a means for the initiator to manage statistical information maintained by the device about the device or attached logical units. <> <> <> <> page 3 of 14 X.Y.1 CDB Fields [[A save parameters (SP) bit of zero indicates the target shall perform the specified LOG SELECT operation, and may or may not save any parameters. A SP bit of one indicates that the target shall perform the specified LOG SELECT operation, and shall save all savable parameters to a non-volatile vendor specific location including any sent during the DATA OUT phase.]] <> <> <> The page control (PC) field defines the type of parameter values to be selected. The page control field is defined in Table X.Y-2. See section X.Y.2 for an explanation of the types of parameter values. Table X.Y-2: Page Control Field ====================================================================== Bit 7 Bit 6 Type of Parameter Values ----- ----- ------------------------ 0 0 Threshold Values 0 1 Cumulative Values 1 0 Reserved 1 1 Reserved ====================================================================== <> page 4 of 14 If multiple pages are sent during this DATA OUT phase then they shall be sent in ascending order according to page code. If multiple parameters within a page are sent during this DATA OUT phase then they shall be sent in ascending order according to parameter code. A parameter list length that results in the truncation of any page header or parameter shall cause the target to terminate the command with CHECK CONDITION status. The sense key shall be set to ILLEGAL REQUEST, and the additional sense code shall be set to INVALID FIELD IN COMMAND DESCRIPTOR BLOCK. X.Y.2 Type of Parameter Values The LOG SELECT command supports two types of parameter values for each log parameter. The cumulative value is updated by the target to reflect the cumulative record of events experienced by the target. It may also be updated by the initiator via the LOG SELECT command. IMPLEMENTOR'S NOTE: updating the cumulative parameters via the LOG SELECT command may be used to reset the parameter value to a default state (e.g. zero). The default cumulative value, read by the initiator using the LOG SENSE command, provides the default values suggested by the target manufacturer. The updating and saving of cumulative parameters may be controlled by bits set in the parameter control byte (see section X.Y-5). The threshold value can only be modified by the initiator via the LOG SELECT command. When cumulative values are updated, they are compared to the threshold values. When the threshold has been met, the target shall indicate this by posting to all initiators an UNIT ATTENTION condition, with the additional sense code set to THRESHOLD CONDITION MET. Those targets that support the AEN protocol may use it instead of posting an UNIT ATTENTION condition. If the <> threshold values are not available or not implemented for the parameter the LOG SELECT command shall be terminated with CHECK CONDITION status with the sense key set to ILLEGAL REQUEST and the additional sense code set to THRESHOLD PARAMETERS NOT SUPPORTED. The saving of threshold parameters and the criteria for the threshold being met may be controlled by bits set in the parameter control byte (see section X.Y-5). X.Y.3 Page Structure The format of the LOG SELECT/SENSE data consists of zero or more variable-length pages. Each page starts with a 4-byte page header followed by one or more variable-length parameters associated with that page. The 4-byte header is illustrated in <>[[Figure]] X.Y-3. page 5 of 14 Table X.Y-3: SELECT LOG Page Structure ====================================================================== Bit| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | Byte | | | | | | | | | ====================================================================== 0 | <>[[Reserved]] | -----|---------------------------------------------------------------| 1 | <>[[PAGE Code (__h)]] | -----|---------------------------------------------------------------| 2 | (MSB) | -----|--- Page Length (n) ---| 3 | (LSB) | -----|---------------------------------------------------------------| 4 | | - - -|- - Page-Specific Parameters - -| n + 3| | ====================================================================== The page code field identifies which page of data is being transferred. If the page code value is reserved or not implemented by the target, then the target shall terminate the command with a CHECK CONDITION status. The sense key shall be set to ILLEGAL REQUEST, and the additional sense code shall be set to INVALID FIELD IN PARAMETER LIST. The page parameter length field defines the length, in bytes, of the page-specific parameters. This length does not include bytes zero through three. A page parameter length value that results in the truncation of any [[or]] parameter shall cause the target to terminate the command with CHECK CONDITION status. The sense key shall be set to ILLEGAL REQUEST, and the additional sense code shall be set to INVALID FIELD IN COMMAND DESCRIPTOR BLOCK. The page-specific parameters are defined within the appropriate page definitions <>. X.Y.4 Parameter Structure The format of the LOG SELECT/SENSE pages consists of zero or more variable-length parameters. Each parameter starts with a 4-byte parameter header followed by one or more bytes of parameter value for that parameter. The 4-byte header is illustrated in <
> [[Figure]] X.Y-4. page 6 of 14 Table X.Y-4: SELECT LOG Parameter Structure ====================================================================== Bit| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | Byte | | | | | | | | | ====================================================================== 0 | (MSB) | -----|--- Parameter Code (p) ---| 1 | (LSB) | -----|---------------------------------------------------------------| 2 | Parameter Control Byte | -----|---------------------------------------------------------------| 3 | Parameter Length (n) | -----|---------------------------------------------------------------| 4 | | - - -|- - Parameter Value Bytes - -| n + 3| | ====================================================================== The parameter code field identifies which parameter of data is being transferred. If the parameter code value is reserved or not implemented by the target, then the target shall terminate the command with a CHECK CONDITION status. The sense key shall be set to ILLEGAL REQUEST, and the additional sense code shall be set to INVALID FIELD IN PARAMETER LIST. The parameter control byte contains bits and fields that control how the target and initiator use the parameter. See section X.Y.5 for an explanation of these fields. The parameter length field defines the length, in bytes, of the parameter value. This length does not include bytes zero through three. A parameter length value that results in the truncation of the parameter shall cause the target to terminate the command with CHECK CONDITION status. The sense key shall be set to ILLEGAL REQUEST, and the additional sense code shall be set to INVALID FIELD IN PARAMETER LIST. <> <<(1) round the value to an acceptable value and terminate the command as described in section 6._._.>> <<(2) terminate the command with CHECK CONDITION status, the sense key set to ILLEGAL REQUEST, and the additional sense code set to Invalid Field In Parameter List.>> The meaning of the parameter values are defined within the appropriate parameter definitions <>. page 7 of 14 X.Y.5 Parameter Control Byte The parameter control byte is part of the parameter header, and controls the manner in which the cumulative parameter values are updated, saved, and compared to the threshold parameter values. It also indicates the type of parameter (e.g. counter). Table X.Y-5: SELECT LOG Parameter Control Byte ====================================================================== Bit| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | ====================================================================== | DU | DS | ET | Operation |Reserved| FP | ====================================================================== A disable update (DU) bit of zero indicates that the target shall update the cumulative parameter value to reflect all of the events that should be noted by that parameter. This update operation may use volatile memory, and thus the value is not guaranteed to survive a power cycle. A DU bit of one indicates that the target shall not update the cumulative parameter value except in response to a LOG SELECT command. The DU bit is ignored for the threshold parameter value. [[A disable save (DS) bit of zero indicates that the target shall save, at vendor specific times, the cumulative or threshold parameter value to a non-volatile vendor specific location. This implicit saving operation shall be done frequently enough to insure that the cumulative parameter values retain statistical significance across power cycles.]] <> [[A DS bit of one indicates that the target shall only save the cumulative or threshold parameter value to a non-volatile vendor specific location in response to a LOG SELECT command with the SP bit set.]] <> page 8 of 14 An enable threshold (ET) bit of zero indicates that the cumulative parameter value is never compared to the threshold parameter value. An ET bit of one indicates that when the cumulative parameter value is updated, it is compared to the threshold parameter value. Setting the ET <> to a certain <>[[option]] for either the cumulative or threshold parameter [[value]] forces the target to set the ET bit of the other parameter [[value]] to that same <>[[option]]. The operation field is a control variable. It defines the binary relationship between the cumulative and threshold parameter values under which the threshold is met. When the threshold is met, then a UNIT ATTENTION condition shall be posted to all initiators, with an additional sense code THRESHOLD CONDITION MET. <> {Still unresolved in how to terminate the condition met status, since resetting the parameter value on read to its default value both violates the concept of a cumulative value and does not work well in a multiple initiator environment.} Table X.Y-6: Threshold Met Criteria ====================================================================== Bit 4 Bit 3 Threshold Met Criteria ----- ----- ------------------------ 0 0 any update of parameter 0 1 cumulative = threshold [[1 0 cumulative > threshold]] <<1 0 cumulative <> threshold>> 1 1 cumulative >= threshold ====================================================================== Setting the operation field to a certain criteria for either the cumulative or threshold parameter [[value]] forces the target to set the operation field of the other parameter [[value]] to that same criteria. The form of parameter (FP) bit shall be ignored. page 9 of 14 X.Z LOG SENSE Command <> Table X.Z-1: LOG SENSE CDB ====================================================================== Bit| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | Byte | | | | | | | | | ====================================================================== 0 | Operation Code (TBD) | -----|---------------------------------------------------------------| 1 | Logical Unit Number | Reserved | SP | -----|---------------------------------------------------------------| 2 | PC | Page Code (__h) | -----|---------------------------------------------------------------| 3 | Reserved | -----|---------------------------------------------------------------| 4 | Reserved | -----|---------------------------------------------------------------| 5 | Reserved | -----|---------------------------------------------------------------| 6 | Reserved | -----|---------------------------------------------------------------| 7 | (MSB) | -----|--- Allocation Length ---| 8 | (LSB) | -----|---------------------------------------------------------------| 9 | Control Byte | ====================================================================== The LOG SENSE command provides a means for the initiator to retrieve statistical information maintained by the device about the device or attached logical units. It is a complementary command to the LOG SELECT command. X.Z.1 CDB Fields [[A save parameters (SP) bit of zero indicates the target shall perform the specified LOG SENSE operation, and may or may not save any parameters. A SP bit of one indicates that the target shall perform the specified LOG SENSE operation, and shall save all savable parameters to a non-volatile vendor specific location.]] [[The target is expected to save, at vendor specific times, the savable parameters to this non-volatile vendor specific location. This implicit saving operation shall be done frequently enough to insure that the parameter values retain statistical significance across power cycles.]] page 10 of 14 <> <> <> The page control (PC) field defines the type of parameter values to be selected. The page control field is defined in Table X.Z-2. Table X.Z-2: Page Control Field ====================================================================== Bit 7 Bit 6 Type of Parameter Values ----- ----- ------------------------ 0 0 Threshold Values 0 1 Cumulative Values 1 0 Default Threshold Values 1 1 Default Cumulative Values ====================================================================== The allocation length field specifies the number of bytes that the initiator has allocated for returned LOG SENSE data. An allocation length of zero indicates that no LOG SENSE data shall be transferred. This condition shall not be considered as an error. Any other value indicates the maximum number of bytes that shall be transferred. The target shall terminate the DATA IN phase when allocation length bytes have been transferred or when all available LOG SENSE data have been transferred to the initiator, whichever is less. <> <> page 11 of 14 X.Z.2 Type of Parameter Values The LOG SENSE command supports four types of parameter values for each log parameter. The cumulative and threshold parameter values are the same as those defined for the LOG SELECT command (see section X.Y.2). Note that the cumulative parameter values returned are: 1) The values since the last update (done by either the target or in response to a LOG SELECT or LOG SENSE command). 2) The saved values if an update has not occurred since the last power-on RESET condition and saved parameters are implemented. 3) The default values if an update has not occurred since the last power-on RESET condition and saved parameters values are not available or not implemented. The threshold parameter values returned are: 1) The values since the last update via a successful LOG SELECT command. 2) The saved values if an update has not occurred since the last power-on RESET condition and saved parameters are implemented. 3) The default values if an update has not occurred since the last power-on RESET condition and saved parameters values are not available or not implemented. The default cumulative parameter values are provided to the initiator by the target so that the cumulative parameters may be reset to a default condition by a LOG SELECT command after executing a LOG SENSE command. The default threshold parameter values are provided to the initiator by the target so that the threshold parameters may be reset to a vendor specific condition by a LOG SELECT command after executing a LOG SENSE command. IMPLEMENTOR'S NOTE: this vendor specific condition usually indicates a reasonable level at which a threshold met condition should be detected, and the initiator notified to do a LOG SENSE. For example, if the parameter tracks an error rate, then the default value for this parameter might be the specified rate, or the specified rate plus some variance. X.Z.3 Page Structure The page structure is the same as that defined for the LOG SELECT command (see section X.Y.3). page 12 of 14 X.Z.4 Parameter Structure The parameter structure is the same as that defined for the LOG SELECT command (see section X.Y.4). X.Z.5 Parameter Control Byte The parameter control byte is the same as that defined for the LOG SELECT command (see section X.Y.5) for the cumulative and threshold parameter values. For the default cumulative and threshold parameter values, the value of the DU bit indicates the target's default updating option of the cumulative parameter values. For the default cumulative and threshold parameter values, a DS bit of zero indicates that the saving of the corresponding parameter value is implemented by the target, while a bit of one indicates that the saving of the corresponding parameter value is not implemented by the target. For the default cumulative and threshold parameter values, an ET bit of zero indicates that the threshold function is not supported for this parameter, while a bit of one indicates that the threshold function is supported for this parameter. The same value of the ET bit is returned for both the default cumulative and default threshold parameter values. For the default cumulative and threshold parameter values, the operation field indicates the target's default threshold condition met criteria. The same criteria is returned for both the default cumulative and default threshold parameter values. A form of parameter (FP) bit of zero indicates that the parameter is a counter. A FP bit of one indicates that the parameter is a list of non-counter values. The same value of the FP bit is returned for all parameter types. <> <> <> page 13 of 14 <> <> <> <> <<{There is a problem here in that two LOG SENSE commands are required to read the page - the first for the data counter values to determine the number of list parameters, the second for the list parameters. In addition, all the list parameters must be read if the one with the highest parameter code is desired. The first problem can be partially solved by including a bit in the CDB to disable the sending of supported parameter values that have never been updated from the default state. The second can be solved by defining a new two byte parameter in the CDB indicating the starting parameter code value for the data transfer.}>> <> <> page 14 of 14 <
> << ====================================================================== Bit| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | Byte | | | | | | | | | ====================================================================== 0 | Reserved | Page Code (00h) | -----|---------------------------------------------------------------| 1 | Reserved | -----|---------------------------------------------------------------| 2 | (MSB) | -----|--- Page Parameter Length ---| 3 | (LSB) | -----|---------------------------------------------------------------| 4 | First supported page number | - - -|- - - -| n + 4| Last supported page number | ====================================================================== >> <> <> <> <<{This page may want to appear in another section.}>>