Initial definition of host state management properties
Change-Id: I5047fce6ebd921547b5a6017cd909b2c97e10d96
Signed-off-by: Andrew Geissler <andrewg@us.ibm.com>
diff --git a/xyz/openbmc_project/State/Chassis.interface.yaml b/xyz/openbmc_project/State/Chassis.interface.yaml
new file mode 100644
index 0000000..42c8f71
--- /dev/null
+++ b/xyz/openbmc_project/State/Chassis.interface.yaml
@@ -0,0 +1,40 @@
+description:
+ Implement to provide the chassis power management
+
+properties:
+ - name: RequestedPowerTransition
+ type: enum[self.Transition]
+ default: 'Off'
+ description: >
+ The desired power transition to start on this chassis.
+ This will be preserved across AC power cycles of the BMC.
+
+ - name: CurrentPowerState
+ type: enum[self.PowerState]
+ description: >
+ A read-only property describing the current chassis power state.
+ A user can determine if a chassis is in transition by comparing
+ the CurrentPowerState and RequestedPowerTransition properties.
+
+enumerations:
+ - name: Transition
+ description: >
+ The desired power transition for the chassis
+ values:
+ - name: 'Off'
+ description: >
+ Chassis power should be off
+ - name: 'On'
+ description: >
+ Chassis power should be on
+
+ - name: PowerState
+ description: >
+ The current state of the chassis power
+ values:
+ - name: 'Off'
+ description: >
+ Chassis power is off
+ - name: 'On'
+ description: >
+ Chassis power is on
diff --git a/xyz/openbmc_project/State/Host.interface.yaml b/xyz/openbmc_project/State/Host.interface.yaml
new file mode 100644
index 0000000..a5e95e8
--- /dev/null
+++ b/xyz/openbmc_project/State/Host.interface.yaml
@@ -0,0 +1,44 @@
+description: >
+ Implement to provide host state management
+
+properties:
+ - name: RequestedHostTransition
+ type: enum[self.Transition]
+ default: 'Off'
+ description: >
+ The desired host transition. This will be preserved across AC
+ power cycles of the BMC.
+
+ - name: CurrentHostState
+ type: enum[self.HostState]
+ description: >
+ A read-only property describing the current state of the host
+ firmware. A user can determine if a system is in transition by
+ comparing the CurrentHostState and the RequestedHostTransition
+ properties.
+
+enumerations:
+ - name: Transition
+ description: >
+ The desired transition for host firmware
+ values:
+ - name: 'Off'
+ description: >
+ Host firmware should be off
+ - name: 'On'
+ description: >
+ Host firmware should be on
+ - name: 'Reboot'
+ description: >
+ Host firmware should be rebooted with chassis power remaining on
+
+ - name: HostState
+ description: >
+ The current state of the host firmware
+ values:
+ - name: 'Off'
+ description: >
+ Host firmware is not running
+ - name: 'Running'
+ description: >
+ Host firmware is running
diff --git a/xyz/openbmc_project/State/README.md b/xyz/openbmc_project/State/README.md
new file mode 100644
index 0000000..05f5a55
--- /dev/null
+++ b/xyz/openbmc_project/State/README.md
@@ -0,0 +1,66 @@
+# BMC, Host, and Chassis State Management
+
+## Overview
+
+The goal of the phosphor-state-manager repository is to control and track the
+states of the different software entities in a system. All users will usually
+implement the BMC state interfaces, and some, when creating servers will do the
+Host and Chassis state interfaces. These interfaces will be the mechanism by
+which you determine the state of their corresponding instances, as well as
+reboot the BMC and hosts, and turn on and off power to the chassis. The
+interfaces are designed in a way to support a many to many mappings of each
+interface.
+
+There are three states to track and control on a BMC based server. The states
+below in () represent the actual parameter name as found in
+`/xyz/openbmc_project/state/`+`/bmcX,/hostY,/chassisZ` where X,Y,Z are the
+instances (in most cases 0). For all three states, the software tracks a
+current state, and a requested transition.
+
+1. *BMC* : The BMC has either started all required systemd services and reached
+it's required target (Ready) or it's on it's way there (NotReady). Users can
+request a (Reboot).
+
+2. *Host* : The host is either (Off), or it's (Running).
+Running simply implies that the processors are executing instructions. Users
+can request the host be in a (Off), (On), or (Reboot) state. More details on
+different Reboot options below.
+
+3. *Chassis* : The chassis is either (Off) or (On)
+This represents the state of power to the chassis. The Chassis being on
+is a pre-req to the Host being running. Users can request for the chassis to be
+(Off) or (On). A transition to one or the other is implied by the transition
+not matching the current state.
+
+A simple system design would be to include a single *BMC*, *Host*, and
+*Chassis*.
+
+Details of the properties and their valid settings can be found in the state
+manager dbus interface [specification](https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/xyz/openbmc_project/State/)
+
+### BMC
+
+The *BMC* would provide interfaces at
+`/xyz/openbmc_project/state/bmc<instance>`
+
+### *Host*
+
+The *Host* would provide interfaces at
+`/xyz/openbmc_project/state/host<instance>`
+
+### *Chassis*
+
+The *Chassis* would provide interfaces at
+`/xyz/openbmc_project/state/chassis<instance>`
+
+## Cold vs. Warm Host Reboots
+
+A cold reboot is where you simply cut power to a chassis, and then reapply
+power. You don't give the software running on that chassis any chance to
+cleanly shut down. A warm reboot is where you send a notification to the host
+that is running on that chassis that a shutdown is requested, and wait for that
+host firmware to indicate it has shut itself down. You then remove power from
+the chassis. By default, a reboot transition request against the host object
+will result in a warm reboot. If a user desires a cold reboot then they should
+simply issue a power off transition request to the chassis, and then issue an on
+transition request to the host.