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=-12.3 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM, HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH, MAILING_LIST_MULTI,NICE_REPLY_A,SPF_HELO_NONE,SPF_PASS,USER_AGENT_SANE_1 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 55A92C4338F for ; Sun, 1 Aug 2021 19:50:37 +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 5D7B660F36 for ; Sun, 1 Aug 2021 19:50:36 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.4.1 mail.kernel.org 5D7B660F36 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=gmx.de 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 5B2F08311A; Sun, 1 Aug 2021 21:50:34 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=fail (p=none dis=none) header.from=gmx.de 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; secure) header.d=gmx.net header.i=@gmx.net header.b="F0gkOE4B"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 24CD683191; Sun, 1 Aug 2021 21:50:33 +0200 (CEST) Received: from mout.gmx.net (mout.gmx.net [212.227.15.19]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) (No client certificate requested) by phobos.denx.de (Postfix) with ESMTPS id 2321682B45 for ; Sun, 1 Aug 2021 21:50:29 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=gmx.de Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=xypron.glpk@gmx.de DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=gmx.net; s=badeba3b8450; t=1627847426; bh=Pzj9mtZlofV9Wjj5nFo+IX+er5HRbmq0IZTjyS5mBxo=; h=X-UI-Sender-Class:Subject:To:Cc:References:From:Date:In-Reply-To; b=F0gkOE4BRb1bugIASFT3lh2FoUzKbOw/iLsxwGHbiDlw3MdB6Ly8neQOl8543ntaY j8/NjoxZBGSQPk8HWSQI0xklyOuF8Judc/VTUYC4sRRIxetR/koHSWAqMwuMCsaNmO yvePdIBBxgemSsblE/MuzPdGtuAGXthqa0/6Oc0g= X-UI-Sender-Class: 01bb95c1-4bf8-414a-932a-4f6e2808ef9c Received: from [192.168.123.35] ([88.152.144.157]) by mail.gmx.net (mrgmx004 [212.227.17.190]) with ESMTPSA (Nemesis) id 1MNswE-1mYNwY2eJk-00OImi; Sun, 01 Aug 2021 21:50:26 +0200 Subject: Re: [PATCH v2 3/4] sf: doc: Add documentation for the 'sf' command To: Simon Glass , U-Boot Mailing List Cc: Jagan Teki , Mike Frysinger , Patrick Delaunay References: <20210801180243.2166525-1-sjg@chromium.org> <20210801180243.2166525-4-sjg@chromium.org> From: Heinrich Schuchardt Message-ID: <98730a34-4fad-06df-1dab-6fd57b2e0731@gmx.de> Date: Sun, 1 Aug 2021 21:50:21 +0200 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101 Thunderbird/78.11.0 MIME-Version: 1.0 In-Reply-To: <20210801180243.2166525-4-sjg@chromium.org> Content-Type: text/plain; charset=utf-8; format=flowed Content-Language: en-US Content-Transfer-Encoding: quoted-printable X-Provags-ID: V03:K1:ry47sBgXbs9IbZFSqz9li+9dS/3rF8unMI4hQ30h+o+OtnjVk8X OWPMmBwGN1zQpuxbQest5rkFDyf/WbfeDoaxK3YImELL+pq+rk6tjz1MpCWd5LjaQ5L00tN Se+7fq0sg1WGqDfdLd0K1XEfLQts9pW2edJghoJlmlY2vRO3mnXjBV7nEbDMoKSxxljIAn8 W5KOvq2AVc2ink5kC69FQ== X-UI-Out-Filterresults: notjunk:1;V03:K0:EUSTCKSMnO0=:Hh3+zD7CM8xwp2FHqxrC3U xzAde5aywdIiqvNPV1SqH2yjim4SRzf/RBtAaJu9TN47K5h+nq0+oTCAW9Tulf52HBpPucrWt ZK8OqwqF8ak1mEK3pGDHFZWvpCbkc9L5bR6CQoRlHBY0Ok0dwz9SZkT0KKSPfUtXQukbWKEW7 /krOqZrZrfrJtLFak5N1r5YH6mynlwf4CA0/thQjYMCuhz8F4jAPLjMMnnVd1Aobwr+t1ISZt i8k/6n+oQIsmph0+tYIAFKGZadiqBSo80H3/QMYbYCPJOOrwKK/DIELGx9WEHxvIdNZLsPetS IxlJiuMPDLgryP5qpqk5YmvV+EjoSib5MbcgAR8LjRcEkSX17l5su/0U1rKrOC0O6dty6DLO0 h6uDu0CwW0VJE47hQcSyLOJ4U6qt+jU07ZZ5HolC5x+RJVSQKr3U4NnknkOQO6dg3kbiPWYMY 1R7Ylu9LNkaAcFbCErWxFZEOoP7AW1SMJCh6wjRXU2KH5xvUfas4zg/17iFFitwU47/E7HmMY I1yrvh/OUA96JgWbGk0DSJI7T7fZm3tdgvmWYfg6N5YRSMJ0SFyaWMyj2KT3UDrXYQZj3fxMG Q7wsE1wgyuXTA1shIgRwv6btT28UiHjgxfGA+knigDDV/npePOA5N5D3+pnID5Nd0VICEMIbv pUenwHJFiu4J6fBfpwAPN/cUGHX4QGY/F0+4/IbNXd1fXSfo7j7kiuWXkp6Cngd3fHU4qhwit HYdfcCTTApVAjaILB4zMzYiCMqv3cW+qbDXUwcxajDzD2DK52gpkASbyIMp5EqbBp2LLu98uG Xjr+jTB/aK6Jetjf/NKFhsRNNRG+v2f+ApkipBpDwAbsNMZ6GAohQ94wMfddDP9lFPEz8PeA5 sTZ5ZYF0FGPtSsL82dqtHVZfuWqk7+65wt4RatK2BtasE2iv5Qt/iTGBISFbMWYuJgPHYt8do mnm6xr8RKIKk/zg3odAyZzMk5GYwUVF6dszci6YmHJ6/SR3pTdo47lBxbgABnc1DbIyrrO2+q 5+ufSEge6Bd2mSLxKYmEl+GhVRbAhSO+PV5BHBviPLqJPEGfRWP6drnMPQvsJ2JDrRW1U8BC6 +j9WQAMVVjco4B0BfhiYEXQR+g/jTJ+Nr0R 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 On 8/1/21 8:02 PM, Simon Glass wrote: > 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 > --- > > 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 > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > + > +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/era= se 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 kno= w > + 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 omitte= d, > + 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: > + > + =3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > + Mode Meaning > + =3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > + 0 CPOL=3D0, CPHA=3D0 > + 1 CPOL=3D0, CPHA=3D1 > + 2 CPOL=3D1, CPHA=3D0 > + 3 CPOL=3D1, CPHA=3D1 > + =3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > + > + 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 a= n > +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 f= lash. > + > + > +Erase > +~~~~~ > + > +Use *sf erase* to erase a region of SPI flash. The erase will fail if a= ny part > +of the region to be erased is protected or lies past the end of the fla= sh. 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 e= ach > +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 th= at if > +the length is not a multiple of the erase size, the space after the dat= a in > +the last sector will be erased. If the offset does not start at the beg= inning > +of an erase block, the operation will fail. > + > +Speed statistics are shown including the number of bytes that were alre= ady > +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 possib= le 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 som= e > + 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-B= oot code > + * read - reads back the test pattern to check that it was written co= rrectly > + > +Memory is allocated for two buffers, each bytes in size. At typic= al > +size is 64KB to 1MB. The offset and size must be aligned to an erase bo= undary. > + > +Note that this test will fail if any part of the SPI flash is write-pro= tected. > + > + > +Examples > +-------- > + > +This first example uses sandbox:: > + > + =3D> sf read 1000 1100 80000 > + device 0 offset 0x1100, size 0x80000 > + SF: 524288 bytes @ 0x1100 Read: OK > + =3D> 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...... > + =3D> sf erase 0 80000 > + SF: 524288 bytes @ 0x0 Erased: OK > + =3D> sf read 1000 1100 80000 > + device 0 offset 0x1100, size 0x80000 > + SF: 524288 bytes @ 0x1100 Read: OK > + =3D> 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:: > + > + =3D> sf erase 300000 80000 > + SF: 524288 bytes @ 0x300000 Erased: OK > + =3D> 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 > + =3D> sf update 1110000 300000 80000 > + device 0 offset 0x300000, size 0x80000 > + 0 bytes written, 524288 bytes skipped in 0.196s, speed 2684354 B/s > + =3D> sf test 00000 80000 # try a protected region > + SPI flash test: > + Erase failed (err =3D -5) > + Test failed > + =3D> 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 > For other commands we have mentioned the relvant configuration options. Cf. mmc.rst. Could you, please, add a chapter 'Configuration'. CONFIG_CMD_SF depends on DM_SPI_FLASH [=3Dy] || SPI_FLASH [=3Dy]. I think there is no SPI driver left that is not migrated to DM. Can't we get rid of either CONFIG_DM_SPI_FLASH or CONFIG_SPI_FLASH? Best regards Heinrich