summaryrefslogtreecommitdiffstats
path: root/user/tools/boot-image.rst
blob: 8e8f63d41f9d9ba0b8386e415e6927809a34ca51 (plain)
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
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
.. SPDX-License-Identifier: CC-BY-SA-4.0

.. Copyright (C) 2019 Chris Johns <chrisj@rtems.org>

.. _rtems-boot-image:

RTEMS Boot Image
================

.. index:: Tools, rtems-boot-image

The RTEMS Boot Image (:program:`rtems-boot-image`) command is an RTEMS
tool to create disk images suitable for SD cards to boot RTEMS on a
range of boards. The supported hosts are:

- FreeBSD

- Linux

- MacOS

The tool captures the specific details for a host operating system to
create a bootable disk image as well as capturing the specific detail
of the boards that are supported. The tool brings these detail
together under a sigle command line interface that is portable across
the supported hosts.

The boot image tool can:

- Create a disk image to boot an RTEMS executable

- Create a disk image to network boot an RTEMS executable

- Convert an RTEMS executable into the format a board's bootloader
  can load.

The disk images are suitable for booting a range of hardware that have
media interfaces, such as an SD card. The default partition type is
the Master Boot Record (MRB) and a single root DOS-FS partition is
created.

Boot Loaders
------------

The boot image tool supports the following boot loaders:

- U-boot

U-Boot
~~~~~~

The U-Boot boards supported are:

- BeagleBone (`arm-ti-am335x_evm`)

- Zedboard (`arm-xilinx-zynq-common`)

These boards can be booted with executable and Flat Device Tree (FDT)
blobs on disk or view a network if supported by the boards.

The boot image tool can create the following boot configurations for
U-Boot:

- **Executable**

  A kernel executable is copied in the disk image, loaded by U-Boot
  and control is passed to the kernel. A reset is performed if the
  load fails or the kernel returns control to U-Boot.

- **Executable and FDT**

  A kernel executable and FDT blob are copied to the disk image,
  loaded by U-boot and control is passed to the kernel. A reset is
  performed if the load fails or the kernel returns control to U-Boot.

- **Network DHCP and Executable**

  The board's network interface is initialised, a DHCP request made
  and a kernel image loaded using TFTP. The loaded kernel is passed
  control. A reset is performed if the load fails or the kernel
  returns control to U-Boot.

- **Network DHCP, Executable and FDT**

  The board's network interface is initialised, a DHCP request made
  and a kernel image loaded using TFTP. The loaded kernel is passed
  control. A reset is performed if the load fails or the kernel
  returns control to U-Boot.

  The FDT can be installed in and disk image and loaded from it on
  each boot.

- **Network Static IP and Executable**

  The board's network interface is initialised with a static IP
  address and a kernel image loaded using TFTP. The loaded kernel is
  passed control. A reset is performed if the load fails or the kernel
  returns control to U-Boot.

- **Network Static IP, Executable and FDT**

  The board's network interface is initialised with a static IP
  address and a kernel image loaded using TFTP. The loaded kernel is
  passed control. A reset is performed if the load fails or the kernel
  returns control to U-Boot.

  The FDT can be installed in and disk image and loaded from it on
  each boot.

Hosts
-----

The hosts each require specific set up to run the boot image
buildier. The tool creates special devices to access the image as a
disk and runs file system partitioning and formatting tools. These
tools typically require super user or root access. It is not good
practice to run commands like this one as root and so the tool
dispatches any specific command that needs higher privileges via
``sudo``. If you see a password prompt please enter your password, not
a root password if you have one confgiured.

FreeBSD
~~~~~~~

Install the ``sudo`` package. All commands used are in standard
operating system paths and should not require any specific
configurations.

Linux
~~~~~

The loop back kernel module needs to be loaded.

MacOS
~~~~~

All command used are part of the base OS. No external packages are
required.

Configuration
-------------

The boot image tool is configured by the file :file:`rtems-boot.ini`
that is installed in the

Command
-------

The :program:`rtems-boot-image` tool creates a boot disk image for a
specified board. The command line options are:

:program:`rtems-boot-image`

.. option:: -h, --help

   Display the command line help.

.. option:: -l, --log

   Set the log file name. The default is
   :file:`rtems-log-boot-image.txt`.

.. option:: -v, --trace

   Enable trace or debug logging.

.. option:: -s IMAGE_SIZE, --image-size IMAGE_SIZE

   Set the image size. The size can be in SI units of ``k``, ``m``, or
   ``g``. The size needs to be something the host's parition and
   format tools will accept and it must be large enough to fit the
   root partition plus any alignments. The default is ``64m``.

.. option:: -F FS_FORMAT, --fs-format FS_FORMAT

   Specify type type of format. The supported formats are ``fat16``
   and ``fat32``. The default format is ``fat16``.

.. option:: -S FS_SIZE, --fs-size FS_SIZE

   Set the size of the first partition in the disk image. The
   partition need to be less than the size of the image plus the
   alignment. The default size is ``auto`` which will fill the image
   with the partition.

.. option:: -A FS_ALIGN, --fs-align FS_ALIGN

   Set the alignment of the first partition. The default is ``1m``.

.. option:: -k KERNEL, --kernel KERNEL

   Optionally provide a kernel image that is copied into the root
   partition of the disk image and loaded and run when the board
   boots. The file is an RTEMS executable in the ELF format which is
   converted to a format the boot loader can load.

.. option:: -d FDT, --fdt FDT

   Optionally provide a FDT blob that is copied into the root
   partition of the disk image and loaded when the board boots. If a
   kernel is provided or a kernel is loaded via a net boot a kernel
   boot with FDT is executabled. The file is an FDT blob created by
   the FDT compiler.

.. option:: -f FILE, --file FILE

   Optionally provide a file to be copied to the root partition of the
   disk image. This option can be provided more than once if more than
   one file needs to be installed.

.. option:: --net-boot

   Not used and will be removed.

.. option:: --net-boot-dhcp

   Configure a network boot using DHCP. The kernel will be loaded
   using TFTP and the file request can be specific by the
   ``--net-boot-file`` option.

.. option:: --net-boot-ip NET_BOOT_IP

   Configure a network boot using a static IP address. The kernel will
   be loaded using TFTP and the file request can be specific by the
   ``--net-boot-file`` option. A server IP needs to be specified using
   the ``--net-boot-server``.

.. option:: --net-boot-file NET_BOOT_FILE

   Specify the kernel image file name requested using the TFTP
   protocol. The default is :file:`rtems.img`.

.. option:: --net-boot-fdt NET_BOOT_FDT

   Optionally specify the file name of a FDT blob loaded using the
   TFTP protocol. If a net boot FDT file is provide the kernel will be
   executable with a suitable kernel and FDT boot command.

.. option:: -U CUSTOM_UENV, --custom-uenv CUSTOM_UENV

   Optionally provide a custom U-boot :file:`uEnv.txt` file that is
   copied to into the root directory of the root partition of the disk
   image.

.. option:: -b BOARD, --board BOARD

   Specify the board the disk image is built for. The default board is
   ``list`` which lists the available board configurations.

.. option:: --convert-kernel

   Convert an RTEMS ELF executable into an image file the selected
   board's bootloader can load. This option does not create a disk
   image. The option can be used to create images that can be loaded
   when network booting.

.. option:: --no-clean

   If provided the :file:`build` directory will not be removed after
   the disk image has been created.

.. option:: -o OUTPUT, --output OUTPUT

   The output file name for the image. If the ``--convert-kernel``
   option is used the conversion is written as this file name and if
   it is not provided the output file is the built disk image.

.. option:: paths [paths ...]

   The required paths depend on the mix of other options.

   If the ``--convert-kernel`` option is provided a single path to an
   RTEMS executable file is required. If this option is not provided
   the number of paths provided determine how they are processed.

   If a single path a built U-boot directory is provided the board
   configuration will automatically find and pick up the first and
   second stage boot loader executables.

   If two paths are provided they are paths to the first and second
   stage boot loader executables. This can be used with loader images
   they you have not built.

Examples
--------

The examples show the output for FreeBSD. It may vary depending on
your type of host, how it is configured and what is running.

If the board option is not provided a list of boards is displayed:

.. code-block:: none

  $ rtems-boot-image -o sd-card.img u-boot
  RTEMS Tools - Boot Image, 5.0.not_released
   Board list: bootloaders (1)
    u-boot: 2
     u-boot-beaglebone
     u-boot-zedboard

Create a disk image from a built U-Boot sandbox:

.. code-block:: none

  $ rtems-boot-image -o sd-card.img -b u-boot-beaglebone u-boot
  RTEMS Tools - Boot Image, 5.0.not_released
  Create image: sd-card.img size 64m
  Attach image to device: sd-card.img
  Password:
  Partition device: md0 as MBR
  Format: /dev/md0s1 as fat16
  Mount: /dev/md0s1
  Install: MLO
  Install: u-boot.img
  Finished
  Cleaning up

Create a 32M byte SD card image with the testsuite's hello world
executable (``hello.exe``):

.. code-block:: none

  $ rtems-boot-image -o sd-card.img -b u-boot-beaglebone -s 32m -k hello.exe u-boot
  RTEMS Tools - Boot Image, 5.0.not_released
  Create image: sd-card.img size 32m
  Attach image to device: sd-card.img
  Password:
  Partition device: md0 as MBR
  Format: /dev/md0s1 as fat16
  Mount: /dev/md0s1
  Install: MLO
  Install: u-boot.img
  Install: hello.exe.img
  Uenv template: uenv_exe
  Install: uEnv.txt
  Finished
  Cleaning up

Build the same image using the first and second stage boot loaders:

.. code-block:: none

  $ rtems-boot-image -o sd-card.img -b u-boot-beaglebone -s 32m -k hello.exe MLO u-boot.img
  RTEMS Tools - Boot Image, 5.0.not_released
  Create image: sd-card.img size 32m
  Attach image to device: sd-card.img
  Password:
  Partition device: md0 as MBR
  Format: /dev/md0s1 as fat16
  Mount: /dev/md0s1
  Install: MLO
  Install: u-boot.img
  Install: hello.exe.img
  Uenv template: uenv_exe
  Install: uEnv.txt
  Finished
  Cleaning up

Install and load the TI standard FDT for the Beaglebone Black board
with the LibBSD DHCP 01 test application:

.. code-block:: none

  $ rtems-boot-image -o sd-card.img -b u-boot-beaglebone -s 32m \
    -k dhcpcd01.exe -d am335x-boneblack.dtb MLO u-boot.img
  RTEMS Tools - Boot Image, 5.0.not_released
  Create image: sd-card.img size 32m
  Attach image to device: sd-card.img
  Password:
  Partition device: md0 as MBR
  Format: /dev/md0s1 as fat16
  Mount: /dev/md0s1
  Install: MLO
  Install: u-boot.img
  Install: dhcpcd01.exe.img
  Install: am335x-boneblack.dtb
  Uenv template: uenv_exe_fdt
  Install: uEnv.txt
  Finished
  Cleaning up

Create a DHCP network boot image where the TFTP client requests ``rtems.img``:

.. code-block:: none

  $ rtems-boot-image -o sd-card.img -b u-boot-beaglebone -s 32m \
    --net-boot-dhcp MLO u-boot.img
  RTEMS Tools - Boot Image, 5.0.not_released
  Create image: sd-card.img size 32m
  Attach image to device: sd-card.img
  Password:
  Partition device: md0 as MBR
  Format: /dev/md0s1 as fat16
  Mount: /dev/md0s1
  Install: MLO
  Install: u-boot.img
  Uenv template: uenv_net_dhcp
  Install: uEnv.txt
  Finished
  Cleaning up

Select a specific kernel image to load using TFTP and load a FDT blob
from the SD card:

.. code-block:: none

  $ rtems-boot-image -o sd-card.img -b u-boot-beaglebone -s 32m \
    --net-boot-dhcp --net-boot-file bbb1a.img \
    -d am335x-boneblack.dtb MLO u-boot.img
  RTEMS Tools - Boot Image, 5.0.not_released
  Create image: sd-card.img size 32m
  Attach image to device: sd-card.img
  Password:
  Partition device: md0 as MBR
  Format: /dev/md0s1 as fat16
  Mount: /dev/md0s1
  Install: MLO
  Install: u-boot.img
  Install: am335x-boneblack.dtb
  Uenv template: uenv_net_dhcp
  Install: uEnv.txt
  Finished
  Cleaning up

Create an image where a specific kernel image and FDT blob is loaded
using the TFTP protocol:

.. code-block:: none

  $ rtems-boot-image -o sd-card.img -b u-boot-beaglebone -s 32m \
    --net-boot-dhcp --net-boot-file bbb1a.img \
    --net-boot-fdt bbb/am335x-boneblack.dtb MLO u-boot.img
  RTEMS Tools - Boot Image, 5.0.not_released
  Create image: sd-card.img size 32m
  Attach image to device: sd-card.img
  Password:
  Partition device: md0 as MBR
  Format: /dev/md0s1 as fat16
  Mount: /dev/md0s1
  Install: MLO
  Install: u-boot.img
  Uenv template: uenv_net_dhcp_net_fdt
  Install: uEnv.txt
  Finished
  Cleaning up