1
0
Fork 0
mirror of https://github.com/betaflight/betaflight.git synced 2025-07-13 03:20:00 +03:00
betaflight/docs/EXST bootloader.md
Dominic Clifton 0632eeb934 Support compilation of EXST (EXTERNAL STORAGE) targets
- Initial

- Adjust load address of EXST firmware.

- Add helper script to pad an EXST binary to the expected size.

Padded firmware currently required due to a bug in the flash/dfu code
which causes anything less than a flash page size to be truncated when
uploading new firmware via the bootloader DFU.

- Minor linker script cleanups.

- STM32H7.mk change hardcoded TARGET_FLASH (384) to FIRMWARE_SIZE

- Delete unused configuration section entries from linker
scripts.

- Increase EXST firmware size to 448K.
It turns out 384K wasn't enough for a feature-complete firmware.

- Update pad-exst.sh to use 448K by default.

- Move the EXST file generation to the makefile.

[EXST] Embed firmware hash in ELF

- Add debug marker at end of CODE_RAM section.

It was found when transferring firmware to the H7 RAM via a BMP probe
using the 'gdb load' command, that the last few bytes were not
transferred, this debug marker is present to ensure all needed parts of
the firmware are present.

Example memory view of corrupted bytes at end of transfer:
0x2407DFAE  DEB90000 DEB9DEB9 DEB9DEB9 DEB9DEB9  ..¹Þ¹Þ¹Þ¹Þ¹Þ¹Þ¹Þ
0x2407DFBE  000000B9 00000000 00000000 00000000  ¹...............

should be:
0x2407DFAE  DEB9DEB9 DEB9DEB9 DEB9DEB9 DEB9DEB9  ¹Þ¹Þ¹Þ¹Þ¹Þ¹Þ¹Þ¹Þ
0x2407DFBE  00000000 00000000 00000000 00000000  ................

- Remove debug marker in EXST firmware.

STM32H750_EXST - Provide space for empty hash.

* Bootloader will run firmware if hash is empty, without re-verifying
RAM content against hash.
* CODE_RAM always shows as 100% usage.

STM32H750_EXST - Use a specific ELF section for a hash.

Two benefits:
1) CODE_RAM no-longer shows 100% full, since it is no-longer
padded/filled.
2) Prepares the code so that objcopy can be used to inject the hash
into the ELF.

STM32H750_EXST - Patch MD5 into ELF.

Process is now as follows.

* Binary generated (via make target dependency) so there is something to
hash.
* Binary copied (and padded).
* MD5 Hash computed.
* xxd patch file generated from hash.
* xxd hash patch applied to copy of binary at correct address.
* elf .exst_hash section dumped.
* hash injected into into dumped section.
* elf .exst_hash section updated with updated dumped section.

Replace EXST with USE_EXST.

Add documentation for the EXST firmware format.

Add table formatting to EXST documentation.

Update bootloader block.

Update H750 EXST linker script to use block format 0x00.

Use .exst.elf and .exst.bin on the exst files.

Add 'no checksum' to list of checksum hash methods.

Update EXST build system so it generates the following sets of files

obj/main/betaflight_TARGET.elf
obj/main/betaflight_TARGET.map
obj/main/betaflight_TARGET_EXST.elf
obj/betaflight_VERSION_TARGET.bin
obj/betaflight_VERSION_TARGET.bin.md5
obj/betaflight_VERSION_TARGET_EXST.bin

Update EXST build system to be more user-friendly.

* user-flashable files are generated in the normal place.
* Intermediate files are generated in `obj/main/...`
* Removes the `exst` goal.
* Adds .hex generation for EXST builds based on the patched .elf.

To build EXST targets, simply use `make TARGET=x` as normal and flash
the resulting `.hex/.bin` files rather than the .exst.bin file.

Developers can use either the `.elf` or patched `_EXST.elf` file as is
appropriate for their needs.

EXST documentation updated to match changes to build system.
2019-06-07 09:14:49 +12:00

4.4 KiB

EXST bootloader

The EXST (External Storage) system requires that the targets' CPU has a small program, called a bootloader, that provides functionality to load firmware from an external storage into the CPU's RAM so that the firmware can be executed.

Example external storage systems include:

  • External Flash using Firmware Partition
  • File on an SD card.

EXST targets also have the requirement of providing a mechansim to load and save configuration ('eeprom'). options for this include:

  • CPU Embedded flash page.
  • External Flash using Config Partition
  • File on an SD card.

Since external storage systems can become corrupted, and communication errors can occur, Bootloaders should verify correct loading of the firmware from an external storage system, or after transferring via a debugger. An hash is provided for this purpose.

Bootloaders are not limited to just one storage system.

Bootloaders may offer additional functionality, such as:

  • a means to update the firmware on an external storage medium (e.g. via DFU)
  • update one external storage system from another (i.e. update external flash from file on SD card)
  • backup, select, swap or erase firmware
  • backup, select, swap or erase configuration.

Users should consult the manual that came with their EXST bootloader-equipped flight controller for details on how to use any such features.

The build system provides a way to build files suitable for transferring onto an external storage medium via the standard 'bin'/'hex' make goals.

make TARGET=<targetname>

This results in the usual *.bin and *.hex files and also a *_EXST.elf file which have been patched to contain information required for bootloader operation.

The .bin file is a binary file which should be transferred to the storage medium and is suitable for distribution. The .hex file is a hex file which can be used by tools for uploading to a bootloader and is suitable for distribution.

For developers there is a _EXST.elf file which is a standard .elf file that has had one section replaced, this file is suitable for uploading to targets using a debugger such as GDB.

For details on the memory sections used refer to the linker files.

EXST format

The format for EXST targets is as follows:

  • Firmware.
  • Bootloader block.

The bootloader block is 64 bytes.

For example a 448K EXST .bin file is comprised as follows:

Start Address End address Usage
0x00000 0x6FFBF Firmware section
0x6FFC0 0x6FFFF Bootloader block

EXST bootloader block

The bootloader block is comprised as follows:

Start Address End address Usage
0x00 0x00 Block Format
0x01 0x3F Block Content

Block Formats

Value Meaning
0x00 Block format 0x00

Block Format 0x00 Content

Note: addresses relative to start of bootloader block

Start Address End address Usage
0x01 0x01 Checksum/Hash method
0x02 0x2F Reserved, fill with 0x00
0x30 0x3F Checksum value, pad with trailing 0x00

Checksum Hash methods

Value Meaning
0x00 No checksum.
0x01 MD5.

Checksum locations:

Start Address End address Usage
0x30 0x3F MD5 hash of firmware section

The bootloader should make no attempt to use any reserved area otherwise this prevents it's future use by the firmware.

The bootloader should ensure this block is in RAM when the firmware is loaded. i.e. copy the entire EXST image.

As the reserved area is under control of the build system, not the bootloader, additional information can stored there for use by the firmware or future bootloaders. Extreme care must be taken not to break the bootloaders ability to load firmware. Consultation with the developers for any changes to this area is required.

Example possible future enhancements for the EXST bootloader block

  • Hardware layout identification - to allow the firmware to identify the hardware, such that IO pins and peripherals can be reserved/initialised.
  • Alternative hashes/CRCs.