Documentation/driver-api/nvdimm/firmware-activate.rst

   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/