[PATCH 09/10] doc: cmd: add documentation for scmi

[AKASHI Takahiro]

On Thu, Jun 29, 2023 at 08:10:02PM +0100, Simon Glass wrote:
> Hi AKASHI,
> 
> On Wed, 28 Jun 2023 at 01:49, AKASHI Takahiro
> <takahiro.akashi at linaro.org> wrote:
> >
> > This is a help text for scmi command.
> >
> > Signed-off-by: AKASHI Takahiro <takahiro.akashi at linaro.org>
> > ---
> >  doc/usage/cmd/scmi.rst | 98 ++++++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 98 insertions(+)
> >  create mode 100644 doc/usage/cmd/scmi.rst
> >
> > diff --git a/doc/usage/cmd/scmi.rst b/doc/usage/cmd/scmi.rst
> > new file mode 100644
> > index 000000000000..20cdae4b877d
> > --- /dev/null
> > +++ b/doc/usage/cmd/scmi.rst
> > @@ -0,0 +1,98 @@
> > +.. SPDX-License-Identifier: GPL-2.0+:
> > +
> > +scmi command
> > +============
> > +
> > +Synopsis
> > +--------
> > +
> > +::
> > +
> > +    scmi base info
> > +    scmi base perm_dev <agent id> <device id> <flags>
> > +    scmi base perm_proto <agent id> <device id> <command id> <flags>
> > +    scmi base reset <agent id> <flags>
> > +
> > +Description
> > +-----------
> > +
> > +The scmi command is used to access and operate on SCMI server.
> > +
> > +scmi base info
> > +~~~~~~~~~~~~~~
> > +    Show base information about SCMI server and supported protocols
> > +
> > +scmi base perm_dev
> > +~~~~~~~~~~~~~~~~~~
> > +    Allow or deny access permission to the device
> > +
> > +scmi base perm_proto
> > +~~~~~~~~~~~~~~~~~~~~
> > +    Allow or deny access to the protocol on the device
> > +
> > +scmi base reset
> > +~~~~~~~~~~~~~~~
> > +    Reset the existing configurations
> > +
> > +Parameters are used as follows:
> > +
> > +<agent id>
> > +    Agent ID
> 
> what is this?

I thought that the meaning was trivial in SCMI context.
Will change it to "SCMI Agent ID".


> > +
> > +<device id>
> > +    Device ID
> 
> what is this?

Again, will change it to "SCMI Device ID".

> > +
> > +<command id>
> > +    Protocol ID, should not be 0x10 (base protocol)
> 
> what is this? Please add more detail

Again, will change it to "SCMI Protocol ID".
I think that users should be familiar with those terms
if they want to use these interfaces.

> > +
> > +<flags>
> > +    Flags to control the action. See SCMI specification for
> > +    defined values.
> 
> ?
> 
> Please add the flags here, or at the very least provide a URL and page
> number, etc.

I intentionally avoid providing details here because a set of flags
acceptable to a specific SCMI server may depend on the server
and its implementation version.
The interface on U-Boot is just a wrapper to make a call to SCMI server
via a transport layer and doesn't care what the parameters means.
That said, I agree to referring to a URL to SCMI specification somewhere
in this document.

Thanks,
-Takahiro Akashi

> > +
> > +Example
> > +-------
> > +
> > +Obtain basic information about SCMI server:
> > +
> > +::
> > +
> > +    => scmi base info
> > +    SCMI device: scmi
> > +      protocol version: 0x20000
> > +      # of agents: 3
> > +          0: platform
> > +        > 1: OSPM
> > +          2: PSCI
> > +      # of protocols: 4
> > +          Power domain management
> > +          Performance domain management
> > +          Clock management
> > +          Sensor management
> > +      vendor: Linaro
> > +      sub vendor: PMWG
> > +      impl version: 0x20b0000
> > +
> > +Ask for access permission to device#0:
> > +
> > +::
> > +
> > +    => scmi base perm_dev 1 0 1
> > +
> > +Reset configurations with all access permission settings retained:
> > +
> > +::
> > +
> > +    => scmi base reset 1 0
> > +
> > +Configuration
> > +-------------
> > +
> > +The scmi command is only available if CONFIG_CMD_SCMI=y.
> > +Default n because this command is mainly for debug purpose.
> > +
> > +Return value
> > +------------
> > +
> > +The return value ($?) is set to 0 if the operation succeeded,
> > +1 if the operation failed or -1 if the operation failed due to
> > +a syntax error.
> > --
> > 2.41.0
> >
> 
> Regards,
> Simon