Commit | Line | Data |
---|---|---|
b64f6822 | 1 | .. SPDX-License-Identifier: GPL-2.0 |
7a3e97b0 | 2 | |
b64f6822 MCC |
3 | ======================= |
4 | Universal Flash Storage | |
5 | ======================= | |
7a3e97b0 | 6 | |
7a3e97b0 | 7 | |
b64f6822 MCC |
8 | .. Contents |
9 | ||
10 | 1. Overview | |
11 | 2. UFS Architecture Overview | |
12 | 2.1 Application Layer | |
296559d4 RD |
13 | 2.2 UFS Transport Protocol (UTP) layer |
14 | 2.3 UFS Interconnect (UIC) Layer | |
b64f6822 MCC |
15 | 3. UFSHCD Overview |
16 | 3.1 UFS controller initialization | |
17 | 3.2 UTP Transfer requests | |
18 | 3.3 UFS error handling | |
19 | 3.4 SCSI Error handling | |
ca452621 DL |
20 | 4. BSG Support |
21 | 5. UFS Reference Clock Frequency configuration | |
7a3e97b0 SY |
22 | |
23 | ||
24 | 1. Overview | |
b64f6822 | 25 | =========== |
7a3e97b0 | 26 | |
296559d4 RD |
27 | Universal Flash Storage (UFS) is a storage specification for flash devices. |
28 | It aims to provide a universal storage interface for both | |
29 | embedded and removable flash memory-based storage in mobile | |
7a3e97b0 SY |
30 | devices such as smart phones and tablet computers. The specification |
31 | is defined by JEDEC Solid State Technology Association. UFS is based | |
296559d4 | 32 | on the MIPI M-PHY physical layer standard. UFS uses MIPI M-PHY as the |
7a3e97b0 SY |
33 | physical layer and MIPI Unipro as the link layer. |
34 | ||
296559d4 | 35 | The main goals of UFS are to provide: |
b64f6822 | 36 | |
7a3e97b0 | 37 | * Optimized performance: |
b64f6822 MCC |
38 | |
39 | For UFS version 1.0 and 1.1 the target performance is as follows: | |
40 | ||
41 | - Support for Gear1 is mandatory (rate A: 1248Mbps, rate B: 1457.6Mbps) | |
42 | - Support for Gear2 is optional (rate A: 2496Mbps, rate B: 2915.2Mbps) | |
43 | ||
7a3e97b0 | 44 | Future version of the standard, |
b64f6822 MCC |
45 | |
46 | - Gear3 (rate A: 4992Mbps, rate B: 5830.4Mbps) | |
47 | ||
7a3e97b0 SY |
48 | * Low power consumption |
49 | * High random IOPs and low latency | |
50 | ||
51 | ||
52 | 2. UFS Architecture Overview | |
b64f6822 | 53 | ============================ |
7a3e97b0 SY |
54 | |
55 | UFS has a layered communication architecture which is based on SCSI | |
56 | SAM-5 architectural model. | |
57 | ||
296559d4 | 58 | UFS communication architecture consists of the following layers. |
7a3e97b0 SY |
59 | |
60 | 2.1 Application Layer | |
b64f6822 | 61 | --------------------- |
7a3e97b0 | 62 | |
296559d4 | 63 | The Application layer is composed of the UFS command set layer (UCS), |
7a3e97b0 SY |
64 | Task Manager and Device manager. The UFS interface is designed to be |
65 | protocol agnostic, however SCSI has been selected as a baseline | |
296559d4 | 66 | protocol for versions 1.0 and 1.1 of the UFS protocol layer. |
b64f6822 | 67 | |
296559d4 | 68 | UFS supports a subset of SCSI commands defined by SPC-4 and SBC-3. |
b64f6822 MCC |
69 | |
70 | * UCS: | |
71 | It handles SCSI commands supported by UFS specification. | |
72 | * Task manager: | |
73 | It handles task management functions defined by the | |
7a3e97b0 | 74 | UFS which are meant for command queue control. |
b64f6822 MCC |
75 | * Device manager: |
76 | It handles device level operations and device | |
7a3e97b0 SY |
77 | configuration operations. Device level operations mainly involve |
78 | device power management operations and commands to Interconnect | |
79 | layers. Device level configurations involve handling of query | |
80 | requests which are used to modify and retrieve configuration | |
81 | information of the device. | |
82 | ||
296559d4 RD |
83 | 2.2 UFS Transport Protocol (UTP) layer |
84 | -------------------------------------- | |
7a3e97b0 | 85 | |
296559d4 | 86 | The UTP layer provides services for |
7a3e97b0 SY |
87 | the higher layers through Service Access Points. UTP defines 3 |
88 | service access points for higher layers. | |
b64f6822 | 89 | |
7a3e97b0 SY |
90 | * UDM_SAP: Device manager service access point is exposed to device |
91 | manager for device level operations. These device level operations | |
92 | are done through query requests. | |
93 | * UTP_CMD_SAP: Command service access point is exposed to UFS command | |
296559d4 | 94 | set layer (UCS) to transport commands. |
7a3e97b0 SY |
95 | * UTP_TM_SAP: Task management service access point is exposed to task |
96 | manager to transport task management functions. | |
b64f6822 | 97 | |
296559d4 | 98 | UTP transports messages through UFS protocol information unit (UPIU). |
7a3e97b0 | 99 | |
296559d4 RD |
100 | 2.3 UFS Interconnect (UIC) Layer |
101 | -------------------------------- | |
7a3e97b0 | 102 | |
296559d4 RD |
103 | UIC is the lowest layer of the UFS layered architecture. It handles |
104 | the connection between UFS host and UFS device. UIC consists of | |
7a3e97b0 | 105 | MIPI UniPro and MIPI M-PHY. UIC provides 2 service access points |
296559d4 | 106 | to upper layer: |
b64f6822 | 107 | |
7a3e97b0 SY |
108 | * UIC_SAP: To transport UPIU between UFS host and UFS device. |
109 | * UIO_SAP: To issue commands to Unipro layers. | |
110 | ||
111 | ||
112 | 3. UFSHCD Overview | |
b64f6822 | 113 | ================== |
7a3e97b0 | 114 | |
296559d4 RD |
115 | The UFS host controller driver is based on the Linux SCSI Framework. |
116 | UFSHCD is a low-level device driver which acts as an interface between | |
117 | the SCSI Midlayer and PCIe-based UFS host controllers. | |
7a3e97b0 | 118 | |
296559d4 | 119 | The current UFSHCD implementation supports the following functionality: |
7a3e97b0 SY |
120 | |
121 | 3.1 UFS controller initialization | |
b64f6822 | 122 | --------------------------------- |
7a3e97b0 | 123 | |
296559d4 RD |
124 | The initialization module brings the UFS host controller to active state |
125 | and prepares the controller to transfer commands/responses between | |
7a3e97b0 SY |
126 | UFSHCD and UFS device. |
127 | ||
128 | 3.2 UTP Transfer requests | |
b64f6822 | 129 | ------------------------- |
7a3e97b0 SY |
130 | |
131 | Transfer request handling module of UFSHCD receives SCSI commands | |
296559d4 RD |
132 | from the SCSI Midlayer, forms UPIUs and issues the UPIUs to the UFS Host |
133 | controller. Also, the module decodes responses received from the UFS | |
7a3e97b0 SY |
134 | host controller in the form of UPIUs and intimates the SCSI Midlayer |
135 | of the status of the command. | |
136 | ||
137 | 3.3 UFS error handling | |
b64f6822 | 138 | ---------------------- |
7a3e97b0 SY |
139 | |
140 | Error handling module handles Host controller fatal errors, | |
296559d4 | 141 | Device fatal errors and UIC interconnect layer-related errors. |
7a3e97b0 SY |
142 | |
143 | 3.4 SCSI Error handling | |
b64f6822 | 144 | ----------------------- |
7a3e97b0 SY |
145 | |
146 | This is done through UFSHCD SCSI error handling routines registered | |
296559d4 RD |
147 | with the SCSI Midlayer. Examples of some of the error handling commands |
148 | issues by the SCSI Midlayer are Abort task, LUN reset and host reset. | |
7a3e97b0 SY |
149 | UFSHCD Routines to perform these tasks are registered with |
150 | SCSI Midlayer through .eh_abort_handler, .eh_device_reset_handler and | |
151 | .eh_host_reset_handler. | |
152 | ||
296559d4 | 153 | In this version of UFSHCD, Query requests and power management |
7a3e97b0 SY |
154 | functionality are not implemented. |
155 | ||
df032bf2 | 156 | 4. BSG Support |
b64f6822 | 157 | ============== |
df032bf2 AA |
158 | |
159 | This transport driver supports exchanging UFS protocol information units | |
160 | (UPIUs) with a UFS device. Typically, user space will allocate | |
161 | struct ufs_bsg_request and struct ufs_bsg_reply (see ufs_bsg.h) as | |
162 | request_upiu and reply_upiu respectively. Filling those UPIUs should | |
163 | be done in accordance with JEDEC spec UFS2.1 paragraph 10.7. | |
164 | *Caveat emptor*: The driver makes no further input validations and sends the | |
165 | UPIU to the device as it is. Open the bsg device in /dev/ufs-bsg and | |
b64f6822 | 166 | send SG_IO with the applicable sg_io_v4:: |
df032bf2 AA |
167 | |
168 | io_hdr_v4.guard = 'Q'; | |
169 | io_hdr_v4.protocol = BSG_PROTOCOL_SCSI; | |
170 | io_hdr_v4.subprotocol = BSG_SUB_PROTOCOL_SCSI_TRANSPORT; | |
171 | io_hdr_v4.response = (__u64)reply_upiu; | |
172 | io_hdr_v4.max_response_len = reply_len; | |
173 | io_hdr_v4.request_len = request_len; | |
174 | io_hdr_v4.request = (__u64)request_upiu; | |
4eaa329e AA |
175 | if (dir == SG_DXFER_TO_DEV) { |
176 | io_hdr_v4.dout_xfer_len = (uint32_t)byte_cnt; | |
177 | io_hdr_v4.dout_xferp = (uintptr_t)(__u64)buff; | |
5c17f87a AA |
178 | } else { |
179 | io_hdr_v4.din_xfer_len = (uint32_t)byte_cnt; | |
180 | io_hdr_v4.din_xferp = (uintptr_t)(__u64)buff; | |
4eaa329e AA |
181 | } |
182 | ||
5c17f87a AA |
183 | If you wish to read or write a descriptor, use the appropriate xferp of |
184 | sg_io_v4. | |
185 | ||
4e1c94b0 | 186 | The userspace tool that interacts with the ufs-bsg endpoint and uses its |
296559d4 | 187 | UPIU-based protocol is available at: |
4e1c94b0 AS |
188 | |
189 | https://github.com/westerndigitalcorporation/ufs-tool | |
190 | ||
191 | For more detailed information about the tool and its supported | |
192 | features, please see the tool's README. | |
df032bf2 | 193 | |
296559d4 | 194 | UFS specifications can be found at: |
b64f6822 MCC |
195 | |
196 | - UFS - http://www.jedec.org/sites/default/files/docs/JESD220.pdf | |
197 | - UFSHCI - http://www.jedec.org/sites/default/files/docs/JESD223.pdf | |
ca452621 DL |
198 | |
199 | 5. UFS Reference Clock Frequency configuration | |
200 | ============================================== | |
201 | ||
202 | Devicetree can define a clock named "ref_clk" under the UFS controller node | |
203 | to specify the intended reference clock frequency for the UFS storage | |
204 | parts. ACPI-based system can specify the frequency using ACPI | |
205 | Device-Specific Data property named "ref-clk-freq". In both ways the value | |
206 | is interpreted as frequency in Hz and must match one of the values given in | |
207 | the UFS specification. UFS subsystem will attempt to read the value when | |
208 | executing common controller initialization. If the value is available, UFS | |
cf065a7d | 209 | subsystem will ensure the bRefClkFreq attribute of the UFS storage device is |
ca452621 | 210 | set accordingly and will modify it if there is a mismatch. |