1# Requirements and Expectations for dbus interfaces
2
3This document outlines requirements and expectations for dbus interfaces.
4These are usually specified as requirements due to our dbus architecture
5or for consistency in implementations.
6
7## General
8
9### Prefer `size` and `uint64`/`int64` over explicit sizes
10
11Do not over-optimize properties by selecting explicit sizes such as `uint8`
12unless there is a strong basis for it (usually driven by hardware or another
13protocol's specification).
14
15For countable entities always prefer `size`, which are an sdbusplus implemented
16type that maps to the C equivalent of `size_t` on the architecture.  For
17non-countable values prefer `uint64` or `int64`.
18
19### Avoid use of arbitrary strings
20
21Arbitrary strings should only be utilized for human consumption and never
22parsed by code. Any arbitrary string is typically expected to have a
23description such as "... can be shown in user interfaces but this field should
24not be used for any programmatic interrogation of an object".
25
26### Leverage enumerations instead of strings or magic values
27
28The sdbusplus implementation has built-in support for enumerations, which
29flow across the dbus as uniquely encoded string values but has support in the
30bindings for automatically converting to a C++ enum type.
31
32In some cases it is useful to have hardware-specific or OEM values for
33enumerations. In those cases a property may be a string, but should specify
34that the values contained within are to be sdbusplus-enumerations of a specific
35pattern. See the [software compatiblity][software-compat] and
36[dump interface][dump-interface] as two current examples of this.
37
38[software-compat]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Software/README.md#compatibility
39[dump-interface]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/991b2b8bdbc950f2a85aebfc29d1b34ea3264686/yaml/xyz/openbmc_project/Dump/Create.interface.yaml#L25
40
41## Interfaces
42
43## Methods
44
45## Properties
46
47## Signals
48
49## Associations
50
51There are typically two types of associations we use:
52
53- Peer associations.
54- Directed associations.
55
56Peer associations are rare, but are used to link a single entity that is
57required to be represented in different dbus path hierarchies due to some
58overriding aspect of the dbus design.
59
60Directed associations are more common and are used to show a relationship
61between two different entities. Though it may at times feel contrived,
62directed associations should be considered to have a "primary" and "secondary"
63end, which helps establish a pattern for naming consistency.  For example, a
64chassis might be "containing" (primary) any number of other inventory objects
65which are "contained_by" (secondary) the chassis.
66
67### Peer associations should be named with hierarchy names
68
69Consider an entity which is contained at `/.../foo/entity` and
70`/.../bar/entity`. The association is what links the `foo` and `bar` aspects
71of the entity in the dbus path hierarchy. Accordingly, the association should
72be named with end-points "foo" and "bar".
73
74A made-up example of a peer association might be a `Inventory.Processor`,
75located under the `.../inventory` hierarchy, and a `Control.Power.Cap` for that
76processor, located under the `.../control` hierarchy.  The peer association
77allows traversal between the `inventory` and `control` namespaces for the
78single Processor entity.
79
80### Directed associations should not codify type
81
82The end-point names of an association should not codify the types of the
83interfaces pointed to by the association.
84
85- Bad: powered_processor
86- Good: powering
87
88### Directed associations should be named with participle verbs
89
90The primary relationship should be a verb with a Present Participle tense
91(ending in '-ing'). The secondary relationship should be a verb with a Past
92Participle tense (typically ending in '-ed').
93
94The association end-points should be named in a way that the following
95sentences are grammatically correct:
96
97- The `{primary element}` is `{primary association}` the `{secondary element}`.
98- The `{secondary element}` is `{secondary association}` the
99  `{primary element}`.
100
101In some cases it may be required for grammatical correctness to add a
102preposition to the secondary assocation, such as 'by' or 'with'.
103