search

openbmc / docs

OpenBMC Documentation
Creative Commons Attribution 4.0 International
277 stars 307 forks source link

Take a stab at a proper DBUS API document. #25

Closed bradbishop closed 8 years ago

bradbishop commented 8 years ago

Changed the main structure to be interface based rather than topic based. Each interface should have a methods, signals properties and namespace section with a table and option free form examples or additional overview information. If an interface doesn't have any properties, methods or signals those sections can be omitted.

The namespace section outlines where objects implementing certain interfaces are expected to be found.

There are a number of things that still need to be filled out.

This change is Reviewable

causten commented 8 years ago

Review status: 0 of 1 files reviewed at latest revision, 4 unresolved discussions.

dbus-interfaces.md, line 50 [r1] (raw file):

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

n: you did not specify where n comes from. The tag does not translate in md. maybe you need ?

_dbus-interfaces.md, line 62 [r1] (raw file):_

| ------------ | ------------ | ------------- | ---------------------------------------- |
| SoftPowerOff | void         | x             | Prepare the host processor firmware for an orderly shutdown. |
|              |              | x             | The result status.                       |

x would be a negative number for bad results, positive for good? Will need someone to define that

dbus-interfaces.md, line 81 [r1] (raw file):

| ---------- | ------------ | ------------- | ----------------------------- |
| setPresent | s            | void          | Indicate the item is present. |
|            | s            |               | true or false                 |

I looked at the code, the first letter is capitalized

dbus-interfaces.md, line 192 [r1] (raw file):

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

those angled brackets do not show up on the web. HTML must want to use them. perhaps the hexcode for them ?

Comments from Reviewable

jk-ozlabs commented 8 years ago

Awesome, merged. Thanks!