System State Framework (SSF)

Introduction

This document describes an extensible design for tracking and publishing the system state for NG800 and OEM products derived from NG800.

The system state is a string variable that reflects the run-level of the overall system (off, booting, starting, up, shutdown-pending, shutting-down, powering-down). This value is published to user applications via the sysfs (file system).

At the core of the design a state machine tracks the system state and processes multiple inputs such as the ignition signal. Before shutting down Linux because of a de-asserted ignition signal, the state machine grants user-space application time to properly shut down. User applications can prolong the shutdown timer if they need more time to terminate. If the timer elapses, the state machine instructs the kernel to shut down.

File System Entries

All the entries are available under the directory /sys/kernel/broker:

  • ignition

    • status of the ignition signal

      • 1 = asserted
      • 0 = de-asserted

  • system-state

    • state of the system

      • starting –> operating system, applications, etc are starting up
      • up –> system start-up finished, i.e. fully booted, up and running
      • shutdown-pending –> system was told to shut down by giving applications time to terminate, see also shutdown-delay
      • shutting-down –> shut down in progress

  • system-state-target

    • interface to “command” the SSF, i.e. the following parts can be written in it:

      • up –> –> triggers the SSF for being up (transition from starting to up)
      • reboot –> triggers an immediate reboot
      • powerdown –> triggers an immediate power-off

  • shutdown-delay [seconds]

    • set or read the default shutdown-delay
    • this value is initialized in the device-tree

  • extend-shutdown-delay [seconds]

    • delay the shutdown to have more time to terminate applications

  • remaining-shutdown-delay [seconds]

    • countdown with the remaining time until the device shuts down

  • start-reason

    • information about the reason for the start-up

      • power –> ignition and power are both attached to the device
      • reboot –> device is rebooting (reboot command, ignition signal or RTC alarm during shut down process)
      • wakeup;ignition –> the device was ignited at a power down (power supply still attached)
      • wakeup;rtc-alarm –> the device woke up by an RTC alarm (power supply still attached)

Device Tree Entries

At the moment there are only two relevant options to set in the device-tree. The rest of the device tree entries should be left as is or the device may not function properly.

  • default-shutdown-delay-s

    • the default shutdown-delay when no extending of the shutdown-delay is requested.
    • sets the value of shutdown-delay on startup.

  • max-shutdown-delay-s

    • sets the maximum time of the shutdown-delay. This is used to make sure the shutdown delay can’t be extended forever.

Pending Shutdown

When the ignition signal is de-asserted the system-state shows shutdown-pending for the time located in the file remaining-shutdown-delay. Re-asserting the ignition signal during this time the system-state changes back to up.

Prolonging a pending shutdown is described in the next section.

Extending a Shutdown

As mentioned above the shut down can be delayed to have time to terminate applications properly. The following example shows about how to use it:

Example: Let’s assume the default shutdown is 60s and after 30s we notice that we need to delay it for 75s. Perform the following command:

echo "75" > /sys/kernel/broker/extend-shutdown-delay

With this command the shutdown countdown starts again from 75s.

Note

The maximum total delay is configured in the device-tree or is 300s by default.

RTC wake-up

The SSF provides a start reason to differentiate between RTC wake-up and ignition signal. To set up an RTC wake-up you can just use the linux command rtcwake.

Example: If I want to wake-up my device after 90s from now and in the meantime it shall be powered off, I can call this:

rtcwake -s 90 -m off

The start reason read from start-reason is wakeup;rtc-alarm.

Device is Shutting down

The system is rebooting if during the shutting down process the following events are given:

  • re-assertion of the ignition signal
  • wake-up event of an RTC alarm
  • reboot commanded

Powering the Device Off

The system is powering off on the following events:

  • poweroff commanded
  • RTC alarm set up with mode to power off
  • de-assertion of the ignition signal