Create New Payload

Note

Before you decide to support a new payload in SBL, it is recommended to check whether the existing payloads can be updated to support the new requirement.

For tightly-coupled payload, two steps are required to integrate a new payload:

1. Create a new payload starts with adding a new module in PayloadPkg/<payload_bar> with entry point function PayloadMain().

   See Package Dependency when you are implementing payload code.

2. Build and integrate the new payload

   The image size and memory location of the new payload can be configured in BoardConfig.py. The following values are used in Apollo Lake platform payload configurations:

   PAYLOAD_SIZE         = 0x0001F000
   EPAYLOAD_SIZE        = 0x00120000
   LOADER_RSVD_MEM_SIZE = 0x00B8C000
   PLD_RSVD_MEM_SIZE    = 0x00500000
   PAYLOAD_LOAD_HIGH    = 1
   

For loosely-coupled payload, you are full control of payload design and implementation.

For example, UEFI Payload is loosely-coupled payload.

HelloWorld Payload

SBL provides a HelloWorld payload example to illustrate how to write a very simple payload.

To build the HelloWorld payload, run the following command from SBL source tree:

python BuildLoader.py build_dsc -p PayloadPkg\PayloadPkg.dsc

The generated payload binary will be located at:

Build\PayloadPkg\DEBUG_VS2019\IA32\HelloWorld.efi

Note

The path might change a little bit if using different toolchain or build options.

To use HelloWorld payload as the default payload instead of the OsLoader on QEMU platform, build SBL with the following command:

copy Build\PayloadPkg\DEBUG_VS2019\IA32\HelloWorld.efi PayloadPkg\PayloadBins /y
python BuildLoader.py build qemu -p HelloWorld.efi:HLWD:Lz4

This generated SlimBootloader.bin will boot into HelloWorld payload on QEMU platform.

To add HelloWorld payload as additional paylaod, build SBL with the following command:

copy Build\PayloadPkg\DEBUG_VS2019\IA32\HelloWorld.efi PayloadPkg\PayloadBins /y
python BuildLoader.py build qemu -p OsLoader.efi:LLDR:Lz4;HelloWorld.efi:HLWD:Lz4

The generated SlimBootloader.bin will boot into OsLoader or HelloWorld payload on QEMU platform depends on the GEN_CFG_DATA.PayloadId value at build time and runtime.

Note

GEN_CFG_DATA.PayloadId can be customized in board CFGDATA DLT file. The PayloadId can be updated by SBL at runtime code by SetPayloadId() function.

Please refer to Integrate Multiple Payloads for multiple payloads support.