This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision Next revision Both sides next revision | ||
doc:lighthouse:bootloader [2019-02-06 16:59] arnaud |
doc:lighthouse:bootloader [2019-03-07 11:20] arnaud |
||
---|---|---|---|
Line 1: | Line 1: | ||
====== Lighthouse deck bootloader ====== | ====== Lighthouse deck bootloader ====== | ||
- | <WRAP center round important 100%> | + | The [[projects: |
- | **Warning**: This documentation | + | |
+ | The bootloader protocol is inspired by the [[https:// | ||
+ | |||
+ | ===== Interface protocols ===== | ||
+ | |||
+ | ==== Uart protocol ==== | ||
+ | |||
+ | There is two UARTs on the deck, UART0 on the Crazyflie deck interface and UART1 on 2.54mm soldering pads available for external communication. The bootloader is available on both UARTs. The UARTs are setup with 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 bootloader 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 UARTs 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 " | ||
+ | |||
+ | Since 0xBC is not an implemented command, the suggested sequence in order to start the communication is sending "Break condition" | ||
+ | |||
+ | <WRAP center round info> | ||
+ | **Note**: There is a priority between the different interfaces. The priority | ||
</ | </ | ||
- | The lighthouse deck is based on an [[https:// | ||
- | The bootloader protocol is inspired | + | ==== I2C protocol ==== |
+ | |||
+ | The I2C 7 bit address is 0x2F. Sending command and receiving to answer from the bootloader | ||
+ | |||
+ | 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 | ||
+ | |||
+ | 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 ^ | ||
+ | | | ||
+ | |||
+ | ==== SPI Exchange ==== | ||
+ | |||
+ | The SPI exchange command execute 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) | ||
+ | |||
+ | Received from the bootloader: | ||
+ | |||
+ | ^ Byte # ^ Value ^ Note ^ | ||
+ | | 0-(RLEN-1) | ||
+ | |||
+ | ==== Get version ==== | ||
+ | |||
+ | Returns the bootloader version. Can be useful to identify that the firmware currently running | ||
+ | currently only version 1 exists | ||
+ | |||
+ | Sent to the bootloader: | ||
+ | |||
+ | ^ Byte # ^ Value ^ Note ^ | ||
+ | | 0 | 0x02 | Get version command | | ||
+ | |||
+ | Received from the bootloader: | ||
+ | |||
+ | ^ Byte # ^ Value ^ Note ^ | ||
+ | | 0 | 0x01 | Bootloader version | | ||
+ | |||
+ | |||
+ | ===== Flash layout ===== | ||
+ | |||
+ | The flash is layered as follow: | ||
+ | |||
+ | < | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | Free | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | Firmware | ||
+ | | ||
+ | | ||
+ | | ||
+ | | Bootloader | ||
+ | | ||
+ | | MBR | ||
+ | | ||
+ | </ | ||
+ | |||
+ | The write protection is implemented | ||
+ | |||
+ | ===== Firmware versioning ===== | ||
+ | |||
+ | The firmware is an iCE40 bitstream ((The bitstream format has been [[http://www.clifford.at/icestorm/format.html|documented by the icestorm project]] )). The bitstream start with the bytes 0xff 0x00 followed by a null terminated string | ||
+ | |||
+ | The version string format is a base 10 integer number in ascii indicating the version. For example " | ||
+ | |||
+ | In the context of the lighthouse firmware, versions >= 1 are released version and should be in parity (or handled) by the client connecting the board in order to boot the firmware. Versions <= 0 are development version and the intention is that the client will then boot it without further check. | ||
+ | |||
+ | This format is simple enough for current needs and allows to add other fields later by separating it from the version with any non-decimal character. |