mirror of
https://github.com/AsahiLinux/u-boot
synced 2024-12-04 18:41:03 +00:00
81cf99e723
The sphinx-prompt documentation[0] provides examples on how we can use prompt as a parameter to simplify the description. Use the same. While at it, ensure to make all relevant prompts clarified such as gdb prompts. [0] http://sbrunner.github.io/sphinx-prompt/ Signed-off-by: Nishanth Menon <nm@ti.com> Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt@canonical.com>
473 lines
16 KiB
ReStructuredText
473 lines
16 KiB
ReStructuredText
.. 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
|