From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-19.4 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_CR_TRAILER,INCLUDES_PATCH,MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS, USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 6A566C4338F for ; Sun, 1 Aug 2021 21:13:23 +0000 (UTC) Received: from phobos.denx.de (phobos.denx.de [85.214.62.61]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id E0F9F60241 for ; Sun, 1 Aug 2021 21:13:22 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.4.1 mail.kernel.org E0F9F60241 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=chromium.org Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=lists.denx.de Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id D554983304; Sun, 1 Aug 2021 23:13:01 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=chromium.org Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=u-boot-bounces@lists.denx.de Authentication-Results: phobos.denx.de; dkim=pass (1024-bit key; unprotected) header.d=chromium.org header.i=@chromium.org header.b="hMqsP4Uk"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 03FCE832F0; Sun, 1 Aug 2021 23:12:58 +0200 (CEST) Received: from mail-oo1-xc2d.google.com (mail-oo1-xc2d.google.com [IPv6:2607:f8b0:4864:20::c2d]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits)) (No client certificate requested) by phobos.denx.de (Postfix) with ESMTPS id BA5CC8311A for ; Sun, 1 Aug 2021 23:12:53 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=chromium.org Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=sjg@chromium.org Received: by mail-oo1-xc2d.google.com with SMTP id k7-20020a4abd870000b029025e4d9b0a3dso206315oop.6 for ; Sun, 01 Aug 2021 14:12:53 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=chromium.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=lRM+KIFXYSAxPtqZL9GF1jVw3mDCSpsMoCIXmELp8Yw=; b=hMqsP4UkAvcfBGBTBR3u+17+3u2swLn7nmkuPdz033yo2Q9wCRVJ1HFqiKO6Ji8XUX m4KV5MkBnW7984U6sFUch38ZU9TmAfcRpjqdMT1XS+Um3KwQ+J/neb2wRgdrnIzzyEZk 3PwcCsGybHi8MVt25l601hkNEwszYaC0Ip2XA= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=lRM+KIFXYSAxPtqZL9GF1jVw3mDCSpsMoCIXmELp8Yw=; b=ieNrlX73UkYSh6BcvOW5JDTFxRPFk4cotO5mesOETPhzTYpY1xIi6ioQEH9QAS3+fL HkGLI1lSH2N6292pY20YNf8sYEAWUNafV7G+u1KvxQPbTQ8pgUWy8cMlo08HTaBBp4bD 29RJ/ZhTV9DjNvKXkHYWIT2cTVrIwogZOJs9gptDAy+OpZBFgf+7Ou6iKp0aazkVbmcN /FD0/MZKI8CvYnK80/2paXZbRwY3or77PkjhWazCx7B/zlobosIIlPVoRv/X4XBtdSK0 Xp881wa1XzXY6T+ER6i/edK6vxlfSpf1dCYHnMVWW27ypA/PsON6p/HyuW6hL3iJXqZK 3hoQ== X-Gm-Message-State: AOAM533fGAKeIqwprsPORKuxHy4IN2y4vx40n5bjuA+26qAzM6179RDp wR2C6gtwR+WaObjC7CCyNxiKGQaxSytb+FsB X-Google-Smtp-Source: ABdhPJwOCGHJ7Q0wy1BAliIn+YibkL6kd1M1ThCoWJHIBsO5D7+ppSK2WtWXNxcFJrn+LPpNg2j94g== X-Received: by 2002:a4a:e923:: with SMTP id a3mr8512482ooe.45.1627852372115; Sun, 01 Aug 2021 14:12:52 -0700 (PDT) Received: from kiwi.bld.corp.google.com (c-67-190-101-114.hsd1.co.comcast.net. [67.190.101.114]) by smtp.gmail.com with ESMTPSA id i188sm1446105oih.7.2021.08.01.14.12.51 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 01 Aug 2021 14:12:51 -0700 (PDT) From: Simon Glass To: U-Boot Mailing List Cc: Heinrich Schuchardt , Jagan Teki , Simon Glass , Mike Frysinger Subject: [PATCH v3 3/4] sf: doc: Add documentation for the 'sf' command Date: Sun, 1 Aug 2021 15:12:44 -0600 Message-Id: <20210801211245.2208037-4-sjg@chromium.org> X-Mailer: git-send-email 2.32.0.554.ge1b32706d8-goog In-Reply-To: <20210801211245.2208037-1-sjg@chromium.org> References: <20210801211245.2208037-1-sjg@chromium.org> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.34 Precedence: list List-Id: U-Boot discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: u-boot-bounces@lists.denx.de Sender: "U-Boot" X-Virus-Scanned: clamav-milter 0.103.2 at phobos.denx.de X-Virus-Status: Clean This command is fairly complicated so documentation is useful. Unfortunately I an not sure how the MTD side of things works and cannot find information about that. Signed-off-by: Simon Glass --- (no changes since v2) Changes in v2: - Many fixes as suggested by Heinrich doc/usage/index.rst | 1 + doc/usage/sf.rst | 241 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 242 insertions(+) create mode 100644 doc/usage/sf.rst diff --git a/doc/usage/index.rst b/doc/usage/index.rst index 719b2c90b9d..501cf6ae733 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -42,6 +42,7 @@ Shell commands qfw reset sbi + sf scp03 setexpr size diff --git a/doc/usage/sf.rst b/doc/usage/sf.rst new file mode 100644 index 00000000000..6ace1b428d9 --- /dev/null +++ b/doc/usage/sf.rst @@ -0,0 +1,241 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +sf command +========== + +Synopis +------- + +:: + + sf probe [[[:]] [ []]] + sf read | + sf write | + sf erase | + sf update | + sf protect lock|unlock + sf test | + +Description +----------- + +The *sf* command is used to access SPI flash, supporting read/write/erase and +a few other functions. + +Probe +----- + +The flash must first be probed with *sf probe* before any of the other +subcommands can be used. All of the parameters are optional: + +bus + SPI bus number containing the SPI-flash chip, e.g. 0. If you don't know + the number, you can use 'dm uclass' to see all the spi devices, + and check the value for 'seq' for each one (here 0 and 2):: + + uclass 89: spi + 0 spi@0 @ 05484960, seq 0 + 1 spi@1 @ 05484b40, seq 2 + +cs + SPI chip-select to use for the chip. This is often 0 and can be omitted, + but in some cases multiple slaves are attached to a SPI controller, + selected by a chip-select line for each one. + +hz + Speed of the SPI bus in hertz. This normally defaults to 100000, i.e. + 100KHz, which is very slow. Note that if the device exists in the + device tree, there might be a speed provided there, in which case this + setting is ignored. + +mode + SPI mode to use: + + ===== ================ + Mode Meaning + ===== ================ + 0 CPOL=0, CPHA=0 + 1 CPOL=0, CPHA=1 + 2 CPOL=1, CPHA=0 + 3 CPOL=1, CPHA=1 + ===== ================ + + Clock phase (CPHA) 0 means that data is transferred (sampled) on the + first clock edge; 1 means the second. + + Clock polarity (CPOL) controls the idle state of the clock, 0 for low, + 1 for high. + The active state is the opposite of idle. + + You may find this `SPI documentation`_ useful. + +Parameters for other subcommands (described below) are as follows: + +addr + Memory address to start transfer + +offset + Flash offset to start transfer + +partition + If the parameter is not numeric, it is assumed to be a partition + description in the format , which is not + covered here. This requires CONFIG_CMD_MTDPARTS. + +len + Number of bytes to transfer + +Read +~~~~ + +Use *sf read* to read from SPI flash to memory. The read will fail if an +attempt is made to read past the end of the flash. + + +Write +~~~~~ + +Use *sf write* to write from memory to SPI flash. The SPI flash should be +erased first, since otherwise the result is undefined. + +The write will fail if an attempt is made to read past the end of the flash. + + +Erase +~~~~~ + +Use *sf erase* to erase a region of SPI flash. The erase will fail if any part +of the region to be erased is protected or lies past the end of the flash. It +may also fail if the start offset or length are not aligned to an erase region +(e.g. 256 bytes). + + +Update +~~~~~~ + +Use *sf update* to automatically erase and update a region of SPI flash from +memory. This works a sector at a time (typical 256 bytes or 4KB). For each +sector it first checks if the sector already has the right data. If so it is +skipped. If not, the sector is erased and the new data written. Note that if +the length is not a multiple of the erase size, the space after the data in +the last sector will be erased. If the offset does not start at the beginning +of an erase block, the operation will fail. + +Speed statistics are shown including the number of bytes that were already +correct. + + +Protect +~~~~~~~ + +SPI-flash chips often have a protection feature where the chip is split up into +regions which can be locked or unlocked. With *sf protect* it is possible to +change these settings, if supported by the driver. + +lock|unlock + Selects whether to lock or unlock the sectors + + + Start sector number to lock/unlock. This may be the byte offset or some + other value, depending on the chip. + + + Number of bytes to lock/unlock + + +Test +~~~~ + +A convenient and fast *sf test* subcommand provides a way to check that SPI +flash is working as expected. This works in four stages: + + * erase - erases the entire region + * check - checks that the region is erased + * write - writes a test pattern to the region, consisting of the U-Boot code + * read - reads back the test pattern to check that it was written correctly + +Memory is allocated for two buffers, each bytes in size. At typical +size is 64KB to 1MB. The offset and size must be aligned to an erase boundary. + +Note that this test will fail if any part of the SPI flash is write-protected. + + +Examples +-------- + +This first example uses sandbox:: + + => sf read 1000 1100 80000 + device 0 offset 0x1100, size 0x80000 + SF: 524288 bytes @ 0x1100 Read: OK + => md 1000 + 00001000: edfe0dd0 f33a0000 78000000 84250000 ......:....x..%. + 00001010: 28000000 11000000 10000000 00000000 ...(............ + 00001020: 6f050000 0c250000 00000000 00000000 ...o..%......... + 00001030: 00000000 00000000 00000000 00000000 ................ + 00001040: 00000000 00000000 00000000 00000000 ................ + 00001050: 00000000 00000000 00000000 00000000 ................ + 00001060: 00000000 00000000 00000000 00000000 ................ + 00001070: 00000000 00000000 01000000 00000000 ................ + 00001080: 03000000 04000000 00000000 01000000 ................ + 00001090: 03000000 04000000 0f000000 01000000 ................ + 000010a0: 03000000 08000000 1b000000 646e6173 ............sand + 000010b0: 00786f62 03000000 08000000 21000000 box............! + 000010c0: 646e6173 00786f62 01000000 61696c61 sandbox.....alia + 000010d0: 00736573 03000000 07000000 2c000000 ses............, + 000010e0: 6332692f 00003040 03000000 07000000 /i2c@0.......... + 000010f0: 31000000 6963702f 00003040 03000000 ...1/pci@0...... + => sf erase 0 80000 + SF: 524288 bytes @ 0x0 Erased: OK + => sf read 1000 1100 80000 + device 0 offset 0x1100, size 0x80000 + SF: 524288 bytes @ 0x1100 Read: OK + => md 1000 + 00001000: ffffffff ffffffff ffffffff ffffffff ................ + 00001010: ffffffff ffffffff ffffffff ffffffff ................ + 00001020: ffffffff ffffffff ffffffff ffffffff ................ + 00001030: ffffffff ffffffff ffffffff ffffffff ................ + 00001040: ffffffff ffffffff ffffffff ffffffff ................ + 00001050: ffffffff ffffffff ffffffff ffffffff ................ + 00001060: ffffffff ffffffff ffffffff ffffffff ................ + 00001070: ffffffff ffffffff ffffffff ffffffff ................ + 00001080: ffffffff ffffffff ffffffff ffffffff ................ + 00001090: ffffffff ffffffff ffffffff ffffffff ................ + 000010a0: ffffffff ffffffff ffffffff ffffffff ................ + 000010b0: ffffffff ffffffff ffffffff ffffffff ................ + 000010c0: ffffffff ffffffff ffffffff ffffffff ................ + 000010d0: ffffffff ffffffff ffffffff ffffffff ................ + 000010e0: ffffffff ffffffff ffffffff ffffffff ................ + 000010f0: ffffffff ffffffff ffffffff ffffffff ................ + +This second example is running on coral, an x86 Chromebook:: + + => sf erase 300000 80000 + SF: 524288 bytes @ 0x300000 Erased: OK + => sf update 1110000 300000 80000 + device 0 offset 0x300000, size 0x80000 + 524288 bytes written, 0 bytes skipped in 0.457s, speed 1164578 B/s + + # This does nothing as the flash is already updated + => sf update 1110000 300000 80000 + device 0 offset 0x300000, size 0x80000 + 0 bytes written, 524288 bytes skipped in 0.196s, speed 2684354 B/s + => sf test 00000 80000 # try a protected region + SPI flash test: + Erase failed (err = -5) + Test failed + => sf test 800000 80000 + SPI flash test: + 0 erase: 18 ticks, 28444 KiB/s 227.552 Mbps + 1 check: 192 ticks, 2666 KiB/s 21.328 Mbps + 2 write: 227 ticks, 2255 KiB/s 18.040 Mbps + 3 read: 189 ticks, 2708 KiB/s 21.664 Mbps + Test passed + 0 erase: 18 ticks, 28444 KiB/s 227.552 Mbps + 1 check: 192 ticks, 2666 KiB/s 21.328 Mbps + 2 write: 227 ticks, 2255 KiB/s 18.040 Mbps + 3 read: 189 ticks, 2708 KiB/s 21.664 Mbps + + +.. _SPI documentation: + https://en.wikipedia.org/wiki/Serial_Peripheral_Interface -- 2.32.0.554.ge1b32706d8-goog