Host State Module

Overview & Purpose

The Host State subsystem in tlBMC is responsible for monitoring, reporting, and actuating the physical power state (PowerState) and operating system execution state (OSState) of the host machine.

When integrated into a platform, this module acts as the authoritative source for host power transitions and drives Redfish chassis power status and ComputerSystem reset actions (such as PowerOn, ForceOff, GracefulShutdown, and GracefulRestart). It provides a flexible architecture supporting direct hardware actuation via GPIO pins as well as seamless software integration via Linux inotify file watching for platforms utilizing external power control agents.

Abstract `PowerControl` Interface

At the core of the host state management architecture is the abstract PowerControl interface defined in power_control.h. This interface establishes a unified contract for querying power status, executing reset actions, and subscribing to state transition events.

Key Control Methods

SystemResetRequest(ResetType reset_type, absl::Duration delay): Maps high-level Redfish actions to specific hardware/software actuation sequences based on the requested ResetType:
- RESET_TYPE_ON / FORCE_ON $\rightarrow$ PowerOnRequest()
- RESET_TYPE_FORCE_OFF $\rightarrow$ PowerOffRequest()
- RESET_TYPE_POWER_CYCLE $\rightarrow$ PowerCycleRequest()
- RESET_TYPE_FORCE_RESTART $\rightarrow$ ResetRequest()
- RESET_TYPE_GRACEFUL_SHUTDOWN $\rightarrow$ GracefulPowerOffRequest()
- RESET_TYPE_GRACEFUL_RESTART $\rightarrow$ GracefulPowerCycleRequest()
GetHostState(): Returns the complete current HostState protobuf containing the host identifier, current PowerState, and current OSState.

Event Subscription Methods

Subsystems and external services can register thread-safe callbacks triggered during critical host transitions:

RegisterHostPowerOnToOffCallback: Invoked when the chassis transitions from powered-on to off.
RegisterHostPowerOffToOnCallback: Invoked when the chassis asserts power-ok and transitions from off to powered-on.
RegisterHostOSInactiveToStandbyCallback: Invoked when host POST completes successfully.
RegisterHostOSStandbyToInactiveCallback: Invoked when OS execution halts or resets.

Hardware Actuation Mode (`PowerControlGpio`)

The PowerControlGpio implementation (power_control.cc) interacts directly with physical board logic to govern host state transitions and actuate hardware signals.

State Machine Transitions

PowerControlGpio maintains an active internal state machine representing the chassis state:

POWER_STATE_ON: Physical power is established and verified.
POWER_STATE_WAIT_FOR_POWER_OK: Power-on initiated; awaiting board assertion of physical power good.
POWER_STATE_OFF: System is fully powered down.
POWER_STATE_TRANSITION_TO_OFF: Actively asserting force-off pulse.
POWER_STATE_GRACEFUL_TRANSITION_TO_OFF: Actively awaiting graceful ACPI shutdown.
POWER_STATE_CYCLE_OFF: Intermediate off state during a power cycle before re-initiating power-on.
POWER_STATE_TRANSITION_TO_CYCLE_OFF: Initiating hard cycle shutdown.
POWER_STATE_GRACEFUL_TRANSITION_TO_CYCLE_OFF: Awaiting ACPI graceful shutdown prior to power cycle.
POWER_STATE_CHECK_FOR_WARM_RESET: POST complete deasserted; verifying if host triggered a warm reset rather than full shutdown.

GPIO Actuation & Monitoring

Output Control Pins: Actuates hardware lines via precise time-duration pulses using GpioCollector::SetActiveForDuration:
- power_out_gpio_name: Asserted to trigger power button presses (PowerPulseMs for standard toggle, ForceOffPulseMs for hard power cut).
- reset_out_gpio_name: Asserted to trigger warm hardware reset (ResetPulseMs).
Input Sensing Handlers: Subscribes to hardware line status shifts:
- PowerOkHandler: Monitors power_ok_gpio_name. Rising edges transition the host to POWER_STATE_ON. Falling edges trigger power-loss callbacks and drop state to POWER_STATE_OFF or POWER_STATE_CYCLE_OFF.
- PostCompleteHandler: Monitors post_complete_gpio_name. Rising edges set OS execution to OS_STATE_STANDBY. Falling edges transition OS execution to OS_STATE_INACTIVE and activate warm reset verification.

Watchdog & Steady Timers

The hardware controller utilizes asynchronous boost::asio::steady_timer instances managed by PowerControlThreadManager:

PowerCycleTimer (PowerCycleMs = 5000ms): Enforces a steady off-duration delay before re-enabling power during a reboot cycle.
PowerOKWatchdogTimer (PowerOKWatchdogMs = 8000ms): Fires when power-on is requested. If power_ok_gpio_name fails to assert before expiration, aborts and resets state to POWER_STATE_OFF.
GracefulPowerOffTimer (GracefulPowerOffS = 300s): Sets a maximum timeout window for OS-cooperative ACPI shutdowns.
WarmResetCheckTimer (WarmResetCheckMs = 500ms): Distinguishes between intentional host reboot events and system crashes upon POST drop.

File/inotify Integration Mode (`PowerControlInotify`)

For platforms where host power state is managed by external daemons or openbmc legacy layers, PowerControlInotify (host_state_collector.cc) operates as a zero-hardware integration bridge.

Linux `inotify` Monitoring

Instead of polling or reading GPIO lines, PowerControlInotify establishes non-blocking file descriptors using inotify_init1 and attaches IN_CLOSE_WRITE watches directly to status JSON files (host_power_file_path and os_state_file_path). Asynchronous reads are dispatched over boost::asio::posix::stream_descriptor.

D-Bus OpenBMC State Parsing

Upon detection of an IN_CLOSE_WRITE event, the module parses the file payload as JSON and evaluates canonical D-Bus state strings:

Power State (PowerState):
- xyz.openbmc_project.State.Chassis.PowerState.On $\rightarrow$ HOST_POWER_STATE_ON
- xyz.openbmc_project.State.Chassis.PowerState.Off $\rightarrow$ HOST_POWER_STATE_OFF
OS Status (OperatingSystemState):
- xyz.openbmc_project.State.OperatingSystem.Status.OSStatus.Standby $\rightarrow$ OS_STATE_STANDBY
- xyz.openbmc_project.State.OperatingSystem.Status.OSStatus.Inactive $\rightarrow$ OS_STATE_INACTIVE

Transitions automatically fire registered callback collections (host_power_on_to_off_callbacks_, etc.).

Robust Initialization Retries

If target synchronization files do not exist during early boot, the module utilizes TaskScheduler::ScheduleOneShotAsync to execute configurable exponential retries (default 5 attempts, 10-second intervals) until the integration path establishes.

Protobuf Schema Reference

The primary configurations governing host state collection and actuation reside within power_control.proto.

`PowerControlConfig` Schema Table

Field Name	Type	Default	Description
`host_id`	`string`	empty	Unique identifier for the target host instance (e.g., `"system"`).
`chassis_id`	`string`	empty	Target chassis physical identifier (e.g., `"chassis_1"`).
`power_ok_gpio_name`	`string`	empty	Input GPIO line name detecting physical host power assertion.
`post_complete_gpio_name`	`string`	empty	Input GPIO line name detecting operating system POST readiness.
`power_out_gpio_name`	`string`	empty	Output GPIO pin line triggering power button actuation.
`reset_out_gpio_name`	`string`	empty	Output GPIO pin line triggering hardware warm reset actuation.
`timer_map`	`map<string, uint32>`	standard defaults	Custom override durations for pulse widths and watchdogs in milliseconds.
`host_power_file_path`	`string`	`"/var/lib/power-control/state.json"`	Target file path monitored via `inotify` for physical power changes.
`os_state_file_path`	`string`	`"/var/lib/power-control/os-state.json"`	Target file path monitored via `inotify` for OS state transitions.
`host_power_related_state_config`	`RelatedStateConfig`	none	Mapping linking physical power status to downstream Redfish resource dependencies.
`os_state_related_state_config`	`RelatedStateConfig`	none	Mapping linking OS execution status to processor and memory resource active visibility.

Platform Configuration Examples

Platform integrators activate and tailor host state handling by supplying an explicit power_control_configs.textproto bundle loaded automatically by ProtoConfigParser.

Example 1: Direct Hardware GPIO Mode

# proto-file: third_party/milotic/external/cc/tlbmc/configs/power_control.proto
# proto-message: PowerControlConfigs

hotswap_pin_name: "FM_HOTSWAP_PWR_CYCLE_R"

power_control_configs {
  host_id: "system1"
  chassis_id: "chassis_1"
  power_ok_gpio_name: "PWRGD_CPU0_PLD"
  post_complete_gpio_name: "POST_DONE"
  power_out_gpio_name: "PWR_BTN_N"
  reset_out_gpio_name: "RESET_BTN_N"
  timer_map: { key: "ForceOffPulseMs" value: 5000 }
  timer_map: { key: "GracefulPowerOffS" value: 300 }
  timer_map: { key: "PowerCycleMs" value: 5000 }
  timer_map: { key: "PowerOKWatchdogMs" value: 8000 }
  timer_map: { key: "PowerPulseMs" value: 1000 }
  timer_map: { key: "ResetPulseMs" value: 100 }
}

Example 2: File-Based `inotify` Bridge Mode

# proto-file: third_party/milotic/external/cc/tlbmc/configs/power_control.proto
# proto-message: PowerControlConfigs

power_control_configs {
  host_id: "system"
  chassis_id: "chassis_main"

  host_power_file_path: "/var/lib/power-control/state.json"
  os_state_file_path: "/var/lib/power-control/os-state.json"

  host_power_related_state_config {
    host_id: "system"
    resource_identifiers: "/phys/M2_0"
    related_state: RELATED_STATE_HOST_POWER
    expected_uptime { seconds: 30 }
  }

  os_state_related_state_config {
    host_id: "system"
    resource_identifiers: "/phys/CPU0"
    resource_identifiers: "/phys/DIMM0"
    related_state: RELATED_STATE_OS_STATE
  }
}

Code References

Main Interfaces:
- power_control.h
- host_state_collector.h
Primary Implementations:
- power_control.cc
- host_state_collector.cc
Configuration & Schemas:
- power_control.proto
- proto_config_parser.cc