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 LeafHill is using PCI UART2 device as a serial port.
 115 For MEM32 serial port, CONFIG_SYS_NS16550_MEM32 needs to be enabled in U-Boot.
 116
 117 1. Enable CONFIG_SYS_NS16550_MEM32 in U-Boot::
 118
 119     $ vi include/configs/slimbootloader.h
 120     +#define CONFIG_SYS_NS16550_MEM32
 121      #ifdef CONFIG_SYS_NS16550_MEM3
 122
 123 2. Build U-Boot::
 124
 125    $ make disclean
 126    $ make slimbootloader_defconfig
 127    $ make all
 128
 129 3. Copy u-boot-dtb.bin to Slim Bootloader.
 130    Slim Bootloader looks for a payload from the specific location.
 131    Copy the build u-boot-dtb.bin to the expected location::
 132
 133    $ mkdir -p <Slim Bootloader Dir>/PayloadPkg/PayloadBins/
 134    $ cp <U-Boot Dir>/u-boot-dtb.bin <Slim Bootloader Dir>/PayloadPkg/PayloadBins/u-boot-dtb.bin
 135
 136 4. Update PayloadId. Let's use 'U-BT' as an example::
 137
 138     $ vi Platform/ApollolakeBoardPkg/CfgData/CfgData_Int_LeafHill.dlt
 139     -GEN_CFG_DATA.PayloadId                     | 'AUTO
 140     +GEN_CFG_DATA.PayloadId                     | 'U-BT'
 141
 142 5. Update payload text base.
 143
 144 * PAYLOAD_EXE_BASE must be the same as U-Boot CONFIG_SYS_TEXT_BASE
 145   in board/intel/slimbootloader/Kconfig.
 146 * PAYLOAD_LOAD_HIGH must be 0::
 147
 148     $ vi Platform/ApollolakeBoardPkg/BoardConfig.py
 149     +               self.PAYLOAD_LOAD_HIGH    = 0
 150     +               self.PAYLOAD_EXE_BASE     = 0x00100000
 151
 152 6. Build APL target. Make sure u-boot-dtb.bin and U-BT PayloadId
 153    in build command. The output is Outputs/apl/Stitch_Components.zip::
 154
 155    $ python BuildLoader.py build apl -p "OsLoader.efi:LLDR:Lz4;u-boot-dtb.bin:U-BT:Lzma"
 156
 157 7. Stitch IFWI.
 158
 159    Refer to Apollolake_ page in Slim Bootloader document site::
 160
 161    $ python Platform/ApollolakeBoardPkg/Script/StitchLoader.py -i <Existing IFWI> -s Outputs/apl/Stitch_Components.zip -o <Output IFWI>
 162
 163 8. Flash IFWI.
 164
 165    Use DediProg to flash IFWI. You should reach at U-Boot serial console.
 166
 167
 168 Build Instruction to use ELF U-Boot
 169 -----------------------------------
 170
 171 1. Enable CONFIG_OF_EMBED::
 172
 173     $ vi configs/slimbootloader_defconfig
 174     +CONFIG_OF_EMBED=y
 175
 176 2. Build U-Boot::
 177
 178    $ make disclean
 179    $ make slimbootloader_defconfig
 180    $ make all
 181    $ strip u-boot (removing symbol for reduced size)
 182
 183 3. Do same steps as above
 184
 185 * Copy u-boot (ELF) to PayloadBins directory
 186 * Update PayloadId 'U-BT' as above.
 187 * No need to set PAYLOAD_LOAD_HIGH and PAYLOAD_EXE_BASE.
 188 * Build Slim Bootloader. Use u-boot instead of u-boot-dtb.bin::
 189
 190    $ python BuildLoader.py build <qemu or apl> -p "OsLoader.efi:LLDR:Lz4;u-boot:U-BT:Lzma"
 191
 192 .. _U-Boot: https://gitlab.denx.de/
 193 .. _`Slim Bootloader`: https://github.com/slimbootloader/
 194 .. _`Intel FSP`: https://github.com/IntelFsp/
 195 .. _`Getting Started`: https://slimbootloader.github.io/getting-started/
 196 .. _Apollolake: https://slimbootloader.github.io/supported-hardware/apollo-lake-crb.html#stitching