dev/arm/ufs_device.hh

/*
 * Copyright (c) 2013-2015 ARM Limited
 * All rights reserved
 *
 * The license below extends only to copyright in the software and shall
 * not be construed as granting a license to any other intellectual
 * property including but not limited to intellectual property relating
 * to a hardware implementation of the functionality of the software
 * licensed hereunder.  You may use the software subject to the license
 * terms below provided that you ensure that this notice is replicated
 * unmodified and in its entirety in all distributions of the software,
 * modified or unmodified, in source code or in binary form.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are
 * met: redistributions of source code must retain the above copyright
 * notice, this list of conditions and the following disclaimer;
 * redistributions in binary form must reproduce the above copyright
 * notice, this list of conditions and the following disclaimer in the
 * documentation and/or other materials provided with the distribution;
 * neither the name of the copyright holders nor the names of its
 * contributors may be used to endorse or promote products derived from
 * this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * Authors: Rene de Jong
 */


/** @file
 * This is a base class for UFS devices
 * The UFS interface consists out of one host controller which connects a
 * number of devices which together contain up to 8 logic units. A Logical
 * Unit is an externally addressable, independent, processing entity that
 * processes SCSI tasks (commands) and performs task management functions.
 * The decision has been made to abstract the device away, and model the
 * different logic units. Effectively this means that there is one Host layer
 * which handles all the UFS commands (everything UTP, UPIU and UNIpro
 * related) and a SCSI layer, which handles the SCSI interpretation and the
 * interaction with the "disk" (effectively the LBA that that particular
 * Logic Unit controls). Each Logic unit should therefor control a disk image
 * and a timing model. The UFS protocol has three types of commands
 * (explained later). Each has different phases and each phase need to wait
 * for its particular data. This is the reason that this model contains a lot
 * of events. For clarity, a state diagram in doxygen has been provided. To
 * fully apreciate the stages that the model flows through, the states have
 * been broken into three state diagrams. It is best if one imagines the
 * command flow state machine to be happening in the UFSHost layer, and the
 * other two to flow through all the layers of the model (UFS host, SCSI and
 * NVM model). See it as a quarry, one state diagram is moving the crane into
 * place, and the other ones are transporting the dirt down, or the valuables
 * up. For complete information about the working of UFS please refer to
 * http://www.jedec.org/standards-documents/results/jesd220 or
 * http://www.jedec.org/standards-documents/results/jesd223
 * The documents are available free of charge, although you will need to have
 * an acount.
 */

/** UFS command flow state machine
 *digraph CommandFlow{
    node [fontsize=10];
    IDLE -> transferHandler
    [ label=" transfer/task/command request " fontsize=6];
    transferHandler -> command
    [ label=" It is a command " fontsize=6];
    command -> IDLE
    [ label=" Command done, no further action " fontsize=6];
    transferHandler -> taskStart
    [ label=" It is a task " fontsize=6];
    taskStart -> finalUTP
    [ label=" Task handled, now acknowledge (UFS) " fontsize=6];
    transferHandler -> transferStart
    [ label=" It is a transfer " fontsize=6];
    transferStart -> SCSIResume
    [ label=" Transfer, obtain the specific command " fontsize=6];
    SCSIResume -> DiskDataFlowPhase
    [ label=" Disk data transfer (see other graphs) " fontsize=6];
    SCSIResume -> DeviceDataPhase
    [ label=" Device info transfer (handled in SCSIResume) "
        fontsize=6];
    DiskDataFlowPhase -> transferDone
    [ label=" Transfer done, acknowledge SCSI command " fontsize=6];
    DeviceDataPhase -> transferDone
    [ label=" Transfer done, acknowledge SCSI command " fontsize=6];
    transferDone -> finalUTP
    [ label=" Transfer handled, now acknowledge (UFS) " fontsize=6];
    finalUTP -> readDone
    [ label=" All handled, clear data structures " fontsize=6];
    readDone -> IDLE
    [ label=" All handled, nothing outstanding " fontsize=6];
    readDone -> transferHandler
    [ label=" All handled, handle next outstanding " fontsize=6];
    }
 */
/** UFS read transaction flow state machine
 digraph readFlow{
    node [fontsize=10];
    getScatterGather -> commitReadFromDisk
    [ label=" Put the information about the data transfer to the disk "
        fontsize=6];
    commitReadFromDisk -> waitForReads
    [ label=" Push the reads to the flashmodel and wait for callbacks "
        fontsize=6];
    waitForReads -> pushToDMA
    [ label=" Push to the DMA and wait for them to finish " fontsize=6];
    pushToDMA -> waitForReads
    [ label=" Wait for the next disk event " fontsize=6];
    pushToDMA -> waitForDMA
    [ label=" Wait for the last DMA transfer to finish " fontsize=6];
    waitForDMA -> finishTransfer
    [ label=" Continue with the command flow " fontsize=6];
    }
 */
/** UFS write transaction flow state machine
 digraph WriteFlow{
    node [fontsize=10];
    getScatterGather -> getFromDMA
    [ label=" Put the transfer information to the DMA " fontsize=6];
    getFromDMA -> waitForDMA
    [ label=" Wait for dma actions to arrive " fontsize=6];
    waitForDMA -> pushToDisk
    [ label=" Push arrived DMA to disk " fontsize=6];
    pushToDisk -> waitForDMA
    [ label=" Wait for next DMA action " fontsize=6];
    pushToDisk -> waitForDisk
    [ label=" All DMA actions are done, wait for disk " fontsize=6];
    waitForDisk -> finishTransfer
    [ label=" All transactions are done , continue the command flow "
        fontsize=6];
    }
 */

#ifndef __DEV_ARM_UFS_DEVICE_HH__
#define __DEV_ARM_UFS_DEVICE_HH__

#include <deque>

#include "base/addr_range.hh"
#include "base/bitfield.hh"
#include "base/statistics.hh"
#include "debug/UFSHostDevice.hh"
#include "dev/arm/abstract_nvm.hh"
#include "dev/arm/base_gic.hh"
#include "dev/storage/disk_image.hh"
#include "dev/dma_device.hh"
#include "dev/io_device.hh"
#include "mem/packet.hh"
#include "mem/packet_access.hh"
#include "params/UFSHostDevice.hh"
#include "sim/serialize.hh"
#include "sim/stats.hh"

/**
 * Host controller layer: This is your Host controller
 * This layer handles the UFS functionality.
 * It tracks all the different transaction stages and uses
 * the device layer and the flash layer to determine the transaction flow.
 */
class UFSHostDevice : public DmaDevice
{
  public:

    UFSHostDevice(const UFSHostDeviceParams* p);

    DrainState drain() override;
    void checkDrain();
    void serialize(CheckpointOut &cp) const override;
    void unserialize(CheckpointIn &cp) override;

  private:
    /**
     * Host Controller Interface
     * This is a set of registers that allow the driver to control the
     * transactions to the flash devices.
     * As defined in:
     * http://www.jedec.org/standards-documents/results/jesd223
     */
    struct HCIMem {
        /**
         * Specify the host capabilities
         */
        uint32_t HCCAP;
        uint32_t HCversion;
        uint32_t HCHCDDID;
        uint32_t HCHCPMID;

        /**
         * Operation and runtime registers
         */
        uint32_t ORInterruptStatus;
        uint32_t ORInterruptEnable;
        uint32_t ORHostControllerStatus;
        uint32_t ORHostControllerEnable;
        uint32_t ORUECPA;
        uint32_t ORUECDL;
        uint32_t ORUECN;
        uint32_t ORUECT;
        uint32_t ORUECDME;
        uint32_t ORUTRIACR;

        /**
         * vendor specific register
         */
        uint32_t vendorSpecific;

        /**
         * Transfer control registers
         */
        uint32_t TRUTRLBA;
        uint32_t TRUTRLBAU;
        uint32_t TRUTRLDBR;
        uint32_t TRUTRLCLR;
        uint32_t TRUTRLRSR;

        /**
         * Task control registers
         */
        uint32_t TMUTMRLBA;
        uint32_t TMUTMRLBAU;
        uint32_t TMUTMRLDBR;
        uint32_t TMUTMRLCLR;
        uint32_t TMUTMRLRSR;

        /**
         * Command registers
         */
        uint32_t CMDUICCMDR;
        uint32_t CMDUCMDARG1;
        uint32_t CMDUCMDARG2;
        uint32_t CMDUCMDARG3;
    };

    /**
     * All the data structures are defined in the UFS standard
     * This standard be found at the JEDEC website free of charge
     * (login required):
     * http://www.jedec.org/standards-documents/results/jesd220
     */

    /**
     * struct UTPUPIUHeader - UPIU header structure
     * dWord0: UPIU header DW-0
     * dWord1: UPIU header DW-1
     * dWord2: UPIU header DW-2
     */
    struct UTPUPIUHeader {
        uint32_t dWord0;
        uint32_t dWord1;
        uint32_t dWord2;
    };

    /**
     * struct UTPUPIURSP - Response UPIU structure
     * header: UPIU header DW-0 to DW-2
     * residualTransferCount: Residual transfer count DW-3
     * reserved: Reserved DW-4 to DW-7
     * senseDataLen: Sense data length DW-8 U16
     * senseData: Sense data field DW-8 to DW-12
     */
    struct UTPUPIURSP {
        struct UTPUPIUHeader header;
        uint32_t residualTransferCount;
        uint32_t reserved[4];
        uint16_t senseDataLen;
        uint8_t senseData[18];
    };

    /**
     * struct UTPUPIUTaskReq - Task request UPIU structure
     * header - UPIU header structure DW0 to DW-2
     * inputParam1: Input param 1 DW-3
     * inputParam2: Input param 2 DW-4
     * inputParam3: Input param 3 DW-5
     * reserved: Reserver DW-6 to DW-7
     */
    struct UTPUPIUTaskReq {
        struct UTPUPIUHeader header;
        uint32_t inputParam1;
        uint32_t inputParam2;
        uint32_t inputParam3;
        uint32_t reserved[2];
    };

    /**
     * struct UFSHCDSGEntry - UFSHCI PRD Entry
     * baseAddr: Lower 32bit physical address DW-0
     * upperAddr: Upper 32bit physical address DW-1
     * reserved: Reserved for future use DW-2
     * size: size of physical segment DW-3
     */
    struct UFSHCDSGEntry {
        uint32_t baseAddr;
        uint32_t upperAddr;
        uint32_t reserved;
        uint32_t size;
    };

    /**
     * struct UTPTransferCMDDesc - UFS Commad Descriptor structure
     * commandUPIU: Command UPIU Frame address
     * responseUPIU: Response UPIU Frame address
     * PRDTable: Physcial Region Descriptor
     * All lengths as defined by JEDEC220
     */
    struct UTPTransferCMDDesc {
        uint8_t commandUPIU[128];
        uint8_t responseUPIU[128];
        struct UFSHCDSGEntry PRDTable[128];
    };

    /**
     * UPIU tranfer message.
     */
    struct UPIUMessage {
        struct UTPUPIUHeader header;
        uint32_t dataOffset;
        uint32_t dataCount;
        std::vector<uint32_t> dataMsg;
    };

    /**
     * struct UTPTransferReqDesc - UTRD structure
     * header: UTRD header DW-0 to DW-3
     * commandDescBaseAddrLo: UCD base address low DW-4
     * commandDescBaseAddrHi: UCD base address high DW-5
     * responseUPIULength: response UPIU length DW-6
     * responseUPIUOffset: response UPIU offset DW-6
     * PRDTableLength: Physical region descriptor length DW-7
     * PRDTableOffset: Physical region descriptor offset DW-7
     */
    struct UTPTransferReqDesc {

        /**
         * struct RequestDescHeader
         * dword0: Descriptor Header DW0
         * dword1: Descriptor Header DW1
         * dword2: Descriptor Header DW2
         * dword3: Descriptor Header DW3
         */
        struct RequestDescHeader {
            uint32_t dWord0;
            uint32_t dWord1;
            uint32_t dWord2;
            uint32_t dWord3;
        } header;

        /* DW 4-5*/
        uint32_t commandDescBaseAddrLo;
        uint32_t commandDescBaseAddrHi;

        /* DW 6 */
        uint16_t responseUPIULength;
        uint16_t responseUPIUOffset;

        /* DW 7 */
        uint16_t PRDTableLength;
        uint16_t PRDTableOffset;
    };

    /**
     * SCSI reply structure. In here is all the information that is needed to
     * build a SCSI reply.
     */
    struct SCSIReply {
        void reset() {
            memset(static_cast<void*>(this), 0, sizeof(*this));
        }

        uint8_t status;
        uint32_t msgSize;
        uint8_t LUN;
        struct UPIUMessage message;
        uint8_t senseSize;
        uint8_t expectMore;//0x01 is for writes, 0x02 is for reads
        uint64_t offset;
        uint8_t senseCode[19];
    };

    /**
     * Logic unit information structure. SCSI requires information of each LUN.
     * This structure is defined in the SCSI standard, and can also be found in
     * the UFS standard. http://www.jedec.org/standards-documents/results/jesd220
     */
    struct LUNInfo {
        uint32_t dWord0;
        uint32_t dWord1;
        uint32_t vendor0;
        uint32_t vendor1;
        uint32_t product0;
        uint32_t product1;
        uint32_t product2;
        uint32_t product3;
        uint32_t productRevision;
    };

    /**
     * Different events, and scenarios require different types of information.
     * Keep in mind that for a read-from-disk transaction the host at first a
     * datastructure fetches to determine where and what the command is, then the
     * command fetches and the structure fetches to determine where the
     * different read transactions should be placed and then transfers all the
     * read fragments. It then answers to the original caller with two replies,
     * one for the command, and one for UFS. Each of these stages trigger a
     * different event, and each event needs to know what happened in the
     * previous stage and what is going to happen in the current one. This
     * happens also for writes, SCSI maintanance, UFS maintanance, command
     * management and task management.
     */

    /**
     * Transfer information.
     * @filePointer this does not point to a file, but to a position on the disk
     * image (which is from the software systems perspective a position in a file)
     */
    struct transferInfo {
        std::vector <uint8_t> buffer;
        uint32_t size;
        uint64_t offset;
        uint32_t filePointer;
        uint32_t lunID;
    };

    /**
     * transfer completion info.
     * This information is needed by transferDone to finish the transfer.
     */
    struct transferDoneInfo {
        Addr responseStartAddr;
        uint32_t reqPos;
        struct UTPUPIURSP requestOut;
        uint32_t size;
        Addr address;
        uint8_t *destination;
        bool finished;
        uint32_t lunID;
    };

    /**
     * Transfer start information.
     */
    struct transferStart {
        struct UTPTransferReqDesc* destination;
        uint32_t mask;
        Addr address;
        uint32_t size;
        uint32_t done;
        uint32_t lun_id;
    };

    /**
     * Task start information. This is for the device, so no lun id needed.
     */
    struct taskStart {
        struct UTPUPIUTaskReq destination;
        uint32_t mask;
        Addr address;
        uint32_t size;
        bool done;
    };

    /**
     * After a SCSI command has been identified, the SCSI resume function will
     * handle it. This information will provide context information.
     */
    struct SCSIResumeInfo {
        struct UTPTransferReqDesc* RequestIn;
        int reqPos;
        Addr finalAddress;
        uint32_t finalSize;
        std::vector <uint8_t> destination;
        uint32_t done;
    };

    /**
     * Disk transfer burst information. Needed to allow communication between the
     * disk transactions and dma transactions.
     */
    struct writeToDiskBurst {
        Addr start;
        uint64_t SCSIDiskOffset;
        uint32_t size;
        uint32_t LUN;
    };

    /**
     * Statistics
     */
    struct UFSHostDeviceStats {
        /** Queue lengths */
        Stats::Scalar currentSCSIQueue;
        Stats::Scalar currentReadSSDQueue;
        Stats::Scalar currentWriteSSDQueue;

        /** Amount of data read/written */
        Stats::Scalar totalReadSSD;
        Stats::Scalar totalWrittenSSD;
        Stats::Scalar totalReadDiskTransactions;
        Stats::Scalar totalWriteDiskTransactions;
        Stats::Scalar totalReadUFSTransactions;
        Stats::Scalar totalWriteUFSTransactions;

        /** Average bandwidth for reads and writes */
        Stats::Formula averageReadSSDBW;
        Stats::Formula averageWriteSSDBW;

        /** Average Queue lengths*/
        Stats::Average averageSCSIQueue;
        Stats::Average averageReadSSDQueue;
        Stats::Average averageWriteSSDQueue;

        /** Number of doorbells rung*/
        Stats::Formula curDoorbell;
        Stats::Scalar maxDoorbell;
        Stats::Average averageDoorbell;

        /** Histogram of latencies*/
        Stats::Histogram transactionLatency;
        Stats::Histogram idleTimes;
    };

    /**
     * device layer: This is your Logic unit
     * This layer implements the SCSI functionality of the UFS Device
     * One logic unit controls one or more disk partitions
     */
    class UFSSCSIDevice: SimObject
    {
      public:
        /**
         * Constructor and destructor
         */
        UFSSCSIDevice(const UFSHostDeviceParams* p, uint32_t lun_id, Callback*
                      transfer_cb, Callback *read_cb);
        ~UFSSCSIDevice();

        /**
         * SCSI command handle function; determines what the command is and
         * returns a reply structure that allows the host device to continue
         * with the transfer.
         */
        struct SCSIReply SCSICMDHandle(uint32_t* SCSI_msg);

        /**
         * Disk access functions. These will transfer the data from/to the disk
         */

        /**
         * Read flash. read the data from the disk image. This function
         * doesn't model timing behaviour
         */
        void readFlash(uint8_t* readaddr, uint64_t offset, uint32_t size);

        /**
         * Write flash. write the data to the disk image. This function
         * doesn't model timing behaviour
         */
        void writeFlash(uint8_t* writeaddr, uint64_t offset, uint32_t size);

        /**
         * finished command. Probe to find out wether this logic unit
         * finished its transfer and triggered the callback; The host needs
         * this to handle the final part of the transaction.
         */
        bool finishedCommand() const {return transferCompleted;};

        /**
         * Clear signal. Handle for the host to clear the transfer complete
         * signal.
         */
        void clearSignal() {transferCompleted = false;};

        /**
         * Finished read. Probe to find out which logic unit finished its
         * read. This is needed, because multiple units can do transactions
         * at the same time, and need to push back data at the right time in
         * the right order. (because writes work the other way round, they do
         * not need this mechanism)
         */
        bool finishedRead() const {return readCompleted;};

        /**
         * Clear signal. Handle for the host to clear the read complete
         * signal.
         */
        void clearReadSignal() {readCompleted = false;};

        /**
         * Start the transactions to (and from) the disk
         * The host will queue all the transactions. Once the next phase
         * commences, this function should be started.
         */
        void SSDReadStart(uint32_t total_read);
        void SSDWriteStart();

        /**
         * Sets total amount of write transactions that needs to be made.
         * First they need to be fetched via DMA, so this value is needed in
         * a later stage.
         */
        void setTotalWrite(uint32_t total_write) {totalWrite = total_write;};

        /**
         * End of transfer information
         */
        transferDoneInfo transferInfo;

        /**
         * Information message queues, as there can be multiple messages
         * queued for handling in this system. These are the main
         * communication interfaces between the Host and the device layers
         */

        /**
         * SCSIInfoQueue: each LU handles its own SCSI commands.
         */
        std::deque<struct SCSIResumeInfo> SCSIInfoQueue;

        /**
         * SSDReadInfo: Structure from disk to dma, that contains data, and
         * helper info to get it to the right place in the memory.
         */
        std::deque<struct transferInfo> SSDReadInfo;

        /**
         * SSDWriteDoneInfo: Structure from dma to disk, that contains data,
         * and helper info to get it to the right place in the memory.
         * The done is added because it is going to the last phase of the
         * write transfer.
         */
        std::deque<struct transferInfo> SSDWriteDoneInfo;

      private:
        /**
         * Functions to indicate that the action to the SSD has completed.
         */
        /**
         * Read Call back; This is the callback function for the memory model
         */
        void readCallback();

        /**
         * SSD Read done; Determines if the final callback of the transaction
         * should be made at the end of a read transfer.
         */
        void SSDReadDone();

        /**
         * SSD Write Done; This is the callback function for the memory model.
         */
        void SSDWriteDone();

        /**
         * Status of SCSI. This may be linked to a status check in the future.
         * For now it (mainly) fills a data structure with sense information
         * for a successfull transaction
         */
        void statusCheck(uint8_t status, uint8_t* sensecodelist);

        /**
         * set signal to indicate that the transaction has been completed.
         */
        void setSignal() {transferCompleted = true;};

        /**
         * set signal to indicate that the read action has been completed
         */
        void setReadSignal() {readCompleted = true;};

        /**
         * The objects this model links to.
         * 1: the disk data model
         * 2: the memory timing model
         */
        DiskImage* flashDisk;
        AbstractNVM* flashDevice;

        /**
         * Logic unit dimensions
         */
        const uint32_t blkSize;
        const uint32_t lunAvail;
        const uint64_t diskSize;
        const uint32_t capacityLower;
        const uint32_t capacityUpper;

        /**
         * Logic unit info; needed for SCSI Info messages and LU
         * identification
         */
        struct LUNInfo lunInfo;
        const uint32_t lunID;

        /**
         * Signals to Host layer
         * 1: signal for transaction completion
         * 2: signal for read action completion
         */
        bool transferCompleted;
        bool readCompleted;

        /**
         * Total amount transactions that need to be made
         */
        uint32_t totalRead;
        uint32_t totalWrite;

        /**
         * transaction progress tracking
         */
        uint32_t amountOfWriteTransfers;
        uint32_t amountOfReadTransfers;

        /**
         * Callbacks between Host and Device
         */
        Callback* signalDone;
        Callback* deviceReadCallback;

        /**
         * Callbacks between Device and Memory
         */
        Callback* memReadCallback;
        Callback* memWriteCallback;

        /*
         * Default response header layout. For more information refer to
         * chapter 7 http://www.jedec.org/standards-documents/results/jesd220
         */
        static const unsigned int UPIUHeaderDataIndWord0 = 0x0000C022;
        static const unsigned int UPIUHeaderDataIndWord1 = 0x00000000;
        static const unsigned int UPIUHeaderDataIndWord2 = 0x40000000;

        /*
         * SCSI mode pages values assigned in ufs_device.cc
         * The mode pages give device specific information via the SCSI
         * protocol. They are defined in
         * http://www.jedec.org/standards-documents/results/jesd220
         */
        static const unsigned int controlPage[3];
        static const unsigned int recoveryPage[3];
        static const unsigned int cachingPage[5];

        /*
         * SCSI command set; defined in
         * http://www.jedec.org/standards-documents/results/jesd220
         */
        enum SCSICommandSet {
            SCSIInquiry = 0x12,
            SCSIRead6 = 0x08,
            SCSIRead10 = 0x28,
            SCSIRead16 = 0x88,
            SCSIReadCapacity10 = 0x25,
            SCSIReadCapacity16 = 0x9E,
            SCSIReportLUNs = 0xA0,
            SCSIStartStop = 0x1B,
            SCSITestUnitReady = 0x00,
            SCSIVerify10 = 0x2F,
            SCSIWrite6 = 0x0A,
            SCSIWrite10 = 0x2A,
            SCSIWrite16 = 0x8A,
            SCSIFormatUnit = 0x04,
            SCSISendDiagnostic = 0x1D,
            SCSISynchronizeCache = 0x35,
            //UFS SCSI additional command set for full functionality
            SCSIModeSelect10 = 0x55,
            SCSIModeSense6 = 0x1A,
            SCSIModeSense10 = 0x5A,
            SCSIRequestSense = 0x03,
            SCSIUnmap = 0x42,
            SCSIWriteBuffer = 0x3B,
            SCSIReadBuffer = 0x3C,
            //SCSI commands not supported by UFS; but Linux send them anyway
            SCSIMaintenanceIn = 0xA3
        };

        /*
         * SCSI status codes; defined in
         * http://www.jedec.org/standards-documents/results/jesd220
         */
        enum SCSIStatusCodes {
            SCSIGood = 0x00,
            SCSICheckCondition = 0x02,
            SCSIConditionGood = 0x04,
            SCSIBusy = 0x08,
            SCSIIntermediateGood = 0x10,
            SCSIIntermediatCGood = 0x14,
            SCSIReservationConflict = 0x18,
            SCSICommandTerminated = 0x22,
            SCSITaskSetFull = 0x28,
            SCSIACAActive = 0x30,
            SCSITaskAborted = 0x40
        };

        /*
         * SCSI sense codes; defined in
         * http://www.jedec.org/standards-documents/results/jesd220
         */
        enum SCSISenseCodes {
            SCSINoSense = 0x00,
            SCSIRecoverdError = 0x01,
            SCSINotReady = 0x02,
            SCSIMediumError = 0x03,
            SCSIHardwareError = 0x04,
            SCSIIllegalRequest = 0x05,
            SCSIUnitAttention = 0x06,
            SCSIDataProtect = 0x07,
            SCSIBlankCheck = 0x08,
            SCSIAbortedCommand = 0x0B,
            SCSIVolumeOverflow = 0x0D,
            SCSIMisCompare = 0x0E
        };

    };

    //All access functions are inherrited; no need to make them public
    /**
     * Address range functions
     */
    AddrRangeList getAddrRanges() const override;

    /**
     * register access functions
     */
    Tick read(PacketPtr pkt) override;
    Tick write(PacketPtr pkt) override;
    // end of access functions

    /**
     * Initialization function. Sets the sefault HCI register values
     */
    void setValues();

    /**
     * Handler functions. Each function handles a different stage of the
     * transfer. Note that the UFS protocol specifies three types of messages
     * to the host (and devices):
     * 1: Command (to Host specifically)
     * 2: Task (to device; to control flow, not for data)
     * 3: Transfer (to device; to transfer data)
     */
    /**
     * request handler. This function finds the cause of the request and
     * triggers the right follow-up action (command handler, task handler,
     * or transferhandler)
     */
    void requestHandler();

    /**
     * Command handler function. Handles the command send to the Host
     * controller
     */
    void commandHandler();

    /**
     * Task Start function. Starts the task handler once the task data
     * structure has arrived
     */
    void taskStart();

    /**
     * Task handler function. Handles the tasks send to the devices
     * because there are not many tasks implemented yet this is kept in the
     * Host controller layer
     */
    void taskHandler(struct UTPUPIUTaskReq* request_in,
                     uint32_t req_pos, Addr finaladdress, uint32_t finalsize);

    /**
     * Transfer Start function. Starts the transfer handler once the transfer
     * data structure has arrived
     */
    void transferStart();

    /**
     * Transfer handler function. Handles the transfers send to the devices
     * Important to understand here is that a Logic unit is not a device (a
     * device can contain multiple logic units). This function analyses the
     * first data structure that has been transfered. Which will tell the
     * host to expect SCSI frames for the rest of the transaction. Note that
     * the host has no indication whatsoever which LU to address. That will
     * follow in the next transaction.
     */
    void transferHandler(struct UTPTransferReqDesc*
                         request_in, int req_pos, Addr finaladdress,
                         uint32_t finalsize, uint32_t done);

    /**
     * Transfer SCSI function. Determines which Logic unit to address and
     * starts the SCSI resume function
     */
    void SCSIStart();

    /**
     * Starts the scsi handling function in the apropriate Logic unit,
     * prepares the right data transfer scheme and kicks it off.
     */
    void SCSIResume(uint32_t lun_id);

    /**
     * LU callback function to indicate that the action has completed.
     */
    void LUNSignal();

    /**
     * transfer done, the beginning of the final stage of the transfer.
     * Acknowledges UPIU frame and prepares the UTP response frame
     */
    void transferDone(Addr responseStartAddr, uint32_t req_pos,
                      struct UTPUPIURSP request_out, uint32_t size,
                      Addr address, uint8_t* destination, bool finished,
                      uint32_t lun_id);
    /**
     * final UTP, sends the last acknowledge data structure to the system;
     * prepares the clean up functions.
     */
    void finalUTP();

    /**
     * Interrupt control functions
     */
    void clearInterrupt();
    void generateInterrupt();

    /**
     * DMA transfer functions
     * These allow the host to push/pull the data to the memory
     * The provided event indicates what the next phase it that will handle
     * the obtained data, or what the follow up action is once the data has
     * been pushed to the memory
     */
    void writeDevice(Event* additional_action, bool toDisk, Addr start,
                     int size, uint8_t* destination, uint64_t SCSIDiskOffset,
                     uint32_t lun_id);
    void readDevice(bool lastTransfer, Addr SCSIStart, uint32_t SCSISize,
                    uint8_t* SCSIDestination, bool no_cache,
                    Event* additional_action);

    /**
     * Disk transfer management functions
     * these set up the queues, and initiated them, leading to the data
     * transaction timing model based on the scatter gather list constructed
     * in SCSIresume.
     */
    void manageWriteTransfer(uint8_t LUN, uint64_t offset, uint32_t
                             sg_table_length, struct UFSHCDSGEntry* sglist);
    void manageReadTransfer(uint32_t size, uint32_t LUN, uint64_t offset,
                            uint32_t sg_table_length,
                            struct UFSHCDSGEntry* sglist);

    /**
     * Read done
     * Started at the end of a transaction after the last read action. Cleans
     * up UTP descriptor and other remaining data structures. It also raises
     * the interrupt.
     */
    void readDone();

    /**
     * Write done
     * After a DMA write with data intended for the disk, this function is
     * called. It ensures that the disk image is modified, and that the
     * correct timing function is triggered.
     */
    void writeDone();

    /**
     * Read callback
     * Call back function for the logic units to indicate the completion of
     * a read action. Note that this is needed because the read functionality
     * needs to push data structures back to the memory.
     */
    void readCallback();

    /**
     * Read garbage
     * A read from disk data structure can vary in size and is therefor
     * allocated on creation. It can only be destroyed once that particular
     * read action has completed. This function is called on completion of a
     * read from disk action to handle this.
     */
    void readGarbage();

    /**register statistics*/
    void regStats() override;

    /**
     * Host controller information
     */
    const Addr pioAddr;
    const Addr pioSize;
    const Tick pioDelay;
    const int intNum;
    BaseGic* gic;
    const uint32_t lunAvail;
    const uint8_t UFSSlots;

    /**
     * Host controller memory
     */
    HCIMem UFSHCIMem;

    /**
     * Track number of DMA transactions in progress
     */
    int readPendingNum;
    int writePendingNum;

    /**
     * Statistics helper variables
     * Active doorbells indicates how many doorbells are in teh process of
     * being handled.
     * Pending doorbells have been handled and are waiting to be acknowledged
     * by the host system.
     * The doorbell register is 32 bits wide, so one byte is enough to keep
     * track of the numbers
     */
    uint8_t activeDoorbells;
    uint8_t pendingDoorbells;

    /**
     * interrupt verification
     * This keeps track of the number of interrupts generated. It is usefull
     * for debug purposes. Make sure that the implemented driver prints the
     * number of interrupts it has handled so far to fully benefit from this
     * feature.
     */
    uint32_t countInt;

    /**
     * Track the transfer
     * This is allows the driver to "group" certain transfers together by
     * using a tag in the UPIU. The messages with the same tag should be
     * handled together, i.e. their doorbells should be cleared when they are
     * all done. but we need to keep track of the ones we already handled,
     * this integer shadows the doorbells to allow this behaviour.
     */
    uint32_t transferTrack;
    uint32_t taskCommandTrack;

    /**
     * Helper for latency stats
     * These variables keep track of the latency for every doorbell.
     * Eventually the latenmcies will be put in a histogram.
     */
    Tick transactionStart[32];
    Tick idlePhaseStart;

    /**
     * logic units connected to the UFS Host device
     * Note again that the "device" as such is represented by one or multiple
     * logic units.
     */
    std::vector<UFSSCSIDevice*> UFSDevice;

    /**
     * SCSI reply structure, used for direct answering. Might be refered to
     * during the assembly of the reply (data, and response; e.g. if
     * something goes wrong along the way, the reply will be different)
     */
    struct SCSIReply request_out_datain;

    /**
     * SCSI resume info
     * information structure for SCSI resume. it keeps track of all the
     * information that is needed to successfully complete the transaction
     * (response addresses, communicated information so far, etc.).
     */
    struct SCSIResumeInfo SCSIInfo;

    /**
     * To finish the transaction one needs information about the original
     * message. This is stored in this queue
     * transferEnd uses the same structure as transferStartInfo, because all
     * the information it needs is in there. It improves readability in the
     * cc file.
     */
    std::deque<struct transferStart> transferEnd;

    /**
     * When a task/transfer is started it needs information about the
     * task/transfer it is about to perform. This is defined in these
     * structures. If multiple tasks/transfers are issued at the same time,
     * they still need to be fetched one by one. They then need to be
     * executed in the order specified by the UFS standard (least significant
     * doorbell first). The tasks/transfers are placed in the queue in that
     * specific order.
     */
    std::deque<struct taskStart> taskInfo;
    std::deque<struct transferStart> transferStartInfo;

    /**
     * Information to get a DMA transaction
     */
    std::deque<struct writeToDiskBurst> dmaWriteInfo;

    /**
     * Information from DMA transaction to disk
     */
    std::deque<struct transferInfo> SSDWriteinfo;

    /**
     * Information from the Disk, waiting to be pushed to the DMA
     */
    std::deque<struct transferInfo> SSDReadPending;

    /**
     * garbage queue, ensure clearing of the allocated memory
     */
    std::deque<struct UTPTransferReqDesc*> garbage;

    /**
     * RequestHandler stats
     */
    struct UFSHostDeviceStats stats;

    /**
     * Transfer flow events
     * Basically these events form two queues, one from memory to UFS device
     * (DMA) and one from device to flash (SSD). The SSD "queue" is
     * maintained by the flash and the lun classes and does not form a queue
     * of events as such, but rather a queue of information. This can be done
     * because the flow of the events is completely in the control of these
     * classes. (Whereas in the DMA case we rely on an external class)
     */
    std::deque<EventFunctionWrapper> readDoneEvent;
    std::deque<EventFunctionWrapper> writeDoneEvent;

    /**
     * Callbacks for the logic units. One to indicate the completion of a
     * transaction, the other one to indicate the completion of a read
     * action.
     */
    Callback* transferDoneCallback;
    Callback* memReadCallback;

    /**
     * The events that control the functionality.
     * After a doorbell has been set, either a taskevent or a transfer event
     * is scheduled. A transfer event might schedule a SCSI event, all events
     * sequences end with an UTP event, which can be considered as the event
     * which answers the doorbell.
     */
    /**
     * Wait for the SCSI specific data to arive
     */
    EventFunctionWrapper SCSIResumeEvent;

    /**
     * Wait for the moment where we can send the last frame
     */
    EventFunctionWrapper UTPEvent;

    /**
     * Event after a read to clean up the UTP data structures
     */
    std::deque<EventFunctionWrapper> readGarbageEventQueue;

    /**
     * Multiple tasks transfers can be scheduled at once for the device, the
     * only thing we know for sure about them is that they will happen in a
     * first come first serve order; hence we need to queue.
     */
    std::deque<EventFunctionWrapper> taskEventQueue;
    std::deque<EventFunctionWrapper> transferEventQueue;

    /**
     * Bits of interest within UFS data packages
     */
    static const unsigned int UTPTransferREQCOMPL = 0x01;//UFS_BIT(0)
    static const unsigned int UTPTaskREQCOMPL = 0x200;//UFS_BIT(9)
    static const unsigned int UICCommandCOMPL = 0x400;//UFS_BIT(10)
    static const unsigned int UICCommandReady = 0x08;//UFS_BIT(3)

    /*
     * UFSHCI Registers; please refer to
     * http://www.jedec.org/standards-documents/results/jesd223
     * for their definition.
     */
    enum UFSHCIRegisters {
        regControllerCapabilities = 0x00,
        regUFSVersion = 0x08,
        regControllerDEVID = 0x10,
        regControllerPRODID = 0x14,
        regInterruptStatus = 0x20,
        regInterruptEnable = 0x24,
        regControllerStatus = 0x30,
        regControllerEnable = 0x34,
        regUICErrorCodePHYAdapterLayer = 0x38,
        regUICErrorCodeDataLinkLayer = 0x3C,
        regUICErrorCodeNetworkLayer = 0x40,
        regUICErrorCodeTransportLayer = 0x44,
        regUICErrorCodeDME = 0x48,
        regUTPTransferREQINTAGGControl = 0x4C,
        regUTPTransferREQListBaseL = 0x50,
        regUTPTransferREQListBaseH = 0x54,
        regUTPTransferREQDoorbell = 0x58,
        regUTPTransferREQListClear = 0x5C,
        regUTPTransferREQListRunStop = 0x60,
        regUTPTaskREQListBaseL = 0x70,
        regUTPTaskREQListBaseH = 0x74,
        regUTPTaskREQDoorbell = 0x78,
        regUTPTaskREQListClear = 0x7C,
        regUTPTaskREQListRunStop = 0x80,
        regUICCommand = 0x90,
        regUICCommandArg1 = 0x94,
        regUICCommandArg2 = 0x98,
        regUICCommandArg3 = 0x9C
    };
};

#endif //__DEV_ARM_UFS_DEVICE_HH__