NOTE: Copies of this document may be purchased from: X3T9/90-122 Global Engineering Documents, 2805 McGaw, Irvine, CA 92714 X3T9.2/90-165 (800) 854-7179 or (714) 261-1455. SCSI Information Bulletin #1 Procedures for Logging Operations in SCSI-2 October 19, 1990 Abstract: This document provides guidance in the use of the LOG SELECT and LOG SENSE commands contained in American National Standard X3.131-1990, Small Computer System Interface-2 (SCSI-2). This document does not replace the descriptions in SCSI-2 and is not intended to conflict with SCSI-2. The purpose of this document is to provide more information to gain a more uniform implementation of the SCSI-2 logging functions. NOTICE Recognizing the need for a uniform approach to the responsibility for disseminating interpretations to approved American National Standards, the Accredited National Standards Committee X3 - Information Processing Systems has authorized the publication of Technical Information Bulletins. This Technical Information Bulletin is issued in response to questions which have been raised regarding certain specifications in the content of: X3.131-1990, American National Standard Small Computer System Interface-2 (SCSI-2). This Bulletin was prepared by Technical Committee X3T9, which developed that standard and was authorized for release by Committee X3 in order to provide interpretations as quickly as possible in response to questions raised. This Bulletin, while reflecting the technical opinion of the Technical Committee which developed the standard, is intended solely as supplementary information to other users of the standard. That standard, ANS X3.131-1990, as approved through the publication and voting procedures of the American National Standards Institute, is not altered by this Bulletin. Any subsequent revision to the standard, ANS X3.131-1990, may or may not reflect the contents of this Technical Information Bulletin. Glossary List Parameter - A Parameter Value which consists of a string of ASCII graphic codes Log Page - A page made up of one or more Log Parameters Log Parameter - Log information which is made up of a Parameter Code, a Parameter Control Byte, and a Parameter Value. Parameter Code - A unique identifier which is used to distinguish between the different Log Parameters within a single Log Page. Parameter Control Byte - Used to tell the target how to update, save, use thresholds, determine format, etc. of the Parameter Value. Parameter Pointer Field - Contains a Parameter Code Parameter Value - A counter, cumulative, threshold, or ASCII value NV - Not Valid x - The value of the bit or field is not relevant. LOG SENSE Command The LOG SENSE command may be used to do two functions: One is to allow the target to save the Log Parameters in a Log Page to non-volatile storage. The other is to allow the initiator to receive the value of the current Log Parameters for a given Log Page. The following lists the definitions of the LOG SENSE Command Descriptor Block (CDB) fields: LOG SENSE CDB Values PPC SP PC Bit Bit Field Description --- --- ----- ------------------------------------------------------- 0 - -- Indicates that the log parameter requested from the target shall begin with the parameter code specified by the allocation length field in ascending order of parameter codes from the specified log page. 1 - -- Indicates that the target shall return a log page consisting only of the log parameters in which a log parameter value has changed since the last LOG SELECT or LOG SENSE command. The target shall return only those log parameters following the parameter pointer field. - 0 -- Indicates the target shall perform the specified LOG SENSE command and shall not save any log parameters. - 1 -- Indicates that the target shall perform the specified LOG SENSE command and shall save all log parameters identified as savable by the DS bit to a non-volatile vendor-specific location if allowed. (See the list below to determine the interaction between the SP and DS bits to see what 'allowed' means.) - - 00 Indicates the target shall return the Current Threshold Values. - - 01 Indicates the target shall return the Current Cumulative Values. - - 10 Indicates the target shall return the Default Threshold Values. - - 11 Indicates the target shall return the Default Cumulative Values. The following lists the possible Parameter Values which can be returned: Log Page Parameter Log Sense CDB Control Values Byte Value Target Action ------------- ---------- ------------------------------------------------- PPC PC LP Bit Field Bit Parameter Values returned to the Initiator --- ----- --- ------------------------------------------------- 0 00 0 Returns all Current Threshold Values starting with the specified Parameter Pointer. 0 01 0 Returns all Current Cumulative Values starting with the specified Parameter Pointer. 0 10 0 Returns all Default Threshold Values starting with the specified Parameter Pointer. 0 11 0 Returns all Default Cumulative Values starting with the specified Parameter Pointer. 1 00 0 Returns only the Current Threshold Values which have changed starting with the specified Parameter Pointer. 1 10 0 Returns only the Current Cumulative Values which have changed starting with the specified Parameter Pointer. 1 01 0 Returns only the Default Threshold Values which have changed starting with the specified Parameter Pointer. 1 11 0 Returns only the Default Cumulative Values which have changed starting with the specified Parameter Pointer. 0 xx 1 Returns all the List Parameters starting with the specified Parameter Pointer. 1 xx 1 Returns only the List Parameters which have changed starting with the specified Parameter Pointer. The following lists the possible save options for the LOG SENSE command. The listed options define the save operations which occur as a direct result of the LOG SENSE command. Further save operations are a function of the TSD bit in the Log Parameter Control Byte. Log Page Parameter CDB Control Values Byte Value Target Action ---------- ---------- ----------------------------------------------------- SP PC DS LP Bit Field Bit Bit --- ----- --- --- 0 xx x x Do not save any of the Log Parameters into non- volatile storage. 1 00 0 0 Save all the Current Threshold Values of the selected Log Page into non-volatile storage. 1 01 0 0 Save all the Current Cumulative Values of the selected Log Page into non-volatile storage. 1 10 0 0 Save all the Default Threshold Values of the selected Log Page into non-volatile storage. 1 11 0 0 Save all the Default Cumulative Values of the selected Log Page into non-volatile storage. 1 xx 0 1 Save all the current List Parameter Values of the selected Log Page into non-volatile storage. 1 xx 1 x Do not save any of the Log Parameters into non- volatile storage. Log Select Command One function of the LOG SELECT command is to allow the initiator a method of sending parameter values to the target. The following lists the definitions of the LOG SELECT Command Descriptor Block (CDB) fields: LOG SELECT CDB Values -------------------------- Parameter PCR SP PC List Bit Bit Field Length Description --- --- ----- --------- -------------------------------------------------- 0 - -- - Indicates that the log parameters shall not be reset. 1 x xx 0000h Indicates the target shall set all implemented parameter values to the target-defined default values. 1 x xx GT 0 An illegal condition. - 0 -- - Indicates the target shall not save any of of the log parameters. - 1 -- - Indicates that after performing the specified LOG SELECT operation the target shall save to non- volatile memory all savable log parameters. (See the list above to determine the interaction between the SP and DS bits to see what 'savable' means.) - - 00 - Indicates the initiator shall send Threshold Values. - - 01 - Indicates the initiator shall send Cumulative Values. - - 10 - Indicates the initiator shall send Default Threshold Values. - - 11 - Indicates the initiator shall send Default Cumulative Values. The following lists the possible save options for the LOG SELECT command. All the Log Parameters which are selected for saving shall be saved to non- volatile storage after the target performs the specified LOG SELECT operation. Further save operations are a function of the TSD bit in the Log Parameter Control Byte. Log Page Parameter CDB Control Values Byte Value Target Action ---------- ---------- ----------------------------------------------------- SP PC DS LP Bit Field Bit Bit --- ----- --- --- 0 xx x x Do not save any of the Log Parameters into non- volatile storage. 1 00 0 0 Save all the Threshold Values of the selected Log Page into non-volatile storage. 1 01 0 0 Save all the Cumulative Values of the selected Log Page into non-volatile storage. 1 10 0 0 Save all the Default Threshold Values of the selected Log Page into non-volatile storage. 1 11 0 0 Save all the Default Cumulative Values of the selected Log Page into non-volatile storage. 1 xx 0 1 Save all the List Parameter Values of the selected Log Page into non-volatile storage. 1 xx 1 x Do not save any of the Log Parameters into non- volatile storage. The following lists the possible Parameter Values which can be controlled: Log Page LOG SENSE Parameter CDB Control Values Byte Value Target Action --------- ---------- ------------------------------------------------------- PC LP Field Bit Updated Parameter Value Usage ----- --- ------------------------------------------------------- 00 0 The Parameter Values for all the Log Parameters in the Log Page(s) sent to the target shall be used as Threshold Values, unless the LP bit is set. 01 0 The Parameter Values for all the Log Parameters in the Log Page(s) sent to the target shall be used as Cumulative Values, unless the LP bit is set. 10 0 The target shall set the Current Threshold Values to the Default Threshold Values for all the Log Parameters specified in the Log Page(s) sent during a LOG SELECT command, unless the LP bit is set. 11 0 The target shall set the Current Cumulative Values to the Default Cumulative Values for all the Log Parameters specified in the Log Page(s) sent during a LOG SELECT command, unless the LP bit is set. xx 1 Replace the Current List Parameter with the List Parameter sent to the target. Logging Operations The logging operations can be setup to keep track of many different things. What those things are is left up to the imagination of implementors. But what should be well defined is how a target informs the initiator when a log reaches a critical point thereby creating an exception condition. What follows is a description of how the target shall deal with these exception conditions. The following lists the definitions of the Parameter Control Byte of the Log Parameter: Parameter Control Byte values ------------------------------ DU DS TSD ETC TMC LP Bit Bit Bit Bit Field Bit Description --- --- --- --- ----- --- ---------------------------------------------- 0 - - - -- - Indicates that the target shall update the log parameter value to reflect all events that should be noted by that log parameter. 1 - - - -- - Indicates that the target shall not update the log parameter value except in response to a LOG SELECT command that specifies a new value the log parameter. - 0 - - -- - Indicates that the target supports saving for of the log parameter. - 1 - - -- - Indicates the target does not support saving of the log parameter in response to a LOG SELECT or LOG SENSE command. - - 0 - -- - Indicates that the target provides a target- defined method of saving log parameters. - - 1 - -- - Indicates that either the target does not provide a target-defined method for saving log parameters or the target- defined method has been disabled by the initiator. - - - 0 -- - Indicates that a comparison between the threshold value and the cumulative value is not performed. - - - 1 -- - Indicates that a comparison to the threshold value is performed whenever the cumulative value is updated - - - - 00 - Indicates the target shall inform the initiator on every update to the cumulative value. Parameter Control Byte values (Continued) ------------------------------ DU DS TSD ETC TMC LP Bit Bit Bit Bit Field Bit Description --- --- --- --- ----- --- ---------------------------------------------- - - - - 01 - Indicates the target shall inform the initiator every time the cumulative value is equal to the threshold value. - - - - 10 - Indicates the target shall inform the initiator every time the cumulative value is not equal to the threshold value. - - - - 11 - Indicates the target shall inform the initiator every time the cumulative value is greater than the threshold value. - - - - -- 0 Indicates the log parameter is a data counter. - - - - -- 1 Indicates the log parameter is a list parameter. What follows is a description of how the target shall deal with exception conditions. Control Log Page Parameter Mode Page Control Byte Values (0Ah) Target Action -------------------- --------- --------------------------------------------- DU ETC TMC LP RLEC Bit Bit Field Bit Bit Exception Condition Actions --- --- ----- --- ---- --------------------------------------------- x x xx x 0 No logging activities will cause a Contingent Allegiance Condition or a Unit Attention Condition. x 0 GT 0 1 x An illegal condition x 1 xx 1 x An illegal condition 0 1 xx 0 1 IF the threshold condition as defined by the TMC field is met a)IF there is an active I/O process a)Complete the active I/O process b)If a Contingent Allegiance Condition exists wait for it to be cleared END b)Issue a Unit Attention Condition to all Initiators c)IF the Unit Attention Condition is ignored a)Continue normal operations until the threshold condition is met again END END DU ETC TMC LP RLEC Bit Bit Field Bit Bit Exception Condition Actions --- --- ----- --- ---- --------------------------------------------- 0 0 NV 0 1 IF a log counter reaches its maximum value 1 a)Set DU to 1 b)IF there is no active I/O process a)Wait until there is an active I/O process END c)Complete the active I/O process d)IF no Contingent Allegiance Condition exists a)Create a Contingent Allegiance Condition with a sense key of Recovered Error and an ASCQ of Log Exception, Count At Maximum END e)Wait for the Contingent Allegiance Condition to be cleared f)IF the cause of the counter reaching maximum is not cleared by the Initiator a)Create a Contingent Allegiance Condition every time the counter should be incremented. END END DU ETC TMC LP RLEC Bit Bit Field Bit Bit Exception Condition Actions --- --- ----- --- --- --------------------------------------------- 0 0 00 1 1 IF the log of parameters is full a)Place the new log parameter code value into the lowest parameter code value position (wrap-around the parameter codes) b)IF there is no active I/O process a)Wait until there is an active I/O process END c)Complete the active I/O process d)IF no Contingent Allegiance Condition exists a)Create a Contingent Allegiance Condition with a sense key of Recovered Error and an ASCQ of Log Exception, List Codes Exhausted END e)Wait for the Contingent Allegiance Condition to be cleared f)IF the cause of the log of parameters filling is not cleared by the Initiator a)Create a Contingent Allegiance Condition every time an entry is placed into the log of parameters END END