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 92C55C433EF for ; Sat, 13 Nov 2021 14:21:33 +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 13A84611AE for ; Sat, 13 Nov 2021 14:21:33 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.4.1 mail.kernel.org 13A84611AE 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 7F90283110; Sat, 13 Nov 2021 15:21:31 +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="chS33ce4"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 02EF5831F0; Sat, 13 Nov 2021 15:21:30 +0100 (CET) Received: from mail-ua1-x92e.google.com (mail-ua1-x92e.google.com [IPv6:2607:f8b0:4864:20::92e]) (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 034B883102 for ; Sat, 13 Nov 2021 15:21:26 +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-x92e.google.com with SMTP id v3so24814191uam.10 for ; Sat, 13 Nov 2021 06:21:25 -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=CLuo3Sdm7xYJ1n2BCtqYBHzryuHysKcZt+jyYE8gEWw=; b=chS33ce4N50z4Ub7hkrt6H4ihc4LWgAHmKhjTG/dGxr6jwjHXDaI+kL3ODUMC0R3uR rjj4L+V2FOSEAA5DXCDRXiQZLKRmYcZ+eYDzUswlImtHXq86TnEZK5FiuSKsMOuZporS rK1w0gsQRPJq/GON7YUwkqnBh5/8oGVmBjliY= 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=CLuo3Sdm7xYJ1n2BCtqYBHzryuHysKcZt+jyYE8gEWw=; b=POZGCJDwvPGWlpzJl9XxJPX6gPAN0MZJY78FGbpOHrNv2ZEiJM1qV0J1YrJFT+fhzr 7P2Ru57vagprC6v0u1D8dZjdvckjLgyyvxmhflR2nwc8wax4lmocXH1uwksPiH8ypjj5 KyelKl6y/P8XzPQYsKR/Qs4bZXItbtYwQ0QY7A9z9ot0vr3zqSxCxK7BEVX36Vn8eqbb ZJ/N1HTwWSFGxubNx1XBL19k5t5M20x0MeXQm4gmJ95XF81JUclS5DyMjNo2nwAXq58S Q78uy614czTQPSHYbcq1J6EPZzRM0iTZwViLjJNYlC33j5vAMI0q0C/qK5BLLLbhpcZU 78jQ== X-Gm-Message-State: AOAM5305OB1qJjqq684KnaJt8cTgbwnHkHSzrZ8Xp/WY52YlMHFBGEzX RiJYRkQUZ+Ynfzjwhx2QDBwRA9D3NbhL7d+SD7Mt7A== X-Google-Smtp-Source: ABdhPJymUhkrsLJPXaX52lNyspQP+EaOzdAvzcFsteafgvlW/bYkFdPQEtEyjc/sH5MJFCF8pmHzIhOuBpKfKJ+LYhA= X-Received: by 2002:a05:6102:905:: with SMTP id x5mr21439173vsh.58.1636813284563; Sat, 13 Nov 2021 06:21:24 -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: <6763e3e8-853f-1d39-8111-c6b66e9c4fe6@gmx.de> From: Simon Glass Date: Sat, 13 Nov 2021 07:21:13 -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 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. Regards, Simon