design: gpio based hardware inventory
Design to support the gpio based detection of hardware.
Change-Id: Idbf2dc2cc77a637c58ad32af54c7c094a53a2a50
Signed-off-by: Alexander Hansen <alexander.hansen@9elements.com>
diff --git a/designs/inventory/gpio-based-hardware-inventory.md b/designs/inventory/gpio-based-hardware-inventory.md
new file mode 100644
index 0000000..ac349b6
--- /dev/null
+++ b/designs/inventory/gpio-based-hardware-inventory.md
@@ -0,0 +1,443 @@
+# GPIO based hardware inventory
+
+Author: Alexander Hansen <alexander.hansen@9elements.com>
+
+Other contributors: Chu Lin <linchuyuan@google.com> (through their previous
+works), Amithash Prasad <amithash@meta.com>
+
+Created: August 26, 2024
+
+Reference:
+[Chu Lin's gpio based cable presence detection](https://github.com/openbmc/docs/blob/46902afd6ebd20d1148379df99fe2c0c591f56ba/designs/gpio-based-cable-presence.md)
+
+## Problem Description
+
+Due to increasing complexity of server designs and different configurations of
+the same system being possible, there is a need for a simple way to detect the
+presence of cards, cables and other connected entities which may or may not be
+plugged into a system. A subset of these entities support presence detection via
+gpios. This design focuses on those.
+
+Connected entities detectable via other means are out of scope of this design.
+
+## Background and References
+
+The existing design for the gpio based cable presence is partially implemented
+and focuses on IPMI use-case.
+
+[existing design by Chu Lin](https://github.com/openbmc/docs/blob/879601d92becfa1dbc082f487abfb5e0151a5091/designs/gpio-based-cable-presence.md)
+
+Currently the way to do gpio based presence detection is via
+phosphor-multi-gpio-presence and phosphor-inventory-manager.
+
+The static inventory is declared and the inventory items are exposed at runtime
+by phosphor-inventory-manager.
+
+The presence daemon then toggles the 'Present' property on dbus interface
+xyz.openbmc_project.Inventory.Item.
+
+Additional item-specific properties are statically declared in the
+phosphor-inventory-manager configuration.
+
+An example of how this is currently done:
+
+[presence daemon config](https://github.com/openbmc/openbmc/blob/1d438f68277cdb37e8062ae298402e9685882acb/meta-ibm/meta-sbp1/recipes-phosphor/gpio/phosphor-gpio-monitor/phosphor-multi-gpio-presence.json)
+
+[phosphor-inventory-manager config](https://github.com/openbmc/openbmc/blob/1d438f68277cdb37e8062ae298402e9685882acb/meta-ibm/meta-sbp1/recipes-phosphor/inventory/static-inventory/static-inventory.yaml)
+
+In the example we have inventory item **dimm_c0a1** which has following
+phosphor-multi-gpio-presence configuration:
+
+```json
+{
+ "Name": "DIMM_C0A1",
+ "LineName": "PLUG_DETECT_DIMM_C0A1",
+ "ActiveLow": true,
+ "Bias": "PULL_UP",
+ "Inventory": "/system/chassis/motherboard/dimm_c0a1"
+}
+```
+
+and phosphor-inventory-manager configuration:
+
+```yaml
+- name: Add DIMMs
+ description: >
+ Add the DIMM inventory path.
+ type: startup
+ actions:
+ - name: createObjects
+ objs:
+ /system/chassis/motherboard/dimm_c0a1:
+ xyz.openbmc_project.Inventory.Decorator.Replaceable:
+ FieldReplaceable:
+ value: true
+ type: boolean
+ xyz.openbmc_project.State.Decorator.OperationalStatus:
+ Functional:
+ value: true
+ type: boolean
+ xyz.openbmc_project.Inventory.Item:
+ PrettyName:
+ value: "DIMM C0A1"
+ type: string
+ Present:
+ value: false
+ type: boolean
+ xyz.openbmc_project.Inventory.Item.Dimm:
+ xyz.openbmc_project.Inventory.Decorator.LocationCode:
+ LocationCode:
+ value: "CPU0_DIMM_A1"
+ type: string
+```
+
+## Requirements
+
+- Support the gpio based detection of inventory items without static
+ configuration
+
+- Allow configuration of the detectable inventory items through entity-manager
+ configuration
+
+ - e.g. cable
+ - e.g. fan board
+ - e.g. daughter board
+ - entity-manager should expose all required Inventory interfaces
+ - the properties for these inventory interfaces can be obtained through the
+ exposes record in the json configuration
+
+- When a device is detected as present using the GPIO configuration published by
+ entity-manager, its probe match data is published to D-Bus, which triggers
+ entity-manager to publish the associated configuration.
+
+- Support for re-use of presence information in PROBE statements
+ - detecting one entity as 'Present' should enable detecting other entities
+ based on that info
+
+## Proposed Design
+
+The proposed design is to create a new daemon in the entity-manager repository,
+which is 'gpio-presence-sensor'.
+
+It can be inspired by implementations found in downstream forks such as the
+[NVIDIA gpio presence sensor implementation](https://github.com/NVIDIA/dbus-sensors/blob/889abc1c9bfae9395690d1562f3e08453dfa12ba/src/GPIOPresenceSensorMain.cpp)
+
+### Diagram
+
+```mermaid
+sequenceDiagram
+
+participant PresenceDaemon
+participant EM
+participant AnyService
+
+note over PresenceDaemon: cable0 plug
+
+%% initial base configuration
+
+activate EM
+EM ->> EM: PROBE true on <br> xyz.openbmc_project.FruDevice <br> PRODUCT_PRODUCT_NAME=Yosemite V4
+EM ->> PresenceDaemon: expose Configuration <br> xyz.openbmc_project.Configuration.GPIODeviceDetect <br> Name=com.meta.Hardware.Yv4.cable0
+deactivate EM
+activate PresenceDaemon
+PresenceDaemon ->> PresenceDaemon: create dbus matcher <br> in case our configuration is removed
+
+%% start forward flow
+
+PresenceDaemon ->> PresenceDaemon: detect Device present <br> via GPIO Event
+PresenceDaemon ->> EM: expose <br>xyz.openbmc_project.Inventory.Source.DevicePresence <br> Name=com.meta.Hardware.Yv4.cable0
+activate EM
+deactivate PresenceDaemon
+EM ->> EM: PROBE true on <br>xyz.openbmc_project.Inventory.Source.DevicePresence <br> Name=com.meta.Hardware.Yv4.cable0
+EM ->> AnyService: expose new Configuration <br> Example: Voltage Sensor
+deactivate EM
+
+activate AnyService
+AnyService ->> AnyService: Example: <br> expose new Voltage Sensor
+AnyService ->> AnyService: produce Sensor readings
+
+%% start reverse flow
+note over PresenceDaemon: cable0 unplug
+
+activate PresenceDaemon
+PresenceDaemon ->> PresenceDaemon: detect Device absent <br> via GPIO Event
+PresenceDaemon ->> EM: remove <br>xyz.openbmc_project.Inventory.Source.DevicePresence <br> Name=com.meta.Hardware.Yv4.cable0
+deactivate PresenceDaemon
+
+activate EM
+EM ->> EM: PROBE false on <br>xyz.openbmc_project.Inventory.Source.DevicePresence <br> Name=com.meta.Hardware.Yv4.cable0
+EM ->> AnyService: remove new Configuration <br> Example: Voltage Sensor
+deactivate EM
+AnyService ->> AnyService: remove Sensor
+deactivate AnyService
+```
+
+### Forward flow summary
+
+- EM exposes configuration for 'gpio-presence-sensor'
+- 'gpio-presence-sensor' creates a dbus matcher to watch for removal of it's
+ configuration
+- 'gpio-presence-sensor' uses gpios to detect hardware
+- 'gpio-presence-sensor' creates a dbus interface when it detects hardware
+- EM can probe new configuration files based on that dbus interface, via PROBE
+ statement
+- EM exposes the new configuration for the detected hardware
+
+### Reverse flow summary
+
+- 'gpio-presence-sensor' detects that the hardware is gone
+- 'gpio-presence-sensor' takes down the respective dbus interface
+- EM detects that via dbus matcher
+- EM removes the configuration for that hardware from dbus
+
+### Reverse flow summary (removal of configuration)
+
+- EM exposes configuration for 'gpio-presence-sensor'
+- 'gpio-presence-sensor' creates a dbus matcher to watch for removal of it's
+ configuration
+- 'gpio-presence-sensor' uses gpios to detect hardware
+- 'gpio-presence-sensor' creates a dbus interface when it detects hardware
+- EM removes the config for 'gpio-presence-sensor'
+- 'gpio-presence-sensor' takes down any dbus interfaces it created for detecting
+ hardware
+- EM detects that via dbus matcher
+- EM removes the configuration for that hardware from dbus
+
+### Proposed DBus Interfaces
+
+'gpio-presence-sensor' should consume configuration via dbus interface
+
+`xyz.openbmc_project.Configuration.GPIODeviceDetect`
+
+entity-manager already creates the needed dbus interfaces here. So there is no
+need to make something new.
+
+Below is a PDI yaml file to describe the proposed configuration interface:
+
+```yaml
+description: >
+ Information to enable a daemon to probe hardware based on gpio values
+properties:
+ - name: Name
+ type: string
+ description: >
+ Used by entity-manager to identify which hardware was detected. For
+ internal use by entity-manager.
+ - name: PresencePinNames
+ type: array[string]
+ description: >
+ Names of the gpio lines.
+ - name: PresencePinValues
+ type: array[uint64]
+ description: >
+ Values of the gpio lines for which the device is considered present.
+ Choosing 'uint64' instead of 'bool' here for compatibility with how EM
+ exposes configuration on dbus.
+```
+
+'gpio-presence-sensor' then exposes
+`xyz.openbmc_project.Inventory.Source.DevicePresence` dbus interface of its own
+if it detects the hardware:
+
+```yaml
+description: >
+ Information for a daemon to expose if hardware has been detected based on
+ xyz.openbmc_project.Configuration.GPIODeviceDetect interface
+properties:
+ - name: Name
+ type: string
+ description: >
+ Used by entity-manager to identify which hw was detected. For internal use
+ by entity-manager.
+```
+
+entity-manager can then consider the hardware as present and expose the
+inventory interfaces for it.
+
+### Handling removal of the device
+
+In case the gpio state changes, 'gpio-presence-sensor' can remove the
+`xyz.openbmc_project.Inventory.Source.DevicePresence` interface and
+entity-manager can have a dbus matcher for that, to then remove the respective
+inventory items and any inventory items detected below it aswell.
+
+### Proposed changes in entity-manager
+
+entity-manager needs to be extended to handle a new type 'GPIODeviceDetect'
+Exposes record. It needs to then create the
+`xyz.openbmc_project.Configuration.GPIODeviceDetect` dbus interface.
+
+#### Proposed EM Configuration Schema
+
+```json
+{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "$defs": {
+ "GPIODeviceDetect": {
+ "type": "object",
+ "properties": {
+ "Name": {
+ "type": "string"
+ },
+ "Type": {
+ "type": "string"
+ },
+ "PresencePinNames": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "PresencePinValues": {
+ "type": "array",
+ "items": {
+ "type": "number"
+ }
+ }
+ },
+ "required": ["Name", "Type", "PresencePinNames", "PresencePinValues"]
+ }
+ }
+}
+```
+
+### Example EM Config Fragments
+
+Below is an incomplete example of how such a config could look like.
+
+The new part is the `"Type": "GPIODeviceDetect"` which is conveniently named the
+same as the Dbus interface.
+
+```json
+{
+ Exposes:
+ [
+ {
+ "Name": "com.meta.Hardware.Yv4.cable0",
+ "PresencePinNames": ["presence-cable0"],
+ "PresencePinValues": [1],
+ "Type": "GPIODeviceDetect"
+ },
+ {
+ "Name": "com.meta.Hardware.Yv4.ComputeCard",
+ "PresencePinNames": ["presence-slot0a", "presence-slot0b"],
+ "PresencePinValues": [0, 1],
+ "Type": "GPIODeviceDetect"
+ },
+ {
+ "Name": "com.meta.Hardware.Yv4.SidecarExpansion",
+ "PresencePinNames": ["presence-slot0a", "presence-slot0b"],
+ "PresencePinValues": [1, 0],
+ "Type": "GPIODeviceDetect"
+ },
+ {
+ "Name": "com.meta.Hardware.Yv4.AirBlocker",
+ "PresencePinNames": ["presence-slot0a", "presence-slot0b"],
+ "PresencePinValues": [1, 1],
+ "Type": "GPIODeviceDetect"
+ },
+ {
+ "Name": "com.meta.Hardware.Yv4.fanboard0",
+ "PresencePinNames": ["presence-fanboard0"],
+ "PresencePinValues": [0],
+ "Type": "GPIODeviceDetect"
+ },
+ ...
+ ],
+ ...
+ "Name": "Chassis",
+ "Probe": "xyz.openbmc_project.FruDevice({'BOARD_PRODUCT_NAME': 'MYBOARDPRODUCT*'})",
+ "Type": "Board",
+}
+```
+
+Another configuration can then contain additional records for the newly detected
+e.g. fan board.
+
+```json
+{
+ Exposes:
+ [
+ {
+ "Address": "0x28",
+ "Bus": 5,
+ "EntityId": 7,
+ "EntityInstance": 0,
+ "Name": "fanboard_air_inlet",
+ "Name1": "fanboard_air_outlet",
+ "Type": "NCT7802"
+ },
+ ...
+ ],
+ ...
+ "Name": "My Fan Board 0",
+ "Probe": "xyz.openbmc_project.Inventory.Source.DevicePresence({'Name': 'com.meta.Hardware.Yv4.fanboard0'})",
+ "Type": "Board",
+}
+```
+
+### Uniqueness of the "Name" property
+
+There is a need to namespace configuration for devices probed via gpios,
+according to their vendor or location in the system. "Name" is just a string but
+it can be used to create namespacing with dots. This will prevent accidental
+probing of unrelated configuration.
+
+## Alternatives Considered
+
+- The existing approach with phosphor-inventory-manager and static configuration
+ Leaning away from that because it cannot support multiple different chassis
+ configurations in one fw image.
+
+- Presence detection integrated into entity-manager. There already exists a
+ presence daemon, and it's an explicit non-goal of EM to implement any presence
+ detection. Maintainers have confirmed that EM should not implement this
+ feature internally.
+
+- Another daemon which would expose inventory items based on EM configuration.
+ This would mean EM does not need to expose the item-specific inventory
+ interfaces and properties.
+
+- Exposing the item-specific interfaces and properties in a generic way. This
+ means EM would lose any semantic knowledge of the entities it exposes and
+ become more like phosphor-inventory-manager
+
+- Preventing duplication in case of multiple instances of e.g. fan
+ board/daughter board/cable through an additional variable besides "Name" that
+ could then be used in the the configuration file of the entity. This is
+ already covered partially by `$index` but `$index` is not stable and depends
+ on order and count of the devices probed successfully. But this feature is
+ left out intentionally here to limit the scope. So multiple instances of a
+ daughter board may need multiple slightly different configuration files.
+
+- Comparing to Chu Lin's design, this design is not focused on the IPMI or
+ redfish use-case. It is separate from the external interface. It is assumed
+ the external interfaces can expose a cable inventory based on the
+ [cable dbus interface](https://github.com/openbmc/phosphor-dbus-interfaces/commit/3c5b76491afb8401627fc343077fe420f8a5e7f9)
+ which was created as part of Chu Lin's design.
+
+- Comparing to Chu Lin's design, this design does not directly provide a cable
+ inventory. So there is another daemon or configuration decorator needed to
+ expose a cable inventory item.
+
+- Comparing to Chu Lin's design, this design is not limited to cables.
+
+## Impacts
+
+### Organizational
+
+- Does this repository require a new repository? No
+- Who will be the initial maintainer(s) of this repository?
+- Which repositories are expected to be modified to execute this design?
+ - entity-manager
+- Make a list, and add listed repository maintainers to the gerrit review.
+
+## Testing
+
+How will this be tested? How will this feature impact CI testing?
+
+The feature can be tested in the entity-manager repository. We can use
+dbus-run-session to run an actual entity-manager to provide the configuration or
+simply provide a hardcoded configuration for 'gpio-presence-sensor'. For the
+gpio interactions, we can use `CONFIG_GPIO_SIM` or alternatively abstract the
+gpio interactions into a separate class which can then be stubbed.