1/*
2 * Copyright (c) 2013-2015 ARM Limited
3 * All rights reserved
4 *
5 * The license below extends only to copyright in the software and shall
6 * not be construed as granting a license to any other intellectual
7 * property including but not limited to intellectual property relating
8 * to a hardware implementation of the functionality of the software
9 * licensed hereunder.  You may use the software subject to the license
10 * terms below provided that you ensure that this notice is replicated
11 * unmodified and in its entirety in all distributions of the software,
12 * modified or unmodified, in source code or in binary form.
13 *
14 * Redistribution and use in source and binary forms, with or without
15 * modification, are permitted provided that the following conditions are
16 * met: redistributions of source code must retain the above copyright
17 * notice, this list of conditions and the following disclaimer;
18 * redistributions in binary form must reproduce the above copyright
19 * notice, this list of conditions and the following disclaimer in the
20 * documentation and/or other materials provided with the distribution;
21 * neither the name of the copyright holders nor the names of its
22 * contributors may be used to endorse or promote products derived from
23 * this software without specific prior written permission.
24 *
25 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
26 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
27 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
28 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
29 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
30 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
31 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
32 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
33 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
34 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
35 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
36 *
37 * Authors: Rene de Jong
38 */
39
40
41/** @file
42 * This is a base class for UFS devices
43 * The UFS interface consists out of one host controller which connects a
44 * number of devices which together contain up to 8 logic units. A Logical
45 * Unit is an externally addressable, independent, processing entity that
46 * processes SCSI tasks (commands) and performs task management functions.
47 * The decision has been made to abstract the device away, and model the
48 * different logic units. Effectively this means that there is one Host layer
49 * which handles all the UFS commands (everything UTP, UPIU and UNIpro
50 * related) and a SCSI layer, which handles the SCSI interpretation and the
51 * interaction with the "disk" (effectively the LBA that that particular
52 * Logic Unit controls). Each Logic unit should therefor control a disk image
53 * and a timing model. The UFS protocol has three types of commands
54 * (explained later). Each has different phases and each phase need to wait
55 * for its particular data. This is the reason that this model contains a lot
56 * of events. For clarity, a state diagram in doxygen has been provided. To
57 * fully apreciate the stages that the model flows through, the states have
58 * been broken into three state diagrams. It is best if one imagines the
59 * command flow state machine to be happening in the UFSHost layer, and the
60 * other two to flow through all the layers of the model (UFS host, SCSI and
61 * NVM model). See it as a quarry, one state diagram is moving the crane into
62 * place, and the other ones are transporting the dirt down, or the valuables
63 * up. For complete information about the working of UFS please refer to
64 * http://www.jedec.org/standards-documents/results/jesd220 or
65 * http://www.jedec.org/standards-documents/results/jesd223
66 * The documents are available free of charge, although you will need to have
67 * an acount.
68 */
69
70/** UFS command flow state machine
71 *digraph CommandFlow{
72    node [fontsize=10];
73    IDLE -> transferHandler
74    [ label=" transfer/task/command request " fontsize=6];
75    transferHandler -> command
76    [ label=" It is a command " fontsize=6];
77    command -> IDLE
78    [ label=" Command done, no further action " fontsize=6];
79    transferHandler -> taskStart
80    [ label=" It is a task " fontsize=6];
81    taskStart -> finalUTP
82    [ label=" Task handled, now acknowledge (UFS) " fontsize=6];
83    transferHandler -> transferStart
84    [ label=" It is a transfer " fontsize=6];
85    transferStart -> SCSIResume
86    [ label=" Transfer, obtain the specific command " fontsize=6];
87    SCSIResume -> DiskDataFlowPhase
88    [ label=" Disk data transfer (see other graphs) " fontsize=6];
89    SCSIResume -> DeviceDataPhase
90    [ label=" Device info transfer (handled in SCSIResume) "
91        fontsize=6];
92    DiskDataFlowPhase -> transferDone
93    [ label=" Transfer done, acknowledge SCSI command " fontsize=6];
94    DeviceDataPhase -> transferDone
95    [ label=" Transfer done, acknowledge SCSI command " fontsize=6];
96    transferDone -> finalUTP
97    [ label=" Transfer handled, now acknowledge (UFS) " fontsize=6];
98    finalUTP -> readDone
99    [ label=" All handled, clear data structures " fontsize=6];
100    readDone -> IDLE
101    [ label=" All handled, nothing outstanding " fontsize=6];
102    readDone -> transferHandler
103    [ label=" All handled, handle next outstanding " fontsize=6];
104    }
105 */
106/** UFS read transaction flow state machine
107 digraph readFlow{
108    node [fontsize=10];
109    getScatterGather -> commitReadFromDisk
110    [ label=" Put the information about the data transfer to the disk "
111        fontsize=6];
112    commitReadFromDisk -> waitForReads
113    [ label=" Push the reads to the flashmodel and wait for callbacks "
114        fontsize=6];
115    waitForReads -> pushToDMA
116    [ label=" Push to the DMA and wait for them to finish " fontsize=6];
117    pushToDMA -> waitForReads
118    [ label=" Wait for the next disk event " fontsize=6];
119    pushToDMA -> waitForDMA
120    [ label=" Wait for the last DMA transfer to finish " fontsize=6];
121    waitForDMA -> finishTransfer
122    [ label=" Continue with the command flow " fontsize=6];
123    }
124 */
125/** UFS write transaction flow state machine
126 digraph WriteFlow{
127    node [fontsize=10];
128    getScatterGather -> getFromDMA
129    [ label=" Put the transfer information to the DMA " fontsize=6];
130    getFromDMA -> waitForDMA
131    [ label=" Wait for dma actions to arrive " fontsize=6];
132    waitForDMA -> pushToDisk
133    [ label=" Push arrived DMA to disk " fontsize=6];
134    pushToDisk -> waitForDMA
135    [ label=" Wait for next DMA action " fontsize=6];
136    pushToDisk -> waitForDisk
137    [ label=" All DMA actions are done, wait for disk " fontsize=6];
138    waitForDisk -> finishTransfer
139    [ label=" All transactions are done , continue the command flow "
140        fontsize=6];
141    }
142 */
143
144#ifndef __DEV_ARM_UFS_DEVICE_HH__
145#define __DEV_ARM_UFS_DEVICE_HH__
146
147#include <deque>
148
149#include "base/addr_range.hh"
150#include "base/bitfield.hh"
151#include "base/statistics.hh"
152#include "debug/UFSHostDevice.hh"
153#include "dev/arm/abstract_nvm.hh"
154#include "dev/arm/base_gic.hh"
155#include "dev/storage/disk_image.hh"
156#include "dev/dma_device.hh"
157#include "dev/io_device.hh"
158#include "mem/packet.hh"
159#include "mem/packet_access.hh"
160#include "params/UFSHostDevice.hh"
161#include "sim/serialize.hh"
162#include "sim/stats.hh"
163
164/**
165 * Host controller layer: This is your Host controller
166 * This layer handles the UFS functionality.
167 * It tracks all the different transaction stages and uses
168 * the device layer and the flash layer to determine the transaction flow.
169 */
170class UFSHostDevice : public DmaDevice
171{
172  public:
173
174    UFSHostDevice(const UFSHostDeviceParams* p);
175
176    DrainState drain() override;
177    void checkDrain();
178    void serialize(CheckpointOut &cp) const override;
179    void unserialize(CheckpointIn &cp) override;
180
181  private:
182    /**
183     * Host Controller Interface
184     * This is a set of registers that allow the driver to control the
185     * transactions to the flash devices.
186     * As defined in:
187     * http://www.jedec.org/standards-documents/results/jesd223
188     */
189    struct HCIMem {
190        /**
191         * Specify the host capabilities
192         */
193        uint32_t HCCAP;
194        uint32_t HCversion;
195        uint32_t HCHCDDID;
196        uint32_t HCHCPMID;
197
198        /**
199         * Operation and runtime registers
200         */
201        uint32_t ORInterruptStatus;
202        uint32_t ORInterruptEnable;
203        uint32_t ORHostControllerStatus;
204        uint32_t ORHostControllerEnable;
205        uint32_t ORUECPA;
206        uint32_t ORUECDL;
207        uint32_t ORUECN;
208        uint32_t ORUECT;
209        uint32_t ORUECDME;
210        uint32_t ORUTRIACR;
211
212        /**
213         * vendor specific register
214         */
215        uint32_t vendorSpecific;
216
217        /**
218         * Transfer control registers
219         */
220        uint32_t TRUTRLBA;
221        uint32_t TRUTRLBAU;
222        uint32_t TRUTRLDBR;
223        uint32_t TRUTRLCLR;
224        uint32_t TRUTRLRSR;
225
226        /**
227         * Task control registers
228         */
229        uint32_t TMUTMRLBA;
230        uint32_t TMUTMRLBAU;
231        uint32_t TMUTMRLDBR;
232        uint32_t TMUTMRLCLR;
233        uint32_t TMUTMRLRSR;
234
235        /**
236         * Command registers
237         */
238        uint32_t CMDUICCMDR;
239        uint32_t CMDUCMDARG1;
240        uint32_t CMDUCMDARG2;
241        uint32_t CMDUCMDARG3;
242    };
243
244    /**
245     * All the data structures are defined in the UFS standard
246     * This standard be found at the JEDEC website free of charge
247     * (login required):
248     * http://www.jedec.org/standards-documents/results/jesd220
249     */
250
251    /**
252     * struct UTPUPIUHeader - UPIU header structure
253     * dWord0: UPIU header DW-0
254     * dWord1: UPIU header DW-1
255     * dWord2: UPIU header DW-2
256     */
257    struct UTPUPIUHeader {
258        uint32_t dWord0;
259        uint32_t dWord1;
260        uint32_t dWord2;
261    };
262
263    /**
264     * struct UTPUPIURSP - Response UPIU structure
265     * header: UPIU header DW-0 to DW-2
266     * residualTransferCount: Residual transfer count DW-3
267     * reserved: Reserved DW-4 to DW-7
268     * senseDataLen: Sense data length DW-8 U16
269     * senseData: Sense data field DW-8 to DW-12
270     */
271    struct UTPUPIURSP {
272        struct UTPUPIUHeader header;
273        uint32_t residualTransferCount;
274        uint32_t reserved[4];
275        uint16_t senseDataLen;
276        uint8_t senseData[18];
277    };
278
279    /**
280     * struct UTPUPIUTaskReq - Task request UPIU structure
281     * header - UPIU header structure DW0 to DW-2
282     * inputParam1: Input param 1 DW-3
283     * inputParam2: Input param 2 DW-4
284     * inputParam3: Input param 3 DW-5
285     * reserved: Reserver DW-6 to DW-7
286     */
287    struct UTPUPIUTaskReq {
288        struct UTPUPIUHeader header;
289        uint32_t inputParam1;
290        uint32_t inputParam2;
291        uint32_t inputParam3;
292        uint32_t reserved[2];
293    };
294
295    /**
296     * struct UFSHCDSGEntry - UFSHCI PRD Entry
297     * baseAddr: Lower 32bit physical address DW-0
298     * upperAddr: Upper 32bit physical address DW-1
299     * reserved: Reserved for future use DW-2
300     * size: size of physical segment DW-3
301     */
302    struct UFSHCDSGEntry {
303        uint32_t baseAddr;
304        uint32_t upperAddr;
305        uint32_t reserved;
306        uint32_t size;
307    };
308
309    /**
310     * struct UTPTransferCMDDesc - UFS Commad Descriptor structure
311     * commandUPIU: Command UPIU Frame address
312     * responseUPIU: Response UPIU Frame address
313     * PRDTable: Physcial Region Descriptor
314     * All lengths as defined by JEDEC220
315     */
316    struct UTPTransferCMDDesc {
317        uint8_t commandUPIU[128];
318        uint8_t responseUPIU[128];
319        struct UFSHCDSGEntry PRDTable[128];
320    };
321
322    /**
323     * UPIU tranfer message.
324     */
325    struct UPIUMessage {
326        struct UTPUPIUHeader header;
327        uint32_t dataOffset;
328        uint32_t dataCount;
329        std::vector<uint32_t> dataMsg;
330    };
331
332    /**
333     * struct UTPTransferReqDesc - UTRD structure
334     * header: UTRD header DW-0 to DW-3
335     * commandDescBaseAddrLo: UCD base address low DW-4
336     * commandDescBaseAddrHi: UCD base address high DW-5
337     * responseUPIULength: response UPIU length DW-6
338     * responseUPIUOffset: response UPIU offset DW-6
339     * PRDTableLength: Physical region descriptor length DW-7
340     * PRDTableOffset: Physical region descriptor offset DW-7
341     */
342    struct UTPTransferReqDesc {
343
344        /**
345         * struct RequestDescHeader
346         * dword0: Descriptor Header DW0
347         * dword1: Descriptor Header DW1
348         * dword2: Descriptor Header DW2
349         * dword3: Descriptor Header DW3
350         */
351        struct RequestDescHeader {
352            uint32_t dWord0;
353            uint32_t dWord1;
354            uint32_t dWord2;
355            uint32_t dWord3;
356        } header;
357
358        /* DW 4-5*/
359        uint32_t commandDescBaseAddrLo;
360        uint32_t commandDescBaseAddrHi;
361
362        /* DW 6 */
363        uint16_t responseUPIULength;
364        uint16_t responseUPIUOffset;
365
366        /* DW 7 */
367        uint16_t PRDTableLength;
368        uint16_t PRDTableOffset;
369    };
370
371    /**
372     * SCSI reply structure. In here is all the information that is needed to
373     * build a SCSI reply.
374     */
375    struct SCSIReply {
376        void reset() {
377            memset(static_cast<void*>(this), 0, sizeof(*this));
378        }
379
380        uint8_t status;
381        uint32_t msgSize;
382        uint8_t LUN;
383        struct UPIUMessage message;
384        uint8_t senseSize;
385        uint8_t expectMore;//0x01 is for writes, 0x02 is for reads
386        uint64_t offset;
387        uint8_t senseCode[19];
388    };
389
390    /**
391     * Logic unit information structure. SCSI requires information of each LUN.
392     * This structure is defined in the SCSI standard, and can also be found in
393     * the UFS standard. http://www.jedec.org/standards-documents/results/jesd220
394     */
395    struct LUNInfo {
396        uint32_t dWord0;
397        uint32_t dWord1;
398        uint32_t vendor0;
399        uint32_t vendor1;
400        uint32_t product0;
401        uint32_t product1;
402        uint32_t product2;
403        uint32_t product3;
404        uint32_t productRevision;
405    };
406
407    /**
408     * Different events, and scenarios require different types of information.
409     * Keep in mind that for a read-from-disk transaction the host at first a
410     * datastructure fetches to determine where and what the command is, then the
411     * command fetches and the structure fetches to determine where the
412     * different read transactions should be placed and then transfers all the
413     * read fragments. It then answers to the original caller with two replies,
414     * one for the command, and one for UFS. Each of these stages trigger a
415     * different event, and each event needs to know what happened in the
416     * previous stage and what is going to happen in the current one. This
417     * happens also for writes, SCSI maintanance, UFS maintanance, command
418     * management and task management.
419     */
420
421    /**
422     * Transfer information.
423     * @filePointer this does not point to a file, but to a position on the disk
424     * image (which is from the software systems perspective a position in a file)
425     */
426    struct transferInfo {
427        std::vector <uint8_t> buffer;
428        uint32_t size;
429        uint64_t offset;
430        uint32_t filePointer;
431        uint32_t lunID;
432    };
433
434    /**
435     * transfer completion info.
436     * This information is needed by transferDone to finish the transfer.
437     */
438    struct transferDoneInfo {
439        Addr responseStartAddr;
440        uint32_t reqPos;
441        struct UTPUPIURSP requestOut;
442        uint32_t size;
443        Addr address;
444        uint8_t *destination;
445        bool finished;
446        uint32_t lunID;
447    };
448
449    /**
450     * Transfer start information.
451     */
452    struct transferStart {
453        struct UTPTransferReqDesc* destination;
454        uint32_t mask;
455        Addr address;
456        uint32_t size;
457        uint32_t done;
458        uint32_t lun_id;
459    };
460
461    /**
462     * Task start information. This is for the device, so no lun id needed.
463     */
464    struct taskStart {
465        struct UTPUPIUTaskReq destination;
466        uint32_t mask;
467        Addr address;
468        uint32_t size;
469        bool done;
470    };
471
472    /**
473     * After a SCSI command has been identified, the SCSI resume function will
474     * handle it. This information will provide context information.
475     */
476    struct SCSIResumeInfo {
477        struct UTPTransferReqDesc* RequestIn;
478        int reqPos;
479        Addr finalAddress;
480        uint32_t finalSize;
481        std::vector <uint8_t> destination;
482        uint32_t done;
483    };
484
485    /**
486     * Disk transfer burst information. Needed to allow communication between the
487     * disk transactions and dma transactions.
488     */
489    struct writeToDiskBurst {
490        Addr start;
491        uint64_t SCSIDiskOffset;
492        uint32_t size;
493        uint32_t LUN;
494    };
495
496    /**
497     * Statistics
498     */
499    struct UFSHostDeviceStats {
500        /** Queue lengths */
501        Stats::Scalar currentSCSIQueue;
502        Stats::Scalar currentReadSSDQueue;
503        Stats::Scalar currentWriteSSDQueue;
504
505        /** Amount of data read/written */
506        Stats::Scalar totalReadSSD;
507        Stats::Scalar totalWrittenSSD;
508        Stats::Scalar totalReadDiskTransactions;
509        Stats::Scalar totalWriteDiskTransactions;
510        Stats::Scalar totalReadUFSTransactions;
511        Stats::Scalar totalWriteUFSTransactions;
512
513        /** Average bandwidth for reads and writes */
514        Stats::Formula averageReadSSDBW;
515        Stats::Formula averageWriteSSDBW;
516
517        /** Average Queue lengths*/
518        Stats::Average averageSCSIQueue;
519        Stats::Average averageReadSSDQueue;
520        Stats::Average averageWriteSSDQueue;
521
522        /** Number of doorbells rung*/
523        Stats::Formula curDoorbell;
524        Stats::Scalar maxDoorbell;
525        Stats::Average averageDoorbell;
526
527        /** Histogram of latencies*/
528        Stats::Histogram transactionLatency;
529        Stats::Histogram idleTimes;
530    };
531
532    /**
533     * device layer: This is your Logic unit
534     * This layer implements the SCSI functionality of the UFS Device
535     * One logic unit controls one or more disk partitions
536     */
537    class UFSSCSIDevice: SimObject
538    {
539      public:
540        /**
541         * Constructor and destructor
542         */
543        UFSSCSIDevice(const UFSHostDeviceParams* p, uint32_t lun_id, Callback*
544                      transfer_cb, Callback *read_cb);
545        ~UFSSCSIDevice();
546
547        /**
548         * SCSI command handle function; determines what the command is and
549         * returns a reply structure that allows the host device to continue
550         * with the transfer.
551         */
552        struct SCSIReply SCSICMDHandle(uint32_t* SCSI_msg);
553
554        /**
555         * Disk access functions. These will transfer the data from/to the disk
556         */
557
558        /**
559         * Read flash. read the data from the disk image. This function
560         * doesn't model timing behaviour
561         */
562        void readFlash(uint8_t* readaddr, uint64_t offset, uint32_t size);
563
564        /**
565         * Write flash. write the data to the disk image. This function
566         * doesn't model timing behaviour
567         */
568        void writeFlash(uint8_t* writeaddr, uint64_t offset, uint32_t size);
569
570        /**
571         * finished command. Probe to find out wether this logic unit
572         * finished its transfer and triggered the callback; The host needs
573         * this to handle the final part of the transaction.
574         */
575        bool finishedCommand() const {return transferCompleted;};
576
577        /**
578         * Clear signal. Handle for the host to clear the transfer complete
579         * signal.
580         */
581        void clearSignal() {transferCompleted = false;};
582
583        /**
584         * Finished read. Probe to find out which logic unit finished its
585         * read. This is needed, because multiple units can do transactions
586         * at the same time, and need to push back data at the right time in
587         * the right order. (because writes work the other way round, they do
588         * not need this mechanism)
589         */
590        bool finishedRead() const {return readCompleted;};
591
592        /**
593         * Clear signal. Handle for the host to clear the read complete
594         * signal.
595         */
596        void clearReadSignal() {readCompleted = false;};
597
598        /**
599         * Start the transactions to (and from) the disk
600         * The host will queue all the transactions. Once the next phase
601         * commences, this function should be started.
602         */
603        void SSDReadStart(uint32_t total_read);
604        void SSDWriteStart();
605
606        /**
607         * Sets total amount of write transactions that needs to be made.
608         * First they need to be fetched via DMA, so this value is needed in
609         * a later stage.
610         */
611        void setTotalWrite(uint32_t total_write) {totalWrite = total_write;};
612
613        /**
614         * End of transfer information
615         */
616        transferDoneInfo transferInfo;
617
618        /**
619         * Information message queues, as there can be multiple messages
620         * queued for handling in this system. These are the main
621         * communication interfaces between the Host and the device layers
622         */
623
624        /**
625         * SCSIInfoQueue: each LU handles its own SCSI commands.
626         */
627        std::deque<struct SCSIResumeInfo> SCSIInfoQueue;
628
629        /**
630         * SSDReadInfo: Structure from disk to dma, that contains data, and
631         * helper info to get it to the right place in the memory.
632         */
633        std::deque<struct transferInfo> SSDReadInfo;
634
635        /**
636         * SSDWriteDoneInfo: Structure from dma to disk, that contains data,
637         * and helper info to get it to the right place in the memory.
638         * The done is added because it is going to the last phase of the
639         * write transfer.
640         */
641        std::deque<struct transferInfo> SSDWriteDoneInfo;
642
643      private:
644        /**
645         * Functions to indicate that the action to the SSD has completed.
646         */
647        /**
648         * Read Call back; This is the callback function for the memory model
649         */
650        void readCallback();
651
652        /**
653         * SSD Read done; Determines if the final callback of the transaction
654         * should be made at the end of a read transfer.
655         */
656        void SSDReadDone();
657
658        /**
659         * SSD Write Done; This is the callback function for the memory model.
660         */
661        void SSDWriteDone();
662
663        /**
664         * Status of SCSI. This may be linked to a status check in the future.
665         * For now it (mainly) fills a data structure with sense information
666         * for a successfull transaction
667         */
668        void statusCheck(uint8_t status, uint8_t* sensecodelist);
669
670        /**
671         * set signal to indicate that the transaction has been completed.
672         */
673        void setSignal() {transferCompleted = true;};
674
675        /**
676         * set signal to indicate that the read action has been completed
677         */
678        void setReadSignal() {readCompleted = true;};
679
680        /**
681         * The objects this model links to.
682         * 1: the disk data model
683         * 2: the memory timing model
684         */
685        DiskImage* flashDisk;
686        AbstractNVM* flashDevice;
687
688        /**
689         * Logic unit dimensions
690         */
691        const uint32_t blkSize;
692        const uint32_t lunAvail;
693        const uint64_t diskSize;
694        const uint32_t capacityLower;
695        const uint32_t capacityUpper;
696
697        /**
698         * Logic unit info; needed for SCSI Info messages and LU
699         * identification
700         */
701        struct LUNInfo lunInfo;
702        const uint32_t lunID;
703
704        /**
705         * Signals to Host layer
706         * 1: signal for transaction completion
707         * 2: signal for read action completion
708         */
709        bool transferCompleted;
710        bool readCompleted;
711
712        /**
713         * Total amount transactions that need to be made
714         */
715        uint32_t totalRead;
716        uint32_t totalWrite;
717
718        /**
719         * transaction progress tracking
720         */
721        uint32_t amountOfWriteTransfers;
722        uint32_t amountOfReadTransfers;
723
724        /**
725         * Callbacks between Host and Device
726         */
727        Callback* signalDone;
728        Callback* deviceReadCallback;
729
730        /**
731         * Callbacks between Device and Memory
732         */
733        Callback* memReadCallback;
734        Callback* memWriteCallback;
735
736        /*
737         * Default response header layout. For more information refer to
738         * chapter 7 http://www.jedec.org/standards-documents/results/jesd220
739         */
740        static const unsigned int UPIUHeaderDataIndWord0 = 0x0000C022;
741        static const unsigned int UPIUHeaderDataIndWord1 = 0x00000000;
742        static const unsigned int UPIUHeaderDataIndWord2 = 0x40000000;
743
744        /*
745         * SCSI mode pages values assigned in ufs_device.cc
746         * The mode pages give device specific information via the SCSI
747         * protocol. They are defined in
748         * http://www.jedec.org/standards-documents/results/jesd220
749         */
750        static const unsigned int controlPage[3];
751        static const unsigned int recoveryPage[3];
752        static const unsigned int cachingPage[5];
753
754        /*
755         * SCSI command set; defined in
756         * http://www.jedec.org/standards-documents/results/jesd220
757         */
758        enum SCSICommandSet {
759            SCSIInquiry = 0x12,
760            SCSIRead6 = 0x08,
761            SCSIRead10 = 0x28,
762            SCSIRead16 = 0x88,
763            SCSIReadCapacity10 = 0x25,
764            SCSIReadCapacity16 = 0x9E,
765            SCSIReportLUNs = 0xA0,
766            SCSIStartStop = 0x1B,
767            SCSITestUnitReady = 0x00,
768            SCSIVerify10 = 0x2F,
769            SCSIWrite6 = 0x0A,
770            SCSIWrite10 = 0x2A,
771            SCSIWrite16 = 0x8A,
772            SCSIFormatUnit = 0x04,
773            SCSISendDiagnostic = 0x1D,
774            SCSISynchronizeCache = 0x35,
775            //UFS SCSI additional command set for full functionality
776            SCSIModeSelect10 = 0x55,
777            SCSIModeSense6 = 0x1A,
778            SCSIModeSense10 = 0x5A,
779            SCSIRequestSense = 0x03,
780            SCSIUnmap = 0x42,
781            SCSIWriteBuffer = 0x3B,
782            SCSIReadBuffer = 0x3C,
783            //SCSI commands not supported by UFS; but Linux send them anyway
784            SCSIMaintenanceIn = 0xA3
785        };
786
787        /*
788         * SCSI status codes; defined in
789         * http://www.jedec.org/standards-documents/results/jesd220
790         */
791        enum SCSIStatusCodes {
792            SCSIGood = 0x00,
793            SCSICheckCondition = 0x02,
794            SCSIConditionGood = 0x04,
795            SCSIBusy = 0x08,
796            SCSIIntermediateGood = 0x10,
797            SCSIIntermediatCGood = 0x14,
798            SCSIReservationConflict = 0x18,
799            SCSICommandTerminated = 0x22,
800            SCSITaskSetFull = 0x28,
801            SCSIACAActive = 0x30,
802            SCSITaskAborted = 0x40
803        };
804
805        /*
806         * SCSI sense codes; defined in
807         * http://www.jedec.org/standards-documents/results/jesd220
808         */
809        enum SCSISenseCodes {
810            SCSINoSense = 0x00,
811            SCSIRecoverdError = 0x01,
812            SCSINotReady = 0x02,
813            SCSIMediumError = 0x03,
814            SCSIHardwareError = 0x04,
815            SCSIIllegalRequest = 0x05,
816            SCSIUnitAttention = 0x06,
817            SCSIDataProtect = 0x07,
818            SCSIBlankCheck = 0x08,
819            SCSIAbortedCommand = 0x0B,
820            SCSIVolumeOverflow = 0x0D,
821            SCSIMisCompare = 0x0E
822        };
823
824    };
825
826    //All access functions are inherrited; no need to make them public
827    /**
828     * Address range functions
829     */
830    AddrRangeList getAddrRanges() const override;
831
832    /**
833     * register access functions
834     */
835    Tick read(PacketPtr pkt) override;
836    Tick write(PacketPtr pkt) override;
837    // end of access functions
838
839    /**
840     * Initialization function. Sets the sefault HCI register values
841     */
842    void setValues();
843
844    /**
845     * Handler functions. Each function handles a different stage of the
846     * transfer. Note that the UFS protocol specifies three types of messages
847     * to the host (and devices):
848     * 1: Command (to Host specifically)
849     * 2: Task (to device; to control flow, not for data)
850     * 3: Transfer (to device; to transfer data)
851     */
852    /**
853     * request handler. This function finds the cause of the request and
854     * triggers the right follow-up action (command handler, task handler,
855     * or transferhandler)
856     */
857    void requestHandler();
858
859    /**
860     * Command handler function. Handles the command send to the Host
861     * controller
862     */
863    void commandHandler();
864
865    /**
866     * Task Start function. Starts the task handler once the task data
867     * structure has arrived
868     */
869    void taskStart();
870
871    /**
872     * Task handler function. Handles the tasks send to the devices
873     * because there are not many tasks implemented yet this is kept in the
874     * Host controller layer
875     */
876    void taskHandler(struct UTPUPIUTaskReq* request_in,
877                     uint32_t req_pos, Addr finaladdress, uint32_t finalsize);
878
879    /**
880     * Transfer Start function. Starts the transfer handler once the transfer
881     * data structure has arrived
882     */
883    void transferStart();
884
885    /**
886     * Transfer handler function. Handles the transfers send to the devices
887     * Important to understand here is that a Logic unit is not a device (a
888     * device can contain multiple logic units). This function analyses the
889     * first data structure that has been transfered. Which will tell the
890     * host to expect SCSI frames for the rest of the transaction. Note that
891     * the host has no indication whatsoever which LU to address. That will
892     * follow in the next transaction.
893     */
894    void transferHandler(struct UTPTransferReqDesc*
895                         request_in, int req_pos, Addr finaladdress,
896                         uint32_t finalsize, uint32_t done);
897
898    /**
899     * Transfer SCSI function. Determines which Logic unit to address and
900     * starts the SCSI resume function
901     */
902    void SCSIStart();
903
904    /**
905     * Starts the scsi handling function in the apropriate Logic unit,
906     * prepares the right data transfer scheme and kicks it off.
907     */
908    void SCSIResume(uint32_t lun_id);
909
910    /**
911     * LU callback function to indicate that the action has completed.
912     */
913    void LUNSignal();
914
915    /**
916     * transfer done, the beginning of the final stage of the transfer.
917     * Acknowledges UPIU frame and prepares the UTP response frame
918     */
919    void transferDone(Addr responseStartAddr, uint32_t req_pos,
920                      struct UTPUPIURSP request_out, uint32_t size,
921                      Addr address, uint8_t* destination, bool finished,
922                      uint32_t lun_id);
923    /**
924     * final UTP, sends the last acknowledge data structure to the system;
925     * prepares the clean up functions.
926     */
927    void finalUTP();
928
929    /**
930     * Interrupt control functions
931     */
932    void clearInterrupt();
933    void generateInterrupt();
934
935    /**
936     * DMA transfer functions
937     * These allow the host to push/pull the data to the memory
938     * The provided event indicates what the next phase it that will handle
939     * the obtained data, or what the follow up action is once the data has
940     * been pushed to the memory
941     */
942    void writeDevice(Event* additional_action, bool toDisk, Addr start,
943                     int size, uint8_t* destination, uint64_t SCSIDiskOffset,
944                     uint32_t lun_id);
945    void readDevice(bool lastTransfer, Addr SCSIStart, uint32_t SCSISize,
946                    uint8_t* SCSIDestination, bool no_cache,
947                    Event* additional_action);
948
949    /**
950     * Disk transfer management functions
951     * these set up the queues, and initiated them, leading to the data
952     * transaction timing model based on the scatter gather list constructed
953     * in SCSIresume.
954     */
955    void manageWriteTransfer(uint8_t LUN, uint64_t offset, uint32_t
956                             sg_table_length, struct UFSHCDSGEntry* sglist);
957    void manageReadTransfer(uint32_t size, uint32_t LUN, uint64_t offset,
958                            uint32_t sg_table_length,
959                            struct UFSHCDSGEntry* sglist);
960
961    /**
962     * Read done
963     * Started at the end of a transaction after the last read action. Cleans
964     * up UTP descriptor and other remaining data structures. It also raises
965     * the interrupt.
966     */
967    void readDone();
968
969    /**
970     * Write done
971     * After a DMA write with data intended for the disk, this function is
972     * called. It ensures that the disk image is modified, and that the
973     * correct timing function is triggered.
974     */
975    void writeDone();
976
977    /**
978     * Read callback
979     * Call back function for the logic units to indicate the completion of
980     * a read action. Note that this is needed because the read functionality
981     * needs to push data structures back to the memory.
982     */
983    void readCallback();
984
985    /**
986     * Read garbage
987     * A read from disk data structure can vary in size and is therefor
988     * allocated on creation. It can only be destroyed once that particular
989     * read action has completed. This function is called on completion of a
990     * read from disk action to handle this.
991     */
992    void readGarbage();
993
994    /**register statistics*/
995    void regStats() override;
996
997    /**
998     * Host controller information
999     */
1000    const Addr pioAddr;
1001    const Addr pioSize;
1002    const Tick pioDelay;
1003    const int intNum;
1004    BaseGic* gic;
1005    const uint32_t lunAvail;
1006    const uint8_t UFSSlots;
1007
1008    /**
1009     * Host controller memory
1010     */
1011    HCIMem UFSHCIMem;
1012
1013    /**
1014     * Track number of DMA transactions in progress
1015     */
1016    int readPendingNum;
1017    int writePendingNum;
1018
1019    /**
1020     * Statistics helper variables
1021     * Active doorbells indicates how many doorbells are in teh process of
1022     * being handled.
1023     * Pending doorbells have been handled and are waiting to be acknowledged
1024     * by the host system.
1025     * The doorbell register is 32 bits wide, so one byte is enough to keep
1026     * track of the numbers
1027     */
1028    uint8_t activeDoorbells;
1029    uint8_t pendingDoorbells;
1030
1031    /**
1032     * interrupt verification
1033     * This keeps track of the number of interrupts generated. It is usefull
1034     * for debug purposes. Make sure that the implemented driver prints the
1035     * number of interrupts it has handled so far to fully benefit from this
1036     * feature.
1037     */
1038    uint32_t countInt;
1039
1040    /**
1041     * Track the transfer
1042     * This is allows the driver to "group" certain transfers together by
1043     * using a tag in the UPIU. The messages with the same tag should be
1044     * handled together, i.e. their doorbells should be cleared when they are
1045     * all done. but we need to keep track of the ones we already handled,
1046     * this integer shadows the doorbells to allow this behaviour.
1047     */
1048    uint32_t transferTrack;
1049    uint32_t taskCommandTrack;
1050
1051    /**
1052     * Helper for latency stats
1053     * These variables keep track of the latency for every doorbell.
1054     * Eventually the latenmcies will be put in a histogram.
1055     */
1056    Tick transactionStart[32];
1057    Tick idlePhaseStart;
1058
1059    /**
1060     * logic units connected to the UFS Host device
1061     * Note again that the "device" as such is represented by one or multiple
1062     * logic units.
1063     */
1064    std::vector<UFSSCSIDevice*> UFSDevice;
1065
1066    /**
1067     * SCSI reply structure, used for direct answering. Might be refered to
1068     * during the assembly of the reply (data, and response; e.g. if
1069     * something goes wrong along the way, the reply will be different)
1070     */
1071    struct SCSIReply request_out_datain;
1072
1073    /**
1074     * SCSI resume info
1075     * information structure for SCSI resume. it keeps track of all the
1076     * information that is needed to successfully complete the transaction
1077     * (response addresses, communicated information so far, etc.).
1078     */
1079    struct SCSIResumeInfo SCSIInfo;
1080
1081    /**
1082     * To finish the transaction one needs information about the original
1083     * message. This is stored in this queue
1084     * transferEnd uses the same structure as transferStartInfo, because all
1085     * the information it needs is in there. It improves readability in the
1086     * cc file.
1087     */
1088    std::deque<struct transferStart> transferEnd;
1089
1090    /**
1091     * When a task/transfer is started it needs information about the
1092     * task/transfer it is about to perform. This is defined in these
1093     * structures. If multiple tasks/transfers are issued at the same time,
1094     * they still need to be fetched one by one. They then need to be
1095     * executed in the order specified by the UFS standard (least significant
1096     * doorbell first). The tasks/transfers are placed in the queue in that
1097     * specific order.
1098     */
1099    std::deque<struct taskStart> taskInfo;
1100    std::deque<struct transferStart> transferStartInfo;
1101
1102    /**
1103     * Information to get a DMA transaction
1104     */
1105    std::deque<struct writeToDiskBurst> dmaWriteInfo;
1106
1107    /**
1108     * Information from DMA transaction to disk
1109     */
1110    std::deque<struct transferInfo> SSDWriteinfo;
1111
1112    /**
1113     * Information from the Disk, waiting to be pushed to the DMA
1114     */
1115    std::deque<struct transferInfo> SSDReadPending;
1116
1117    /**
1118     * garbage queue, ensure clearing of the allocated memory
1119     */
1120    std::deque<struct UTPTransferReqDesc*> garbage;
1121
1122    /**
1123     * RequestHandler stats
1124     */
1125    struct UFSHostDeviceStats stats;
1126
1127    /**
1128     * Transfer flow events
1129     * Basically these events form two queues, one from memory to UFS device
1130     * (DMA) and one from device to flash (SSD). The SSD "queue" is
1131     * maintained by the flash and the lun classes and does not form a queue
1132     * of events as such, but rather a queue of information. This can be done
1133     * because the flow of the events is completely in the control of these
1134     * classes. (Whereas in the DMA case we rely on an external class)
1135     */
1136    std::deque<EventFunctionWrapper> readDoneEvent;
1137    std::deque<EventFunctionWrapper> writeDoneEvent;
1138
1139    /**
1140     * Callbacks for the logic units. One to indicate the completion of a
1141     * transaction, the other one to indicate the completion of a read
1142     * action.
1143     */
1144    Callback* transferDoneCallback;
1145    Callback* memReadCallback;
1146
1147    /**
1148     * The events that control the functionality.
1149     * After a doorbell has been set, either a taskevent or a transfer event
1150     * is scheduled. A transfer event might schedule a SCSI event, all events
1151     * sequences end with an UTP event, which can be considered as the event
1152     * which answers the doorbell.
1153     */
1154    /**
1155     * Wait for the SCSI specific data to arive
1156     */
1157    EventFunctionWrapper SCSIResumeEvent;
1158
1159    /**
1160     * Wait for the moment where we can send the last frame
1161     */
1162    EventFunctionWrapper UTPEvent;
1163
1164    /**
1165     * Event after a read to clean up the UTP data structures
1166     */
1167    std::deque<EventFunctionWrapper> readGarbageEventQueue;
1168
1169    /**
1170     * Multiple tasks transfers can be scheduled at once for the device, the
1171     * only thing we know for sure about them is that they will happen in a
1172     * first come first serve order; hence we need to queue.
1173     */
1174    std::deque<EventFunctionWrapper> taskEventQueue;
1175    std::deque<EventFunctionWrapper> transferEventQueue;
1176
1177    /**
1178     * Bits of interest within UFS data packages
1179     */
1180    static const unsigned int UTPTransferREQCOMPL = 0x01;//UFS_BIT(0)
1181    static const unsigned int UTPTaskREQCOMPL = 0x200;//UFS_BIT(9)
1182    static const unsigned int UICCommandCOMPL = 0x400;//UFS_BIT(10)
1183    static const unsigned int UICCommandReady = 0x08;//UFS_BIT(3)
1184
1185    /*
1186     * UFSHCI Registers; please refer to
1187     * http://www.jedec.org/standards-documents/results/jesd223
1188     * for their definition.
1189     */
1190    enum UFSHCIRegisters {
1191        regControllerCapabilities = 0x00,
1192        regUFSVersion = 0x08,
1193        regControllerDEVID = 0x10,
1194        regControllerPRODID = 0x14,
1195        regInterruptStatus = 0x20,
1196        regInterruptEnable = 0x24,
1197        regControllerStatus = 0x30,
1198        regControllerEnable = 0x34,
1199        regUICErrorCodePHYAdapterLayer = 0x38,
1200        regUICErrorCodeDataLinkLayer = 0x3C,
1201        regUICErrorCodeNetworkLayer = 0x40,
1202        regUICErrorCodeTransportLayer = 0x44,
1203        regUICErrorCodeDME = 0x48,
1204        regUTPTransferREQINTAGGControl = 0x4C,
1205        regUTPTransferREQListBaseL = 0x50,
1206        regUTPTransferREQListBaseH = 0x54,
1207        regUTPTransferREQDoorbell = 0x58,
1208        regUTPTransferREQListClear = 0x5C,
1209        regUTPTransferREQListRunStop = 0x60,
1210        regUTPTaskREQListBaseL = 0x70,
1211        regUTPTaskREQListBaseH = 0x74,
1212        regUTPTaskREQDoorbell = 0x78,
1213        regUTPTaskREQListClear = 0x7C,
1214        regUTPTaskREQListRunStop = 0x80,
1215        regUICCommand = 0x90,
1216        regUICCommandArg1 = 0x94,
1217        regUICCommandArg2 = 0x98,
1218        regUICCommandArg3 = 0x9C
1219    };
1220};
1221
1222#endif //__DEV_ARM_UFS_DEVICE_HH__
1223