| .. SPDX-License-Identifier: GPL-2.0+ OR BSD-3-Clause |
| .. sectionauthor:: Tom Rini <trini@konsulko.com> |
| |
| AM335x Generation |
| ================= |
| |
| Summary |
| ------- |
| |
| This document covers various features of the `am335x_evm` default |
| configuration, some of the related defconfigs, and how to enable hardware |
| features not present by default in the defconfigs. |
| |
| Hardware |
| -------- |
| |
| The binary produced by this board supports, based on parsing of the EEPROM |
| documented in TI's reference designs: |
| * AM335x GP EVM |
| * AM335x EVM SK |
| * The Beaglebone family of designs |
| |
| Customization |
| ------------- |
| |
| Given that all of the above boards are reference platforms (and the |
| Beaglebone platforms are OSHA), it is likely that this platform code and |
| configuration will be used as the basis of a custom platform. It is |
| worth noting that aside from things such as NAND or MMC only being |
| required if a custom platform makes use of these blocks, the following |
| are required, depending on design: |
| |
| * GPIO is only required if DDR3 power is controlled in a way similar to EVM SK |
| * SPI is only required for SPI flash, or exposing the SPI bus. |
| |
| The following blocks are required: |
| |
| * I2C, to talk with the PMIC and ensure that we do not run afoul of |
| errata 1.0.24. |
| |
| When removing options as part of customization, note that you will likely need |
| to look at both `include/configs/am335x_evm.h`, |
| `include/configs/ti_am335x_common.h` and `include/configs/am335x_evm.h` as the |
| migration to Kconfig is not yet complete. |
| |
| Secure Boot |
| ----------- |
| |
| .. secure_boot_include_start_config_ti_secure_device |
| |
| Secure TI devices require a boot image that is authenticated by ROM |
| code to function. Without this, even JTAG remains locked and the |
| device is essentially useless. In order to create a valid boot image for |
| a secure device from TI, the initial public software image must be signed |
| and combined with various headers, certificates, and other binary images. |
| |
| Information on the details on the complete boot image format can be obtained |
| from Texas Instruments. The tools used to generate boot images for secure |
| devices are part of a secure development package (SECDEV) that can be |
| downloaded from: |
| |
| https://www.ti.com/mysecuresoftware (login required) |
| |
| The secure development package is access controlled due to NDA and export |
| control restrictions. Access must be requested and granted by TI before the |
| package is viewable and downloadable. Contact TI, either online or by way |
| of a local TI representative, to request access. |
| |
| .. secure_boot_include_end_config_ti_secure_device |
| |
| .. secure_boot_include_start_spl_boot |
| |
| 1. Booting of U-Boot SPL |
| ^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| When CONFIG_TI_SECURE_DEVICE is set, the U-Boot SPL build process |
| requires the presence and use of these tools in order to create a |
| viable boot image. The build process will look for the environment |
| variable TI_SECURE_DEV_PKG, which should be the path of the installed |
| SECDEV package. If the TI_SECURE_DEV_PKG variable is not defined or |
| if it is defined but doesn't point to a valid SECDEV package, a |
| warning is issued during the build to indicate that a final secure |
| bootable image was not created. |
| |
| Within the SECDEV package exists an image creation script: |
| |
| .. prompt:: bash $ |
| |
| ${TI_SECURE_DEV_PKG}/scripts/create-boot-image.sh |
| |
| This is called as part of the SPL/u-boot build process. As the secure |
| boot image formats and requirements differ between secure SOC from TI, |
| the purpose of this script is to abstract these details as much as |
| possible. |
| |
| The script is basically the only required interface to the TI SECDEV |
| package for creating a bootable SPL image for secure TI devices. |
| |
| .. prompt:: bash $ |
| |
| create-boot-image.sh \ |
| <IMAGE_FLAG> <INPUT_FILE> <OUTPUT_FILE> <SPL_LOAD_ADDR> |
| |
| .. secure_boot_include_end_spl_boot |
| |
| <IMAGE_FLAG> is a value that specifies the type of the image to |
| generate OR the action the image generation tool will take. Valid |
| values are: |
| |
| .. list-table:: |
| :widths: 25 25 |
| :header-rows: 0 |
| |
| * - PI_X-LOADER |
| - Generates an image for SPI flash (byte swapped) |
| * - X-LOADER |
| - Generates an image for non-XIP flash |
| * - MLO |
| - Generates an image for SD/MMC/eMMC media |
| * - 2ND |
| - Generates an image for USB, UART and Ethernet |
| * - XIP_X-LOADER |
| - Generates a single stage u-boot for NOR/QSPI XiP |
| |
| <INPUT_FILE> is the full path and filename of the public world boot |
| loaderbinary file (depending on the boot media, this is usually |
| either u-boot-spl.bin or u-boot.bin). |
| |
| <OUTPUT_FILE> is the full path and filename of the final secure |
| image. The output binary images should be used in place of the standard |
| non-secure binary images (see the platform-specific user's guides and |
| releases notes for how the non-secure images are typically used) |
| |
| .. list-table:: |
| :widths: 25 25 |
| :header-rows: 0 |
| |
| * - u-boot-spl_HS_SPI_X-LOADER |
| - byte swapped boot image for SPI flash |
| * - u-boot-spl_HS_X-LOADER |
| - boot image for NAND or SD/MMC/eMMC rawmode |
| * - u-boot-spl_HS_MLO |
| - boot image for SD/MMC/eMMC media |
| * - u-boot-spl_HS_2ND |
| - boot image for USB, UART and Ethernet |
| * - u-boot_HS_XIP_X-LOADER |
| - boot image for NOR or QSPI Xip flash |
| |
| <SPL_LOAD_ADDR> is the address at which SOC ROM should load the |
| <INPUT_FILE> |
| |
| .. secure_boot_include_start_primary_u_boot |
| |
| 2. Booting of Primary U-Boot (u-boot.img) |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| The SPL image is responsible for loading the next stage boot loader, |
| which is the main u-boot image. For secure TI devices, the SPL will |
| be authenticated, as described above, as part of the particular |
| device's ROM boot process. In order to continue the secure boot |
| process, the authenticated SPL must authenticate the main u-boot |
| image that it loads. |
| |
| The configurations for secure TI platforms are written to make the boot |
| process use the FIT image format for the u-boot.img (CONFIG_SPL_FRAMEWORK |
| and CONFIG_SPL_LOAD_FIT). With these configurations the binary |
| components that the SPL loads include a specific DTB image and u-boot |
| image. These DTB image may be one of many available to the boot |
| process. In order to secure these components so that they can be |
| authenticated by the SPL as they are loaded from the FIT image, the |
| build procedure for secure TI devices will secure these images before |
| they are integrated into the FIT image. When those images are extracted |
| from the FIT image at boot time, they are post-processed to verify that |
| they are still secure. The outlined security-related SPL post-processing |
| is enabled through the CONFIG_SPL_FIT_IMAGE_POST_PROCESS option which |
| must be enabled for the secure boot scheme to work. In order to allow |
| verifying proper operation of the secure boot chain in case of successful |
| authentication messages like "Authentication passed" are output by the |
| SPL to the console for each blob that got extracted from the FIT image. |
| |
| The exact details of the how the images are secured is handled by the |
| SECDEV package. Within the SECDEV package exists a script to process |
| an input binary image: |
| |
| .. prompt:: bash $ |
| |
| ${TI_SECURE_DEV_PKG}/scripts/secure-binary-image.sh |
| |
| This is called as part of the u-boot build process. As the secure |
| image formats and requirements can differ between the various secure |
| SOCs from TI, this script in the SECDEV package abstracts these |
| details. This script is essentially the only required interface to the |
| TI SECDEV package for creating a u-boot.img image for secure TI |
| devices. |
| |
| The SPL/u-boot code contains calls to dedicated secure ROM functions |
| to perform the validation on the secured images. The details of the |
| interface to those functions is shown in the code. The summary |
| is that they are accessed by invoking an ARM secure monitor call to |
| the device's secure ROM (fixed read-only-memory that is secure and |
| only accessible when the ARM core is operating in the secure mode). |
| |
| Invoking the secure-binary-image script for Secure Devices |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| .. prompt:: bash $ |
| |
| secure-binary-image.sh <INPUT_FILE> <OUTPUT_FILE> |
| |
| <INPUT_FILE> is the full path and filename of the input binary image |
| |
| <OUTPUT_FILE> is the full path and filename of the output secure image. |
| |
| .. secure_boot_include_end_primary_u_boot |
| |
| NAND |
| ---- |
| |
| The AM335x GP EVM ships with a 256MiB NAND available in most profiles. In |
| this example to program the NAND we assume that an SD card has been |
| inserted with the files to write in the first SD slot and that mtdparts |
| have been configured correctly for the board. All images are first loaded |
| into memory, then written to NAND. |
| |
| 1. Building u-boot for NAND boot |
| |
| .. list-table:: CONFIGxx options for NAND device |
| :widths: 25 25 |
| :header-rows: 1 |
| |
| * - Config |
| - Description |
| * - CONFIG_SYS_NAND_PAGE_SIZE |
| - number of main bytes in NAND page |
| * - CONFIG_SYS_NAND_OOBSIZE |
| - number of OOB bytes in NAND page |
| * - CONFIG_SYS_NAND_BLOCK_SIZE |
| - number of bytes in NAND erase-block |
| * - CFG_SYS_NAND_ECCPOS |
| - ECC map for NAND page |
| * - CONFIG_NAND_OMAP_ECCSCHEME |
| - (refer doc/README.nand) |
| |
| 2. Flashing NAND via MMC/SD |
| |
| .. prompt:: bash => |
| |
| # select BOOTSEL to MMC/SD boot and boot from MMC/SD card |
| mmc rescan |
| # erase flash |
| nand erase.chip |
| env default -f -a |
| saveenv |
| # flash MLO. Redundant copies of MLO are kept for failsafe |
| load mmc 0 0x82000000 MLO |
| nand write 0x82000000 0x00000 0x20000 |
| nand write 0x82000000 0x20000 0x20000 |
| nand write 0x82000000 0x40000 0x20000 |
| nand write 0x82000000 0x60000 0x20000 |
| # flash u-boot.img |
| load mmc 0 0x82000000 u-boot.img |
| nand write 0x82000000 0x80000 0x60000 |
| # flash kernel image |
| load mmc 0 0x82000000 uImage |
| nand write 0x82000000 ${nandsrcaddr} ${nandimgsize} |
| # flash filesystem image |
| load mmc 0 0x82000000 filesystem.img |
| nand write 0x82000000 ${loadaddress} 0x300000 |
| |
| 3. Set BOOTSEL pin to select NAND boot, and POR the device. |
| The device should boot from images flashed on NAND device. |
| |
| |
| Falcon Mode |
| ----------- |
| |
| The default build includes "Falcon Mode" (see doc/README.falcon) via NAND, |
| eMMC (or raw SD cards) and FAT SD cards. Our default behavior currently is |
| to read a 'c' on the console while in SPL at any point prior to loading the |
| OS payload (so as soon as possible) to opt to booting full U-Boot. Also |
| note that while one can program Falcon Mode "in place" great care needs to |
| be taken by the user to not 'brick' their setup. As these are all eval |
| boards with multiple boot methods, recovery should not be an issue in this |
| worst-case however. |
| |
| Falcon Mode: eMMC |
| ----------------- |
| |
| The recommended layout in this case is: |
| |
| .. list-table:: eMMC Recommended Layout |
| :widths: 25 25 50 |
| :header-rows: 1 |
| |
| * - MMC Blocks |
| - Description |
| - Location in bytes |
| * - 0x0000 - 0x007F |
| - MBR or GPT table |
| - 0x000000 - 0x020000 |
| * - 0x0080 - 0x00FF |
| - ARGS or FDT file |
| - 0x010000 - 0x020000 |
| * - 0x0100 - 0x01FF |
| - SPL.backup1 (first copy used) |
| - 0x020000 - 0x040000 |
| * - 0x0200 - 0x02FF |
| - SPL.backup2 (second copy used) |
| - 0x040000 - 0x060000 |
| * - 0x0300 - 0x06FF |
| - U-Boot |
| - 0x060000 - 0x0e0000 |
| * - 0x0700 - 0x08FF |
| - U-Boot Env + Redundant |
| - 0x0e0000 - 0x120000 |
| * - 0x0900 - 0x28FF |
| - Kernel |
| - 0x120000 - 0x520000 |
| |
| Note that when we run 'spl export' it will prepare to boot the kernel. |
| This includes relocation of the uImage from where we loaded it to the entry |
| point defined in the header. As these locations overlap by default, it |
| would leave us with an image that if written to MMC will not boot, so |
| instead of using the loadaddr variable we use 0x81000000 in the following |
| example. In this example we are loading from the network, for simplicity, |
| and assume a valid partition table already exists and 'mmc dev' has already |
| been run to select the correct device. Also note that if you previously |
| had a FAT partition (such as on a Beaglebone Black) it is not enough to |
| write garbage into the area, you must delete it from the partition table |
| first. |
| |
| .. prompt:: bash => |
| |
| # Ensure we are able to talk with this mmc device |
| mmc rescan |
| tftp 81000000 am335x/MLO |
| # Write to two of the backup locations ROM uses |
| mmc write 81000000 100 100 |
| mmc write 81000000 200 100 |
| # Write U-Boot to the location set in the config |
| tftp 81000000 am335x/u-boot.img |
| mmc write 81000000 300 400 |
| # Load kernel and device tree into memory, perform export |
| tftp 81000000 am335x/uImage |
| run findfdt |
| tftp ${fdtaddr} am335x/${fdtfile} |
| run mmcargs |
| spl export fdt 81000000 - ${fdtaddr} |
| # Write the updated device tree to MMC |
| mmc write ${fdtaddr} 80 80 |
| # Write the uImage to MMC |
| mmc write 81000000 900 2000 |
| |
| Falcon Mode: FAT SD cards |
| ------------------------- |
| |
| In this case the additional file is written to the filesystem. In this |
| example we assume that the uImage and device tree to be used are already on |
| the FAT filesystem (only the uImage MUST be for this to function |
| afterwards) along with a Falcon Mode aware MLO and the FAT partition has |
| already been created and marked bootable: |
| |
| .. prompt:: bash => |
| |
| mmc rescan |
| # Load kernel and device tree into memory, perform export |
| load mmc 0:1 ${loadaddr} uImage |
| run findfdt |
| load mmc 0:1 ${fdtaddr} ${fdtfile} |
| run mmcargs |
| spl export fdt ${loadaddr} - ${fdtaddr} |
| |
| This will print a number of lines and then end with something like: |
| |
| .. code-block:: bash |
| |
| Using Device Tree in place at 80f80000, end 80f85928 |
| Using Device Tree in place at 80f80000, end 80f88928 |
| |
| So then you: |
| |
| .. prompt:: bash => |
| |
| fatwrite mmc 0:1 0x80f80000 args 8928 |
| |
| Falcon Mode: NAND |
| ----------------- |
| |
| In this case the additional data is written to another partition of the |
| NAND. In this example we assume that the uImage and device tree to be are |
| already located on the NAND somewhere (such as filesystem or mtd partition) |
| along with a Falcon Mode aware MLO written to the correct locations for |
| booting and mtdparts have been configured correctly for the board: |
| |
| .. prompt:: bash => |
| |
| nand read ${loadaddr} kernel |
| load nand rootfs ${fdtaddr} /boot/am335x-evm.dtb |
| run nandargs |
| spl export fdt ${loadaddr} - ${fdtaddr} |
| nand erase.part u-boot-spl-os |
| nand write ${fdtaddr} u-boot-spl-os |
| |
| USB device |
| ---------- |
| |
| The platform code for am33xx based designs is legacy in the sense that |
| it is not fully compliant with the driver model in its management of the |
| various resources. This is particularly true for the USB Ethernet gadget |
| which will automatically be bound to the first USB Device Controller |
| (UDC). This make the USB Ethernet gadget work out of the box on common |
| boards like the Beagle Bone Blacks and by default will prevents other |
| gadgets to be used. |
| |
| The output of the 'dm tree' command shows which driver is bound to which |
| device, so the user can easily configure their platform differently from |
| the command line: |
| |
| .. prompt:: bash => |
| |
| dm tree |
| |
| .. code-block:: text |
| |
| Class Index Probed Driver Name |
| ----------------------------------------------------------- |
| [...] |
| misc 0 [ + ] ti-musb-wrapper | |-- usb@47400000 |
| usb 0 [ + ] ti-musb-peripheral | | |-- usb@47401000 |
| ethernet 1 [ + ] usb_ether | | | `-- usb_ether |
| bootdev 3 [ ] eth_bootdev | | | `-- usb_ether.bootdev |
| usb 0 [ ] ti-musb-host | | `-- usb@47401800 |
| |
| Typically here any network command performed using the usb_ether |
| interface would work, while using other gadgets would fail: |
| |
| .. prompt:: bash => |
| |
| fastboot usb 0 |
| |
| .. code-block:: text |
| |
| All UDC in use (1 available), use the unbind command |
| g_dnl_register: failed!, error: -19 |
| exit not allowed from main input shell. |
| |
| As hinted by the primary error message, the only controller available |
| (usb@47401000) is currently bound to the usb_ether driver, which makes |
| it impossible for the fastboot command to bind with this device (at |
| least from a bootloader point of view). The solution here would be to |
| use the unbind command specifying the class and index parameters (as |
| shown above in the 'dm tree' output) to target the driver to unbind: |
| |
| .. prompt:: bash => |
| |
| unbind ethernet 1 |
| |
| The output of the 'dm tree' command now shows the availability of the |
| first USB device controller, the fastboot gadget will now be able to |
| bind with it: |
| |
| .. prompt:: bash => |
| |
| dm tree |
| |
| .. code-block:: text |
| |
| Class Index Probed Driver Name |
| ----------------------------------------------------------- |
| [...] |
| misc 0 [ + ] ti-musb-wrapper | |-- usb@47400000 |
| usb 0 [ ] ti-musb-peripheral | | |-- usb@47401000 |
| usb 0 [ ] ti-musb-host | | `-- usb@47401800 |