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

[Nishanth Menon]

On 21:01-20230823, Simon Glass wrote:
> Hi Nishanth,
> 
> On Wed, 23 Aug 2023 at 18:18, Nishanth Menon <nm at ti.com> wrote:
> >
> > On 17:57-20230823, Simon Glass wrote:
> > [...]
> > > > 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
> >
> > I was not able to succeed with complex includes such as:
> > https://github.com/u-boot/u-boot/blob/master/doc/board/ti/am62x_sk.rst?plain=1#L89
> >
> > am62x complete build procedure defined once and reused in other am62x
> > platforms.. But the am62x build procedure itself is reused from common
> > k3 build steps.
> 
> I followed through these instructions. I find the env vars quite
> confusing, since I don't really know what it is doing. It feels like a
> script:
> 
> do $a $b $c
> do $f $e
> 
> it is pretty hard to follow. I think it would be better to write
> everything out in full for each board, like rockchip does.

Unfortunately, this is a few major steps that is repeated for
(currently):
	AM62x SK
	Toradex Verdin
	(pending: beagleplay - )
	(once all the dust clears up, hopefully phytec)
	SK-LP
	....

I have no reasonable way to offer to keep them all in sync.
	https://libera.irclog.whitequark.org/u-boot/2023-07-26#34662854;
is kind of why I went down this path.S

> 
> Some other minor feedback:
> 
> - The 'make' lines should really have -j $(nproc) added

Different styles of shells..

> - The $ signs at the start of each command in the docs are a pain
> since it stops me copying the commands into the terminal - can you
> remove them?

hehe.. "dont" let people blindly copy paste without understanding what is
going on argument?

If folks are OK, I sure can send a different patch series for that.. (or
maybe motivate someone to do that instead of me ;))


> - It doesn't build for me:
> 
>   BINMAN  .binman_stamp
> Image 'ti-dm' is missing external blobs and is non-functional: blob-ext
> 
> /binman/ti-dm/blob-ext (ti-dm/am62xx/ipc_echo_testb_mcu1_0_release_strip.xer5f):
>    Missing blob
> 
> Some images are invalid
> make[1]: *** [/scratch/sglass/cosarm/src/third_party/u-boot/files/Makefile:1115:
> .binman_stamp] Error 103
> make[1]: Leaving directory '/tmp/b/play'
> make: *** [Makefile:177: sub-make] Error 2


^^ Neha: This is what I was complaining about.

https://u-boot.readthedocs.io/en/latest/board/ti/am62x_sk.html?highlight=am62#sources

source: https://git.ti.com/git/processor-firmware/ti-linux-firmware.git
is missing, we never used to break build previously binman converted now does.

I am wondering if I need to explicitly call out git clone instructions
out..

-- 
Regards,
Nishanth Menon
Key (0xDDB5849D1736249D) / Fingerprint: F8A2 8693 54EB 8232 17A3  1A34 DDB5 849D 1736 249D