aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/driver-api/mmc
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/driver-api/mmc')
-rw-r--r--Documentation/driver-api/mmc/index.rst13
-rw-r--r--Documentation/driver-api/mmc/mmc-async-req.rst98
-rw-r--r--Documentation/driver-api/mmc/mmc-dev-attrs.rst91
-rw-r--r--Documentation/driver-api/mmc/mmc-dev-parts.rst41
-rw-r--r--Documentation/driver-api/mmc/mmc-tools.rst37
5 files changed, 280 insertions, 0 deletions
diff --git a/Documentation/driver-api/mmc/index.rst b/Documentation/driver-api/mmc/index.rst
new file mode 100644
index 000000000000..7339736ac774
--- /dev/null
+++ b/Documentation/driver-api/mmc/index.rst
@@ -0,0 +1,13 @@
1.. SPDX-License-Identifier: GPL-2.0
2
3========================
4MMC/SD/SDIO card support
5========================
6
7.. toctree::
8 :maxdepth: 1
9
10 mmc-dev-attrs
11 mmc-dev-parts
12 mmc-async-req
13 mmc-tools
diff --git a/Documentation/driver-api/mmc/mmc-async-req.rst b/Documentation/driver-api/mmc/mmc-async-req.rst
new file mode 100644
index 000000000000..0f7197c9c3b5
--- /dev/null
+++ b/Documentation/driver-api/mmc/mmc-async-req.rst
@@ -0,0 +1,98 @@
1========================
2MMC Asynchronous Request
3========================
4
5Rationale
6=========
7
8How significant is the cache maintenance overhead?
9
10It depends. Fast eMMC and multiple cache levels with speculative cache
11pre-fetch makes the cache overhead relatively significant. If the DMA
12preparations for the next request are done in parallel with the current
13transfer, the DMA preparation overhead would not affect the MMC performance.
14
15The intention of non-blocking (asynchronous) MMC requests is to minimize the
16time between when an MMC request ends and another MMC request begins.
17
18Using mmc_wait_for_req(), the MMC controller is idle while dma_map_sg and
19dma_unmap_sg are processing. Using non-blocking MMC requests makes it
20possible to prepare the caches for next job in parallel with an active
21MMC request.
22
23MMC block driver
24================
25
26The mmc_blk_issue_rw_rq() in the MMC block driver is made non-blocking.
27
28The increase in throughput is proportional to the time it takes to
29prepare (major part of preparations are dma_map_sg() and dma_unmap_sg())
30a request and how fast the memory is. The faster the MMC/SD is the
31more significant the prepare request time becomes. Roughly the expected
32performance gain is 5% for large writes and 10% on large reads on a L2 cache
33platform. In power save mode, when clocks run on a lower frequency, the DMA
34preparation may cost even more. As long as these slower preparations are run
35in parallel with the transfer performance won't be affected.
36
37Details on measurements from IOZone and mmc_test
38================================================
39
40https://wiki.linaro.org/WorkingGroups/Kernel/Specs/StoragePerfMMC-async-req
41
42MMC core API extension
43======================
44
45There is one new public function mmc_start_req().
46
47It starts a new MMC command request for a host. The function isn't
48truly non-blocking. If there is an ongoing async request it waits
49for completion of that request and starts the new one and returns. It
50doesn't wait for the new request to complete. If there is no ongoing
51request it starts the new request and returns immediately.
52
53MMC host extensions
54===================
55
56There are two optional members in the mmc_host_ops -- pre_req() and
57post_req() -- that the host driver may implement in order to move work
58to before and after the actual mmc_host_ops.request() function is called.
59
60In the DMA case pre_req() may do dma_map_sg() and prepare the DMA
61descriptor, and post_req() runs the dma_unmap_sg().
62
63Optimize for the first request
64==============================
65
66The first request in a series of requests can't be prepared in parallel
67with the previous transfer, since there is no previous request.
68
69The argument is_first_req in pre_req() indicates that there is no previous
70request. The host driver may optimize for this scenario to minimize
71the performance loss. A way to optimize for this is to split the current
72request in two chunks, prepare the first chunk and start the request,
73and finally prepare the second chunk and start the transfer.
74
75Pseudocode to handle is_first_req scenario with minimal prepare overhead::
76
77 if (is_first_req && req->size > threshold)
78 /* start MMC transfer for the complete transfer size */
79 mmc_start_command(MMC_CMD_TRANSFER_FULL_SIZE);
80
81 /*
82 * Begin to prepare DMA while cmd is being processed by MMC.
83 * The first chunk of the request should take the same time
84 * to prepare as the "MMC process command time".
85 * If prepare time exceeds MMC cmd time
86 * the transfer is delayed, guesstimate max 4k as first chunk size.
87 */
88 prepare_1st_chunk_for_dma(req);
89 /* flush pending desc to the DMAC (dmaengine.h) */
90 dma_issue_pending(req->dma_desc);
91
92 prepare_2nd_chunk_for_dma(req);
93 /*
94 * The second issue_pending should be called before MMC runs out
95 * of the first chunk. If the MMC runs out of the first data chunk
96 * before this call, the transfer is delayed.
97 */
98 dma_issue_pending(req->dma_desc);
diff --git a/Documentation/driver-api/mmc/mmc-dev-attrs.rst b/Documentation/driver-api/mmc/mmc-dev-attrs.rst
new file mode 100644
index 000000000000..4f44b1b730d6
--- /dev/null
+++ b/Documentation/driver-api/mmc/mmc-dev-attrs.rst
@@ -0,0 +1,91 @@
1==================================
2SD and MMC Block Device Attributes
3==================================
4
5These attributes are defined for the block devices associated with the
6SD or MMC device.
7
8The following attributes are read/write.
9
10 ======== ===============================================
11 force_ro Enforce read-only access even if write protect switch is off.
12 ======== ===============================================
13
14SD and MMC Device Attributes
15============================
16
17All attributes are read-only.
18
19 ====================== ===============================================
20 cid Card Identification Register
21 csd Card Specific Data Register
22 scr SD Card Configuration Register (SD only)
23 date Manufacturing Date (from CID Register)
24 fwrev Firmware/Product Revision (from CID Register)
25 (SD and MMCv1 only)
26 hwrev Hardware/Product Revision (from CID Register)
27 (SD and MMCv1 only)
28 manfid Manufacturer ID (from CID Register)
29 name Product Name (from CID Register)
30 oemid OEM/Application ID (from CID Register)
31 prv Product Revision (from CID Register)
32 (SD and MMCv4 only)
33 serial Product Serial Number (from CID Register)
34 erase_size Erase group size
35 preferred_erase_size Preferred erase size
36 raw_rpmb_size_mult RPMB partition size
37 rel_sectors Reliable write sector count
38 ocr Operation Conditions Register
39 dsr Driver Stage Register
40 cmdq_en Command Queue enabled:
41
42 1 => enabled, 0 => not enabled
43 ====================== ===============================================
44
45Note on Erase Size and Preferred Erase Size:
46
47 "erase_size" is the minimum size, in bytes, of an erase
48 operation. For MMC, "erase_size" is the erase group size
49 reported by the card. Note that "erase_size" does not apply
50 to trim or secure trim operations where the minimum size is
51 always one 512 byte sector. For SD, "erase_size" is 512
52 if the card is block-addressed, 0 otherwise.
53
54 SD/MMC cards can erase an arbitrarily large area up to and
55 including the whole card. When erasing a large area it may
56 be desirable to do it in smaller chunks for three reasons:
57
58 1. A single erase command will make all other I/O on
59 the card wait. This is not a problem if the whole card
60 is being erased, but erasing one partition will make
61 I/O for another partition on the same card wait for the
62 duration of the erase - which could be a several
63 minutes.
64 2. To be able to inform the user of erase progress.
65 3. The erase timeout becomes too large to be very
66 useful. Because the erase timeout contains a margin
67 which is multiplied by the size of the erase area,
68 the value can end up being several minutes for large
69 areas.
70
71 "erase_size" is not the most efficient unit to erase
72 (especially for SD where it is just one sector),
73 hence "preferred_erase_size" provides a good chunk
74 size for erasing large areas.
75
76 For MMC, "preferred_erase_size" is the high-capacity
77 erase size if a card specifies one, otherwise it is
78 based on the capacity of the card.
79
80 For SD, "preferred_erase_size" is the allocation unit
81 size specified by the card.
82
83 "preferred_erase_size" is in bytes.
84
85Note on raw_rpmb_size_mult:
86
87 "raw_rpmb_size_mult" is a multiple of 128kB block.
88
89 RPMB size in byte is calculated by using the following equation:
90
91 RPMB partition size = 128kB x raw_rpmb_size_mult
diff --git a/Documentation/driver-api/mmc/mmc-dev-parts.rst b/Documentation/driver-api/mmc/mmc-dev-parts.rst
new file mode 100644
index 000000000000..995922f1f744
--- /dev/null
+++ b/Documentation/driver-api/mmc/mmc-dev-parts.rst
@@ -0,0 +1,41 @@
1============================
2SD and MMC Device Partitions
3============================
4
5Device partitions are additional logical block devices present on the
6SD/MMC device.
7
8As of this writing, MMC boot partitions as supported and exposed as
9/dev/mmcblkXboot0 and /dev/mmcblkXboot1, where X is the index of the
10parent /dev/mmcblkX.
11
12MMC Boot Partitions
13===================
14
15Read and write access is provided to the two MMC boot partitions. Due to
16the sensitive nature of the boot partition contents, which often store
17a bootloader or bootloader configuration tables crucial to booting the
18platform, write access is disabled by default to reduce the chance of
19accidental bricking.
20
21To enable write access to /dev/mmcblkXbootY, disable the forced read-only
22access with::
23
24 echo 0 > /sys/block/mmcblkXbootY/force_ro
25
26To re-enable read-only access::
27
28 echo 1 > /sys/block/mmcblkXbootY/force_ro
29
30The boot partitions can also be locked read only until the next power on,
31with::
32
33 echo 1 > /sys/block/mmcblkXbootY/ro_lock_until_next_power_on
34
35This is a feature of the card and not of the kernel. If the card does
36not support boot partition locking, the file will not exist. If the
37feature has been disabled on the card, the file will be read-only.
38
39The boot partitions can also be locked permanently, but this feature is
40not accessible through sysfs in order to avoid accidental or malicious
41bricking.
diff --git a/Documentation/driver-api/mmc/mmc-tools.rst b/Documentation/driver-api/mmc/mmc-tools.rst
new file mode 100644
index 000000000000..54406093768b
--- /dev/null
+++ b/Documentation/driver-api/mmc/mmc-tools.rst
@@ -0,0 +1,37 @@
1======================
2MMC tools introduction
3======================
4
5There is one MMC test tools called mmc-utils, which is maintained by Chris Ball,
6you can find it at the below public git repository:
7
8 http://git.kernel.org/cgit/linux/kernel/git/cjb/mmc-utils.git/
9
10Functions
11=========
12
13The mmc-utils tools can do the following:
14
15 - Print and parse extcsd data.
16 - Determine the eMMC writeprotect status.
17 - Set the eMMC writeprotect status.
18 - Set the eMMC data sector size to 4KB by disabling emulation.
19 - Create general purpose partition.
20 - Enable the enhanced user area.
21 - Enable write reliability per partition.
22 - Print the response to STATUS_SEND (CMD13).
23 - Enable the boot partition.
24 - Set Boot Bus Conditions.
25 - Enable the eMMC BKOPS feature.
26 - Permanently enable the eMMC H/W Reset feature.
27 - Permanently disable the eMMC H/W Reset feature.
28 - Send Sanitize command.
29 - Program authentication key for the device.
30 - Counter value for the rpmb device will be read to stdout.
31 - Read from rpmb device to output.
32 - Write to rpmb device from data file.
33 - Enable the eMMC cache feature.
34 - Disable the eMMC cache feature.
35 - Print and parse CID data.
36 - Print and parse CSD data.
37 - Print and parse SCR data.
generated by cgit v1.2.2 (git 2.25.0) at 2025-10-01 11:04:49 -0400