Received: by 2002:a25:4158:0:0:0:0:0 with SMTP id o85csp2418216yba; Mon, 22 Apr 2019 06:31:11 -0700 (PDT) X-Google-Smtp-Source: APXvYqycAEo+elMqbCwEoB/Saz++4+fdWZRN0lJ/KLXgAPU6QLRBmbf/wXoH5ezMhypSruA6Me/c X-Received: by 2002:a17:902:380c:: with SMTP id l12mr20086823plc.320.1555939871671; Mon, 22 Apr 2019 06:31:11 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1555939871; cv=none; d=google.com; s=arc-20160816; b=s6YyC8ONZjGFhXVfKBqBmf29hHGYfGQxjv240QG1HngBcZDGmcwXuOqb3xGyk7Yg/r xUNSeBCTXecF+u/f2JrFybz8YCt87q+rpChjOAu3V6fzYbGiTyCEL+TJSjXD9105zYvl FIRqk08IdItAEK1mlkSMkuQdaNFDjfyJB8mq49otZlFebyFV/nCLzRgxkTTwyEh8PlNZ 87psZAfheegp3FLHXCIbJOCmG8VQ0PTeH/rQZfHYN8ePxgOTOdCacnx+abVjugtBJgtC cg+sMEJEleLxgt60RelP/ZdGAdOkJzF05Cp+ylmcN+vlCVYHq7sepqCQKYfsh6dJhZ4U Q4xw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:content-transfer-encoding:mime-version :references:in-reply-to:message-id:date:subject:cc:to:from :dkim-signature; bh=cQY43MPArmwZuFfu6bTfT8QQw2Mpx/rEXeT6lNvrai0=; b=ax4mg/n7ztVLyD2Lkvi9d7t7bKLtD9bo2g8xwMc53UogArFYhqWqAt7q3P5Fm4vnLu Sff3Fu7N2AtGB6GrHP9Otf+qK9DUFazNJEIFeAivUUgXCVFnWc4Y295yjg9EuJTYfQHd TfcU5BCvgJvIpQcObhda6p23JnTrNBDqnSIBRl1r3D//cbu9JRlkREL6AnkhBjgK5Spx Ia1mG8e2Dw8YajLvEe1xDQbFUBrvl3e9KzQCFPfBSi1qhq18AG91zM/bexQM5h5iClnn VIR9QpSuoEGLATgM1aSPGC5ryLMCZDyMblH1G+/uleEJwrD7ewjgsnsZQUodRhtIbCUN xL/Q== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@infradead.org header.s=bombadil.20170209 header.b=LO+7dyr0; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id f127si13465286pfc.176.2019.04.22.06.30.55; Mon, 22 Apr 2019 06:31:11 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; dkim=fail header.i=@infradead.org header.s=bombadil.20170209 header.b=LO+7dyr0; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727744AbfDVN2f (ORCPT + 99 others); Mon, 22 Apr 2019 09:28:35 -0400 Received: from bombadil.infradead.org ([198.137.202.133]:37422 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727460AbfDVN2R (ORCPT ); Mon, 22 Apr 2019 09:28:17 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20170209; h=Sender:Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Reply-To:Content-Type:Content-ID:Content-Description:Resent-Date:Resent-From: Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help: List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=cQY43MPArmwZuFfu6bTfT8QQw2Mpx/rEXeT6lNvrai0=; b=LO+7dyr0bwnYLA9482OkNw9vig eCeo5gem0gT/2M6o6Ncqc+bFjKPKeaozjg3agP6gzSXoijW+jpfTHA8f3IDBnDKM1PvVO/kT6Ijjc 4UW72OGj+nCbn8sb6mU9tCyusutS88TfzB5bOUOBI1AXnxN7JiOwzs5wWGTTDgeLo6tcononWupx/ 2rIE4xAc0k2okxJtx7CHKvodMaBXqG6mCwJmfGKFscqpMmuVytjBq9pdiPOv7+xfMGmMZk6LzbyJf j97kw/95AdkYbkTbRzjROTz1z8kbp5Cr1F3jLmJeZ2Wd8wLX8YMGA22Rq5ktHZTYjH2MvuP7dMIcY wjsF5LCg==; Received: from 179.176.125.229.dynamic.adsl.gvt.net.br ([179.176.125.229] helo=bombadil.infradead.org) by bombadil.infradead.org with esmtpsa (Exim 4.90_1 #2 (Red Hat Linux)) id 1hIYzY-0005HS-Pe; Mon, 22 Apr 2019 13:28:17 +0000 Received: from mchehab by bombadil.infradead.org with local (Exim 4.92) (envelope-from ) id 1hIYzU-0005pH-K5; Mon, 22 Apr 2019 10:28:12 -0300 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet Subject: [PATCH v2 72/79] docs: mmc: convert to ReST Date: Mon, 22 Apr 2019 10:28:01 -0300 Message-Id: <18e9ca201cbf4d46ceff57f6bf1179d32bdb014f.1555938376.git.mchehab+samsung@kernel.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: References: MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org 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 --- Documentation/mmc/index.rst | 13 +++++ .../{mmc-async-req.txt => mmc-async-req.rst} | 53 +++++++++++-------- .../{mmc-dev-attrs.txt => mmc-dev-attrs.rst} | 32 +++++++---- .../{mmc-dev-parts.txt => mmc-dev-parts.rst} | 13 ++--- .../mmc/{mmc-tools.txt => mmc-tools.rst} | 5 +- 5 files changed, 79 insertions(+), 37 deletions(-) create mode 100644 Documentation/mmc/index.rst rename Documentation/mmc/{mmc-async-req.txt => mmc-async-req.rst} (75%) rename Documentation/mmc/{mmc-dev-attrs.txt => mmc-dev-attrs.rst} (73%) rename Documentation/mmc/{mmc-dev-parts.txt => mmc-dev-parts.rst} (83%) rename Documentation/mmc/{mmc-tools.txt => mmc-tools.rst} (92%) diff --git a/Documentation/mmc/index.rst b/Documentation/mmc/index.rst new file mode 100644 index 000000000000..3305478ddadb --- /dev/null +++ b/Documentation/mmc/index.rst @@ -0,0 +1,13 @@ +:orphan: + +======================== +MMC/SD/SDIO card support +======================== + +.. toctree:: + :maxdepth: 1 + + mmc-dev-attrs + mmc-dev-parts + mmc-async-req + mmc-tools diff --git a/Documentation/mmc/mmc-async-req.txt b/Documentation/mmc/mmc-async-req.rst similarity index 75% rename from Documentation/mmc/mmc-async-req.txt rename to Documentation/mmc/mmc-async-req.rst index ae1907b10e4a..0f7197c9c3b5 100644 --- a/Documentation/mmc/mmc-async-req.txt +++ b/Documentation/mmc/mmc-async-req.rst @@ -1,13 +1,20 @@ +======================== +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,33 +65,34 @@ 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 */ - mmc_start_command(MMC_CMD_TRANSFER_FULL_SIZE); + if (is_first_req && req->size > threshold) + /* start MMC transfer for the complete transfer size */ + mmc_start_command(MMC_CMD_TRANSFER_FULL_SIZE); - /* - * Begin to prepare DMA while cmd is being processed by MMC. - * The first chunk of the request should take the same time - * to prepare as the "MMC process command time". - * If prepare time exceeds MMC cmd time - * the transfer is delayed, guesstimate max 4k as first chunk size. - */ - prepare_1st_chunk_for_dma(req); - /* flush pending desc to the DMAC (dmaengine.h) */ - dma_issue_pending(req->dma_desc); + /* + * Begin to prepare DMA while cmd is being processed by MMC. + * The first chunk of the request should take the same time + * to prepare as the "MMC process command time". + * If prepare time exceeds MMC cmd time + * the transfer is delayed, guesstimate max 4k as first chunk size. + */ + prepare_1st_chunk_for_dma(req); + /* flush pending desc to the DMAC (dmaengine.h) */ + dma_issue_pending(req->dma_desc); - prepare_2nd_chunk_for_dma(req); - /* - * The second issue_pending should be called before MMC runs out - * of the first chunk. If the MMC runs out of the first data chunk - * before this call, the transfer is delayed. - */ - dma_issue_pending(req->dma_desc); + prepare_2nd_chunk_for_dma(req); + /* + * The second issue_pending should be called before MMC runs out + * of the first chunk. If the MMC runs out of the first data chunk + * before this call, the transfer is delayed. + */ + dma_issue_pending(req->dma_desc); diff --git a/Documentation/mmc/mmc-dev-attrs.txt b/Documentation/mmc/mmc-dev-attrs.rst similarity index 73% rename from Documentation/mmc/mmc-dev-attrs.txt rename to Documentation/mmc/mmc-dev-attrs.rst index 4ad0bb17f343..4f44b1b730d6 100644 --- a/Documentation/mmc/mmc-dev-attrs.txt +++ b/Documentation/mmc/mmc-dev-attrs.rst @@ -1,3 +1,4 @@ +================================== 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. + ======== =============================================== + 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,14 +54,15 @@ 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 + + 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 I/O for another partition on the same card wait for the duration of the erase - which could be a several minutes. - 2. To be able to inform the user of erase progress. - 3. The erase timeout becomes too large to be very + 2. To be able to inform the user of erase progress. + 3. The erase timeout becomes too large to be very useful. Because the erase timeout contains a margin which is multiplied by the size of the erase area, the value can end up being several minutes for large @@ -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 + + RPMB partition size = 128kB x raw_rpmb_size_mult diff --git a/Documentation/mmc/mmc-dev-parts.txt b/Documentation/mmc/mmc-dev-parts.rst similarity index 83% rename from Documentation/mmc/mmc-dev-parts.txt rename to Documentation/mmc/mmc-dev-parts.rst index f08d078d43cf..995922f1f744 100644 --- a/Documentation/mmc/mmc-dev-parts.txt +++ b/Documentation/mmc/mmc-dev-parts.rst @@ -1,3 +1,4 @@ +============================ SD and MMC Device Partitions ============================ @@ -18,18 +19,18 @@ 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 + 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 + 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 + echo 1 > /sys/block/mmcblkXbootY/ro_lock_until_next_power_on This is a feature of the card and not of the kernel. If the card does not support boot partition locking, the file will not exist. If the diff --git a/Documentation/mmc/mmc-tools.txt b/Documentation/mmc/mmc-tools.rst similarity index 92% rename from Documentation/mmc/mmc-tools.txt rename to Documentation/mmc/mmc-tools.rst index 735509c165d5..54406093768b 100644 --- a/Documentation/mmc/mmc-tools.txt +++ b/Documentation/mmc/mmc-tools.rst @@ -1,14 +1,17 @@ +====================== 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/ + + 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. -- 2.20.1