README.md

   1 System Firmware (SYSFW) and Configuration Image Generator TI K3 Family SoCs
   2 ===========================================================================
   3
   4 Overview
   5 --------
   6 This tool is intended to be a simple solution to allow users to create an image
   7 tree blob (a.k.a. FIT image) comprising a signed System Firmware image as well
   8 as the binary configuration artifacts needed to bring up SYSFW as part of the
   9 U-Boot SPL startup. Note that the final SYSFW configuration itself is expected
  10 to be performed by the end user by directly modifying different C source files
  11 included into this project as needed for an application and board-specific use
  12 case. The domain-specific configuration artifacts to be tailored are:
  13
  14 * *board-cfg.c* contains the general board configuration
  15 * *pm-cfg.c* contains the power management / clock related configuration
  16 * *rm-cfg.c* contains the resource management / allocation related configuration
  17 * *sec-cfg.c* contains the security configuration
  18
  19 These files exist under {srcroot}/soc/{soc}/{configuration}/ folders, Where:
  20 * srcroot - Is the root folder of source code
  21 * soc - Is one of the supported SoCs. Example: am65x
  22 * configuration - This is one of the supported configurations for various
  23   resource division desired. Example: evm
  24
  25 NOTE: The definitions for the same are available under
  26 {srcroot}/include/soc/{soc} folder
  27
  28 The build process consumes a raw (unsigned) SYSFW binary image as released by
  29 the SYSFW development team and signs it by adding an X.509 certificate using a
  30 random key.
  31
  32 The signed SYSFW image as well as the configuration artifacts will then all get
  33 build into an ITB blob (FIT image) named **sysfw-{soc}-{configuration}.itb**
  34 ready for consumption by U-Boot SPL.
  35
  36
  37 Building SYSFW Image and Configuration Data
  38 -------------------------------------------
  39 First, ensure you have a current mkimage tool and ARMv7 cross toolchain
  40 installed. The SYSFW configuration generator was developed and tested using...
  41
  42     $ mkimage -V
  43     mkimage version 2013.10
  44
  45     $ arm-linux-gnueabihf-gcc --version
  46     arm-linux-gnueabihf-gcc (Linaro GCC 7.2-2017.11) 7.2.1 20171011
  47     Copyright (C) 2017 Free Software Foundation, Inc.
  48     This is free software; see the source for copying conditions.  There is NO
  49     warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  50
  51 Also make sure to have a proper unsigned SYSFW image populated at the root of
  52 this project, otherwise a version specified in the Makefile via Git commit hash
  53 will be downloaded from the TI SYSFW release URL (see download location below).
  54
  55 The default SYSFW image consumed by the build process is called
  56 **ti-sci-firmware-{soc}-gp.bin** however this may be overwritten and customized
  57 using the **SYSFW_PATH** make variable. The build process will fail if the
  58 image can't be downloaded to {srcroot} or no such file has gotten populated into
  59 that folder by other means.
  60
  61 Further note by default the SYSFW image for use with general purpose (GP) devices
  62 (as opposed to high security devices) is signed with the TI degenerate key to
  63 optimize boot time (less processing time needed by ROM) but can also be signed
  64 with a random cryptoraphic key or another user-provided key. This signing behavior
  65 is controlled through the **KEY** make variable. Not explicitly setting **KEY**
  66 will result in the use of the TI degenerate key. To use a custom key populate the
  67 **KEY** variable to point to the key to get used. By clearing the default key
  68 setting by passing in **KEY=""** a random key will get generated and used during
  69 the build process.
  70
  71 In order to download the SYSFW release image (if needed) and build the final
  72 **sysfw-{soc}-{configuration}.itb** for consumption by U-Boot SPL simply by
  73 perform a make.
  74
  75     $ make
  76
  77 Note that in case of filesystem-based boot such as booting from SD card
  78 **sysfw-{soc}-{configuration}.itb** needs to be manually renamed to
  79 **syswfw.itb** before populating it to the (SD card) boot media as this is the
  80 file name U-Boot SPL will be trying to load early during the boot process. This
  81 renaming step is not necessary for RAW boot modes such as eMMC (in RAW mode),
  82 (x)SPI, and others.
  83
  84     $ mv sysfw-{soc}-{configuration}.itb syswfw.itb
  85
  86 To extract and show the release version of the SYSFW image being used...
  87
  88     $ make sysfw_version
  89     SYSFW Version: v2018.08a (Curious Crow)
  90
  91 To extract the 'creator' information from the final generated
  92 **sysfw-{soc}-{configuration}.itb** image tree blob...
  93
  94     $ fdtget sysfw-am65x-evm.itb / creator
  95     SIG am65x/evm-ti2019.01-14-g47b8d
  96
  97 The workspace can be cleaned up by doing...
  98
  99     $ make clean
 100
 101 To also remove the SYSFW image do this...
 102
 103     $ make mrproper
 104
 105 The following flags further modify the build steps:
 106 * SOC - Choose one of the supported SoCs (see folder name under {srcroot}/soc).
 107   Defaults to am65x
 108 * CONFIG - Choose of various configurations supported (see folder name under
 109   {srcroot}/soc/{soc}). Defaults to evm
 110 * O - Choose where the intermediate build files need to be located
 111 * BIN_DIR - Choose where the final output sysfw-{soc}-{configuration}.itb needs
 112   to be generated to.
 113 * KEY - Choose key to use for the signing system firmware image
 114
 115
 116 Building SYSFW Image for High-Security(HS) devices
 117 --------------------------------------------------
 118 The process for building and image suitable for use with HS devices is similar
 119 to the above process with the following differences:
 120
 121 The make commands should be appended with HS=1,
 122
 123     $ make HS=1
 124
 125 The environment variable **TI_SECURE_DEV_PKG** should be defined to point to
 126 the TI Secure Development Tools package.
 127
 128 There are two images downloaded and consumed by the build process.
 129
 130     * ti-sci-firmware-{soc}-hs-enc.bin: Encrypted HS SYSFW image
 131     * ti-sci-firmware-{soc}-hs-cert.bin: Inner-certificate for HS SYSFW image
 132
 133 The inner-certificate is signed by the key provided by the **TI_SECURE_DEV_PKG**
 134 path producing an outer-certificate. These images are then appended to produce
 135 the final **sysfw-{soc}-{configuration}.bin** which is bundled with the
 136 configuration data exactly as the non-HS version above.
 137
 138
 139 Important Notes
 140 ---------------
 141 There is a strong dependency of the used System Firmware release version and
 142 how the board configuration data needs to be structured and/or filled in. Using
 143 config data that is not compatible with a given SYSFW release may lead to
 144 failures during loading of the data by U-Boot SPL, or failures later downstream
 145 in U-Boot or during Linux boot.
 146
 147 It is strongly recommended to review System Firmware release documentation in
 148 great detail(!) to make sure suitable board configuration is provided. Common
 149 pitfalls preventing proper system operation include but are not limited to using
 150 an unsuitable or invalid resource management configuration.
 151
 152
 153 References
 154 ----------
 155 * [Latest SYSFW Release Documentation](http://software-dl.ti.com/tisci/esd/latest/)
 156 * [Official SYSFW Release Download Location](https://git.ti.com/processor-firmware/ti-linux-firmware/trees/ti-linux-firmware/ti-sysfw)