mctpd: Add mctp/links/<linkName> D-Bus object

CHANGELOG.md

@@ -12,6 +12,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 2. mctpd: Allow recovery of devices reporting a nil UUID for development
 3. mctpd: Allow configuring .Connectivity as writable for development
 4. mctpd: Add AssignEndpointStatic for static EID allocations
+5. mctpd: Add a configuration file facility, defaulting to /etc/mctpd.conf.
+6. mctpd: Add mctp/interfaces/<name> D-Bus object
 
 ### Changed
 
@@ -27,6 +29,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 3. The `tests` option has changed type from `feature` to `boolean`. Tests are
    enabled by default.
 
+4. The dbus interface has undergone a major rework, using standard prefixes
+   and version interface, bus owner and entry-point object names. See
+   docs/mctpd.md for full details on the new interface.
+
 ### Fixed
 
 1. mctpd: EID assignments now work in the case where a new endpoint has a

README.md

@@ -68,13 +68,17 @@ configured (ie., interfaces are enabled, and local addresses have been
 assigned). There are two sample systemd unit files under the conf/ directory, to
 coordinate the local setup and the supervision of the mctpd process.
 
+`mctpd` can read some basic configuration from a file, by default
+`/etc/mctpd.conf`, but other files can be specified with the `-c FILE` argument.
+An example configuration is in [`conf/mctpd.conf`](conf/mctpd.conf).
+
 The `mctpd` daemon will expose a dbus interface, claiming the bus name
-`xyz.openbmc_project.MCTP` and object path `/xyz/openbmc_project/mctp`. This
+`au.com.codeconstruct.MCTP1` and object path `/au/com/codeconstruct/mctp1`. This
 provides a few functions for configuring remote endpoints:
 
-    # busctl introspect xyz.openbmc_project.MCTP /xyz/openbmc_project/mctp
+    # busctl introspect au.com.codeconstruct.MCTP1 /au/com/codeconstruct/mctp1/
     NAME                                TYPE      SIGNATURE  RESULT/VALUE  FLAGS
-    au.com.CodeConstruct.MCTP           interface -          -             -
+    au.com.codeconstruct.MCTP           interface -          -             -
     .AssignEndpoint                     method    say        yisb          -
     .AssignEndpointStatic               method    sayy       yisb          -
     .LearnEndpoint                      method    say        yisb          -
@@ -84,7 +88,7 @@ Results of mctpd enumeration are also represented as dbus objects, using the
 OpenBMC-specified MCTP endpoint format. Each endpoint appears on the bus at the
 object path:
 
-    /xyz/openbmc_project/mctp/<network-id>/<endpoint-id>
+    /au/com/codeconstruct/mctp/networks/<network-id>/endpoints/<endpoint-id>
 
 where `mctpd` exposes three dbus interfaces for each:
 
@@ -99,7 +103,7 @@ where `mctpd` exposes three dbus interfaces for each:
 
    This interface is defined by the Common.UUID phosphor-dbus specification.
 
- - `au.com.CodeConstruct.MCTP.EndPoint`: Additional control methods for the
+ - `au.com.codeconstruct.MCTP1.Endpoint1`: Additional control methods for the
    endpoint - for example, `Remove`
 
 Testing

conf/mctpd-dbus.conf

@@ -3,8 +3,8 @@
         "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">
 <busconfig>
  <policy user="root">
-  <allow own="xyz.openbmc_project.MCTP"/>
-  <allow send_destination="xyz.openbmc_project.MCTP"/>
-  <allow receive_sender="xyz.openbmc_project.MCTP"/>
+  <allow own="au.com.codeconstruct.MCTP1"/>
+  <allow send_destination="au.com.codeconstruct.MCTP1"/>
+  <allow receive_sender="au.com.codeconstruct.MCTP1"/>
  </policy>
 </busconfig>

conf/mctpd.conf

@@ -0,0 +1,10 @@
+# Mode: either bus-owner or endpoint or unknown
+mode = "bus-owner"
+
+# MCTP protocol configuration. Used for both endpoint and bus-owner modes.
+[mctp]
+message_timeout_ms = 30
+
+# Specify a UUID: not generally required - mctpd will query the system UUID
+# where available.
+# uuid = "21f0f554-7f7c-4211-9ca1-6d0f000ea9e7"

conf/mctpd.service

@@ -6,7 +6,7 @@ After=mctp-local.target
 
 [Service]
 Type=dbus
-BusName=xyz.openbmc_project.MCTP
+BusName=au.com.codeconstruct.MCTP1
 ExecStart=/usr/sbin/mctpd
 
 [Install]

docs/endpoint-recovery.md

@@ -144,20 +144,21 @@ issues. This may include applications in addition to the process which requested
 `mctpd` currently structures its D-Bus objects as follows:
 
 ```
-root@cc-nvme-mi:~# busctl tree xyz.openbmc_project.MCTP
-`-/xyz
-  `-/xyz/openbmc_project
-    `-/xyz/openbmc_project/mctp
-      `-/xyz/openbmc_project/mctp/1
-        |-/xyz/openbmc_project/mctp/1/12
-        |-/xyz/openbmc_project/mctp/1/8
-        `-/xyz/openbmc_project/mctp/1/9
+root@cc-nvme-mi:~# busctl tree au.com.codeconstruct.MCTP1
+└─/au
+  └─/au/com
+    └─/au/com/codeconstruct
+      └─/au/com/codeconstruct/mctp1
+        ├─/au/com/codeconstruct/mctp1/networks/1
+        │ └─/au/com/codeconstruct/mctp1/networks/1/endpoints/12
+          ├─/au/com/codeconstruct/mctp1/networks/1/endpoints/8
+          └─/au/com/codeconstruct/mctp1/networks/1/endpoints/9
 ```
 
 ```
-root@cc-nvme-mi:~# busctl introspect xyz.openbmc_project.MCTP /xyz/openbmc_project/mctp
+root@cc-nvme-mi:~# busctl introspect au.com.codeconstruct.MCTP1 /au/com/codeconstruct/mctp1
 NAME                                TYPE      SIGNATURE  RESULT/VALUE  FLAGS
-au.com.CodeConstruct.MCTP           interface -          -             -
+au.com.codeconstruct.Endpoint1      interface -          -             -
 .AssignEndpoint                     method    say        yisb          -
 .LearnEndpoint                      method    say        yisb          -
 .SetupEndpoint                      method    say        yisb          -
@@ -178,7 +179,7 @@ org.freedesktop.DBus.Properties     interface -          -             -
 ```
 
 ```
-root@cc-nvme-mi:~# busctl introspect xyz.openbmc_project.MCTP /xyz/openbmc_project/mctp/1
+root@cc-nvme-mi:~# busctl introspect au.com.codeconstruct.MCTP1 /au/com/codecontrust/mctp1/networks/1
 NAME                                TYPE      SIGNATURE RESULT/VALUE FLAGS
 org.freedesktop.DBus.Introspectable interface -         -            -
 .Introspect                         method    -         s            -
@@ -193,9 +194,9 @@ org.freedesktop.DBus.Properties     interface -         -            -
 ```
 
 ```
-root@cc-nvme-mi:~# busctl introspect xyz.openbmc_project.MCTP /xyz/openbmc_project/mctp/1/9
+root@cc-nvme-mi:~# busctl introspect au.com.codeconstruct.MCTP1 /au/com/codecontrust/mctp1/networks/1/endpoints/9
 NAME                                TYPE      SIGNATURE RESULT/VALUE                           FLAGS
-au.com.CodeConstruct.MCTP.Endpoint  interface -         -                                      -
+au.com.codeconstruct.MCTP.Endpoint1 interface -         -                                      -
 .Remove                             method    -         -                                      -
 .SetMTU                             method    u         -                                      -
 org.freedesktop.DBus.Introspectable interface -         -                                      -
@@ -217,16 +218,16 @@ xyz.openbmc_project.MCTP.Endpoint   interface -         -
 ```
 
 The problem we have deals with specific endpoints. To satisfy the third scenario
-the object `/xyz/openbmc_project/mctp/1/9` would be removed.
+the object `/au/com/codeconstruct/mctp1/networks/1/endpoints/9` would be removed.
 
 For scenarios 1 and 2 we need to add capabilities on the endpoint object. The
-`au.com.CodeConstruct.MCTP.Endpoint` already exposes endpoint control APIs, and
+`au.com.codeconstruct.MCTP.Endpoint` already exposes endpoint control APIs, and
 given we're not removing capabilities we can change it.
 
 ## Proposed Design
 
 The approach is to add a `.Recover` method and a `.Connectivity` property to the
-`au.com.CodeConstruct.MCTP.Endpoint` interface. `.Recover` takes no arguments,
+`au.com.codeconstruct.MCTP.Endpoint1` interface. `.Recover` takes no arguments,
 produces no result, and returns immediately. `.Connectivity` takes one of two
 values:
 
@@ -346,11 +347,11 @@ The general strategy for tracking endpoint lifecycles is [as follows]
    data-structures
 
    ```
-   type='signal',sender='xyz.openbmc_project.MCTP',path_namespace='/xyz/openbmc_project/mctp'
+   type='signal',sender='xyz.openbmc_project.MCTP',path_namespace='/au/com/codeconstruct/mctp1'
    ```
 
 2. Issue a call to `GetManagedObjects` `org.freedesktop.DBus.ObjectManager` on
-   `/xyz/openbmc_project/mctp` for initial population of local data-structures
+   `/au/com/codeconstruct/mctp1` for initial population of local data-structures
 
 3. Issue
 
@@ -360,7 +361,8 @@ The general strategy for tracking endpoint lifecycles is [as follows]
    registered as an MCTP endpoint.
 
 2. The FRU data is decoded and `SetupEndpoint` on the
-   `au.com.CodeConstruct.MCTP` interface of the `/xyz/openbmc_project/mctp`
+   `au.com.codeconstruct.MCTP.BusOwner1.DRAFT` interface of the
+   `/au/com/codeconstruct/mctp1`
    object hosted by `mctpd` is invoked.
 
 3. The device was not previously configured and has no programmed static EID.
@@ -372,8 +374,8 @@ The general strategy for tracking endpoint lifecycles is [as follows]
    interfaces):
 
    ```
-   "/xyz/openbmc_project/mctp/1/9": {
-     "au.com.CodeConstruct.MCTP.Endpoint": { },
+   "/au.com.codeconstruct/mctp1/networks/1/endpoints/9": {
+     "au.com.codeconstruct.MCTP.Endpoint1": { },
      "xyz.openbmc_project.Common.UUID": {
        "UUID": "..."
      },
@@ -394,16 +396,18 @@ The general strategy for tracking endpoint lifecycles is [as follows]
 7. MCTP endpoint 9 stops responding to NVMe-MI commands from `nvmesensor`.
 
 8. `nvmesensor` calls the `Recover` method on the
-   `au.com.CodeConstruct.MCTP.Endpoint` of the `/xyz/openbmc_project/mctp/1/9`
+   `au.com.codeconstruct.MCTP.Endpoint1` of the
+   `/au/com/codeconstruct/mctp1/networks/1/endpoints/9`
    D-Bus object hosted by `mctpd`. This may occur via e.g. failure to regularly
    poll the drive CTEMP.
 
 9. `mctpd` [emits a `PropertiesChanged` signal][dbus-spec-standard-interfaces-properties]
-   from `/xyz/openbmc_project/mctp/1/9` with the following contents:
+   from `/au/com/codeconstruct/mctp/networks/1/endpoints/9` with the following
+   contents:
 
    ```
    [
-     "au.com.CodeConstruct.MCTP.Endpoint",
+     "au.com.codeconstruct.MCTP.Endpoint1",
      { "Connectivity": "Degraded" },
      { }
    ]
@@ -417,12 +421,12 @@ The general strategy for tracking endpoint lifecycles is [as follows]
 
 12. The device fails to respond to all (retried) queries issued inside `Treclaim`.
 
-13. `mctpd` removes `/xyz/openbmc_project/mctp/1/9` from D-Bus, emitting an
-    `InterfacesRemoved` signal with the following content
+13. `mctpd` removes `/au/com/codeconstruct/mctp1/networks/1/endpoints/9` from
+    D-Bus, emitting an `InterfacesRemoved` signal with the following content
 
     ```
-    "/xyz/openbmc_project/mctp/1/9": [
-      "au.com.CodeConstruct.MCTP.Endpoint",
+    "/au/com/codeconstruct/mctp1/networks/1/endpoints/9": [
+      "au.com.codeconstruct.MCTP.Endpoint1",
       "xyz.openbmc_project.MCTP.Endpoint",
       ...
     ]

docs/mctpd.md

@@ -2,20 +2,28 @@
 
 ## D-Bus
 
-`mctpd` provides a D-Bus path of `/xyz/openbmc_project/mctp`. For each known MCTP endpoint, `mctpd`
-will populate an object `/xyz/openbmc_project/mctp/<NetworkId>/<EID>`. The objects have interface
-`xyz.openbmc_project.MCTP.Endpoint`, as per 
-[OpenBMC documentation](https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/MCTP).
+`mctpd` provides a D-Bus service named `au.com.codeconstruct.MCTP1`, and a base
+object path of `/au/com/codeconstruct/mctp1`. For each known MCTP endpoint,
+`mctpd` will populate an object at
+`/au/com/codeconstruct/mctp1/networks/<NetworkId>/endpoints/<EID>`. The objects have
+interface `xyz.openbmc_project.MCTP.Endpoint`, as per [OpenBMC
+documentation](https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/MCTP).
 
-As well as the standard interfaces, `mctpd` provides methods to add and configure MCTP endpoints.
-These are provided by the `au.com.CodeConstruct.MCTP` D-Bus interface.
+As well as those standard interfaces, `mctpd` provides methods to add and
+configure MCTP endpoints. These are provided by the `au.com.codeconstruct.MCTP1`
+D-Bus interface.
 
-### `.SetupEndpoint`
+## Bus-owner methods: `au.com.codeconstruct.MCTP.BusOwner1.DRAFT` interface
 
-This method is the normal method used to add a MCTP endpoint.
-The endpoint is identified by MCTP network interface, and physical address.
-`mctpd` will query for the endpoint's current EID, and assign an EID to the endpoint if needed.
-`mctpd` will add local MCTP routes and neighbour table entries for endpoints as they are added.
+This interface exposes bus-owner level functions.
+
+### `.SetupEndpoint`: `say` → `yisb`
+
+This method is the normal method used to add a MCTP endpoint. The endpoint is
+identified by MCTP network interface, and physical address. `mctpd` will query
+for the endpoint's current EID, and assign an EID to the endpoint if needed.
+`mctpd` will add local MCTP routes and neighbour table entries for endpoints as
+they are added.
 
 `SetupEndpoint <interface name> <hwaddr>`
 
@@ -29,23 +37,27 @@ new  (bool) - true if a new EID was assigned
 
 `<interface name>` is an interface such as `mctpi2c6`.
 
-`<hwaddr>` depends on the transport type - for i2c it is a 1 byte client address (7-bit, the same as other Linux tools like `i2cdetect`).
+`<hwaddr>` depends on the transport type - for i2c it is a 1 byte client address
+(7-bit, the same as other Linux tools like `i2cdetect`).
 
 
 An example:
 
 ```shell
-busctl call xyz.openbmc_project.MCTP /xyz/openbmc_project/mctp \
-        au.com.CodeConstruct.MCTP SetupEndpoint say mctpi2c6 1 0x1d
+busctl call au.com.codeconstruct.MCTP1 \
+    /au/com/codeconstruct/mctp1 \
+    au.com.codeconstruct.MCTP1 \
+    SetupEndpoint say mctpi2c6 1 0x1d
 ```
 `1` is the length of the hwaddr array.
 
-### `.AssignEndpoint`
+### `.AssignEndpoint`: `say` → `yisb`
 
-Similar to SetupEndpoint, but will always assign an EID rather than querying for existing ones.
-Will return `new = false` when an endpoint is already known to `mctpd`.
+Similar to SetupEndpoint, but will always assign an EID rather than querying for
+existing ones. Will return `new = false` when an endpoint is already known to
+`mctpd`.
 
-### `.AssignEndpointStatic`
+### `.AssignEndpointStatic`: `sayy` → `yisb`
 
 Similar to AssignEndpoint, but takes an additional EID argument:
 
@@ -59,35 +71,50 @@ This call will fail if the endpoint already has an EID, and that EID is
 different from `static-EID`, or if `static-EID` is already assigned to another
 endpoint.
 
-### `.LearnEndpoint`
+### `.LearnEndpoint`: `say` → `yisb`
 
-Like SetupEndpoint but will not assign EIDs, will only query endpoints for a current EID.
-The `new` return value is set to `false` for an already known endpoint, or `true` when an
-endpoint's EID is newly discovered.
+Like SetupEndpoint but will not assign EIDs, will only query endpoints for a
+current EID. The `new` return value is set to `false` for an already known
+endpoint, or `true` when an endpoint's EID is newly discovered.
 
-## Endpoint Methods
+## Endpoint methods: the `au.com.codeconstruct.MCTP.Endpoint1` interface
 
-Each endpoint object has methods to configure it, with `au.com.CodeConstruct.MCTP.Endpoint`
-interface on each endpoint.
+Each endpoint object has methods to configure it, through the
+`au.com.codeconstruct.MCTP.Endpoint1` interface on each endpoint.
 
-## `.SetMTU`
+## `.SetMTU`: `u`
 
-Sets the MTU (maximum transmission unit) on the route for that endpoint. This must be within
-the MTU range allowed for the network device. For i2c that is [68, 254].
+Sets the MTU (maximum transmission unit) on the route for that endpoint. This
+must be within the MTU range allowed for the network device. For i2c that is
+[68, 254].
 
-If a route-specific MTU has not been set (or set to 0), Linux will use the per-interface
-MTU, configurable with `mctp link set <ifname> mtu <value>`.
+If a route-specific MTU has not been set (or set to 0), Linux will use the
+per-interface MTU, configurable with `mctp link set <ifname> mtu <value>`.
 
 An example, setting MTU of 80:
 
 ```shell
-busctl call xyz.openbmc_project.MCTP  /xyz/openbmc_project/mctp/1/11 \
-        au.com.CodeConstruct.MCTP.Endpoint  SetMTU u 80
+busctl call au.com.codeconstruct.MCTP1 \
+    /au/com/codeconstruct/mctp1/networks/1/endpoints/11 \
+    au.com.codeconstruct.MCTP.Endpoint1 \
+    SetMTU u 80
 ```
 
 ## `.Remove`
 
 Removes the MCTP endpoint from `mctpd`, and deletes routes and neighbour entries.
 
-
-
+## D-Bus /au/com/codeconstruct/mctp1/interfaces/<name>
+
+`mctpd` provides a D-Bus path of `/au/com/codeconstruct/mctp1/interfaces`.
+For each known MCTP interfaces, `mctpd` will populate an D-Bus object
+`/au/com/codeconstruct/mctp1/interfaces/<name>`. The D-Bus objects have
+interface `au.com.CodeConstruct.MCTP.Link1`.
+The D-Bus interface includes the `Role` property which reports BMC roles
+in the link. The possible value of `Role` are `BusOwner`, `Endpoint` and
+`Unknown`. The `Role` property is a changeable value but it can only be
+changed when the current configured value is `Unknown` because the BMC
+`Role` in the MCTP link is specific depend on the system.
+The D-Bus `/au/com/codeconstruct/mctp1/interfaces/<name>` objects also
+includes an au.com.codeconstruct.MCTP.BusOwner1 which exposes bus-owner
+level functions.