# openbmc/phosphor-state-manager architecture

> Architecture diagram of the GitHub repository openbmc/phosphor-state-manager, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openbmc/phosphor-state-manager
- Repository: https://github.com/openbmc/phosphor-state-manager

## Overview

##### Project Type and Purpose
- This is a system‐level daemon suite for OpenBMC called “phosphor-state-manager” (PSM). It is **not** a web app or microservices platform but a collection of C++ daemons that track and control hardware/OS states (BMC, chassis, host, hypervisor). It integrates tightly with systemd and D-Bus, exposes state via D-Bus interfaces, and provides a CLI tool (`obmcutil`) for debugging.

##### File‐Structure Analysis
Top‐level
- C++ source files (`*.cpp`, `*.hpp`) and Meson build files (`meson.build`, `meson.options`)
- `obmcutil` CLI binary source
- Service/target unit definitions under `service_files/` and `target_files/`
- Configuration and defaults in `data/`
- Helper scripts in `scripts/`
Subcomponents
- One state manager per object: `bmc_state_manager`, `chassis_state_manager`, `host_state_manager`, `hypervisor_state_manager`, plus auxiliary daemons like `discover_system_state`, `scheduled_host_transition`, `host_condition_gpio`
- Systemd abstractions: service parser, target parser/signals
- Tests under `test/`
- Third‐party libs in `subprojects/`

##### Key Architectural Insights from README
- PSM uses **systemd targets** as triggers: targets represent power‐on/off workflows.
- Each state manager monitors specific targets, updates its D-Bus property when targets transition.
- Restore policies and conditional boot‐when‐BMC‐ready are implemented by PSM code coordinating systemd.
- D-Bus is the control API; external interfaces (Redfish, IPMI) sit above D-Bus.
- CLI tool (`obmcutil`) calls into these same D-Bus interfaces.
- Hardware interactions: chassis “pgood” sensor, host via GPIO or host controller commands.

- Hardware Layer
– Chassis Power Supply & Sensors (pgood)
– Host Board (OS, “host on” signal)
- systemd Orchestration Layer
– Service Units (`phosphor-*` services)
– Target Units (`obmc-chassis-poweron@.target`, `obmc-host-start@.target`, etc.)
- phosphor‐state‐manager Daemons
– bmc_state_manager
– chassis_state_manager
– host_state_manager
– hypervisor_state_manager
– discover_system_state, scheduled_host_transition, host_condition_gpio
- D‐Bus IPC Layer
– `xyz.openbmc_project.State.*` interfaces
– RestorePolicy interface
- Control & External Interfaces
– obmcutil CLI
– Redfish/IPMI adapter daemons (outside repo)

1. On boot, systemd fires default.target → PSM daemons register for target‐complete signals
2. Target completion → DBus signals → PSM updates D-Bus state properties
3. PSM receiving a state‐request (via D-Bus) → invokes systemd StartUnit on corresponding target
4. systemd starts service units → they perform hardware actions (turn on PSU, manipulate GPIO)
5. Hardware feedback (pgood, GPIO read) → discover_system_state or host_condition_gpio → signals back via D-Bus
6. obmcutil ↔ D-Bus → queries or requests state transitions

c. Architectural Patterns & Principles
- **Event-driven**: systemd events drive state transitions
- **Separation of concerns**: one daemon per managed object
- **Minimal code**: use systemd targets for orchestration, keep PSM logic lean
- **Discover, don’t cache**: read true hardware state at run time

d. Key Technologies & Frameworks
- C++17, Meson/Ninja build
- sdbusplus / phosphor‐dbus‐interfaces
- systemd (units, targets)
- JSON for default configurations (`data/*.json`)
- GoogleTest for unit tests

##### Essential Elements to Capture
- Per‐object daemons and their monitored targets
- systemd’s role as workflow engine
- D-Bus interface layer and external API consumers
- Hardware feedback loops (pgood, GPIO)
- Config/data inputs (JSON defaults, meson options)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients Layer
    subgraph "External Interfaces"
        direction TB
        OBMCUTIL["obmcutil CLI"]:::external
        REDFISH["Redfish/IPMI Adapter"]:::external
    end

    %% D-Bus Layer
    DBUS["D-Bus IPC Layer"]:::dbus

    OBMCUTIL -->|Queries/Requests| DBUS
    REDFISH -->|Queries/Requests| DBUS

    %% PSM Daemons Layer
    subgraph "phosphor-state-manager Daemons"
        direction TB
        BMC["bmc_state_manager"]:::daemon
        CHASSIS["chassis_state_manager"]:::daemon
        HOST["host_state_manager"]:::daemon
        HYPERVISOR["hypervisor_state_manager"]:::daemon
        DISCOVER["discover_system_state"]:::daemon
        SCHEDULED["scheduled_host_transition"]:::daemon
        GPIO["host_condition_gpio"]:::daemon
    end

    DBUS -->|Signals & PropertiesChanged| BMC
    DBUS -->|Signals & PropertiesChanged| CHASSIS
    DBUS -->|Signals & PropertiesChanged| HOST
    DBUS -->|Signals & PropertiesChanged| HYPERVISOR
    DBUS -->|Invoke| DISCOVER
    DBUS -->|Invoke| SCHEDULED
    DBUS -->|Invoke| GPIO

    %% Systemd Orchestration Layer
    subgraph "systemd Orchestration" 
        direction TB
        SPARSER["Service Parser"]:::orchestration
        TPARSER["Target Parser"]:::orchestration
        TSIGNAL["Target Signal Handler"]:::orchestration
        TMONITOR["Target Monitor"]:::orchestration
        subgraph "Units & Targets"
            direction TB
            SVCUNITS["service_files/*.service"]:::orchestration
            TGTUNITS["target_files/*.target"]:::orchestration
        end
    end

    BMC -->|StartUnit| SPARSER
    CHASSIS -->|StartUnit| SPARSER
    HOST -->|StartUnit| SPARSER
    HYPERVISOR -->|StartUnit| SPARSER
    SPARSER -->|StartService| SVCUNITS
    TPARSER -->|MonitorTarget| TGTUNITS
    TGTUNITS -->|EmitSignal| TSIGNAL
    TSIGNAL -->|Notify| TMONITOR
    TMONITOR -->|PropertiesChanged| DBUS

    %% Hardware Layer
    subgraph "Hardware Layer"
        direction TB
        PSU["Chassis Power Supply & Sensors (pgood)"]:::hardware
        HOSTBOARD["Host Board & GPIO"]:::hardware
    end

    SVCUNITS -->|Drive Hardware| PSU
    SVCUNITS -->|Drive GPIO| HOSTBOARD
    PSU -->|Feedback| DISCOVER
    HOSTBOARD -->|Feedback| GPIO

    %% Configuration & Settings
    CONFIG["Configuration Defaults (JSON)"]:::config
    SETTINGS["RestorePolicy & Settings"]:::config

    BMC -->|Read Config| CONFIG
    CHASSIS -->|Read Config| CONFIG
    SETTINGS -->|Policy| BMC

    %% Click Events
    click BMC "https://github.com/openbmc/phosphor-state-manager/blob/master/bmc_state_manager_main.cpp"
    click CHASSIS "https://github.com/openbmc/phosphor-state-manager/blob/master/chassis_state_manager_main.cpp"
    click HOST "https://github.com/openbmc/phosphor-state-manager/blob/master/host_state_manager_main.cpp"
    click HYPERVISOR "https://github.com/openbmc/phosphor-state-manager/blob/master/hypervisor_state_manager_main.cpp"
    click DISCOVER "https://github.com/openbmc/phosphor-state-manager/blob/master/discover_system_state.cpp"
    click SCHEDULED "https://github.com/openbmc/phosphor-state-manager/blob/master/scheduled_host_transition_main.cpp"
    click GPIO "https://github.com/openbmc/phosphor-state-manager/blob/master/host_condition_gpio/host_condition_main.cpp"
    click SPARSER "https://github.com/openbmc/phosphor-state-manager/blob/master/systemd_service_parser.cpp"
    click TPARSER "https://github.com/openbmc/phosphor-state-manager/blob/master/systemd_target_parser.cpp"
    click TSIGNAL "https://github.com/openbmc/phosphor-state-manager/blob/master/systemd_target_signal.cpp"
    click TMONITOR "https://github.com/openbmc/phosphor-state-manager/blob/master/systemd_target_monitor.cpp"
    click OBMCUTIL "https://github.com/openbmc/phosphor-state-manager/tree/master/obmcutil/"
    click CONFIG "https://github.com/openbmc/phosphor-state-manager/blob/master/data/phosphor-service-monitor-default.json"
    click SETTINGS "https://github.com/openbmc/phosphor-state-manager/blob/master/settings.cpp"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef dbus fill:#ffa500,stroke:#333,stroke-width:1px
    classDef daemon fill:#afa,stroke:#333,stroke-width:1px
    classDef orchestration fill:#aaf,stroke:#333,stroke-width:1px
    classDef hardware fill:#ffa,stroke:#333,stroke-width:1px
    classDef config fill:#ccf,stroke:#333,stroke-width:1px
```
