DOCUMENT NUMBER 87-43 FIRST DRAFT: 3/18/87 REVISION 1: 5/18/87 REVISION 2: 7/21/87 Gregory G. Floryance IBM Corporation Storage Products Development System Products Division Hwy 52 & 37 Street NW Rochester, Mn 55901 (507) 253-1869 [edited into wordstar format by L. Lamers 09/04/87] READ LOG Command Peripheral Device Type: All Operation Code Type: Optional ============================================================================== Bit| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | Byte | | | | | | | | | ============================================================================== 0 | Operation Code (1Fh) | -----|-----------------------------------------------------------------------| 1 | Logical Unit Number | PF | Reserved | NLS | NLR | -----|-----------------------------------------------------------------------| 2 | Reserved | Page Code | -----|-----------------------------------------------------------------------| 3 | (MSB) | -----|--- Allocation Length ---| 4 | (LSB) | -----|-----------------------------------------------------------------------| 5 | Control Byte | ============================================================================== The READ LOG command is used to obtain and/or manage statistical information maintained by the device about the device or attached medium. This standard defines the mechanism to read, save and/or clear all or selected portions of the log data. Logging information can also be returned to the initiator on a REQUEST SENSE command in the REQUEST SENSE data. The log implementation can be volatile, non-volatile or a combination of both. Similarly, a single log can support both volatile and non-volatile parameters simultaneously. The term volatile indicates that the log data is temporary and is lost on a power-down or reset. The term non-volatile refers to log data which retains it's information across power cycles. Indication of whether a log is volatile, non-volatile or both is hidden from the initiator such that the log information is presented in a consistent manner regardless of the implementation. Indication of whether a parameter is volatile or non- volatile is defined within the format of the returned log data. When performing a read operation on a combination volatile and non-volatile log, parameters common to both logs shall be combined so as to present the appearance of a single log to the initiator. When performing a clear operation, the specified data from both logs shall be cleared. When performing a read operation, a save operation is implicit unless the NLS bit is set to one. Section (** later on **) discusses volatile and non-volatile logs in more detail. No Log Save (NLS) bit of one, indicates that the saved non-volatile log data, specified by the PF bit and page code, should not be updated with the volatile log data at the conclusion of the read operation. (This does not effect the data transferred to the initiator which shall always be combined.) A NLS bit of zero indicates that the non-volatile log data shall be updated with the volatile log information. The NLS bit is intended to provide the initiator with the ability to selectively disable the update operation as may be desirable in a diagnostic or testing mode. The No Log Clear (NLC) bit, set to one, causes the requested log data to be transferred but not cleared. The NLC bit set to zero, causes the log data (in both the volatile and non-volatile logs) specified by the PF bit and page code to be cleared after the data has been transferred. The allocation length being zero and the NLR bit set to zero causes the specified log data to be cleared without transferring any data to the initiator. When the NLR bit is set to zero and either PF=0 or PF=1 with Page Code 0 causes all supported log data for all pages to be cleared. A device may selectively choose to support the ability to clear all, some or none of the log data. When requested to clear a log (NLR=0), the device shall clear those portions of the log for which clearing is supported. For those portions where clearing is not supported, the request to clear shall not be considered an error. The Allocation length indicates the number of bytes the initiator has set aside for the READ LOG data. The target shall terminate the data transfer when either the allocation length has been transferred or when all available log data has been transferred to the initiator, whichever is less. An allocation length of zero is not considered an error. IMPLEMENTORS NOTE: Specifying an allocation length smaller than the available log data will result in lost log data if the NLC bit is set to clear the log. The Page Format (PF) bit of one indicates that the Read Log data conforms to page format. A value of zero indicates that the Read Log data is vendor unique and may or may not conform to page format. The Page Code (PC) field specifies which page to return and is only valid when the PF bit is set to 1. The page codes are defined in the following figure. Page Codes for READ LOG Command ============================================================================== Page Code Description ---------- ------------------------------------------------------------------ 00h Summary list of supported READ LOG pages 01h Device Specific Log Data (for compatibility to SCSI-1) 02 Medium Specific Log Data (for compatibility to SCSI-1) 03 Buffer Over/Under run counters 04 Read/Write Counters 05 Seek Length Counters 06 - 7Fh Reserved 80 - FFh Vendor Unique ============================================================================== It is considered an error for both the NLC and the NLS bit to be set to zero. A CHECK CONDITION shall be returned with illegal request sense key set. IMPLEMENTORS NOTE: This could be changed to interpret this as a clear operation instead since this would be the logical effect. All or a portion of the log data which is stored on the medium may not be available prior to the completion of device initialization. Device initialization is considered complete when GOOD status would be returned for the Test Unit Ready command. This could occur when part of the non-volatile log is on the medium and the other part is in non-volatile RAM. This could also occur when the medium has become unavailable (STOP UNIT or simply removed) with some residual log information previously created in volatile RAM. When only a portion of the data is available, that portion shall be returned followed by a CHECK CONDITION status and a NOT READY sense key. When a parameter is implemented in both volatile and non-volatile store, by not saving it (NLS=1), the initiator can obtain the combined value of the parameter but the non-volatile value is not updated. When the initiator issues a reset to the device, the volatile parameter is cleared. Clarifications on Implementing Dual Logs For performance, it is desirable to implement the logging function in high speed volatile memory without introducing medium access delays. However, for historical purposes, it is required that the log be implemented in non- volatile memory such as on the device medium in order to ensure data retention across power cycles. To obtain both performance and device history, a combination volatile and non-volatile log for either all or a subset of parameters may be implemented. This can introduce confusion in the read, save and clear operations in identifying which log is being operated upon and when. Fig. __.__ illustrates how the various combinations of NLS and NLC affect parameters in a dual log. The left chart represents initial conditions prior to command execution. The right charts represent the results of the indicated operations. N-VOL indicates the non-volatile log, VOL indicates the volatile log, Data represents the data which is transferred to the initiator and A,B,C represent three log parameters which are supported in non-volatile only, volatile only and both logs respectively. Note that the case of NLS and NLC both equal zero is not listed since this is illegal. Note also from the initiators perspective that the same data is returned in all three cases. Initial Condition Command Parameters Result ------------------- ---------------------- ------------------- | A | B | C | | A | B | C | ------|---|---|---| NLS = 1 = Do not save ------|---|---|---| N-VOL | 1 | | 3 | NLC = 0 = Clear N-VOL | 0 | | 0 | ------|---|---|---| ------|---|---|---| VOL | | 2 | 4 | ===============> VOL | | 0 | 0 | ------|---|---|---| ------|---|---|---| Data | 1 | 2 | 7 | ------|---|---|---| | A | B | C | NLS = 0 = Save ------|---|---|---| NLC = 1 = Do not clear N-VOL | 1 | | 7 | ------|---|---|---| ===============> VOL | | 2 | 0 | ------|---|---|---| Data | 1 | 2 | 7 | ------|---|---|---| NLS = 1 = Do not save ------|---|---|---| NLC = 1 = Do not clear N-VOL | 1 | | 3 | ------|---|---|---| ===============> VOL | | 2 | 4 | ------|---|---|---| Data | 1 | 2 | 7 | ------|---|---|---| Dual Log Illustration READ LOG DATA FORMAT The format of the log data consists of a 4 byte header followed by 1 or more variable parameters. The 4 byte header is illustrated in Fig __.__. Following the 4 byte page header, are the data parameters associated with that page. The Page Code field identifies the page of data which is being returned. The Parameter List Length field defines the length, in bytes, of the remaining page data. The length does not include bytes zero through three. Each parameter within the page contains a 2 byte header followed by 1 or more bytes of parameter information. The first byte contains the parameter code which identifies the parameter along with flag information indicating whether the parameter is stored in volatile memory (VOL=1), non-volatile memory (NVOL)=1 or both. The second byte o the header contains the parameters length and does not include the 2 header bytes. READ LOG Page Code Header ============================================================================== Bit| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | Byte | | | | | | | | | ============================================================================== 0 |Reserved|Reserved| Page Code (__h) | -----|-----------------------------------------------------------------------| 1 | Reserved | -----|-----------------------------------------------------------------------| 2 | (MSB) | -----|--- Page Parameter Length ---| 3 | (LSB) | -----|-----------------------------------------------------------------------| 4 | | -----|--- page specific parameters ---| n + 4| | ============================================================================== Log Data Parameters The following rules apply for log parameter implementation. After being reset, a log counter will contain the value of zero. A counter will continue to increment until the maximum value has been reached. Upon reaching the maximum value, the counter will no longer increment (will not wrap) but rather retain the maximum value as an indication that the counter has overflowed. When multiple parameters are defined to a single page code, they shall be returned in ascending order. A device may indicate non support of a parameter either by not including the parameter in the list or by returning a zero length in the parameter length field. Parameters can either be cleared (volatile) or their values retained (non- volatile) during a power-down or a reset. Each parameters definition identifies which applies to the particular parameter. IMPLEMENTORS NOTE: The reserved area allows for an extension to the parameter code field. One possible use of the reserved area is to report whether the counter is cleared during a power-down or reset. Another use would be to indicate if the counter can be reset or not. Summary List of Supported READ LOG Pages ============================================================================== Bit| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | Byte | | | | | | | | | ============================================================================== 0 |Reserved|Reserved| Page Code (0h) | -----|-----------------------------------------------------------------------| 1 | Reserved | -----|-----------------------------------------------------------------------| 2 | (MSB) | -----|--- Page Parameter Length ---| 3 | (LSB) | -----|-----------------------------------------------------------------------| 4 | First supported page number | -----|--- ---| n + 4| Last supported page number | ============================================================================== This page requests that a summary list of supported READ LOG pages for the device be sent to the Initiator. If any other pages are supported by the device, then support of page zero is mandatory. IMPLEMENTORS NOTE: Typically, an initiator should first request page zero to determine the list of other supported pages within the device. The supported page number list begins at byte 4 and contains a list of the supported pages for the device. Buffer Over/Underrun Counters ============================================================================== Bit| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | Byte | | | | | | | | | ============================================================================== 0 |Reserved|Reserved| Page Code (3h) | -----|-----------------------------------------------------------------------| 1 | Reserved | -----|-----------------------------------------------------------------------| 2 | (MSB) | -----|--- Page Parameter Length ---| 3 | (LSB) | -----|-----------------------------------------------------------------------| 5 | VOL | NVOL |Reserved| Parameter Code | -----|-----------------------------------------------------------------------| 6 | Counter Length | -----|-----------------------------------------------------------------------| 7 | (MSB) | -----|--- Counter ---| n + 7| (LSB) | ============================================================================== Description of Buffer Overrun/Underrun This page returns the device buffer overrun and underrun counters to the Initiator. A buffer overrun or underrun can occur when the initiator does not transmit the data to/from the buffer fast enough to keep up with the media. This can be caused either by a slow transfer rate on the SCSI interface or because of heavy SCSI bus usage preventing reconnection by the target. A buffer overrun condition occurs during a read operation when a buffer full condition prevents continued transfer of data from the media to the buffer. In the case of a disk drive, a mechanical delay is introduced equivalent to the time required for the data to reappear under the head. A buffer underrun condition occurs during a write operation when a buffer empty condition prevents continued transfer of data to the media from the buffer. In the case of a disk drive, a mechanical delay is introduced equivalent to the time required for the target sector of the drive to reappear under the head. Parameter Format The Parameter Code field defines the criteria used by the device to record overruns and underruns. Bits 0 through 4 of the Parameter Code field are defined in the Fig __.__. Bit 0 indicates if the counter type is overrun or underrun. Bits 1 and 2 indicate the cause of the overrun or underrun as either undefined, a busy bus, or a slow transfer rate on the interface. Bits 3 and 4 indicates the basis upon which the counter will be incremented as either undefined, per command, per reconnect attempt or per latency (i.e., disk revolution). Table Title ============================================================ | 43 = count basis | 21 = cause | 0 = type | ============================================================ | 00 = undefined | 00 = undefined | 0 = Underrun | | 01 = command | 01 = busy bus | 1 = Overrun | | 10 = failed reconnect | 10 = transfer rate| | | 11 = latency | 11 = reserved | | ============================================================ The overrun count and underrun count fields contain the total number of times a buffer overrun or underrun has occurred since the last time the counter was cleared. The count will be incremented for each occurrence of an underrun or overrun condition and can be incremented more than once for multiple occurrences during the execution of a single command. [I removed description of read/write ops page and seek pages in order to get document completed. Text for the removed pages is available to serve as a basis for additional proposals. G.F.]