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
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
|
flash-kernel
------------
flash-kernel is a script which will put the kernel and initramfs in
the boot location of embedded devices that don't load the kernel and
initramfs directly from /boot. flash-kernel supports devices that
boot from flash memory (hence the name) as well as some devices that
require a special boot image on the disk.
Check the Database file db/all.db (in the source package) or
/usr/share/flash-kernel/db/all.db (in the installed package) for supported
machines.
If you would like to see support for another device, please file a bug
report in the Debian Bug Tracking System and include all information
related to the boot process of your device. Instructions can be found
at https://bugs.debian.org/ . Alternatively prepare a Merge Request on
https://salsa.debian.org/ .
Testsuite
- - - - -
Run the testsuite with:
FK_CHECKOUT=. ./test_db
FK_CHECKOUT=. ./test_flash-kernel
FK_CHECKOUT=. ./test_functions
You need the devscripts package for the checkbashisms test.
Database format
- - - - - - - -
To accommodate the differences between machines, db/*.db files contain
information on supported machines. The files look somewhat like
RFC 2822 data or Debian control data, i.e. header: value pairs,
with definitions separated by an empty line. Comments starting with a
pound are ignored.
/etc/flash-kernel/db is parsed first and allows for local override of
any field. Note that you must include the "Machine" field (including
multiple instances if necessary) here as well as the field(s) to be
overridden.
The supported fields are:
* Machine: (required) value of the "Hardware:" line in /proc/cpuinfo
or content of /proc/device-tree/model. Used as a unique
identifier. Must be the first field in each stanza. There can be
multiple instances of this field (to support system which have both
cpuinfo:Hardware and device-tree based identifiers depending on the
current kernel) but all instances of the Machine: field must come
before any other field in the stanza.
* Kernel-Flavors: (optional) allowed flavors (suffixes) for the to be
installed kernel; if the vmlinuz file doesn't end with a listed
suffix, installation is aborted
* Machine-Id: (optional) linux mach-type to set before starting vmlinuz;
will be set by a small piece of ARM code prepended to the kernel image.
This option is ignored if a DTB is to be appended, via either DTB-Append or
DTB-Append-From.
* DTB-Id: (optional) specifies the name of the DTB file for this device.
If DTB-Id specifies an absolute path the directory specifies the path from
where the DTB is copied.
If DTB-Id specifies a relative path the directory specifies the subdirectory
of the kernel version directory where the DTB will be installed.
The filename is used to search for the filename in subdirectories of
/usr/lib/linux-image-* or /etc/flash-kernel/dtbs.
If the value begins with a `!' then the field is a script which should be
run. The script must produce the DTB filename (possibly including a
directory) on stdout.
* DTB-Append: (optional) when yes the DTB specified by DTB-Id will be appended
to the kernel image.
* DTB-Append-From: (optional): Can be used instead of DTB-Append. The argument
is a kernel version, if the kernel to be installed is at least this version
then the DTB specified named by DTB-Id will be appended to the kernel image.
When adding or updating this field remember to consider whether the kernel
will require an update to its versioned Breaks: on flash-kernel.
* U-Boot-Kernel-Address, U-Boot-Kernel-Entry-Point, U-Boot-Initrd-Address:
(optional) address where to load in (physical) RAM the kernel, entry point
and initrd, respectively; this also indicates that U-Boot images should be
generated with mkimage
* U-Boot-Script-Address: (optional) like U-Boot-Kernel-Address and
U-Boot-Initrd-Address but for an U-Boot boot script; see also
U-Boot-Script-Name
* U-Boot-Script-Name: (optional) name of U-Boot boot script to install
from the flash-kernel files. @@KERNEL_VERSION@@ will be substituted for the
actual kernel version
* Boot-Kernel-Path, Boot-Initrd-Path: (optional) where to put the
generated kernel and initrd files on the filesystem; see also
Boot-Device
* Boot-Kernel-Path-Version, Boot-Initrd-Path-Version, Boot-DTB-Path-Version:
(optional) if "yes" appends the kernel version to files created with
Boot-Kernel-Path, Boot-Initrd-Path and Boot-DTB-Path.
* Boot-Script-Path: (optional) like Boot-Kernel-Path and
Boot-Initrd-Path but for an U-Boot boot script; see also
U-Boot-Script-Name and Boot-Device
* Boot-DTB-Path: (optional) like Boot-Kernel-Path and Boot-Initrd-Path
but for a DTB file. The DTB file named by DTB-Id will be copied
here; see also DTB-Id
* Mtd-Kernel, Mtd-Initrd: (optional) Specifies the raw MTD partition
name (per /proc/mtd) to use for the kernel and initrd respectively.
* Required-Packages: (optional) list of packages which must be added
during installer phase for flash-kernel to work properly; failure to
add these packages aborts the installation
* Optional-Packages: (optional) list of packages which should be
added during installer phase for flash-kernel to offer full
functionality; failure to add these packages just triggers a warning
* Bootloader-Sets-Incorrect-Root: (optional) when "yes" indicates that
the bootloader passes a root= value to the kernel and that this
should be overridden in the initrd; when "no", flash-kernel only sets
a default value for the root device, which allows end-users to pass
root= to the kernel.
* Method: (optional) indicates how to support this particular machine;
the default is "generic"; other available methods are: android, bootspec,
multi, redboot, slug, symlink and olpc
* Boot-Device: (optional) block device to mount before installing
kernel, initrd and U-Boot script; Boot-Kernel-Path, Boot-Initrd-Path and
Boot-Script-Path are then taken relative to this boot device
Configuration
- - - - - - -
Configuration files currently supported:
* /etc/flash-kernel/machine allows skipping the machine auto-detection from
/proc/cpuinfo or /proc/dtmodel and forcing a specific Machine.
* /etc/flash-kernel/db allows overriding / adding fields from the Machine
database (but it doesn't allow removing fields or entries).
* /etc/flash-kernel/dtbs (directory). If a DTB matching DTB-Id is
found here then it will be used in preference to the one shipped by
the kernel being installed.
* /etc/flash-kernels/bootscript (directory). The files referenced via
the Boot-Script-Name field are installed here.
* /etc/flash-kernel/ubootenv.d and /etc/flash-kernel/preboot.d can be used to
add or override u-boot script snippets. See "Adding U-Boot Commands for
Pre-Boot Execution" below for more details.
* /etc/default/flash-kernel currently contains the following variables:
- LINUX_KERNEL_CMDLINE, which should be used by bootscripts to set kernel
options, overriding the firmwares defaults (e.g. u-boot's ${bootargs}).
- LINUX_KERNEL_CMDLINE_DEFAULTS, which should be used by bootscripts to set
kernel options which should be overrideable by the firmware's defaults
(e.g. u-boot's ${bootargs}).
- NO_CREATE_DOT_BAK_FILES, which if set to "true" or "yes" will
prevent flash-kernel from creating backup ".bak" versions of
kernel, initrd, and dtb files when installing a new version. The
default is to create such backups to aid in recovery from
failed updates. If this option is enabled then more complex
methods or specialised hardware (e.g. JTAG) may be required to
recover.
- MTD_BACKUP_DIR, which if set, names a directory to which
flash-kernel will write copies of files which would not normally
be accessible in the regular filesystem (either written to a
rawflash partition or to a firmware partition which is not
normally mounted). If unset defaults to
/var/backups/flash-kernel. Set to "none" to disable.
Adding U-Boot Commands for Pre-Boot Execution
- - - - - - - - - - - - - - - - - - - - - - -
Packages can drop in files containing U-Boot commands to be executed by a
platform's bootscript before starting the OS. These files should be
dropped in /usr/share/flash-kernel/ubootenv.d and
/usr/share/flash-kernel/preboot.d. Users can add additional
stubs, or override stubs provided by packages, by adding files to
/etc/flash-kernel/ubootenv.d and /etc/flash-kernel/preboot.d. Files in the
/etc path that have the same name as files in the /usr path will override the
/usr counterparts.
Platform bootscripts must contain the @@UBOOT_ENV_EXTRA@@ and
@@UBOOT_PREBOOT_EXTRA@@ macros for the contents of these stubs to be
incorporated.
|
