doc/board/intel/slimbootloader.rst

   1 .. SPDX-License-Identifier: GPL-2.0+
   2 .. sectionauthor:: Aiden Park <aiden.park@intel.com>
   3
   4 Slim Bootloader
   5 ===============
   6
   7 Introduction
   8 ------------
   9
  10 This target is to enable U-Boot_ as a payload of `Slim Bootloader`_ (a.k.a SBL)
  11 boot firmware which currently supports QEMU, Apollolake, Whiskeylake,
  12 Coffeelake-R platforms.
  13
  14 The `Slim Bootloader`_ is designed with multi-stages (Stage1A/B, Stage2, Payload)
  15 architecture to cover from reset vector to OS booting and it consumes
  16 `Intel FSP`_ for silicon initialization.
  17
  18 * Stage1A: Reset vector, CAR init with FSP-T
  19 * Stage1B: Memory init with FSP-M, CAR teardown, Continue execution in memory
  20 * Stage2 : Rest of Silicon init with FSP-S, Create HOB, Hand-off to Payload
  21 * Payload: Payload init with HOB, Load OS from media, Booting OS
  22
  23 The Slim Bootloader stages (Stage1A/B, Stage2) focus on chipset, hardware and
  24 platform specific initialization, and it provides useful information to a
  25 payload in a HOB (Hand-Off Block) which has serial port, memory map, performance
  26 data info and so on. This is Slim Bootloader architectural design to make a
  27 payload light-weight, platform independent and more generic across different
  28 boot solutions or payloads, and to minimize hardware re-initialization in a
  29 payload.
  30
  31 Build Instruction for U-Boot as a Slim Bootloader payload
  32 ---------------------------------------------------------
  33
  34 Build U-Boot and obtain u-boot-dtb.bin::
  35
  36    $ make distclean
  37    $ make slimbootloader_defconfig
  38    $ make all
  39
  40 Prepare Slim Bootloader
  41 -----------------------
  42
  43 1. Setup Build Environment for Slim Bootloader.
  44
  45    Refer to `Getting Started`_ page in `Slim Bootloader`_ document site.
  46
  47 2. Get source code. Let's simply clone the repo::
  48
  49    $ git clone https://github.com/slimbootloader/slimbootloader.git
  50
  51 3. Copy u-boot-dtb.bin to Slim Bootloader.
  52    Slim Bootloader looks for a payload from the specific location.
  53    Copy the build u-boot-dtb.bin to the expected location::
  54
  55    $ mkdir -p <Slim Bootloader Dir>/PayloadPkg/PayloadBins/
  56    $ cp <U-Boot Dir>/u-boot-dtb.bin <Slim Bootloader Dir>/PayloadPkg/PayloadBins/u-boot-dtb.bin
  57
  58 Build Instruction for Slim Bootloader for QEMU target
  59 -----------------------------------------------------
  60
  61 Slim Bootloader supports multiple payloads, and a board of Slim Bootloader
  62 detects its target payload by PayloadId in board configuration.
  63 The PayloadId can be any 4 Bytes value.
  64
  65 1. Update PayloadId. Let's use 'U-BT' as an example::
  66
  67     $ vi Platform/QemuBoardPkg/CfgData/CfgDataExt_Brd1.dlt
  68     -GEN_CFG_DATA.PayloadId                     | 'AUTO'
  69     +GEN_CFG_DATA.PayloadId                     | 'U-BT'
  70
  71 2. Update payload text base. PAYLOAD_EXE_BASE must be the same as U-Boot
  72    CONFIG_SYS_TEXT_BASE in board/intel/slimbootloader/Kconfig.
  73    PAYLOAD_LOAD_HIGH must be 0::
  74
  75     $ vi Platform/QemuBoardPkg/BoardConfig.py
  76     +               self.PAYLOAD_LOAD_HIGH    = 0
  77     +               self.PAYLOAD_EXE_BASE     = 0x00100000
  78
  79 3. Build QEMU target. Make sure u-boot-dtb.bin and U-BT PayloadId
  80    in build command. The output is Outputs/qemu/SlimBootloader.bin::
  81
  82    $ python BuildLoader.py build qemu -p "OsLoader.efi:LLDR:Lz4;u-boot-dtb.bin:U-BT:Lzma"
  83
  84 4. Launch Slim Bootloader on QEMU.
  85    You should reach at U-Boot serial console::
  86
  87    $ qemu-system-x86_64 -machine q35 -nographic -serial mon:stdio -pflash Outputs/qemu/SlimBootloader.bin
  88
  89 Test Linux booting on QEMU target
  90 ---------------------------------
  91
  92 Let's use LeafHill (APL) Yocto image for testing.
  93 Download it from http://downloads.yoctoproject.org/releases/yocto/yocto-2.0/machines/leafhill/.
  94
  95 1. Prepare Yocto hard disk image::
  96
  97    $ wget http://downloads.yoctoproject.org/releases/yocto/yocto-2.0/machines/leafhill/leafhill-4.0-jethro-2.0.tar.bz2
  98    $ tar -xvf leafhill-4.0-jethro-2.0.tar.bz2
  99    $ ls -l leafhill-4.0-jethro-2.0/binary/core-image-sato-intel-corei7-64.hddimg
 100
 101 2. Launch Slim Bootloader on QEMU with disk image::
 102
 103    $ qemu-system-x86_64 -machine q35 -nographic -serial mon:stdio -pflash Outputs/qemu/SlimBootloader.bin -drive id=mydrive,if=none,file=/path/to/core-image-sato-intel-corei7-64.hddimg,format=raw -device ide-hd,drive=mydrive
 104
 105 3. Update boot environment values on shell::
 106
 107    => setenv bootfile vmlinuz
 108    => setenv bootdev scsi
 109    => boot
 110
 111 Build Instruction for Slim Bootloader for LeafHill (APL) target
 112 ---------------------------------------------------------------
 113
 114 Prepare U-Boot and Slim Bootloader as described at the beginning of this page.
 115 Also, the PayloadId needs to be set for APL board.
 116
 117 1. Update PayloadId. Let's use 'U-BT' as an example::
 118
 119     $ vi Platform/ApollolakeBoardPkg/CfgData/CfgData_Int_LeafHill.dlt
 120     -GEN_CFG_DATA.PayloadId                     | 'AUTO
 121     +GEN_CFG_DATA.PayloadId                     | 'U-BT'
 122
 123 2. Update payload text base.
 124
 125 * PAYLOAD_EXE_BASE must be the same as U-Boot CONFIG_SYS_TEXT_BASE
 126   in board/intel/slimbootloader/Kconfig.
 127 * PAYLOAD_LOAD_HIGH must be 0::
 128
 129     $ vi Platform/ApollolakeBoardPkg/BoardConfig.py
 130     +               self.PAYLOAD_LOAD_HIGH    = 0
 131     +               self.PAYLOAD_EXE_BASE     = 0x00100000
 132
 133 3. Build APL target. Make sure u-boot-dtb.bin and U-BT PayloadId
 134    in build command. The output is Outputs/apl/Stitch_Components.zip::
 135
 136    $ python BuildLoader.py build apl -p "OsLoader.efi:LLDR:Lz4;u-boot-dtb.bin:U-BT:Lzma"
 137
 138 4. Stitch IFWI.
 139
 140    Refer to Apollolake_ page in Slim Bootloader document site::
 141
 142    $ python Platform/ApollolakeBoardPkg/Script/StitchLoader.py -i <Existing IFWI> -s Outputs/apl/Stitch_Components.zip -o <Output IFWI>
 143
 144 5. Flash IFWI.
 145
 146    Use DediProg to flash IFWI. You should reach at U-Boot serial console.
 147
 148
 149 Build Instruction to use ELF U-Boot
 150 -----------------------------------
 151
 152 1. Enable CONFIG_OF_EMBED::
 153
 154     $ vi configs/slimbootloader_defconfig
 155     +CONFIG_OF_EMBED=y
 156
 157 2. Build U-Boot::
 158
 159    $ make distclean
 160    $ make slimbootloader_defconfig
 161    $ make all
 162    $ strip u-boot (removing symbol for reduced size)
 163
 164 3. Do same steps as above
 165
 166 * Copy u-boot (ELF) to PayloadBins directory
 167 * Update PayloadId 'U-BT' as above.
 168 * No need to set PAYLOAD_LOAD_HIGH and PAYLOAD_EXE_BASE.
 169 * Build Slim Bootloader. Use u-boot instead of u-boot-dtb.bin::
 170
 171    $ python BuildLoader.py build <qemu or apl> -p "OsLoader.efi:LLDR:Lz4;u-boot:U-BT:Lzma"
 172
 173 .. _U-Boot: https://gitlab.denx.de/
 174 .. _`Slim Bootloader`: https://github.com/slimbootloader/
 175 .. _`Intel FSP`: https://github.com/IntelFsp/
 176 .. _`Getting Started`: https://slimbootloader.github.io/getting-started/
 177 .. _Apollolake: https://slimbootloader.github.io/supported-hardware/apollo-lake-crb.html#stitching