[PATCH V4 8/8] doc: board: ti: Add BeaglePlay documentation

[Simon Glass]

Hi Tom,

On Wed, 23 Aug 2023 at 11:15, Tom Rini <trini at konsulko.com> wrote:
>
> On Wed, Aug 23, 2023 at 09:30:31AM -0600, Simon Glass wrote:
> > Hi Nishanth,
> >
> > On Tue, 22 Aug 2023 at 12:43, Nishanth Menon <nm at ti.com> wrote:
> > >
> > > Add base documentation for BeaglePlay
> > >
> > > Signed-off-by: Nishanth Menon <nm at ti.com>
> > > ---
> > > Cc: Heinrich Schuchardt <heinrich.schuchardt at canonical.com>
> > >
> > > Changes Since V3:
> > > * Updated documentation to give a more clear overview of MMC partitions
> > >   and flashing information.
> > > * Added OpenOCD debug documentation
> > > * Added LED status information and indication of various boot stages
> > >
> > > V3: https://lore.kernel.org/all/20230815164440.2713726-5-nm@ti.com/
> > > V2: https://lore.kernel.org/u-boot/20230727234446.3651836-5-nm@ti.com/
> > > V1: https://lore.kernel.org/all/20230725185253.2123433-7-nm@ti.com/
> > >
> > >  doc/board/ti/am62x_beagleplay.rst    | 256 ++++++++++
> > >  doc/board/ti/img/beagleplay_emmc.svg | 697 +++++++++++++++++++++++++++
> > >  doc/board/ti/k3.rst                  |   1 +
> > >  3 files changed, 954 insertions(+)
> > >  create mode 100644 doc/board/ti/am62x_beagleplay.rst
> > >  create mode 100644 doc/board/ti/img/beagleplay_emmc.svg
> > >
> >
> > Great docs, an example to others.
> >
> > Some nits below.
> >
> > The bigger problem is that we cannot build this with buildman since it
> > needs config fragments and we don't have a way to describe them. In
> > fact none of my existing flows can build this board and it breaks all
> > my scripts, etc.
> >
> > I don't think anyone else sees this as a problem?
> >
> > Anyway, I'll send a separate email on the topic.
> >
> > > diff --git a/doc/board/ti/am62x_beagleplay.rst b/doc/board/ti/am62x_beagleplay.rst
> > > new file mode 100644
> > > index 000000000000..5adb7b4c9ace
> > > --- /dev/null
> > > +++ b/doc/board/ti/am62x_beagleplay.rst
> > > @@ -0,0 +1,256 @@
> > > +.. SPDX-License-Identifier: GPL-2.0+ OR BSD-3-Clause
> > > +.. sectionauthor:: Nishanth Menon <nm at ti.com>
> > > +
> > > +AM62x Beagleboard.org Beagleplay
> > > +================================
> > > +
> > > +Introduction:
> > > +-------------
> > > +
> > > +BeagleBoard.org BeaglePlay is an easy to use, affordable open source
> > > +hardware single board computer based on the Texas Instruments AM625
> > > +SoC that allows you to create connected devices that work even at long
> > > +distances using IEEE 802.15.4g LR-WPAN and IEEE 802.3cg 10Base-T1L.
> > > +Expansion is provided over open standards based mikroBUS, Grove and
> > > +QWIIC headers among other interfaces.
> > > +
> > > +Further information can be found at:
> > > +
> > > +* Product Page: https://beagleplay.org/
> > > +* Hardware documentation: https://git.beagleboard.org/beagleplay/beagleplay
> > > +
> > > +Boot Flow:
> > > +----------
> > > +Below is the pictorial representation of boot flow:
> > > +
> > > +.. image:: img/boot_diagram_k3_current.svg
> > > +  :alt: Boot flow diagram
> > > +
> > > +- On this platform, 'TI Foundational Security' (TIFS) functions as the
> > > +  security enclave master while 'Device Manager' (DM), also known as the
> > > +  'TISCI server' in "TI terminology", offers all the essential services.
> > > +  The A53/M4F (Aux core) sends requests to TIFS/DM to accomplish these
> > > +  services, as illustrated in the diagram above.
> > > +
> > > +Sources:
> > > +--------
> > > +.. include::  k3.rst
> > > +    :start-after: .. k3_rst_include_start_boot_sources
> > > +    :end-before: .. k3_rst_include_end_boot_sources
> > > +
> > > +Build procedure:
> > > +----------------
> > > +0. Setup the environment variables:
> > > +
> > > +.. include::  k3.rst
> > > +    :start-after: .. k3_rst_include_start_common_env_vars_desc
> > > +    :end-before: .. k3_rst_include_end_common_env_vars_desc
> > > +
> > > +.. include::  k3.rst
> > > +    :start-after: .. k3_rst_include_start_board_env_vars_desc
> > > +    :end-before: .. k3_rst_include_end_board_env_vars_desc
> > > +
> > > +Set the variables corresponding to this platform:
> > > +
> > > +.. include::  k3.rst
> > > +    :start-after: .. k3_rst_include_start_common_env_vars_defn
> > > +    :end-before: .. k3_rst_include_end_common_env_vars_defn
> > > +.. code-block:: bash
> > > +
> > > + $ export UBOOT_CFG_CORTEXR="am62x_evm_r5_defconfig beagleplay_r5.config"
> > > + $ export UBOOT_CFG_CORTEXA="am62x_evm_a53_defconfig beagleplay_a53.config"
> >
> > Can you drop those two variables? It seems to just confuse the matter.
> > They are only used once. We are used to seeing a 'defconfig' target
> > when configuring, and this just obfuscates things.
>
> This is how we have a common bit of rST for how to build N boards,
> without having to do a literal copy and paste N times.

How about using this?

https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#substitution-definitions

Regards,
Simon