docs: propose D-Bus paths and service-name format for interface yaml
This patch proposes format for adding D-Bus paths and service-name to
yaml interface files. The intent of this addition is to facilitate
const auto-generation for paths and service-names so they can be used
by D-Bus interface developers rather than using static strings at
multiple places which makes code browsing & maintainability a
challenge.
Change-Id: I09fbc4d9745b2101136a815a8c9d1790047121db
Signed-off-by: Jagpal Singh Gill <paligill@gmail.com>
Signed-off-by: Patrick Williams <patrick@stwcx.xyz>
diff --git a/docs/yaml/interface.md b/docs/yaml/interface.md
index e5b6e28..ec71433 100644
--- a/docs/yaml/interface.md
+++ b/docs/yaml/interface.md
@@ -18,6 +18,11 @@
- A list of signals generated by this D-Bus interface.
- enumerations
- A list of enumerations defined by this D-Bus interface.
+- paths
+ - A list of D-Bus paths where this D-Bus interface will be implemented.
+- service_names
+ - A default service name or a list of service names which can host this D-Bus
+ interface.
## Enumerations
@@ -234,3 +239,84 @@
[dbus-design-guidelines]: https://dbus.freedesktop.org/doc/dbus-api-design.html
[dbus-spec]: https://dbus.freedesktop.org/doc/dbus-specification.html
+
+## Paths
+
+A path must have the YAML property `name` & `value` and may optionally have a
+`description` and `segments`. Each `segments` entry must have the YAML property
+`name` & `value` and may optionally have a `description` & nested `segments`.
+
+Example:
+
+```yaml
+paths:
+ - name: CardGames
+ description: >
+ The root path for the card games.
+ value: /xyz/openbmc_project/card_games
+ segments:
+ - name: BlackJack
+ description: >
+ The relative path for the black jack game.
+ value: black_jack
+ - name: Rummy
+ description: >
+ The relative path for the rummy game.
+ value: rummy
+```
+
+A common approach is to have a single path which is used as a root of all
+instances, which is often documented as a "namespace". For convenience, this can
+be represented with a single `namespace` value. If the interface is intended to
+be used as a singleton at a specific object path, similarly the `instance` value
+can be used.
+
+Example:
+
+```yaml
+paths:
+ - namespace: /xyz/openbmc_project/decks
+ description: >
+ The root path for all decks.
+ - instance: /xyz/openbmc_projects/decks/standard
+ description: >
+ The root path for a standard deck of cards.
+```
+
+## Service Name
+
+An interface can be implemented either by a single service or multiple services.
+
+### Singleton host service name
+
+A singleton host service name must have the YAML property `default` and may
+optionally have a `description`. `xyz.openbmc_project.ObjectMapper` is one such
+example.
+
+Example:
+
+```yaml
+service_names:
+ default: xyz.openbmc_project.deck
+ description: >
+ The service name for the card deck manager.
+```
+
+### Multiton host service names
+
+A multiton host service name must have the YAML property `name` & `value` and
+may optionally have a `description`.
+
+Example:
+
+```yaml
+service_names:
+ - name: BlackJack
+ description: >
+ The service name for the Back Jack game manager.
+ value: xyz.openbmc_project.black_jack
+ - name: Rummy
+ description: >
+ The service name for rummy game manager.
+ value: xyz.openbmc_project.rummy
+```