2 * Copyright (c) 2013-2015 ARM Limited
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.
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.
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.
37 * Authors: Rene de Jong
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
70 /** UFS command flow state machine
73 IDLE -> transferHandler
74 [ label=" transfer/task/command request " fontsize=6];
75 transferHandler -> command
76 [ label=" It is a command " fontsize=6];
78 [ label=" Command done, no further action " fontsize=6];
79 transferHandler -> taskStart
80 [ label=" It is a task " fontsize=6];
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) "
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];
99 [ label=" All handled, clear data structures " fontsize=6];
101 [ label=" All handled, nothing outstanding " fontsize=6];
102 readDone -> transferHandler
103 [ label=" All handled, handle next outstanding " fontsize=6];
106 /** UFS read transaction flow state machine
109 getScatterGather -> commitReadFromDisk
110 [ label=" Put the information about the data transfer to the disk "
112 commitReadFromDisk -> waitForReads
113 [ label=" Push the reads to the flashmodel and wait for callbacks "
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];
125 /** UFS write transaction flow state machine
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 "
144 #ifndef __DEV_ARM_UFS_DEVICE_HH__
145 #define __DEV_ARM_UFS_DEVICE_HH__
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"
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.
170 class UFSHostDevice : public DmaDevice
174 UFSHostDevice(const UFSHostDeviceParams* p);
176 DrainState drain() override;
178 void serialize(CheckpointOut &cp) const override;
179 void unserialize(CheckpointIn &cp) override;
183 * Host Controller Interface
184 * This is a set of registers that allow the driver to control the
185 * transactions to the flash devices.
187 * http://www.jedec.org/standards-documents/results/jesd223
191 * Specify the host capabilities
199 * Operation and runtime registers
201 uint32_t ORInterruptStatus;
202 uint32_t ORInterruptEnable;
203 uint32_t ORHostControllerStatus;
204 uint32_t ORHostControllerEnable;
213 * vendor specific register
215 uint32_t vendorSpecific;
218 * Transfer control registers
227 * Task control registers
239 uint32_t CMDUCMDARG1;
240 uint32_t CMDUCMDARG2;
241 uint32_t CMDUCMDARG3;
245 * All the data structures are defined in the UFS standard
246 * This standard be found at the JEDEC website free of charge
248 * http://www.jedec.org/standards-documents/results/jesd220
252 * struct UTPUPIUHeader - UPIU header structure
253 * dWord0: UPIU header DW-0
254 * dWord1: UPIU header DW-1
255 * dWord2: UPIU header DW-2
257 struct UTPUPIUHeader {
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
272 struct UTPUPIUHeader header;
273 uint32_t residualTransferCount;
274 uint32_t reserved[4];
275 uint16_t senseDataLen;
276 uint8_t senseData[18];
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
287 struct UTPUPIUTaskReq {
288 struct UTPUPIUHeader header;
289 uint32_t inputParam1;
290 uint32_t inputParam2;
291 uint32_t inputParam3;
292 uint32_t reserved[2];
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
302 struct UFSHCDSGEntry {
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
316 struct UTPTransferCMDDesc {
317 uint8_t commandUPIU[128];
318 uint8_t responseUPIU[128];
319 struct UFSHCDSGEntry PRDTable[128];
323 * UPIU tranfer message.
326 struct UTPUPIUHeader header;
329 std::vector<uint32_t> dataMsg;
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
342 struct UTPTransferReqDesc {
345 * struct RequestDescHeader
346 * dword0: Descriptor Header DW0
347 * dword1: Descriptor Header DW1
348 * dword2: Descriptor Header DW2
349 * dword3: Descriptor Header DW3
351 struct RequestDescHeader {
359 uint32_t commandDescBaseAddrLo;
360 uint32_t commandDescBaseAddrHi;
363 uint16_t responseUPIULength;
364 uint16_t responseUPIUOffset;
367 uint16_t PRDTableLength;
368 uint16_t PRDTableOffset;
372 * SCSI reply structure. In here is all the information that is needed to
373 * build a SCSI reply.
379 struct UPIUMessage message;
381 uint8_t expectMore;//0x01 is for writes, 0x02 is for reads
383 uint8_t senseCode[19];
387 * Logic unit information structure. SCSI requires information of each LUN.
388 * This structure is defined in the SCSI standard, and can also be found in
389 * the UFS standard. http://www.jedec.org/standards-documents/results/jesd220
400 uint32_t productRevision;
404 * Different events, and scenarios require different types of information.
405 * Keep in mind that for a read-from-disk transaction the host at first a
406 * datastructure fetches to determine where and what the command is, then the
407 * command fetches and the structure fetches to determine where the
408 * different read transactions should be placed and then transfers all the
409 * read fragments. It then answers to the original caller with two replies,
410 * one for the command, and one for UFS. Each of these stages trigger a
411 * different event, and each event needs to know what happened in the
412 * previous stage and what is going to happen in the current one. This
413 * happens also for writes, SCSI maintanance, UFS maintanance, command
414 * management and task management.
418 * Transfer information.
419 * @filePointer this does not point to a file, but to a position on the disk
420 * image (which is from the software systems perspective a position in a file)
422 struct transferInfo {
423 std::vector <uint8_t> buffer;
426 uint32_t filePointer;
431 * transfer completion info.
432 * This information is needed by transferDone to finish the transfer.
434 struct transferDoneInfo {
435 Addr responseStartAddr;
437 struct UTPUPIURSP requestOut;
440 uint8_t *destination;
446 * Transfer start information.
448 struct transferStart {
449 struct UTPTransferReqDesc* destination;
458 * Task start information. This is for the device, so no lun id needed.
461 struct UTPUPIUTaskReq destination;
469 * After a SCSI command has been identified, the SCSI resume function will
470 * handle it. This information will provide context information.
472 struct SCSIResumeInfo {
473 struct UTPTransferReqDesc* RequestIn;
477 std::vector <uint8_t> destination;
482 * Disk transfer burst information. Needed to allow communication between the
483 * disk transactions and dma transactions.
485 struct writeToDiskBurst {
487 uint64_t SCSIDiskOffset;
495 struct UFSHostDeviceStats {
497 Stats::Scalar currentSCSIQueue;
498 Stats::Scalar currentReadSSDQueue;
499 Stats::Scalar currentWriteSSDQueue;
501 /** Amount of data read/written */
502 Stats::Scalar totalReadSSD;
503 Stats::Scalar totalWrittenSSD;
504 Stats::Scalar totalReadDiskTransactions;
505 Stats::Scalar totalWriteDiskTransactions;
506 Stats::Scalar totalReadUFSTransactions;
507 Stats::Scalar totalWriteUFSTransactions;
509 /** Average bandwidth for reads and writes */
510 Stats::Formula averageReadSSDBW;
511 Stats::Formula averageWriteSSDBW;
513 /** Average Queue lengths*/
514 Stats::Average averageSCSIQueue;
515 Stats::Average averageReadSSDQueue;
516 Stats::Average averageWriteSSDQueue;
518 /** Number of doorbells rung*/
519 Stats::Formula curDoorbell;
520 Stats::Scalar maxDoorbell;
521 Stats::Average averageDoorbell;
523 /** Histogram of latencies*/
524 Stats::Histogram transactionLatency;
525 Stats::Histogram idleTimes;
529 * device layer: This is your Logic unit
530 * This layer implements the SCSI functionality of the UFS Device
531 * One logic unit controls one or more disk partitions
533 class UFSSCSIDevice: SimObject
537 * Constructor and destructor
539 UFSSCSIDevice(const UFSHostDeviceParams* p, uint32_t lun_id, Callback*
540 transfer_cb, Callback *read_cb);
544 * SCSI command handle function; determines what the command is and
545 * returns a reply structure that allows the host device to continue
548 struct SCSIReply SCSICMDHandle(uint32_t* SCSI_msg);
551 * Disk access functions. These will transfer the data from/to the disk
555 * Read flash. read the data from the disk image. This function
556 * doesn't model timing behaviour
558 void readFlash(uint8_t* readaddr, uint64_t offset, uint32_t size);
561 * Write flash. write the data to the disk image. This function
562 * doesn't model timing behaviour
564 void writeFlash(uint8_t* writeaddr, uint64_t offset, uint32_t size);
567 * finished command. Probe to find out wether this logic unit
568 * finished its transfer and triggered the callback; The host needs
569 * this to handle the final part of the transaction.
571 bool finishedCommand() const {return transferCompleted;};
574 * Clear signal. Handle for the host to clear the transfer complete
577 void clearSignal() {transferCompleted = false;};
580 * Finished read. Probe to find out which logic unit finished its
581 * read. This is needed, because multiple units can do transactions
582 * at the same time, and need to push back data at the right time in
583 * the right order. (because writes work the other way round, they do
584 * not need this mechanism)
586 bool finishedRead() const {return readCompleted;};
589 * Clear signal. Handle for the host to clear the read complete
592 void clearReadSignal() {readCompleted = false;};
595 * Start the transactions to (and from) the disk
596 * The host will queue all the transactions. Once the next phase
597 * commences, this function should be started.
599 void SSDReadStart(uint32_t total_read);
600 void SSDWriteStart();
603 * Sets total amount of write transactions that needs to be made.
604 * First they need to be fetched via DMA, so this value is needed in
607 void setTotalWrite(uint32_t total_write) {totalWrite = total_write;};
610 * End of transfer information
612 transferDoneInfo transferInfo;
615 * Information message queues, as there can be multiple messages
616 * queued for handling in this system. These are the main
617 * communication interfaces between the Host and the device layers
621 * SCSIInfoQueue: each LU handles its own SCSI commands.
623 std::deque<struct SCSIResumeInfo> SCSIInfoQueue;
626 * SSDReadInfo: Structure from disk to dma, that contains data, and
627 * helper info to get it to the right place in the memory.
629 std::deque<struct transferInfo> SSDReadInfo;
632 * SSDWriteDoneInfo: Structure from dma to disk, that contains data,
633 * and helper info to get it to the right place in the memory.
634 * The done is added because it is going to the last phase of the
637 std::deque<struct transferInfo> SSDWriteDoneInfo;
641 * Functions to indicate that the action to the SSD has completed.
644 * Read Call back; This is the callback function for the memory model
649 * SSD Read done; Determines if the final callback of the transaction
650 * should be made at the end of a read transfer.
655 * SSD Write Done; This is the callback function for the memory model.
660 * Status of SCSI. This may be linked to a status check in the future.
661 * For now it (mainly) fills a data structure with sense information
662 * for a successfull transaction
664 void statusCheck(uint8_t status, uint8_t* sensecodelist);
667 * set signal to indicate that the transaction has been completed.
669 void setSignal() {transferCompleted = true;};
672 * set signal to indicate that the read action has been completed
674 void setReadSignal() {readCompleted = true;};
677 * The objects this model links to.
678 * 1: the disk data model
679 * 2: the memory timing model
681 DiskImage* flashDisk;
682 AbstractNVM* flashDevice;
685 * Logic unit dimensions
687 const uint32_t blkSize;
688 const uint32_t lunAvail;
689 const uint64_t diskSize;
690 const uint32_t capacityLower;
691 const uint32_t capacityUpper;
694 * Logic unit info; needed for SCSI Info messages and LU
697 struct LUNInfo lunInfo;
698 const uint32_t lunID;
701 * Signals to Host layer
702 * 1: signal for transaction completion
703 * 2: signal for read action completion
705 bool transferCompleted;
709 * Total amount transactions that need to be made
715 * transaction progress tracking
717 uint32_t amountOfWriteTransfers;
718 uint32_t amountOfReadTransfers;
721 * Callbacks between Host and Device
723 Callback* signalDone;
724 Callback* deviceReadCallback;
727 * Callbacks between Device and Memory
729 Callback* memReadCallback;
730 Callback* memWriteCallback;
733 * Default response header layout. For more information refer to
734 * chapter 7 http://www.jedec.org/standards-documents/results/jesd220
736 static const unsigned int UPIUHeaderDataIndWord0 = 0x0000C022;
737 static const unsigned int UPIUHeaderDataIndWord1 = 0x00000000;
738 static const unsigned int UPIUHeaderDataIndWord2 = 0x40000000;
741 * SCSI mode pages values assigned in ufs_device.cc
742 * The mode pages give device specific information via the SCSI
743 * protocol. They are defined in
744 * http://www.jedec.org/standards-documents/results/jesd220
746 static const unsigned int controlPage[3];
747 static const unsigned int recoveryPage[3];
748 static const unsigned int cachingPage[5];
751 * SCSI command set; defined in
752 * http://www.jedec.org/standards-documents/results/jesd220
754 enum SCSICommandSet {
759 SCSIReadCapacity10 = 0x25,
760 SCSIReadCapacity16 = 0x9E,
761 SCSIReportLUNs = 0xA0,
762 SCSIStartStop = 0x1B,
763 SCSITestUnitReady = 0x00,
768 SCSIFormatUnit = 0x04,
769 SCSISendDiagnostic = 0x1D,
770 SCSISynchronizeCache = 0x35,
771 //UFS SCSI additional command set for full functionality
772 SCSIModeSelect10 = 0x55,
773 SCSIModeSense6 = 0x1A,
774 SCSIModeSense10 = 0x5A,
775 SCSIRequestSense = 0x03,
777 SCSIWriteBuffer = 0x3B,
778 SCSIReadBuffer = 0x3C,
779 //SCSI commands not supported by UFS; but Linux send them anyway
780 SCSIMaintenanceIn = 0xA3
784 * SCSI status codes; defined in
785 * http://www.jedec.org/standards-documents/results/jesd220
787 enum SCSIStatusCodes {
789 SCSICheckCondition = 0x02,
790 SCSIConditionGood = 0x04,
792 SCSIIntermediateGood = 0x10,
793 SCSIIntermediatCGood = 0x14,
794 SCSIReservationConflict = 0x18,
795 SCSICommandTerminated = 0x22,
796 SCSITaskSetFull = 0x28,
797 SCSIACAActive = 0x30,
798 SCSITaskAborted = 0x40
802 * SCSI sense codes; defined in
803 * http://www.jedec.org/standards-documents/results/jesd220
805 enum SCSISenseCodes {
807 SCSIRecoverdError = 0x01,
809 SCSIMediumError = 0x03,
810 SCSIHardwareError = 0x04,
811 SCSIIllegalRequest = 0x05,
812 SCSIUnitAttention = 0x06,
813 SCSIDataProtect = 0x07,
814 SCSIBlankCheck = 0x08,
815 SCSIAbortedCommand = 0x0B,
816 SCSIVolumeOverflow = 0x0D,
817 SCSIMisCompare = 0x0E
822 //All access functions are inherrited; no need to make them public
824 * Address range functions
826 AddrRangeList getAddrRanges() const override;
829 * register access functions
831 Tick read(PacketPtr pkt) override;
832 Tick write(PacketPtr pkt) override;
833 // end of access functions
836 * Initialization function. Sets the sefault HCI register values
841 * Handler functions. Each function handles a different stage of the
842 * transfer. Note that the UFS protocol specifies three types of messages
843 * to the host (and devices):
844 * 1: Command (to Host specifically)
845 * 2: Task (to device; to control flow, not for data)
846 * 3: Transfer (to device; to transfer data)
849 * request handler. This function finds the cause of the request and
850 * triggers the right follow-up action (command handler, task handler,
851 * or transferhandler)
853 void requestHandler();
856 * Command handler function. Handles the command send to the Host
859 void commandHandler();
862 * Task Start function. Starts the task handler once the task data
863 * structure has arrived
868 * Task handler function. Handles the tasks send to the devices
869 * because there are not many tasks implemented yet this is kept in the
870 * Host controller layer
872 void taskHandler(struct UTPUPIUTaskReq* request_in,
873 uint32_t req_pos, Addr finaladdress, uint32_t finalsize);
876 * Transfer Start function. Starts the transfer handler once the transfer
877 * data structure has arrived
879 void transferStart();
882 * Transfer handler function. Handles the transfers send to the devices
883 * Important to understand here is that a Logic unit is not a device (a
884 * device can contain multiple logic units). This function analyses the
885 * first data structure that has been transfered. Which will tell the
886 * host to expect SCSI frames for the rest of the transaction. Note that
887 * the host has no indication whatsoever which LU to address. That will
888 * follow in the next transaction.
890 void transferHandler(struct UTPTransferReqDesc*
891 request_in, int req_pos, Addr finaladdress,
892 uint32_t finalsize, uint32_t done);
895 * Transfer SCSI function. Determines which Logic unit to address and
896 * starts the SCSI resume function
901 * Starts the scsi handling function in the apropriate Logic unit,
902 * prepares the right data transfer scheme and kicks it off.
904 void SCSIResume(uint32_t lun_id);
907 * LU callback function to indicate that the action has completed.
912 * transfer done, the beginning of the final stage of the transfer.
913 * Acknowledges UPIU frame and prepares the UTP response frame
915 void transferDone(Addr responseStartAddr, uint32_t req_pos,
916 struct UTPUPIURSP request_out, uint32_t size,
917 Addr address, uint8_t* destination, bool finished,
920 * final UTP, sends the last acknowledge data structure to the system;
921 * prepares the clean up functions.
926 * Interrupt control functions
928 void clearInterrupt();
929 void generateInterrupt();
932 * DMA transfer functions
933 * These allow the host to push/pull the data to the memory
934 * The provided event indicates what the next phase it that will handle
935 * the obtained data, or what the follow up action is once the data has
936 * been pushed to the memory
938 void writeDevice(Event* additional_action, bool toDisk, Addr start,
939 int size, uint8_t* destination, uint64_t SCSIDiskOffset,
941 void readDevice(bool lastTransfer, Addr SCSIStart, uint32_t SCSISize,
942 uint8_t* SCSIDestination, bool no_cache,
943 Event* additional_action);
946 * Disk transfer management functions
947 * these set up the queues, and initiated them, leading to the data
948 * transaction timing model based on the scatter gather list constructed
951 void manageWriteTransfer(uint8_t LUN, uint64_t offset, uint32_t
952 sg_table_length, struct UFSHCDSGEntry* sglist);
953 void manageReadTransfer(uint32_t size, uint32_t LUN, uint64_t offset,
954 uint32_t sg_table_length,
955 struct UFSHCDSGEntry* sglist);
959 * Started at the end of a transaction after the last read action. Cleans
960 * up UTP descriptor and other remaining data structures. It also raises
967 * After a DMA write with data intended for the disk, this function is
968 * called. It ensures that the disk image is modified, and that the
969 * correct timing function is triggered.
975 * Call back function for the logic units to indicate the completion of
976 * a read action. Note that this is needed because the read functionality
977 * needs to push data structures back to the memory.
983 * A read from disk data structure can vary in size and is therefor
984 * allocated on creation. It can only be destroyed once that particular
985 * read action has completed. This function is called on completion of a
986 * read from disk action to handle this.
990 /**register statistics*/
991 void regStats() override;
994 * Host controller information
1001 const uint32_t lunAvail;
1002 const uint8_t UFSSlots;
1005 * Host controller memory
1010 * Track number of DMA transactions in progress
1013 int writePendingNum;
1016 * Statistics helper variables
1017 * Active doorbells indicates how many doorbells are in teh process of
1019 * Pending doorbells have been handled and are waiting to be acknowledged
1020 * by the host system.
1021 * The doorbell register is 32 bits wide, so one byte is enough to keep
1022 * track of the numbers
1024 uint8_t activeDoorbells;
1025 uint8_t pendingDoorbells;
1028 * interrupt verification
1029 * This keeps track of the number of interrupts generated. It is usefull
1030 * for debug purposes. Make sure that the implemented driver prints the
1031 * number of interrupts it has handled so far to fully benefit from this
1037 * Track the transfer
1038 * This is allows the driver to "group" certain transfers together by
1039 * using a tag in the UPIU. The messages with the same tag should be
1040 * handled together, i.e. their doorbells should be cleared when they are
1041 * all done. but we need to keep track of the ones we already handled,
1042 * this integer shadows the doorbells to allow this behaviour.
1044 uint32_t transferTrack;
1045 uint32_t taskCommandTrack;
1048 * Helper for latency stats
1049 * These variables keep track of the latency for every doorbell.
1050 * Eventually the latenmcies will be put in a histogram.
1052 Tick transactionStart[32];
1053 Tick idlePhaseStart;
1056 * logic units connected to the UFS Host device
1057 * Note again that the "device" as such is represented by one or multiple
1060 std::vector<UFSSCSIDevice*> UFSDevice;
1063 * SCSI reply structure, used for direct answering. Might be refered to
1064 * during the assembly of the reply (data, and response; e.g. if
1065 * something goes wrong along the way, the reply will be different)
1067 struct SCSIReply request_out_datain;
1071 * information structure for SCSI resume. it keeps track of all the
1072 * information that is needed to successfully complete the transaction
1073 * (response addresses, communicated information so far, etc.).
1075 struct SCSIResumeInfo SCSIInfo;
1078 * To finish the transaction one needs information about the original
1079 * message. This is stored in this queue
1080 * transferEnd uses the same structure as transferStartInfo, because all
1081 * the information it needs is in there. It improves readability in the
1084 std::deque<struct transferStart> transferEnd;
1087 * When a task/transfer is started it needs information about the
1088 * task/transfer it is about to perform. This is defined in these
1089 * structures. If multiple tasks/transfers are issued at the same time,
1090 * they still need to be fetched one by one. They then need to be
1091 * executed in the order specified by the UFS standard (least significant
1092 * doorbell first). The tasks/transfers are placed in the queue in that
1095 std::deque<struct taskStart> taskInfo;
1096 std::deque<struct transferStart> transferStartInfo;
1099 * Information to get a DMA transaction
1101 std::deque<struct writeToDiskBurst> dmaWriteInfo;
1104 * Information from DMA transaction to disk
1106 std::deque<struct transferInfo> SSDWriteinfo;
1109 * Information from the Disk, waiting to be pushed to the DMA
1111 std::deque<struct transferInfo> SSDReadPending;
1114 * garbage queue, ensure clearing of the allocated memory
1116 std::deque<struct UTPTransferReqDesc*> garbage;
1119 * RequestHandler stats
1121 struct UFSHostDeviceStats stats;
1124 * Transfer flow events
1125 * Basically these events form two queues, one from memory to UFS device
1126 * (DMA) and one from device to flash (SSD). The SSD "queue" is
1127 * maintained by the flash and the lun classes and does not form a queue
1128 * of events as such, but rather a queue of information. This can be done
1129 * because the flow of the events is completely in the control of these
1130 * classes. (Whereas in the DMA case we rely on an external class)
1132 std::deque<EventWrapper<UFSHostDevice, &UFSHostDevice::readDone> >
1134 std::deque<EventWrapper<UFSHostDevice, &UFSHostDevice::writeDone> >
1138 * Callbacks for the logic units. One to indicate the completion of a
1139 * transaction, the other one to indicate the completion of a read
1142 Callback* transferDoneCallback;
1143 Callback* memReadCallback;
1146 * The events that control the functionality.
1147 * After a doorbell has been set, either a taskevent or a transfer event
1148 * is scheduled. A transfer event might schedule a SCSI event, all events
1149 * sequences end with an UTP event, which can be considered as the event
1150 * which answers the doorbell.
1153 * Wait for the SCSI specific data to arive
1155 EventWrapper<UFSHostDevice, &UFSHostDevice::SCSIStart> SCSIResumeEvent;
1158 * Wait for the moment where we can send the last frame
1160 EventWrapper<UFSHostDevice, &UFSHostDevice::finalUTP> UTPEvent;
1163 * Event after a read to clean up the UTP data structures
1165 std::deque<EventWrapper<UFSHostDevice, &UFSHostDevice::readGarbage> >
1166 readGarbageEventQueue;
1169 * Multiple tasks transfers can be scheduled at once for the device, the
1170 * only thing we know for sure about them is that they will happen in a
1171 * first come first serve order; hence we need to queue.
1173 std::deque<EventWrapper<UFSHostDevice, &UFSHostDevice::taskStart> >
1175 std::deque<EventWrapper<UFSHostDevice, &UFSHostDevice::transferStart> >
1179 * Bits of interest within UFS data packages
1181 static const unsigned int UTPTransferREQCOMPL = 0x01;//UFS_BIT(0)
1182 static const unsigned int UTPTaskREQCOMPL = 0x200;//UFS_BIT(9)
1183 static const unsigned int UICCommandCOMPL = 0x400;//UFS_BIT(10)
1184 static const unsigned int UICCommandReady = 0x08;//UFS_BIT(3)
1187 * UFSHCI Registers; please refer to
1188 * http://www.jedec.org/standards-documents/results/jesd223
1189 * for their definition.
1191 enum UFSHCIRegisters {
1192 regControllerCapabilities = 0x00,
1193 regUFSVersion = 0x08,
1194 regControllerDEVID = 0x10,
1195 regControllerPRODID = 0x14,
1196 regInterruptStatus = 0x20,
1197 regInterruptEnable = 0x24,
1198 regControllerStatus = 0x30,
1199 regControllerEnable = 0x34,
1200 regUICErrorCodePHYAdapterLayer = 0x38,
1201 regUICErrorCodeDataLinkLayer = 0x3C,
1202 regUICErrorCodeNetworkLayer = 0x40,
1203 regUICErrorCodeTransportLayer = 0x44,
1204 regUICErrorCodeDME = 0x48,
1205 regUTPTransferREQINTAGGControl = 0x4C,
1206 regUTPTransferREQListBaseL = 0x50,
1207 regUTPTransferREQListBaseH = 0x54,
1208 regUTPTransferREQDoorbell = 0x58,
1209 regUTPTransferREQListClear = 0x5C,
1210 regUTPTransferREQListRunStop = 0x60,
1211 regUTPTaskREQListBaseL = 0x70,
1212 regUTPTaskREQListBaseH = 0x74,
1213 regUTPTaskREQDoorbell = 0x78,
1214 regUTPTaskREQListClear = 0x7C,
1215 regUTPTaskREQListRunStop = 0x80,
1216 regUICCommand = 0x90,
1217 regUICCommandArg1 = 0x94,
1218 regUICCommandArg2 = 0x98,
1219 regUICCommandArg3 = 0x9C
1223 #endif //__DEV_ARM_UFS_DEVICE_HH__