1.\"	$NetBSD: mkubootimage.1,v 1.20 2024/05/22 00:02:46 uwe Exp $
2.\"
3.\" Copyright (c) 2012 The NetBSD Foundation, Inc.
4.\" All rights reserved.
5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Jeremy C. Reed
8.\"
9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions
11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright
13.\"    notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\"    notice, this list of conditions and the following disclaimer in the
16.\"    documentation and/or other materials provided with the distribution.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28.\" POSSIBILITY OF SUCH DAMAGE.
29.\"
30.Dd May 21, 2024
31.Dt MKUBOOTIMAGE 1
32.Os
33.Sh NAME
34.Nm mkubootimage
35.Nd create U-Boot loader image
36.Sh SYNOPSIS
37.Nm
38.
39.Op Fl hu
40.
41.Fl A Po Xo
42.Li arm     Ns \||\| Ns
43.Li arm64   Ns \||\| Ns
44.Li i386    Ns \||\| Ns
45.Li mips    Ns \||\| Ns
46.Li mips64  Ns \||\| Ns
47.Li or1k    Ns \||\| Ns
48.Li powerpc Ns \||\| Ns
49.Li riscv   Ns \||\| Ns
50.Li sh
51.Xc Pc
52.
53.br
54.Fl a Ar address
55.
56.Oo Fl C Po Xo
57.Li bz2  Ns \||\| Ns
58.Li gz   Ns \||\| Ns
59.Li lzma Ns \||\| Ns
60.Li lzo  Ns \||\| Ns
61.Li none
62.Xc Pc Oc
63.
64.Op Fl E Ar address
65.
66.Op Fl e Ar address
67.
68.Oo Fl f Po Xo
69.Li arm64 Ns \||\| Ns
70.Li uimg
71.Xc Pc Oc
72.
73.Op Fl m Ar magic
74.
75.Fl n Ar name
76.
77.br
78.Oo Fl O Po Xo
79.Li freebsd Ns \||\| Ns
80.Li linux   Ns \||\| Ns
81.Li netbsd  Ns \||\| Ns
82.Li openbsd
83.Xc Pc Oc
84.
85.br
86.Fl T Po Xo
87.Li fs            Ns \||\| Ns
88.Li kernel        Ns \||\| Ns
89.Li kernel_noload Ns \||\| Ns
90.Li ramdisk       Ns \||\| Ns
91.Li script        Ns \||\| Ns
92.Li standalone
93.Xc Pc
94.
95.Op Fl t Ar epoch
96.
97.Ar source destination
98.\"
99.Sh DESCRIPTION
100The
101.Nm
102utility is used to create an image for Das U-Boot, the
103.Qq Universal Boot Loader .
104.Pp
105The arguments are as follows:
106.Bl -tag -width Fl
107.
108.It Fl A Po Xo
109.Li arm     Ns \||\| Ns
110.Li arm64   Ns \||\| Ns
111.Li i386    Ns \||\| Ns
112.Li mips    Ns \||\| Ns
113.Li mips64  Ns \||\| Ns
114.Li or1k    Ns \||\| Ns
115.Li powerpc Ns \||\| Ns
116.Li riscv   Ns \||\| Ns
117.Li sh
118.Xc Pc
119Defines the architecture.
120This is required for
121.Ql uimg
122format images.
123.
124.It Fl a Ar address
125Sets the image load address.
126This is an integer between 0 and
127.Dv UINT32_MAX .
128This is required for all
129.Ql uimg
130image types except for
131.Li script , ramdisk ,
132and
133.Li kernel_noload .
134.
135.It Fl C Po Xo
136.Li bz2  Ns \||\| Ns
137.Li gz   Ns \||\| Ns
138.Li lzma Ns \||\| Ns
139.Li lzo  Ns \||\| Ns
140.Li none
141.Xc Pc
142Defines the compression.
143The default is
144.Ql none .
145.
146.It Fl E Ar address
147Define the entry point.
148This is an integer between 0 and
149.Dv UINT32_MAX .
150This option is the same as
151.Fl e
152but it inverts the bytes to convert the 32 bit integer
153from little to big endian (or vice versa).
154If
155.Fl E
156or
157.Fl e
158are not set, the entry point defaults to the
159image load address
160.Pq Fl a .
161.
162.It Fl e Ar address
163Define the entry point.
164This is an integer between 0 and
165.Dv UINT32_MAX .
166If
167.Fl E
168or
169.Fl e
170are not set, the entry point defaults to the
171image load address
172.Pq Fl a .
173.
174.It Fl f Po Xo
175.Li arm64 Ns \||\| Ns
176.Li uimg
177.Xc Pc
178Defines the output image format type.
179The default is
180.Ql uimg .
181.
182.It Fl h
183Display the usage and exit.
184.
185.It Fl m Ar magic
186Set the magic used for
187.Ql uimg
188format images.
189This is an integer between 0 and
190.Dv UINT32_MAX .
191The default is
192.Ql 0x27051956 .
193.
194.It Fl n Ar name
195Defines the image name.
196This is required.
197.
198.It Fl O Po Xo
199.Li freebsd Ns \||\| Ns
200.Li linux   Ns \||\| Ns
201.Li netbsd  Ns \||\| Ns
202.Li openbsd
203.Xc Pc
204Defines the operating system type.
205The default OS name is
206.Ql netbsd .
207.
208.It Fl T Po Xo
209.Li fs            Ns \||\| Ns
210.Li kernel        Ns \||\| Ns
211.Li kernel_noload Ns \||\| Ns
212.Li ramdisk       Ns \||\| Ns
213.Li script        Ns \||\| Ns
214.Li standalone
215.Xc Pc
216Defines the image type.
217This is required for
218.Ql uimg
219format images.
220.
221.It Fl t Ar epoch
222Use given epoch timestamp as image creation time.
223.Pq This is only used for legacy U-Boot images.
224.
225.It Fl u
226Update the header in an existing file instead of creating a new one.
227.
228.El
229.Pp
230The required
231.Ar source
232argument is the filename of the kernel that is read.
233The required
234.Ar destination
235argument is the filename of the image file that is created.
236.\"
237.Sh EXIT STATUS
238.Nm
239returns 1 on failure to read the kernel,
240generate a header, or create the image.
241.\"
242.Sh EXAMPLES
243Before the image is written, the header is displayed to standard out;
244for example:
245.Bd -literal -offset indent
246 image type:  uimg
247 magic:       0x27051956
248 time:        Tue May 21 18:05:09 2024
249 size:        137
250 load addr:   0x00000000
251 entry point: 0x00000000
252 data crc:    0xface05f2
253 os:          2 (netbsd)
254 arch:        2 (arm)
255 type:        6 (script)
256 comp:        0 (none)
257 name:        NetBSD/armv7 boot
258 header crc:  0x2164b567
259.Ed
260.\" .Sh FILES
261.Sh SEE ALSO
262.Rs
263.%T Das U-Boot \(en the Universal Boot Loader
264.%U http://www.denx.de/wiki/U-Boot/
265.Re
266.\"
267.\" .Sh STANDARDS
268.\"
269.Sh HISTORY
270The
271.Nm
272command first appeared in
273.Nx 6.0 .
274.\"
275.Sh AUTHORS
276.An -nosplit
277The
278.Nm
279utility was originally written by
280.An Jared McNeill .
281This manual page was written by
282.An Jeremy C. Reed .
283.\" .Sh CAVEATS
284.\" .Sh BUGS
285.\" .Sh SECURITY CONSIDERATIONS
286