Commit f408510c authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab
Browse files

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: default avatarMauro Carvalho Chehab <mchehab+samsung@kernel.org>
parent 8ea0afa3

Documentation/mmc/index.rst

0 → 100644
+13 −0
Original line number Diff line number Diff line 
:orphan:



========================

MMC/SD/SDIO card support

========================



.. toctree::

   :maxdepth: 1



   mmc-dev-attrs

   mmc-dev-parts

   mmc-async-req

   mmc-tools

Documentation/mmc/mmc-async-req.txt→Documentation/mmc/mmc-async-req.rst

+35 −24
Original line number Diff line number Diff line 
========================

MMC Asynchronous Request

========================



Rationale

=========



How significant is the cache maintenance overhead?



It depends. Fast eMMC and multiple cache levels with speculative cache

pre-fetch makes the cache overhead relatively significant. If the DMA

preparations for the next request are done in parallel with the current

transfer, the DMA preparation overhead would not affect the MMC performance.



The intention of non-blocking (asynchronous) MMC requests is to minimize the

time between when an MMC request ends and another MMC request begins.



Using mmc_wait_for_req(), the MMC controller is idle while dma_map_sg and

dma_unmap_sg are processing. Using non-blocking MMC requests makes it

possible to prepare the caches for next job in parallel with an active
@@ -17,6 +24,7 @@ MMC block driver 
================



The mmc_blk_issue_rw_rq() in the MMC block driver is made non-blocking.



The increase in throughput is proportional to the time it takes to

prepare (major part of preparations are dma_map_sg() and dma_unmap_sg())

a request and how fast the memory is. The faster the MMC/SD is the
@@ -35,6 +43,7 @@ MMC core API extension 
======================



There is one new public function mmc_start_req().



It starts a new MMC command request for a host. The function isn't

truly non-blocking. If there is an ongoing async request it waits

for completion of that request and starts the new one and returns. It
@@ -47,6 +56,7 @@ MMC host extensions 
There are two optional members in the mmc_host_ops -- pre_req() and

post_req() -- that the host driver may implement in order to move work

to before and after the actual mmc_host_ops.request() function is called.



In the DMA case pre_req() may do dma_map_sg() and prepare the DMA

descriptor, and post_req() runs the dma_unmap_sg().
@@ -55,13 +65,14 @@ Optimize for the first request 


The first request in a series of requests can't be prepared in parallel

with the previous transfer, since there is no previous request.



The argument is_first_req in pre_req() indicates that there is no previous

request. The host driver may optimize for this scenario to minimize

the performance loss. A way to optimize for this is to split the current

request in two chunks, prepare the first chunk and start the request,

and finally prepare the second chunk and start the transfer.



Pseudocode to handle is_first_req scenario with minimal prepare overhead:

Pseudocode to handle is_first_req scenario with minimal prepare overhead::



  if (is_first_req && req->size > threshold)

     /* start MMC transfer for the complete transfer size */

Documentation/mmc/mmc-dev-attrs.txt→Documentation/mmc/mmc-dev-attrs.rst

+23 −9
Original line number Diff line number Diff line 
==================================

SD and MMC Block Device Attributes

==================================
@@ -6,23 +7,29 @@ SD or MMC device. 


The following attributes are read/write.



	========		===============================================

	force_ro		Enforce read-only access even if write protect 					switch is off.

	========		===============================================



SD and MMC Device Attributes

============================



All attributes are read-only.



	======================	===============================================

	cid			Card Identification Register

	csd			Card Specific Data Register

	scr			SD Card Configuration Register (SD only)

	date			Manufacturing Date (from CID Register)

	fwrev			Firmware/Product Revision (from CID Register) (SD and MMCv1 only)

	hwrev			Hardware/Product Revision (from CID Register) (SD and MMCv1 only)

	fwrev			Firmware/Product Revision (from CID Register)

				(SD and MMCv1 only)

	hwrev			Hardware/Product Revision (from CID Register)

				(SD and MMCv1 only)

	manfid			Manufacturer ID (from CID Register)

	name			Product Name (from CID Register)

	oemid			OEM/Application ID (from CID Register)

	prv			Product Revision (from CID Register) (SD and MMCv4 only)

	prv			Product Revision (from CID Register)

				(SD and MMCv4 only)

	serial			Product Serial Number (from CID Register)

	erase_size		Erase group size

	preferred_erase_size	Preferred erase size
@@ -30,7 +37,10 @@ All attributes are read-only. 
	rel_sectors		Reliable write sector count

	ocr 			Operation Conditions Register

	dsr			Driver Stage Register

	cmdq_en			Command Queue enabled: 1 => enabled, 0 => not enabled

	cmdq_en			Command Queue enabled:



					1 => enabled, 0 => not enabled

	======================	===============================================



Note on Erase Size and Preferred Erase Size:
@@ -44,6 +54,7 @@ Note on Erase Size and Preferred Erase Size: 
	SD/MMC cards can erase an arbitrarily large area up to and

	including the whole card.  When erasing a large area it may

	be desirable to do it in smaller chunks for three reasons:



	     1. A single erase command will make all other I/O on

		the card wait.  This is not a problem if the whole card

		is being erased, but erasing one partition will make
@@ -72,6 +83,9 @@ Note on Erase Size and Preferred Erase Size: 
	"preferred_erase_size" is in bytes.



Note on raw_rpmb_size_mult:



	"raw_rpmb_size_mult" is a multiple of 128kB block.



	RPMB size in byte is calculated by using the following equation:



		RPMB partition size = 128kB x raw_rpmb_size_mult

Documentation/mmc/mmc-dev-parts.txt→Documentation/mmc/mmc-dev-parts.rst

+7 −6
Original line number Diff line number Diff line 
============================

SD and MMC Device Partitions

============================
@@ -18,16 +19,16 @@ platform, write access is disabled by default to reduce the chance of 
accidental bricking.



To enable write access to /dev/mmcblkXbootY, disable the forced read-only

access with:

access with::



	echo 0 > /sys/block/mmcblkXbootY/force_ro



To re-enable read-only access:

To re-enable read-only access::



	echo 1 > /sys/block/mmcblkXbootY/force_ro



The boot partitions can also be locked read only until the next power on,

with:

with::



	echo 1 > /sys/block/mmcblkXbootY/ro_lock_until_next_power_on

Documentation/mmc/mmc-tools.txt→Documentation/mmc/mmc-tools.rst

+4 −1
Original line number Diff line number Diff line 
======================

MMC tools introduction

======================



There is one MMC test tools called mmc-utils, which is maintained by Chris Ball,

you can find it at the below public git repository:



	http://git.kernel.org/cgit/linux/kernel/git/cjb/mmc-utils.git/



Functions

=========



The mmc-utils tools can do the following:



 - Print and parse extcsd data.

 - Determine the eMMC writeprotect status.

 - Set the eMMC writeprotect status.