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