This wiki provides details on building, customizing FSBL for Zynq UltraScale+ MPSoC, and important notes on FSBL. All the information is presented in the format of FAQs.

What's new in 2017.3 release ?

  • Secondary boot mode support added
    • Supported secondary boot modes: QSPI24, QSPI32, SD0, SD1, eMMC, SD1-LS, USB, NAND.
  • QSPI 1-bit and 2-bit support added

What is FSBL

First Stage Bootloader (FSBL) for Zynq UltraScale+ MPSoC configures the FPGA with hardware bitstream (if it exists) and loads the Operating System (OS) Image or Standalone (SA) Image or 2nd Stage Boot Loader image from the non-volatile memory (NAND/SD/eMMC/QSPI) to Memory (DDR/TCM/OCM) and takes A53/R5 out of reset. It supports multiple partitions, and each partition can be a code image or a bitstream. Each of these partitions, if required, will be authenticated and/or decrypted.
FSBL is loaded into OCM and handed off by CSU BootROM after authenticating and/or decrypting (as required) FSBL.

How to create FSBL from SDK

  • Launch SDK with the below command: xsdk
  • Provide path where SDK workspace and project need to be created. With this SDK workspace will be created
  • (Optional step) To work with local repos, Select "Xilinx Tools" (ALT - x) -> Repositories. Against Local Repositories, click on "New..." and provide path of the local repo
  • Select File-->New-->Application Project to open "New Project" window, provide name for FSBL project
  • In the "Target Hardware" section, select a pre-defined hardware platform for ZynqMP (e.g. ZCU102_hw_platform).
    • Alternatively, to create a new/custom platform from a .hdf file, click on "New", to create a new hardware platform. Then in the next (New Hardware Project) window, enter the "Project name" and under the "Target Hardware Specification", click on browse and select the HDF file and a new hardware platform is created.
  • In the "New Project" window, select the processor psu_cortexa53_0/psu_cortexr5_0
  • If the Processor selected is psu_cortexa53, select “Compiler” to be either 64-bit (default) or 32-bit from drop down menu
  • Click Next and select "Zynq MP FSBL"
  • Click "Finish" to generate the A53/R5 FSBL. This populates the FSBL code and also builds it (along with BSP)
  • Debug prints in FSBL are now disabled by default (except for FSBL banner). To enable debug prints, define symbol: FSBL_DEBUG_INFO
    • In SDK this can be done by: right click on FSBL application project -> select “C/C++ Build Settings” -> “Tool Settings” tab -> Symbols (under ARM A53 gcc compiler)
    • Click on Add (+) icon and Enter Value: FSBL_DEBUG_INFO, click on "OK" to close the "Properties" screen
  • In case any of the source files (FSBL or BSP) need to be modified, browse the file, make the change and save the file, build the project. elf file will be present in the Debug/Release folder of FSBL project.

What are various levels of debug prints in FSBL

FSBL supports four levels of debug prints:
Type or prints
Enabled by defining.. in FSBL code
Alternative way of enabling by defining symbol..
Used for prints, which should be always enabled (e.g. FSBL banner)
To print errors and basic general information
To have more prints with format specifiers, in addition to basic general information
To have more detailed prints, in addition to above prints

On what all processor cores can FSBL run on

FSBL can only be run from A53_0 (AArch32 and AArch64), R5_0, R5_Lockstep

What part of OCM is used by FSBL

OCM region used by FSBL: 0xFFFC0000 – 0xFFFE9FFF. The last 512 bytes of this region is used by FSBL to share the handoff parameters corresponding to applications ATF hands off.
ATF starts at 0xFFFEA000. Please note that the current implementation of APU only restart assumes that FSBL "resides" in OCM even after its execution is complete. This is since, in such scenarios, PMUFW hands off to (already existing) FSBL without actually restarting.

How is xfsbl_translation_table.S different from translation_table.S of BSP

xfsbl_translation_table.S is a copy of file translation_table.S (of A53). The difference is that the FSBL’s copy of this file marks DDR region as reserved. This is to avoid speculative access to DDR before it is initialized. Once the DDR initialization is done in FSBL, memory attributes for DDR region is changed to “Memory” so that it is cacheable.

What ECC initialization is done by FSBL

TCM ECC Initialization: When FSBL runs on R5, TCM ECC is always initialized. Also, when FSBL loads application targeted on R5, the corresponding TCM's ECC is initialized. When FSBL runs on A53, by default, TCM ECC is not initialized as this also involves powering up of RPU. In such cases, TCM ECC Initialization can be performed by defining FSBL_A53_TCM_ECC_EXCLUDE_VAL to 0 in xfsbl_config.h.
DDR ECC Initialization: Done in FSBL if ECC for DDR is enabled in design.

I’m unable to build FSBL due to size issues, how can I reduce its footprint

FSBL provides option to enable/disable certain features from building. By selectively disabling certain features as mentioned in below table, code size can be reduced. These flags are defined in xfsbl_config.h of FSBL.
default value
Meaning of default setting / Notes
Significant impact on FSBL size?
NAND Boot mode related code is included (if NAND is present in design)
QSPI Boot mode related code is included (if QSPI is present in design)
SD Boot mode related code is included (if SD is present in design)
Secure features (Authenctication and decryption) are enabled
PL Bitstream load capability is enabled
SHA2 is not supported
This flag/feature is not fully supported and hence is not recommended to change this setting
Watchdod timer feature is included
Performance prints are not shown by default
TCM ECC is not initialized for A53 ALWAYS. Changing this flag will result in TCM ECC being initialized always.
PL Initialization/clearing will be done ONLY when the boot image has PL bitstream. Changing this will result in PL Initialization/clearing to be done ALWAYS during FSBL Initialization
USB Slave boot mode support is disabled
FSBL shall bypass XPPU and FPD XMPU configuration BY DEFAULT and isolation/protection feature is just limited to OCM slave. Changing this flag will result in complete XMPU/XPPU configuration, but the corresponding support in sofware is not complete, hence this shouldn't be selected.
NOTE: If the Isolation Configuration check box is not selected in PCW, this flag has no significance.

Are there any other ways by which FSBL foot print can be further reduced

Debug prints: By default only FSBL banner is printed. If more debug prints are enabled, these will result in use of more memory.
Drivers Asserts: Asserts are used within all Xilinx drivers and can be turned off on a system-wide basis by defining, at compile time, the NDEBUG identifier (adding –DNDEBUG against extra_compiler_flags of drivers). This will help further reduce FSBL footprint.

I’m unable to debug FSBL in SDK. Any change in optimizations used by FSBL

For 2017.1, FSBL will be built with –Os and LTO optimizations by default in SDK.
If the user need to disable the optimization (for debugging), two things need to be done:
Since removing optimization results in increase of code size and can result in not being able to build FSBL, some of the features that the user don’t use, need to be disabled in xfsbl_config.h file of FSBL
To disable/modify Optimizations, below changes need to be done:
FSBL app: In the “Miscellaneous” section, need to remove/modify highlighted options below:


IMPORTANT NOTE: It has to be noted that the compiler “Optimization” screen in SDK cannot sense the optimization selected through “Miscellaneous” flags screen (above). This means “Optimization” screen still shows “-O0”, which can be misleading to the users (as shown below).


BSP Settings: The below highlighted extra_compiler_options need to be removed/changed:


BSP settings: highlighted zynqmp_fsbl_bsp flag need to be changed to false (to avoid turning on of optimization again of BSP for FSBL during rebuilding caused by above change.


What are the memory regions/registers reserved for FSBL

DDR region - 0x100000U (XFSBL_DDR_TEMP_ADDRESS) - This is the address in DDR where bitstream will be copied temporarily
DDR region - 0x4000000U (XFSBL_DDR_TEMP_BUFFER_ADDRESS) - This is the address in DDR where boot image will be copied in USB boot mode
0XFFD80040 (PMU_GLOBAL_GLOBAL_GEN_STORAGE4) -> Written by PMUFW, FSBL uses this register to know if reset is APU only reset
0XFFD80048 (PMU_GLOBAL_GLOBAL_GEN_STORAGE6) -> FSBL writes to this register the address from where ATF can read the details of partitions to which ATF has to handoff
0XFFD80060 (PMU_GLOBAL_PERS_GLOB_GEN_STORAGE4) – For error reporting in FSBL
0XFFD80064 (PMU_GLOBAL_PERS_GLOB_GEN_STORAGE5)– FSBL uses this register to indicate to PMUFW that FSBL has completed with system initialization. This is needed in the JTAG boot mode.

Is there any order in which I have to specify bitstream in BIF file (for boot image creation)

Yes, from 2017.1 release. Bitstream should be loaded before ATF is loaded. The reason is FSBL uses the OCM region which is reserved for ATF for holding a temporary buffer in the case where bitstream is present in .BIN file. Because of this, if bitstream is loaded after ATF, FSBL will overwrite the ATF image with its temporary buffer, corrupting ATF image. Hence, bitstream should be positioned in .BIF before ATF and preferably immediately after FSBL and PMUFW.

I could see that USB boot mode support is added in FSBL but is disabled by default. Why

USB boot mode support increases the footprint of FSBL further (by ~10KB). Since it is intended mostly during initial development phase, its support is disabled by default to conserve OCM space. Please refer “I’m unable to build FSBL due to size issues, how can I reduce its footprint” section for details on how to reduce memory foot print of FSBL.

What board specific configuration is done in FSBL

FSBL should be generic and ideally should be free from any board specific configuration. However, for the ease of development, certain board specific initialization is done in XFsbl_BoardInit() in which below are done:
Feature applicability board wise
GT configuration for ZCU102 board
Reset to GEM
Enabling FMC ADJ
PCIe reset (GPIO_DATA_1 register)

What is early handoff and does FSBL support this

FSBL loads the partitions one after other and once loading of all partitions is complete, handing off to CPUs of corresponding partitions is done by FSBL. Early handoff is a scenario where a partition is handed off immediately after its loading into memory. This feature can be useful when an (e.g. RPU) application needs to be started as early as possible after its loading.
This feature (for R5 partitions) was supported by FSBL in earlier releases. The corresponding code in FSBL is still present but this feature is no more being supported in FSBL. This is since, Isolation will be enabled in FSBL while handing off (first/early). This can create problem when loading of further partitions (accessing of memory, CSU).

What are various handoffs supported (between AArch32, AArch64, different cores)

Below table shows various combinations of handoffs supported in FSBL:
Processor cores
Execution address
All (i.e. A53-0, A53-1, A53-2, A53-3)
Any address
A53-1, A53-2, A53-3
Any address
A53-1, A53-2, A53-3
A53-1, A53-2, A53-3
Any address

What are the various hooks provided in FSBL code

Hooks are functions which can be defined by users. FSBL provides blank functions, and calls them from certain strategic locations. Below are the hooks available currently:
Hook purpose/location
Hook function name
Before PL bitstream loading
After PL bitstream loading
Before (the first) Handoff (to any application)
Before fallback
To add more initialization code, in addition to that in psu_init or to replace psu_init with custom initialization

How boot time measurements can be done in FSBL

Boot time (or performance) measurement is a way to measure time taken to complete certain time consuming activities (e.g. partition copy, authentication, decryption etc). In addition, overall time taken by FSBL (measured from after psu_init completion to completion of all partitions/bitstream loading) is also provided. This feature can be enabled by defining macro FSBL_PERF_EXCLUDE_VAL (in xfsbl_config.h) to 1U. Debug prints should not be enabled when p

What is Secondary Boot mode

A secondary boot device can be specified in the bif file as [boot_device] qspi24. This implies that FSBL would be loaded from the primary boot device but all other partitions will be loaded from the secondary boot device qspi24. Secondary boot requires and two bif files and hence two boot images. The first bif contains the partitions loaded by BootRom and also the “[boot_device] qspi24“statement specifying the secondary boot mode. The second bif file contains the FSBL partition followed by all the partitions to be loaded by FSBL.
"bootgen -bif_help boot_device" will list all the secondary boot options.

What are the peripherals/IPs required for FSBL

CSUDMA, ADMA_0 and any one instance of IPI are required IPs for FSBL. In addition, for ZCU102 and ZCU106 boards, I2C0 is needed for board-specific configuration done in FSBL. Hence these IPs are required in design and also should be not isolated from the processor for which FSBL is being created.

Related Links

1) XFSBL_PL_PWRUP_WAIT_MICROSEC macro added to provide wait time for PL to power up. The default value is zero but customers can set it as per their requirements.

csudma, amda_0 and any one instance of ipi are required IPs for FSBL.

# In addition, for ZCU102 and ZCU106, i2c0 is needed for board-specific

# configuration done in FSBL. Hence, print the required (for FSBL) IPs

# which are in design but are isolated from the selected processor.