-
Notifications
You must be signed in to change notification settings - Fork 3
/
fwupgrade-doc.txt
111 lines (89 loc) · 4.89 KB
/
fwupgrade-doc.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
Firmware upgrade
================
This software is composed of two applications :
* fwupgrade-tool, which is an utility compiled for the host machine,
that allows to generate and inspect a firmware image
* fwupgrade, which is an executable typically compiled for the target
and having two roles:
When called with just the name 'fwupgrade' and a file name as
argument, it triggers the firmware upgrade process using a locally
stored firmware image file.
When called with the name 'fwupgrade-cgi', it acts as a cgi-bin
executable, that receives the firmware image from HTTP and then
runs the firmware upgrade process.
In both cases, the firmware upgrade process will flash the various
parts of the firmware image in the right MTD partitions/UBIFS volumes
and will update the U-Boot environment accordingly
Typically, the 'fwupgrade' program is installed in /usr/bin, and
for the CGI side, a symbolic link from for example
/var/www/cgi-bin/fwupgrade-cgi to /usr/bin/fwupgrade is used.
The firmware image contains a set of "parts", each identified by a
name. The fwupgrade-cgi program contains a configuration telling where
a given part should be flashed. For each part, two MTD partitions (or
UBIFS volumes) are specified, so that the updates are not done by
overwriting the currently running kernel or the currently mounted
filesystems. The fwupgrade-cgi looks at the U-Boot environment for
variables named <partname>_mtdpart (or <partname>_ubivol) to know where
the current version of the part is being stored.
As this tool handles MTD or UBI partitions, a fourth field must be
defined to indicate if it is a MTD or UBI partition type. In case this
field is not defined, it will assume MTD partitions by default.
** Example for MTD partitions **
For exemple, if a part is named "rootfs" and the fwupgrade-cgi program
has the configuration that the "rootfs" part is on mtd2 or mtd3, then:
* If the rootfs_mtdpart U-Boot variable says 'mtd2', the new image is
flashed on mtd3 and the U-Boot variable rootfs_mtdpart is changed
to 'mtd3'
* If the rootfs_mtdpart U-Boot variable says 'mtd3', the new image is
flashed on mtd2 and the U-Boot variable rootfs_mtdpart is changed
to 'mtd2'
Of course, the U-Boot environnement is supposed to be configured so
that the rootfs_mtdpart is used to tell the kernel where the current
root filesystem is.
** Example for UBIFS volumes **
In case of a UBI/UBIFS system, the fwupgrade tool will update UBIFS
volumes. In that case, it follows the same description than above with
some differences:
* You will specify a volume name and not a MTD partition name
* You *must* define the 4th field to indicate that it is a UBI
partition type with "ubi" keyword.
* The u-boot environment variable is no longer "<name>_mtdpart" but
"<name>_ubivol".
See "fwupgrade-ubi-example.conf" file to have an example of a UBI
configuration.
Firmware image file format
==========================
+------------+ --------------------------- +--------------+
| header | | magic |
+------------+ \ | hwid |
| | \ | flags |
| part 0 | \ +--------------+ ----------- +-------------+
| | \ | part 0 desc | | name |
+------------+ \ +--------------+ \ | crc |
| | \ | part 1 desc | \ | length |
| | \ +--------------+ \ | offset |
| part 1 | \ | part 2 desc | \ | padding |
| | \ +--------------+ \______ +-------------+
| | \ | part 3 desc | 128 bytes
+------------+ \ +--------------+
| | \ | part 4 desc |
| | \ +--------------+
| | \ ...........
| | \ +--------------+
| part 2 | \ | part 15 desc |
| | \ +--------------+
| | \ | padding |
| | \________ +--------------+
| | 2048 bytes
+------------+
| |
| |
| part 3 |
| |
| |
+------------+
Testing
=======
To test the firmware upgrade process, it is nice to have this curl
command around:
curl -F "file=@./firmware.img" http://IPADDR/cgi-bin/fwupgrade-cgi