doc/board/ti/am62x_beagleplay.rst

   1 .. SPDX-License-Identifier: GPL-2.0+ OR BSD-3-Clause
   2 .. sectionauthor:: Nishanth Menon <nm@ti.com>
   3
   4 AM62x Beagleboard.org Beagleplay
   5 ================================
   6
   7 Introduction:
   8 -------------
   9
  10 BeagleBoard.org BeaglePlay is an easy to use, affordable open source
  11 hardware single board computer based on the Texas Instruments AM625
  12 SoC that allows you to create connected devices that work even at long
  13 distances using IEEE 802.15.4g LR-WPAN and IEEE 802.3cg 10Base-T1L.
  14 Expansion is provided over open standards based mikroBUS, Grove and
  15 QWIIC headers among other interfaces.
  16
  17 Further information can be found at:
  18
  19 * Product Page: https://beagleplay.org/
  20 * Hardware documentation: https://git.beagleboard.org/beagleplay/beagleplay
  21
  22 Boot Flow:
  23 ----------
  24 Below is the pictorial representation of boot flow:
  25
  26 .. image:: img/boot_diagram_k3_current.svg
  27   :alt: Boot flow diagram
  28
  29 - On this platform, 'TI Foundational Security' (TIFS) functions as the
  30   security enclave master while 'Device Manager' (DM), also known as the
  31   'TISCI server' in "TI terminology", offers all the essential services.
  32   The A53 or M4F (Aux core) sends requests to TIFS/DM to accomplish these
  33   services, as illustrated in the diagram above.
  34
  35 Sources:
  36 --------
  37 .. include::  k3.rst
  38     :start-after: .. k3_rst_include_start_boot_sources
  39     :end-before: .. k3_rst_include_end_boot_sources
  40
  41 Build procedure:
  42 ----------------
  43 0. Setup the environment variables:
  44
  45 .. include::  k3.rst
  46     :start-after: .. k3_rst_include_start_common_env_vars_desc
  47     :end-before: .. k3_rst_include_end_common_env_vars_desc
  48
  49 .. include::  k3.rst
  50     :start-after: .. k3_rst_include_start_board_env_vars_desc
  51     :end-before: .. k3_rst_include_end_board_env_vars_desc
  52
  53 Set the variables corresponding to this platform:
  54
  55 .. include::  k3.rst
  56     :start-after: .. k3_rst_include_start_common_env_vars_defn
  57     :end-before: .. k3_rst_include_end_common_env_vars_defn
  58 .. code-block:: bash
  59
  60  $ export UBOOT_CFG_CORTEXR="am62x_evm_r5_defconfig beagleplay_r5.config"
  61  $ export UBOOT_CFG_CORTEXA="am62x_evm_a53_defconfig beagleplay_a53.config"
  62  $ export TFA_BOARD=lite
  63  $ # we dont use any extra TFA parameters
  64  $ unset TFA_EXTRA_ARGS
  65  $ export OPTEE_PLATFORM=k3-am62x
  66  $ export OPTEE_EXTRA_ARGS="CFG_WITH_SOFTWARE_PRNG=y"
  67
  68 .. include::  am62x_sk.rst
  69     :start-after: .. am62x_evm_rst_include_start_build_steps
  70     :end-before: .. am62x_evm_rst_include_end_build_steps
  71
  72 Target Images
  73 --------------
  74 Copy the below images to an SD card and boot:
  75
  76 * tiboot3-am62x-gp-evm.bin from R5 build as tiboot3.bin
  77 * tispl.bin_unsigned from Cortex-A build as tispl.bin
  78 * u-boot.img_unsigned from Cortex-A build as u-boot.img
  79
  80 Image formats
  81 -------------
  82
  83 - tiboot3.bin
  84
  85 .. image:: img/multi_cert_tiboot3.bin.svg
  86   :alt: tiboot3.bin image format
  87
  88 - tispl.bin
  89
  90 .. image:: img/dm_tispl.bin.svg
  91   :alt: tispl.bin image format
  92
  93 Additional hardware for U-Boot development
  94 ------------------------------------------
  95
  96 * Serial Console is critical for U-Boot development on BeaglePlay. See
  97   `BeaglePlay serial console documentation
  98   <https://docs.beagleboard.org/latest/boards/beagleplay/demos-and-tutorials/using-serial-console.html>`_.
  99 * uSD is preferred option over eMMC, and a SD/MMC reader will be needed.
 100 * (optionally) JTAG is useful when working with very early stages of boot.
 101
 102 Default storage options
 103 -----------------------
 104
 105 There are multiple storage media options on BeaglePlay, but primarily:
 106
 107 * Onboard eMMC (default) - reliable, fast and meant for deployment use.
 108 * SD/MMC card interface (hold 'USR' switch and power on) - Entirely
 109   depends on the SD card quality.
 110
 111 Flash to uSD card or how to deal with "bricked" Board
 112 --------------------------------------------------------
 113
 114 When deploying or working on Linux, it's common to use the onboard
 115 eMMC. However, avoiding the eMMC and using the uSD card is safer when
 116 working with U-Boot.
 117
 118 If you choose to  hand format your own bootable uSD card, be
 119 aware that it can be difficult. The following information
 120 may be helpful, but remember that it is only sometimes
 121 reliable, and partition options can cause issues. These
 122 can potentially help:
 123
 124 * https://git.ti.com/cgit/arago-project/tisdk-setup-scripts/tree/create-sdcard.sh
 125 * https://elinux.org/Beagleboard:Expanding_File_System_Partition_On_A_microSD
 126
 127 The simplest option is to start with a standard distribution
 128 image like those in `BeagleBoard.org Distros Page
 129 <https://www.beagleboard.org/distros>`_ and download a disk image for
 130 BeaglePlay. Pick a 16GB+ uSD card to be on the safer side.
 131
 132 With an SD/MMC Card reader and `Balena Etcher
 133 <https://etcher.balena.io/>`_, having a functional setup in minutes is
 134 a trivial matter, and it works on almost all Host Operating Systems.
 135 Yes Windows users, Windows Subsystem for Linux(WSL) based development
 136 with U-Boot and update uSD card is practical.
 137
 138 Updating U-Boot is a matter of copying the tiboot3.bin, tispl.bin and
 139 u-boot.img to the "BOOT" partition of the uSD card. Remember to sync
 140 and unmount (or Eject - depending on the Operating System) the uSD
 141 card prior to physically removing from SD card reader.
 142
 143 Also see following section on switch setting used for booting using
 144 uSD card.
 145
 146 .. note::
 147   Great news! If the board has not been damaged physically, there's no
 148   need to worry about it being "bricked" on this platform. You only have
 149   to flash an uSD card, plug it in, and reinstall the image on eMMC. This
 150   means that even if you make a mistake, you can quickly fix it and rest
 151   easy.
 152
 153   If you are frequently working with uSD cards, you might find the
 154   following useful:
 155
 156   * `USB-SD-Mux <https://www.linux-automation.com/en/products/usb-sd-mux.html>`_
 157   * `SD-Wire <https://wiki.tizen.org/SDWire>`_
 158
 159 Flash to eMMC
 160 -------------
 161
 162 The eMMC layout selected is user-friendly for developers. The
 163 boot hardware partition of the eMMC only contains the fixed-size
 164 tiboot3.bin image. This is because the contents of the boot partitions
 165 need to run from the SoC's internal SRAM, which remains a fixed size
 166 constant. The other components of the boot sequence, such as tispl.bin
 167 and u-boot.img, are located in the /BOOT partition in the User Defined
 168 Area (UDA) hardware partition of the eMMC. These components can vary
 169 significantly in size. The choice of keeping tiboot3.bin in boot0 or
 170 boot1 partition depends on A/B update requirements.
 171
 172 .. image:: img/beagleplay_emmc.svg
 173   :alt: eMMC partitions and boot file organization for BeaglePlay
 174
 175 The following are the steps from Linux shell to program eMMC:
 176
 177 .. code-block:: bash
 178
 179   # # Enable Boot0 boot
 180   # mmc bootpart enable 1 2 /dev/mmcblk0
 181   # mmc bootbus set single_backward x1 x8 /dev/mmcblk0
 182   # mmc hwreset enable /dev/mmcblk0
 183
 184   # # Clear eMMC boot0
 185   # echo '0' >> /sys/class/block/mmcblk0boot0/force_ro
 186   # dd if=/dev/zero of=/dev/mmcblk0boot0 count=32 bs=128k
 187   # # Write tiboot3.bin
 188   # dd if=tiboot3.bin of=/dev/mmcblk0boot0 bs=128k
 189
 190   # # Copy the rest of the boot binaries
 191   # mount /dev/mmcblk0p1 /boot/firmware
 192   # cp tispl.bin /boot/firmware
 193   # cp u-boot.img /boot/firmware
 194   # sync
 195
 196 .. warning ::
 197
 198   U-Boot is configured to prioritize booting from an SD card if it
 199   detects a valid boot partition and boot files on it, even if the
 200   system initially booted from eMMC. The boot order is set as follows:
 201
 202   * SD/MMC
 203   * eMMC
 204   * USB
 205   * PXE
 206
 207 LED patterns during boot
 208 ------------------------
 209
 210 .. list-table:: USR LED status indication
 211    :widths: 16 16
 212    :header-rows: 1
 213
 214    * - USR LEDs (012345)
 215      - Indicates
 216
 217    * - 00000
 218      - Boot failure or R5 image not started up
 219
 220    * - 11111
 221      - A53 SPL/U-boot has started up
 222
 223    * - 10101
 224      - OS boot process has been initiated
 225
 226    * - 01010
 227      - OS boot process failed and drops to U-Boot shell
 228
 229 .. note ::
 230
 231   In the table above, 0 indicates LED switched off and 1 indicates LED
 232   switched ON.
 233
 234 .. warning ::
 235
 236   If the "red" power LED is not glowing, the system power supply is not
 237   functional. Please refer to `BeaglePlay documentation
 238   <https://beagleplay.org/>`_ for further information.
 239
 240 A53 SPL DDR Memory Layout
 241 -------------------------
 242
 243 .. include::  am62x_sk.rst
 244     :start-after: .. am62x_evm_rst_include_start_ddr_mem_layout
 245     :end-before: .. am62x_evm_rst_include_end_ddr_mem_layout
 246
 247 Switch Setting for Boot Mode
 248 ----------------------------
 249
 250 The boot time option is configured via "USR" button on the board.
 251 See `Beagleplay Schematics <https://git.beagleboard.org/beagleplay/beagleplay/-/blob/main/BeaglePlay_sch.pdf>`_
 252 for details.
 253
 254 .. list-table:: Boot Modes
 255    :widths: 16 16 16
 256    :header-rows: 1
 257
 258    * - USR Switch Position
 259      - Primary Boot
 260      - Secondary Boot
 261
 262    * - Not Pressed
 263      - eMMC
 264      - UART
 265
 266    * - Pressed
 267      - SD/MMC File System (FS) mode
 268      - USB Device Firmware Upgrade (DFU) mode
 269
 270 To switch to SD card boot mode, hold the USR button while powering on
 271 with Type-C power supply, then release when power LED lights up.
 272
 273 Debugging U-Boot
 274 ----------------
 275
 276 See :ref:`Common Debugging environment - OpenOCD<k3_rst_refer_openocd>`: for
 277 detailed setup and debugging information.
 278
 279 .. warning::
 280
 281   **OpenOCD support since**: v0.12.0
 282
 283   If the default package version of OpenOCD in your development
 284   environment's distribution needs to be updated, it might be necessary to
 285   build OpenOCD from the source.
 286
 287 .. include::  k3.rst
 288     :start-after: .. k3_rst_include_start_openocd_connect_tag_connect
 289     :end-before: .. k3_rst_include_end_openocd_connect_tag_connect
 290
 291 .. include::  k3.rst
 292     :start-after: .. k3_rst_include_start_openocd_cfg_external_intro
 293     :end-before: .. k3_rst_include_end_openocd_cfg_external_intro
 294
 295 For example, with BeaglePlay (AM62X platform), the openocd_connect.cfg:
 296
 297 .. code-block:: tcl
 298
 299   # TUMPA example:
 300   # http://www.tiaowiki.com/w/TIAO_USB_Multi_Protocol_Adapter_User's_Manual
 301   source [find interface/ftdi/tumpa.cfg]
 302
 303   transport select jtag
 304
 305   # default JTAG configuration has only SRST and no TRST
 306   reset_config srst_only srst_push_pull
 307
 308   # delay after SRST goes inactive
 309   adapter srst delay 20
 310
 311   if { ![info exists SOC] } {
 312     # Set the SoC of interest
 313     set SOC am625
 314   }
 315
 316   source [find target/ti_k3.cfg]
 317
 318   ftdi tdo_sample_edge falling
 319
 320   # Speeds for FT2232H are in multiples of 2, and 32MHz is tops
 321   # max speed we seem to achieve is ~20MHz.. so we pick 16MHz
 322   adapter speed 16000