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