README.md

   1 System Firmware (SYSFW) and Configuration Image Generator for AM65x
   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 The build process consumes a raw (unsigned) SYSFW binary image as released by
  20 the SYSFW development team and signs it by adding an X.509 certificate using a
  21 random key.
  22
  23 The signed SYSFW image as well as the configuration artifacts will then all get
  24 build into an ITB blob (FIT image) named **sysfw.itb** ready for consumption by
  25 U-Boot SPL.
  26
  27
  28 Building SYSFW Image and Configuration Data
  29 -------------------------------------------
  30 First, ensure you have a current mkimage tool and ARMv7 cross toolchain
  31 installed. The SYSFW configuration generator was developed and tested using...
  32
  33     $ mkimage -V
  34     mkimage version 2013.10
  35
  36     $ arm-linux-gnueabihf-gcc --version
  37     arm-linux-gnueabihf-gcc (Linaro GCC 7.2-2017.11) 7.2.1 20171011
  38     Copyright (C) 2017 Free Software Foundation, Inc.
  39     This is free software; see the source for copying conditions.  There is NO
  40     warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  41
  42 Also make sure to have a proper unsigned SYSFW image populated at the root of
  43 this project, otherwise a version specified in the Makefile via Git commit hash
  44 will be downloaded from the TI SYSFW release URL (see download location below).
  45
  46 The default SYSFW image consumed by the build process is called
  47 **ti-sci-firmware-am65x-gp.bin** however this may be overwritten and customized
  48 using the **SYSFW_PATH** make variable. The build process will fail if the
  49 image can't be downloaded or no such file is provided.
  50
  51 In order to download the SYSFW release image (if needed) and build the final
  52 **sysfw.itb** for consumption by U-Boot simply perform a make...
  53
  54     $ make
  55
  56 To extract and show the release version of the SYSFW image being used...
  57
  58     $ make sysfw_version
  59     SYSFW Version: v2018.08a (Curious Crow)
  60
  61 The workspace can be cleaned up by doing...
  62
  63     $ make clean
  64
  65 To also remove the SYSFW image do this...
  66
  67     $ make mrproper
  68
  69 Building SYSFW Image for High-Security(HS) devices
  70 --------------------------------------------------
  71 The process for building and image suitable for use with HS devices is similar
  72 to the above process with the following differences:
  73
  74 The make commands should be appended with HS=1,
  75
  76     $ make HS=1
  77
  78 The environment variable **TI_SECURE_DEV_PKG** should be defined to point to
  79 the TI Secure Development Tools package.
  80
  81 There are two images downloaded and consumed by the build process.
  82
  83     * ti-sci-firmware-am65x-hs-enc.bin: Encrypted HS SYSFW image
  84     * ti-sci-firmware-am65x-hs-cert.bin: Inner-certificate for HS SYSFW image
  85
  86 The inner-certificate is signed by the key provided by the **TI_SECURE_DEV_PKG**
  87 path producing an outer-certificate. These images are then appended to produce
  88 the final **sysfw.bin** which is bundled with the configuration data exactly as
  89 the non-HS version above.
  90
  91 Important Notes
  92 ---------------
  93 There is a strong dependency of the used System Firmware release version and
  94 how the board configuration data needs to be structured and/or filled in. Using
  95 config data that is not compatible with a given SYSFW release may lead to
  96 failures during loading of the data by U-Boot SPL, or failures later downstream
  97 in U-Boot or during Linux boot.
  98
  99 It is strongly recommended to review System Firmware release documentation in
 100 great detail(!) to make sure suitable board configuration is provided. Common
 101 pitfalls preventing proper system operation include but are not limited to using
 102 an unsuitable or invalid resource management configuration.
 103
 104
 105 References
 106 ----------
 107 * [Latest SYSFW Release Documentation](http://software-dl.ti.com/tisci/esd/latest/)
 108 * [Official SYSFW Release Download Location](https://git.ti.com/processor-firmware/ti-linux-firmware/trees/ti-linux-firmware-4.1.y/ti-sysfw)