doc: board: ti: Move documentation from README to .rst
Make the conversion for all existing TI documentation from README to
.rst
Signed-off-by: Neha Malcom Francis <n-francis@ti.com>
diff --git a/doc/board/ti/am335x_evm.rst b/doc/board/ti/am335x_evm.rst
index 3332d51..2ba651e 100644
--- a/doc/board/ti/am335x_evm.rst
+++ b/doc/board/ti/am335x_evm.rst
@@ -43,6 +43,180 @@
`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:
+
+ http://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
+ :prompts: $
+
+ ${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
+ :prompts: $
+
+ 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
+ :prompts: $
+
+ ${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
+ :prompts: $
+
+ 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
----
@@ -52,41 +226,53 @@
have been configured correctly for the board. All images are first loaded
into memory, then written to NAND.
-Step-1: Building u-boot for NAND boot
- Set following CONFIGxx options for NAND device.
- 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)
+1. Building u-boot for NAND boot
-Step-2: Flashing NAND via MMC/SD
+.. list-table:: CONFIGxx options for NAND device
+ :widths: 25 25
+ :header-rows: 1
-.. code-block:: text
+ * - 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)
- # select BOOTSEL to MMC/SD boot and boot from MMC/SD card
- U-Boot # mmc rescan
- # erase flash
- U-Boot # nand erase.chip
- U-Boot # env default -f -a
- U-Boot # saveenv
- # flash MLO. Redundant copies of MLO are kept for failsafe
- U-Boot # load mmc 0 0x82000000 MLO
- U-Boot # nand write 0x82000000 0x00000 0x20000
- U-Boot # nand write 0x82000000 0x20000 0x20000
- U-Boot # nand write 0x82000000 0x40000 0x20000
- U-Boot # nand write 0x82000000 0x60000 0x20000
- # flash u-boot.img
- U-Boot # load mmc 0 0x82000000 u-boot.img
- U-Boot # nand write 0x82000000 0x80000 0x60000
- # flash kernel image
- U-Boot # load mmc 0 0x82000000 uImage
- U-Boot # nand write 0x82000000 ${nandsrcaddr} ${nandimgsize}
- # flash filesystem image
- U-Boot # load mmc 0 0x82000000 filesystem.img
- U-Boot # nand write 0x82000000 ${loadaddress} 0x300000
+2. Flashing NAND via MMC/SD
-Step-3: Set BOOTSEL pin to select NAND boot, and POR the device.
+.. prompt:: bash
+ :prompts: =>
+
+ # 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.
@@ -107,16 +293,34 @@
The recommended layout in this case is:
-.. code-block:: text
+.. list-table:: eMMC Recommended Layout
+ :widths: 25 25 50
+ :header-rows: 1
- MMC BLOCKS |--------------------------------| 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
+ * - 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
@@ -130,27 +334,28 @@
write garbage into the area, you must delete it from the partition table
first.
-.. code-block:: text
+.. prompt:: bash
+ :prompts: =>
- # Ensure we are able to talk with this mmc device
- U-Boot # mmc rescan
- U-Boot # tftp 81000000 am335x/MLO
- # Write to two of the backup locations ROM uses
- U-Boot # mmc write 81000000 100 100
- U-Boot # mmc write 81000000 200 100
- # Write U-Boot to the location set in the config
- U-Boot # tftp 81000000 am335x/u-boot.img
- U-Boot # mmc write 81000000 300 400
- # Load kernel and device tree into memory, perform export
- U-Boot # tftp 81000000 am335x/uImage
- U-Boot # run findfdt
- U-Boot # tftp ${fdtaddr} am335x/${fdtfile}
- U-Boot # run mmcargs
- U-Boot # spl export fdt 81000000 - ${fdtaddr}
- # Write the updated device tree to MMC
- U-Boot # mmc write ${fdtaddr} 80 80
- # Write the uImage to MMC
- U-Boot # mmc write 81000000 900 2000
+ # 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
-------------------------
@@ -161,28 +366,30 @@
afterwards) along with a Falcon Mode aware MLO and the FAT partition has
already been created and marked bootable:
-.. code-block:: text
+.. prompt:: bash
+ :prompts: =>
- U-Boot # mmc rescan
- # Load kernel and device tree into memory, perform export
- U-Boot # load mmc 0:1 ${loadaddr} uImage
- U-Boot # run findfdt
- U-Boot # load mmc 0:1 ${fdtaddr} ${fdtfile}
- U-Boot # run mmcargs
- U-Boot # spl export fdt ${loadaddr} - ${fdtaddr}
+ 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:: text
+.. code-block:: bash
- Using Device Tree in place at 80f80000, end 80f85928
- Using Device Tree in place at 80f80000, end 80f88928
+ Using Device Tree in place at 80f80000, end 80f85928
+ Using Device Tree in place at 80f80000, end 80f88928
So then you:
-.. code-block:: text
+.. prompt:: bash
+ :prompts: =>
- U-Boot # fatwrite mmc 0:1 0x80f80000 args 8928
+ fatwrite mmc 0:1 0x80f80000 args 8928
Falcon Mode: NAND
-----------------
@@ -193,14 +400,15 @@
along with a Falcon Mode aware MLO written to the correct locations for
booting and mtdparts have been configured correctly for the board:
-.. code-block:: text
+.. prompt:: bash
+ :prompts: =>
- U-Boot # nand read ${loadaddr} kernel
- U-Boot # load nand rootfs ${fdtaddr} /boot/am335x-evm.dtb
- U-Boot # run nandargs
- U-Boot # spl export fdt ${loadaddr} - ${fdtaddr}
- U-Boot # nand erase.part u-boot-spl-os
- U-Boot # nand write ${fdtaddr} u-boot-spl-os
+ 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
----------
@@ -217,27 +425,35 @@
device, so the user can easily configure their platform differently from
the command line:
+.. prompt:: bash
+ :prompts: =>
+
+ dm tree
+
.. code-block:: text
- => dm tree
- 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
+ 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
+ :prompts: =>
+
+ fastboot usb 0
+
.. code-block:: text
- => fastboot usb 0
- All UDC in use (1 available), use the unbind command
- g_dnl_register: failed!, error: -19
- exit not allowed from main input shell.
+ 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
@@ -246,20 +462,25 @@
use the unbind command specifying the class and index parameters (as
shown above in the 'dm tree' output) to target the driver to unbind:
-.. code-block:: text
+.. prompt:: bash
+ :prompts: =>
- => unbind ethernet 1
+ 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
+ :prompts: =>
+
+ dm tree
+
.. code-block:: text
- => dm tree
- 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
+ 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