tlbmc/g3doc/general/redfish_resource_ownership_model.md

# tlBMC Redfish Resource Ownership Model

go/tlbmc-redfish-resource-ownership

<!--*
# Document freshness: For more information, see go/fresh-source.
freshness: { owner: 'tlbmc-dev' reviewed: '2025-05-13' }
*-->

[TOC]

Note: This is an evolving document and definitions may shift as the scope of
tlBMC increases.

tlBMC ownership of a redfish resource happens when a redfish URL is sent to the
tlBMC app rather than the traditional gBMCweb app. As described in
go/tlbmc-smart-routing, an incoming redfish query may be routed to traditional
bmcweb or to the tlBMC app depending on if the resource is "owned" by tlBMC,
this is called smart routing. In the case of tlBMC ownership, a query being sent
to tlBMC means that tlBMC is providing the query response based on the internal
representation of the requested object after tlBMC has parsed the EM config.
There are no dbus calls being made or interactions with other daemons to return
this response.

There are three possible models for a redfish resource to be "owned" by tlBMC
today. This document describes the extent to which tlBMC may have ownership over
a resource.

## Fully Owned

### Chassis

Chassis resources onboarded to tlBMC are detected and fully owned. In this case,
FRUs are detected by tlBMC over I2C scan and the Redfish response is provided by
the tlBMC backend. Every part of the Chassis response comes from tlBMC,
including Fru info received from the eeprom of the device and links to
associated Chassis, Cables, Processors, or Drives which are configured in the EM
config.

An example can be seen from this config:

```json
{
  "Name": "foo",
  "ProbeV2": {
    "IpmiFru": {
      "BOARD_PRODUCT_NAME": "Foo"
    }
  },
  "ResourceType": "RESOURCE_TYPE_BOARD",
  "Exposes":[
    {
      "Name": "Foo Downstream Port",
      "Label": "PE0",
      "Type": "PortDownstream"
    },
    {
      "Type": "MAX31725",
      "Bus": 1,
      "Address": "0x4c",
      "Name": "max31725_0",
      "Name1": "max31725_1",
      "TlbmcOwned":true
    }
  ],
  "Asset": {
    "Manufacturer": "$BOARD_MANUFACTURER",
    "Model": "$BOARD_PRODUCT_NAME",
    "PartNumber": "$BOARD_PART_NUMBER",
    "SerialNumber": "$BOARD_SERIAL_NUMBER"
  }
}
```

The above config might produce the following redfish response, which contains
fields fully populated by tlBMC, requiring no additional dbus calls or
interactions with other daemons.

```json
{
  "@odata.id": "/redfish/v1/Chassis/Foo",
  "@odata.type": "#Chassis.v1_17_0.Chassis",
  "Assembly": {
    "@odata.id": "/redfish/v1/Chassis/Foo/Assembly"
  },
  "Certificates": {
    "@odata.id": "/redfish/v1/Chassis/Foo/Certificates"
  },
  "ChassisType": "Module",
  "Drives": {
    "@odata.id": "/redfish/v1/Chassis/Foo/Drives"
  },
  "EnvironmentMetrics": {
    "@odata.id": "/redfish/v1/Chassis/Foo/EnvironmentMetrics"
  },
  "Id": "Foo",
  "Links": {
    "ComputerSystems": [
      {
        "@odata.id": "/redfish/v1/Systems/system"
      }
    ],
    "Contains": {
      "@odata.id": "/redfish/v1/Chassis/Bar"
    },
    "ManagedBy": [
      {
        "@odata.id": "/redfish/v1/Managers/bmc"
      }
    ]
  },
  "Manufacturer": "Foo_Manufacturer",
  "Memory": {
    "@odata.id": "/redfish/v1/Systems/system/Memory"
  },
  "Model": "Foo_Model",
  "Name": "Foo",
  "PCIeDevices": {
    "@odata.id": "/redfish/v1/Systems/system/PCIeDevices"
  },
  "PCIeSlots": {
    "@odata.id": "/redfish/v1/Chassis/Foo/PCIeSlots"
  },
  "PartNumber": "1111111-11",
  "Power": {
    "@odata.id": "/redfish/v1/Chassis/Foo/Power"
  },
  "PowerState": "On",
  "PowerSubsystem": {
    "@odata.id": "/redfish/v1/Chassis/Foo/PowerSubsystem"
  },
  "Sensors": {
    "@odata.id": "/redfish/v1/Chassis/Foo/Sensors"
  },
  "SerialNumber": "AAAAA-11111111",
  "Status": {
    "Health": "OK",
    "HealthRollup": "OK",
    "State": "Enabled"
  },
  "Thermal": {
    "@odata.id": "/redfish/v1/Chassis/Foo/Thermal"
  },
  "ThermalSubsystem": {
    "@odata.id": "/redfish/v1/Chassis/Foo/ThermalSubsystem"
  },
  "TrustedComponents": {
    "@odata.id": "/redfish/v1/Chassis/Foo/TrustedComponents"
  }
}
```

### Sensors

Sensors supported by tlBMC are fully owned. Sensor configurations are parsed
from EM configs and readings are polled directly from hwmon files. There are no
dbus calls being made to supply sensor readings in tlBMC.

Note: Since tlBMC does not support all sensor types yet (only Hwmon Temp, PSU,
and I2CFan sensors for now), tlBMC does not own sensor collection. The response
at `/redfish/v1/Chassis/{ChassisId}/Sensors` is routed to bmcweb but a query for
individual sensor will be routed to tlBMC if supported.

An example can be seen from this config:

```json
"Exposes": [
  {
    "Name": "foo_external_sensor",
    "Units": "Watts",
    "MinValue": 6500,
    "MaxValue": 7500,
    "Type": "ExternalSensor"
  },
  {
    "Name": "foo_psu_sensor",
    "Address": "0x44",
    "Bus": "11",
    "Labels": [
      "vout1",
      "vout2",
      "vout3",
      "vout4"
    ],
    "vout1_Name": "foo_psu_sensor_0",
    "vout2_Name": "foo_psu_sensor_1",
    "vout3_Name": "foo_psu_sensor_2",
    "vout4_Name": "foo_psu_sensor_3",
    "Type": "ADM1266",
    "TlbmcOwned": true
  },
  ...
]
```

Since the `foo_psu_sensor` has the field `"TlbmcOwned"` and is of the supported
type `ADM1266`, the response when any of these individual sensors is queried
will be provided by tlBMC.

## Linked Resources Not Owned

For some configurations, tlBMC may detect and own the Chassis resource, but
there may be resources configured in the EM config file that are not owned by
tlBMC.

Since the scope of tlBMC is limited to only the Chassis path at the moment it is
possible for some Chassis to not own the resources linked in its "Links", even
when configured in the EM config. When these properties are queried, the
response will be populated from the traditional bmcweb path.

These associated resources that are linked in response but not yet owned by
tlBMC include:

-   Storages
-   Processors
-   Cables

An example can be seen in this config:

```json
# Assume there are two other Chassis EM configs connecting to the ports
# Assume there is another Cable EM config with CableUpstreamConnection to Foo Cable Downstream
{
...
  "Exposes": [
    {
      "Label": "IO0",
      "Name": "foo Port 1",
      "Type": "PortDownstream",
      "User": "tlbmc"
    },
    {
      "Label": "IO1",
      "Name": "foo Port 2",
      "Type": "PortDownstream",
      "User": "tlbmc"
    },
    {
      "Name": "Foo Cable Downstream",
      "CableId": "foo_cable",
      "Type": "CableDownstreamConnection",
      "User": "tlbmc"
    },
    ...
    {
      "Name": "cpu0",
      "Type": "Processor",
      "User": "tlbmc"
    },
    {
      "Name": "cpu1",
      "Type": "Processor",
      "User": "tlbmc"
    },
  ],
  ...
  "Storage":
  {
    "Id": "foo_storage",
    "User": "tlbmc"
  }
...
}
```

A snippet of the `Links` field resulting from querying this chassis is provided
below. This has been annotated to show the resources that are tlBMC owned and
not. As seen from the EM config above, several fields are configured for tlBMC
to produce these links but tlBMC does not have ownership of the resource paths
when queried.

<pre><code class="lang-json">
  {
  ...
  "Links": {
    "Cables": [
      {
        "@odata.id": <del>"/redfish/v1/Cables/foo_cable"</del>
      }
    ],
    "Cables@odata.count": 1,
    "ComputerSystems": [
      {
        "@odata.id": "/redfish/v1/Systems/system"
      }
    ],
    "Contains": [
      {
        "@odata.id":<ins>"/redfish/v1/Chassis/bar"</ins>
      },
      {
        "@odata.id":<ins>"/redfish/v1/Chassis/baz"</ins>
      }
    ],
    "Contains@odata.count": 2,
    "ManagedBy": [
      {
        "@odata.id": "/redfish/v1/Managers/bmc"
      }
    ],
    "Processors": [
      {
        "@odata.id": <del>"/redfish/v1/Systems/system/Processors/cpu0"</del>
      },
      {
        "@odata.id":<del> "/redfish/v1/Systems/system/Processors/cpu1"</del>
      }
    ],
    "Processors@odata.count": 2,
    "Storage": [
      {
        "@odata.id": <del>"/redfish/v1/Systems/system/Storage/foo_storage"</del>
      }
    ],
    "Storage@odata.count": 1
  },
  ...
}
</code></pre>

## FRUs Not Detected by tlBMC but Modeled

For some configurations, tlBMC does not detect the existence of the resource but
may model it. tlBMC would have a TRUE probe for the resource i.e. Cables. In
this case, the existence of the cable is implied by the successful detection of
the surrounding Chassis resource and will be populated in the Cables Links of
the associated Chassis.

Here, tlBMC does not own the resource and querying the `/redfish/v1/Cables` path
will return the traditional bmcweb response. tlBMC properties in this case exist
only to correctly populate the associations (Links) to the `/redfish/v1/Cables`
path in the associated resources that tlBMC does own i.e. upstream and
downstream chassis to the cable. This is necessary for tlBMC to correctly fully
own Chassis. In the future, when tlBMC fully owns these resources, the probe
will become a real probe.

An example can be seen from this cable config:

```json
{
  "Exposes": [
    {
      "Name": "Foo Cable Downstream",
      "CableId": "FooCable",
      "Type": "CableUpstreamConnection",
      "User": "tlbmc"
    },
    {
      "Name": "Foo Cable Upstream",
      "CableId": "FooCable",
      "Type": "CableDownstreamConnection",
      "User": "tlbmc"
    }
  ],
  "Name": "NcsiCable",
  "ProbeV2": "TRUE",
  "ResourceType": "RESOURCE_TYPE_CABLE",
  "Type": "Cable",
}
```

Although tlBMC fields are required in this EM config to create the correct
relationships when queried, tlBMC does not own `/redfish/v1/Cables/FooCable` and
this will be served from traditional Bmcweb.