Skip to content

Commit 61fec07

Browse files
michallencacassis
michallenc
authored and
acassis
committedNov 1, 2024
boot: add NuttX bootloader with update and recovery support
This commit adds NuttX based bootloader with the support for image update and recovery if not confirmed. The algorithm utilizes three flash partitions: primary (image runs from this area), secondary and tertiary. Secondary and tertiary areas are used for update upload and recovery. The update is performed by simple copy from update area to primary area with recovery being created in recovery area if not already present. Once image is confirmed by the user, the image in update area is confirmed as well, update area becomes recovery area and vice versa. This means the recovery is always present (except for the first update) and subsequent updates just copy image from update to primary. This makes the update significantly faster and more considerable to flash wear while keeping the recovery/revert possibility. A header (aligned to flash's erase size) must be added to the beginning of the image. Python script nximage.py can be used to prepend this header to built binary. The algorithm also uses one erase page at the end of a partition (partition, not image!) to store flags used to indicate image confirm status and to detect update/recovery partitions. Any program uploading update image to the update partition has to erase this page for the boot to work correctly! The algorithm implementation is based on a patch initially developed for MCUboot project but rejected by the project's maintainers mcu-tools/mcuboot#1902 Signed-off-by: Michal Lenc <michallenc@seznam.cz>
1 parent 242b947 commit 61fec07

File tree

11 files changed

+1800
-0
lines changed

11 files changed

+1800
-0
lines changed
 

‎boot/nxboot/CMakeLists.txt

+32
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# ##############################################################################
2+
# apps/boot/nxboot/CMakeLists.txt
3+
#
4+
# Licensed to the Apache Software Foundation (ASF) under one or more contributor
5+
# license agreements. See the NOTICE file distributed with this work for
6+
# additional information regarding copyright ownership. The ASF licenses this
7+
# file to you under the Apache License, Version 2.0 (the "License"); you may not
8+
# use this file except in compliance with the License. You may obtain a copy of
9+
# the License at
10+
#
11+
# http://www.apache.org/licenses/LICENSE-2.0
12+
#
13+
# Unless required by applicable law or agreed to in writing, software
14+
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
15+
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
16+
# License for the specific language governing permissions and limitations under
17+
# the License.
18+
#
19+
# ##############################################################################
20+
21+
if(CONFIG_BOOT_NXBOOT)
22+
nuttx_add_library(nxboot)
23+
set(SRCS loader/boot.c loader/flash.c)
24+
25+
if(BOOT_NXBOOT)
26+
nuttx_add_application(NAME nxboot_loader SRCS nxboot_main.c
27+
INCLUDE_DIRECTORIES include)
28+
endif()
29+
30+
target_include_directories(nxboot PUBLIC include)
31+
target_sources(nxboot PRIVATE ${SRCS})
32+
endif()

‎boot/nxboot/Kconfig

+88
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
#
2+
# For a description of the syntax of this configuration file,
3+
# see the file kconfig-language.txt in the NuttX tools repository.
4+
#
5+
6+
menuconfig BOOT_NXBOOT
7+
bool "NuttX bootloader"
8+
default n
9+
select BCH
10+
---help---
11+
Enable support for the minimal NuttX based bootloader.
12+
13+
if BOOT_NXBOOT
14+
15+
config NXBOOT_PRIMARY_SLOT_PATH
16+
string "Application firmware primary image slot path"
17+
default "/dev/ota0"
18+
---help---
19+
The path to the application firmware image primary slot character
20+
device driver. The image runs from this location.
21+
Default: /dev/ota0
22+
23+
config NXBOOT_SECONDARY_SLOT_PATH
24+
string "Application firmware secondary image slot path"
25+
default "/dev/ota1"
26+
---help---
27+
The path to the application firmware image primary slot character
28+
device driver. This is either update or recovery slot.
29+
Default: /dev/ota1
30+
31+
config NXBOOT_TERTIARY_SLOT_PATH
32+
string "Application firmware tertiary image slot path"
33+
default "/dev/ota2"
34+
---help---
35+
The path to the application firmware image primary slot character
36+
device driver. This is either update or recovery slot.
37+
Default: /dev/ota2
38+
39+
config NXBOOT_HEADER_SIZE
40+
hex "Application firmware image header size"
41+
default 0x200
42+
---help---
43+
Note that this size should be aligned with the program memory write
44+
page size!
45+
46+
config NXBOOT_BOOTLOADER
47+
bool "Build nxboot bootloader application"
48+
default n
49+
select BOARDCTL
50+
select BOARDCTL_BOOT_IMAGE
51+
---help---
52+
This option builds and links a bootloader application. This application
53+
should be an entry function for NuttX. It checks for possible update/
54+
revert operation, performs it and boot the correct image.
55+
56+
if NXBOOT_BOOTLOADER
57+
58+
config NXBOOT_SWRESET_ONLY
59+
bool "Perform update/revert only on SW reset"
60+
default n
61+
select BOARDCTL_RESET_CAUSE
62+
---help---
63+
This option ensures the update/revert is performed only for following
64+
reset causes:
65+
BOARDIOC_RESETCAUSE_CPU_SOFT: software reset
66+
BOARDIOC_RESETCAUSE_CPU_RWDT: watchdog error
67+
BOARDIOC_RESETCAUSE_PIN: reset button
68+
69+
This way the board can keep its image (even if not confirmed) during
70+
for example power shutdown and perform update/revent only if expected
71+
based on user/maintainer input.
72+
73+
config NXBOOT_PREVENT_DOWNGRADE
74+
bool "Perform update only for newer version"
75+
default n
76+
---help---
77+
NXboot uses Semantic Version 2.0.0 (without build metadata). By default
78+
the update is performed for every version that doesn't match the
79+
currently running one. If NXBOOT_PREVENT_DOWNGRADE selected, update is
80+
performed only for newer versions (according to Semantic Version
81+
preference rules).
82+
83+
WARNING: NXboot currently implementes preferences only for
84+
MAJOR.MINOR.PATCH and ignores prerelease.
85+
86+
endif # NXBOOT_BOOTLOADER
87+
88+
endif # BOOT_NXBOOT

‎boot/nxboot/Make.defs

+26
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
############################################################################
2+
# apps/boot/nxboot/Make.defs
3+
#
4+
# Licensed to the Apache Software Foundation (ASF) under one or more
5+
# contributor license agreements. See the NOTICE file distributed with
6+
# this work for additional information regarding copyright ownership. The
7+
# ASF licenses this file to you under the Apache License, Version 2.0 (the
8+
# "License"); you may not use this file except in compliance with the
9+
# License. You may obtain a copy of the License at
10+
#
11+
# http://www.apache.org/licenses/LICENSE-2.0
12+
#
13+
# Unless required by applicable law or agreed to in writing, software
14+
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
15+
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
16+
# License for the specific language governing permissions and limitations
17+
# under the License.
18+
#
19+
############################################################################
20+
21+
ifneq ($(CONFIG_BOOT_NXBOOT),)
22+
CONFIGURED_APPS += $(APPDIR)/boot/nxboot
23+
24+
CFLAGS += ${INCDIR_PREFIX}$(APPDIR)/boot/nxboot/include
25+
26+
endif

‎boot/nxboot/Makefile

+34
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
############################################################################
2+
# apps/boot/nxboot/Makefile
3+
#
4+
# Licensed to the Apache Software Foundation (ASF) under one or more
5+
# contributor license agreements. See the NOTICE file distributed with
6+
# this work for additional information regarding copyright ownership. The
7+
# ASF licenses this file to you under the Apache License, Version 2.0 (the
8+
# "License"); you may not use this file except in compliance with the
9+
# License. You may obtain a copy of the License at
10+
#
11+
# http://www.apache.org/licenses/LICENSE-2.0
12+
#
13+
# Unless required by applicable law or agreed to in writing, software
14+
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
15+
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
16+
# License for the specific language governing permissions and limitations
17+
# under the License.
18+
#
19+
############################################################################
20+
21+
include $(APPDIR)/Make.defs
22+
23+
ifneq ($(CONFIG_NXBOOT_BOOTLOADER),)
24+
PROGNAME = nxboot_loader
25+
PRIORITY = SCHED_PRIORITY_DEFAULT
26+
STACKSIZE = $(CONFIG_DEFAULT_TASK_STACKSIZE)
27+
28+
MAINSRC = nxboot_main.c
29+
endif
30+
31+
CSRCS := loader/boot.c \
32+
loader/flash.c
33+
34+
include $(APPDIR)/Application.mk

‎boot/nxboot/include/nxboot.h

+181
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
/****************************************************************************
2+
* apps/boot/nxboot/include/nxboot.h
3+
*
4+
* Licensed to the Apache Software Foundation (ASF) under one or more
5+
* contributor license agreements. See the NOTICE file distributed with
6+
* this work for additional information regarding copyright ownership. The
7+
* ASF licenses this file to you under the Apache License, Version 2.0 (the
8+
* "License"); you may not use this file except in compliance with the
9+
* License. You may obtain a copy of the License at
10+
*
11+
* http://www.apache.org/licenses/LICENSE-2.0
12+
*
13+
* Unless required by applicable law or agreed to in writing, software
14+
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
15+
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
16+
* License for the specific language governing permissions and limitations
17+
* under the License.
18+
*
19+
****************************************************************************/
20+
21+
#ifndef __BOOT_NXBOOT_INCLUDE_NXBOOT_H
22+
#define __BOOT_NXBOOT_INCLUDE_NXBOOT_H
23+
24+
/****************************************************************************
25+
* Included Files
26+
****************************************************************************/
27+
28+
#include <nuttx/config.h>
29+
#include <assert.h>
30+
#include <stdbool.h>
31+
32+
/****************************************************************************
33+
* Pre-processor Definitions
34+
****************************************************************************/
35+
36+
#define NXBOOT_PRIMARY_SLOT_NUM (0)
37+
#define NXBOOT_SECONDARY_SLOT_NUM (1)
38+
#define NXBOOT_TERTIARY_SLOT_NUM (2)
39+
40+
/* Offsets to write pages containing confirmed and updated flags. These
41+
* pages are located at the end of the partition, therefore index 0 means
42+
* the first page from the end.
43+
*/
44+
45+
#define NXBOOT_CONFIRMED_PAGE_INDEX (0)
46+
#define NXBOOT_UPDATED_PAGE_INDEX (1)
47+
48+
#define NXBOOT_HEADER_MAGIC 0x534f584e /* NXOS. */
49+
#define NXBOOT_HEADER_MAGIC_INV 0xaca0abb1 /* NXOS inverted. This is used
50+
* for images uploaded directly
51+
* to the primary flash with
52+
* the debugger. These images
53+
* does not have precalculated
54+
* CRC and flags at the
55+
* end of the partition, but
56+
* are considered to be valid.
57+
*/
58+
59+
#define NXBOOT_HEADER_PRERELEASE_MAXLEN 110
60+
61+
/****************************************************************************
62+
* Public Types
63+
****************************************************************************/
64+
65+
enum nxboot_update_type
66+
{
67+
NXBOOT_UPDATE_TYPE_NONE = 0, /* No action to do */
68+
NXBOOT_UPDATE_TYPE_UPDATE = 1, /* Update will take place upon reboot */
69+
NXBOOT_UPDATE_TYPE_REVERT = 2, /* Revert will take place upon reboot */
70+
};
71+
72+
/* Versioning is according to Semantic Versioning 2.0.0
73+
* refer to (https://semver.org/spec/v2.0.0.html)
74+
*/
75+
76+
struct nxboot_img_version
77+
{
78+
uint16_t major; /* MAJOR version */
79+
uint16_t minor; /* MINOR version */
80+
uint16_t patch; /* PATCH version */
81+
82+
char pre_release[NXBOOT_HEADER_PRERELEASE_MAXLEN]; /* Additional pre-release version */
83+
};
84+
85+
struct nxboot_img_header
86+
{
87+
uint32_t magic; /* Header magic */
88+
uint32_t size; /* Image size (excluding the header) */
89+
uint32_t crc; /* CRC32 of image (excluding the header). */
90+
91+
struct nxboot_img_version img_version; /* Image version */
92+
};
93+
static_assert(CONFIG_NXBOOT_HEADER_SIZE > sizeof(struct nxboot_img_header),
94+
"CONFIG_NXBOOT_HEADER_SIZE has to be larger than"
95+
"sizeof(struct nxboot_img_header)");
96+
97+
struct nxboot_state
98+
{
99+
int update; /* Number of update slot */
100+
int recovery; /* Number of recovery slot */
101+
bool recovery_valid; /* True if recovery image contains valid recovery */
102+
bool primary_confirmed; /* True if primary slot is confirmed */
103+
enum nxboot_update_type next_boot; /* True if update slot has a valid image */
104+
};
105+
106+
/****************************************************************************
107+
* Public Function Prototypes
108+
****************************************************************************/
109+
110+
/****************************************************************************
111+
* Name: nxboot_get_state
112+
*
113+
* Description:
114+
* Gets the current bootloader state and stores it in the nxboot_state
115+
* structure passed as an argument. This function may be used to determine
116+
* which slot is update slot and where should application save incoming
117+
* firmware.
118+
*
119+
* Input parameters:
120+
* state: The pointer to nxboot_state structure. The state is stored here.
121+
*
122+
* Returned Value:
123+
* 0 on success, -1 and sets errno on failure.
124+
*
125+
****************************************************************************/
126+
127+
int nxboot_get_state(struct nxboot_state *state);
128+
129+
/****************************************************************************
130+
* Name: nxboot_get_confirm
131+
*
132+
* Description:
133+
* This function can be used to determine whether primary image is
134+
* confirmed or not. This provides more direct access to confirm
135+
* state compared to nxboot_get_state function that returns the full
136+
* state of the bootloader.
137+
*
138+
* Returned Value:
139+
* 1 means confirmed, 0 not confirmed, -1 and sets errno on failure.
140+
*
141+
****************************************************************************/
142+
143+
int nxboot_get_confirm(void);
144+
145+
/****************************************************************************
146+
* Name: nxboot_confirm
147+
*
148+
* Description:
149+
* Confirms the image currently located in primary partition and marks
150+
* its copy in update partition as a recovery.
151+
*
152+
* Returned Value:
153+
* 0 on success, -1 and sets errno on failure.
154+
*
155+
****************************************************************************/
156+
157+
int nxboot_confirm(void);
158+
159+
/****************************************************************************
160+
* Name: nxboot_perform_swap
161+
*
162+
* Description:
163+
* Checks for the possible firmware update and performs it by copying
164+
* update image to primary slot or recovery image to primary slot in case
165+
* of the revert. In any situation, this function ends with the valid
166+
* image in primary slot.
167+
*
168+
* This is an entry point function that should be called from the
169+
* bootloader application.
170+
*
171+
* Input parameters:
172+
* check_only: Only repairs corrupted update, but do not start another one
173+
*
174+
* Returned Value:
175+
* 0 on success, -1 and sets errno on failure.
176+
*
177+
****************************************************************************/
178+
179+
int nxboot_perform_update(bool check_only);
180+
181+
#endif /* __BOOT_NXBOOT_INCLUDE_NXBOOT_H */

0 commit comments

Comments
 (0)
Please sign in to comment.