-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
123 lines (95 loc) · 5.27 KB
/
README
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
112
113
114
115
116
117
118
119
120
121
122
This is the tool to generate the OSD upgrade packages. They're called
UPK files. Usage:
./upk-builder nh [upk_desc] [upk_name] [bins ...]
Read below for explanation of the arguments
Introduction to UPK files
================================
Nobody wants a bricked OSD (I've got one, it's not much fun), so it is
important to ensure that any community-supplied UPK update doesn't touch
the core bootloader.
The OSD's core bootloader - Das U-boot - contains code which offers the
[Emergency Firmware Upgrade](http://neurostechnology.com/neuros-osd-emergency-upgrade-instructions)
mechanism, to allow one to recover a non-booting unit by detecting an
SD-card or CF-card with a UPK file precisely located at `newpackage/r3.upk`
(and usually a file of name `newpackage/disable_upk_version_check`).
We would like to ensure this remains untouched by a firmware update.
Make-up of a UPK
-------------------------
UPKs can contain individual updates to the following parts of the OSD's firmware:
* MSP430 chip
* U-boot bootloader (`u-boot.bin`)
* Bootloader environment variables (`env.img`)
* Kernel (`uImage`)
* Root filesystem (`root.cramfs`) - limited in size to under 15MB
* Extended filesystem (`programs_*.tar.gz`) - see Note 1 below
But all parts are optional, so critical parts like U-boot and its env vars
can be omitted.
U-boot, Kernel, Root & Extended filesystems are versioned - they have individual
version strings. These are checked before installation - though the check
is ignored if the `disable_upk_version_check` file exists. If the version
is older than that on the unit, it is not installed.
**But even if U-boot and/or the kernel is not contained in the UPK, the
version string must _exactly match_ that installed on the unit. If not, the
update will not proceed.**
So to make a safe UPK which works, you must omit U-boot and its env vars,
but ensure the U-boot version string matches that already installed on the
unit. Similar rule applies if you omit the kernel.
How UPK is actually made
-------------------------
In Neuros' firmware build scripts, this is managed by the
`neuros-bsp/build-helper.sh` script, in the `make_upk()` method. A (open-source)
tool named `packet_16M` is built in `linux-r3-extra-apps/upgrade-tools/uboot-tools`
during the build, and is copied into `neuros-bsp/images`.
Also copied into `neuros-bsp/images` are (among other things):
env.img
extapp.version
root.cramfs
rootfs.version
u-boot.bin
u-boot.version
uImage
uImage.version
programs/extapp.version
programs_0.tar.gz
The *.version files are generated somehow (I don't see how just yet) containing
just the version strings of the form: `A.BC-D.EF-GH.IJK`. See
[here](http://wiki.neurostechnology.com/index.php/Developer_FAQ#Beta_.26_Production_Release_Version)
for the explanation of this. Slightly over-engineered IMO!
Then these files are integrated into a UPK file with the command
./packet_16M nh "Identifying String" dev.upk u-boot.bin env.img uImage root.cramfs programs_0.tar.gz
which creates a `dev.upk` file in that directory. ('nh' means no firmware for
MSP430 - we'll leave that alone too)
This tool uses the filename to determine what kind of file is supplied, and
opens the relevant `.version` file to incorporate its version string. The tool
is flexible enough that we can omit U-boot and its env vars, so this will work
too:
./packet_16M nh 'Safer UPK' dev.upk uImage root.cramfs programs_0.tar.gz
But make sure that the `*.version` files contain the correct version strings to
apply over whatever firmware version exists. Then you have a safe UPK file to
give to a user.
Note 1
-------------------------
There is both a Root filesystem and an Extended filesystem because original OSD
units had only 16MB of internal storage (NOR flash). Under 15MB of this is
available for software. Later in the device's lifetime, this was found to be
insufficient so Neuros offered customers free 128MB CF cards to extend the
internal storage for newer firmwares.
New OSDs (version 1.15 I think) contain 128MB of internal NAND flash - but lack
a CF card slot.
NOR flash is primarily read-only, each block capable of only around 100,000
write cycles before expiry. It has fast read speeds but very slow writes, thus
it is usually used as a read-only medium. The Cramfs filesystem is a compressed
read-only filesystem which is good for use on NOR flash, and the OSD uses this.
Note that Squashfs is a newer equivalent, with better read speeds and higher
compression ratios, and is worth investigating.
NAND flash has a similar number of write cycles, but writes are much faster, so
is mostly used as a read-write filesystem with particular formatting - jffs2 is
used for this. This distributes all writes over all the blocks - known as
wear-leveling - to prolong the life of the medium.
Note also that the OSD has a 1MB designated read-write partition for settings -
this is most notable on the older units. It is located at /mnt/OSD and uses
jffs2 filesystem. For older units, this works ok but the number of writes to
this should be minimised. This partition is untouched by any UPK installation,
so settings are always preserved.
Thus all OSD units contain a read-only root filesystem, and a read-write
filesystem in /media/ext. The underlying hardware differences are moot.