1# Requirements and Expectations for dbus interfaces
2
3This document outlines requirements and expectations for dbus interfaces. These
4are usually specified as requirements due to our dbus architecture or for
5consistency 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 parsed
22by code. Any arbitrary string is typically expected to have a description such
23as "... can be shown in user interfaces but this field should not be used for
24any 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 flow
29across 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 that
34the values contained within are to be sdbusplus-enumerations of a specific
35pattern. See the [software compatibility][software-compat] and [dump
36interface][dump-interface] as two current examples of this.
37
38[software-compat]:
39  https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Software/README.md#compatibility
40[dump-interface]:
41  https://github.com/openbmc/phosphor-dbus-interfaces/blob/991b2b8bdbc950f2a85aebfc29d1b34ea3264686/yaml/xyz/openbmc_project/Dump/Create.interface.yaml#L25
42
43## Interfaces
44
45## Methods
46
47## Properties
48
49## Signals
50
51## Associations
52
53There are typically two types of associations we use:
54
55- Peer associations.
56- Directed associations.
57
58Peer associations are rare, but are used to link a single entity that is
59required to be represented in different dbus path hierarchies due to some
60overriding aspect of the dbus design.
61
62Directed associations are more common and are used to show a relationship
63between two different entities. Though it may at times feel contrived, directed
64associations should be considered to have a "primary" and "secondary" end, which
65helps establish a pattern for naming consistency. For example, a chassis might
66be "containing" (primary) any number of other inventory objects which are
67"contained_by" (secondary) the chassis.
68
69### Peer associations should be named with hierarchy names
70
71Consider an entity which is contained at `/.../foo/entity` and
72`/.../bar/entity`. The association is what links the `foo` and `bar` aspects of
73the entity in the dbus path hierarchy. Accordingly, the association should be
74named with end-points "foo" and "bar".
75
76A made-up example of a peer association might be a `Inventory.Processor`,
77located under the `.../inventory` hierarchy, and a `Control.Power.Cap` for that
78processor, located under the `.../control` hierarchy. The peer association
79allows traversal between the `inventory` and `control` namespaces for the single
80Processor entity.
81
82### Directed associations should not codify type
83
84The end-point names of an association should not codify the types of the
85interfaces pointed to by the association.
86
87- Bad: powered_processor
88- Good: powering
89
90### Directed associations should be named with participle verbs
91
92The primary relationship should be a verb with a Present Participle tense
93(ending in '-ing'). The secondary relationship should be a verb with a Past
94Participle tense (typically ending in '-ed').
95
96The association end-points should be named in a way that the following sentences
97are grammatically correct:
98
99- The `{primary element}` is `{primary association}` the `{secondary element}`.
100- The `{secondary element}` is `{secondary association}` the
101  `{primary element}`.
102
103These correspond to the mapper D-Bus object paths
104`{primary element}/{primary association}` with an endpoints property value of
105`{secondary element}` and `{secondary element}/{secondary association}` with an
106endpoints property value of `{primary element}`.
107
108In some cases it may be required for grammatical correctness to add a
109preposition to the secondary association, such as 'by' or 'with'.
110
111Additional information on associations is in the [mapper documentation][].
112
113[mapper documentation]:
114  https://github.com/openbmc/docs/blob/master/architecture/object-mapper.md#associations
115