1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 ======================== 3 ========================
4 MMC Test Framework 4 MMC Test Framework
5 ======================== 5 ========================
6 6
7 Overview 7 Overview
8 ======== 8 ========
9 9
10 The `mmc_test` framework is designed to test t 10 The `mmc_test` framework is designed to test the performance and reliability of host controller drivers and all devices handled by the MMC subsystem. This includes not only MMC devices but also SD cards and other devices supported by the subsystem.
11 11
12 The framework provides a variety of tests to e 12 The framework provides a variety of tests to evaluate different aspects of the host controller and device interactions, such as read and write performance, data integrity, and error handling. These tests help ensure that the host controller drivers and devices operate correctly under various conditions.
13 13
14 The `mmc_test` framework is particularly usefu 14 The `mmc_test` framework is particularly useful for:
15 15
16 - Verifying the functionality and performance 16 - Verifying the functionality and performance of MMC and SD host controller drivers.
17 - Ensuring compatibility and reliability of MM 17 - Ensuring compatibility and reliability of MMC and SD devices.
18 - Identifying and diagnosing issues in the MMC 18 - Identifying and diagnosing issues in the MMC subsystem.
19 19
20 The results of the tests are logged in the ker 20 The results of the tests are logged in the kernel log, providing detailed information about the test outcomes and any encountered issues.
21 21
22 Note: whatever is on your card will be overwri 22 Note: whatever is on your card will be overwritten by these tests.
23 23
24 Initialization 24 Initialization
25 ============== 25 ==============
26 26
27 To use the ``mmc_test`` framework, follow thes 27 To use the ``mmc_test`` framework, follow these steps:
28 28
29 1. **Enable the MMC Test Framework**: 29 1. **Enable the MMC Test Framework**:
30 30
31 Ensure that the ``CONFIG_MMC_TEST`` kernel 31 Ensure that the ``CONFIG_MMC_TEST`` kernel configuration option is enabled. This can be done by configuring the kernel:
32 32
33 .. code-block:: none 33 .. code-block:: none
34 34
35 make menuconfig 35 make menuconfig
36 36
37 Navigate to: 37 Navigate to:
38 38
39 Device Drivers ---> 39 Device Drivers --->
40 <*> MMC/SD/SDIO card support ---> 40 <*> MMC/SD/SDIO card support --->
41 [*] MMC host test driver 41 [*] MMC host test driver
42 42
43 Alternatively, you can enable it directly i 43 Alternatively, you can enable it directly in the kernel configuration file:
44 44
45 .. code-block:: none 45 .. code-block:: none
46 46
47 echo "CONFIG_MMC_TEST=y" >> .config 47 echo "CONFIG_MMC_TEST=y" >> .config
48 48
49 Rebuild and install the kernel if necessary 49 Rebuild and install the kernel if necessary.
50 50
51 2. **Load the MMC Test Module**: 51 2. **Load the MMC Test Module**:
52 52
53 If the ``mmc_test`` framework is built as a 53 If the ``mmc_test`` framework is built as a module, you need to load it using ``modprobe``:
54 54
55 .. code-block:: none 55 .. code-block:: none
56 56
57 modprobe mmc_test 57 modprobe mmc_test
58 58
59 Binding the MMC Card for Testing 59 Binding the MMC Card for Testing
60 ================================ 60 ================================
61 61
62 To enable MMC testing, you need to unbind the 62 To enable MMC testing, you need to unbind the MMC card from the ``mmcblk`` driver and bind it to the ``mmc_test`` driver. This allows the ``mmc_test`` framework to take control of the MMC card for testing purposes.
63 63
64 1. Identify the MMC card: 64 1. Identify the MMC card:
65 65
66 .. code-block:: sh 66 .. code-block:: sh
67 67
68 ls /sys/bus/mmc/devices/ 68 ls /sys/bus/mmc/devices/
69 69
70 This will list the MMC devices, such as ``m 70 This will list the MMC devices, such as ``mmc0:0001``.
71 71
72 2. Unbind the MMC card from the ``mmcblk`` dri 72 2. Unbind the MMC card from the ``mmcblk`` driver:
73 73
74 .. code-block:: sh 74 .. code-block:: sh
75 75
76 echo 'mmc0:0001' > /sys/bus/mmc/drivers/ 76 echo 'mmc0:0001' > /sys/bus/mmc/drivers/mmcblk/unbind
77 77
78 3. Bind the MMC card to the ``mmc_test`` drive 78 3. Bind the MMC card to the ``mmc_test`` driver:
79 79
80 .. code-block:: sh 80 .. code-block:: sh
81 81
82 echo 'mmc0:0001' > /sys/bus/mmc/drivers/ 82 echo 'mmc0:0001' > /sys/bus/mmc/drivers/mmc_test/bind
83 83
84 After binding, you should see a line in the ke 84 After binding, you should see a line in the kernel log indicating that the card has been claimed for testing:
85 85
86 .. code-block:: none 86 .. code-block:: none
87 87
88 mmc_test mmc0:0001: Card claimed for testin 88 mmc_test mmc0:0001: Card claimed for testing.
89 89
90 90
91 Usage - Debugfs Entries 91 Usage - Debugfs Entries
92 ======================= 92 =======================
93 93
94 Once the ``mmc_test`` framework is enabled, yo 94 Once the ``mmc_test`` framework is enabled, you can interact with the following debugfs entries located in ``/sys/kernel/debug/mmc0/mmc0:0001``:
95 95
96 1. **test**: 96 1. **test**:
97 97
98 This file is used to run specific tests. Wr 98 This file is used to run specific tests. Write the test number to this file to execute a test.
99 99
100 .. code-block:: sh 100 .. code-block:: sh
101 101
102 echo <test_number> > /sys/kernel/debug/m 102 echo <test_number> > /sys/kernel/debug/mmc0/mmc0:0001/test
103 103
104 The test result is indicated in the kernel 104 The test result is indicated in the kernel log info. You can view the kernel log using the `dmesg` command or by checking the log file in `/var/log/`.
105 105
106 .. code-block:: sh 106 .. code-block:: sh
107 107
108 dmesg | grep mmc0 108 dmesg | grep mmc0
109 109
110 Example: 110 Example:
111 111
112 To run test number 4 (Basic read with data 112 To run test number 4 (Basic read with data verification):
113 113
114 .. code-block:: sh 114 .. code-block:: sh
115 115
116 echo 4 > /sys/kernel/debug/mmc0/mmc0:000 116 echo 4 > /sys/kernel/debug/mmc0/mmc0:0001/test
117 117
118 Check the kernel log for the result: 118 Check the kernel log for the result:
119 119
120 .. code-block:: sh 120 .. code-block:: sh
121 121
122 dmesg | grep mmc0 122 dmesg | grep mmc0
123 123
124 2. **testlist**: 124 2. **testlist**:
125 125
126 This file lists all available tests. You ca 126 This file lists all available tests. You can read this file to see the list of tests and their corresponding numbers.
127 127
128 .. code-block:: sh 128 .. code-block:: sh
129 129
130 cat /sys/kernel/debug/mmc0/mmc0:0001/tes 130 cat /sys/kernel/debug/mmc0/mmc0:0001/testlist
131 131
132 The available tests are listed in the table 132 The available tests are listed in the table below:
133 133
134 +------+--------------------------------+----- 134 +------+--------------------------------+---------------------------------------------+
135 | Test | Test Name | Test 135 | Test | Test Name | Test Description |
136 +======+================================+===== 136 +======+================================+=============================================+
137 | 0 | Run all tests | Runs 137 | 0 | Run all tests | Runs all available tests |
138 +------+--------------------------------+----- 138 +------+--------------------------------+---------------------------------------------+
139 | 1 | Basic write | Perf 139 | 1 | Basic write | Performs a basic write operation of a |
140 | | | sing 140 | | | single 512-Byte block to the MMC card |
141 | | | with 141 | | | without data verification. |
142 +------+--------------------------------+----- 142 +------+--------------------------------+---------------------------------------------+
143 | 2 | Basic read | Same 143 | 2 | Basic read | Same for read |
144 +------+--------------------------------+----- 144 +------+--------------------------------+---------------------------------------------+
145 | 3 | Basic write | Perf 145 | 3 | Basic write | Performs a basic write operation of a |
146 | | (with data verification) | sing 146 | | (with data verification) | single 512-Byte block to the MMC card |
147 | | | with 147 | | | with data verification by reading back |
148 | | | the 148 | | | the written data and comparing it. |
149 +------+--------------------------------+----- 149 +------+--------------------------------+---------------------------------------------+
150 | 4 | Basic read | Same 150 | 4 | Basic read | Same for read |
151 | | (with data verification) | 151 | | (with data verification) | |
152 +------+--------------------------------+----- 152 +------+--------------------------------+---------------------------------------------+
153 | 5 | Multi-block write | Perf 153 | 5 | Multi-block write | Performs a multi-block write operation of |
154 | | | 8 bl 154 | | | 8 blocks (each 512 bytes) to the MMC card. |
155 +------+--------------------------------+----- 155 +------+--------------------------------+---------------------------------------------+
156 | 6 | Multi-block read | Same 156 | 6 | Multi-block read | Same for read |
157 +------+--------------------------------+----- 157 +------+--------------------------------+---------------------------------------------+
158 | 7 | Power of two block writes | Perf 158 | 7 | Power of two block writes | Performs write operations with block sizes |
159 | | | that 159 | | | that are powers of two, starting from 1 |
160 | | | byte 160 | | | byte up to 256 bytes, to the MMC card. |
161 +------+--------------------------------+----- 161 +------+--------------------------------+---------------------------------------------+
162 | 8 | Power of two block reads | Same 162 | 8 | Power of two block reads | Same for read |
163 +------+--------------------------------+----- 163 +------+--------------------------------+---------------------------------------------+
164 | 9 | Weird sized block writes | Perf 164 | 9 | Weird sized block writes | Performs write operations with varying |
165 | | | bloc 165 | | | block sizes starting from 3 bytes and |
166 | | | incr 166 | | | increasing by 7 bytes each iteration, up |
167 | | | to 5 167 | | | to 511 bytes, to the MMC card. |
168 +------+--------------------------------+----- 168 +------+--------------------------------+---------------------------------------------+
169 | 10 | Weird sized block reads | same 169 | 10 | Weird sized block reads | same for read |
170 +------+--------------------------------+----- 170 +------+--------------------------------+---------------------------------------------+
171 | 11 | Badly aligned write | Perf 171 | 11 | Badly aligned write | Performs write operations with buffers |
172 | | | star 172 | | | starting at different alignments (0 to 7 |
173 | | | byte 173 | | | bytes offset) to test how the MMC card |
174 | | | hand 174 | | | handles unaligned data transfers. |
175 +------+--------------------------------+----- 175 +------+--------------------------------+---------------------------------------------+
176 | 12 | Badly aligned read | same 176 | 12 | Badly aligned read | same for read |
177 +------+--------------------------------+----- 177 +------+--------------------------------+---------------------------------------------+
178 | 13 | Badly aligned multi-block write| same 178 | 13 | Badly aligned multi-block write| same for multi-write |
179 +------+--------------------------------+----- 179 +------+--------------------------------+---------------------------------------------+
180 | 14 | Badly aligned multi-block read | same 180 | 14 | Badly aligned multi-block read | same for multi-read |
181 +------+--------------------------------+----- 181 +------+--------------------------------+---------------------------------------------+
182 | 15 | Proper xfer_size at write | inte 182 | 15 | Proper xfer_size at write | intentionally create a broken transfer by |
183 | | (Start failure) | modi 183 | | (Start failure) | modifying the MMC request in a way that it |
184 | | | will 184 | | | will not perform as expected, e.g. use |
185 | | | MMC_ 185 | | | MMC_WRITE_BLOCK for a multi-block transfer |
186 +------+--------------------------------+----- 186 +------+--------------------------------+---------------------------------------------+
187 | 16 | Proper xfer_size at read | same 187 | 16 | Proper xfer_size at read | same for read |
188 | | (Start failure) | 188 | | (Start failure) | |
189 +------+--------------------------------+----- 189 +------+--------------------------------+---------------------------------------------+
190 | 17 | Proper xfer_size at write | same 190 | 17 | Proper xfer_size at write | same for 2 blocks |
191 | | (Midway failure) | 191 | | (Midway failure) | |
192 +------+--------------------------------+----- 192 +------+--------------------------------+---------------------------------------------+
193 | 18 | Proper xfer_size at read | same 193 | 18 | Proper xfer_size at read | same for read |
194 | | (Midway failure) | 194 | | (Midway failure) | |
195 +------+--------------------------------+----- 195 +------+--------------------------------+---------------------------------------------+
196 | 19 | Highmem write | use 196 | 19 | Highmem write | use a high memory page |
197 +------+--------------------------------+----- 197 +------+--------------------------------+---------------------------------------------+
198 | 20 | Highmem read | same 198 | 20 | Highmem read | same for read |
199 +------+--------------------------------+----- 199 +------+--------------------------------+---------------------------------------------+
200 | 21 | Multi-block highmem write | same 200 | 21 | Multi-block highmem write | same for multi-write |
201 +------+--------------------------------+----- 201 +------+--------------------------------+---------------------------------------------+
202 | 22 | Multi-block highmem read | same 202 | 22 | Multi-block highmem read | same for mult-read |
203 +------+--------------------------------+----- 203 +------+--------------------------------+---------------------------------------------+
204 | 23 | Best-case read performance | Perf 204 | 23 | Best-case read performance | Performs 512K sequential read (non sg) |
205 +------+--------------------------------+----- 205 +------+--------------------------------+---------------------------------------------+
206 | 24 | Best-case write performance | same 206 | 24 | Best-case write performance | same for write |
207 +------+--------------------------------+----- 207 +------+--------------------------------+---------------------------------------------+
208 | 25 | Best-case read performance | Same 208 | 25 | Best-case read performance | Same using sg |
209 | | (Into scattered pages) | 209 | | (Into scattered pages) | |
210 +------+--------------------------------+----- 210 +------+--------------------------------+---------------------------------------------+
211 | 26 | Best-case write performance | same 211 | 26 | Best-case write performance | same for write |
212 | | (From scattered pages) | 212 | | (From scattered pages) | |
213 +------+--------------------------------+----- 213 +------+--------------------------------+---------------------------------------------+
214 | 27 | Single read performance | By t 214 | 27 | Single read performance | By transfer size |
215 +------+--------------------------------+----- 215 +------+--------------------------------+---------------------------------------------+
216 | 28 | Single write performance | By t 216 | 28 | Single write performance | By transfer size |
217 +------+--------------------------------+----- 217 +------+--------------------------------+---------------------------------------------+
218 | 29 | Single trim performance | By t 218 | 29 | Single trim performance | By transfer size |
219 +------+--------------------------------+----- 219 +------+--------------------------------+---------------------------------------------+
220 | 30 | Consecutive read performance | By t 220 | 30 | Consecutive read performance | By transfer size |
221 +------+--------------------------------+----- 221 +------+--------------------------------+---------------------------------------------+
222 | 31 | Consecutive write performance | By t 222 | 31 | Consecutive write performance | By transfer size |
223 +------+--------------------------------+----- 223 +------+--------------------------------+---------------------------------------------+
224 | 32 | Consecutive trim performance | By t 224 | 32 | Consecutive trim performance | By transfer size |
225 +------+--------------------------------+----- 225 +------+--------------------------------+---------------------------------------------+
226 | 33 | Random read performance | By t 226 | 33 | Random read performance | By transfer size |
227 +------+--------------------------------+----- 227 +------+--------------------------------+---------------------------------------------+
228 | 34 | Random write performance | By t 228 | 34 | Random write performance | By transfer size |
229 +------+--------------------------------+----- 229 +------+--------------------------------+---------------------------------------------+
230 | 35 | Large sequential read | Into 230 | 35 | Large sequential read | Into scattered pages |
231 +------+--------------------------------+----- 231 +------+--------------------------------+---------------------------------------------+
232 | 36 | Large sequential write | From 232 | 36 | Large sequential write | From scattered pages |
233 +------+--------------------------------+----- 233 +------+--------------------------------+---------------------------------------------+
234 | 37 | Write performance | With 234 | 37 | Write performance | With blocking req 4k to 4MB |
235 +------+--------------------------------+----- 235 +------+--------------------------------+---------------------------------------------+
236 | 38 | Write performance | With 236 | 38 | Write performance | With non-blocking req 4k to 4MB |
237 +------+--------------------------------+----- 237 +------+--------------------------------+---------------------------------------------+
238 | 39 | Read performance | With 238 | 39 | Read performance | With blocking req 4k to 4MB |
239 +------+--------------------------------+----- 239 +------+--------------------------------+---------------------------------------------+
240 | 40 | Read performance | With 240 | 40 | Read performance | With non-blocking req 4k to 4MB |
241 +------+--------------------------------+----- 241 +------+--------------------------------+---------------------------------------------+
242 | 41 | Write performance | Bloc 242 | 41 | Write performance | Blocking req 1 to 512 sg elems |
243 +------+--------------------------------+----- 243 +------+--------------------------------+---------------------------------------------+
244 | 42 | Write performance | Non- 244 | 42 | Write performance | Non-blocking req 1 to 512 sg elems |
245 +------+--------------------------------+----- 245 +------+--------------------------------+---------------------------------------------+
246 | 43 | Read performance | Bloc 246 | 43 | Read performance | Blocking req 1 to 512 sg elems |
247 +------+--------------------------------+----- 247 +------+--------------------------------+---------------------------------------------+
248 | 44 | Read performance | Non- 248 | 44 | Read performance | Non-blocking req 1 to 512 sg elems |
249 +------+--------------------------------+----- 249 +------+--------------------------------+---------------------------------------------+
250 | 45 | Reset test | 250 | 45 | Reset test | |
251 +------+--------------------------------+----- 251 +------+--------------------------------+---------------------------------------------+
252 | 46 | Commands during read | No S 252 | 46 | Commands during read | No Set Block Count (CMD23) |
253 +------+--------------------------------+----- 253 +------+--------------------------------+---------------------------------------------+
254 | 47 | Commands during write | No S 254 | 47 | Commands during write | No Set Block Count (CMD23) |
255 +------+--------------------------------+----- 255 +------+--------------------------------+---------------------------------------------+
256 | 48 | Commands during read | Use 256 | 48 | Commands during read | Use Set Block Count (CMD23) |
257 +------+--------------------------------+----- 257 +------+--------------------------------+---------------------------------------------+
258 | 49 | Commands during write | Use 258 | 49 | Commands during write | Use Set Block Count (CMD23) |
259 +------+--------------------------------+----- 259 +------+--------------------------------+---------------------------------------------+
260 | 50 | Commands during non-blocking | Read 260 | 50 | Commands during non-blocking | Read - use Set Block Count (CMD23) |
261 +------+--------------------------------+----- 261 +------+--------------------------------+---------------------------------------------+
262 | 51 | Commands during non-blocking | Writ 262 | 51 | Commands during non-blocking | Write - use Set Block Count (CMD23) |
263 +------+--------------------------------+----- 263 +------+--------------------------------+---------------------------------------------+
264 264
265 Test Results 265 Test Results
266 ============ 266 ============
267 267
268 The results of the tests are logged in the ker 268 The results of the tests are logged in the kernel log. Each test logs the start, end, and result of the test. The possible results are:
269 269
270 - **OK**: The test completed successfully. 270 - **OK**: The test completed successfully.
271 - **FAILED**: The test failed. 271 - **FAILED**: The test failed.
272 - **UNSUPPORTED (by host)**: The test is unsup 272 - **UNSUPPORTED (by host)**: The test is unsupported by the host.
273 - **UNSUPPORTED (by card)**: The test is unsup 273 - **UNSUPPORTED (by card)**: The test is unsupported by the card.
274 - **ERROR**: An error occurred during the test 274 - **ERROR**: An error occurred during the test.
275 275
276 Example Kernel Log Output 276 Example Kernel Log Output
277 ========================= 277 =========================
278 278
279 When running a test, you will see log entries 279 When running a test, you will see log entries similar to the following in the kernel log:
280 280
281 .. code-block:: none 281 .. code-block:: none
282 282
283 [ 1234.567890] mmc0: Starting tests of card 283 [ 1234.567890] mmc0: Starting tests of card mmc0:0001...
284 [ 1234.567891] mmc0: Test case 4. Basic rea 284 [ 1234.567891] mmc0: Test case 4. Basic read (with data verification)...
285 [ 1234.567892] mmc0: Result: OK 285 [ 1234.567892] mmc0: Result: OK
286 [ 1234.567893] mmc0: Tests completed. 286 [ 1234.567893] mmc0: Tests completed.
287 287
288 In this example, test case 4 (Basic read with 288 In this example, test case 4 (Basic read with data verification) was executed, and the result was OK.
289 289
290 290
291 Contributing 291 Contributing
292 ============ 292 ============
293 293
294 Contributions to the `mmc_test` framework are 294 Contributions to the `mmc_test` framework are welcome. Please follow the standard Linux kernel contribution guidelines and submit patches to the appropriate maintainers.
295 295
296 Contact 296 Contact
297 ======= 297 =======
298 298
299 For more information or to report issues, plea 299 For more information or to report issues, please contact the MMC subsystem maintainers.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.