OpenBMC DBUS API

This document aims to specify the OpenBMC DBUS API.

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.

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.

The OpenBMC DBUS API is still alpha. If you have questions or suggestions please let the community know.

`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.

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.

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.

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.

`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.

methods

name	in signature	out signature	description
`SoftPowerOff`	`void`	`x`	Prepare the host processor firmware for an orderly shutdown.
		`x`	The result status.

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

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.

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.

namespace

path	required	description
`/org/openbmc/inventory/<item>`	No	Inventory items must be instantiated in the inventory namespace.

`org.openbmc.NetworkManager`

The NetworkManager interface allows applications to examine and manipulate network settings.

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`	?

namespace

path	required	description
`/org/openbmc/NetworkManager/Interface`	Yes on systems with the network machine feature, otherwise no.	?

`org.openbmc.Sensors`

The Sensors interface allows applications to register a sensor instance with a sensor management application.

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.

namespace

path	required	description
`/org/openbmc/sensors`	Yes	The sensor manager must be instantiated here.

`org.openbmc.HwmonSensor`

The HwmonSensor interface allows applications to query and manipulate hwmon based sensors.

methods

name	in signature	out signature	description
`setByPoll`	`v`	`(bv)`	?
	`v`		?
		`(bv)`	?

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.

`org.openbmc.SensorThresholds`

The SensorThreshold interface allows applications to query and manipulate sensors thresholds.

methods

name	in signature	out signature	description
`resetThresholdState`	`void`	`void`	?

signals

name	signature	description
`Emergency`	`void`	?

properties

name	signature	description
`thresholds_enabled`	`?`	?
`emergency_enabled`	`?`	?
`warning_upper`	`?`	?
`warning_lower`	`?`	?
`critical_upper`	`?`	?
`critical_lower`	`?`	?
`threshold_state`	`?`	?
`worst_threshold_state`	`?`	?

namespace

path	required	description
`/org/openbmc/sensors/<class>/<sensor>`	No	Any sensor instances must be instantiated in the sensors namespace.

`org.openbmc.SensorValue`

The SensorValue interface allows applications to query and manipulate sensors that only provide a value.

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.

properties

name	signature	description
`units`	`s`	The units associated with the sensor value.
`error`	`?`	?

namespace

path	required	description
`/org/openbmc/sensors/<class>/<sensor>`	No	Any sensor instances must be instantiated in the sensors namespace.

`org.openbmc.Button`

The Button interface allows applications to query the state of buttons.

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.

signals

name	signature	description
`Released`	`void`	The button was released.
`Pressed`	`void`	The button was pressed.
`PressedLong`	`void`	The button was pressed and held.

properties

name	signature	description
`state`	`b`	The current button state.

namespace

path	required	description
`/org/openbmc/buttons/<button>`	No	Any button instances must be instantiated in the buttons namespace.

`org.openbmc.control.Bmc`

The control.Bmc interface allows applications control the BMC.

methods

name	in signature	out signature	description
`warmReset`	`void`	`void`	Reset the BMC.

namespace

path	required	description
`/org/openbmc/control/bmc<instance>`	Yes	Any BMC control instances must be instantiated in the control namespace.

`org.openbmc.managers.Download`

The managers.Download interface allows applications to receive file download notifications.

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.

namespace

path	required	description
`/org/openbmc/managers/Download`	?	?

`org.openbmc.control.BmcFlash`

The control.BmcFlash interface allows applications update the BMC firmware.

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.
`update`	`s`	`void`	Perform a BMC firmware update with a file already on the BMC.
	`s`		The name of the file containing the BMC firmware image.
`PrepareForUpdate`	`void`	`void`	Reboot BMC with Flash content cached in RAM.
`Abort`	`void`	`void`	Abort any pending, broken, or in-progress flash update.
`Apply`	`void`	`void`	Initiate writing image to flash.
`GetUpdateProgress`	`void`	`s`	Display progress log `Apply` phase.
		`s`	The `status` and log output from `Apply`

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.

properties

name	signature	description
`status`	`s`	Description of the phase of the update.
`filename`	`s`	The name of the file containing the BMC firmware image.
`preserve_network_settings`	`b`	Perform a factory reset.
`restore_application_defaults`	`b`	Clear modified files in read-write filesystem.
`update_kernel_and_apps`	`b`	Do not update bootloader (requires image pieces).
`clear_persistent_files`	`b`	Also remove persistent files when updating read-write filesystem.
`auto_apply`	`b`	Attempt to apply image after unpacking (cleared if image verification fails).

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.

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.

properties

name	signature	description
`uuid`	`s`	The chassis UUID.

namespace

path	required	description
`/org/openbmc/control/chassis<instance>`	?	Any chassis control instances must be instantiated in the control namespace.

`org.openbmc.Flash`

The Flash interface allows applications update the host firmware.

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.

signals

name	signature	description
`Updated`	`void`	?
`Download`	`ss`	?
	`s`	The TFTP server url.
	`s`	The file containing the host firmware image.

properties

name	signature	description
`filename`	`s`	?
`flasher_path`	`s`	?
`flasher_name`	`s`	?
`flasher_instance`	`s`	?
`status`	`s`	?

namespace

path	required	description
?	?	?

`org.openbmc.SharedResource`

Insert description of the SharedResource interface here.

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.

properties

name	signature	description
`lock`	`b`	The lock state.
`name`	`s`	The shared resource name.

`org.openbmc.control.Host`

The control.Host interface allows applications to manipulate the host processor firmware.

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.

signals

name	signature	description
`Booted`	`void`	The host processor firmware was started.

properties

name	signature	description
`debug_mode`	`i`	?
`flash_side`	`s`	?

namespace

path	required	description
`/org/openbmc/control/host<instance>`	No	Any host control instances must be instantiated in the control namespace.

`org.openbmc.control.Power`

Insert a description of the control.Power interface here.

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.

signals

name	signature	description
`PowerGood`	`void`	The power is on.
`PowerLost`	`void`	The power is off.

properties

name	signature	description
`pgood`	`i`	?
`state`	`i`	?
`pgood_timeout`	`i`	?

namespace

path	required	description
`/org/openbmc/control/power<instance>`	?	Any power control instances must be instantiated in the control namespace.

`org.openbmc.Led`

Insert a description of the Led interface here.

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.

properties

name	signature	description
`color`	`i`	The color of the LED.
`function`	`s`	?
`state`	`s`	The current LED state.

namespace

path	required	description
`/org/openbmc/control/led/<led>`	No	Any LED instances must be instantiated in the control/led namespace.

`org.openbmc.objectmapper.ObjectMapper`

The ObjectMapper interface enables applications to discover the DBUS unique connection name(s) for a given object path.

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.

namespace

path	required	description
`/org/openbmc/objectmapper/objectmapper`	Yes	The object mapper must be instantiated here.

`org.openbmc.recordlog`

Insert a description of the record log interface here.

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`	?

namespace

path	required	description
`/org/openbmc/records/<class>`	No	Any recordlog instances must be instantiated in the records namespace.

`org.openbmc.record`

Insert a description of the record interface here.

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.

namespace

path	required	description
`/org/openbmc/records/<class>/<record>`	No	Records must be instantiated in the records namespace.

`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.

methods

name	in signature	out signature	description
`delete`	`void`	`void`	Remove the object from the DBUS namespace.

`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.

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.

For example, given an object /org/openbmc/events/1 that implements org.openbmc.Associations and then sets the associations property to:

"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

`org.openbmc.Association`

Applications use this interface to inject associations into the DBUS namespace.

properties

name	signature	description
`endpoints`	`as`	An array of association endpoints.

For example, given:

"/org/openbmc/events/1/frus": {
    "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

`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 interface.

signals

Applications are notified of host setting changes using the standard org.freedesktop.DBus.ObjectManager interface.

properties

Settings are accessed using the standard org.freedesktop.DBus.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.

Files

dbus-interfaces.md

Latest commit

History

dbus-interfaces.md

File metadata and controls

OpenBMC DBUS API

org.openbmc.HostIpmi

methods

signals

namespace

org.openbmc.HostServices

methods

namespace

org.openbmc.InventoryItem

methods

properties

namespace

org.openbmc.NetworkManager

methods

namespace

org.openbmc.Sensors

methods

namespace

org.openbmc.HwmonSensor

methods

properties

namespace

org.openbmc.SensorThresholds

methods

signals

properties

namespace

org.openbmc.SensorValue

methods

properties

namespace

org.openbmc.Button

methods

signals

properties

namespace

org.openbmc.control.Bmc

methods

namespace

org.openbmc.managers.Download

signals

namespace

org.openbmc.control.BmcFlash

methods

signals

properties

namespace

org.openbmc.control.Chassis

methods

properties

namespace

org.openbmc.Flash

methods

signals

properties

namespace

org.openbmc.SharedResource

methods

properties

org.openbmc.control.Host

methods

signals

properties

namespace

org.openbmc.control.Power

methods

signals

properties

namespace

org.openbmc.Led

methods

properties

namespace

org.openbmc.objectmapper.ObjectMapper

`org.openbmc.HostIpmi`

`org.openbmc.HostServices`

`org.openbmc.InventoryItem`

`org.openbmc.NetworkManager`

`org.openbmc.Sensors`

`org.openbmc.HwmonSensor`

`org.openbmc.SensorThresholds`

`org.openbmc.SensorValue`

`org.openbmc.Button`

`org.openbmc.control.Bmc`

`org.openbmc.managers.Download`

`org.openbmc.control.BmcFlash`

`org.openbmc.control.Chassis`

`org.openbmc.Flash`

`org.openbmc.SharedResource`

`org.openbmc.control.Host`

`org.openbmc.control.Power`

`org.openbmc.Led`

`org.openbmc.objectmapper.ObjectMapper`

`org.openbmc.recordlog`

`org.openbmc.record`

`org.openbmc.Object.Delete`

`org.openbmc.Associations`

`org.openbmc.Association`

`org.openbmc.settings.Host`

`org.openbmc.Watchdog`