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

Wed Aug 23 17:30:31 CEST 2023

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.

> + $ export TFA_BOARD=lite
> + $ # we dont use any extra TFA parameters
> + $ unset TFA_EXTRA_ARGS
> + $ export OPTEE_PLATFORM=k3-am62x
> + $ export OPTEE_EXTRA_ARGS="CFG_WITH_SOFTWARE_PRNG=y"
> +
> +.. include::  am62x_sk.rst
> +    :start-after: .. am62x_evm_rst_include_start_build_steps
> +    :end-before: .. am62x_evm_rst_include_end_build_steps
> +
> +Target Images
> +--------------
> +Copy the below images to an SD card and boot:
> +
> +* tiboot3-am62x-gp-evm.bin from R5 build as tiboot3.bin
> +* tispl.bin_unsigned from Cortex-A build as tispl.bin
> +* u-boot.img_unsigned from Cortex-A build as uboot.img
> +
> +Image formats:
> +--------------
> +
> +- tiboot3.bin
> +
> +.. image:: img/multi_cert_tiboot3.bin.svg
> +  :alt: tiboot3.bin image format
> +
> +- tispl.bin
> +
> +.. image:: img/dm_tispl.bin.svg
> +  :alt: tispl.bin image format
> +
> +Flash to eMMC
> +-------------
> +
> +The eMMC layout selected is user-friendly for developers. The
> +boot hardware partition of the eMMC only contains the fixed-size
> +tiboot3.bin image. This is because the contents of the boot partitions
> +need to run from the SoC's internal SRAM, which remains a fixed size
> +constant. The other components of the boot sequence, such as tispl.bin
> +and u-boot.img, are located in the /BOOT partition in the User Defined
> +Area (UDA) hardware partition of the eMMC. These components can vary
> +significantly in size, so readjusting the boot partition offsets is
> +not practical.
> +
> +.. image:: img/beagleplay_emmc.svg
> +  :alt: eMMC partitions and boot file organization for BeaglePlay
> +
> +The following are the steps from Linux shell to program eMMC:
> +
> +.. code-block:: bash
> +
> +  # # Enable Boot0 boot
> +  # mmc bootpart enable 1 2 /dev/mmcblk0
> +  # mmc bootbus set single_backward x1 x8 /dev/mmcblk0
> +  # mmc hwreset enable /dev/mmcblk0
> +
> +  # # Clear eMMC boot0
> +  # echo '0' >> /sys/class/block/mmcblk0boot0/force_ro
> +  # dd if=/dev/zero of=/dev/mmcblk0boot0 count=32 bs=128k
> +  # # Write tiboot3.bin
> +  # dd if=tiboot3.bin of=/dev/mmcblk0boot0 bs=128k
> +
> +  # # Copy the rest of the boot binaries
> +  # mount /dev/mmcblk0p1 /boot/firmware
> +  # cp tispl.bin /boot/firmware
> +  # cp u-boot.img /boot/firmware
> +  # sync
> +
> +.. warning ::
> +
> +  The U-Boot is configured to prioritize booting from an SD card if

U-Boot is configured

> +  it detects a valid boot partition and boot files on it, even if the
> +  system initially booted from eMMC. The boot order is set as follows:
> +
> +  * SD/MMC
> +  * eMMC
> +  * USB
> +  * PXE
> +
[..]

Regards,
Simon