[PATCH 2/2] doc: ti: add the K3 generation page

[Bryan Brattlof]

Hi Andrew!

On January  3, 2023 thus sayeth Andrew Davis:
> On 12/19/22 2:29 PM, Bryan Brattlof wrote:
> > Texas Instrument's entire K3 generation of SoCs use much of the same
> > frameworks and boot flow, especially at the uboot level. Though there
> > are small differences introduced as each new K3 based SoC is developed
> > and as the K3 generation matures that will also need to be documented.
> > 
> > Rather than copying the same documentation, with the small differences
> > applicable to that specific SoC to a new page, introduce a new K3
> > page that can describe the general boot flow and design decisions for
> > the entire K3 generation of chips, leaving the specifics for that
> > particular SoC to a unique sub-page below this one.
> > 
> > Signed-off-by: Bryan Brattlof <bb at ti.com>
> > ---

...

> > +
> > +Boot Flow Overview
> > +------------------
> > +
> > +For all K3 SoCs the first core started will be inside the Security
> > +Management Subsystem (SMS) which will secure the device and start a core
> 
> 
> This name (SMS, DMSC, HSM) changes over the K3 devices, how about just
> "Security Enclave".
> 

Good point... I'll get this updated.

> > +in the wakeup domain to run the ROM code. ROM will then initialize the
> 
> Not always in the wakeup domain either.. Also what "ROM code", the "Security
> Enclave" also has ROM code, should refer to this second ROM as "Public ROM".
> 

True and I was trying to keep Public vs Private ROM out of this, but I'm 
good with this if you are :)

> > +boot media needed to load the binaries packaged inside `tiboot3.bin`,
> > +including a 32bit U-Boot SPL, (called the wakup SPL) that ROM will jump
> 
> Does anyone call it "wakeup SPL"? I'd call it R5 SPL everywhere.
> 

haha I started calling it the wakup spl because calling it the r5 spl 
felt too specific

> > +to after it has finished loading everything into internal SRAM.
> > +
> > +.. code-block:: text
> > +
> > +   |  WKUP Domain
> > +    ROM -> WKUP SPL ->
> > +
> > +The wakeup SPL, running on a wakeup domain core, will initialize DDR and
> > +any peripherals needed load the larger binaries inside the `tispl.bin`
> 
> Some of this is sounding specific to file-system based boot modes, might
> be good to pick a name for this blob, then point out what we expect it
> to be called when still on filesystems.
>

Ah that's true. I think I can do that

> > +into DDR.  Once loaded the wakeup SPL will start one of the 'big'
> > +application cores inside the main domain to initialize the main domain,
> > +starting with ARM Trusted Firmware (ATF), before moving on to start
> > +OPTEE and the main domain's U-Boot SPL.
> > +
> > +.. code-block:: text
> > +
> > +   |  WKUP Domain   | Main Domain ->
> > +    ROM -> WKUP SPL -> ATF -> OPTEE -> Main SPL
> > +
> > +The main domain's SPL, running on a 64bit application core, has
> > +virtually unlimited space (billions of bytes now that DDR is working) to
> > +initialize even more peripherals needed to load in the `u-boot.img`
> > +which loads more firmware into the micro-controller & wakeup domains and
> 
> Also loads up cores in the MAIN domain, could be easier to make this generic.
>

Didn't think many people used that unprofessional hobby project ;)

> > +finally prepare the main domain to run Linux.
> > +
> > +.. code-block:: text
> > +
> > +   |  WKUP Domain   | Main Domain ->
> > +    ROM -> WKUP SPL -> ATF -> OPTEE -> Main SPL -> UBoot -> Linux
> > +
> 
> Could help to lay this out virtually, since the R5 core keeps running
> after the MAIN domain is running, it is not a direct execution handover.
>

Ah that's a good idea, kinda like what we already have for the am62x 
documentation.

> > +This is the typical boot flow for all K3 based SoCs, however this flow
> > +offers quite a lot in the terms of flexibility, especially on High
> > +Security (HS) SoCs.
> > +
> > +Boot Flow Variations
> > +^^^^^^^^^^^^^^^^^^^^
> > +
> > +All K3 SoCs will generally use the above boot flow with two main
> > +differences depending on the capabilities of the boot ROM and the number
> > +of cores inside the device. These differences split the bootflow into
> > +essentially 4 unique but very similar flows:
> > +
> > +* Split binary with a combined firmware: (eg: AM65)
> 
> What binary/firmware is split, you have not talked about SYSFW/TIFS/DM at this point yet..
>

Oh good point... This could use a reordering.

> > +* Combined binary with a combined firmware: (eg: AM64)
> > +* Split binary with a split firmware: (eg: J721E)
> > +* Combined binary with a split firmware: (eg: AM62)
> > +
> > +For devices that utilize the split binary approach, ROM is not capable
> > +of loading the firmware into the SoC requiring the wakeup domain's
> > +U-Boot SPL to load the firmware.
> > +
> > +Devices with a split firmware will have two firmwares loaded into the
> > +device at different times during the bootup process. TI's Foundational
> > +Security (TIFS), needed to operate the Security Management Subsystem,
> > +will either be loaded by ROM or the WKUP U-Boot SPL, then once the
> > +wakeup U-Boot SPL has completed, the second Device Management (DM)
> > +firmware can be loaded on the now free core in the wakeup domain.
> > +
> 
> Could help to draw this one out visually.
> 

Yeah more visuals couldn't hurt

> > +
> > +.. code-block:: bash
> > +
> > +   # inside k3-image-gen source
> > +   make CROSS_COMPILE=$CC32 SOC={SOC} SOC_TYPE={hs,gp} \
> > +        TI_SECURE_DEV_PKG=<path/to/securit-development-tools> \
> 
> s/securit/security
> 

Good catch!

Thanks for the review Andrew!
~Bryan