Merge pull request #21 from hramasub/logman
RFC on the OBMC Service Interface.
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..261867b
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,21 @@
+
+# we need xelatex for utf-8 support
+tex = xelatex
+
+all: userguide.pdf
+
+.PHONY: all clean
+
+userguide.pdf: userguide.tex
+ $(tex) $^
+
+userguide.tex: userguide/userguide.tex
+ pandoc -f latex -t latex -s -o $@ $^
+
+userguide/userguide.tex: rest-api.tex host-management.tex console.tex code-update.tex
+
+%.tex: %.md
+ pandoc -o $@ $^
+
+clean:
+ rm -f *.tex userguide.*
diff --git a/README.md b/README.md
index c0bae54..31d79e6 100644
--- a/README.md
+++ b/README.md
@@ -3,6 +3,27 @@
This repository contains documentation for OpenBMC as a whole. There may
be component-specific documentation in the repository for each component.
+OpenBMC Usage
+-------------
+
+These documents describe how to use OpenBMC, including using the programmatic
+interfaces to an OpenBMC system.
+
+ - [rest-api.md](rest-api.md): Introduction to using the OpenBMC REST API
+
+ - [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
+
+
+OpenBMC Development
+-------------------
+
+These documents contain details on developing OpenBMC code itself
+
- [cheatsheet.md](cheatsheet.md): Quick reference for some common
development tasks
@@ -15,5 +36,30 @@
- [kernel-development.md](kernel-development.md): Reference for common
kernel development tasks
- - [rest-api.md](rest-api.md): Introduction to using the OpenBMC REST
- API
+
+OpenBMC Goals
+-------------
+
+The OpenBMC project's aim is to create a highly extensible framework for BMC
+software and implement for data-center computer systems.
+
+We have a few high-level objectives:
+
+ * The OpenBMC framework must be extensible, easy to learn, and usable in a
+ variety of programming languages.
+
+ * Provide a REST API for external management, and allow for "pluggable"
+ interfaces for other types of management interactions.
+
+ * Provide a remote host console, accessible over the network
+
+ * Persist network configuration settable from REST interface and host
+
+ * Provide a robust solution for RTC management, exposed to the host.
+
+ * Compatible with host firmware implementations for basic IPMI communication
+ between host and BMC
+
+ * Provide a flexible and hierarchical inventory tracking component
+
+ * Maintain a sensor database and track thresholds
diff --git a/cheatsheet.md b/cheatsheet.md
index 2f9fc15..2a77481 100644
--- a/cheatsheet.md
+++ b/cheatsheet.md
@@ -33,6 +33,17 @@
$ bitbake obmc-phosphor-image
```
+## Building for Barreleye
+
+The Barreleye target is `barreleye`.
+
+If you are starting from scratch without a `build/conf` directory you can just:
+```
+$ cd openbmc
+$ TEMPLATECONF=meta-openbmc-machines/meta-openpower/meta-rackspace/meta-barreleye/conf . oe-init-build-env
+$ bitbake obmc-phosphor-image
+```
+
## Building the OpenBMC SDK
Looking for a way to compile your programs for 'ARM' but you happen to be running on a 'PPC' or 'x86' system? You can build the sdk receive a fakeroot environment.
```
diff --git a/code-update.md b/code-update.md
new file mode 100644
index 0000000..da85f5e
--- /dev/null
+++ b/code-update.md
@@ -0,0 +1,98 @@
+OpenBMC & Host Code Update
+===================
+
+After building OpenBMC, you will end up with a set of image files in
+`tmp/deploy/images/<platform>/`. The `image-*` symlinks correspond to components
+that can be updated on the BMC:
+
+ * `image-bmc` → `flash-<platform>-<timestamp>`
+
+ The whole-of-flash image for the BMC
+
+ * `image-initramfs` → `core-image-minimal-initramfs-palmetto.cpio.lzma.u-boot`
+
+ The small initramfs image; used for early init and flash management
+
+ * `image-kernel` → `cuImage`
+
+ The OpenBMC kernel cuImage (combined kernel and device tree)
+
+ * `image-rofs` → `obmc-phosphor-image-palmetto.squashfs-xz`
+
+ The read-only OpenBMC filesystem
+
+ * `image-rwfs` → `rwfs.jffs2`
+
+ The read-write filesystem for persistent changes to the OpenBMC filesystem
+
+ * `image-u-boot` → `u-boot.bin`
+
+ The OpenBMC bootloader
+
+Update from the OpenBMC shell
+-----------------------------
+
+To update from the OpenBMC shell, copy one or more of these `image-*` files to
+the directory:
+
+ /run/initramfs/
+
+(preserving the filename), then reboot. Before the system reboots, the new image
+will be copied to the appropriate flash partition.
+
+
+Update via REST
+---------------
+
+An OpenBMC system can download an update image from a TFTP server, and apply
+updates, controlled via REST. The general procedure is:
+
+ 1. Configure update settings
+ 2. Initiate update
+ 3. Check flash status
+
+### Configure update settings
+
+There are a few settings available to control the update process:
+
+ * `preserve_network_settings`: Preserve network settings, only needed if updating uboot
+ * `restore_application_defaults`: update read-only file system
+ * `update_kernel_and_apps_only`: update kernel and initramfs
+ * `clear_persistent_files`: Erase persistent files
+
+To configure the update settings, perform a REST PUT to
+`/control/flash/bmc/attr/<setting>`. For example:
+
+ curl -b cjar -k -H "Content-Type: application/json" -X PUT \
+ -d '{"data": 1}' \
+ https://bmc/org/openbmc/control/flash/bmc/attr/preserve_network_settings
+
+### Initiate update
+
+Perform a POST to invoke the `updateViaTftp` method of the `/flash/bmc` object:
+
+ curl -b cjar -k -H "Content-Type: application/json" -X POST \
+ -d '{"data": ["<TFTP server IP address>", "<filename>"]}' \
+ https://bmc/org/openbmc/control/flash/bmc/action/updateViaTftp
+
+### Check flash status
+
+You can query the progress of the flash with a simple GET request:
+
+ curl -b cjar -k https://bmc/org/openbmc/control/flash/bmc
+
+Host code update
+================
+
+Using a similar method, we can update the host firmware (or "BIOS"), by
+performing a POST request to call the `updateViaTftp` method of
+`/control/flash/bios` (instead of `/control/flash/bmc` used above). To initiate
+the update:
+
+ curl -b cjar -k -H "Content-Type: application/json" -X POST \
+ -d '{"data": ["<TFTP server IP address>", "<filename>"]}' \
+ https://bmc/org/openbmc/control/flash/bios/action/updateViaTftp
+
+And to check the flash status:
+
+ curl -b cjar -k https://bmc/org/openbmc/control/flash/bios
diff --git a/console.md b/console.md
new file mode 100644
index 0000000..2b83d8d
--- /dev/null
+++ b/console.md
@@ -0,0 +1,43 @@
+OpenBMC host console support
+============================
+
+This document describes how to connect to the host UART console from an OpenBMC
+management system.
+
+The console infrastructure allows multiple shared connections to a single host
+UART. UART data from the host is output to all connections, and input from any
+connection is sent to the host.
+
+Remote console connections
+--------------------------
+
+To connect to an OpenBMC console session remotely, just ssh to your BMC on port
+2200. Use the same login credentials you would for a normal ssh session:
+
+ $ ssh -p 2200 [user]@[bmc-hostname]
+
+
+Local console connections
+-------------------------
+
+If you're already logged into an OpenBMC machine, you can start a console
+session directly, using:
+
+ $ obmc-console-client
+
+To exit from a console, type:
+
+ return ~ .
+
+Note that if you're on an ssh connection, you'll need to 'escape' the ~
+character, by entering it twice.
+
+Logging
+-------
+
+Console logs are kept in:
+
+ /var/log/obmc-console.log
+
+This log is limited in size, and will wrap after hitting that limit (currently
+set at 16kB).
diff --git a/contributing.md b/contributing.md
index 8867fb8..db485a0 100644
--- a/contributing.md
+++ b/contributing.md
@@ -25,6 +25,20 @@
should be logically grouped, and keep related parts together where it
makes sense.
+Starting out
+------------
+
+If you're starting out with OpenBMC, you may want to take a look at the issues
+tagged with 'bitesize'. These are fixes or enhancements that don't require
+extensive knowledge of the OpenBMC codebase, and are easier for a newcomer to
+start working with.
+
+Check out that list here:
+
+ https://github.com/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+user%3Aopenbmc+label%3Abitesize
+
+If you need further details on any of these issues, feel free to add comments.
+
Coding style
------------
diff --git a/dbus-interfaces.md b/dbus-interfaces.md
index 51aa114..524bc3f 100644
--- a/dbus-interfaces.md
+++ b/dbus-interfaces.md
@@ -1,247 +1,691 @@
+OpenBMC DBUS API
+================
+This document aims to specify the OpenBMC DBUS API.
-This document aims to specify the dbus interfaces exported by OpenBMC objects.
+The Phosphor distribution provides sample applications that implement off all
+the interfaces and objects listed below. Alternative or more feature complete
+applications are possible by implementing parts of this DBUS API.
-# Host IPMI
+OpenBMC typically adheres to DBUS best practices and usage models; however, one
+deviation is that OpenBMC places no requirements on well known service names.
+This allows developers to structure their object implementations in whatever
+processes they choose. In the standard DBUS programming model, applications
+connect to a service with a well known name. The well known name is
+associated with a fixed schema. In OpenBMC, without any standardization of
+well known names, applications lose the knowledge of what applications provide
+which objects. To address this, the Phosphor distribution provides the
+objectmapper service. See the `org.openbmc.objectmapper.ObjectMapper`
+interface below for more information.
-## `/org/openbmc/HostIpmi`
+The OpenBMC DBUS API is still alpha. If you have questions or suggestions
+please [let the community know](https://lists.ozlabs.org/listinfo/openbmc).
-signals:
+`org.openbmc.HostIpmi`
+----------------------
+The HostIpmi interface allows applications to interact with host processor
+firmware using IPMI. Typically applications should use the higher level APIs
+provided by `org.openbmc.HostServices` to interact with the host processor
+firmware.
- * `ReceivedMessage(seq : byte, netfn : byte, lun : byte, cmd : byte, data: array[byte])`
+### methods
+| name | in signature | out signature | description |
+| ------------ | ------------ | ------------- | ---------------------------- |
+| `sendMessage` | `yyyyyay` | `x` | **Send an IPMI message to the host processor firmware.**|
+| | `y` | | IPMI seq. |
+| | `y` | | IPMI netfn. |
+| | `y` | | IPMI lun. |
+| | `y` | | IPMI cmd. |
+| | `y` | | IPMI cc. |
+| | `ay` | | IPMI msg. |
+| | | `x` | The result status. |
+| `setAttention` | `void` | `x` | **Raise an SMS attention event.**|
+| | | `x` | The result status. |
-methods:
+### signals
+| name | signature | description |
+| ------------- | --------- | ------------------------------------------------ |
+| `ReceivedMsg` | `yyyyay` | **An IPMI message was received from the host processor firmware.**|
+| | `y` | IPMI seq. |
+| | `y` | IPMI netfn. |
+| | `y` | IPMI lun. |
+| | `y` | IPMI cmd. |
+| | `ay` | IPMI message. |
- * `sendMessage(seq : byte, netfn : byte, lun : byte, cmd : byte, cc : byte, data : array[byte])`
-
- * `setAttention()`
+### namespace
+| path | required | description |
+| ------------- | ----------- | ---------------------------------------------- |
+| `/org/openbmc/HostIpmi/<n>` | Yes on systems with the host-ipmi machine feature, otherwise no. | n: IPMI interface number. If implemented, at least one IPMI interface must exist. |
-# Chassis Control
+`org.openbmc.HostServices`
+------------------------
+The HostServices interface allows applications to interact with the host
+processor firmware. Applications should use the high level APIs provided here
+in favor of `org.openbmc.HostIpmi` where applicable.
-## `/org/openbmc/control/chassis0`
+### methods
+| name | in signature | out signature | description |
+| -------------- | ------------ | ------------- | ---------------------------- |
+| `SoftPowerOff` | `void` | `x` | **Prepare the host processor firmware for an orderly shutdown.**|
+| | | `x` | The result status. |
-signals:
+### namespace
+| path | required | description |
+| --------------------------- | -------------------------------- | ----------- |
+| `/org/openbmc/HostServices` | Yes on systems with the host-ipmi machine feature, otherwise no. | ? |
+`org.openbmc.InventoryItem`
+---------------------------
+The InventoryItem interface allows applications to examine and manipulate
+information that relates to inventory items.
-methods:
+### methods
+| name | in signature | out signature | description |
+| ------------ | ------------ | ------------- | ----------------------------- |
+| `setPresent` | `s` | `void` | **Indicate the item is present.**|
+| | `s` | | true or false |
+| `setFault` | `s` | `void` | **Indicate the item is faulted.**|
+| | `s` | | true or false |
+| `update` | `a{sv}` | `void` | **Update the item attributes.**|
+| | `a{sv}` | | Key/value pair dictionary. |
- * `(state : int) = getPowerState()`
+### properties
+| name | signature | description |
+| ---------- | --------- | --------------------------------------- |
+| `is_fru` | `b` | **The item is field replaceable.** |
+| `fru_type` | `s` | **The type of the item.** |
+| `present` | `s` | **The item is physically present.** |
+| `fault` | `s` | **Whether or not the item is faulted.** |
- * `powerOff()`
+### namespace
+| path | required | description |
+| ------------------------------- | -------- | ------------------------------- |
+| `/org/openbmc/inventory/<item>` | No | Inventory items must be instantiated in the inventory namespace.|
- * `powerOn()`
+`org.openbmc.NetworkManager`
+----------------------------
+The NetworkManager interface allows applications to examine and manipulate
+network settings.
- * `softPowerOff()`
+### methods
+| name | in signature | out signature | description |
+| ---------------- | ------------ | ------------- | -------------------------- |
+| `GetAddressType` | `s` | `s` | **Query the IP address type.**|
+| | `s` | | The network device to query.|
+| | | `s` | The address type for the network device.|
+| `GetHwAddress` | `s` | `s` | **Query the hardware address.**|
+| | `s` | | The network device to query.|
+| | | `s` | The hardware address for the network device.|
+| `SetAddress4` | `ssss` | `x` | **Set the IPV4 address.** |
+| | `s` | | The network device on which to set the ipv4 address.|
+| | `s` | | The ipv4 address to set. |
+| | `s` | | The ipv4 mask to set. |
+| | `s` | | The ipv4 gateway to set |
+| | | `x` | The result status. |
+| `EnableDHCP` | `s` | `x` | **Enable DHCP.** |
+| | `s` | | The network device on which to enable DHCP.|
+| | | `x` | The result status. |
+| `SetHwAddress` | `ss` | `i` | **Set the hardware address.**|
+| | `s` | | The network device on which to set the hardware address.|
+| | `s` | | The hardware address to set.|
+| | | `i` | The result status. |
+| `GetAddress4` | `s` | `iyss` | **Query the IPV4 address.**|
+| | `s` | | The network device to query.|
+| | | `i` | ? |
+| | | `y` | ? |
+| | | `s` | ? |
+| | | `s` | ? |
- * `reboot()`
-
- * `softReboot()`
+### namespace
+| path | required | description |
+| --------------------------------------- | -------------------- | ----------- |
+| `/org/openbmc/NetworkManager/Interface` | Yes on systems with the network machine feature, otherwise no. | ? |
- * `setIdentify()`
+`org.openbmc.Sensors`
+---------------------
+The Sensors interface allows applications to register a sensor instance with a
+sensor management application.
- * `clearIdentify()`
+### methods
+| name | in signature | out signature | description |
+| ---------- | ------------ | ------------- | -------------------------------- |
+| `register` | `ss` | `void` | **Register a sensor instance of type class.**|
+| | `s` | | The class name of the sensor. |
+| | `s` | | The object path of the sensor. |
+| `delete` | `s` | `void` | **Deregister a sensor instance.**|
+| | `s` | | The object path of the sensor. |
- * `setPowerPolicy(policy : int)`
+### namespace
+| path | required | description |
+| ---------------------- | -------- | ---------------------------------------- |
+| `/org/openbmc/sensors` | Yes | The sensor manager must be instantiated here.|
- * `setDebugMode()`
+`org.openbmc.HwmonSensor`
+-------------------------
+The HwmonSensor interface allows applications to query and manipulate hwmon
+based sensors.
-properties:
+### methods
+| name | in signature | out signature | description |
+| ----------- | ------------ | ------------- | ----------- |
+| `setByPoll` | `v` | `(bv)` | **?** |
+| | `v` | | ? |
+| | | `(bv)` | ? |
- * `reboot`
+### properties
+| name | signature | description |
+| ---------- | --------- | ----------- |
+| `scale` | `?` | **?** |
+| `offset` | `?` | **?** |
+| `filename` | `?` | **?** |
+### namespace
+| path | required | description |
+| --------------------------------------- | -------- | ----------------------- |
+| `/org/openbmc/sensors/<class>/<sensor>` | No | Any sensor instances must be instantiated in the sensors namespace.|
-# Sensors
+`org.openbmc.SensorThresholds`
+------------------------------
+The SensorThreshold interface allows applications to query and manipulate
+sensors thresholds.
-## `/org/openbmc/sensors/<type>/<name hierarchy>`
+### methods
+| name | in signature | out signature | description |
+| --------------------- | ------------ | ------------- | ----------- |
+| `resetThresholdState` | `void` | `void` | **?** |
-signals:
+### signals
+| name | signature | description |
+| ----------- | --------- | ----------- |
+| `Emergency` | `void` | **?** |
- * `Warning(value : variant)`
+### properties
+| name | signature | description |
+| ----------------------- | --------- | ----------- |
+| `thresholds_enabled` | `?` | **?** |
+| `emergency_enabled` | `?` | **?** |
+| `warning_upper` | `?` | **?** |
+| `warning_lower` | `?` | **?** |
+| `critical_upper` | `?` | **?** |
+| `critical_lower` | `?` | **?** |
+| `threshold_state` | `?` | **?** |
+| `worst_threshold_state` | `?` | **?** |
- * `Critical(value : variant)`
+### namespace
+| path | required | description |
+| --------------------------------------- | -------- | ----------------------- |
+| `/org/openbmc/sensors/<class>/<sensor>` | No | Any sensor instances must be instantiated in the sensors namespace.|
-methods:
+`org.openbmc.SensorValue`
+-------------------------
+The SensorValue interface allows applications to query and manipulate sensors
+that only provide a value.
- * `(value : variant) = getValue()`
+### methods
+| name | in signature | out signature | description |
+| ---------- | ------------ | ------------- | ------------------------- |
+| `setValue` | `v` | `void` | **Set the sensor value.** |
+| | `v` | | The value to set. |
+| `getValue` | `void` | `v` | **Get the sensor value.** |
+| | | `v` | The sensor value. |
- * `setValue(value : variant)`
+### properties
+| name | signature | description |
+| ------- | --------- | ------------------------------------------------------ |
+| `units` | `s` | **The units associated with the sensor value.** |
+| `error` | `?` | **?** |
- * `resetThresholdState()`
+### namespace
+| path | required | description |
+| --------------------------------------- | -------- | ----------------------- |
+| `/org/openbmc/sensors/<class>/<sensor>` | No | Any sensor instances must be instantiated in the sensors namespace.|
-properties:
+`org.openbmc.Button`
+--------------------
+The Button interface allows applications to query the state of buttons.
- * `error`
+### methods
+| name | in signature | out signature | description |
+| -------------- | ------------ | ------------- | ---------------------------- |
+| `isOn` | `void` | `b` | **Query the button state.** |
+| | | `b` | The button state. |
+| `simPress` | `void` | `void` | **Simulate a button press.** |
+| `simLongPress` | `void` | `void` | **Simulate a long button press.**|
- * `units`
+### signals
+| name | signature | description |
+| ------------- | --------- | ------------------------------------ |
+| `Released` | `void` | **The button was released.** |
+| `Pressed` | `void` | **The button was pressed.** |
+| `PressedLong` | `void` | **The button was pressed and held.** |
- * `value`
+### properties
+| name | signature | description |
+| ------- | --------- | ----------------------------- |
+| `state` | `b` | **The current button state.** |
- * `critical_upper`
+### namespace
+| path | required | description |
+| ------------------------------- | -------- | ------------------------------- |
+| `/org/openbmc/buttons/<button>` | No | Any button instances must be instantiated in the buttons namespace.|
- * `critical_lower`
+`org.openbmc.control.Bmc`
+-------------------------
+The control.Bmc interface allows applications control the BMC.
- * `warning_upper`
+### methods
+| name | in signature | out signature | description |
+| ----------- | ------------ | ------------- | ------------------ |
+| `warmReset` | `void` | `void` | **Reset the BMC.** |
- * `warning_lower`
+### namespace
+| path | required | description |
+| ------------------------------------ | -------- | -------------------------- |
+| `/org/openbmc/control/bmc<instance>` | Yes | Any BMC control instances must be instantiated in the control namespace.|
- * `threshold_state`
+`org.openbmc.managers.Download`
+-------------------------------
+The managers.Download interface allows applications to receive file download
+notifications.
- * `worst_threshold_state`
+### signals
+| name | signature | description |
+| ------------------ | --------- | ------------------------------------------- |
+| `DownloadComplete` | `ss` | **The file was downloaded successfully.** |
+| | `s` | The file path in the local filesystem. |
+| | `s` | The name of the file that was requested. |
+| `DownloadError` | `s` | **An error occurred downloading the file.** |
+| | `s` | The name of the file that was requested. |
-### `/org/openbmc/sensors/host/PowerCap`
-This object is used to set Host PowerCap. In turn a OCC "Set User PowerCap" command is sent to OCC.
+### namespace
+| path | required | description |
+| -------------------------------- | -------- | ----------- |
+| `/org/openbmc/managers/Download` | ? | ? |
-### `/org/openbmc/sensors/host/OccStatus`
-This object can set OCC state to either: "Enabled" or "Disabled".
+`org.openbmc.control.BmcFlash`
+------------------------------
+The control.BmcFlash interface allows applications update the BMC firmware.
-# Inventory
+### methods
+| name | in signature | out signature | description |
+| --------------- | ------------ | ------------- | --------------------------- |
+| `updateViaTftp` | `ss` | `void` | **Perform a BMC firmware update using a TFTP server.**|
+| | `s` | | The ipv4 address of the TFTP server hosting the firmware image file.|
+| | `s` | | The name of the file containing the BMC firmware image.|
-## `/org/openbmc/inventory/<item hierarchy>`
-
-signals:
-
-
-methods:
-
- * `setPresent(present : string)`
-
- * `setFault(fault : string)`
-
- * `update(dict ( key : string, data : variant ) )`
-
-properties:
-
- * `fault`
-
- * `fru_type`
-
- * `is_fru`
+### signals
+| name | signature | description |
+| -------------- | --------- | ---------------------------------------- |
+| `TftpDownload` | `ss` | **A request to download a file using TFTP occurred.**|
+| | `s` | The ipv4 address of the TFTP server hosting the firmware image file.|
+| | `s` | The name of the file containing the BMC firmware image.|
- * `present1`
+### properties
+| name | signature | description |
+| ------------------------------ | --------- | ------------------------------- |
+| `status` | `s` | **?** |
+| `filename` | `s` | **The name of the file containing the BMC firmware image.**|
+| `preserve_network_settings` | `b` | **Perform a factory reset.** |
+| `restore_application_defaults` | `b` | **Perform a factory reset.** |
+| `update_kernel_and_apps` | `b` | **Perform a factory reset.** |
+| `clear_persistent_files` | `b` | **Perform a factory reset.** |
- * `version`
+### namespace
+| path | required | description |
+| -------------------------------- | -------- | ----------- |
+| `/org/openbmc/control/flash/bmc` | ? | ? |
+`org.openbmc.control.Chassis`
+-----------------------------
+The control.Chassis interface allows applications to query and manipulate the
+state of a Chassis.
-# Buttons
+### methods
+| name | in signature | out signature | description |
+| --------------- | ------------ | ------------- | --------------------------- |
+| `setIdentity` | `void` | `void` | **Turn on the identification indicator.**|
+| `clearIdentity` | `void` | `void` | **Turn off the identification indicator.**|
+| `powerOn` | `void` | `void` | **Power the chassis on.** |
+| `powerOff` | `void` | `void` | **Power the chassis off immediately.**|
+| `softPowerOff` | `void` | `void` | **Perform a graceful shutdown of the chassis.**|
+| `reboot` | `void` | `void` | **Reboot the chassis immediately.**|
+| `softReboot` | `void` | `void` | **Perform a graceful reboot of the chassis.**|
-## `/org/openbmc/buttons/<button_name>`
+### properties
+| name | signature | description |
+| ------ | --------- | --------------------- |
+| `uuid` | `s` | **The chassis UUID.** |
-signals:
+### namespace
+| path | required | description |
+| ---------------------------------------- | -------- | ---------------------- |
+| `/org/openbmc/control/chassis<instance>` | ? | Any chassis control instances must be instantiated in the control namespace.|
- * `Pressed`
+`org.openbmc.Flash`
+-------------------
+The Flash interface allows applications update the host firmware.
- * `PressedLong`
+### methods
+| name | in signature | out signature | description |
+| --------------- | ------------ | ------------- | --------------------------- |
+| `update` | `s` | `void` | **Update the host firmware.**|
+| | `s` | | The file containing the host firmware image.|
+| `error` | `s` | `void` | **?** |
+| | `s` | | The error message. |
+| `done` | `void` | `void` | **?** |
+| `init` | `void` | `void` | **?** |
+| `updateViaTftp` | `ss` | `void` | **Update the host firmware using a TFTP server.**|
+| | `s` | | The TFTP server url. |
+| | `s` | | The file containing the host firmware image.|
- * `Released`
+### signals
+| name | signature | description |
+| ---------- | --------- | -------------------------------------------- |
+| `Updated` | `void` | **?** |
+| `Download` | `ss` | **?** |
+| | `s` | The TFTP server url. |
+| | `s` | The file containing the host firmware image. |
-methods:
+### properties
+| name | signature | description |
+| ------------------ | --------- | --------------- |
+| `filename` | `s` | **?** |
+| `flasher_path` | `s` | **?** |
+| `flasher_name` | `s` | **?** |
+| `flasher_instance` | `s` | **?** |
+| `status` | `s` | **?** |
- * `simPress`
+### namespace
+| path | required | description |
+| ---- | -------- | ----------- |
+| ? | ? | ? |
-# LEDs
+`org.openbmc.SharedResource`
+----------------------------
+Insert description of the SharedResource interface here.
-## `/org/openbmc/control/leds/<led_name>`
+### methods
+| name | in signature | out signature | description |
+| ---------- | ------------ | ------------- | -------------------------------- |
+| `lock` | `s` | `void` | **Lock the shared resource.** |
+| | `s` | | The shared resource name. |
+| `unlock` | `void` | `void` | **Unlock the shared resource.** |
+| `isLocked` | `void` | `bs` | **Get the lock state of the resource.**|
+| | | `b` | The lock state. |
+| | | `s` | The shared resource name. |
-methods:
+### properties
+| name | signature | description |
+| ------ | --------- | ----------------------------- |
+| `lock` | `b` | **The lock state.** |
+| `name` | `s` | **The shared resource name.** |
- * `setOn()`
+`org.openbmc.control.Host`
+--------------------------
+The control.Host interface allows applications to manipulate the host processor
+firmware.
- * `setOff()`
+### methods
+| name | in signature | out signature | description |
+| ---------- | ------------ | ------------- | -------------------------------- |
+| `boot` | `void` | `void` | **Start the host processor firmware.**|
+| `shutdown` | `void` | `void` | **Stop the host processor firmware.**|
+| `reboot` | `void` | `void` | **Restart the host processor firmware.**|
- * `setBlinkSlow()`
+### signals
+| name | signature | description |
+| -------- | --------- | ---------------------------------------- |
+| `Booted` | `void` | **The host processor firmware was started.** |
- * `setBlinkFast()`
+### properties
+| name | signature | description |
+| ------------ | --------- | --------------- |
+| `debug_mode` | `i` | **?** |
+| `flash_side` | `s` | **?** |
-properties:
+### namespace
+| path | required | description |
+| ------------------------------------- | -------- | ------------------------- |
+| `/org/openbmc/control/host<instance>` | No | Any host control instances must be instantiated in the control namespace.|
- * `color`
+`org.openbmc.control.Power`
+---------------------------
+Insert a description of the control.Power interface here.
- * `state`
+### methods
+| name | in signature | out signature | description |
+| --------------- | ------------ | ------------- | --------------------------- |
+| `setPowerState` | `i` | `void` | **Set the power state.** |
+| | `i` | | The state to enter. |
+| `getPowerState` | `void` | `i` | **Query the current power state.**|
+| | | `i` | The current power state. |
-# Event Logs
+### signals
+| name | signature | description |
+| ----------- | --------- | --------------------- |
+| `PowerGood` | `void` | **The power is on.** |
+| `PowerLost` | `void` | **The power is off.** |
-## `/org/openbmc/records/events`
+### properties
+| name | signature | description |
+| ------------- | --------- | --------------- |
+| `pgood` | `i` | **?** |
+| `state` | `i` | **?** |
+| `pgood_timeout` | `i` | **?** |
-methods:
+### namespace
+| path | required | description |
+| -------------------------------------- | -------- | ------------------------ |
+| `/org/openbmc/control/power<instance>` | ? | Any power control instances must be instantiated in the control namespace.|
- * `Clear()`
+`org.openbmc.Led`
+---------------
+Insert a description of the Led interface here.
-## `/org/openbmc/records/events/<logid>`
+### methods
+| name | in signature | out signature | description |
+| -------------- | ------------ | ------------- | -------------------------- |
+| `setOn` | `void` | `void` | **Turn the LED on.** |
+| `SetOff` | `void` | `void` | **Turn the LED off.** |
+| `setBlinkSlow` | `void` | `void` | **Blink the LED slowly.** |
+| `setBlinkFast` | `void` | `void` | **Blink the LED quickly.** |
-methods:
+### properties
+| name | signature | description |
+| ---------- | --------- | -------------------------- |
+| `color` | `i` | **The color of the LED.** |
+| `function` | `s` | **?** |
+| `state` | `s` | **The current LED state.** |
- * `delete()`
+### namespace
+| path | required | description |
+| -------------------------------- | -------- | ------------------------------ |
+| `/org/openbmc/control/led/<led>` | No | Any LED instances must be instantiated in the control/led namespace.|
-properties:
+`org.openbmc.objectmapper.ObjectMapper`
+---------------------------------------
+The ObjectMapper interface enables applications to discover the DBUS unique
+connection name(s) for a given object path.
- * `message`
+### methods
+| name | in signature | out signature | description |
+| ----------------- | ------------ | ------------- | ------------------------- |
+| `GetObject` | `s` | `a{sas}` | **Determine the DBUS unique connection name(s) implementing a single object and the interfaces implemented by those services.**|
+| | `s` | | The path of the object to query.|
+| | | `a{sas}` | A dictionary with DBUS unique connection names as keys, and interfaces as values.|
+| `GetAncestors` | `s` | `a{sa{sas}}` | **Determine the DBUS unique connection name(s) implementing any ancestor objects and the interfaces implemented by those services.**|
+| | `s` | | The point in the namespace from which to provide results.|
+| | | `a{sa{sas}}` | A dictionary of dictionaries, with object paths as outer keys, DBUS unique connection names as inner keys, and implemented interfaces as values.|
+| `GetSubTree` | `si` | `a{sa{sas}}` | **Determine the DBUS unique connection name(s) implementing an entire subtree of objects in the DBUS namespace.**|
+| | `s` | | The point in the namespace from which to provide results.|
+| | `i` | | The number of path elements to descend.|
+| | | `a{sa{sas}}` | A dictionary of dictionaries, with object paths as outer keys, DBUS unique connection names as inner keys, and interfaces implemented by those services as values.|
+| `GetSubTreePaths` | `si` | `as` | **List all known DBUS objects.**|
+| | `s` | | The point in the namespace from which to provide results.|
+| | `i` | | The number of path elements to descend.|
+| | | `as` | An array of object paths. |
- * `association`
+### namespace
+| path | required | description |
+| ---------------------------------------- | -------- | ---------------------- |
+| `/org/openbmc/objectmapper/objectmapper` | Yes | The object mapper must be instantiated here.|
- * `reported_by`
+`org.openbmc.recordlog`
+-----------------------
+Insert a description of the record log interface here.
- * `severity`
+### methods
+| name | in signature | out signature | description |
+| ------------------- | ------------ | ------------- | ----------------------- |
+| `acceptHostMessage` | `sssay` | `q` | **Accept a message from the host processor firmware.**|
+| | `s` | | The message content. |
+| | `s` | | The message severity. |
+| | `s` | | An association between the message and another entity.|
+| | `ay` | | Development data associated with the message.|
+| | | `q` | The created record ID. |
+| `clear` | `void` | `q` | **Remove all record instances.**|
+| | | `q` | ? |
- * `debug_data`
+### namespace
+| path | required | description |
+| ------------------------------ | -------- | -------------------------------- |
+| `/org/openbmc/records/<class>` | No | Any recordlog instances must be instantiated in the records namespace. |
- * `time`
+`org.openbmc.record`
+--------------------
+Insert a description of the record interface here.
-# Associations
-OpenBMC uses associations to extend the DBUS API without impacting existing objects and interfaces.
-## `org.openbmc.Associations`
-A object wishing to create an association implements this interface.
+### properties
+| name | signature | description |
+| ------------- | --------- | ------------------------------------------------ |
+| `message` | `s` | **A free from message.** |
+| `severity` | `s` | **The record severity.** |
+| `reported_by` | `s` | **The originating entity of the record.** |
+| `time` | `s` | **The timestamp associated with the record.** |
+| `debug_data` | `ay` | **Development data associated with the record.** |
-methods:
-* None
+### namespace
+| path | required | description |
+| --------------------------------------- | -------- | ----------------------- |
+| `/org/openbmc/records/<class>/<record>` | No | Records must be instantiated in the records namespace.|
-properties:
-* `associations signature=a(sss):` An array of forward, reverse, endpoint tuples where:
- * fowrard - the type of the association to create
- * reverse - the type of the association to create for the endpoint
- * endpoint - the endpoint of the association
+`org.openbmc.Object.Delete`
+---------------------------
+Applications that create objects that can be removed for any reason must
+implement this interface. Some common examples of this could be an event log
+instance or a user account instance.
-For example, given an object: `/org/openbmc/events/1`
-that implements `org.openbmc.Associations` and sets the `associations` property to:
+### methods
+| name | in signature | out signature | description |
+| -------- | ------------ | ------------- | ---------------------------------- |
+| `delete` | `void` | `void` | **Remove the object from the DBUS namespace.**|
-`associations: [`
+`org.openbmc.Associations`
+--------------------------
+Applications wishing to create an association between two or more objects
+implement can this interface. Associations exist to provide a stable but
+extendable DBUS API.
-` ["events", "frus", "/org/openbmc/piece_of_hardware"],`
+### properties
+| name | signature | description |
+| -------------- | --------- | ---------------------------------------- |
+| `associations` | `a(sss)` | **An array of forward, reverse, endpoint tuples.**|
+| | `s` | The type of association to create. |
+| | `s` | The type of association to create for the endpoint.|
+| | `s` | The object path of the endpoint. |
-` ["events", "times", "/org/openbmc/timestamps/1"]`
+For example, given an object /org/openbmc/events/1 that implements
+`org.openbmc.Associations` and then sets the associations property to:
-`]`
+```json
+"associations": [
+ ["events", "frus", "/org/openbmc/piece_of_hardware"],
+ ["events", "times", "/org/openbmc/timestamps/1"]
+]
+```
would result in the following associations:
-* /org/openbmc/events/1/frus
-* /org/openbmc/events/1/times
-* /org/openbmc/piece_of_hardware/events
-* /org/openbmc/timestamps/1/events
+```shell
+/org/openbmc/events/1/frus
+/org/openbmc/events/1/times
+/org/openbmc/piece_of_hardware/events
+/org/openbmc/timestamps/1/events
+```
-It is up to the specific OpenBMC implementation to decide, what, if anything to do with these.
-For example, the Phosphor mapper application looks for objects that implement this interface
-and creates objects in its /org/openbmc DBUS namespace.
+`org.openbmc.Association`
+-------------------------
+Applications use this interface to inject associations into the DBUS namespace.
-## `org.openbmc.Association`
-OpenBMC implementations use this interface to insert associations into the DBUS namespace.
+### properties
+| name | signature | description |
+| ----------- | --------- | -------------------------------------- |
+| `endpoints` | `as` | **An array of association endpoints.** |
-methods:
-* None
-
-properties:
-* `endpoints signature=as:` An array of association endpoints.
-
For example, given:
-/org/openbmc/events/1/frus:
+```json
+"/org/openbmc/events/1/frus": {
+ "endpoints": [
+ "/org/openbmc/hardware/cpu0",
+ "/org/openbmc/hardware/cpu1",
+ ]
+}
+```
-`endpoints: [`
-
-` ["/org/openbmc/hardware/cpu0"],`
-
-` ["/org/openbmc/hardware/cpu1"],`
-
-`]`
-
Denotes the following:
-* /org/openbmc/events/1 => fru => /org/openbmc/hardware/cpu0
-* /org/openbmc/events/1 => fru => /org/openbmc/hardware/cpu1
+
+```shell
+/org/openbmc/events/1 => fru => /org/openbmc/hardware/cpu0
+/org/openbmc/events/1 => fru => /org/openbmc/hardware/cpu1
+```
+
+`org.openbmc.settings.Host`
+---------------------------
+The settings.Host interface provides a basic settings repository for host
+processor firmware settings.
+
+### methods
+Host settings are accessed using the standard
+[`org.freedesktop.DBus.Properties`](
+https://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties)
+interface.
+
+### signals
+Applications are notified of host setting changes using the standard
+[`org.freedesktop.DBus.ObjectManager`](
+https://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager)
+interface.
+
+### properties
+Settings are accessed using the standard [`org.freedesktop.DBus.Properties`](
+https://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties)
+interface.
+
+### namespace
+| path | required | description |
+| -------------------------------------- | -------- | ----------------------- |
+| `/org/openbmc/settings/host<instance>` | No | Any host settings instances must be instantiated in the settings namespace. |
+
+`org.openbmc.Watchdog`
+----------------------
+The Watchdog interface enables health monitoring applications to offload timer
+bookeeping to another application.
+
+### methods
+| name | in signature | out signature | description |
+| ------- | ------------ | ------------- | ------------------------------ |
+| `start` | `void` | `void` | **Start the countdown timer.** |
+| `poke` | `void` | `void` | **Ping the watchdog.** |
+| `stop` | `void` | `void` | **Stop the countdown timer.** |
+| `set` | `i` | `void` | **Set the timer interval.** |
+| | `i` | | The timer interval. |
+
+### signals
+| name | signature | description |
+| --------------- | --------- | ---------------------------------------- |
+| `WatchdogError` | `void` | *The watchdog was not pinged before the timer expired.**|
+
+### namespace
+| path | required | description |
+| -------------------------------- | -------- | ---------------------------------------- |
+| `/org/openbmc/watchdog/<watchdog>` | No | Any watchdog instances must be instantiated in the watchdog namespace. |
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.
diff --git a/rest-api.md b/rest-api.md
index 935c929..10b01e9 100644
--- a/rest-api.md
+++ b/rest-api.md
@@ -1,119 +1,188 @@
# OpenBMC REST API
+The primary management interface for OpenBMC is REST. This document provides
+some basic structure and usage examples for the REST interface.
+
+The schema for the rest interface is directly defined by the OpenBMC dbus
+structure. Therefore, the objects, attributes and methods closely map to those
+in the dbus schema.
+
+For a quick explanation of HTTP verbs and how they relate to a RESTful API, see
+<http://www.restapitutorial.com/lessons/httpmethods.html>.
+
## Logging in
+
Before you can do anything you first need to log in:
-```
-curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST https://bmc/login -d "{\"data\": [ \"root\", \"0penBmc\" ] }"
-```
+
+ curl -c cjar -k -X POST -H "Content-Type: application/json" \
+ -d '{"data": [ "root", "0penBmc" ] }' \
+ https://bmc/login
+
+
+This performs a login using the provided username and password, and stores the
+newly-acquired authentication credentials in the `curl` "Cookie jar" file (named
+`cjar` in this example). We will use this file (with the `-b` argument) for
+future requests.
To log out:
-```
-curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST https://bmc/logout -d "{\"data\": [ ] }"
-```
-You need to use the provided cookie on any subsequent requests with the -c and -b options.
+ curl -c cjar -b cjar -k -X POST -H "Content-Type: application/json" \
+ -d '{"data": [ ] }' \
+ https://bmc/logout
-## HTTP GET operations
-List directory:
-```
-curl -c cjar -b cjar -k https://bmc/<path>/
-```
-Examples:
-```
-curl -c cjar -b cjar -k https://bmc/
-curl -c cjar -b cjar -k https://bmc/org/
-curl -c cjar -b cjar -k https://bmc/org/openbmc/
-curl -c cjar -b cjar -k https://bmc/org/openbmc/inventory/
-curl -c cjar -b cjar -k https://bmc/org/openbmc/inventory/system/chassis/
-```
+(or just delete your cookie jar file)
-List objects recursively:
-```
-curl -c cjar -b cjar -k https://bmc/<path>/list
-```
-Examples:
-```
-curl -c cjar -b cjar -k https://bmc/list
-curl -c cjar -b cjar -k https://bmc/org/openbmc/inventory/list
-```
+## HTTP GET operations & URL structure
-Enumerate objects recursively:
-```
-curl -c cjar -b cjar -k https://bmc/<path>/enumerate
-```
-Examples:
-```
-curl -c cjar -b cjar -k https://bmc/enumerate
-curl -c cjar -b cjar -k https://bmc/org/openbmc/inventory/enumerate
+There are a few conventions on the URL structure of the OpenBMC rest interface.
+They are:
-```
+ - To query the attributes of an object, perform a GET request on the object
+ name, with no trailing slash. For example:
-Get object:
-```
-curl -c cjar -b cjar -k https://bmc/<path>
-```
-Examples:
-```
-curl -c cjar -b cjar -k https://bmc/org/openbmc/inventory/system/chassis/fan2
-```
+ $ curl -b cjar -k https://bmc/org/openbmc/inventory/system
+ {
+ "data": {
+ "Asset Tag": [],
+ "Custom Field 1": "\tbuildroot-dcb6dc3",
+ "Custom Field 2": "\tskiboot-5.1.15",
+ "Custom Field 3": "\thostboot-c223637-017f5fd",
+ "Custom Field 4": "\tlinux-4.4.6-openpower1-2291fe8",
+ "Custom Field 5": "\tpetitboot-72928ed-a75299d",
+ "Custom Field 6": "\tpalmetto-xml-8281868-6b8b2bb",
+ "Custom Field 7": "\tocc-1093bf9",
+ "Custom Field 8": "\thostboot-binaries-7f593a3",
+ "FRU File ID": [],
+ "Manufacturer": [],
+ "Model Number": [],
+ "Name": "OpenPOWER Firmware",
+ "Serial Number": [],
+ "Version": "open-power-palmetto-5a4a3d9",
+ "fault": "False",
+ "fru_type": "SYSTEM",
+ "is_fru": 1,
+ "present": "False",
+ "version": ""
+ },
+ "message": "200 OK",
+ "status": "ok"
+ }
-Get property:
-```
-curl -c cjar -b cjar -k https://bmc/<path>/attr/<attr>
-curl -c cjar -b cjar -k https://bmc/org/openbmc/inventory/system/chassis/fan2/attr/is_fru
-```
+ - To query a single attribute, use the `attr/<name>` path. Using the
+ `system` object from above, we can query just the `Name` value:
+
+ $ curl -b cjar -k https://bmc/org/openbmc/inventory/system/attr/Name
+ {
+ "data": "OpenPOWER Firmware",
+ "message": "200 OK",
+ "status": "ok"
+ }
+
+ - When a path has a trailing-slash, the response will list the sub objects of
+ the URL. For example, using the same object path as above, but adding a
+ slash:
+
+ $ curl -b cjar -k https://bmc/org/openbmc/inventory/system/
+ {
+ "data": [
+ "/org/openbmc/inventory/system/systemevent",
+ "/org/openbmc/inventory/system/chassis"
+ ],
+ "message": "200 OK",
+ "status": "ok"
+ }
+
+ This shows that there are two children of the `system/` object: `systemevent`
+ and `chassis`. This can be used with the base REST URL (ie., `http://bmc/`),
+ to discover all objects in the hierarchy.
+
+ - Performing the same query with `/list` will list the child objects
+ *recursively*.
+
+ $ curl -b cjar -k https://palm5-bmc/list
+ [output omitted]
+
+ - Adding `/enumerate` instead of `/list` will also include the attributes of
+ the listed objects.
+
## HTTP PUT operations
-PUT operations are for updating an existing resource ( an object or property ), or for creating a new resource when the client already knows where to put it.
-For a quick explanation of HTTP verbs and how they relate to a RESTful API see this page:
-```
-http://www.restapitutorial.com/lessons/httpmethods.html
-```
-These require a json formatted payload. To get an example of what that looks like:
-```
-curl -c cjar -b cjar -k https://bmc/org/openbmc/control/flash/bios > bios.json # - or -
-curl -c cjar -b cjar -k https://bmc/org/openbmc/control/flash/bios/attr/flasher_path > flasher_path.json
-```
+PUT operations are for updating an existing resource (an object or property), or
+for creating a new resource when the client already knows where to put it.
+These require a json formatted payload. To get an example of what that looks
+like:
-When turning around and sending these as requests, delete the message and status properties.
+ curl -b cjar -k \
+ https://bmc/org/openbmc/control/flash/bios > bios.json
-To make curl use the correct content type header use the -H option:
-```
-curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST -d <json> <url>
-```
-A put operation on an object requires a complete object. For partial updates there is PATCH but that is not implemented yet. As a workaround individual attributes are PUTable.
+or
-Make changes to the file and do a put (upload):
+ curl -b cjar -k \
+ https://bmc/org/openbmc/control/flash/bios/attr/flasher_path > flasher_path.json
-```
-curl -c cjar -b cjar -k -H "Content-Type: application/json" -X PUT -T bios.json https://bmc/org/openbmc/control/flash/bios
-curl -c cjar -b cjar -k -H "Content-Type: application/json" -X PUT -T flasher_path.json https://bmc/org/openbmc/control/flash/bios/attr/flasher_path
-```
+When turning around and sending these as requests, delete the message and status
+properties.
+
+To make curl use the correct content type header use the -H option to specify
+that we're sending JSON data:
+
+ curl -b cjar -k -H "Content-Type: application/json" -X POST -d <json> <url>
+
+A PUT operation on an object requires a complete object. For partial updates
+there is PATCH but that is not implemented yet. As a workaround individual
+attributes are PUTable.
+
+For example, make changes to the file and do a PUT (upload):
+
+
+ curl -b cjar -k -H "Content-Type: application/json" \
+ -X PUT -T bios.json \
+ https://bmc/org/openbmc/control/flash/bios
+
+ curl -b cjar -k -H "Content-Type: application/json" \
+ -X PUT -T flasher_path.json \
+ https://bmc/org/openbmc/control/flash/bios/attr/flasher_path
+
Alternatively specify the json inline with -d:
-```
-curl -c cjar -b cjar -k -H "Content-Type: application/json" -X PUT -d "{\"data\": <value>}" flasher_path.json https://bmc/org/openbmc/control/flash/bios/attr/flasher_path
-```
-When using '-d' Just remember that json requires double quotes and any shell metacharacters need to be escaped.
+ curl -b cjar -k -H "Content-Type: application/json" -X PUT
+ -d '{"data": <value>}' \
+ https://bmc/org/openbmc/control/flash/bios/attr/flasher_path
+
+When using '-d' just remember that json requires quoting.
## HTTP POST operations
-POST operations are for calling methods, but also for creating new resources when the client doesn't know where to put it. OpenBMC does not support creating new resources via REST so any attempt to create a new resource will result in a HTTP 403 ( Forbidden ).
+POST operations are for calling methods, but also for creating new resources
+when the client doesn't know where to put it. OpenBMC does not support creating
+new resources via REST so any attempt to create a new resource will result in a
+HTTP 403 (Forbidden).
+
These also require a json formatted payload.
To invoke a method with parameters:
-```
-curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST -d "{\"data\": [<positional-parameters>]}" https://bmc/org/openbmc/control/fan0/action/setspeed
-```
+
+ curl -b cjar -k -H "Content-Type: application/json" -X POST \
+ -d '{"data": [<positional-parameters>]}' \
+ https://bmc/org/openbmc/control/fan0/action/setspeed
+
To invoke a method without parameters:
-```
-curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST -d "{\"data\": []}" https://bmc/org/openbmc/control/fan0/action/getspeed
-```
+
+ curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST \
+ -d '{"data": []}' \
+ https://bmc/org/openbmc/control/fan0/action/getspeed
+
## HTTP DELETE operations
-DELETE operations are for removing instances. Only DBUS objects (instances) can be removed. If the underlying DBUS object implements the org.openbmc.Object.Delete interface the REST server will call it. If org.openbmc.Object.Delete is not implemented, HTTP 403 will be returned.
+DELETE operations are for removing instances. Only DBUS objects (instances) can
+be removed. If the underlying DBUS object implements the
+`org.openbmc.Object.Delete` interface the REST server will call it. If
+`org.openbmc.Object.Delet`e is not implemented, the REST server will return a
+HTTP 403 (Forbidden) error.
-```
-curl -c cjar -b cjar -k -X DELETE https://bmc/org/openbmc/events/record/0
-```
+For example, to delete the event record with ID 0:
+
+ curl -b cjar -k -X DELETE \
+ https://bmc/org/openbmc/events/record/0
+
diff --git a/userguide/userguide.tex b/userguide/userguide.tex
new file mode 100644
index 0000000..5c7287c
--- /dev/null
+++ b/userguide/userguide.tex
@@ -0,0 +1,30 @@
+\documentclass[]{article}
+
+% fonts: libertine for roman text, inconsolata for monospace
+\usepackage{fontspec}
+\setmainfont{Linux Libertine O}
+\setmonofont{Inconsolata}
+
+% page layout: full page, no paragraph indent
+\usepackage{fullpage}
+\usepackage{parskip}
+
+% document metadata
+\usepackage{hyperref}
+\hypersetup{
+ pdftitle={OpenBMC User’s Guide},
+ colorlinks=true,
+ urlcolor=blue
+}
+
+\begin{document}
+
+\title{OpenBMC User's Guide}
+\maketitle
+
+\input{rest-api}
+\input{host-management}
+\input{console}
+\input{code-update}
+
+\end{document}