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