[[PageOutline]]

= Venice Boot Firmware
The 'Boot Firmware' for Venice is defined as the combination of the firmware stages through up to and including the bootloader. This can be broken down into the following stages:
 * Boot ROM (internal on i.MX8 SoC): fetch first level boot firmware from boot device (ie MMC or SPI FLASH) into L2 cache
 * SPL (Secondary Program Loader) - (U-Boot)
 * ATF (ARM Trusted Firmware)
 * Bootloader (U-Boot)

Gateworks provides [http://dev.gateworks.com/venice/boot_firmware/ pre-built Boot Firmware] ready to flash onto boot devices as well as source for building and/or modifying the boot firmware yourself.

[=#bootrom]
== i.MX8 BOOT ROM
The BOOT ROM is firmware baked into the SoC and is in charge of loading code from the 'boot device' into an L2 cache scratchpad, verifying signatures (if using trusted boot) and executing it.

The BOOT ROM fetches code from an offset of 33KiB on the boot device which leaves the first 33KiB available for other firmware needs.

[=#firmware-image]
== Boot Firmware Image
The firmware image contains all of the components of the 'Boot Firmware':
- ARM Trusted Firmware (ATF)
- SPL
- U-Boot
- U-Boot environment

This firmware is typically put on the eMMC boot0 hardware partition to keep it separate from the eMMC user partition used for the OS.

Venice Boot Firmware Image Map:
 * imx8mm:
||= start-end             =||= len   =||= item =||= notes =||
|| 0x00000000 - 0x00008400 || 33KiB   || unused ||
|| 0x00008400 - 0x00060000 || 351KiB  || SPL (spl.bin) || Loads and u-boot.itb and transfers control to the ATF ||
|| 0x00060000 - 0x003F0000 || 3648KiB || U-Boot (u-boot.itb) || FIT image containing u-boot, ATF, and fdt ||
|| 0x003F0000 - 0x00400000 || 64KB    || U-Boot env || redundant 32KB env ||
 * imx8mn/imx8mp:
||= start-end             =||= len   =||= item =||= notes =||
|| 0x00000000 - 0x00058000 || 352KiB  || SPL (spl.bin) || Loads and u-boot.itb and transfers control to the ATF ||
|| 0x00058000 - 0x003F0000 || 3680KiB || U-Boot(u-boot.itb) || FIT image containing u-boot, ATF, and fdt ||
|| 0x003F0000 - 0x00400000 || 64KB    || U-Boot env || redundant 32KB env ||

Note that while the size of the SPL and offset/size of U-Boot can vary based on bootloader configuration the start offset of the SPL is dictated by the SOC-specific BOOTROM and varies based on the boot device and hardware partition:
 * imx8mm:
  - eMMC user partition: 33KiB
  - eMMC boot partition: 33KiB
 * imx8mn/imx8mp:
  - eMMC user partition: 32KiB
  - eMMC boot partition: 0KiB

== Legacy Boot Firmware Image
The original Gateworks IMX8MM Boot Firmware (now considered legacy) was installed to the eMMC user hardware partition.

Legacy Venice IMX8MM Boot Firmware Image Map:
||= start-end             =||= len  =||= item =||= notes =||
|| 0x00000000 - 0x00008400 || 33KiB  || MBR Partition Table || only first 512B used ||
|| 0x00008400 - 0x00060000 || 351KiB || SPL (spl.bin) || Loads and u-boot.itb and transfers control to the ATF ||
|| 0x00060000 - 0x00FF0000 || 15MiB  || U-Boot (u-boot.itb) || FIT image containing u-boot, ATF, and fdt ||
|| 0x00FF0000 - 0x01000000 || 64KB   || U-Boot env || redundant 32KB env ||
|| 0x01000000 -            ||        || Disk Partitions || used by the OS ||


[=#u-boot]
== U-Boot Bootloader
Read more on the dedicated bootloader page here: [wiki:venice/bootloader Venice U-Boot Bootloader]