Add host management doc
From content in the user manual.
Signed-off-by: Jeremy Kerr <jk@ozlabs.org>
diff --git a/README.md b/README.md
index 564575c..3197604 100644
--- a/README.md
+++ b/README.md
@@ -13,6 +13,9 @@
- [console.md](console.md): Using the host console
+ - [host-management.md](host-management.md): Performing host management tasks
+ with OpenBMC
+
- [code-update.md](code-update.md): Updating OpenBMC and host platform firmware
diff --git a/host-management.md b/host-management.md
new file mode 100644
index 0000000..d223850
--- /dev/null
+++ b/host-management.md
@@ -0,0 +1,142 @@
+Host Management with OpenBMC
+============================
+
+This document describes the host-management interfaces of the OpenBMC object
+structure, accessible over REST.
+
+Inventory
+---------
+
+The system inventory structure is under the `/org/openbmc/inventory` hierarchy.
+
+In OpenBMC the inventory is represented as a path which is hierarchical to the
+physical system topology. Items in the inventory are referred to as inventory
+items and are not necessarily FRUs. If the system contains one chassis, a
+motherboard, and a CPU on the motherboard, then the path to that inventory item
+would be:
+
+ inventory/system/chassis0/motherboard0/cpu0
+
+The properties associated with an inventory item are specific to that item with
+the addition of these common properties:
+
+ * `version`: a code version associated with this item
+ * `fault`: indicates whether this item has reported an error condition (True/False)
+ * `present`: indicates whether this item is present in the system (True/False)
+
+The usual `list` and `enumerate` REST queries allow the system inventory
+structure to be accessed. For example, to enumerate all inventory items and
+their properties:
+
+ curl -b cjar -k https://bmc/org/openbmc/inventory/enumerate
+
+To list the properties of one item:
+
+ curl -b cjar -k https://bmc/org/openbmc/inventory/system/chassis/motherboard
+
+Sensors
+-------
+
+The system inventory structure is under the `/org/openbmc/sensors` hierarchy.
+
+This interface allows monitoring of system attributes like temperature or
+altitude, and are represented similar to the inventory, by object paths under
+the top-level `sensors` object name. The path categorizes the sensor and shows
+what the sensor represents, but does not necessarily represent the physical
+topology of the system.
+
+For example, all temperature sensors are under `sensors/temperature`. CPU
+temperature sensors would be `sensors/temperature/cpu[n]`.
+
+These are the common properties associated all sensors:
+
+ * `value`: current value of sensor
+ * `units`: units of value
+ * `warning_upper` & `warning_lower`: upper & lower threshold for a warning error
+ * `critical_upper` & `critical_lower`: upper & lower threshold for a critical error
+ * `threshold_state`: current threshold state (normal, warning, critical)
+ * `worst_threshold_state`: highest threshold state seen for all time. There is
+ a REST call to reset this state to normal.
+
+Unlike IPMI, there are no "functional" sensors in OpenBMC; functional states are
+represented in the inventory.
+
+To enumerate all sensors in the system:
+
+ curl -c cjar -k https://bmc/org/openbmc/sensors/enumerate
+
+List properties of one inventory item:
+
+ curl -c cjar -k https://bmc/org/openbmc/sensors/temperature/ambient
+
+Event Logs
+----------
+
+The event log structure is under the `/org/openbmc/records/events` hierarchy.
+Each event is a separate object under this structure, referenced by number.
+
+BMC and host firmware on POWER-based servers can report logs to the BMC.
+Typically, these logs are reported in cases where host firmware cannot start the
+OS, or cannot reliably log to the OS.
+
+The properties associated with an error log are as follows:
+
+ * `Association`: a uri to the failing inventory part
+ * `Message`: An English text string indicating the failure
+ * `Reported By`: Firmware region that created the log ('Host', 'BMC')
+ * `Severity`: level of problem (Info, Predictive Error, etc)
+ * `Development Data`: Data dump for use by Development to analyze the failure
+
+To list all reported events:
+
+ $ curl -b cjar -k https://bmc/org/openbmc/records/events/
+ {
+ "data": [
+ "/org/openbmc/records/events/1",
+ "/org/openbmc/records/events/2",
+ "/org/openbmc/records/events/3",
+ ],
+ "message": "200 OK",
+ "status": "ok"
+ }
+
+To read a specific event log:
+
+ $ curl -b cjar -k https://bmc/org/openbmc/records/events/1
+ {
+ "data": {
+ "association": "/org/openbmc/inventory/system/systemevent",
+ "debug_data": [ ... ],
+ "message": "A systemevent has experienced a unrecoverable error",
+ "reported_by": "Host",
+ "severity": "unrecoverable error",
+ "time": "2016:05:04 01:43:57"
+ },
+ "message": "200 OK",
+ "status": "ok"
+ }
+
+To delete an event log (log 1 in his example), call the `delete` method on the event:
+
+ curl -b cjar -k -H "Content-Type: application/json" -X POST \
+ -d '{"data" : []}' \
+ https://bmc/org/openbmc/records/events/1/action/delete
+
+To clear all logs, call the top-level `clear` method:
+
+ curl -b cjar -k -H "Content-Type: application/json" -X POST \
+ -d '{"data" : []}' \
+ https://bmc/org/openbmc/records/events/action/clear
+
+BIOS boot options
+-----------------
+
+With OpenBMC, the BIOS boot options are stored as dbus properties under the
+`settings/host0` path, in the `boot_flags` property. Their format adheres to the
+Boot Options Parameters table specified in the IPMI Specification Document,
+section 28.13.
+
+Each boot parameter is represented by an individual property, and their hex
+value is displayed in a string format. For example, a boot flags parameter value
+of `0x8014000000` would be stored as a `8014000000` string in the
+`settings/host0/boot_flags` property.