Component Types ​

In openUBMC, there are two types of components: Tianchi Components and Non-Tianchi Components. Tianchi is a protocol which provides hardware modular designs for server components, including standardized discovery process and standardized interfaces between BMC and CPLD.

The board and card management of Tianchi components is basically integrated into the general_hardware component repository.

In order to standardize the interface between BMC and CPLD, Tianchi introduces SMC (Satellite Management Controller) protocol for the communitcations. It's defined by a set of function, opcode, R/W and param.

openUBMC manages Tianchi and non-Tianchi components as follows:

1. CSR (Component Self-description Record) management: The CSR of Tianchi components is stored in the EEPROM of boards, while other CSR are buitt into the BMC firmware.
2. CSR upgrade: Only Tianchi components support CSR upgrade, while other components require BMC upgrade to update the CSR.

Hardware Component Discover Process ​

openUBMC discovers hardware components based on the toplogy of the server. In a typical Tianchi server design, BMC card is connected to the EXU(Extension Unit), which also connects the BCU(Basic Computing Unit), CLU(Cooling Unit), SEU(Storage Expansion Unit) and PSU(Power Supply Unit). IEU(IO Extension Unit) is connected to the BCU and PCIe Cards are connected to the IEU. openUBMC follows breath-first search algorithm to discover the hardware components level by level via Connector. For details about the hardware discovery process, please refer to Hardware Self-Discovery for more details.

Due to the discovery process, CSR are conncted by Connector. Therefore, Connector contains the association information between CSRs. For details, please refer to Connector Object.

Example of Component Discover Process ​

1. Check the Connector object in DBus

   shell

   ~~# busctl --user tree bmc.kepler.hwdiscovery
   └─/bmc
   └─/bmc/kepler
       ├─/bmc/kepler/Connector
       │ ├─/bmc/kepler/Connector/Connector_EXU_1_01

2. Figure 1 shows that root.csr -> EXU. You can view the Connector information of root.csr to find the CSR file of the EXU board.

   shell

   ~~# busctl --user introspect bmc.kepler.hwdiscovery /bmc/kepler/Connector/Connector_EXU_1_01
   NAME                                TYPE      SIGNATURE   RESULT/VALUE         FLAGS
   bmc.kepler.Connector                interface -           -                    -
   .AuxId                              property  s           "01"                 emits-change writa>
   .Bom                                property  s           "14100513"           emits-change
   .Buses                              property  as          0                    emits-change
   .ChassisId                          property  s           ""                   emits-change
   .GroupId                            property  u           2                    emits-change
   .GroupPosition                      property  s           "0101"               emits-change
   .Id                                 property  s           "EXU"                emits-change writa>
   .IdentifyMode                       property  y           2                    emits-change
   .LoadStatus                         property  y           0                    emits-change
   .ManagerId                          property  s           "1"                  emits-change
   .Presence                           property  y           1                    emits-change writa>
   .SilkText                           property  s           "EXU"                emits-change
   .Slot                               property  y           1                    emits-change writa>
   .SystemId                           property  y           1                    emits-change
   .Type                               property  s           ""                   emits-change
   bmc.kepler.Object.Properties        interface -           -                    -
   .GetAllWithContext                  method    a{ss}s      a{sv}                -
   .GetOptions                         method    a{ss}ss     a{ss}                -
   .GetPropertiesByNames               method    a{ss}sas    a{sv}a{sv}           -
   .GetPropertiesByOptions             method    a{ss}sa{ss} as                   -
   .GetWithContext                     method    a{ss}ss     v                    -
   .SetWithContext                     method    a{ss}ssv    -                    -
   .ClassName                          property  s           "Connector"          emits-change
   .ObjectIdentifier                   property  (ysss)      0 "1" "" "01"        emits-change
   .ObjectName                         property  s           "Connector_EXU_1_01" emits-change

   Explanation:

   a. According to the preceding resource collaboration interface information, the Connector object that connects to the downstream board 14100513_EXU_01.csr in root.csr is Connector_EXU_1. For details, see bmc.kepler.Object.Properties.

   b. The attributes and attribute values of Connector_EXU_1 are mounted to the bmc.kepler.Connector interface. You can query the value of IdentifyMode to determine whether to use the Tianchi or non-Tianchi component to load the downstream component.

   c. IdentifyMode = 2 indicates the non-Tianchi loading mode. Combine the Bom, Id, and AuxId to search for the downstream component Bom_Id_AuxId.csr.

   d. IdentifyMode = 3 indicates the Tianchi loading mode. Combine the Bom and Id to search for the downstream component Bom_Id.csr.

Connector Object ​

Connector is a logical concept. In CSR, different components are connected through connectors. Therefore, the correct configuration of the Connector object is crucial to load the downstream components.

Common Connector Configuration

{
    "Connector_xxx": {
        "Bom": ,
        "Slot": ,
        "Position": ,
        "Presence": ,
        "Id": ,
        "AuxId": ,
        "Buses": [],
        "SystemId": ,
        "SilkText": ,
        "IdentifyMode": ,
        "Type": ,
        "ManagerId": ,
        "ChassisId": ,
        "Chip": ,
        "Container": ,
        "IdChipAddr": ,
    }
}

Explanation:

1. The CSR specification defines a Connector object's name as ClassName.InstanceIdentifier, which must be globally unique across the CSR.
2. Configure the attributes of the Connector object following this table.

Loading Modes ​

IdentifyMode is used to define whether the downstream component is Tianchi or not. If set to 3, openUBMC will load the CSR from Eeprom following the Tianchi discovery process. If set to 2, then it will load from local CSR.

root.sr -> EXU -> BCU/SEU/CLU/PSR -> IEU (I/O expansion component) -> PCIe

Loading Mode of Tianchi Components ​

Take the BCU Connector on the EXU as an example (as shown in Figure 1). If the Presence attribute of Connector_BCU is 1, that is, the connected BCU is present. In this case, the framework automatically reads the register (EEPROM) of the downstream object, parses and verifies the UID (unique identifier of each Tianchi component) in the header data in the EEPROM, updates Connector ID, parses the binary data of the EEPROM, and distributes the downstream object. The framework obtains the Bom_Id.sr of the downstream object based on the Bom attribute of the Connector and the UID in the parsed EEPROM data, and directly loads the downstream object file in the EEPROM.

Loading Mode of Non-Tianchi Components ​

Take the PCIe Connector of the Riser card as an example (as shown in Figure 1). During initialization, the PCIe Device component sends an ipmi command to the BIOS to obtain the 4-tuple of the PCIe card in in-band mode and update Connector id and AuxId. Similarly, if the value of the Presence attribute is 1, the downstream component object of the connector is present. In this case, the framework checks whether the Bom_Id_AuxId.sr and Bom_Id_AuxId_soft.sr object files exist and directly loads the built-in .sr file of the BMC.

Component Configuration ​

It is recommended that developers use BMC Studio to configure CSR files as it offers comprehensive guidance to help developers quickly and accurately configure CSR files.

The following uses a riser card as an example to describe how to configure and adapt a component.

A riser card is an adapter card used to expand slots of a computer mainboard. It changes the slot direction on the mainboard from vertical to horizontal so that other internal components can be easily accommodated, especially in a small or space-constrained computer chassis. The riser card is usually used to add more expansion cards, such as audio cards, video cards, and network adapters.

1. The following describes the management topology of the riser card based on its hardware diagram.

   
   json

   {
       "FormatVersion": "3.00",
       "DataVersion": "1.00",
       "Unit": {
           "Type": "IEU",
           "Name": "RiserCard_1"
       },
       "ManagementTopology": {
           "Anchor": {
               "Buses": [
                   "I2c_1"
               ]
           },
           "I2c_1": {
               "Chips": [
                   "Eeprom_IEU",
                   "Pca9545_IEU"
               ]
           },
           "Pca9545_IEU": {
               "Buses": [
                   "I2cMux_9545Chan1",
                   "I2cMux_9545Chan2",
                   "I2cMux_9545Chan3"
               ]
           },
           "I2cMux_9545Chan1": {
               "Connectors": [
                   "Connector_PCIe_1"
               ]
           },
           "I2cMux_9545Chan2": {
               "Connectors": [
                   "Connector_PCIe_2"
               ]
           },
           "I2cMux_9545Chan3": {
               "Chips": [
                   "PCA9555_IEU",
                   "Chip_MCU"
               ]
           }
       }
   }

   Explanation: Configure the relationship between FormatVersion, DataVersion, Unit, and ManagementTopology of the riser card based on the riser card management topology shown in Figure 1.

2. Determine the objects required for configuring a riser card, the attributes of the objects, and the sources of the values.

   • When configuring a riser card, you must configure the RiserCard object to describe the information about the riser card.
   json

   {
       "Objects": {
           "RiserCard_1": {
               "Slot": 1,
               "UID": "00000001040302023940",
               "Name": "BC83PRUI", 
               "Manufacturer": "openUBMC",
               "Type": "IEU",
               "Description": "Riser(X8*2)",
               "PartNumber": "0302023940",
               "PcbID": "#/Accessor_PcbID.Value",
               "PcbVersion": "",
               "LogicVersion": "N/A",
               "SRVersion": "${DataVersion}",
               "MCUVersion": "",
               "BoardID": 65535,
               "BoardType": "RiserCard",
               "Number": 1,
               "DeviceName": "PCIeRiser${Slot}",
               "Position": "chassis",
               "NodeId": "chassisPCIeRiser${Slot}",
               "FruID": "<=/Fru_IEU.FruId",
               "RefMCUChip": "#/Chip_MCU"
           }
       }
   }

   Explanation:

   a. The RiserCard_1 object describes the information about the riser card as follows: The riser card is located in slot 1 of the BCU. The UID that uniquely identifies the riser card is 00000001040302023940. The card name is BC83PRUI. Some riser card information is displayed on the WebUI.

   b. For details about the configuration description of each attribute of the RiserCard object, see Object Configuration > RiserCard.

   2.2 According to the object description of RiserCard_1, the RiserCard needs to reference the MCU register and the MCU is a logic chip that needs to be upgraded. Therefore, you need to configure the object that describes an MCU upgrade and MCU register information.

   json

   {
       "Objects": {
           "Chip_MCU": {
               "OffsetWidth": 1,
               "AddrWidth": 1,
               "Address": 200,
               "WriteTmout": 100,
               "ReadTmout": 100,
               "HealthStatus": 0,
               "WriteRetryTimes": 2,
               "ReadRetryTimes": 0,
               "DrvWriteDelay": "<=/RiserCard_1.MCUVersion |> string.sub($1, 1, 4) |> expr($1 >= '1.12' ? 0 : 1)"
           },
           "MCUFirmware_1": {
               "UID": "00000001040302023940",
               "RefChip": "#/Chip_MCU",
               "Address": 200,
               "SoftwareId": "MCU-BC83PRUI",
               "BoardType": "IEU"
           }
       }
   }

   Explanation:

   a. Describe the information about the register where the MCU is located and the MCU upgrade information.

   b. For details about the configuration description of each attribute of the Chip_MCU object, see Object Configuration > Chip.

   c. For details about the configuration description of each attribute of the MCUFirmware_1 object, see Object Configuration > MCU Upgrade.

   2.3 The riser card is a Tianchi component and uses EEPROM to store CSR data that needs to be updated. Therefore, you need to configure the Eeprom object and SR upgrade object.

   json

   {
       "Objects": {
           "Eeprom_IEU": {
               "OffsetWidth": 2,
               "AddrWidth": 1,
               "Address": 174,
               "WriteTmout": 100,
               "ReadTmout": 100,
               "RwBlockSize": 32,
               "WriteInterval": 20,
               "HealthStatus": 0
           },
           "SRUpgrade_1": {
               "UID": "00000001040302023940",
               "Type": "IEU",
               "Version": "${DataVersion}",
               "StorageChip": "#/Eeprom_IEU",
               "SoftwareId": "HWSR-BC83PRUI",
               "WriteProtect": "#/Accessor_IEUWP.Value"
           }
       }
   }

   Explanation:

   a. It describes the EEPROM information of the IEU component because EEPROM is used to store Fru and CSR information. Therefore, when the CSR information stored in the EEPROM needs to be upgraded, configure the SRUpgrade object. The object configures information such as the name (UID.sr) of the CSR file package to be upgraded, data version of the CSR file to be upgraded, and register of the EEPROM that stores CSR.

   b. For details about the configuration description of each attribute of the Eeprom_IEU object, see Object Configuration > Eeprom.

   c. For details about the configuration description of each attribute of the SRUpgrade_1 object, see Object Configuration > SR Upgrade.

   2.4 A riser card is an adapter card used to expand slots of a computer mainboard. It has many slots, where PCIe cards or other multiplexers can be inserted. The Pca9545 multiplexer is used on the riser card to connect more devices.

   json

   {
       "Objects": {
           "Pca9545_IEU": {
               "OffsetWidth": 0,
               "AddrWidth": 1,
               "Address": 226,
               "WriteTmout": 100,
               "ReadTmout": 100,
               "HealthStatus": 0
           },
           "I2cMux_9545Chan1": {
               "ChannelId": 1
           },
           "I2cMux_9545Chan2": {
               "ChannelId": 2
           },
           "I2cMux_9545Chan3": {
               "ChannelId": 3
           }
       }
   }

   Explanation:

   a. Here, the information about the Pca9545 multiplexer connected to the riser card is described. The three channels of the Pca9545 multiplexer are used to expand the line.

   b. For details about the configuration description of each attribute of the Pca9545_IEU object, see Object Configuration > Pca9545.

   2.5 Since the Pca9545 multiplexer is used to expand the number of devices, the following describes the information about the devices mounted to the three channels of Pca9545.

   json

   {
       "Objects": {
           "Connector_PCIe_1": {
               "Bom": "14140130",
               "Slot": 1,
               "Position": 1,
               "Presence": 0,
               "Id": "",
               "AuxId": "",
               "Buses": [
                   "I2cMux_9545Chan1"
               ],
               "SystemId": "${SystemId}",
               "ManagerId": "${ManagerId}",
               "ChassisId": "${ChassisId}",
               "SilkText": "RiserCard${Slot}",
               "IdentifyMode": 2,
               "Container": "Component_RiserCard",
               "Type": "PCIe"
           }
       }
   }

   Explanation:

   a. A PCIe device is mounted to the I2cMux_9545Chan1 channel of Pca9545. Herein, how to search for the information about the connected downstream PCIe device is described.

   b. For details about the configuration description of each attribute of the Connector_PCIe_1 object, see Connector.

   json

   {
       "Objects": {
           "Connector_PCIe_2": {
               "Bom": "14140130",
               "Slot": 2,
               "Position": 2,
               "Presence": 0,
               "Id": "",
               "AuxId": "",
               "Buses": [
                   "I2cMux_9545Chan2"
               ],
               "SystemId": "${SystemId}",
               "ManagerId": "${ManagerId}",
               "ChassisId": "${ChassisId}",
               "SilkText": "RiserCard${Slot}",
               "IdentifyMode": 2,
               "Container": "Component_RiserCard",
               "Type": "PCIe"
           }
       }
   }

   Explanation:

   a. Another PCIe device is mounted to the I2cMux_9545Chan2 channel of Pca9545. Herein, how to search for the information about the connected downstream PCIe device is described.

   b. For details about the configuration description of each attribute of the Connector_PCIe_2 object, see Connector.

   json

   {
       "Objects": {
           "Pca9555_IEU": {
               "OffsetWidth": 1,
               "AddrWidth": 1,
               "Address": 64,
               "WriteTmout": 100,
               "ReadTmout": 100,
               "HealthStatus": 0
           },
           "Scanner_Riser3V3Event": {
               "Chip": "#/Pca9555_IEU",
               "Offset": 1,
               "Size": 1,
               "Mask": 16,
               "Type": 0,
               "Period": 400,
               "Debounce": "#/Cont_num5",
               "Value": 0
           },
           "Accessor_PcbID": {
               "Chip": "#/Pca9555_IEU",
               "Offset": 1,
               "Size": 1,
               "Mask": 192,
               "Type": 0,
               "Value": 0
           },
           "Accessor_IEUWP": {
               "Chip": "#/Pca9555_IEU",
               "Size": 1,
               "Offset": 1,
               "Mask": 8,
               "Type": 0,
               "Value": 0
           },
           "Event_Riser3V3Event": {
               "EventKeyId": "Riser.PowerFailure",
               "Condition": 0,
               "Reading": "<=/Scanner_Riser3V3Event.Value",
               "@Default": {
                   "Reading": 1
               },
               "OperatorId": 5,
               "Enabled": false,
               "AdditionalInfo": "1",
               "DescArg1": "#/RiserCard_1.Slot",
               "Component": "#/Component_RiserCard"
           },
           "Cont_num5": {
               "Num": 5,
               "DefaultValue": 1
           }
       }
   }

   Explanation:

   a. The I2cMux_9545Chan3 channel of the Pca9545 is mounted with the register where the MCU is located (for details, see the preceding description) and the Pca9555 multiplexer.

   b. The PcbID needs to be associated with the hardware. Therefore, the Accessor object needs to be configured to read the hardware where the PcbID is located.

   c. The riser card has the 3.3 V voltage. You need to periodically scan the 3.3 V voltage information and configure related alarm events. For details about how to configure the event, see Event Customization. For details about how to configure the scanner, see Object Configuration > Scanner.

   d. When data is read from the register, false alarms may occur due to component jitter. In this case, configure a filter to filter out abnormal scenarios. For details about the Cont configuration, see Object Configuration > Cont.

   e. The Accessor_IEUWP object is used to set the write protection switch of the EEPROM. Possible values are 0: off; 1: on.

   2.6 A riser card is a field replaceable unit (FRU). You need to configure the Fru type object to describe it.

   json

   {
       "Objects": {
           "Fru_IEU": {
               "PcbId": 1,
               "FruId": 1,
               "FruName": "PCIe Riser${Slot}",
               "ConnectorGroupId": "${GroupId}",
               "BoardId": 65535,
               "UniqueId": "00000001040302023940",
               "PcbVersion": ".A",
               "PowerState": 1,
               "Health": 0,
               "EepStatus": "<=/Eeprom_IEU.HealthStatus",
               "Type": 195,
               "FruDataId": "#/FruData_IEU"
           },
           "FruData_IEU": {
               "FruId": 1,
               "FruDev": "#/Eeprom_IEU",
               "EepromWp": "#/Accessor_IEUWP.Value",
               "StorageType": "TianChi"
           },
           "Component_RiserCard": {
               "FruId": "<=/Fru_IEU.FruId",
               "Instance": 0,
               "Type": 15,
               "Location": "<=/RiserCard_1.Position",
               "Name": "<=/RiserCard_1.DeviceName",
               "Presence": 1,
               "Health": 0,
               "PowerState": 1,
               "GroupId": 1,
               "UniqueId": "<=/RiserCard_1.UID",
               "NodeId": "<=/RiserCard_1.Position;<=/RiserCard_1.DeviceName |> string.format('%s%s',$1,$2)",
               "BoardId": "<=/RiserCard_1.BoardID",
               "PartNumber": "<=/RiserCard_1.PartNumber"
           }
       }
   }

   Explanation:

   a. A riser card is an FRU, and you need to use the Fru object to describe its overall information, electronic label information, and component information.

   b. For the configuration description of each attribute of the Fru_IEU class, see Object Configuration > Fru Class > Fru.

   c. For the configuration description of each attribute of the FruData_IEU class, see Object Configuration > Fru Class > FruData.

   d. For the configuration description of each attribute of the Component_RiserCard object, see Object Configuration > Fru Class > Component.

   2.7 The riser card is mounted to the I2C link, and the Pca9545 and Pca9555 multiplexers are mounted to the riser card. Perform self-check for these links to provide query interfaces for the equipment test phase.

   json

   {
       "Objects": {
           "DftPca9555_1": {
               "Type": 1,
               "Id": 3,
               "Slot": "${GroupId}",
               "DeviceNum": 0,
               "ItemName": "PCA9555 For IEU${Slot}",
               "PrompteReady": "",
               "PrompteFinish": "",
               "ProcessPeriod": 65535,
               "RefChip": "#/Pca9555_IEU"
           },
           "DftPca9545_1": {
               "Type": 1,
               "Id": 4,
               "Slot": "${GroupId}",
               "DeviceNum": 0,
               "ItemName": "PCA9545 For IEU${Slot}",
               "PrompteReady": "",
               "PrompteFinish": "",
               "ProcessPeriod": 65535,
               "RefChip": "#/Pca9545_IEU"
           },
           "DftI2c_1": {
               "Type": 1,
               "Id": 33,
               "DeviceNum": 0,
               "Slot": "${GroupId}",
               "ItemName": "I2C-${Slot} Test",
               "PrompteReady": "",
               "PrompteFinish": "",
               "ProcessPeriod": 65535,
               "RefChip": "#/Pca9545_IEU"
           }
       }
   }

   Explanation:

   a. The DftPca9545_1 object is used to support the self-check of the Pca9545 component.

   b. The DftPca9555_1 object is used to support the self-check of the Pca9555 component.

   c. The DftI2c_1 object is used to support self-check over the I2C link. It achieves coverage by associating it with any simple component class for self-test, and in this case, the associated component is Pca9545.

   json

   {
       "Objects": {
           "DftEeprom_1": {
               "Id": 12,
               "Type": 1,
               "Slot": "${GroupId}",
               "DeviceNum": 0,
               "ItemName": "IEU Eeprom Self Test",
               "PrompteReady": "",
               "PrompteFinish": "",
               "ProcessPeriod": 65535,
               "FruData": "#/FruData_IEU"
           },
           "DftEepromWp_1": {
               "Id": 47,
               "Type": 1,
               "Slot": "${GroupId}",
               "DeviceNum": 0,
               "ItemName": "IEU Eeprom Write Protect Self Test",
               "PrompteReady": "",
               "PrompteFinish": "",
               "ProcessPeriod": 65535,
               "FruData": "#/FruData_IEU"
           },
           "DftVersion_RiserCardPcbVersion": {
               "FruId": "<=/Fru_IEU.FruId",
               "VersionType": 0,
               "Version": "<=/RiserCard_1.PcbVersion"
           },
           "DftVersion_RiserCardCsrVersion": {
               "FruId": "<=/Fru_IEU.FruId",
               "VersionType": 25,
               "Version": "<=/RiserCard_1.SRVersion"
           },
           "DftVersion_RiserCardMcuVersion": {
               "FruId": "<=/Fru_IEU.FruId",
               "VersionType": 27,
               "Version": "<=/RiserCard_1.MCUVersion"
           }
       }
   }

   Explanation: DftEeprom and DftEepromWp are used to support the write protection test of the EEPROM. DftVersion is used to support the version test.

   2.8 Generally, a PCIe card is inserted into a riser card (the PCIe card can be found based on the Connector object configured above). If the configured PCIe card is not a Tianchi component, you need to obtain the 4-tuple information of the PCIe card in in-band mode to combine Id and AuxId, and then fill it into the Connector object. The downstream object is loaded during the hardware self-discovery.

   Before obtaining the 4-tuple information in in-band mode, establish the mapping between the BCU port and IEU port. On the IEU side, the connection to the BCU side is implemented through the definition of BusinessConnector. The ports on both sides are in one-to-one mapping. Therefore, you need to find the upstream BCU objects for configuring the IEU. For details, see PCIe Configuration.

   PSR.sr

   json

   {
       "Objects": {
           "UnitConfiguration_IEU2": {
               "SlotType": "IEU",
               "SlotNumber": 2,
               "SlotSilkText": "IEUSlot2",
               "Configurations": [
                   {
                       "UID": "00000001040302023940",
                       "Index": 2,
                       "SrcPortName": [
                           "B2a",
                           "B2c"
                       ],
                       "TargetPortID": [
                           49,
                           50
                       ],
                       "Slot": [
                           5,
                           6
                       ],
                       "Device": []
                   }
               ],
               "Port1LinkInfo": ""
           }
       }
   }

   BCU.sr

   json

   {
       "Objects": {
           "BusinessConnector_CPU2UBCDD1": {
               "Direction": "Downstream",
               "BCUIndex": "${Slot}",
               "Slot": 6,
               "LinkWidth": "X16",
               "MaxLinkRate": "PCIe 4.0",
               "ConnectorType": "UBCDD",
               "SilkText": "CPU2 UBCDD1",
               "UpstreamResources": [
                   {
                       "Name": "SerDes_1_5",
                       "ID": 5,
                       "Offset": 0,
                       "Width": 8
                   },
                   {
                       "Name": "SerDes_1_6",
                       "ID": 6,
                       "Offset": 0,
                       "Width": 8
                   }
               ],
               "ActualResourceOrder": [
                   "SerDes_1_6",
                   "SerDes_1_5"
               ],
               "Ports": [
                   {
                       "Name": "B2a",
                       "ID": 5,
                       "Offset": 0,
                       "Width": 8
                   },
                   {
                       "Name": "B2c",
                       "ID": 7,
                       "Offset": 8,
                       "Width": 8
                   }
               ],
               "Port1LinkInfo": "",
               "Port2LinkInfo": ""
           },
           "SerDes_1_5": {
               "Name": "SerDes_1_5",
               "ID": 5,
               "SocketID": 1,
               "LinkWidth": 8,
               "WorkMode": 1,
               "ModeConfigs": [
                   {
                       "Mode": 1,
                       "Device": [0,0,1,1,2,2,3,3],
                       "ControllerIndex": [0,0,0,0,0,0,0,0]
                   },
                   {
                       "Mode": 4,
                       "Device": [4,4,4,4,4,4,4,4],
                       "ControllerIndex": [1,1,1,1,1,1,1,1]
                   }
               ]
           },
           "SerDes_1_6": {
               "Name": "SerDes_1_6",
               "ID": 6,
               "SocketID": 1,
               "LinkWidth": 8,
               "WorkMode": 1,
               "ModeConfigs": [
                   {
                       "Mode": 1,
                       "Device": [4,4,5,5,6,6,7,7],
                       "ControllerIndex": [0,0,0,0,0,0,0,0]
                   },
                   {
                       "Mode": 1,
                       "Device": [2,2,2,2,2,2,2,2],
                       "ControllerIndex": [0,0,0,0,0,0,0,0]
                   }
               ]
           },
       }
   }

   RiserCard.sr

   json

   {
       "Objects": {
           "BusinessConnector_1": {
               "Name": "Up_1",
               "Direction": "Upstream",
               "Slot": 1,
               "LinkWidth": "X16",
               "MaxLinkRate": "PCIe 4.0",
               "ConnectorType": "UBCDD",
               "Ports": [
                   {
                       "Name": "Down_1",
                       "ID": 49,
                       "Offset": 0,
                       "Width": 8
                   },
                   {
                       "Name": "Down_2",
                       "ID": 50,
                       "Offset": 8,
                       "Width": 8
                   }
               ]
           },
           "BusinessConnector_2": {
               "Name": "Down_1",
               "Direction": "Downstream",
               "Slot": 1,
               "LinkWidth": "X8",
               "MaxLinkRate": "PCIe 4.0",
               "ConnectorType": "PCIe CEM",
               "UpstreamResources": [
                   {
                       "Name": "Up_1",
                       "ID": 255,
                       "Offset": 0,
                       "Width": 8
                   }
               ],
               "RefMgmtConnector": "#/Connector_PCIe_1",
               "RefPCIeAddrInfo": "#/PcieAddrInfo_1"
           },
           "BusinessConnector_3": {
               "Name": "Down_2",
               "Direction": "Downstream",
               "Slot": 2,
               "LinkWidth": "X8",
               "MaxLinkRate": "PCIe 4.0",
               "ConnectorType": "PCIe CEM",
               "UpstreamResources": [
                   {
                       "Name": "Up_1",
                       "ID": 255,
                       "Offset": 8,
                       "Width": 8
                   }
               ],
               "RefMgmtConnector": "#/Connector_PCIe_2",
               "RefPCIeAddrInfo": "#/PcieAddrInfo_2"
           }
       }
   }

   Explanation:

   a. The BusinessConnector object of IEU.sr needs to be classified into two types: One is connected to the upstream BCU.sr, and the other is connected to the downstream PCIe device.

   b. The connection to the upstream BCU is established through the UBCDD. Set ConnectorType of the BusinessConnector object to UBCDD. To configure some attributes of this object, find the corresponding PSR.sr and BCU.sr. Specifically, the IDs (49 and 50) of the Ports attribute of the BusinessConnector_1 object in the IEU.sr file must be the same as the TargetPortID value in the Configurations attribute of the UnitConfiguration_IEU2 object in the PSR.sr file. The SrcPortName attribute (B2a and B2c) and Slot attribute (5 and 6) of the Configurations object are the same as the Name and ID in the Ports attribute of the BusinessConnector_CPU2UBCDD1 object in the BCU.sr file. In addition, configure the SerDes_1_5 and SerDes_1_6 objects in the BCU.sr file. The Device attribute value of the SerDes object must be the same as the PortId value of the PCIeAddrInfo object, as the SocketID attribute indicates the model of the CPU connected to the SerDes. In this way, a mapping relationship between the BCU and IEU is established, and the RootBDF can be calculated based on the mapping relationship.

   c. The connection to the downstream PCIe is established through the PCIe CEM. Set ConnectorType of the BusinessConnector object to PCIe CEM.

   d. For details about the configuration description of the BusinessConnector_1, BusinessConnector_2, and BusinessConnector_3 objects, see Object Configuration > BusinessConnector.

   2.9 Use the BusinessConnector object to establish the mappings between BCU and IEU and between IEU and PCIe and calculate the RootBDF based on the mapping between BCU and IEU. Then configure the PCIeAddrInfo object based on RootBDF and send the ipmi command in-band based on the attribute value to obtain the PCIe deviceBDF information.

   json

   {
       "Objects": {
           "PcieAddrInfo_1": {
               "Location": "RiserCard${Slot}",
               "ComponentType": 8,
               "ContainerSlot": "${Slot}",
               "ContainerUID": "00000001040302023940",
               "ContainerUnitType": "IEU",
               "GroupPosition": "PcieAddrInfo_1_${GroupPosition}"
           },
           "PcieAddrInfo_2": {
               "Location": "RiserCard${Slot}",
               "ComponentType": 8,
               "ContainerSlot": "${Slot}",
               "ContainerUID": "00000001040302023940",
               "ContainerUnitType": "IEU",
               "GroupPosition": "PcieAddrInfo_2_${GroupPosition}"
           }
       }
   }

   Explanation:

   a. The PcieAddrInfo_1 object is configured to send SlotId, SocketId, and DeviceId in-band to obtain the PCIe deviceBDF information that is then used to query the 4-tuple information about PCIeDevice. Based on the 4-tuple, combine Id and AuxId and fill it into Connector_PCIe_1 to load the downstream PCIe device during hardware self-discovery. For details, see PCIe Configuration.

   b. The PcieAddrInfo_2 object is configured to send SlotId, SocketId, and DeviceId in-band to obtain the PCIe deviceBDF information that is then used to query the 4-tuple information about PCIeDevice. Based on the 4-tuple, combine Id and AuxId and fill it into Connector_PCIe_2 to load the downstream PCIe device during hardware self-discovery. For details, see PCIe Configuration.

   The CSR file of a riser card has been configured. The next step is to perform component adaptation and check whether the riser card can be successfully loaded in the environment.

Component Adaptation ​

Loading a Component ​

1. Use the BMC built-in mode.

   a. Configure the Bom_id.sr file of the riser card in the VPD component repository, for example, riser_00000001040302023940.sr.

   b. Configure or modify the information about the Connector object connected to the riser card in the CSR file of the BCU.

   json

   {
       "Objects": {
           "Connector_IEU_1": {
               "Bom": "14100513",
               "Slot": 1,
               "Position": 1,
               "Presence": 1,
               "Id": "",
               "AuxId": "",
               "Buses": [],
               "SystemId": 1,
               "SilkText": "IEU",
               "IdentifyMode": 2,
               "Container": "Component_RiserCard"
           }
       }
   }

   c. Add the riser card file path to the profile file.

   shell

   /sr/riser_00000001040302023940.sr

   d. Generate the package and verify it in the environment. For details about the package generation process, see BMC Studio CLI (bingo) and BMC Studio User Guide.

2. Use the EEPROM format.

   a. Pack the configured uid.sr file of the riser card, for example, riser_00000001040302023940.sr, into an IMG package. For details, see BMC Studio User Guide.

   b. Upgrade the IMG package of the riser card in the environment.

   c. Verify it in the environment.

Environment Verification ​

1. Find the file in the environment.

   shell

   ~ ~ $ find / -name riser_00000001040302023940.sr
   ../sr/riser_00000001040302023940.sr

2. Run the busctl command in the environment to view information about RiserCard to which the resource collaboration interface is mounted.

   shell

   ~ ~ $ busctl --user introspect bmc.kepler.general_hardware /bmc/kepler/Systems/1/Boards/RiserCard/RiserCard_1_01010101
   NAME                                TYPE      SIGNATURE   RESULT/VALUE           FLAGS
   bmc.kepler.Object.Properties        interface -           -                      -
   .GetAllWithContext                  method    a{ss}s      a{sv}                  -
   .GetOptions                         method    a{ss}ss     a{ss}                  -
   .GetPropertiesByNames               method    a{ss}sas    a{sv}a{sv}             -
   .GetPropertiesByOptions             method    a{ss}sa{ss} as                     -
   .GetWithContext                     method    a{ss}ss     v                      -
   .SetWithContext                     method    a{ss}ssv    -                      -
   .ClassName                          property  s           "RiserCard"            emits-change
   .ObjectIdentifier                   property  (ysss)      1 "1" "" "01010101"    emits-change
   .ObjectName                         property  s           "RiserCard_1_01010101" emits-change
   bmc.kepler.Systems.Board            interface -           -                      -
   .BoardID                            property  q           65535                  emits-change
   .BoardType                          property  s           "RiserCard"            emits-change
   .CpldStatus                         property  y           255                    emits-change
   .Description                        property  s           "Riser(X8*2)"          emits-change
   .DeviceName                         property  s           "PCIeRiser1"           emits-change
   .FruID                              property  y           0                      emits-change
   .LogicUnit                          property  u           0                      emits-change
   .LogicVersion                       property  s           "N/A"                  emits-change
   .MCUVersion                         property  s           ""                     emits-change
   .Manufacturer                       property  s           "openUBMC"               emits-change
   .MultiLogicUnit                     property  a{su}       0                      emits-change
   .MultiLogicVersion                  property  a{ss}       0                      emits-change
   .Name                               property  s           "BC83PRUI"             emits-change
   .NodeId                             property  s           "chassisPCIeRiser1"    emits-change
   .Number                             property  y           1                      emits-change
   .PSIPVersion                        property  s           ""                     emits-change
   .PartNumber                         property  s           "0302023940"           emits-change
   .PcbVersion                         property  s           ".A"                   emits-change
   .Position                           property  s           "chassis"              emits-change
   .PowerWatts                         property  u           0                      -
   .ProductName                        property  s           ""                     emits-change
   .RefComponent                       property  s           ""                     emits-change
   .RefFru                             property  s           ""                     emits-change
   .RunningStatus                      property  y           1                      emits-change
   .SRVersion                          property  s           "1.00"                 emits-change
   .SerialNumber                       property  s           ""                     emits-change
   .SilkText                           property  s           ""                     emits-change
   .Slot                               property  y           1                      emits-change
   bmc.kepler.Systems.Board.Unit       interface -           -                      -
   .CurrentUpgradeStatus               property  y           0                      emits-change
   .HWSRVersion                        property  s           ""                     emits-change
   .Type                               property  s           "IEU"                  emits-change
   .UID                                property  s           "00000001040302023940" emits-change

Object Configuration ​

RiserCard ​

During the component loading and adaptation, the RiserCard object is used to describe the riser card information.

Common attribute structure of RiserCard

{
    "RiserCard_xxx": {
        "Slot": ,
        "Number": ,
        "Position": ,
        "Name": ,
        "ProductName": ,
        "SilkText": ,
        "Manufacturer": ,
        "Description": ,
        "BoardID": ,
        "PartNumber": ,
        "PcbVersion": ,
        "LogicVersion": ,
        "SRVersion": ,
        "MCUVersion": ,
        "LogicUnit": ,
        "PowerWatts": ,
        "RunningStatus": ,
        "FruID": ,
        "DeviceName": ,
        "BoardType": ,
        "NodeId": ,
        "RefComponent": ,
        "RefFru": ,
        "SerialNumber": ,
        "CpldStatus": ,
        "UID": ,
        "Type": ,
        "PcbID": ,
        "LogicVersionID": ,
        "RefMCUChip": ,
        "RefSMCChip": ,
        "Container": ,
        "CpldTestNum":
    }
}

Explanation:

1. The CSR specification defines a RiserCard object's name as ClassName.InstanceIdentifier, which must be globally unique across the CSR.
2. Configure the attributes of the RiserCard object following this table.

MCU Upgrade ​

An MCU is a microcontroller unit that needs to be upgraded in the CSR file.

Common attribute structure of an MCU object to be upgraded

{
    "MCUFirmware_xxx": {
        "UID": ,
        "RefChip": ,
        "Address": ,
        "Protocol": ,
        "SoftwareId": ,
        "BoardType": ,
        "LockChip": 
    }
}

Explanation:

1. The CSR specification defines a MCUFirmware object's name as ClassName.InstanceIdentifier, which must be globally unique across the CSR.
2. Configure the attributes of the MCUFirmware object following this table.

Chip ​

Chip is used to describe physical registers.

Common attribute structure of Chip

{
    "Chip_xxx": {
        "HealthStatus": ,
        "PowerStatus": ,
        "SelfTestResult": ,
        "Supported": ,
        "BaseOffset": ,
        "Length": ,
        "Period": ,
        "Address": ,
        "AddrWidth": ,
        "OffsetWidth": ,
        "WriteTmout": ,
        "ReadTmout": ,
        "WriteRetryTimes": ,
        "ReadRetryTimes": ,
        "DrvWriteDelay": ,
    }
}

Explanation:

1. The CSR specification defines a Chip object's name as ClassName.InstanceIdentifier, which must be globally unique across the CSR.
2. Configure the attributes of the Chip object following this table.

SR Upgrade ​

When the CSR file stored in the EEPROM needs to be updated, the SR upgrade object needs to be configured in the CSR file to notify the register where the EEPROM is located.

Common attribute structure of an SR object to be upgraded

{
    "SRUpgrade_xxx": {
        "UID": ,
        "Type": ,
        "Version": ,
        "StorageChip": ,
        "SoftwareId": ,
        "WriteProtect": ,
        "StorageLockChip": ,
        "WriteProtectChip": ,
        "WriteProtectLockChip": 
    }
}

Explanation:

1. The CSR specification defines a SRUpgrade object's name as ClassName.InstanceIdentifier, which must be globally unique across the CSR.
2. Configure the attributes of the SRUpgrade object following this table.

Eeprom ​

According to the Tianchi architecture specifications, each component must have a storage device with the I2C bus address 0xAE. Currently, it is the Eeprom device, which is used to store hardware self-description information, including the header, electronic label, component self-description record (CSR), and extended information.

Common attribute structure of Eeprom

{
    "Eeprom_xxx": {
        "HealthStatus": ,
        "PowerStatus": ,
        "SelfTestResult": ,
        "Address": ,
        "AddrWidth": ,
        "OffsetWidth": ,
        "WriteTmout": ,
        "ReadTmout": ,
        "RwBlockSize": ,
        "WriteInterval": 
    }
}

Explanation:

1. The CSR specification defines a Eeprom object's name as ClassName.InstanceIdentifier, which must be globally unique across the CSR.
2. Configure the attributes of the Eeprom object following this table.

Address must be the same as the hardware design

Pca9545 ​

Pca9545 is an I2c multiplexer used to extend bus channels. It can split a bus into four independent channels, each of which can connect to different secondary devices. You can enable one of the channels by writing a specific bit in the internal registers of Pca9545. Only one channel can be enabled at a time. Pca9545 is often used in hardware design to increase the number of secondary devices, especially when multiple devices are required but the number of buses is limited.

Common attribute structure of Pca9545

{
    "Pca9545_xxx": {
        "HealthStatus": ,
        "PowerStatus": ,
        "SelfTestResult": ,
        "Address": ,
        "AddrWidth": ,
        "OffsetWidth": ,
        "WriteTmout": ,
        "ReadTmout": ,
    }
}

Explanation:

1. The CSR specification defines a Pca9545 object's name as ClassName.InstanceIdentifier, which must be globally unique across the CSR.
2. Configure the attributes of the Pca9545 object following this table.
3. Address must be the same as the hardware design in order to allow openUBMC to switch the channel correctly.
4. Pca9545 is also a register and it has only one channel that can operate. Switching between channels may involve read/write timeout issues, so relevant attributes need to be configured.

Scanner ​

When a Scanner object is configured in the CSR file, the object periodically scans its referenced registers and updates the obtained attribute values to the resource collaboration interface. This is only used in read-only scenarios.

Common attribute structure of Scanner

{
    "Scanner_xxx": {
        "Chip": ,
        "Offset": ,
        "Size": ,
        "Mask": ,
        "Type": ,
        "Period": ,
        "Debounce": ,
        "Value": ,
        "AggregateOffset": ,
        "ScanEnabled": ,
        "NominalValue": ,
        "FailureDebounceCount": ,
        "SuccessDebounceCount": 
    }
}

Explanation:

1. The CSR specification defines a Scanner object's name as ClassName.InstanceIdentifier, which must be globally unique across the CSR.
2. Configure the attributes of the Scanner object following this table.

Key parameters:

Accessor ​

Accessor is applicable to scenarios where values do not need to be obtained cyclically and periodically or hardware values need to be written. The attribute is readable and writable. When a value is obtained, the framework listens to read-only signals, reads the hardware values in real time, and updates them to the resource collaboration interface. When a value is written, the framework listens to change signals and writes them to the hardware in real time.

Accessor configuration example

{
    "Accessor_xxx": {
        "Chip": ,
        "Offset": ,
        "Size": ,
        "Mask": ,
        "Type": ,
        "Value": ,
        "FailureDebounceCount": ,
        "SuccessDebounceCount": 
    }
}

Explanation:

1. The CSR specification defines a Accessor object's name as ClassName.InstanceIdentifier, which must be globally unique across the CSR.
2. Configure the attributes of the Accessor object following this table.

Debounce ​

When data is read from the physical register, false alarms may occur due to component jitter. In this case, take anti-jitter measures to filter out false alarms. The Debounce objects include MidAvg, Median, Cont, ContBin, and None.

The Debounce object defined in the CSR file must be referenced by at least one Scanner object.

Cont ​

The Cont object is used for the continuous and consistent anti-jitter policy.

Common attribute structure of Cont

{
    "Cont_xxx": {
        "Num": ,
        "DefaultValue": 
    }
}

Explanation:

1. The CSR specification defines a Cont object's name as ClassName.InstanceIdentifier, which must be globally unique across the CSR.
2. Configure the attributes of the Cont object following this table.

Fru Class ​

If the CSR file describes FRUs, such as the mainboard, RAID controller card, and disk backplane, configure Fru objects. One FRU has only one Fru object.

Common attribute structure of Fru

{
    "Fru_xxx": {
        "PcbId": ,
        "PcbVersion": ,
        "FruId": ,
        "FruName": ,
        "PowerState": ,
        "Health": ,
        "EepStatus": ,
        "GroupPosition": ,
        "Type": ,
        "BoardId": ,
        "UniqueId": ,
        "FruDataId": ,
        "ConnectorGroupId": 
    }
}

Explanation:

1. The CSR specification defines a Fru object's name as ClassName.InstanceIdentifier, which must be globally unique across the CSR.
2. Configure the attributes of the Fru object following this table.

The electronic label data (FruData) describes the information stored in the EEPROM of the FRU. One FRU has a maximum of one FruData object. The FruData object configured in the CSR file is distributed to the framework. The framework parses the data stored in the EEPROM and file by domain and field.

Common attribute structure of FruData

{
    "FruData_xxx": {
        "FruId": ,
        "FruType": ,
        "FruName": ,
        "BoardManufacturer": ,
        "BoardProductName": ,
        "BoardSerialNumber": ,
        "BoardPartNumber": ,
        "ProductSerialNumber": ,
        "SystemProductName": ,
        "SystemSerialNumber": ,
        "FruDev": ,
        "EepromWp": ,
        "StorageType": ,
        "StorageLoc":
    }
}

Explanation:

1. The CSR specification defines a FruData object's name as ClassName.InstanceIdentifier, which must be globally unique across the CSR.
2. Configure the attributes of the FruData object following this table.

The Component class indicates management information about components, such as memory, disks, and fans. An FRU can contain multiple components. During alarm configuration, a Component object is also configured for event management.

Common attribute structure of Component

{
    "Component_xxx": {
        "FruId": ,
        "Instance": ,
        "Type": ,
        "Name": ,
        "Presence": ,
        "Health": ,
        "PowerState": ,
        "BoardId": ,
        "UniqueId": ,
        "Manufacturer": ,
        "GroupId": ,
        "Location": ,
        "SerialNumber": ,
        "PartNumber": ,
        "SegmentId": ,
        "Function": ,
        "PreviousSN": ,
        "ReplaceFlag": ,
        "NodeId":
    }
}

Explanation:

1. The CSR specification defines a Component object's name as ClassName.InstanceIdentifier, which must be globally unique across the CSR.
2. Configure the attributes of the Component object following this table.

BusinessConnector ​

BusinessConnector objects are classified into upstream and downstream objects. UpstreamResource of the downstream BusinessConnector is configured with the Name of the upstream object. For details about the BusinessConnector object, see PCIe Configuration.

Common attribute structure of BusinessConnector

{
    "BusinessConnector_xxx": {
        "Port1LinkInfo": ,
        "Port1Status": ,
        "Port2LinkInfo": ,
        "Port2Status": ,
        "Name": ,
        "Direction": ,
        "Slot": ,
        "LinkWidth": ,
        "MaxLinkRate": ,
        "ConnectorType": ,
        "SilkText": ,
        "UpstreamResources": ,
        "ActualResourceOrder": ,
        "Ports": ,
        "RefMgmtConnector": ,
        "RefMgmtConnectorTianChi": ,
        "RefPCIeAddrInfo": ,
        "BCUIndex": ,
    }
}

Explanation:

1. The CSR specification defines a BusinessConnector object's name as ClassName.InstanceIdentifier, which must be globally unique across the CSR.
2. Configure the attributes of the BusinessConnector object following this table.

Remarks:

1. UBCDD: a connector with BusinessConnector objects (upstream and downstream).
2. SerDes-x: also called HiLink, represents a set of interfaces provided by the CPU. The interfaces are connected to the UBCDD. The SerDes_xxx object is configured and described in the BCU.sr file.

PcieAddrInfo ​

If the PCIe card is not a Tianchi component, Bom_Id_AuxId is used to search for the corresponding .sr file. The Id and AuxId are obtained in in-band mode.

The PcieAddrInfo object carries the PCIe device slot information. PCIeDevice is loaded after its upstream PCIeAddrInfo object is loaded. The slot number and BDF in PCIeDevice are synchronized from PCIeAddrInfo.

Common attribute structure of PcieAddrInfo

{
    "PcieAddrInfo_xxx": {
        "GroupID": ,
        "SlotID": ,
        "ComponentType": ,
        "ControllerIndex": ,
        "ControllerType": ,
        "SocketID": ,
        "Segment": ,
        "Bus": ,
        "Device": ,
        "Function": ,
        "VendorID": ,
        "DeviceID": ,
        "PortID": ,
        "ContainerUID": ,
        "ContainerUnitType": ,
        "Location": ,
        "ContainerSlot": ,
        "DevBus": ,
        "DevDevice": ,
        "DevFunction": ,
        "GroupPosition": 
    }
}

Explanation:

1. The CSR specification defines a PcieAddrInfo object's name as ClassName.InstanceIdentifier, which must be globally unique across the CSR.
2. Configure the attributes of the PcieAddrInfo object following this table.

Object Configuration of Tianchi Components ​

The following describes how to upgrade the Board object of Tianchi components and the three types of Tianchi logical objects.

Board ​

The following uses the CpuBoard object as an example to describe how to configure Board.

CpuBoard describes the information about the board where the CPU is located, including the device name and vendor.

CpuBoard configuration example

{
    "CpuBoard_xxx": {
        "Slot": ,
        "Number": ,
        "Position": ,
        "Name": ,
        "ProductName": ,
        "SilkText": ,
        "Manufacturer": ,
        "Description": ,
        "BoardID": ,
        "PartNumber": ,
        "PcbVersion": ,
        "LogicVersion": ,
        "SRVersion": ,
        "MCUVersion": ,
        "PSIPVersion": ,
        "LogicUnit": ,
        "PowerWatts": ,
        "RunningStatus": ,
        "FruID": ,
        "DeviceName": ,
        "BoardType": ,
        "NodeId": ,
        "RefComponent": ,
        "RefFru": ,
        "CpldStatus": ,
        "MultiLogicVersion": ,
        "MultiLogicUnit": ,
        "UID": ,
        "Type": ,
        "Platform": ,
        "BIOSVersion": ,
        "PcbID": ,
        "LogicVersionID": ,
        "CPLD2VersionID":
    }
}

Explanation:

1. The CSR specification defines a CpuBoard object's name as ClassName.InstanceIdentifier, which must be globally unique across the CSR.
2. Configure the attributes of the CpuBoard object following this table.

Key parameters: