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 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 11849C433F5 for ; Sat, 13 Nov 2021 15:27:00 +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 2324A610A0 for ; Sat, 13 Nov 2021 15:26:59 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.4.1 mail.kernel.org 2324A610A0 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 648168309F; Sat, 13 Nov 2021 16:26:57 +0100 (CET) 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="WooVvCEs"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 2A895831D1; Sat, 13 Nov 2021 16:26:55 +0100 (CET) Received: from mout.gmx.net (mout.gmx.net [212.227.17.22]) (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 5FC9182FCA for ; Sat, 13 Nov 2021 16:26:51 +0100 (CET) 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=1636817207; bh=swWtw2SrTgntD0JVGyIPoRoZm4Ae2zt/IJGxVWWuEbY=; h=X-UI-Sender-Class:Date:From:To:CC:Subject:In-Reply-To:References; b=WooVvCEsVll+w1O71CD1uUqaOS4kJBlDnnqEBffeMJWbcsKg/0AiAXgr8yYeRFNHs 4VIOwKcTFPEaC2o4IvpzpGuBMBKiOlRFdzeabr55wNsCk3JSS4FB1aJXGllsVmbyIc 1XVZ00156WwPOvjbmtDMku4xuA7rTgbsx1o6sDcQ= X-UI-Sender-Class: 01bb95c1-4bf8-414a-932a-4f6e2808ef9c Received: from [127.0.0.1] ([88.152.144.157]) by mail.gmx.net (mrgmx104 [212.227.17.168]) with ESMTPSA (Nemesis) id 1Mi2O1-1mGgly2rBZ-00e1uB; Sat, 13 Nov 2021 16:26:47 +0100 Date: Sat, 13 Nov 2021 16:26:47 +0100 From: Heinrich Schuchardt To: Simon Glass CC: Jagan Teki , Pratyush Yadav , Mike Frysinger , U-Boot Mailing List Subject: Re: [PATCH v4 4/5] sf: doc: Add documentation for the 'sf' command User-Agent: K-9 Mail for Android In-Reply-To: References: <20210919214937.3829422-1-sjg@chromium.org> <20210919214937.3829422-5-sjg@chromium.org> <6763e3e8-853f-1d39-8111-c6b66e9c4fe6@gmx.de> Message-ID: MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Provags-ID: V03:K1:Zxo8cbWbYY9gPsJxQy8jbyaETfFs6pxSa8q/cnrFWvIrmgppo/B 6yEp+XC8koAypZzCV0VEi3v+M0K2+4w0pQiPK0jKYPGnBXFvtfcLT5M9scEcdTT9jFnTLae 0jBqXdvYJZp8rvvSiLERz0efGOi4DGGNVoNGeNB8CIUBfGzMdXIW0q3cJ/hdHqrvtZ/wHmF bquUixncS5KINV4yqiX+w== X-UI-Out-Filterresults: notjunk:1;V03:K0:VwWkRklxobc=:xYksOa4MvL1tutz2IVBi/5 2gi9shxY10lPm6ItQm/StIORA4zp5IafHOg2K29hshczU6nlo/KeKvHTKL3ID8vzzZ4hXiUu7 LCNeSSiKOA9sSZZYMvgk3isyIAW/hDfGnqiXgPyRH+DiB5pXWKPFg21k4DSaNlQ0xUzlwa5zo qxBsuLo309i3OQudF2elVFdTuHajvYIfu9S8XCxMtSpsl694GHWQ+AfYKxgHfk8TUNpPHRNM9 XCUJFnK9hlSnP/TKa5rdKVjrG6Uuj+zjHXdwHlHM9jce1pzRnx5RgJYrFXM6R17O1wZBnlTnf nwrZHMoUSDpoXjt2Jl9WtlPcmtUTsa6fCCaxamcge61GVeGfgSpBgmu6IsB0mFSSpOAPELvf0 fnknyr1KqnyI4D0CC+crcLJlo4LYCFWZJY18wcoBOMNbXr4wIpOUTit0hyFjfxn7cF6xFP43w EA6j2gzlH6vEMxr57slbMMWYDDflKROuULp4CaFPUPW/hqdP87eGHJe9MAjjG/AgxFlhSKIcv ihMuSpyPglUTQK+B8G4DNKhRNwJEE0h7XvuLd3CkQUUbTRUKhhTj7JRsm9enuOr77mXg5OdYg dklKSzphcspbFGb4l/ykR+NGN4fRZTS0aEW+Ky5siFBi6FULjoHR0r8vlqSF/x5nfRNNrNuVg /sov2ykjOLDKTjk6JUK7/2VijHPx0Liwd6EdvuOHzv+qb6i6QlER0G0LQFHbN1jVStWAM7hQ1 /7GUTx5BGEMg2gmF0/Dwx6613BbgJR4jzy8NXg0P3Wxf4NRVvjWU0LjxrUGhPeLf9TIevpXY7 aCsn9xgRjTRcHEhCNMsHdLUYIDz5cn5BuWd/BmbPakVT4Ej+6h3CXN6SUi3k2C26HEfs2xZbF LSFnRwFLtSihVFiMtMozgqML3fjoxaxzNtNXEWIYGZKWBM2PuMNpzCz9/gDQ7gN9QZJ6z2Drx hl1qxlZ+aVgrv6S1MQmrLsx5pDwlIHsKGl22QgDZoDicJi0d5YAjI2E/QIT1n7JAgC4CuelYs Wv6hL2OxlWRrbop2dZwBOAudhvLgPBeNMEt70kdodOt5eQd1ozB7KPwuoJeYcuUHd9HzqobY7 rgwZ8PdOpFjMqY= X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.35 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 Am 13=2E November 2021 15:21:13 MEZ schrieb Simon Glass : >Hi Heinrich, > >On Sat, 13 Nov 2021 at 04:34, Heinrich Schuchardt wrote: >> >> On 9/19/21 23:49, Simon Glass wrote: >> > This command is fairly complicated so documentation is useful=2E >> > Unfortunately I an not sure how the MTD side of things works and cann= ot >> > find information about that=2E >> > >> > Signed-off-by: Simon Glass >> > >> > Acked-by: Pratyush Yadav >> > --- >> > >> > Changes in v4: >> > - Split out the 'const' change into a separate patch >> > - Show the 'sf probe' output in the examples >> > >> > Changes in v2: >> > - Many fixes as suggested by Heinrich >> > >> > doc/usage/index=2Erst | 1 + >> > doc/usage/sf=2Erst | 245 +++++++++++++++++++++++++++++++++++++++= +++++ >> > 2 files changed, 246 insertions(+) >> > create mode 100644 doc/usage/sf=2Erst >> > >> > diff --git a/doc/usage/index=2Erst b/doc/usage/index=2Erst >> > index 356f2a56181=2E=2E9a7b12b7c54 100644 >> > --- a/doc/usage/index=2Erst >> > +++ b/doc/usage/index=2Erst >> > @@ -43,6 +43,7 @@ Shell commands >> > qfw >> > reset >> > sbi >> > + sf >> >> Please, keep this list in alphabetical order=2E >> >> > scp03 >> > setexpr >> > size >> > diff --git a/doc/usage/sf=2Erst b/doc/usage/sf=2Erst >> > new file mode 100644 >> > index 00000000000=2E=2E71bd1be5175 >> > --- /dev/null >> > +++ b/doc/usage/sf=2Erst >> > @@ -0,0 +1,245 @@ >> > +=2E=2E SPDX-License-Identifier: GPL-2=2E0+: >> > + >> > +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/= erase and >> > +a few other functions=2E >> > + >> > +Probe >> > +----- >> > + >> > +The flash must first be probed with *sf probe* before any of the oth= er >> > +subcommands can be used=2E All of the parameters are optional: >> > + >> > +bus >> > + SPI bus number containing the SPI-flash chip, e=2Eg=2E 0=2E 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):: >> >> I would have expected the 'spi' command to have an info sub-command lik= e >> the other subsystems=2E But that is missing=2E >> >> > + >> > + uclass 89: spi >> > + 0 spi@0 @ 05484960, seq 0 >> > + 1 spi@1 @ 05484b40, seq 2 >> > + >> > +cs >> > + SPI chip-select to use for the chip=2E This is often 0 and can = be omitted, >> > + but in some cases multiple slaves are attached to a SPI control= ler, >> > + selected by a chip-select line for each one=2E >> > + >> > +hz >> > + Speed of the SPI bus in hertz=2E This normally defaults to 1000= 00, i=2Ee=2E >> > + 100KHz, which is very slow=2E Note that if the device exists in= the >> > + device tree, there might be a speed provided there, in which ca= se this >> > + setting is ignored=2E >> > + >> > +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) o= n the >> > + first clock edge; 1 means the second=2E >> > + >> > + Clock polarity (CPOL) controls the idle state of the clock, 0 f= or low, >> > + 1 for high=2E >> > + The active state is the opposite of idle=2E >> > + >> > + You may find this `SPI documentation`_ useful=2E >> > + >> > +Parameters for other subcommands (described below) are as follows: >> >> I would not expect parameters for other sub-commands in chapter "Probe"= =2E >> >> Please put all parameters into a separate section "Parameters"=2E This >> makes navigation easier=2E > >This series was sent back in April and is now at version 5, after >multiple rounds of changes=2E This version alone sat here for nearly two >months=2E Who will want to write documentation in U-Boot if this is the >process? > >I don't disagree with most of your comments, just the timing, although >the 'spi info' thing is highly debatable, as you cannot memory-map SPI >itself, only SPI flash=2E > >The common=2Eh header removal suffered a similar fate and we have never >resolved that, now 18 months later=2E > >So please, let's get something in and move forward=2E We can still in improve the documentation in a follow up patch=2E Acked-by: Heinrich Schuchardt > >Regards, >Simon