Skip to content

Commit 7718f4c

Browse files
danielinuxdanielinux
committed
Added documentation for compile-time options
1 parent 821287f commit 7718f4c

2 files changed

Lines changed: 142 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,7 @@ microcontrollers will be added later. Relocating the interrupt vector can be dis
4646
- Decide a flash partition strategy and modify `include/target.h` accordingly (see [Flash partitions](docs/flash_partitions.md))
4747
- Change the entry point of the firmware image to account for bootloader presence
4848
- Equip the application with the [wolfBoot library](docs/API.md) to interact with the bootloader
49+
- [Configure and compile](docs/compile.md) a bootable image with a single "make" command
4950

5051
### Examples provided
5152

@@ -64,7 +65,9 @@ firmware at the specified address on the flash.
6465

6566
The `ed25519_sign` tool transforms a bootable firmware image to comply with the firmware image format required by the bootloader.
6667

67-
For more detailed information about the firmware image format, see [Firmware image](docs/firmware_image.md)
68+
For detailed information about the firmware image format, see [Firmware image](docs/firmware_image.md)
69+
70+
For detailed information about the configuration options for the target system, see [Compiling wolfBoot](docs/compile.md)
6871

6972
### Upgrading the firmware
7073

‎docs/compile.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
# Compiling wolfBoot
2+
3+
WolfBoot is portable across different types of embedded systems. The platform-specific code
4+
is contained in a single file under the `hal` directory, and implements the hardware-specific functions.
5+
6+
To enable specific compile options, use environment variables while calling make, e.g.
7+
8+
`make CORTEX_M0=1`
9+
10+
## Platform selection
11+
12+
If supported natively, the target platform can be specified using the `TARGET` variable.
13+
Make will automatically select the correct compile option, and include the corresponding HAL for
14+
the selected target.
15+
16+
For a list of the platforms currently supported, see the [HAL documentation](./HAL.md).
17+
18+
To add a new platform, simply create the corresponding HAL driver and linker script file
19+
in the [hal](../hal) directory.
20+
21+
Default option if none specified: `TARGET=stm32f4`
22+
23+
Some platform will require extra options, specific for the architecture.
24+
By default, wolfBoot is compiled for ARM Cortex-M3/4/7. To compile for Cortex-M0, use:
25+
26+
`CORTEX_M0=1`
27+
28+
### Flash partitions
29+
30+
The file [include/target.h](../include/target.h) must be modified according to flash geometry,
31+
partitions size and offset of the target system. The following values must be set to provide the
32+
desired flash configuration:
33+
34+
`WOLFBOOT_SECTOR_SIZE`
35+
36+
This variable determines the size of the physical sector on the flash memory. If areas with different
37+
block sizes are used for the two partitions (e.g. update partition on an external flash), this variable
38+
should indicate the size of the biggest sector shared between the two partitions.
39+
40+
WolfBoot uses this value as minimum unit when swapping the firmware images in place. For this reason,
41+
this value is also used to set the size of the SWAP partition.
42+
43+
`WOLFBOOT_PARTITION_BOOT_ADDRESS`
44+
45+
This is the start address of the boot partition, aligned to the beginning of a new flash sector.
46+
The application code starts after a further offset, equal to the partition header size (256B
47+
for Ed25519 and ECC signature headers).
48+
49+
`WOLFBOOT_PARTITION_UPDATE_ADDRESS`
50+
51+
This is the start address of the update partition. If an external memory is used via the
52+
`EXT_FLASH` option, this variable contains the offset of the update partition from the
53+
beginning of the external memory addressable space.
54+
55+
`WOLFBOOT_PARTITION_SWAP_ADDRESS`
56+
57+
The address for the swap spaced used by wolfBoot to swap the two firmware images in place,
58+
in order to perform a reversable update. The size of the SWAP partition is exactly one sector on the flash.
59+
If an external memory is used, the variable contains the offset of the SWAP area from the beginning
60+
of its addressable space.
61+
62+
`WOLFBOOT_PARTITION_SIZE`
63+
64+
The size of the BOOT and UPDATE partition. The size is the same for both partitions.
65+
66+
## Bootloader features
67+
68+
A number of characteristics can be turned on/off during wolfBoot compilation. Bootloader size,
69+
performance and activated features are affected by compile-time flags.
70+
71+
### Change DSA algorithm
72+
73+
By default, wolfBoot is compiled to use Ed25519 DSA. The implementation of ed25519 is smaller,
74+
while giving a good compromise in terms of boot-up time.
75+
76+
Better performance can be achieved using ECDSA with curve p-256. To activate ECC256 support, use
77+
78+
`SIGN=ECC256`
79+
80+
when invoking `make`.
81+
82+
The default option, if no value is provided for the `SIGN` variable, is
83+
84+
`SIGN=ED25519`
85+
86+
Changing the DSA algorithm will also result in compiling a different set of tools for key generation
87+
and firmware signature.
88+
89+
Find the corresponding key generation and firmware signing tools in the [tools](../tools) directory.
90+
91+
### Enable debug symbols
92+
93+
To debug the bootloader, simply compile with `DEBUG=1`. The size of the bootloade will increase
94+
consistently, so ensure that you have enough space at the beginning of the flash before
95+
`WOLFBOOT_PARTITION_BOOT_ADDRESS`.
96+
97+
### Disable interrupt vector relocation
98+
99+
On some platforms, it might be convenient to avoid the interrupt vector relocation before boot-up.
100+
This is required when a component on the system already manages the interrupt relocation at a different
101+
stage, or on these platform that do not support interrupt vector relocation.
102+
103+
To disable interrupt vector table relocation, compile with `VTOR=0`. By default, wolfBoot will relocate the
104+
interrupt vector by setting the offset in the vector relocation offset register (VTOR).
105+
106+
### Enable workaround for 'write once' flash memories
107+
108+
On some microcontrollers, the internal flash memory does not allow subsequent writes (adding zeroes) to a
109+
sector, after the entire sector has been erased. WolfBoot relies on the mechanism of adding zeroes to the
110+
'flags' fields at the end of both partitions to provide a fail-safe swap mechanism.
111+
112+
To enable the workaround for 'write once' internal flash, compile with
113+
114+
`NVM_FLASH_WRITEONCE=1`
115+
116+
**warning** When this option is enabled, the fail-safe swap is not guaranteed, i.e. the microcontroller
117+
cannot be safely powered down or restarted during a swap operation.
118+
119+
### Allow version roll-back
120+
121+
WolfBoot will not allow updates to a firmware with a version number smaller than the current one. To allow
122+
downgrades, compile with `ALLOW_DOWNGRADE=1`.
123+
124+
Warning: this option will disable version checking before the updates, thus exposing the system to potential
125+
forced downgrade attacks.
126+
127+
### Enable optional support for external flash memory
128+
129+
WolfBoot can be compiled with the makefile option `EXT_FLASH=1`. When the external flash support is
130+
enabled, update and swap partitions can be associated to an external memory, and will use alternative
131+
HAL function for read/write/erase access.
132+
To associate the update or the swap partition to an external memory, define `PART_UPDATE_EXT` and/or
133+
`PART_SWAP_EXT`, respectively. By default, the makefile assumes that if an external memory is present,
134+
both `PART_UPDATE_EXT` and `PART_SWAP_EXT` are defined.
135+
136+
When external memory is used, the HAL API must be extended to define methods to access the custom memory.
137+
Refer to the [HAL](HAL.md) page for the description of the `ext_flash_*` API.
138+

0 commit comments

Comments
 (0)