[3/3] docs: ti: j721s2_evm: Create documentation from J7200 docs

The documentation is based off J7200 documentation tailored for J721S2.

TRM for J721S2: https://www.ti.com/lit/pdf/spruj28
Product Page: https://www.ti.com/product/TDA4AL-Q1

Signed-off-by: Manorit Chawdhry <m-chawdhry@ti.com>
---
 MAINTAINERS                 |   1 +
 doc/board/ti/j721s2_evm.rst | 228 ++++++++++++++++++++++++++++++++++++++++++++
 doc/board/ti/k3.rst         |   1 +
 3 files changed, 230 insertions(+)

On 14:53-20230816, Manorit Chawdhry wrote:
> The documentation is based off J7200 documentation tailored for J721S2.
> 
> TRM for J721S2: https://www.ti.com/lit/pdf/spruj28
> Product Page: https://www.ti.com/product/TDA4AL-Q1
> 
> Signed-off-by: Manorit Chawdhry <m-chawdhry@ti.com>
> ---
>  MAINTAINERS                 |   1 +
>  doc/board/ti/j721s2_evm.rst | 228 ++++++++++++++++++++++++++++++++++++++++++++
>  doc/board/ti/k3.rst         |   1 +
>  3 files changed, 230 insertions(+)
> 
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 77a8b0ac2181..1b14ce541e91 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -667,6 +667,7 @@ F:	arch/arm/mach-omap2/
>  F:	arch/arm/include/asm/arch-omap*/
>  F:	arch/arm/include/asm/ti-common/
>  F:	board/ti/
> +F:	doc/board/ti
>  F:	drivers/dma/ti*
>  F:	drivers/firmware/ti_sci.*
>  F:	drivers/gpio/omap_gpio.c

if this is a proposal, split this into it's own patch please.
doc/board/ti is a wide range. I'd suggest do the specific
documentation in the board specific MAINTAINER file as well to spread
the maintainership load over.


> diff --git a/doc/board/ti/j721s2_evm.rst b/doc/board/ti/j721s2_evm.rst
> new file mode 100644
> index 000000000000..519e43610dcf
> --- /dev/null
> +++ b/doc/board/ti/j721s2_evm.rst
> @@ -0,0 +1,228 @@
> +.. SPDX-License-Identifier: GPL-2.0+ OR BSD-3-Clause
> +.. sectionauthor:: Manorit Chawdhry <m-chawdhry@ti.com>
> +
> +J721S2 Platforms
> +================
> +
> +Introduction:
> +-------------
> +The J721S2 family of SoCs are part of K3 Multicore SoC architecture platform
> +targeting automotive applications. They are designed as a low power, high
> +performance and highly integrated device architecture, adding significant
> +enhancement on processing power, graphics capability, video and imaging
> +processing, virtualization and coherent memory support.
> +
> +The device is partitioned into three functional domains, each containing
> +specific processing cores and peripherals:
> +
> +1. Wake-up (WKUP) domain:
> +        * Device Management and Security Controller (DMSC)
> +
> +2. Microcontroller (MCU) domain:
> +        * Dual Core ARM Cortex-R5F processor
> +
> +3. MAIN domain:
> +        * Dual core 64-bit ARM Cortex-A72
> +
> +More info can be found in TRM: https://www.ti.com/lit/pdf/spruj28
> +
> +Platform information:
> +
> +* https://www.ti.com/tool/J721S2XSOMXEVM
> +
> +Boot Flow:
> +----------
> +Below is the pictorial representation of boot flow:
> +
> +.. image:: img/boot_diagram_k3_current.svg
> +
> +- Here DMSC acts as master and provides all the critical services. R5/A72
> +  requests DMSC to get these services done as shown in the above diagram.

Is this statement accurate? in J7200, DMSC provides a pure TIFS function.

Maybe improve it with a version of the following, perhaps?

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.
As illustrated in the diagram above, R5 SPL manages power and clock
services independently before handing over control to "DM." The A53 or
the M4F (Aux core) software components request TIFS/DM to handle
security or device management services.

> +
> +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=j721s2_evm_r5_defconfig
> + $ export UBOOT_CFG_CORTEXA=j721s2_evm_a72_defconfig
> + $ export TFA_BOARD=generic
> + $ export TFA_EXTRA_ARGS="K3_USART=0x8"
> + $ # This is not a typo, j784s4 is the
> + $ # OP-TEE platform for j721s2
> + $ export OPTEE_PLATFORM=k3-j784s4
> + $ export OPTEE_EXTRA_ARGS="CFG_CONSOLE_UART=0x8"
> +
> +.. j721s2_evm_rst_include_start_build_steps
> +
> +1. Trusted Firmware-A:
> +
> +.. include::  k3.rst
> +    :start-after: .. k3_rst_include_start_build_steps_tfa
> +    :end-before: .. k3_rst_include_end_build_steps_tfa
> +
> +
> +2. OP-TEE:
> +
> +.. include::  k3.rst
> +    :start-after: .. k3_rst_include_start_build_steps_optee
> +    :end-before: .. k3_rst_include_end_build_steps_optee
> +
> +3. U-Boot:
> +
> +* 4.1 R5:

4.1 or 3.1 ?

> +
> +.. include::  k3.rst
> +    :start-after: .. k3_rst_include_start_build_steps_spl_r5
> +    :end-before: .. k3_rst_include_end_build_steps_spl_r5
> +
> +* 4.2 A72:

same.
> +
> +.. include::  k3.rst
> +    :start-after: .. k3_rst_include_start_build_steps_uboot
> +    :end-before: .. k3_rst_include_end_build_steps_uboot
> +.. j721s2_evm_rst_include_end_build_steps
> +
> +Target Images
> +--------------
> +In order to boot we need tiboot3.bin, tispl.bin and u-boot.img. Each SoC
> +variant (GP, HS-FS, HS-SE) requires a different source for these files.
> +
> + - GP
> +
> +        * tiboot3-j721s2-gp-evm.bin from step 4.1

I think we should just use https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html#explicit-targets
to do provide references than numbered scheme.


> +        * tispl.bin_unsigned, u-boot.img_unsigned from step 4.2
> +
> + - HS-FS
> +
> +        * tiboot3-j721s2-hs-fs-evm.bin from step 4.1
> +        * tispl.bin, u-boot.img from step 4.2

These as well

> +
> + - HS-SE
> +
> +        * tiboot3-j721s2-hs-evm.bin from step 4.1
> +        * tispl.bin, u-boot.img from step 4.2

and here.

I just noticed we have a similar problem in other rst files as well.
might be worth a cleanup.

> +
> +Image formats:
> +--------------
> +
> +- tiboot3.bin
> +
> +.. image:: img/multi_cert_tiboot3.bin.svg
> +
> +- tispl.bin
> +
> +.. image:: img/dm_tispl.bin.svg
> +
> +R5 Memory Map:
> +--------------
> +
> +.. list-table::
> +   :widths: 16 16 16
> +   :header-rows: 1
> +
> +   * - Region
> +     - Start Address
> +     - End Address
> +
> +   * - SPL
> +     - 0x41c00000
> +     - 0x41c40000
> +
> +   * - EMPTY
> +     - 0x41c40000
> +     - 0x41c61f20
> +
> +   * - STACK
> +     - 0x41c65f20
> +     - 0x41c61f20
> +
> +   * - Global data
> +     - 0x41c65f20
> +     - 0x41c66000
> +
> +   * - Heap
> +     - 0x41c66000
> +     - 0x41c76000
> +
> +   * - BSS
> +     - 0x41c76000
> +     - 0x41c80000
> +
> +   * - DM DATA
> +     - 0x41c80000
> +     - 0x41c84130
> +
> +   * - EMPTY
> +     - 0x41c84130
> +     - 0x41cff9fc
> +
> +   * - MCU Scratchpad
> +     - 0x41cff9fc
> +     - 0x41cffbfc
> +
> +   * - ROM DATA
> +     - 0x41cffbfc
> +     - 0x41cfffff
> +
> +Switch Setting for Boot Mode
> +----------------------------
> +
> +Boot Mode pins provide means to select the boot mode and options before the
> +device is powered up. After every POR, they are the main source to populate
> +the Boot Parameter Tables.
> +
> +The following table shows some common boot modes used on J721S2 platform.
> +More details can be found in the Technical Reference Manual:
> +https://www.ti.com/lit/pdf/spruj28 under the `Boot Mode Pins` section.
> +
> +.. list-table:: Boot Modes
> +   :widths: 16 16 16
> +   :header-rows: 1
> +
> +   * - Switch Label
> +     - SW9: 12345678
> +     - SW8: 12345678
> +
> +   * - SD
> +     - 00000000
> +     - 10000010
> +
> +   * - EMMC
> +     - 01000000
> +     - 10000000
> +
> +   * - OSPI
> +     - 01000000
> +     - 00000110
> +
> +   * - UART
> +     - 01110000
> +     - 00000000
> +
> +   * - USB DFU
> +     - 00100000
> +     - 10000000
> +
> +For SW8 and SW9, the switch state in the "ON" position = 1.

We need to add the section on openOCD, but I think next does'nt have
the commit for the same - so we might need to do that as a separate
patch.

> diff --git a/doc/board/ti/k3.rst b/doc/board/ti/k3.rst
> index d2f86b0a11a7..b0be048edb12 100644
> --- a/doc/board/ti/k3.rst
> +++ b/doc/board/ti/k3.rst
> @@ -35,6 +35,7 @@ K3 Based SoCs
>     am65x_evm
>     j7200_evm
>     j721e_evm
> +   j721s2_evm
>  
>  Boot Flow Overview
>  ------------------
> 
> -- 
> 2.41.0
>

Hi Nishanth,

On 10:35-20230816, Nishanth Menon wrote:
> On 14:53-20230816, Manorit Chawdhry wrote:
> > The documentation is based off J7200 documentation tailored for J721S2.
> > 
> > TRM for J721S2: https://www.ti.com/lit/pdf/spruj28
> > Product Page: https://www.ti.com/product/TDA4AL-Q1
> > 
> > Signed-off-by: Manorit Chawdhry <m-chawdhry@ti.com>
> > ---
> >  MAINTAINERS                 |   1 +
> >  doc/board/ti/j721s2_evm.rst | 228 ++++++++++++++++++++++++++++++++++++++++++++
> >  doc/board/ti/k3.rst         |   1 +
> >  3 files changed, 230 insertions(+)
> > 
> > diff --git a/MAINTAINERS b/MAINTAINERS
> > index 77a8b0ac2181..1b14ce541e91 100644
> > --- a/MAINTAINERS
> > +++ b/MAINTAINERS
> > @@ -667,6 +667,7 @@ F:	arch/arm/mach-omap2/
> >  F:	arch/arm/include/asm/arch-omap*/
> >  F:	arch/arm/include/asm/ti-common/
> >  F:	board/ti/
> > +F:	doc/board/ti
> >  F:	drivers/dma/ti*
> >  F:	drivers/firmware/ti_sci.*
> >  F:	drivers/gpio/omap_gpio.c
> 
> if this is a proposal, split this into it's own patch please.
> doc/board/ti is a wide range. I'd suggest do the specific
> documentation in the board specific MAINTAINER file as well to spread
> the maintainership load over.
> 

Ah yes, I hadn't found the board specific MAINTAINER file. 

Can you suggest whom to keep the MAINTAINER for J721S2? The previous 
maintainer seems stale, Aswath Govindraju <a-govindraju@ti.com> is no 
longer in TI. Let me know if I can take the ownership for J721S2.

> 
> > diff --git a/doc/board/ti/j721s2_evm.rst b/doc/board/ti/j721s2_evm.rst
> > new file mode 100644
> > index 000000000000..519e43610dcf
> > --- /dev/null
> > +++ b/doc/board/ti/j721s2_evm.rst
> > @@ -0,0 +1,228 @@
> > +.. SPDX-License-Identifier: GPL-2.0+ OR BSD-3-Clause
> > +.. sectionauthor:: Manorit Chawdhry <m-chawdhry@ti.com>
> > +
> > +J721S2 Platforms
> > +================
> > +
> > +Introduction:
> > +-------------
> > +The J721S2 family of SoCs are part of K3 Multicore SoC architecture platform
> > +targeting automotive applications. They are designed as a low power, high
> > +performance and highly integrated device architecture, adding significant
> > +enhancement on processing power, graphics capability, video and imaging
> > +processing, virtualization and coherent memory support.
> > +
> > +The device is partitioned into three functional domains, each containing
> > +specific processing cores and peripherals:
> > +
> > +1. Wake-up (WKUP) domain:
> > +        * Device Management and Security Controller (DMSC)
> > +
> > +2. Microcontroller (MCU) domain:
> > +        * Dual Core ARM Cortex-R5F processor
> > +
> > +3. MAIN domain:
> > +        * Dual core 64-bit ARM Cortex-A72
> > +
> > +More info can be found in TRM: https://www.ti.com/lit/pdf/spruj28
> > +
> > +Platform information:
> > +
> > +* https://www.ti.com/tool/J721S2XSOMXEVM
> > +
> > +Boot Flow:
> > +----------
> > +Below is the pictorial representation of boot flow:
> > +
> > +.. image:: img/boot_diagram_k3_current.svg
> > +
> > +- Here DMSC acts as master and provides all the critical services. R5/A72
> > +  requests DMSC to get these services done as shown in the above diagram.
> 
> Is this statement accurate? in J7200, DMSC provides a pure TIFS function.
> 
> Maybe improve it with a version of the following, perhaps?
> 
> 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.
> As illustrated in the diagram above, R5 SPL manages power and clock
> services independently before handing over control to "DM." The A53 or
> the M4F (Aux core) software components request TIFS/DM to handle
> security or device management services.
> 

Ah yes, this is much better. Thanks! Will be updating it.

> > +
> > +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=j721s2_evm_r5_defconfig
> > + $ export UBOOT_CFG_CORTEXA=j721s2_evm_a72_defconfig
> > + $ export TFA_BOARD=generic
> > + $ export TFA_EXTRA_ARGS="K3_USART=0x8"
> > + $ # This is not a typo, j784s4 is the
> > + $ # OP-TEE platform for j721s2
> > + $ export OPTEE_PLATFORM=k3-j784s4
> > + $ export OPTEE_EXTRA_ARGS="CFG_CONSOLE_UART=0x8"
> > +
> > +.. j721s2_evm_rst_include_start_build_steps
> > +
> > +1. Trusted Firmware-A:
> > +
> > +.. include::  k3.rst
> > +    :start-after: .. k3_rst_include_start_build_steps_tfa
> > +    :end-before: .. k3_rst_include_end_build_steps_tfa
> > +
> > +
> > +2. OP-TEE:
> > +
> > +.. include::  k3.rst
> > +    :start-after: .. k3_rst_include_start_build_steps_optee
> > +    :end-before: .. k3_rst_include_end_build_steps_optee
> > +
> > +3. U-Boot:
> > +
> > +* 4.1 R5:
> 
> 4.1 or 3.1 ?
> 

Oversight.. will fix it.

> > +
> > +.. include::  k3.rst
> > +    :start-after: .. k3_rst_include_start_build_steps_spl_r5
> > +    :end-before: .. k3_rst_include_end_build_steps_spl_r5
> > +
> > +* 4.2 A72:
> 
> same.
> > +
> > +.. include::  k3.rst
> > +    :start-after: .. k3_rst_include_start_build_steps_uboot
> > +    :end-before: .. k3_rst_include_end_build_steps_uboot
> > +.. j721s2_evm_rst_include_end_build_steps
> > +
> > +Target Images
> > +--------------
> > +In order to boot we need tiboot3.bin, tispl.bin and u-boot.img. Each SoC
> > +variant (GP, HS-FS, HS-SE) requires a different source for these files.
> > +
> > + - GP
> > +
> > +        * tiboot3-j721s2-gp-evm.bin from step 4.1
> 
> I think we should just use https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html#explicit-targets
> to do provide references than numbered scheme.
> 

Ah yes, this seems good. Thanks! Will be updating it.

Regards,
Manorit

> 
> > +        * tispl.bin_unsigned, u-boot.img_unsigned from step 4.2
> > +
> > + - HS-FS
> > +
> > +        * tiboot3-j721s2-hs-fs-evm.bin from step 4.1
> > +        * tispl.bin, u-boot.img from step 4.2
> 
> These as well
> 
> > +
> > + - HS-SE
> > +
> > +        * tiboot3-j721s2-hs-evm.bin from step 4.1
> > +        * tispl.bin, u-boot.img from step 4.2
> 
> and here.
> 
> I just noticed we have a similar problem in other rst files as well.
> might be worth a cleanup.
> 
> > +
> > +Image formats:
> > +--------------
> > +
> > +- tiboot3.bin
> > +
> > +.. image:: img/multi_cert_tiboot3.bin.svg
> > +
> > +- tispl.bin
> > +
> > +.. image:: img/dm_tispl.bin.svg
> > +
> > +R5 Memory Map:
> > +--------------
> > +
> > +.. list-table::
> > +   :widths: 16 16 16
> > +   :header-rows: 1
> > +
> > +   * - Region
> > +     - Start Address
> > +     - End Address
> > +
> > +   * - SPL
> > +     - 0x41c00000
> > +     - 0x41c40000
> > +
> > +   * - EMPTY
> > +     - 0x41c40000
> > +     - 0x41c61f20
> > +
> > +   * - STACK
> > +     - 0x41c65f20
> > +     - 0x41c61f20
> > +
> > +   * - Global data
> > +     - 0x41c65f20
> > +     - 0x41c66000
> > +
> > +   * - Heap
> > +     - 0x41c66000
> > +     - 0x41c76000
> > +
> > +   * - BSS
> > +     - 0x41c76000
> > +     - 0x41c80000
> > +
> > +   * - DM DATA
> > +     - 0x41c80000
> > +     - 0x41c84130
> > +
> > +   * - EMPTY
> > +     - 0x41c84130
> > +     - 0x41cff9fc
> > +
> > +   * - MCU Scratchpad
> > +     - 0x41cff9fc
> > +     - 0x41cffbfc
> > +
> > +   * - ROM DATA
> > +     - 0x41cffbfc
> > +     - 0x41cfffff
> > +
> > +Switch Setting for Boot Mode
> > +----------------------------
> > +
> > +Boot Mode pins provide means to select the boot mode and options before the
> > +device is powered up. After every POR, they are the main source to populate
> > +the Boot Parameter Tables.
> > +
> > +The following table shows some common boot modes used on J721S2 platform.
> > +More details can be found in the Technical Reference Manual:
> > +https://www.ti.com/lit/pdf/spruj28 under the `Boot Mode Pins` section.
> > +
> > +.. list-table:: Boot Modes
> > +   :widths: 16 16 16
> > +   :header-rows: 1
> > +
> > +   * - Switch Label
> > +     - SW9: 12345678
> > +     - SW8: 12345678
> > +
> > +   * - SD
> > +     - 00000000
> > +     - 10000010
> > +
> > +   * - EMMC
> > +     - 01000000
> > +     - 10000000
> > +
> > +   * - OSPI
> > +     - 01000000
> > +     - 00000110
> > +
> > +   * - UART
> > +     - 01110000
> > +     - 00000000
> > +
> > +   * - USB DFU
> > +     - 00100000
> > +     - 10000000
> > +
> > +For SW8 and SW9, the switch state in the "ON" position = 1.
> 
> We need to add the section on openOCD, but I think next does'nt have
> the commit for the same - so we might need to do that as a separate
> patch.
> 
> > diff --git a/doc/board/ti/k3.rst b/doc/board/ti/k3.rst
> > index d2f86b0a11a7..b0be048edb12 100644
> > --- a/doc/board/ti/k3.rst
> > +++ b/doc/board/ti/k3.rst
> > @@ -35,6 +35,7 @@ K3 Based SoCs
> >     am65x_evm
> >     j7200_evm
> >     j721e_evm
> > +   j721s2_evm
> >  
> >  Boot Flow Overview
> >  ------------------
> > 
> > -- 
> > 2.41.0
> > 
> 
> -- 
> Regards,
> Nishanth Menon
> Key (0xDDB5849D1736249D) / Fingerprint: F8A2 8693 54EB 8232 17A3  1A34 DDB5 849D 1736 249D

On 13:42-20230817, Manorit Chawdhry wrote:
[...]
> 
> Ah yes, I hadn't found the board specific MAINTAINER file. 
> 
> Can you suggest whom to keep the MAINTAINER for J721S2? The previous 
> maintainer seems stale, Aswath Govindraju <a-govindraju@ti.com> is no 
> longer in TI. Let me know if I can take the ownership for J721S2.

Please propose as a patch if you are able to volunteer.