Skip to content

Commit

Permalink
mctpd: dbus interface rework
Browse files Browse the repository at this point in the history 
This change implements the dbus interface rework specified in
#40.

Essentially: this uses more standard bus, object and path names, and
moves away from the xyz.openbmc_project namespace, and use
au.com.codeconstruct (all lowercase) there instead, as we're not
specificially an OpenBMC project.

We also put collections of things (networks and endpoints) under a
specifically-named object path, so we can introduce new collections
alongside (interfaces) without compatibility issues

This means:

 - the bus owner name is now au.com.codeconstruct.MCTP1

 - interfaces are namespaced and versioned:
    - au.com.codeconstruct.MCTP.Endpoint1
    - au.com.codeconstruct.MCTP.BusOwner1

 - the top-level entrypoint path is versioned, as
    `/au/com/codeconstruct/mctp1`

 - the endpoint object tree is structured as
    `/au/com/codeconstruct/mctp1/networks/<n>/endpoints/<e>`

Signed-off-by: Jeremy Kerr <[email protected]>
  • Loading branch information
@jk-ozlabs
jk-ozlabs committed Jun 6, 2024
1 parent 2830d8a commit f26db98
Show file tree
Hide file tree
Showing 12 changed files with 122 additions and 97 deletions.
4 changes: 4 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,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
Expand Down
10 changes: 5 additions & 5 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -73,12 +73,12 @@ coordinate the local setup and the supervision of the mctpd process.
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 -
Expand All @@ -88,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:

Expand All @@ -103,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
Expand Down
6 changes: 3 additions & 3 deletions conf/mctpd-dbus.conf
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>
2 changes: 1 addition & 1 deletion conf/mctpd.service
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down
60 changes: 32 additions & 28 deletions docs/endpoint-recovery.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 -
Expand All @@ -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 -
Expand All @@ -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 - - -
Expand All @@ -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:

Expand Down Expand Up @@ -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

Expand All @@ -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` 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.
Expand All @@ -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": "..."
},
Expand All @@ -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/enpoints/9` with the following
contents:

```
[
"au.com.CodeConstruct.MCTP.Endpoint",
"au.com.codeconstruct.MCTP.Endpoint1",
{ "Connectivity": "Degraded" },
{ }
]
Expand All @@ -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",
...
]
Expand Down
81 changes: 47 additions & 34 deletions docs/mctpd.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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` 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>`

Expand All @@ -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:

Expand All @@ -59,35 +71,36 @@ 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.



2 changes: 1 addition & 1 deletion meson.build
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ conf.set10('MCTPD_RECOVER_NIL_UUID',
)
conf.set10('MCTPD_WRITABLE_CONNECTIVITY',
get_option('unsafe-writable-connectivity'),
description: 'Allow writes to the Connectivity member of the au.com.CodeConstruct.MCTP.Endpoint interface on endpoint objects')
description: 'Allow writes to the Connectivity member of the au.com.codeconstruct.MCTP.Endpoint1 interface on endpoint objects')

conf.set_quoted('MCTPD_CONF_FILE_DEFAULT',
join_paths(get_option('prefix'), get_option('sysconfdir'), 'mctpd.conf'),
Expand Down
2 changes: 1 addition & 1 deletion meson_options.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,5 +2,5 @@ option('unsafe-recover-nil-uuid', type: 'boolean', value: false)
option('unsafe-writable-connectivity',
type: 'boolean',
value: false,
description: 'Allow writes to the Connectivity member of the au.com.CodeConstruct.MCTP.Endpoint interface on endpoint objects')
description: 'Allow writes to the Connectivity member of the au.com.codeconstruct.MCTP.Endpoint1 interface on endpoint objects')
option('tests', type: 'boolean', value: true)
Loading

0 comments on commit f26db98

Please sign in to comment.