User Tools

Site Tools


doc:lighthouse:bootloader

Lighthouse deck bootloader

Warning: This documentation is currently a work-in-progress working document. None of this is final.

The lighthouse deck is based on an iCE40UP5K FPGA. The FPGA boots from an SPI flash to the bootloader, it is then able to boot to another configuration image. The bootloader gives access to the SPI memory and to a boot command to boot the user image. This allows the deck to be updated easily from the Crazyflie or from the auxiliary serial port.

The bootloader protocol is inspired by the TinyFpga USB bootloader but implemented on serial port and I2C bus. It gives a raw access to the SPI bus, this means that memory operation should be done using SPI commands following the SPI memory documentation.

Interface protocols

Uart protocol

There is two UARTs on the deck, UART0 on te Crazyflie deck interface and UART1 on 2.54mm soldering pads available for external communication. The bootloader is available on both UART. The UARTs are setup at a baudrate of 115200.

When using the UART, commands are sent on the RX line and answer will be sent back by the bootloader on the TX line. Since the bootloader and the Flash SPI bus are working much faster than the UART, there is no need for flow control.

To make sure the boorloader is waiting for a command, a break condition can be sent to the UART to reset the bootloader state. This is good to do before sending the first command in order to make sure the bootloader is not currently in the middle of a command.

Both UART are disabled at startup, this means that the bootloader will ignore all data and break condition coming from them. To enable an UART send the byte “0xBC”. This will enable the UART and reset the bootloader state.

Since 0xBC is not an implemented command. The suggested sequence in order to start the communication is sending “Break condition” and then “0xBC”. This will ensure the UART is enabled and the bootloader is ready to receive the next command.

Note: There is a priority between the different interfaces. The priority is UART0, UART1, I2C. This means that I2C is enabled at startup and that if UART0 is enabled, UART1 is ignored.

I2C protocol

The I2C 7 bit address is 0x2F. Sending command and receiving to answer from the bootloader is done with I2C read and write transaction.

Starting a write transaction will reset the bootloader state and send all the bytes written to the bootloader. The bootloader will then execute the command and write the answer to a memory buffer. Starting a read transaction will read from this memory buffer.

For example, after sending a command that will produce a 5 bytes answer, one should start a read transaction and read the 5 answer bytes.

The buffer is of 15KiB. If a command is executed that returns more than 15KiB bytes, the first bytes of the buffer will be overwritten.

Bootloader protocol

All numbers are expressed in little endian.

Boot

The boot command will boot the firmware. It takes no arguments. The command instructs the bootloader to boot the firmware image, the FPGA will resets and boot on the firmware image from the flash.

Sent to the bootloader:

Byte # Value Note
0 0x00 Boot command

SPI Exchange

The SPI exchange command execure one SPI transaction. On the SPI bus it asserts the CS pin, sends WLEN bytes and then receives RLEN bytes.

Sent to the bootloader:

Byte # Value Note
0 0x01 SPI Exchange command
1-2 WLEN Write length
3-4 RLEN Read length
5-(WLEN-4) Write data Data to write to the SPI device

Received from the bootloader:

Byte # Value Note
0-(RLEN-1) Read data Data read from the SPI device

Flash layout

The flash is layered as follow:

 +-------------+ 
 |             |
 |             |
 |             |
 |             |
 | Free        |
 +-------------+  0x040000
 |             |
 |             |
 | Firmware    |
 +-------------+  0x020000
 |             |            \
 |             |            |
 | Bootloader  |            | Write protected
 +-------------+  0x0000a0  |
 | MBR         |            |
 +-------------+  0x000000  /

The write protection is implemented by setting the SR1 register in the SPI flash memory. This means that it can be disabled by clearing the SR1 register if updating the bootloader is required.

Firmware versioning

The firmware is an iCE40 bitstream 1). The bitstream start with the bytes 0xff 0x00 followed by a null terminated string and the 0x00 0xff. This null terminated string is a comment. In the Lighthouse deck this comment is used to store the version of the firmware as a version string. The intention is that the deck user (ie. the Crazyflie or other external board) must be able to find-out if the firmware is compatible or if it needs to be upgraded or downgraded.

The version string format is TBD.

1)
The bitstream format has been documented by the icestorm project
doc/lighthouse/bootloader.txt · Last modified: 2019-02-20 14:53 by arnaud