1NDCTL-ACTIVATE-FIR(1)            ndctl Manual            NDCTL-ACTIVATE-FIR(1)
2
3
4

NAME

6       ndctl-activate-firmware - activate staged firmware on memory devices
7

SYNOPSIS

9       ndctl activate-firmware [<bus-id> <bus-id2> ... <bus-idN>] [<options>]
10
11       Some persistent memory devices run a firmware locally on the device /
12       "DIMM" to perform tasks like media management, capacity provisioning,
13       and health monitoring. The process of updating that firmware typically
14       involves a reboot because it has implications for in-flight memory
15       transactions. However, reboots can be costly for systems that can not
16       tolerate extended downtime.
17
18       The kernel detects platforms that expose support for
19       runtime-firmware-activation (FWA). The ndctl update-firmware stages new
20       firmware binaries, but if the platform supports FWA it will
21       additionally arm the devices for activation. Then ndctl
22       activate-firmware may attempt to activate the firmware live. However,
23       if the platform indicates that the memory controller will be taken
24       off-line for the duration of the update "activate_method == suspend"
25       then the default policy for firmware activation is to inject a
26       truncated hibernate cycle to freeze devices and applications before the
27       hard quiesce is injected by the platform, and then resume the system.
28
29       DANGER the activate-firmware command includes a --force option to tell
30       the driver bypass the hibernation cycle and perform the update "live".
31       I.e. it arranges for applications and devices to race the platform
32       injected quiesce period. This option should only be used explicit
33       knowledge that the platform quiesce time will not trigger completion
34       timeout violations for any devices in the system.
35

EXAMPLES

37       Check for any buses that support activation without triggering an
38       activation:
39
40
41           .ft C
42           # ndctl activate-firmware all --dry-run
43           ACPI.NFIT: ndbus1: has no devices that support firmware update.
44           nfit_test.1: ndbus3: has no devices that support firmware update.
45           e820: ndbus0: has no devices that support firmware update.
46           [
47             {
48               "provider":"nfit_test.0",
49               "dev":"ndbus1",
50               "scrub_state":"idle",
51               "firmware":{
52                 "activate_method":"suspend",
53                 "activate_state":"idle"
54               },
55               "dimms":[
56                 {
57           ...
58           .ft
59
60
61       Check that a specific bus supports activation without performing an
62       activation:
63
64
65           .ft C
66           # ndctl activate-firmware nfit_test.0 --dry-run --force
67           [
68             {
69               "provider":"nfit_test.0",
70               "dev":"ndbus2",
71               "scrub_state":"idle",
72               "firmware":{
73                 "activate_method":"suspend",
74                 "activate_state":"idle"
75               },
76               "dimms":[
77           ...
78           ]
79           .ft
80
81
82       The result is equivalent to ndctl list -BFDu upon successful
83       activation.
84
85       The ndctl list command can also enumerate the default activation
86       method:
87
88
89           .ft C
90           # ndctl list -b nfit_test.0 -BF
91           [
92             {
93               "provider":"nfit_test.0",
94               "dev":"ndbus2",
95               "scrub_state":"idle",
96               "firmware":{
97                 "activate_method":"suspend",
98                 "activate_state":"idle"
99               }
100             }
101           ]
102           .ft
103
104

OPTIONS

106       -n, --dry-run
107           Perform all actions related to activation including honoring --idle
108           and --force, but skip the final execution of the activation. The
109           overrides are undone before the command completes. Any failed
110           overrides will be reported as error messages.
111
112       -I, --idle
113           Implied by default, this option controls whether the platform will
114           attempt to increase the completion timeout of all devices in the
115           system and validate that the max completion timeout satisfies the
116           time needed to perform the activation. This validation step can be
117           overridden by specifying --no-idle.
118
119       -f, --force
120           The activation method defaults to the reported
121           "bus.firmware.activate_method" property. When the method is "live"
122           then this --force option is ignored. When the method is "reset" no
123           runtime activation is attempted. When the method is "suspend" this
124           option indicates to the driver to bypass the hibernate cycle to
125           activate firmware. in the bus When the reported "activate_method"
126           is "suspend" the kernel driver may support overriding the suspend
127           requirement and instead issue the firmware-activation live.
128           CAUTION this may lead to undefined system behavior if device
129           completion timeouts are violated for in-flight memory operations.
130
131       -v, --verbose
132           Emit debug messages for the firmware activation procedure
133
135       Copyright © 2016 - 2020, Intel Corporation. License GPLv2: GNU GPL
136       version 2 http://gnu.org/licenses/gpl.html. This is free software: you
137       are free to change and redistribute it. There is NO WARRANTY, to the
138       extent permitted by law.
139

SEE ALSO

141       ndctl-update-firmware(1), Intel Optane PMem DSM Interface[1]
142

NOTES

144        1. Intel Optane PMem DSM Interface
145           https://pmem.io/documents/IntelOptanePMem_DSM_Interface-V2.0.pdf
146
147
148
149ndctl 71.1                        01/26/2021             NDCTL-ACTIVATE-FIR(1)
Impressum