From e2415fa730a2b11e465d2453207281578c04dfd0 Mon Sep 17 00:00:00 2001 From: Ed Tanous Date: Wed, 7 Sep 2022 16:51:00 -0700 Subject: Write down the dbus->redfish conversion rules We have a lot of DBus rules that bmcweb tries to abide by because of history and maintainability reasons. These have never been well documented, which causes problems at review time, with maintainers having no place to point to. This commit attempts to write down the guidelines we aim to hit. Signed-off-by: Ed Tanous Change-Id: Icee6f4740d24a69fb2209a7e2c8586bc018ec29a --- DBUS_USAGE.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 DBUS_USAGE.md diff --git a/DBUS_USAGE.md b/DBUS_USAGE.md new file mode 100644 index 0000000000..354a79bb79 --- /dev/null +++ b/DBUS_USAGE.md @@ -0,0 +1,24 @@ +The following are guidelines for bmcweb's use of DBus to construct Redfish +schemas: + +- Do not require (ie set 500 internal error on) an implementation present a + property that wasn't in the first commit of the interface unless it can be + verified that _all_ OpenBMC implementers of the interface support that + property. +- If an implementation presents a property that doesn't match the type specified + by the interface at any version, it shall be repored as a 500 error. +- If the DBus interface definition has an "unknown" or "unspecified" value, + detecting these will omit the property from the Redfish tree, in line with the + Redfish specification. +- All DBus interfaces on all object paths are optional. An object missing an + interface is never an error, and shall simply omit the relevant properties + and/or actions from that Redfish Resource. +- bmcweb will code to the DBus interface itself. This means that daemons are + expected to handle functionally bad, but DBus-correct input in their own + process, and return appropriate return codes. This is done to reduce the + duplication in input processing between the various user-facing daemons. +- There are interfaces for which there is an expectation that there will only + ever be one producer in the project (ex bmc networking, user management). In + these cases, it is desirable to call the daemon by well known name directly. + Bmcweb APIs should call the mapper in cases where it's reasonably expected + that multiple implementations exist (ex, CPU management, Sensors). -- cgit v1.2.3