package org.jscsi.target.scsi.modeSense;

 import java.nio.ByteBuffer;

 import org.jscsi.target.util.BitManip;

 import org.jscsi.target.util.ReadWrite;

 /**

  * The Caching mode page defines the parameters that affect the use of the data cache by the storage medium.

  * 

  * @author Andreas Ergenzinger

  */

 public final class CachingModePage extends Page_0FormatModePage {

     /**

      * An initiator control (IC) enable bit set to one specifies that the device server use one of the following fields

      * to control the caching algorithm rather than the device server’s own adaptive algorithm:

      * <ol>

      * <li>

      * the NUMBER OF CACHE SEGMENTS field, if the SIZE bit is set to zero; or</li>

      * <li>

      * the CACHE SEGMENT SIZE field, if the SIZE bit is set to one.</li>

      * </ol>

      */

     private final boolean initiatorControl;

     /**

      * An abort pre-fetch (ABPF) bit set to one when the DRA bit is set to zero specifies that the device server abort a

      * pre-fetch upon receipt of a new command. An ABPF bit set to one takes precedence over the value specified in the

      * MINIMUM PRE-FETCH field. An ABPF bit set to zero when the DRA bit set to zero specifies that the termination of

      * any active pre-fetch is dependent upon Caching mode page bytes 4 through 11 and is vendor specific.

      */

     private final boolean abortPrefetch;

     /**

      * A caching analysis permitted (CAP) bit set to one specifies that the device server perform caching analysis

      * during subsequent operations. A CAP bit set to zero specifies that caching analysis be disabled (e.g., to reduce

      * overhead time or to prevent nonpertinent operations from impacting tuning values).

      */

     private final boolean cachingAnalysisPermitted;

     /**

      * A discontinuity (DISC) bit set to one specifies that the device server continue the pre-fetch across time

      * discontinuities (e.g., across cylinders) up to the limits of the buffer, or segment, space available for the

      * pre-fetch. A DISC bit set to zero specifies that pre-fetches be truncated or wrapped at time discontinuities.

      */

     private final boolean discontinuity;

     /**

      * A size enable (SIZE) bit set to one specifies that the CACHE SEGMENT SIZE field be used to control caching

      * segmentation. A SIZE bit set to zero specifies that the NUMBER OF CACHE SEGMENTS field be used to control caching

      * segmentation. Simultaneous use of both the number of segments and the segment size is vendor specific.

      */

     private final boolean sizeEnable;

     /**

      * A writeback cache enable (WCE) bit set to zero specifies that the device server shall complete a WRITE command

      * with GOOD status only after writing all of the data to the medium without error. A WCE bit set to one specifies

      * that the device server may complete a WRITE command with GOOD status after receiving the data without error and

      * prior to having written the data to the medium.

      */

     private final boolean writebackCacheEnable;

     /**

      * A multiplication factor (MF) bit set to zero specifies that the device server shall interpret the MINIMUM

      * PRE-FETCH field and the MAXIMUM PRE-FETCH field in terms of the number of logical blocks for each of the

      * respective types of pre-fetch. An MF bit set to one specifies that the device server shall interpret the MINIMUM

      * PRE-FETCH field and the MAXIMUM PRE-FETCH field to be specified in terms of a scalar number that, when multiplied

      * by the number of logical blocks to be transferred for the current command, yields the number of logical blocks

      * for each of the respective types of pre-fetch.

      */

     private final boolean multiplicationFactor;

     /**

      * A read cache disable (RCD) bit set to zero specifies that the device server may return data requested by a READ

      * command by accessing either the cache or medium. A RCD bit set to one specifies that the device server shall

      * transfer all of the data requested by a READ command from the medium (i.e., data shall not be transferred from

      * the cache).

      */

     private final boolean readCacheDisable;

     /**

      * The DEMAND READ RETENTION PRIORITY field specifies the retention priority the device server should assign for

      * data read into the cache that has also been transferred to the data-in buffer.

      * <table border="1">

      * <tr>

      * <th>Code</th>

      * <th>Description</th>

      * </tr>

      * <tr>

      * <td>0x0</td>

      * <td>The device server should not distinguish between retaining the<br/>

      * indicated data and data placed into the cache by other means <br/>

      * (e.g., pre-fetch).</td>

      * </tr>

      * <tr>

      * <td>0x1</td>

      * <td>The device server should replace data put into the cache via a<br/>

      * READ command sooner (i.e., read data has lower priority) than data<br/>

      * placed into the cache by other means (e.g., pre-fetch).</td>

      * </tr>

      * <tr>

      * <td>0x2 to 0xE</td>

      * <td>Reserved</td>

      * </tr>

      * </tr>

      * <tr>

      * <td>0xF</td>

      * <td>The device server should not replace data put into the cache<br/>

      * via a READ command if there is other data in the cache that was<br/>

      * placed into the cache by other means (e.g., pre-fetch) and the<br/>

      * data in the cache may be replaced.</td>

      * </tr>

      * </table>

      */

     private final byte demandReadRetentionPriority;

     /**

      * The WRITE RETENTION PRIORITY field (see table 155) specifies the retention priority the device server should

      * assign for data written into the cache that has also been transferred from the cache to the medium.

      * <table border="1">

      * <tr>

      * <th>Code</th>

      * <th>Description</th>

      * </tr>

      * <tr>

      * <td>0x0</td>

      * <td>The device server should not distinguish between retaining the<br/>

      * indicated data and data placed into the cache by other means<br/>

      * (e.g., pre-fetch).</td>

      * </tr>

      * <tr>

      * <td>0x1</td>

      * <td>The device server should replace data put into the cache during a<br/>

      * WRITE command or a WRITE AND VERIFY command sooner (i.e., has lower<br/>

      * priority) than data placed into the cache by other means (e.g., pre-fetch).</td>

      * </tr>

      * <tr>

      * <td>0x2 to 0xE</td>

      * <td>Reserved</td>

      * </tr>

      * </tr>

      * <tr>

      * <td>0xF</td>

      * <td>The device server should not replace data put into the cache during<br/>

      * a WRITE command or a WRITE AND VERIFY command if there is other data in<br/>

      * the cache that was placed into the cache by other means (e.g., pre-fetch) <br/>

      * and the data in the cache may be replaced.</td>

      * </tr>

      * </table>

      */

     private final byte writeRetentionPriority;

     /**

      * The DISABLE PRE-FETCH TRANSFER LENGTH field specifies the selective disabling of anticipatory pre-fetch on long

      * transfer lengths. The value in this field is compared to the transfer length requested by a READ command. If the

      * transfer length is greater than the disable pre-fetch transfer length, then an anticipatory pre-fetch is not done

      * for the command. Otherwise the device server should attempt an anticipatory pre-fetch. If the DISABLE PRE-FETCH

      * TRANSFER LENGTH field is set to zero, then all anticipatory pre-fetching is disabled for any request for data,

      * including those with a transfer length of zero.

      * <p>

      * An anticipatory pre-fetch occurs when data is placed in the cache that has not been requested. This may happen in

      * conjunction with the reading of data that has been requested. The DISABLE PRE-FETCH TRANSFER LENGTH field, the

      * MINIMUM PRE-FETCH field, the MAXIMUM PRE-FETCH field, and the MAXIMUM PRE-FETCH CEILING field give an indication

      * to the device server how it should manage the cache based on the most recent READ command. An anticipatory

      * pre-fetch may occur based on other information. These fields are only recommendations to the device server and

      * should not cause a CHECK CONDITION to occur if the device server is not able to satisfy the request.

      */

     private final int disablePrefetchTransferLength;

     /**

      * The MINIMUM PRE-FETCH field specifies the number of logical blocks to pre-fetch regardless of the delays it might

      * cause in processing subsequent commands. The field contains either:

      * <ol>

      * <li>a number of logical blocks, if the MF bit is set to zero; or</li>

      * <li>a scalar multiplier of the value in the TRANSFER LENGTH field, if the MF bit is set to one.</li>

      * </ol>

      * The pre-fetching operation begins at the logical block after the last logical block of a READ command.

      * <p>

      * Pre-fetching shall always halt when it reaches the last logical block on the medium. Errors that occur during the

      * pre-fetching operation shall not be reported to the application client unless the device server is unable to

      * process subsequent commands correctly as a result of the error. In this case the error may be reported either as

      * an error for that subsequent command, or as a deferred error, at the discretion of the device server and

      * according to the rules for reporting deferred errors (see SPC-4).

      * <p>

      * If the pre-fetch has read more than the amount of data specified by the MINIMUM PRE-FETCH field, then

      * pre-fetching should be terminated whenever another command enters the enabled state (see SAM-4). This requirement

      * is ignored when the MINIMUM PRE-FETCH field value is equal to the MAXIMUM PRE-FETCH field value.

      * 

      * @see #disablePrefetchTransferLength

      */

     private final int minimumPrefetch;

     /**

      * A complementary field to the {@link #minimumPrefetch} field.

      * 

      * @see #disablePrefetchTransferLength

      * @see #minimumPrefetch

      */

     private final int maximumPrefetch;

     /**

      * The MAXIMUM PRE-FETCH CEILING field specifies an upper limit on the number of logical blocks computed as the

      * maximum pre-fetch. If this number of logical blocks is greater than the value in the MAXIMUM PRE-FETCH field,

      * then the number of logical blocks to pre-fetch shall be truncated to the value stored in the MAXIMUM PRE-FETCH

      * CEILING field.

      * 

      * @see #disablePrefetchTransferLength

      */

     private final int maximumPrefetchCeiling;

     /**

      * A force sequential write (FSW) bit set to one specifies that, for commands writing to more than one logical

      * block, the device server shall write the logical blocks to the medium in ascending sequential order. An FSW bit

      * set to zero specifies that the device server may reorder the sequence of writing logical blocks (e.g., in order

      * to achieve faster command completion).

      */

     private final boolean forceSequentialWrite;

     /**

      * A logical block cache segment size (LBCSS) bit set to one specifies that the CACHE SEGMENT SIZE field units shall

      * be interpreted as logical blocks. An LBCSS bit set to zero specifies that the CACHE SEGMENT SIZE field units

      * shall be interpreted as bytes. The LBCSS shall not impact the units of other fields.

      */

     private final boolean logicalBlockCacheSegmentSize;

     /**

      * A disable read-ahead (DRA) bit set to one specifies that the device server shall not read into the pre-fetch

      * buffer any logical blocks beyond the addressed logical block(s). A DRA bit set to zero specifies that the device

      * server may continue to read logical blocks into the pre-fetch buffer beyond the addressed logical block(s).

      */

     private final boolean disableReadAhead;

     /**

      * An NV_DIS bit set to one specifies that the device server shall disable a non-volatile cache and indicates that a

      * non-volatile cache is supported but disabled. An NV_DIS bit set to zero specifies that the device server may use

      * a non-volatile cache and indicates that a non-volatile cache may be present and enabled.

      */

     private final boolean nonVolatileCacheDisabled;

     /**

      * The NUMBER OF CACHE SEGMENTS field specifies the number of segments into which the device server shall divide the

      * cache.

      */

     private final short numberOfCacheSegments;

     /**

      * The CACHE SEGMENT SIZE field specifies the segment size in bytes if the LBCSS bit is set to zero or in logical

      * blocks if the LBCSS bit is set to one. The CACHE SEGMENT SIZE field is valid only when the SIZE bit is set to

      * one.

      */

     private final int cacheSegmentSize;

     /**

      * The constructor.

      * <p>

      * The meaning of all parameters is described in the member descriptions of the variables with the same name.

      * 

      * @param parametersSaveable

      * @param initiatorControl

      * @param abortPrefetch

      * @param cachingAnalysisPermitted

      * @param discontinuity

      * @param sizeEnable

      * @param writebackCacheEnable

      * @param multiplicationFactor

      * @param readCacheDisable

      * @param demandReadRetentionPriority

      * @param writeRetentionPriority

      * @param disablePrefetchTransferLength

      * @param minimumPrefetch

      * @param maximumPrefetch

      * @param maximumPrefetchCeiling

      * @param forceSequentialWrite

      * @param logicalBlockCacheSegmentSize

      * @param disableReadAhead

      * @param nonVolatileCacheDisabled

      * @param numberOfCacheSegments

      * @param cacheSegmentSize

      */

     public CachingModePage (final boolean parametersSaveable, final boolean initiatorControl, final boolean abortPrefetch, final boolean cachingAnalysisPermitted, final boolean discontinuity, final boolean sizeEnable, final boolean writebackCacheEnable, final boolean multiplicationFactor, final boolean readCacheDisable, final int demandReadRetentionPriority, final int writeRetentionPriority, final int disablePrefetchTransferLength, final int minimumPrefetch, final int maximumPrefetch, final int maximumPrefetchCeiling, final boolean forceSequentialWrite, final boolean logicalBlockCacheSegmentSize, final boolean disableReadAhead, final boolean nonVolatileCacheDisabled, final int numberOfCacheSegments, final int cacheSegmentSize) {

         super(parametersSaveable,// PS

         0x08,// pageCode

         0x12);// pageLength

         this.initiatorControl = initiatorControl;

         this.abortPrefetch = abortPrefetch;

         this.cachingAnalysisPermitted = cachingAnalysisPermitted;

         this.discontinuity = discontinuity;

         this.sizeEnable = sizeEnable;

         this.writebackCacheEnable = writebackCacheEnable;

         this.multiplicationFactor = multiplicationFactor;

         this.readCacheDisable = readCacheDisable;

         this.demandReadRetentionPriority = (byte) (demandReadRetentionPriority & 0xf);

         this.writeRetentionPriority = (byte) (writeRetentionPriority & 0xf);

         this.disablePrefetchTransferLength = disablePrefetchTransferLength & 0xffff;

         this.minimumPrefetch = minimumPrefetch & 0xffff;

         this.maximumPrefetch = maximumPrefetch & 0xffff;

         this.maximumPrefetchCeiling = maximumPrefetchCeiling & 0xffff;

         this.forceSequentialWrite = forceSequentialWrite;

         this.logicalBlockCacheSegmentSize = logicalBlockCacheSegmentSize;

         this.disableReadAhead = disableReadAhead;

         this.nonVolatileCacheDisabled = nonVolatileCacheDisabled;

         this.numberOfCacheSegments = (short) (numberOfCacheSegments & 0xff);

         this.cacheSegmentSize = cacheSegmentSize & 0xffff;

     }

     @Override

     protected void serializeModeParameters (ByteBuffer buffer, int index) {

         // serialize byte 2

         buffer.position(index + 2);

         byte b = 0;

         b = BitManip.getByteWithBitSet(b, 7, initiatorControl);

         b = BitManip.getByteWithBitSet(b, 6, abortPrefetch);

         b = BitManip.getByteWithBitSet(b, 5, cachingAnalysisPermitted);

         b = BitManip.getByteWithBitSet(b, 4, discontinuity);

         b = BitManip.getByteWithBitSet(b, 3, sizeEnable);

         b = BitManip.getByteWithBitSet(b, 2, writebackCacheEnable);

         b = BitManip.getByteWithBitSet(b, 1, multiplicationFactor);

         b = BitManip.getByteWithBitSet(b, 0, readCacheDisable);

         buffer.put(b);

         // serialize byte 3

         b = (byte) ((demandReadRetentionPriority << 4) | writeRetentionPriority);

         buffer.put(b);

         // bytes 4 to 11 (unsigned short fields)

         ReadWrite.writeTwoByteInt(buffer,// buffer

                 disablePrefetchTransferLength,// value

                 index + 4);// index

         ReadWrite.writeTwoByteInt(buffer,// buffer

                 minimumPrefetch,// value

                 index + 6);// index

         ReadWrite.writeTwoByteInt(buffer,// buffer

                 maximumPrefetch,// value

                 index + 8);// index

         ReadWrite.writeTwoByteInt(buffer,// buffer

                 maximumPrefetchCeiling,// value

                 index + 10);// index

         // byte 12

         b = 0;

         b = BitManip.getByteWithBitSet(b, 7, forceSequentialWrite);

         b = BitManip.getByteWithBitSet(b, 6, logicalBlockCacheSegmentSize);

         b = BitManip.getByteWithBitSet(b, 5, disableReadAhead);

         b = BitManip.getByteWithBitSet(b, 0, nonVolatileCacheDisabled);

         buffer.position(index + 12);

         buffer.put(b);

         // byte 13

         buffer.put((byte) numberOfCacheSegments);

         // bytes 14 and 15

         ReadWrite.writeTwoByteInt(buffer,// buffer

                 cacheSegmentSize,// value

                 index + 14);// index

         // the remaining bytes are reserved or obsolete

     }

 }