From: Simon Glass <sjg@chromium.org>
To: Heinrich Schuchardt <xypron.glpk@gmx.de>
Cc: Jagan Teki <jagan@amarulasolutions.com>,
Pratyush Yadav <p.yadav@ti.com>,
Mike Frysinger <vapier@gentoo.org>,
U-Boot Mailing List <u-boot@lists.denx.de>
Subject: Re: [PATCH v4 4/5] sf: doc: Add documentation for the 'sf' command
Date: Sat, 13 Nov 2021 11:14:21 -0700 [thread overview]
Message-ID: <CAPnjgZ1qYFb5ZYwC6fYLYMDrsdazcFtzXDwEjj6YwZhxyfy0eA@mail.gmail.com> (raw)
In-Reply-To: <D5FF0A36-E3B6-46AA-BF4D-AE3A7744202F@gmx.de>
Hi Heinrich,
On Sat, 13 Nov 2021 at 08:32, Heinrich Schuchardt <xypron.glpk@gmx.de> wrote:
>
> Am 13. November 2021 15:21:13 MEZ schrieb Simon Glass <sjg@chromium.org>:
> >Hi Heinrich,
> >
> >On Sat, 13 Nov 2021 at 04:34, Heinrich Schuchardt <xypron.glpk@gmx.de> 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 <sjg@chromium.org>
> >> >
> >> > Acked-by: Pratyush Yadav <p.yadav@ti.com>
> >> > ---
> >> >
> >> > 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 [[[<bus>:]<cs>] [<hz> [<mode>]]]
> >> > + sf read <addr> <offset>|<partition> <len>
> >> > + sf write <addr> <offset>|<partition> <len>
> >> > + sf erase <offset>|<partition> <len>
> >> > + sf update <addr> <offset>|<partition> <len>
> >> > + sf protect lock|unlock <sector> <len>
> >> > + sf test <offset>|<partition> <len>
> >> > +
> >> > +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 <xypron.glpk@gmx.de>
Thank you.
Regards,
Simon
next prev parent reply other threads:[~2021-11-13 18:14 UTC|newest]
Thread overview: 31+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-09-19 21:49 [PATCH v4 0/5] sf: Add documentation and an 'sf mmap' command Simon Glass
2021-09-19 21:49 ` [PATCH v4 1/5] command: Use a constant pointer for the help Simon Glass
2021-10-08 12:40 ` Jagan Teki
2021-11-13 11:13 ` Heinrich Schuchardt
2021-11-24 17:47 ` Simon Glass
2021-11-24 17:47 ` Simon Glass
2021-09-19 21:49 ` [PATCH v4 2/5] sf: Use const for the stage name Simon Glass
2021-10-08 12:41 ` Jagan Teki
2021-11-13 11:15 ` Heinrich Schuchardt
2021-11-24 17:47 ` Simon Glass
2021-11-24 17:47 ` Simon Glass
2021-09-19 21:49 ` [PATCH v4 3/5] sf: Tidy up code to avoid #ifdef Simon Glass
2021-09-20 11:08 ` Pratyush Yadav
2021-09-24 2:48 ` Simon Glass
2021-10-08 12:41 ` Jagan Teki
2021-11-24 17:47 ` Simon Glass
2021-11-24 17:47 ` Simon Glass
2021-09-19 21:49 ` [PATCH v4 4/5] sf: doc: Add documentation for the 'sf' command Simon Glass
2021-10-08 12:42 ` Jagan Teki
2021-11-13 11:34 ` Heinrich Schuchardt
2021-11-13 14:21 ` Simon Glass
2021-11-13 15:26 ` Heinrich Schuchardt
2021-11-13 18:14 ` Simon Glass [this message]
2021-11-24 17:47 ` Simon Glass
2021-11-24 17:47 ` Simon Glass
2021-09-19 21:49 ` [PATCH v4 5/5] sf: Provide a command to access memory-mapped SPI Simon Glass
2021-10-08 12:47 ` Jagan Teki
2021-10-08 20:29 ` Simon Glass
2021-11-13 11:47 ` Heinrich Schuchardt
2021-11-25 0:12 ` Simon Glass
2021-11-13 3:17 ` [PATCH v4 0/5] sf: Add documentation and an 'sf mmap' command Simon Glass
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=CAPnjgZ1qYFb5ZYwC6fYLYMDrsdazcFtzXDwEjj6YwZhxyfy0eA@mail.gmail.com \
--to=sjg@chromium.org \
--cc=jagan@amarulasolutions.com \
--cc=p.yadav@ti.com \
--cc=u-boot@lists.denx.de \
--cc=vapier@gentoo.org \
--cc=xypron.glpk@gmx.de \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).