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 609EFC433F5 for ; Sat, 13 Nov 2021 18:14:45 +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 7BCDB60F46 for ; Sat, 13 Nov 2021 18:14:44 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.4.1 mail.kernel.org 7BCDB60F46 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 7CE1F83172; Sat, 13 Nov 2021 19:14:41 +0100 (CET) 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="eq462Odp"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id D0991830A4; Sat, 13 Nov 2021 19:14:39 +0100 (CET) Received: from mail-ua1-x931.google.com (mail-ua1-x931.google.com [IPv6:2607:f8b0:4864:20::931]) (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 E351483014 for ; Sat, 13 Nov 2021 19:14:35 +0100 (CET) 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@google.com Received: by mail-ua1-x931.google.com with SMTP id l24so21490100uak.2 for ; Sat, 13 Nov 2021 10:14:35 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=chromium.org; s=google; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=QRUjLhXZqP21ZNu5V+oK3oX2lR2Zsh0oxprPAkwZ/qQ=; b=eq462OdpBdrj8g04RNHCIm+8f4CqBHTPiJSjbKEVBJ+OIwh4FN0YwInUcAQhh/XgK/ nrLxGqYOD5io0nI9xpDsEnTiuKOp1q8OZZ+nwLwPLcvaofRsY6+Wsvxvf28aLAXrdILr PE0Jp8YI22CbCQLKdaC6L2qnwt9jmS/+DeLZI= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=QRUjLhXZqP21ZNu5V+oK3oX2lR2Zsh0oxprPAkwZ/qQ=; b=wIoRGerRtkFpZc8x8/VVLg+37/oThf0CDcAtQczLe4Qmstz4yN7MM1YyDKNYaOwvBk MEdI4dNDWlU28Iic3TEdyMANrqgnGpVkn/11N+ezD/PpRjKpBC94MdxrzreS6MXeBOyM 37SoFs6dTWwEcllMZsNy/ULQ/IZAi/FSoUcr2eLC8eEIlIHGDWE0CF7STIb1lt3hW8BR BI3QdIYj5V4VmGK6liuy0eaqhWykWJEii/JEQHUAeFBxfxV4xcxlBDOfvNkt/jOrdB+j hRVTEUzqMFeXmR+YDBugZIFnGBVP7h1d51lzs0trEte4mTwa14GIVBmPAPn4GqSwge8z ot1g== X-Gm-Message-State: AOAM532MovYI+bWghTm4QY77f3f9XlyIIlm6TrSqh9na37sOfA0AaxMF oiZrT/ALpYxOWfzvUKH/n4dJC66je3F3cmOMxFkzLQ== X-Google-Smtp-Source: ABdhPJx4drzzggBhRlSQBOo7ZgYhbNPW9RtGn2dqLdzY23Oe1f/ONPW9I+6rOyslBQustSNzFjt7cv6oQsuIF/eHoT4= X-Received: by 2002:a05:6102:21a3:: with SMTP id i3mr23578451vsb.8.1636827274291; Sat, 13 Nov 2021 10:14:34 -0800 (PST) MIME-Version: 1.0 References: <20210919214937.3829422-1-sjg@chromium.org> <20210919214937.3829422-5-sjg@chromium.org> <6763e3e8-853f-1d39-8111-c6b66e9c4fe6@gmx.de> In-Reply-To: From: Simon Glass Date: Sat, 13 Nov 2021 11:14:21 -0700 Message-ID: Subject: Re: [PATCH v4 4/5] sf: doc: Add documentation for the 'sf' command To: Heinrich Schuchardt Cc: Jagan Teki , Pratyush Yadav , Mike Frysinger , U-Boot Mailing List Content-Type: text/plain; charset="UTF-8" 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 Hi Heinrich, On Sat, 13 Nov 2021 at 08:32, Heinrich Schuchardt wrote: > > Am 13. 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. > >> > Unfortunately I an not sure how the MTD side of things works and cannot > >> > find information about that. > >> > > >> > 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.rst | 1 + > >> > doc/usage/sf.rst | 245 ++++++++++++++++++++++++++++++++++++++++++++ > >> > 2 files changed, 246 insertions(+) > >> > create mode 100644 doc/usage/sf.rst > >> > > >> > diff --git a/doc/usage/index.rst b/doc/usage/index.rst > >> > index 356f2a56181..9a7b12b7c54 100644 > >> > --- a/doc/usage/index.rst > >> > +++ b/doc/usage/index.rst > >> > @@ -43,6 +43,7 @@ Shell commands > >> > qfw > >> > reset > >> > sbi > >> > + sf > >> > >> Please, keep this list in alphabetical order. > >> > >> > scp03 > >> > setexpr > >> > size > >> > diff --git a/doc/usage/sf.rst b/doc/usage/sf.rst > >> > new file mode 100644 > >> > index 00000000000..71bd1be5175 > >> > --- /dev/null > >> > +++ b/doc/usage/sf.rst > >> > @@ -0,0 +1,245 @@ > >> > +.. 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):: > >> > >> I would have expected the 'spi' command to have an info sub-command like > >> the other subsystems. But that is missing. > >> > >> > + > >> > + 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: > >> > >> I would not expect parameters for other sub-commands in chapter "Probe". > >> > >> Please put all parameters into a separate section "Parameters". This > >> makes navigation easier. > > > >This series was sent back in April and is now at version 5, after > >multiple rounds of changes. This version alone sat here for nearly two > >months. 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. > > > >The common.h header removal suffered a similar fate and we have never > >resolved that, now 18 months later. > > > >So please, let's get something in and move forward. > > We can still in improve the documentation in a follow up patch. > > Acked-by: Heinrich Schuchardt Thank you. Regards, Simon