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