Bare Metal

Bare Metal Firmware

The lab004 contains a clean firmware that can be used as a basis to create a firmware. Most likely, your SoC definition won't have a display and a led so remove any reference to display_*and leds_* in main.c in order to compile it.

Here is an example to build a SoC and the firmware.

Build a (default) SoC:

$ python -m litex_boards.targets.icebreaker --output-dir build

Build the firmware:

$ cd firmware && make

Linking

TODO

Build with bitstream (replace BIOS)

TODO

Booting from BIOS

There are various ways to load a firmware from the BIOS. Use litex_term /dev/ttyUSBX --kernel firmware/firmware.bin (then enter serialboot in the BIOS terminal) to load the firmware into the main_ram data segment and run it.

The firmware can be stored in a non-volatile memory (e.g. SPI flash) to be loaded at startup. During startup, the BIOS will try various boot options (if available), including booting at [FLASH_BOOT_ADDRESS]. The FLASH_BOOT_ADDRESS can be defined in the SoC:

if hasattr(soc, "spiflash"):
    soc.add_constant("FLASH_BOOT_ADDRESS", soc.mem_map["spiflash"])

When a firmware is booted from a non-volatile storage, the BIOS expect a header and a CRC in front of the firmware image:

	length	crc	data
size	4 bytes	4 bytes	length bytes

Creating an image with this header format can be done using mkmscimg:

$ python3 -m litex.soc.software.mkmscimg firmware.bin -f -o firmware.fbi

In addition to using external flash programmers, firmware can be written to flash using litex_term:

$ litex_term --kernel firmware.fbi --flash

Note that using litex_term --kernel-adr KERNEL_ADR on a SPI flash address may not work as the LiteX SPI flash core only supports memory-mapped reads.