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 22## Enumerations 23 24A common problem we have found with D-Bus interfaces is having a consistent way 25to define enumerations. Two common practices are to either assign special 26meaning to integers, as a C compiler might do, or to have specific strings 27representing the enumeration name. The [D-Bus API design 28guidelines][dbus-design-guidelines] specify both of these options: 29 30> For APIs being used in constrained situations, enumerated values should be 31> transmitted as unsigned integers. For APIs which need to be extended by third 32> parties or which are used in more loosely coupled systems, enumerated values 33> should be strings in some defined format. 34 35What we have done in `sdbus++` is to consider enumerations as a first-class 36type. Within an interface you can define an enumeration and the bindings will 37have a C++ enumeration defined for it. At a D-Bus level any property or method 38parameter will be a string, but the string will contain a fully-qualified name 39"interface.enum-name.enum-value" like "org.freedesktop.Example.Color.Red". 40Within the generated bindings, an automatic conversion is done between strings 41and C++ enumeration values and clients will get an 42"xyz.openbmc_project.sdbusplus.Error.InvalidEnumString" error response if they 43attempt to use an invalid string value. 44 45An enumeration must have the YAML properties `name` and `values` and may 46optionally contain a `description`. The `name` is a word corresponding to the 47desired "enum-name" portion of the fully-qualified name and the resulting C++ 48enum type. The `values` are a list of enumeration values each containing their 49own `name` and optional `description`. 50 51Example: 52 53```yaml 54enumerations: 55 - name: Suits 56 description: > 57 The suits found in a deck of cards. 58 values: 59 - name: Diamonds 60 - name: Hearts 61 - name: Clubs 62 description: > 63 This is the suit that looks like a clover. 64 - name: Spades 65``` 66 67## Types 68 69### Base types 70 71Types are identified in YAML using their typename found in the [D-Bus 72specification][dbus-spec], but listed using lowercases: `int64` instead of 73`INT64` or C++ `int64_t`. 74 75- `byte` 76- `boolean` 77- `int16` 78- `uint16` 79- ... 80- `uint64` 81- `size` - maps to the C `size_t` for the architecture. 82- `ssize` - maps to the C `ssize_t` for the architecture. 83- `double` 84- `unixfd` 85- `string` 86- `object_path` 87- `signature` 88 89### Special type values 90 91Note: The special value identifiers are all case-insensitive. 92 93For floating-point types it is possible to express one of the special values: 94 95- `NaN` - A quiet-type not-a-number value. 96- `Infinity` : A positive infinity value. 97- `-Infinity` : A negative infinity value. 98- `Epsilon` : An epsilon value. 99 100For integer types it is possible to express one of the special values: 101 102- `minint` - The mininum value the integer type can hold. 103- `maxint` - The maximum value the integer type can hold. 104 105### Container Types 106 107Container types can also be expressed, but the contained-type should be 108expressed within square-brackets `[]`. The following containers are supported: 109 110- `array[type]` 111 - C++ type is `std::vector` 112- `dict[keytype, valuetype]` 113 - C++ type is `std::map` 114- `set[type]` 115 - C++ type is `std::set` 116- `struct[type0, type1, ...]` 117 - C++ type is `std::tuple` 118- `variant[type0, type1, ...]` 119 - C++ type is `std::variant` 120 121It may seem odd that variants are required to list the types they may contain, 122but this is due to C++ being a strongly-typed language. In order to generate 123bindings, to read from and append to a message, the binding generator must know 124all possible types the variant may contain. 125 126### Enumeration Types 127 128Enumerations are expressed like a container, but the contained-type is an 129identifier of the fully-qualified enum-name or a shortened `self.` identifier 130for locally defined types. 131 132- enum[org.freedesktop.Example.Suits] 133- enum[self.Suits] 134 135## Methods 136 137A method must have the YAML property `name` and may optionally have 138`parameters`, `returns`, `flags`, `errors`, and `description`. Each parameter 139must have a `name`, `type`, and optional `description`. Each return must have a 140`type` and may optionally have a `name` and `description`. Flags are a list of 141sd-bus vtable flags; the supported values are `deprecated`, `hidden`, 142`unprivileged`and `no_reply`, which corresponds to `SD_BUS_VTABLE_DEPRECATED`, 143`SD_BUS_VTABLE_HIDDEN`, `SD_BUS_VTABLE_UNPRIVILEGED`, 144`SD_BUS_VTABLE_METHOD_NO_REPLY`, respectively. Errors are a list of 145fully-qualified or shortened `self.` identifiers for errors the method may 146return, which must be defined in a corresponding errors YAML file. 147 148Example: 149 150```yaml 151methods: 152 - name: Shuffle 153 flags: 154 - unprivileged 155 errors: 156 - self.Error.TooTired 157 - name: Deal 158 description: > 159 Deals a new hand to each player. 160 errors: 161 - self.Error.OutOfCards 162 - name: LookAtTop 163 returns: 164 - name: Card 165 type: struct[enum[self.Suit], byte] 166 - name: MoveToTop 167 flags: 168 - deprecated 169 - no_reply 170 parameters: 171 - name: Card 172 type: struct[enum[self.Suit], byte] 173``` 174 175## Properties 176 177A property must have the YAML property `name` and `type` and may optionally have 178`description`, `flags`, `default`, and `errors`. The `default` defines the 179default value of the property. See the `Methods` section above for more 180information on errors. 181 182The supported values for `flags` are and their equivalent sd-bus flag setting: 183 184- `deprecated` - SD_BUS_VTABLE_DEPRECATED 185- `hidden` - SD_BUS_VTABLE_HIDDEN 186- `unprivileged` - SD_BUS_VTABLE_UNPRIVILEGED 187- `const` - SD_BUS_VTABLE_PROPERTY_CONST 188- `emits_change` - SD_BUS_VTABLE_PROPERTY_EMITS_CHANGE 189- `emits_invalidation` - SD_BUS_VTABLE_PROPERTY_EMITS_INVALIDATION 190- `explicit` - SD_BUS_VTABLE_PROPERTY_EXPLICIT 191- `readonly` - (N/A) 192 193If no flag is given, a property will default to `emits_change`. 194 195Both `const` and `readonly` prevent D-Bus clients from being able to write to a 196property. `const` is a D-Bus indication that the property can never change, 197while `readonly` properties can be changed by the D-Bus server itself. As 198examples, the `Version` property on a software object might be appropriate to be 199`const` and the `Value` property on a sensor object would likely be `readonly`. 200 201Example: 202 203```yaml 204properties: 205 - name: CardsRemaining 206 type: uint32 207 default: 52 208 flags: 209 - const 210 description: > 211 The number of cards remaining in the deck. 212 errors: 213 - self.Error.InvalidNumber 214``` 215 216## Signals 217 218A signal must have the YAML property `name` and may optionally have a 219`description` and list of `properties`. Properties are specified the same as 220interface properties. 221 222Example: 223 224```yaml 225signals: 226 - name: Shuffled 227 description: > 228 The deck has been shuffled. 229 - name: Cheated 230 properties: 231 - name: CardToTop 232 type: struct[enum[self.Suit], byte] 233``` 234 235[dbus-design-guidelines]: https://dbus.freedesktop.org/doc/dbus-api-design.html 236[dbus-spec]: https://dbus.freedesktop.org/doc/dbus-specification.html 237