Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: mmc: convert to ReST
Rename the mmc documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
+79
-37
+13
Documentation/mmc/index.rst
+13
Documentation/mmc/index.rst
+32
-21
Documentation/mmc/mmc-async-req.txt
Documentation/mmc/mmc-async-req.rst
+32
-21
Documentation/mmc/mmc-async-req.txt
Documentation/mmc/mmc-async-req.rst
···
1
+
========================
2
+
MMC Asynchronous Request
3
+
========================
4
+
1
5
Rationale
2
6
=========
3
7
4
8
How significant is the cache maintenance overhead?
9
+
5
10
It depends. Fast eMMC and multiple cache levels with speculative cache
6
11
pre-fetch makes the cache overhead relatively significant. If the DMA
7
12
preparations for the next request are done in parallel with the current
8
13
transfer, the DMA preparation overhead would not affect the MMC performance.
14
+
9
15
The intention of non-blocking (asynchronous) MMC requests is to minimize the
10
16
time between when an MMC request ends and another MMC request begins.
17
+
11
18
Using mmc_wait_for_req(), the MMC controller is idle while dma_map_sg and
12
19
dma_unmap_sg are processing. Using non-blocking MMC requests makes it
13
20
possible to prepare the caches for next job in parallel with an active
···
24
17
================
25
18
26
19
The mmc_blk_issue_rw_rq() in the MMC block driver is made non-blocking.
20
+
27
21
The increase in throughput is proportional to the time it takes to
28
22
prepare (major part of preparations are dma_map_sg() and dma_unmap_sg())
29
23
a request and how fast the memory is. The faster the MMC/SD is the
···
43
35
======================
44
36
45
37
There is one new public function mmc_start_req().
38
+
46
39
It starts a new MMC command request for a host. The function isn't
47
40
truly non-blocking. If there is an ongoing async request it waits
48
41
for completion of that request and starts the new one and returns. It
···
56
47
There are two optional members in the mmc_host_ops -- pre_req() and
57
48
post_req() -- that the host driver may implement in order to move work
58
49
to before and after the actual mmc_host_ops.request() function is called.
50
+
59
51
In the DMA case pre_req() may do dma_map_sg() and prepare the DMA
60
52
descriptor, and post_req() runs the dma_unmap_sg().
61
53
···
65
55
66
56
The first request in a series of requests can't be prepared in parallel
67
57
with the previous transfer, since there is no previous request.
58
+
68
59
The argument is_first_req in pre_req() indicates that there is no previous
69
60
request. The host driver may optimize for this scenario to minimize
70
61
the performance loss. A way to optimize for this is to split the current
71
62
request in two chunks, prepare the first chunk and start the request,
72
63
and finally prepare the second chunk and start the transfer.
73
64
74
-
Pseudocode to handle is_first_req scenario with minimal prepare overhead:
65
+
Pseudocode to handle is_first_req scenario with minimal prepare overhead::
75
66
76
-
if (is_first_req && req->size > threshold)
77
-
/* start MMC transfer for the complete transfer size */
78
-
mmc_start_command(MMC_CMD_TRANSFER_FULL_SIZE);
67
+
if (is_first_req && req->size > threshold)
68
+
/* start MMC transfer for the complete transfer size */
69
+
mmc_start_command(MMC_CMD_TRANSFER_FULL_SIZE);
79
70
80
-
/*
81
-
* Begin to prepare DMA while cmd is being processed by MMC.
82
-
* The first chunk of the request should take the same time
83
-
* to prepare as the "MMC process command time".
84
-
* If prepare time exceeds MMC cmd time
85
-
* the transfer is delayed, guesstimate max 4k as first chunk size.
86
-
*/
87
-
prepare_1st_chunk_for_dma(req);
88
-
/* flush pending desc to the DMAC (dmaengine.h) */
89
-
dma_issue_pending(req->dma_desc);
71
+
/*
72
+
* Begin to prepare DMA while cmd is being processed by MMC.
73
+
* The first chunk of the request should take the same time
74
+
* to prepare as the "MMC process command time".
75
+
* If prepare time exceeds MMC cmd time
76
+
* the transfer is delayed, guesstimate max 4k as first chunk size.
77
+
*/
78
+
prepare_1st_chunk_for_dma(req);
79
+
/* flush pending desc to the DMAC (dmaengine.h) */
80
+
dma_issue_pending(req->dma_desc);
90
81
91
-
prepare_2nd_chunk_for_dma(req);
92
-
/*
93
-
* The second issue_pending should be called before MMC runs out
94
-
* of the first chunk. If the MMC runs out of the first data chunk
95
-
* before this call, the transfer is delayed.
96
-
*/
97
-
dma_issue_pending(req->dma_desc);
82
+
prepare_2nd_chunk_for_dma(req);
83
+
/*
84
+
* The second issue_pending should be called before MMC runs out
85
+
* of the first chunk. If the MMC runs out of the first data chunk
86
+
* before this call, the transfer is delayed.
87
+
*/
88
+
dma_issue_pending(req->dma_desc);
+23
-9
Documentation/mmc/mmc-dev-attrs.txt
Documentation/mmc/mmc-dev-attrs.rst
+23
-9
Documentation/mmc/mmc-dev-attrs.txt
Documentation/mmc/mmc-dev-attrs.rst
···
1
+
==================================
1
2
SD and MMC Block Device Attributes
2
3
==================================
3
4
···
7
6
8
7
The following attributes are read/write.
9
8
10
-
force_ro Enforce read-only access even if write protect switch is off.
9
+
======== ===============================================
10
+
force_ro Enforce read-only access even if write protect switch is off.
11
+
======== ===============================================
11
12
12
13
SD and MMC Device Attributes
13
14
============================
14
15
15
16
All attributes are read-only.
16
17
18
+
====================== ===============================================
17
19
cid Card Identification Register
18
20
csd Card Specific Data Register
19
21
scr SD Card Configuration Register (SD only)
20
22
date Manufacturing Date (from CID Register)
21
-
fwrev Firmware/Product Revision (from CID Register) (SD and MMCv1 only)
22
-
hwrev Hardware/Product Revision (from CID Register) (SD and MMCv1 only)
23
+
fwrev Firmware/Product Revision (from CID Register)
24
+
(SD and MMCv1 only)
25
+
hwrev Hardware/Product Revision (from CID Register)
26
+
(SD and MMCv1 only)
23
27
manfid Manufacturer ID (from CID Register)
24
28
name Product Name (from CID Register)
25
29
oemid OEM/Application ID (from CID Register)
26
-
prv Product Revision (from CID Register) (SD and MMCv4 only)
30
+
prv Product Revision (from CID Register)
31
+
(SD and MMCv4 only)
27
32
serial Product Serial Number (from CID Register)
28
33
erase_size Erase group size
29
34
preferred_erase_size Preferred erase size
···
37
30
rel_sectors Reliable write sector count
38
31
ocr Operation Conditions Register
39
32
dsr Driver Stage Register
40
-
cmdq_en Command Queue enabled: 1 => enabled, 0 => not enabled
33
+
cmdq_en Command Queue enabled:
34
+
35
+
1 => enabled, 0 => not enabled
36
+
====================== ===============================================
41
37
42
38
Note on Erase Size and Preferred Erase Size:
43
39
···
54
44
SD/MMC cards can erase an arbitrarily large area up to and
55
45
including the whole card. When erasing a large area it may
56
46
be desirable to do it in smaller chunks for three reasons:
57
-
1. A single erase command will make all other I/O on
47
+
48
+
1. A single erase command will make all other I/O on
58
49
the card wait. This is not a problem if the whole card
59
50
is being erased, but erasing one partition will make
60
51
I/O for another partition on the same card wait for the
61
52
duration of the erase - which could be a several
62
53
minutes.
63
-
2. To be able to inform the user of erase progress.
64
-
3. The erase timeout becomes too large to be very
54
+
2. To be able to inform the user of erase progress.
55
+
3. The erase timeout becomes too large to be very
65
56
useful. Because the erase timeout contains a margin
66
57
which is multiplied by the size of the erase area,
67
58
the value can end up being several minutes for large
···
83
72
"preferred_erase_size" is in bytes.
84
73
85
74
Note on raw_rpmb_size_mult:
75
+
86
76
"raw_rpmb_size_mult" is a multiple of 128kB block.
77
+
87
78
RPMB size in byte is calculated by using the following equation:
88
-
RPMB partition size = 128kB x raw_rpmb_size_mult
79
+
80
+
RPMB partition size = 128kB x raw_rpmb_size_mult
+7
-6
Documentation/mmc/mmc-dev-parts.txt
Documentation/mmc/mmc-dev-parts.rst
+7
-6
Documentation/mmc/mmc-dev-parts.txt
Documentation/mmc/mmc-dev-parts.rst
···
1
+
============================
1
2
SD and MMC Device Partitions
2
3
============================
3
4
···
19
18
accidental bricking.
20
19
21
20
To enable write access to /dev/mmcblkXbootY, disable the forced read-only
22
-
access with:
21
+
access with::
23
22
24
-
echo 0 > /sys/block/mmcblkXbootY/force_ro
23
+
echo 0 > /sys/block/mmcblkXbootY/force_ro
25
24
26
-
To re-enable read-only access:
25
+
To re-enable read-only access::
27
26
28
-
echo 1 > /sys/block/mmcblkXbootY/force_ro
27
+
echo 1 > /sys/block/mmcblkXbootY/force_ro
29
28
30
29
The boot partitions can also be locked read only until the next power on,
31
-
with:
30
+
with::
32
31
33
-
echo 1 > /sys/block/mmcblkXbootY/ro_lock_until_next_power_on
32
+
echo 1 > /sys/block/mmcblkXbootY/ro_lock_until_next_power_on
34
33
35
34
This is a feature of the card and not of the kernel. If the card does
36
35
not support boot partition locking, the file will not exist. If the
+4
-1
Documentation/mmc/mmc-tools.txt
Documentation/mmc/mmc-tools.rst
+4
-1
Documentation/mmc/mmc-tools.txt
Documentation/mmc/mmc-tools.rst
···
1
+
======================
1
2
MMC tools introduction
2
3
======================
3
4
4
5
There is one MMC test tools called mmc-utils, which is maintained by Chris Ball,
5
6
you can find it at the below public git repository:
6
-
http://git.kernel.org/cgit/linux/kernel/git/cjb/mmc-utils.git/
7
+
8
+
http://git.kernel.org/cgit/linux/kernel/git/cjb/mmc-utils.git/
7
9
8
10
Functions
9
11
=========
10
12
11
13
The mmc-utils tools can do the following:
14
+
12
15
- Print and parse extcsd data.
13
16
- Determine the eMMC writeprotect status.
14
17
- Set the eMMC writeprotect status.