文档中心
NIC Adaptation Guide
更新时间： 2025/07/01
在Gitcode上查看源码

This section describes how to adapt a NIC on openUBMC.

NIC Introduction ​

The network interface controller (NIC), also known as a network adapter, network interface card, or LAN adapter, is the hardware that enables the server to communicate over a network.

NICs are a key part of modern infrastructure. As technology advances, many different types of NICs have been developed. In out-of-band management, supporting diverse NICs has been a challenge in BMC technology. Based on the adapted NICs, openUBMC has formed a unified management framework to standardize management.

NIC Adaptation Process ​

Like other components, each NIC has a CSR file.

NOTE

To simplify CSR configuration, you are advised to use BMC Studio for adaptation.

The Role of CSR in NIC Adaptation ​

The CSR file tells the BMC how to identify, manage, and monitor a NIC. Just like a driver is required when installing new hardware on a computer, this configuration file tells the BMC:

  • Regular information such as the name and model of the NIC
  • Out-of-band protocols supported by the NIC
  • How to monitor working status of the NIC
  • Issues to report
  • The sensor for NIC management

Information Contained in CSR ​

  • Device identification: the static information of the NIC, which helps the BMC to identify installed NICs
  • Status monitoring: the hardware topology information of the NIC for real-time monitoring, including temperature of the NIC, network port, and optical module
  • Fault reporting: sensor and event configuration of the NIC, specifying under which conditions the NIC's status triggers event reporting
  • Speed adjustment policy: the NIC's speed adjustment configuration, guiding the BMC's overall speed adjustment strategy

Step 1: Learning About the NIC to Be Configured ​

  • Check the NIC model (usually marked on the NIC).
  • Confirm the NIC type (PCIe, OCP, or onboard).
  • Record the NIC's basic information (such as the four-tuple information).
  • The thermal design document, which guides the speed adjustment policy
  • The sensors and event design

Step 2: Configuring Basic Information for the NIC ​

Configure basic information to ensure that the NIC can be loaded.

  • Configure the correct file name of the NIC using the BOM and four-tuple information.
  • Enter the NIC name and model.
  • Select the correct NIC type.
  • Enter the vendor ID and device ID.

PCIe Device Object (PCIeDevice_1) ​

Define the basic attributes and types of the PCIe device.

  • Device name
  • Function type
  • Device type
  • Slot type
json
{
    "PCIeDevice_1": {
        "DeviceName": "PCIe Card $ (device model)",
        "FunctionClass": 2,  // Function type
        "PCIeDeviceType": "MultiFunction",  // Device type
        "SlotType": "FullLength",  // Slot type
        "FunctionProtocol": "PCIe",  // Protocol type
        "FunctionType": "Physical"  // Function type
    }
}

NIC Object (PCIeCard_1) ​

Define the basic information and attributes of the NIC.

  • Name
  • Description
  • Vendor ID
  • Device ID
  • Manufacturer information
json
{
    "PCIeCard_1": {
        "Name": "Name",
        "Description": "Description",
        "VendorID": "VendorID",
        "DeviceID": "DeviceID",
        "Manufacturer": "Manufacturer",
        "PartNumber": "PartNumber",
        "Model": "Model",
        "FirmwareVersion": "FirmwareVersion",
        "SerialNumber": "SerialNumber"
    }
}

Network Adapter Object (NetworkAdapter_1) ​

Define the functions and features of the network adapter.

  • Name
  • Description
  • Number of ports
  • Supported features
json
{
    "NetworkAdapter_1": {
        "Name": "Name",
        "Description": "Description",
        "NetworkPortCount": "NetworkPortCount",
        "VendorID": "VendorID",
        "DeviceID": "DeviceID",
        "SupportedMctp": true,  //Whether MCTP is supported
        "SupportedLLDP": true,  // Whether LLDP is supported
        "HotPluggable": false,  // Whether hot swap is supported
        "LinkWidth": "LinkWidth",
        "LinkSpeed": "LinkSpeed"
    }
}

NIC Objects ​

Different objects are used for different types of NICs.

  1. Standard PCIe NIC (BoardPCIeCard_1)

    • Applicable to independent PCIe NICs

  2. OCP NIC (OCPCard_1)

    • Applicable to OCP NICs

  3. Onboard NIC (BoardNICCard_1)

    • Applicable to the NIC integrated on the mainboard

The standard PCIe NIC object (BoardPCIeCard_1) is applicable to the standard PCIe NIC.

  • Slot information
  • Link capability
  • Board type
  • FRU information
json
{
    "BoardPCIeCard_1": {
        "Slot": 1,
        "UID": "N/A",
        "Name": "Name",
        "Manufacturer": "Manufacturer",
        "Type": "PCIeCard",
        "Description": "Description",
        "PartNumber": "PartNumber",
        "BoardType": "BoardPCIeCard",
        "Number": 1,
        "DeviceName": "<=/PCIeDevice_1.DeviceName",
        "Position": "<=/PCIeDevice_1.Position",
        "LinkWidthCapability": "<=/NetworkAdapter_1.LinkWidthCapability",
        "LinkSpeedCapability": "<=/NetworkAdapter_1.LinkSpeedCapability",
        "LinkWidth": "<=/NetworkAdapter_1.LinkWidth",
        "LinkSpeed": "<=/NetworkAdapter_1.LinkSpeed",
        "BoardNodeId": "<=/PCIeDevice_1.DeviceName",
        "FruID": "<=/Fru_PCIeCard.FruId"
    }
}

The OCP NIC object (OCPCard_1) is used for the OCP NIC.

  • Specific OCP attributes
  • Link capability
  • Board type
  • FRU information
json
{
    "OCPCard_1": {
        "Slot": 1,
        "UID": "N/A",
        "Name": "Name",
        "Manufacturer": "Manufacturer",
        "Type": "OCPCard",
        "Description": "Description",
        "PartNumber": "PartNumber",
        "BoardType": "OCPCard",
        "Number": 1,
        "DeviceName": "<=/PCIeDevice_1.DeviceName",
        "Position": "<=/PCIeDevice_1.Position",
        "LinkWidthCapability": "<=/NetworkAdapter_1.LinkWidthCapability",
        "LinkSpeedCapability": "<=/NetworkAdapter_1.LinkSpeedCapability",
        "LinkWidth": "<=/NetworkAdapter_1.LinkWidth",
        "LinkSpeed": "<=/NetworkAdapter_1.LinkSpeed",
        "BoardNodeId": "<=/PCIeDevice_1.DeviceName",
        "FruID": "<=/Fru_PCIeCard.FruId"
    }
}

The onboard NIC object (BoardNICCard_1) is used for the onboard NIC.

  • Specific onboard attributes
  • Link capability
  • Board type
  • FRU information
json
{
    "BoardNICCard_1": {
        "Slot": 1,
        "UID": "N/A",
        "Name": "Name",
        "Manufacturer": "Manufacturer",
        "Type": "NICCard",
        "Description": "Description",
        "PartNumber": "PartNumber",
        "BoardType": "BoardNICCard",
        "Number": 1,
        "DeviceName": "<=/PCIeDevice_1.DeviceName",
        "Position": "<=/PCIeDevice_1.Position",
        "LinkWidthCapability": "<=/NetworkAdapter_1.LinkWidthCapability",
        "LinkSpeedCapability": "<=/NetworkAdapter_1.LinkSpeedCapability",
        "LinkWidth": "<=/NetworkAdapter_1.LinkWidth",
        "LinkSpeed": "<=/NetworkAdapter_1.LinkSpeed",
        "BoardNodeId": "<=/PCIeDevice_1.DeviceName",
        "FruID": "<=/Fru_PCIeCard.FruId"
    }
}

Step 3: Configuring Basic Network Port Information ​

Network Port Object (NetworkPort_X) ​

Define the network port attributes and capabilities.

  • Port ID
  • Medium type
  • Link capability
json
{
    "NetworkPort_0": {
        "@Parent": "NetworkAdapter_1",
        "SystemID": 1,
        "PortID": 0,
        "NetDevFuncType": "NetDevFuncType",
        "MediumType": "FiberOptic",  //Medium type
        "SupportedLinkCapability": "SupportedLinkCapability"
    }
}

Optical Module Object (OpticalModule_X) ​

Define the attributes and monitoring parameters of optical modules (for NICs that support optical modules).

  • Channel number
  • Temperature
  • Power supply status
  • Threshold
json
{
    "OpticalModule_0": {
        "@Parent": "NetworkPort_0",
        "ChannelNum": 1,
        "TemperatureCelsius": 0,
        "PowerState": 0,
        "IsSupportedType": 0,
        "Temp_UpperThresholdCritical": 125
    }
}

Step 4: Configuring Monitoring Parameters ​

For configuration, refer to Sensor Customization and Development. The following example focuses solely on the monitoring configuration of NIC sensors.

  • Set the temperature monitoring threshold for alarm reporting or speed adjustment.
  • Configure voltage and power monitoring for alarms or sensors.
  • Set status monitoring parameters.

Threshold Sensor Object (ThresholdSensor) ​

  • Applicable scenarios:
    • Temperature monitoring
    • Voltage monitoring
    • Power monitoring
  • Key attributes:
    • Threshold settings
    • Hysteresis value
    • Linearization parameters
json
{
    "ThresholdSensor_Temp": {
        "AssertMask": 128,
        "DeassertMask": 28800,
        "ReadingMask": 2056,
        "Linearization": 0,
        "M": 100,
        "RBExp": 224,
        "UpperNoncritical": 105,
        "PositiveHysteresis": 2,
        "NegativeHysteresis": 2
    },
    "ThresholdSensor_Voltage": {
        "AssertMask": 128,
        "DeassertMask": 28800,
        "ReadingMask": 2056,
        "Linearization": 0,
        "M": 100,
        "RBExp": 224,
        "LowerNoncritical": 3.0,
        "UpperNoncritical": 3.6,
        "PositiveHysteresis": 0.1,
        "NegativeHysteresis": 0.1
    },
    "ThresholdSensor_Power": {
        "AssertMask": 128,
        "DeassertMask": 28800,
        "ReadingMask": 2056,
        "Linearization": 0,
        "M": 100,
        "RBExp": 224,
        "UpperNoncritical": 25,
        "PositiveHysteresis": 1,
        "NegativeHysteresis": 1
    }
}

Discrete Sensor Object (DiscreteSensor) ​

Used to monitor the discrete status

  • Applicable scenarios:
    • Device installation status
    • Power supply status
    • Fault status
  • Key attributes:
    • Status mask
    • Type definition
json
{
    "DiscreteSensor_Presence": {
        "AssertMask": 1,
        "DeassertMask": 2,
        "ReadingMask": 3,
        "Type": 0
    },
    "DiscreteSensor_PowerState": {
        "AssertMask": 4,
        "DeassertMask": 8,
        "ReadingMask": 12,
        "Type": 0
    },
    "DiscreteSensor_FaultState": {
        "AssertMask": 16,
        "DeassertMask": 32,
        "ReadingMask": 48,
        "Type": 0
    }
}

Cooling Control Object (CoolingRequirement_X) ​

Define the cooling control parameters.

  • Target temperature
  • Maximum allowed temperature
json
{
    "CoolingRequirement_1_50": {
        "Description": "Description",
        "MonitoringStatus": "MonitoringStatus",
        "TargetTemperatureCelsius": 90,
        "MaxAllowedTemperatureCelsius": 102
    }
}

Step 5: Configuring the Management Feature ​

  • Configure fault alarm conditions.
  • Set the code of the LED indicator.
  • Define alarm levels.

For fine-grained alarm development, refer to Event Customization. The following example focuses solely on NIC alarms.

Basic Event Object ​

Define basic event monitoring.

json
{
    "Event_PCIeBandWidth": {
        "EventKeyId": "PCIeCard.PCIeCardBandWidthDecreased",
        "xxx": "xxxx"
    },
    "Event_PCIeLinkSpeed": {
        "EventKeyId": "PCIeCard.PCIeCardLinkSpeedReduced",
        "xxx": "xxxx"
    },
    "Event_PCIeCardUCE": {
        "EventKeyId": "PCIeCard.PCIeCardUncorrectableErr",
        "xxx": "xxxx"
    }
}

Temperature Events ​

json
{
    "Event_OverTemp": {
        "EventKeyId": "PCIeCard.PCIeCardOverTemp",
        "xxx": "xxxx"
    },
    "Event_TempFail": {
        "EventKeyId": "PcieCard.PCIeCardTempFail",
        "xxx": "xxxx"
    },
    "Event_TempSensorFail": {
        "EventKeyId": "PcieCard.PCIeCardTempSensorFail",
        "xxx": "xxxx"
    }
}

Power Supply Events ​

json
{
    "Event_PowerFail": {
        "EventKeyId": "PCIeCard.PCIeCardPowerFail",
        "xxx": "xxxx"
    },
    "Event_VoltageAlarm": {
        "EventKeyId": "PCIeCard.PCIeCardVoltageAlarm",
        "xxx": "xxxx"
    },
    "Event_PowerOverload": {
        "EventKeyId": "PCIeCard.PCIeCardPowerOverload",
        "xxx": "xxxx"
    }
}

Port Events ​

json
{
    "Event_Port1LinkDown": {
        "EventKeyId": "Port.PortDisconnected",
        "xxx": "xxxx"
    },
    "Event_OM1PowerAlarm": {
        "EventKeyId": "Port.PortOpticalModulePowerAlarm",
        "xxx": "xxxx"
    },
    "Event_OM1SpeedMatch": {
        "EventKeyId": "Port.PortOpticalModuleSpeedMismatch",
        "xxx": "xxxx"
    },
    "Event_Port1BWUsageMntr": {
        "EventKeyId": "NICCard.SystemNetworkBandwidthUsageHigh",
        "xxx": "xxxx"
    }
}

Device Status Events ​

json
{
    "Event_DevicePresence": {
        "EventKeyId": "PCIeCard.PCIeCardPresence",
        "xxx": "xxxx"
    },
    "Event_PowerState": {
        "EventKeyId": "PCIeCard.PCIeCardPowerState",
        "xxx": "xxxx"
    },
    "Event_FaultState": {
        "EventKeyId": "PCIeCard.PCIeCardFaultState",
        "xxx": "xxxx"
    }
}

FRU Object (Fru_PCIeCard) ​

  • FRU ID
  • Name
  • PCB ID
json
{
    "Fru_PCIeCard": {
        "PcbId": "PCB ID",
        "FruId": 1,
        "FruName": "FruName",
        "ConnectorGroupId": "ConnectorGroupId",
        "BoardId": 255
    }
}

Step 6: Configuring Out-of-Band Information Obtaining ​

The NetworkAdapter object has a Model attribute, which is used with the community component network_adapter to load and specify a protocol to obtain the out-of-band NIC information.

Chip Object (Chip_X) ​

Define chip access parameters.

  • Address
  • Timeout duration
json
{
    "Chip_Hi1822": {
        "OffsetWidth": 0,
        "AddrWidth": 1,
        "Address": 232,
        "WriteTmout": 100,
        "ReadTmout": 100
    }
}

Management Bus Object ​

Define the bus for a chip and ensures that the chip is accessible.

  • Bus type
  • Channel
json
{
    "ManagementTopology": {
        "Anchor": {
            "Buses": [
                "I2cMux_Chan"
            ]
        }
    }
}