tweakoz / litex-chainloader

Litex-FPGA Linux Chainloader

Summary

This is a chainloader for easing Litex FPGA TFTP bootloading workflow when you frequently run into any of the following:

• Your software image files change size.
• Your software image files change destination address.
• You add or remove software image files.
• Other conditions that require you to regenerate your FPGA bitstream due to software being embedded within it.

This has only been tested with the VexRiscV / Arty / Linux port, but conceptually at least it should cross over to the other cpu's and OS's.

To Build:

• Set these environment variables:

  • SOC_BUILD_DIR : output dir of your soc's build products (where the gateware and software output directories are)
  • SOC_TFTP_SERVER_IP : 10,0,0,1 (or whatever you wish... - note the commas)
  • SOC_TFTP_CLIENT_IP : 10,0,0,2 (or whatever you wish... - note the commas)
  • SOC_TFTP_SERVER_PORT : 69 (or whatever you wish)

• Set CHAINLOADER_BIN in chainloader.ld to match your system (there is a TODO below to make this dynamic)

• run make

To Use:

• Generate a boot.manifest text file which should look something like the below. The boot.manifest is the list of files the netbooter will pull from the TFTP server. It also includes each file's destination address and and length. Generate this as a part of your build process. Make sure to regenerate it whenever rebuilding buildroot, emulator.bin, your SOC or your devicetree.

download emulator.bin 0x20000000 8776
download rv32.dtb 0xc0ff0000 1885
download Image 0xc0000000 4676580
download rootfs.cpio 0xc1000000 15118848
boot 0x20000000
end

• Place the boot.manifest and any referenced files in your TFTP server directory. your folder should look something like the below.

  ls -l tftp_root/arty
    total 19360
    -rw-rw-r-- 1 someuser someuser      168 Jun 26 21:27 boot.manifest
    -rw-rw-r-- 1 someuser someuser     8776 Jun 26 21:27 emulator.bin
    -rw-r--r-- 1 someuser someuser  4676580 Jun 26 21:27 Image
    -rw-r--r-- 1 someuser someuser 15118848 Jun 26 21:27 rootfs.cpio
    -rw-rw-r-- 1 someuser someuser     1885 Jun 26 21:27 rv32.dtb

• Run a TFTP server (one is included). If using the included TFTP server, place files in a subdirectory named after a 'class' eg - arty. The included TFTP server will route different folders different hosts based on the internal ip->class dictionary. Presumably this behaviour could be used to target specific devices with different software images.

• Boot up the FPGA bitstream.

• litex_term --speed <baudrate> <tty> --kernel $SOC_BUILD_DIR/software/chainloader/chainloader.bin --kernel-adr CHAINLOADER_BIN-address

• This should result in the standard Litex bios booting up, followed by loading the chainloader (via serial), and then followed by a TFTP boot (via the chainloader) of whatever OS and/or data you have put into the manifest.

TODO:

• chainloader.ld ( CHAINLOADER_BIN ) : the CHAINLOADER_BIN address should be autogenerated to point somewhere in the last section of your soc's SDRAM region - as included it is set up for an arty (the end of it's 256MiB SDRAM space). I noticed hangs when trying to overlay the chainloader @ the standard SDRAM address (0xc00000000), hence why I decided to move it 'out of the way'. I'm guessing it had interfered with the bios's stack.

• Improve cross platform story

• Some of the code was copied out of the Litex bios. Perhaps we can integrate it back in.

• IP addresses are fixed in the bitstream. Short of DHCP which sounds complicated - not sure how to fix this, ATM..

• We probably could/should get the flash booter using the manifest.

• Add hashes to the manifest ?