xref: /openbmc/sdbusplus/docs/yaml/interface.md (revision 3baa3045)
1# Interface YAML
2
3D-Bus interfaces can be defined by creating a YAML file to describe the methods,
4properties, and signals they contain. From this YAML file, both documentation
5and binding code may be generated.
6
7## YAML sections
8
9An interface YAML may have the following sections:
10
11- description
12  - A small documentation section describing the purpose of the interface.
13- methods
14  - A list of methods provided by this D-Bus interface.
15- properties
16  - A list of properties provided by this D-Bus interface.
17- signals
18  - A list of signals generated by this D-Bus interface.
19- enumerations
20  - A list of enumerations defined by this D-Bus interface.
21- paths
22  - A list of D-Bus paths where this D-Bus interface will be implemented.
23- service_names
24  - A default service name or a list of service names which can host this D-Bus
25    interface.
26
27## Enumerations
28
29A common problem we have found with D-Bus interfaces is having a consistent way
30to define enumerations. Two common practices are to either assign special
31meaning to integers, as a C compiler might do, or to have specific strings
32representing the enumeration name. The [D-Bus API design
33guidelines][dbus-design-guidelines] specify both of these options:
34
35> For APIs being used in constrained situations, enumerated values should be
36> transmitted as unsigned integers. For APIs which need to be extended by third
37> parties or which are used in more loosely coupled systems, enumerated values
38> should be strings in some defined format.
39
40What we have done in `sdbus++` is to consider enumerations as a first-class
41type. Within an interface you can define an enumeration and the bindings will
42have a C++ enumeration defined for it. At a D-Bus level any property or method
43parameter will be a string, but the string will contain a fully-qualified name
44"interface.enum-name.enum-value" like "org.freedesktop.Example.Color.Red".
45Within the generated bindings, an automatic conversion is done between strings
46and C++ enumeration values and clients will get an
47"xyz.openbmc_project.sdbusplus.Error.InvalidEnumString" error response if they
48attempt to use an invalid string value.
49
50An enumeration must have the YAML properties `name` and `values` and may
51optionally contain a `description`. The `name` is a word corresponding to the
52desired "enum-name" portion of the fully-qualified name and the resulting C++
53enum type. The `values` are a list of enumeration values each containing their
54own `name` and optional `description`.
55
56Example:
57
58```yaml
59enumerations:
60  - name: Suits
61    description: >
62      The suits found in a deck of cards.
63    values:
64      - name: Diamonds
65      - name: Hearts
66      - name: Clubs
67        description: >
68          This is the suit that looks like a clover.
69      - name: Spades
70```
71
72## Types
73
74### Base types
75
76Types are identified in YAML using their typename found in the [D-Bus
77specification][dbus-spec], but listed using lowercases: `int64` instead of
78`INT64` or C++ `int64_t`.
79
80- `byte`
81- `boolean`
82- `int16`
83- `uint16`
84- ...
85- `uint64`
86- `size` - maps to the C `size_t` for the architecture.
87- `ssize` - maps to the C `ssize_t` for the architecture.
88- `double`
89- `unixfd`
90- `string`
91- `object_path`
92- `signature`
93
94### Special type values
95
96Note: The special value identifiers are all case-insensitive.
97
98For floating-point types it is possible to express one of the special values:
99
100- `NaN` - A quiet-type not-a-number value.
101- `Infinity` : A positive infinity value.
102- `-Infinity` : A negative infinity value.
103- `Epsilon` : An epsilon value.
104
105For integer types it is possible to express one of the special values:
106
107- `minint` - The minimum value the integer type can hold.
108- `maxint` - The maximum value the integer type can hold.
109
110### Container Types
111
112Container types can also be expressed, but the contained-type should be
113expressed within square-brackets `[]`. The following containers are supported:
114
115- `array[type]`
116  - C++ type is `std::vector`
117- `dict[keytype, valuetype]`
118  - C++ type is `std::map`
119- `set[type]`
120  - C++ type is `std::set`
121- `struct[type0, type1, ...]`
122  - C++ type is `std::tuple`
123- `variant[type0, type1, ...]`
124  - C++ type is `std::variant`
125
126It may seem odd that variants are required to list the types they may contain,
127but this is due to C++ being a strongly-typed language. In order to generate
128bindings, to read from and append to a message, the binding generator must know
129all possible types the variant may contain.
130
131### Enumeration Types
132
133Enumerations are expressed like a container, but the contained-type is an
134identifier of the fully-qualified enum-name or a shortened `self.` identifier
135for locally defined types.
136
137- enum[org.freedesktop.Example.Suits]
138- enum[self.Suits]
139
140## Methods
141
142A method must have the YAML property `name` and may optionally have
143`parameters`, `returns`, `flags`, `errors`, and `description`. Each parameter
144must have a `name`, `type`, and optional `description`. Each return must have a
145`type` and may optionally have a `name` and `description`. Flags are a list of
146sd-bus vtable flags; the supported values are `deprecated`, `hidden`,
147`unprivileged`and `no_reply`, which corresponds to `SD_BUS_VTABLE_DEPRECATED`,
148`SD_BUS_VTABLE_HIDDEN`, `SD_BUS_VTABLE_UNPRIVILEGED`,
149`SD_BUS_VTABLE_METHOD_NO_REPLY`, respectively. Errors are a list of
150fully-qualified or shortened `self.` identifiers for errors the method may
151return, which must be defined in a corresponding errors YAML file.
152
153Example:
154
155```yaml
156methods:
157  - name: Shuffle
158    flags:
159      - unprivileged
160    errors:
161      - self.Error.TooTired
162  - name: Deal
163    description: >
164      Deals a new hand to each player.
165    errors:
166      - self.Error.OutOfCards
167  - name: LookAtTop
168    returns:
169      - name: Card
170        type: struct[enum[self.Suit], byte]
171  - name: MoveToTop
172    flags:
173      - deprecated
174      - no_reply
175    parameters:
176      - name: Card
177        type: struct[enum[self.Suit], byte]
178```
179
180## Properties
181
182A property must have the YAML property `name` and `type` and may optionally have
183`description`, `flags`, `default`, and `errors`. The `default` defines the
184default value of the property. See the `Methods` section above for more
185information on errors.
186
187The supported values for `flags` are and their equivalent sd-bus flag setting:
188
189- `deprecated` - SD_BUS_VTABLE_DEPRECATED
190- `hidden` - SD_BUS_VTABLE_HIDDEN
191- `unprivileged` - SD_BUS_VTABLE_UNPRIVILEGED
192- `const` - SD_BUS_VTABLE_PROPERTY_CONST
193- `emits_change` - SD_BUS_VTABLE_PROPERTY_EMITS_CHANGE
194- `emits_invalidation` - SD_BUS_VTABLE_PROPERTY_EMITS_INVALIDATION
195- `explicit` - SD_BUS_VTABLE_PROPERTY_EXPLICIT
196- `readonly` - (N/A)
197
198If no flag is given, a property will default to `emits_change`.
199
200Both `const` and `readonly` prevent D-Bus clients from being able to write to a
201property. `const` is a D-Bus indication that the property can never change,
202while `readonly` properties can be changed by the D-Bus server itself. As
203examples, the `Version` property on a software object might be appropriate to be
204`const` and the `Value` property on a sensor object would likely be `readonly`.
205
206Example:
207
208```yaml
209properties:
210  - name: CardsRemaining
211    type: uint32
212    default: 52
213    flags:
214      - const
215    description: >
216      The number of cards remaining in the deck.
217    errors:
218      - self.Error.InvalidNumber
219```
220
221## Signals
222
223A signal must have the YAML property `name` and may optionally have a
224`description` and list of `properties`. Properties are specified the same as
225interface properties.
226
227Example:
228
229```yaml
230signals:
231  - name: Shuffled
232    description: >
233      The deck has been shuffled.
234  - name: Cheated
235    properties:
236      - name: CardToTop
237        type: struct[enum[self.Suit], byte]
238```
239
240[dbus-design-guidelines]: https://dbus.freedesktop.org/doc/dbus-api-design.html
241[dbus-spec]: https://dbus.freedesktop.org/doc/dbus-specification.html
242
243## Paths
244
245A path must have the YAML property `name` & `value` and may optionally have a
246`description` and `segments`. Each `segments` entry must have the YAML property
247`name` & `value` and may optionally have a `description` & nested `segments`.
248
249Example:
250
251```yaml
252paths:
253  - name: CardGames
254    description: >
255      The root path for the card games.
256    value: /xyz/openbmc_project/card_games
257    segments:
258      - name: BlackJack
259        description: >
260          The relative path for the black jack game.
261        value: black_jack
262      - name: Rummy
263        description: >
264          The relative path for the rummy game.
265        value: rummy
266```
267
268A common approach is to have a single path which is used as a root of all
269instances, which is often documented as a "namespace". For convenience, this can
270be represented with a single `namespace` value. If the interface is intended to
271be used as a singleton at a specific object path, similarly the `instance` value
272can be used.
273
274Example:
275
276```yaml
277paths:
278  - namespace: /xyz/openbmc_project/decks
279    description: >
280      The root path for all decks.
281  - instance: /xyz/openbmc_projects/decks/standard
282    description: >
283      The root path for a standard deck of cards.
284```
285
286## Service Name
287
288An interface can be implemented either by a single service or multiple services.
289
290### Singleton host service name
291
292A singleton host service name must have the YAML property `default` and may
293optionally have a `description`. `xyz.openbmc_project.ObjectMapper` is one such
294example.
295
296Example:
297
298```yaml
299service_names:
300  default: xyz.openbmc_project.deck
301  description: >
302    The service name for the card deck manager.
303```
304
305### Multiton host service names
306
307A multiton host service name must have the YAML property `name` & `value` and
308may optionally have a `description`.
309
310Example:
311
312```yaml
313service_names:
314  - name: BlackJack
315    description: >
316      The service name for the Back Jack game manager.
317    value: xyz.openbmc_project.black_jack
318  - name: Rummy
319    description: >
320      The service name for rummy game manager.
321    value: xyz.openbmc_project.rummy
322```
323