-
Notifications
You must be signed in to change notification settings - Fork 5
/
Copy pathmlxbf-bootctl.8
135 lines (132 loc) · 4.74 KB
/
mlxbf-bootctl.8
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
.TH MLXBF\-BOOTCTL 8 "September 3, 2020" "version 2.1" "System Administration"
.SH NAME
mlxbf-bootctl \- control Mellanox BlueField boot partitions
.SH SYNOPSIS
.B mlxbf\-bootctl
[\-h|\-\-help] [options]
.SH DESCRIPTION
.B mlxbf-bootctl
is used to control the two boot firmware partitions present on most Mellanox
BlueField devices.
.SS Boot Partitions
Most Bluefield devices obtain their boot firmware (ATF, UEFI, etc) from an
on-board Embedded Multi-Media Card (eMMC). The eMMC has two partitions that
are treated separately from the others: boot0 and boot1, one of which acts as
the primary, the other acting as a backup. In addition, there is a watchdog
timer present on the chip, which when activated, will automatically swap
which boot partition is active if it is not deactivated in time. These two
features, taken together, allow for safe BlueField firmware upgrades that may
rolled back in case of failure.
.B mlxbf-bootctl
controls these features.
If
.B mlxbf-bootctl
is run without options, it will print the current state of the boot partitions.
.SH OPTIONS
.TP
.B
\-\-device|\-d MMCFILE
Use a device other than the default
.I /dev/mmcblk0
.TP
.B
\-\-bootstream|\-b BFBFILE
Write the specified bootstream to the alternate partition of the device. This
queries the base device (e.g.
.I
/dev/mmcblk0
) for the alternate partition, and
uses that information to open the appropriate boot partition device, e.g. the
.I
/dev/mmcblk0boot0
file. BFB files that can be installed in the boot partitions are typically
named "default.bfb" in BlueField software distributions.
.TP
.B
\-\-overwrite\-current
Used with "\-\-bootstream" to overwrite the current boot partition instead of
the alternate one. This is not recommended as there is no easy way to recover
if the new boot code does not bring the system up.
.TP
.B
\-\-output|\-o OUTPUT
Used with "\-\-bootstream" to specify a file to write the boot partition data
to (creating it if necessary), rather than using an existing master device and
deriving the boot partition device.
.TP
.B
\-\-read|\-r INPUT
Read a bootstream and convert it back to a BFBFILE specified by
"\-\-bootstream". For example use
.RS 11
.B mlxbf-bootctl
\-\-read /dev/mmcblk0boot0
.sp 0
\-\-bootstream current.bfb
.RE
.IP
to read the current bfb installed on boot partition zero.
.TP
.B
\-\-watchdog\-swap SECONDS
Arrange to start the ARM watchdog with a countdown of the specified number of
seconds until it firms; also, set the boot software so that it will swap the
primary and alternate partitions at the next reset. Mutually exclusive with
"\-\-nowatchdog\-swap".
.TP
.B
\-\-nowatchdog-swap
Ensure that after the next reset, no watchdog will be started, and no swapping
of boot partitions will happen.
.TP
.B
\-\-watchdog-boot-mode MODE
Set the watchdog boot mode. This will take effect
on the next boot and start the watchdog with a countdown interval set
by --watchdog-boot-interval or a default value if no interval is set.
This setting will be overridden for the first boot if the watchdog is
being used for boot swap (--watchdog-swap). Boot modes are: disabled,
standard, and time_limit. In disabled mode the watchdog will not be
started on the next boot unless it is used for boot swap. In standard mode
the watchdog will be started on next boot and will be refreshed automatically
during boot (used to recover from hangs). In time_limit mode the watchdog
will be started on next boot, but never refreshed until boot finishes
(used to enforce total boot time).
.TP
.B
\-\-watchdog-boot-interval SECONDS
Set the watchdog interval that will be used when
starting the watchdog on the next boot (configured with --watchdog-swap or
--watchdog--boot-mode). This is also known as the watchdog countdown or
timeout value given in seconds.
.TP
.B
\-\-swap|\-s
Set the boot software so that will swap the primary and alternate partitions
at the next reset.
.TP
.B
\-\-version|\-v
Override automatic image version filtering. By default, when
.B \-v
is not specifed, image versions contained in the bootstream will not be
installed to the boot partition if they are incompatible with the current
BlueField platform.
.B \-v
allows you to manually specify the target version. Version 0 corresponds to BF-1,
version 1 to BF-2, and so on. Version -1, or any version less than zero,
will turn off image filtering entirely.
.SH EXAMPLES
To update to new firmware as safely as possible:
.IP
.B mlxbf-bootctl
\-\-bootstream new.bfb \-\-watchdog\-swap 90
.PP
Once the new firmware is confirmed to be good, turn off watchdog swapping with
.IP
.B mlxbf-bootctl
\-\-nowatchdog-swap
.SH COMMON ISSUES
When the watchdog timer is activated through the "\-\-watchdog\-swap" option,
entering the UEFI menu for long enough will trigger a reboot and partition
swap. To avoid this, run "\-\-nowatchdog\-swap" before entering the UEFI menu.