Orange Pi5 kernel

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