1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 ================================== 3 ==================================
4 NVDIMM Runtime Firmware Activation 4 NVDIMM Runtime Firmware Activation
5 ================================== 5 ==================================
6 6
7 Some persistent memory devices run a firmware 7 Some persistent memory devices run a firmware locally on the device /
8 "DIMM" to perform tasks like media management, 8 "DIMM" to perform tasks like media management, capacity provisioning,
9 and health monitoring. The process of updating 9 and health monitoring. The process of updating that firmware typically
10 involves a reboot because it has implications 10 involves a reboot because it has implications for in-flight memory
11 transactions. However, reboots are disruptive 11 transactions. However, reboots are disruptive and at least the Intel
12 persistent memory platform implementation, des 12 persistent memory platform implementation, described by the Intel ACPI
13 DSM specification [1], has added support for a 13 DSM specification [1], has added support for activating firmware at
14 runtime. 14 runtime.
15 15
16 A native sysfs interface is implemented in lib 16 A native sysfs interface is implemented in libnvdimm to allow platform
17 to advertise and control their local runtime f 17 to advertise and control their local runtime firmware activation
18 capability. 18 capability.
19 19
20 The libnvdimm bus object, ndbusX, implements a 20 The libnvdimm bus object, ndbusX, implements an ndbusX/firmware/activate
21 attribute that shows the state of the firmware 21 attribute that shows the state of the firmware activation as one of 'idle',
22 'armed', 'overflow', and 'busy'. 22 'armed', 'overflow', and 'busy'.
23 23
24 - idle: 24 - idle:
25 No devices are set / armed to activate firmw 25 No devices are set / armed to activate firmware
26 26
27 - armed: 27 - armed:
28 At least one device is armed 28 At least one device is armed
29 29
30 - busy: 30 - busy:
31 In the busy state armed devices are in the p 31 In the busy state armed devices are in the process of transitioning
32 back to idle and completing an activation cy 32 back to idle and completing an activation cycle.
33 33
34 - overflow: 34 - overflow:
35 If the platform has a concept of incremental 35 If the platform has a concept of incremental work needed to perform
36 the activation it could be the case that too 36 the activation it could be the case that too many DIMMs are armed for
37 activation. In that scenario the potential f 37 activation. In that scenario the potential for firmware activation to
38 timeout is indicated by the 'overflow' state 38 timeout is indicated by the 'overflow' state.
39 39
40 The 'ndbusX/firmware/activate' property can be 40 The 'ndbusX/firmware/activate' property can be written with a value of
41 either 'live', or 'quiesce'. A value of 'quies 41 either 'live', or 'quiesce'. A value of 'quiesce' triggers the kernel to
42 run firmware activation from within the equiva 42 run firmware activation from within the equivalent of the hibernation
43 'freeze' state where drivers and applications 43 'freeze' state where drivers and applications are notified to stop their
44 modifications of system memory. A value of 'li 44 modifications of system memory. A value of 'live' attempts
45 firmware activation without this hibernation c 45 firmware activation without this hibernation cycle. The
46 'ndbusX/firmware/activate' property will be el 46 'ndbusX/firmware/activate' property will be elided completely if no
47 firmware activation capability is detected. 47 firmware activation capability is detected.
48 48
49 Another property 'ndbusX/firmware/capability' 49 Another property 'ndbusX/firmware/capability' indicates a value of
50 'live' or 'quiesce', where 'live' indicates th 50 'live' or 'quiesce', where 'live' indicates that the firmware
51 does not require or inflict any quiesce period 51 does not require or inflict any quiesce period on the system to update
52 firmware. A capability value of 'quiesce' indi 52 firmware. A capability value of 'quiesce' indicates that firmware does
53 expect and injects a quiet period for the memo 53 expect and injects a quiet period for the memory controller, but 'live'
54 may still be written to 'ndbusX/firmware/activ 54 may still be written to 'ndbusX/firmware/activate' as an override to
55 assume the risk of racing firmware update with 55 assume the risk of racing firmware update with in-flight device and
56 application activity. The 'ndbusX/firmware/cap 56 application activity. The 'ndbusX/firmware/capability' property will be
57 elided completely if no firmware activation ca 57 elided completely if no firmware activation capability is detected.
58 58
59 The libnvdimm memory-device / DIMM object, nme 59 The libnvdimm memory-device / DIMM object, nmemX, implements
60 'nmemX/firmware/activate' and 'nmemX/firmware/ 60 'nmemX/firmware/activate' and 'nmemX/firmware/result' attributes to
61 communicate the per-device firmware activation 61 communicate the per-device firmware activation state. Similar to the
62 'ndbusX/firmware/activate' attribute, the 'nme 62 'ndbusX/firmware/activate' attribute, the 'nmemX/firmware/activate'
63 attribute indicates 'idle', 'armed', or 'busy' 63 attribute indicates 'idle', 'armed', or 'busy'. The state transitions
64 from 'armed' to 'idle' when the system is prep 64 from 'armed' to 'idle' when the system is prepared to activate firmware,
65 firmware staged + state set to armed, and 'ndb 65 firmware staged + state set to armed, and 'ndbusX/firmware/activate' is
66 triggered. After that activation event the nme 66 triggered. After that activation event the nmemX/firmware/result
67 attribute reflects the state of the last activ 67 attribute reflects the state of the last activation as one of:
68 68
69 - none: 69 - none:
70 No runtime activation triggered since the la 70 No runtime activation triggered since the last time the device was reset
71 71
72 - success: 72 - success:
73 The last runtime activation completed succes 73 The last runtime activation completed successfully.
74 74
75 - fail: 75 - fail:
76 The last runtime activation failed for devic 76 The last runtime activation failed for device-specific reasons.
77 77
78 - not_staged: 78 - not_staged:
79 The last runtime activation failed due to a 79 The last runtime activation failed due to a sequencing error of the
80 firmware image not being staged. 80 firmware image not being staged.
81 81
82 - need_reset: 82 - need_reset:
83 Runtime firmware activation failed, but the 83 Runtime firmware activation failed, but the firmware can still be
84 activated via the legacy method of power-cyc 84 activated via the legacy method of power-cycling the system.
85 85
86 [1]: https://docs.pmem.io/persistent-memory/ 86 [1]: https://docs.pmem.io/persistent-memory/
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.