代码仓
中
network_adapter
更新时间: 2026/05/29
在AtomGit上查看源码

Network Adapter 网卡管理服务 ​

版本信息 ​

项目内容
组件版本1.100.33
首发版本openUBMC 1.0.0
文档作者openUBMC
最后更新2026-05-29

1. 组件概述 ​

1.1 组件简介 ​

Network Adapter(网卡管理服务)是 openUBMC 系统中的网卡组件管理模块,负责网卡、网口、光模块等网络设备的信息获取与管理,以及网口 NCSI 通道的配置与维护。支持通过 NCSI/PLDM over MCTP、SMBus 等带外协议获取网卡信息,同时支持通过 BMA(Board Management Agent)获取带内信息。

1.2 解决什么问题 ​

Network Adapter 组件为用户提供了完整的网卡管理能力,包括网卡/网口/光模块状态监控、链路信息采集、带宽占用率统计、NCSI 带外通信通道管理、VLAN/Bond 配置、网卡热插拔、固件升级、日志收集等功能。通过 Network Adapter 组件,用户可以在不依赖主机操作系统的情况下完成网络设备的全生命周期管理。

1.3 核心功能 ​

  • 网卡管理:支持网卡基本信息获取、健康状态监控、热插拔管理、带宽门限设置、固件升级
  • 网口管理:支持网口链路状态、MAC 地址、速率、统计信息、LLDP 信息获取与配置
  • 光模块管理:支持光模块温度、功率、偏置电流、电压等诊断信息采集与告警
  • 带外协议:支持 NCSI over MCTP、PLDM over MCTP、SMBus、LLDP 等多种协议
  • 带内数据:支持通过 BMA 获取主机侧网口、光模块、VLAN、Bond、Bridge 等信息
  • NCSI 功能:支持 NCSI 通道初始化、Tx 使能、VLAN Filter 配置,与 bmc_network 协同实现 BMC 带外通信
  • VLAN/Bond 管理:支持网口 VLAN 创建/修改/删除,Bond 网口创建/删除
  • IPMI 命令:支持 15 个 OEM IPMI 命令,覆盖 MAC 地址读写、NCSI 配置、网口信息查询等
  • 日志与诊断:支持网卡日志收集、光模块历史信息采集、SDI 卡黑匣子日志收集、PRBS 压测

1.4 关键术语表 ​

术语解释
NCSINetwork Controller Sideband Interface,网络控制器边带接口,BMC 通过网卡实现带外通信的协议
MCTPManagement Component Transport Protocol,管理组件传输协议,用于 BMC 与网卡芯片通信
BMABaseboard Management Agent,主机侧代理,将主机端信息通过带内通道推送给 BMC
LLDPLink Layer Discovery Protocol,链路层发现协议,用于获取交换机端口信息
SMBusSystem Management Bus,系统管理总线,用于 Hi182x 等网卡的带外管理
SDI 卡SmartNIC/DPU 智能网卡,具备独立计算能力的特殊网卡
OCP 卡Open Compute Project 推出的服务器网络接口卡
FC 卡Fibre Channel 光纤通道网卡
Lom 卡LAN on Motherboard,板载网卡
光模块Optical Module,光纤网口上可热插拔的光电转换模块

1.5 外部交互边界图 ​

说明

北向接口(Redfish/WEB/SNMP/CLI)由 rackmount 仓通过 D-Bus 资源协作接口调用 Network Adapter 组件
IPMI 接口由 ipmi_core 组件路由,Network Adapter 向 ipmi_core 注册处理函数
BMA 带内数据由 host_agent 组件直接推送给 Network Adapter 组件
NCSI 带外通信需要与 bmc_network 组件协同,由 Network Adapter 管理 NCSI 通道配置
带外通信通过 mctpd 仓管理 MCTP 通道,通过 hwproxy 仓管理 SMBus/I2C 通道

2. API 使用说明与示例 ​

2.1 网卡组管理 ​

bash
busctl --user introspect bmc.kepler.network_adapter /bmc/kepler/Systems/1/NetworkAdapters bmc.kepler.Systems.NetworkAdapters
NAME TYPE SIGNATURE RESULT/VALUE FLAGS

功能说明 ​

提供网卡组级别的管理功能,包括网卡/网口数量查询、端口速率查询、带宽占用率历史数据管理等。

属性内容
接口名bmc.kepler.Systems.NetworkAdapters
资源路径/bmc/kepler/Systems/:SystemId/NetworkAdapters
首发版本openUBMC 1.0.0
废弃状态正常可用

参数说明 ​

方法参数说明 ​
方法名入参出参描述
GetNetCardPortNumType(U8), SystemID(U8), SlotID(U8)NetcardExist(U8), PortNum(U8)获取指定槽位网卡的网口数量
GetPortSpeedType(U8), Slot(U8), PortID(U8)Status(U8), Speed(U32)获取指定网口速率
GetNetworkAdapterNum-NetworkAdapterNum(U8)获取网卡总数量
GetNetworkPortNum-NetworkPortNum(U8)获取网口总数量
GetBandwidthHistory-History(String)获取各网卡端口带宽占用率历史数据
ClearBandwidthHistoryBWUWaveTitle(String)-清空带宽占用率历史数据
SetBandwidthThresholdBandwidthThresholdPercent(U8)Result(S32)设置网络带宽占用率门限

返回值与异常 ​

返回值含义触发条件处理建议
0成功正常执行完成无
非 0失败参数非法或网卡不存在检查槽位号和网卡类型

应用场景 ​

  • 查询系统中网卡和网口数量
  • 监控网口带宽占用率
  • 设置带宽告警门限

调试示例 ​

bash
# 获取网卡数量
busctl --user call bmc.kepler.network_adapter /bmc/kepler/Systems/1/NetworkAdapters \
    bmc.kepler.Systems.NetworkAdapters GetNetworkAdapterNum a{ss} 0

# 设置带宽占用率门限为 80%
busctl --user call bmc.kepler.network_adapter /bmc/kepler/Systems/1/NetworkAdapters \
    bmc.kepler.Systems.NetworkAdapters SetBandwidthThreshold a{ss}y 0 80

2.2 网卡管理 ​

bash
busctl --user introspect bmc.kepler.network_adapter /bmc/kepler/Systems/1/NetworkAdapters/0 bmc.kepler.Systems.NetworkAdapter
NAME                    TYPE      SIGNATURE RESULT/VALUE FLAGS
.StartRemovingDevice    method    a{ss}s    -            -
.DumpBlackBox           method    a{ss}s    u            -
.Reset                  method    a{ss}s    -            -
.ID                     property  s         "0"          emits-change
.Name                   property  s         "SP580"        emits-change
.Model                  property  s         "Hi1822"       emits-change
.TemperatureCelsius     property  n         45             emits-change
...

功能说明 ​

管理单个网卡的属性和操作,包括基本信息获取、健康状态监控、热插拔管理、黑匣子日志收集等。

属性内容
接口名bmc.kepler.Systems.NetworkAdapter
资源路径/bmc/kepler/Systems/:SystemId/NetworkAdapters/:ID
首发版本openUBMC 1.0.0
废弃状态正常可用

参数说明 ​

方法参数说明 ​
方法名入参出参描述
StartRemovingDeviceID(String)-启动网卡热拔出流程
DumpBlackBoxPath(String)TaskId(U32)收集 SDI 卡黑匣子日志,当前仅 SDI 5.1 网卡支持
ResetResetType(String)-复位或上下电设备。GracefulRestart/ForceOff/ForceOn
属性参数说明 ​
参数名方向类型描述取值范围
ID输出string网卡 ID全局唯一
SystemID输出uint8系统 ID—
Name输出string网卡型号名称CSR 配置
DisplayName输出string网卡显示名称—
Manufacturer输出string厂商名称—
Description输出string网卡描述—
Position输出string网卡容器信息—
DeviceLocator输出string网卡丝印信息—
Type输出uint8网卡类型1=Lom, 3=PCIe, 5=Lom2, 6=虚拟, 7=Team, 8=Bridge, 9=Mezz, 10=OCP, 11=OCP2
NetworkPortCount输出uint8网口个数—
Model输出string芯片型号,决定支持的协议Hi1822/CX5 等
ChipVendor输出string芯片厂商—
ChipManufacturer输出string芯片厂商—
DriverName输出string驱动名称依赖 BMA
DriverVersion输出string驱动版本依赖 BMA
SlotNumber输出uint8槽位号—
RootBDF输出string网卡 BDF 信息—
FirmwareVersion输出string固件版本—
VendorID输出string厂商 IDPCIe 四元组
DeviceID输出string设备 IDPCIe 四元组
SubsystemVendorID输出string子系统厂商 ID—
SubsystemDeviceID输出string子系统设备 ID—
TemperatureCelsius输出int16芯片温度°C
TemperatureStatus输出uint8芯片温度状态0=正常,1=失效
HotPluggable输出bool是否支持热插拔—
ReadyToRemove输出bool热拔出是否已准备好—
AttentionHotPlugState输出uint8热插拔状态0=不可操作,1=可拔出,2=可插入
SerialNumber输出string序列号—
LLDPSupported输出bool是否支持 LLDP—
SupportedMctp输出bool是否支持 MCTP—
BandwidthThresholdPercent输出uint16网络带宽占用率门限百分比,默认100
NetDevFuncCapabilities输出uint8网卡支持的协议0:Disabled 1:Ethernet 2:FC 4:iSCSI 8:FCoE 16:OPA 32:IB
NetworkDeviceFunctionCount输出uint8网卡可用最大物理功能数量—
MaxOperatingTemperatureCelsius输出uint16稳态下支持的最大温度°C
NodeId输出string网卡 NodeId全局唯一

返回值与异常 ​

返回值含义触发条件处理建议
0成功正常执行完成无
非 0失败网卡不支持该操作或状态异常检查网卡类型和状态

应用场景 ​

  • 查询网卡基本信息(型号/固件/温度/BDF 等)
  • 网卡热插拔管理
  • SDI 卡黑匣子日志收集
  • 网卡健康状态监控

限制条件 ​

  • 热插拔操作需要网卡支持(HotPluggable=true)
  • DumpBlackBox 仅适用于 SDI 卡
  • 带外属性依赖网卡协议支持情况

调试示例 ​

bash
# 查询网卡信息
busctl --user introspect bmc.kepler.network_adapter \
    /bmc/kepler/Systems/1/NetworkAdapters/0 bmc.kepler.Systems.NetworkAdapter

# 查询网卡温度
busctl --user get-property bmc.kepler.network_adapter \
    /bmc/kepler/Systems/1/NetworkAdapters/0 \
    bmc.kepler.Systems.NetworkAdapter TemperatureCelsius

2.3 网卡状态子接口 ​

bmc.kepler.Systems.NetworkAdapter.NetworkAdapterMetrics ​

参数名方向类型描述取值范围
LinkWidthCapability输出string网卡支持的最大带宽能力—
LinkSpeedCapability输出string网卡支持的最大速率能力—
LinkWidth输出string网卡实际带宽—
LinkSpeed输出string网卡实际速率—
SFPMaxTemperatureCelsius输出int16光模块最大温度(用于调速)°C
PowerMilliWatts输出uint32网卡当前功率毫瓦,默认4294967295

bmc.kepler.Systems.NetworkAdapter.Status ​

参数名方向类型描述取值范围
Health输出uint8网卡健康状态0=OK, 1=Minor, 2=Major, 3=Critical
FaultCode输出string异常码—
FaultState输出uint32故障状态(用于告警配置)—
PowerStatus输出uint8Hi182x 网卡电源状态1=正常,0=异常,255=未知

bmc.kepler.Inventory.Hardware ​

参数名方向类型描述取值范围
AssetType输出string硬件资产类型—
AssetName输出string硬件资产名称—
SerialNumber输出string硬件资产序列号—
FirmwareVersion输出string硬件资产固件版本—
PCBVersion输出string硬件资产 PCB 版本—
Manufacturer输出string硬件资产制造商—
Model输出string硬件资产型号—

2.4 网口管理 ​

bash
busctl --user introspect bmc.kepler.network_adapter \
    /bmc/kepler/Systems/1/NetworkAdapters/0/Ports/0 bmc.kepler.Systems.NetworkPort
NAME                    TYPE      SIGNATURE RESULT/VALUE FLAGS
.Configure              method    a{ss}a{ss} u            -
.MACAddress             property  s         "00:11:22:33:44:55" emits-change
.LinkStatus             property  s         "Connected"    emits-change
.SpeedMbps              property  u         25000          emits-change
...

功能说明 ​

管理单个网口的属性和操作,包括链路状态、MAC 地址、速率、统计信息、LLDP 信息等。

属性内容
接口名bmc.kepler.Systems.NetworkPort
资源路径/bmc/kepler/Systems/:SystemId/NetworkAdapters/:ID/Ports/:ID
首发版本openUBMC 1.0.0
废弃状态正常可用

参数说明 ​

方法参数说明 ​
方法名入参出参描述
ConfigureRequest(Dictionary)TaskId(U32)配置网口,参数含连接状态、地址、掩码等
属性参数说明 ​
参数名方向类型描述取值范围
SystemID输出uint8系统 ID—
NodeId输出string网口 NodeId全局唯一
Name输出string网口名称—
PortID输出uint8网口 ID—
PermanentMACAddress输出string永久 MAC 地址—
MACAddress输出stringMAC 地址—
LinkStatus输出string链路状态LinkUp/NoLink/LinkDown/Connected/Disconnected
LinkStatusNumeric输出uint8链路状态数值—
SpeedMbps输出uint32链路速率Mbps
FullDuplex输出uint8全双工状态0=关闭,1=开启,255=未知
AutoSpeedNegotiation输出uint8自协商状态0=关闭,1=开启,255=未知
LinkMonitorPeriodMS输出uint32链路监测周期毫秒
MTUSize输出uint16最大传输单元默认1500
MediumType输出string网口介质类型Copper/FiberOptic
FunctionType输出string网口功能类型Virtual/Physical
Type输出uint8网口类型(网卡形态,与所属网卡 Type 取值一致)1=Lom, 3=PCIe, 5=Lom2, 6=虚拟, 7=Team, 8=Bridge, 9=Mezz, 10=OCP1, 11=OCP2
BDF输出string网口 BDF—
LLDPEnabled输入/输出boolLLDP 使能true/false
NetworkAdapterId输出string关联网卡 ID—
DriverName输出string驱动名称依赖 BMA
DriverVersion输出string驱动版本依赖 BMA
FirmwareVersion输出string固件版本—

返回值与异常 ​

返回值含义触发条件处理建议
0成功正常执行完成无
非 0失败网口不存在或操作不支持检查网口状态

应用场景 ​

  • 查询网口链路状态和速率
  • 获取网口 MAC 地址
  • 配置网口 LLDP 使能
  • 监控网口流量统计

调试示例 ​

bash
# 查询网口链路状态
busctl --user get-property bmc.kepler.network_adapter \
    /bmc/kepler/Systems/1/NetworkAdapters/0/Ports/0 \
    bmc.kepler.Systems.NetworkPort LinkStatus

2.5 网口统计与 LLDP 子接口 ​

bmc.kepler.Systems.NetworkPort.Metrics ​

参数名方向类型描述取值范围
RXFrames输出string收到的帧数量—
TXFrames输出string发送的帧数量—
PacketsDropped输出uint64丢包总数—
RXUnicastFrames输出string收到的单播帧数量—
TXUnicastFrames输出string发送的单播帧数量—
RXFCSErrors输出string接收校验错误帧数量—
BandwidthUsagePercent输出double网络带宽占用率%

bmc.kepler.Systems.NetworkPort.LLDPReceive ​

参数名方向类型描述取值范围
ChassisId输出string从交换机接收的 Chassis ID—
ChassisIdSubtype输出stringChassis ID 类型—
PortId输出string从交换机接收的端口 ID—
PortIdSubtype输出string端口 ID 类型—
SystemName输出string网络交换机名称—
ManagementVlanId输出uint16从交换机接收的 VLAN ID—

bmc.kepler.Systems.NetworkPort.FibreChannel ​

参数名方向类型描述取值范围
FCId输出stringFC ID 信息—
WWNN输出string当前生效 WWNN 号—
WWPN输出string当前生效 WWPN 号—
SpeedGbps输出uint32端口链接速率Gb

2.6 光模块管理 ​

bash
busctl --user introspect bmc.kepler.network_adapter \
    /bmc/kepler/Systems/1/NetworkAdapters/0/Ports/0/OpticalModule bmc.kepler.Systems.OpticalModule
NAME                    TYPE      SIGNATURE RESULT/VALUE FLAGS
.Manufacturer           property  s         "Vendor"       emits-change
.TemperatureCelsius     property  d         35.5           emits-change
.Presence               property  y         1              emits-change
...

功能说明 ​

管理网口下的光模块信息,包括基本信息、温度、功率、偏置电流、电压等诊断数据。信息通过带外协议(NCSI over MCTP、SMBus 等)与 BMA 带内上报(handler_optical / handler_optical_diag)共同获取,与网口数据获取方式一致。

属性内容
接口名bmc.kepler.Systems.OpticalModule
资源路径.../Ports/:ID/OpticalModule
首发版本openUBMC 1.0.0
废弃状态正常可用

参数说明 ​

属性参数说明 ​
参数名方向类型描述取值范围
Name输出string名称—
Manufacturer输出string厂商名称—
PartNumber输出string厂商部件名称—
SerialNumber输出string序列号—
TransceiverType输出string收发器类型—
MediumType输出string介质类型Optical/Electric/Copper
SupportedSpeedsMbps输出double[]支持的速率Mbps
Health输出uint8健康状态—
TemperatureCelsius输出double光模块温度°C
Presence输出uint8是否在位0/1
ChannelNum输出uint8内部通道数—
RxLossState输出bool接收端信号是否丢失—
TxLossState输出bool发送端信号是否丢失—
TxFaultState输出bool发送端是否故障—
FaultState输出uint32故障状态—
Accessible输出uint8是否可访问0=不可,1=可

应用场景 ​

  • 查询光模块基本信息和温度
  • 监控光模块功率和偏置电流
  • 光模块故障诊断和告警

2.7 光模块子接口 ​

bmc.kepler.Systems.OpticalModule.Temperature ​

参数名方向类型描述取值范围
ReadingCelsius输出double读取的芯片温度°C
LowerThresholdCritical输出double下限阈值°C
UpperThresholdCritical输出double上限阈值°C

bmc.kepler.Systems.OpticalModule.Power ​

参数名方向类型描述取值范围
RXInputPowerMilliWatts输出double[]接收功率毫瓦
TXOutputPowerMilliWatts输出double[]发送功率毫瓦
RXInputPowerStatus输出uint32接收功率异常状态(按通道位图)—
TXOutputPowerStatus输出uint32发送功率异常状态(按通道位图)—

bmc.kepler.Systems.OpticalModule.BiasCurrent ​

参数名方向类型描述取值范围
TXBiasCurrentMilliAmps输出double[]偏置电流毫安
TXBiasCurrentStatus输出uint32偏置电流异常状态(按通道位图)—

bmc.kepler.Systems.OpticalModule.Voltage ​

参数名方向类型描述取值范围
SupplyVoltage输出double供电电压V
LowerThresholdCritical输出double下限阈值V
UpperThresholdCritical输出double上限阈值V

bmc.kepler.Systems.OpticalModule.Diagnose ​

参数名方向类型描述取值范围
RxLossOfLock输出uint8接收方向 CDR 失败状态—
TxLossOfLock输出uint8发送方向 CDR 失败状态—
LaserRuntimeSeconds输出uint32激光器运行时间秒
SelfTestStatus输出uint64自体诊断告警状态—
PRBSTestSupported输出bool是否支持 PRBS 压测—
FiberDirtyDetected输出bool光模块是否脏污—
FiberLoosenessDetected输出bool光模块是否松动—

bmc.kepler.Systems.OpticalModule.Channel ​

参数名方向类型描述取值范围
Id输出uint8光模块 RX/TX 通道号—
BiasCurrentMilliAmps输出double通道偏置电流毫安
RXPowerMilliWatts输出double通道接收功率毫瓦
TXPowerMilliWatts输出double通道发送功率毫瓦

2.8 VLAN 管理 ​

bash
busctl --user introspect bmc.kepler.network_adapter \
    /bmc/kepler/Systems/1/NetworkAdapters/0/Ports/0/VLANs bmc.kepler.Systems.NetworkPort.VLANs
NAME         TYPE      SIGNATURE RESULT/VALUE FLAGS
.CreateVLAN  method    a{ss}a{ss} u            -

功能说明 ​

管理网口下的 VLAN 配置,支持创建、修改和删除 VLAN。

属性内容
接口名bmc.kepler.Systems.NetworkPort.VLANs
首发版本openUBMC 1.0.0
废弃状态正常可用

参数说明 ​

方法参数说明 ​
方法名入参出参描述
CreateVLANRequest(Dictionary)TaskId(U32)创建网口 VLAN
VLAN 属性参数说明(bmc.kepler.Systems.NetworkPort.VLAN) ​
参数名方向类型描述取值范围
VLANId输出uint16VLAN ID—
VLANEnabled输出boolVLAN 是否启用true/false
VLANPriority输出uint8VLAN 优先级0~7
AutoConnectOnBoot输出bool系统启动时自动创建和启用true/false
AutoConnectOnBootValidity输出boolAutoConnectOnBoot 是否为有效值true/false
方法参数说明(VLAN 对象) ​
方法名入参出参描述
ConfigureVLANRequest(Dictionary)TaskId(U32)修改 VLAN 配置
DeleteVLAN-TaskId(U32)删除 VLAN

2.9 Bond 管理 ​

功能说明 ​

管理 Bond 网口的创建和删除,以及链路监测周期设置。

属性内容
接口名bmc.kepler.Systems.NetworkBondings
资源路径/bmc/kepler/Systems/:SystemId/NetworkAdapters(方法接口);Bond 对象路径为 /bmc/kepler/Systems/:SystemId/NetworkBondings/:ID
首发版本openUBMC 1.0.0
废弃状态正常可用

参数说明 ​

方法参数说明 ​
方法名入参出参描述
CreateBondRequest(Dictionary)TaskId(U32)创建 Bond,参数含 port、BondingType 等
DeleteBondId(String)TaskId(U32)删除指定 Bond
SetLinkMonitorPeriodMSId(String), LinkMonitorPeriodMS(U32)TaskId(U32)设置 Bond 链路监控周期(毫秒)
Bond 属性参数说明(bmc.kepler.Systems.NetworkBonding) ​
参数名方向类型描述取值范围
Id输出stringBonding ID由 BMA 生成
Name输出stringBonding 名称—

2.10 NCSI 调试 ​

bash
busctl --user introspect bmc.kepler.network_adapter \
    /bmc/kepler/Debug/Systems/1/NCSI bmc.kepler.Debug.Systems.NCSI
NAME              TYPE      SIGNATURE RESULT/VALUE FLAGS
.SendCmdOverMCTP  method    a{ss}sys  s            -

功能说明 ​

提供 NCSI over MCTP 调试命令接口,用于开发和问题定位。

属性内容
接口名bmc.kepler.Debug.Systems.NCSI
首发版本openUBMC 1.0.0
废弃状态正常可用

参数说明 ​

方法参数说明 ​
方法名入参出参描述
SendCmdOverMCTPNodeId(String), Command(U8), Payload(String)Data(String)调试 NCSI over MCTP 命令

2.11 调试接口 ​

bmc.kepler.Debug.Systems.NetworkAdapters ​

方法名入参出参描述
Dump--将网卡信息转储到日志文件

3. IPMI 命令 ​

数据来源:network_adapter/mds/ipmi.json(命令定义)+ network_adapter/src/lualib/network_adapter_app.lua(处理函数)

3.1 概述 ​

Network Adapter 组件注册了 15 个 OEM IPMI 命令,网卡 MAC 地址相关命令使用 NetFn=0x30, CMD=0x90;NCSI 和网口信息查询命令使用 NetFn=0x30, CMD=0x93;DPU 相关命令使用 NetFn=0x3E。

3.2 查询类命令 ​

IPMI 命令NetFn/CMDSubCommand处理函数说明
GetMacAddress0x30/0x900x01get_mac_address_from_ipmi获取网口 MAC 地址
GetNcsiSlot0x30/0x930x5B—获取 NCSI 槽位号
GetBusinessPortInfo0x30/0x930x5Eget_business_port_info_from_ipmi查询网口信息
GetIPMCConfiguration0x30/0x930x06/0x19—获取 NCSI channel 的 Rx 配置
GetNetworkAdapterModelByLOM0x30/0x930x40/0x4A—通过 BDF 查询板载网卡芯片型号
GetNetworkAdapterModelByOCPCard0x30/0x930x40/0x53—通过 BDF 查询 OCP 扣卡芯片型号
GetDpuOSStartupStatus0x30/0x930x27—获取 DPU OS 启动状态
GetDpuHostAccess0x3E/0x670x02—获取 DPU 主机访问权限
GetDpuExtendedHostPrivilege0x3E/0x680x02—获取 DPU 扩展主机权限
GetDpuMode0x3E/0x690x02—获取 DPU 模式

3.3 设置类命令 ​

IPMI 命令NetFn/CMDSubCommand处理函数说明
WriteMacAddress0x30/0x900x00—设置网口 MAC 地址(通常由 BIOS 调用)
SetIPMCConfiguration0x30/0x930x05/0x19—设置 NCSI channel 的 Rx
SetDpuHostAccess0x3E/0x670x01—设置 DPU 主机访问权限
SetDpuExtendedHostPrivilege0x3E/0x680x01—设置 DPU 扩展主机权限
SetDpuMode0x3E/0x690x01—设置 DPU 模式

4. 关键特性 ​

4.1 带外协议获取网卡信息 ​

网卡带外管理支持多种协议,芯片型号(Model)决定了该网卡支持哪些协议:

NCSI over MCTP over PCIe

绝大多数网卡支持该协议,可获取:网卡厂商信息、芯片温度、带宽/速率能力、故障状态、网口报文统计、链路状态、MAC 地址、光模块信息等。

PLDM over MCTP over PCIe

主要用于 SDI5x/SDI6x 黑匣子日志收集,未来计划 FC 卡通过该协议获取带外信息。

SMBus

仅 Hi182x 系列网卡支持,可获取:网卡健康状态、故障状态、芯片温度、错误日志、临终遗言日志、运行日志、光模块温度、网口链路状态、MAC 地址等。

LLDP

接收 LLDP 信息,获取交换机 Chassis ID、端口 ID、交换机名称、VLAN ID 等。

4.2 带内 BMA 获取网卡信息 ​

网口信息通过以下路径传递:带内 → SMS 接口 → host_agent → network_adapter。Network Adapter 监听 host_agent 网口相关资源协作接口对象的上树、修改、下树信号,汇总管理网口连接状态、速率、IPv4/IPv6、MAC 地址、BDF、固件版本、Bond/Bridge 网口、光模块信息等。

4.3 网卡 NCSI 功能 ​

部分网卡(PCIe 卡、OCP 卡)具备 NCSI 功能,BMC 可通过 NCSI 通道与网卡相连实现带外通信。主要交互流程:

  1. 初始化时识别网卡 NCSI 能力,识别到 NCSI 网口后上报给 bmc_network 注册 NCSI 网口,并实时更新 link 状态
  2. bmc_network 切换到 NCSI 网口时通知 network_adapter,使能对应 NCSI 通道的 Tx;切换回专用网口时关闭原 NCSI 通道 Tx
  3. bmc_network 设置 NCSI VLAN 后通知 network_adapter,配置 NCSI 通道的 vlan_filter

4.4 已适配网卡类型 ​

类型说明
NIC 卡板载网卡(LOM 卡)、灵活 IO 插卡
PCIe 标卡PCIe 网卡,需要 Riser 卡
SDI 卡智能网卡/DPU
OCP 卡Open Compute Project 服务器网络接口卡
FC 卡光纤通道网卡

4.5 网卡固件升级 ​

数据来源:network_adapter/src/lualib/upgrade/ + firmware_mgmt(UpdateService)升级调度

Network Adapter 负责固件类型为 Nic 的网卡升级与生效,由 firmware_mgmt(UpdateService)统一发起升级流程,本组件订阅其 D-Bus 信号并执行具体刷写逻辑。

4.5.1 功能概述 ​

  • 固件类型标识:firmware_type = Nic(与固件管理模块约定一致)
  • 升级对象:资源树中已登记的网卡固件(NetworkAdapterFirmware / FirmwareInventory),按 ComponentID、ComponentIDEx 及可选 Targets 匹配
  • 升级协议:支持 SFC 协议网卡通过 upgrade_flash 写 Flash;初始化时为 SFC 网卡设置默认固件路由
  • 协同组件:
    • UpdateService:下发 Prepare / Process / Finish 三阶段升级信号
    • FirmwareActive:下电后执行缓存升级包的生效(Active)流程
    • fructrl:下电升级时加/解「上电锁」,防止升级过程中 Host 意外上电

4.5.2 升级流程 ​

阶段处理入口主要动作
Prepareon_upgrade_prepare校验是否在升级中、是否存在网卡固件对象;chown 配置与 HPM 文件;解析 update.cfg;记录升级前版本;下电时通过 fructl 加上电锁
Processon_upgrade_process按 Targets 或全量匹配升级列表;上电时仅缓存 HPM,不写 Flash;下电时调用 upgrade_flash 刷写
Finishon_upgrade_finish若存在缓存 HPM,向 FirmwareActive 注册生效任务(ActiveCondition=PowerOff);清理升级状态
Activeon_active_process下电生效:读取缓存 /data/backup/nic/up_cfg/nic.hpm,解压并刷写,完成后清理缓存

4.5.3 固件对象登记 ​

网卡固件对象由 firmware_objs_mgmt 管理,在 CSR 配置的 NetworkAdapterFirmware 对象上树时登记到可升级列表,下树时移除,并同步注册到 /bmc/kepler/UpdateService/FirmwareInventory 供北向查询。

升级目标 URI 前缀为:

/redfish/v1/Chassis/1/NetworkAdapters/{firmware_id}

可通过升级参数 Targets 指定逗号分隔的 URI 列表,仅升级指定网卡;未指定时按配置文件中 component_id / component_idex 匹配全部符合的网卡固件。

4.5.4 路径与配置 ​

路径/文件说明
update.cfg升级包内配置文件,定义 component_id、component_idex 等,由 parser_cfg 解析
HPM 升级包Process 阶段传入的固件包路径,Prepare 阶段记录 hpm_path
/data/backup/nic/up_cfg/nic.hpm上电升级时缓存的网卡 HPM,供下电后 Active 刷写
/lib/modules/hibmc/sfc0_drv.koSFC 协议相关驱动路径(upgrade_defs)

4.5.5 返回值说明 ​

返回值含义常见原因
0成功阶段正常完成
-1通用失败配置解析失败、Flash 刷写失败、无固件对象等
36IN_UPGRADING已有网卡升级任务进行中
248OTHERS_UPGRADING其他固件正在升级(固件管理侧)

4.5.6 限制与注意事项 ​

  • 仅处理 firmware_type == Nic 的升级/生效请求,其他类型由对应组件处理
  • 上电场景下 Process 不直接写 Flash,需等待 Host 下电后通过 Active 流程生效
  • 下电升级依赖上电锁,Finish 或异常路径会解除锁并清理 cfgs、upgrade_list 等状态
  • Prepare 阶段要求 FirmwareInventory 中已存在可升级的网卡固件对象,否则返回失败
  • SFC 网卡启动时会执行 initial_set_route() 恢复默认固件路由

4.5.7 相关代码目录 ​

文件说明
upgrade/network_adapter_upgrade.lua订阅升级信号、阶段调度与状态管理
upgrade/upgrade_process.luaPrepare/Process/Finish 业务逻辑
upgrade/active_process.lua下电生效(Active)刷写
upgrade/upgrade_flash.luaFlash 刷写与路由切换
upgrade/firmware_objs_mgmt.lua网卡固件对象登记与 FirmwareInventory 同步
upgrade/parser_cfg.lua升级配置与包路径解析
upgrade/upgrade_defs.lua常量与返回值定义

4.6 对象模型 ​

NetworkAdapter 拥有 N 个 NetworkPort,每个 NetworkPort 拥有 0/1 个 OpticalModule,通过 @Parent 属性关联。主要类:

  1. NetworkAdapter:网卡设备信息
  2. NetworkPort:网口设备信息
  3. OpticalModule:光模块设备信息

5. 目录结构 ​

shell
├── src
│   ├── lualib
│   │   ├── bma                                    # BMA 带内数据处理
│   │   │   ├── handles                          # BMA 上报信息处理
│   │   │   └── bma_mdb_mgmt.lua                 # BMA 资源管理
│   │   ├── debug                                # NCSI over MCTP 调试命令
│   │   ├── device
│   │   │   ├── class
│   │   │   │   ├── network_adapter.lua          # 网卡相关业务代码
│   │   │   │   ├── network_port.lua             # 网口相关业务代码
│   │   │   │   ├── optical_module.lua           # 光模块相关业务代码
│   │   │   │   ├── log_collector.lua            # 日志收集
│   │   │   │   ├── vlan/                        # VLAN 对象管理
│   │   │   │   └── nic_mgmt/                    # 网卡/网口/光模块管理
│   │   │   └── device_manager.lua               # 设备管理(method、IPMI 实现)
│   │   ├── hardware_config                        # 各型号网卡协议配置
│   │   │   ├── CX4.lua                          # CX4 型号(SP333/SP380)
│   │   │   ├── CX5.lua                          # CX5 型号(SP351/SP382)
│   │   │   ├── CX6-DX.lua                         # CX6-DX 型号
│   │   │   ├── Hi182X.lua                         # Hi182x 系列(SP580)
│   │   │   └── Gemini.lua                         # SDI 卡协议
│   │   ├── ncsi                                   # NCSI 协议实现
│   │   │   ├── ncsi_core.lua                      # NCSI 协议接口
│   │   │   ├── ncsi_service.lua                   # NCSI 初始化
│   │   │   └── ncsi_worker.lua                    # NCSI 报文接收
│   │   ├── upgrade                                # 网卡固件升级(Nic)
│   │   │   ├── network_adapter_upgrade.lua        # 升级信号订阅与阶段入口
│   │   │   ├── upgrade_process.lua                # Prepare/Process/Finish
│   │   │   ├── active_process.lua                 # 下电生效 Active
│   │   │   ├── upgrade_flash.lua                  # Flash 刷写
│   │   │   ├── firmware_objs_mgmt.lua             # 固件对象登记
│   │   │   └── parser_cfg.lua                     # 升级包配置解析
│   │   ├── metric                                 # 带宽数据采集
│   │   ├── dfx_collect                            # 光模块 DFX 信息采集
│   │   ├── prbs_test                              # PRBS 压测
│   │   ├── network_adapter_app.lua                # 组件入口
│   │   └── ...
│   ├── lualib-src
│   │   └── ncsi_protocol                          # NCSI C 库实现
│   └── service
│       └── main.lua                               # 服务入口
├── mds/
│   ├── model.json                                 # 资源协作接口模型定义
│   ├── ipmi.json                                  # IPMI 命令定义(15 个命令)
│   └── service.json                               # 组件服务配置

6. 组件扩展案例 ​

6.1 新增 IPMI 命令 ​

步骤一:在 mds/ipmi.json 中定义命令

json
{
    "NewCommand": {
        "netfn": "0x30",
        "cmd": "0x93",
        "priority": "Default",
        "role": "Operator",
        "privilege": ["ReadOnly"],
        "req": [
            {"data": "ManuId", "baseType": "U32", "len": "3B", "customizedRule": "Manufacturer"},
            {"data": "SubCmd", "baseType": "U8", "len": "1B", "value": "0xXX"}
        ],
        "rsp": [
            {"data": "CompletionCode", "baseType": "U8", "len": "1B"},
            {"data": "Data", "baseType": "String", "len": "*"}
        ]
    }
}

步骤二:在 device_manager.lua 中实现处理函数

lua
function c_device_manager:new_command_from_ipmi(req, ctx)
    local resp_data = {}
    -- 解析请求数据
    -- 执行业务逻辑
    -- 构造响应数据
    return resp_data
end

步骤三:在 network_adapter_app.lua 中注册命令

lua
self:register_ipmi_cmd(ipmi_struct.NewCommand, function(...)
    return self.device_manager:new_command_from_ipmi(...)
end)

6.2 新增网卡型号协议支持 ​

步骤一:在 hardware_config/ 目录下创建新型号配置文件

lua
-- hardware_config/NewModel.lua
local M = {}

function M.get_card_info()
    -- 实现带外信息获取逻辑
end

return M

步骤二:在网卡初始化流程中根据 Model 字段加载对应协议配置

网卡对象的 Model 属性决定使用哪种带外协议,在 nic_mgmt/card/card_init.lua 中根据 Model 匹配 hardware_config 下的配置文件。

6.3 新增配置导入导出属性 ​

步骤一:注册导入导出处理器

lua
local config_mgmt_engine = require 'config_mgmt.engine'
config_mgmt_engine.register_config_dealer('ClassName', self)

步骤二:实现 import/export 方法

lua
function c_my_object:import(ctx, obj_json)
    self.PropertyName = obj_json.PropertyName
end

function c_my_object:export(ctx)
    return { PropertyName = self.PropertyName }
end

7. 日志说明 ​

7.1 日志路径 ​

日志路径说明
/data/var/log/bmc/network_adapter.logNetwork Adapter 组件主日志
/data/var/log/bmc/pciecard/PCIe 网卡日志收集目录
/data/var/log/bmc/optical_module/光模块日志收集目录
/data/var/log/bmc/optical_module/optical_module_history_info_log.csv光模块历史信息采集文件

7.2 日志级别与关键字 ​

级别说明关键字示例
notice正常业务流程c_network_adapter start、c_network_port init start、add event successfully
info补充信息collect_netcard_info
warn警告—
error异常/错误get mac address fail、get events object failed、NCSI 相关错误
debug调试信息NCSI 报文调试信息

7.3 关键日志说明 ​

日志内容含义定位建议
c_network_adapter init start, NodeId(%s)网卡对象初始化开始网卡不可见时检查是否有此日志
c_network_port init start网口对象初始化开始网口信息异常时关注
c_optical_module init start光模块对象初始化开始光模块信息异常时关注
card orm obj init start, NodeId is %s网卡 ORM 对象初始化网卡识别异常时检查 CSR 配置
[Hi182x] optical module: %s init startHi182x 光模块初始化Hi182x 光模块问题定位
get mac address fail, cause data is invalidIPMI 获取 MAC 地址失败检查 FruId 和 MacId 参数
[network_adapter] reboot preparation completed组件重启准备完成重启相关问题定位
[Network Adapter Upgrade] 系列日志网卡固件升级流程升级失败时按阶段排查

8. 问题定界指南 ​

8.1 总体定界思路 ​

8.2 网卡识别问题 ​

现象:网卡不可见或信息为空

排查步骤:

  1. 检查 CSR 配置:确认 .sr 文件中 NetworkAdapter 对象的 Model、SlotNumber、Type 等配置正确
  2. 检查 PCIe 设备:确认网卡的 PCIe 设备被正确识别
  3. 检查初始化日志:查看是否有 card orm obj init start 和 c_network_adapter init start 日志
  4. 检查 MCTP 通信:对于 MCTP 网卡,确认 mctpd 组件正常运行
    bash
    busctl --user get-property bmc.kepler.network_adapter \
        /bmc/kepler/Systems/1/NetworkAdapters/0 \
        bmc.kepler.Systems.NetworkAdapter SupportedMctp

8.3 网口信息异常 ​

现象:网口链路状态不更新、MAC 地址为空、速率显示异常

排查步骤:

  1. 检查链路状态:LinkStatus 应为 Connected/LinkUp
  2. 检查带外协议:确认网卡 Model 对应的 hardware_config 协议配置正确
  3. 检查 BMA 数据:带内属性(IPv4/IPv6/DriverName 等)依赖 host_agent 数据推送
  4. 检查 NCSI 通信:查看 NCSI 相关错误日志

8.4 NCSI 通信异常 ​

现象:BMC 无法通过 NCSI 网口进行通信

排查步骤:

  1. 检查 NCSI 网口注册:确认 network_adapter 已向 bmc_network 注册 NCSI 网口
  2. 检查 NCSI 通道 Tx 状态:切换到 NCSI 网口时 Tx 应被使能
  3. 检查 VLAN Filter:配置了 VLAN 后确认 vlan_filter 已正确设置

8.5 光模块信息异常 ​

现象:光模块温度/功率信息不显示或显示异常

光模块信息与网卡/网口类似,数据来源分为带外与**带内(BMA)**两类:

来源典型内容实现路径
带外协议温度、功率、偏置电流、电压、在位/可访问性、通道级诊断等NCSI over MCTP、SMBus(如 Hi182x)等,经 hardware_config 与网卡协议栈采集
BMA 带内基本信息、诊断信息、部分告警相关属性等带内 → SMS → host_agent → network_adapter,handler_optical.lua / handler_optical_diag.lua 处理上报

排查步骤:

  1. 检查在位状态:Presence=1 表示在位(带外/BMA 均可更新,以实际生效源为准)
  2. 检查可访问性:Accessible=1 表示带外可访问;为 0 时带外温度/功率等可能无效
  3. 检查网口介质类型:MediumType=FiberOptic 的网口才关联光模块
  4. 检查带外协议:确认网卡 Model 支持光模块带外读取,查看 MCTP/SMBus 通信及 [Hi182x] optical module 相关日志
  5. 检查 BMA 数据:确认 host_agent 正常,光模块 BMA 资源上树/更新是否正常(handler_optical / handler_optical_diag)
  6. 检查初始化日志:查看 c_optical_module init start 日志

8.6 数据不更新 ​

现象:网卡/网口/光模块信息长时间不刷新

排查步骤:

  1. 检查周期采集任务:确认带外数据采集周期任务正常运行
  2. 检查 MCTP/SMBus 通信:查看日志中是否有通信失败
  3. BMA 数据不更新:确认 host_agent 组件正常运行
  4. 检查网卡电源状态:确认网卡供电正常

9. 常见问题解答 ​

Q1:NCSI 网口切换后 BMC 无法通信,如何排查? ​

答:排查步骤:

  1. 确认 network_adapter 已识别网卡 NCSI 能力并注册 NCSI 网口
  2. 确认 bmc_network 切换网口时 network_adapter 收到信号并使能了 NCSI 通道 Tx
  3. 若配置了 VLAN,确认 vlan_filter 已正确设置

Q2:光模块信息显示为空,如何排查? ​

答:光模块属性可能来自带外或 BMA,需分别排查。常见原因:

  1. 网口未插入光模块(Presence=0)
  2. 光模块带外不可访问(Accessible=0),温度/功率等带外属性无效
  3. 带外协议通信异常,检查 MCTP/SMBus 及网卡 hardware_config 是否支持光模块采集
  4. BMA 未上报或 host_agent 异常,检查 handler_optical / handler_optical_diag 相关日志

Q3:某个属性值不符合预期,如何排查? ​

答:网卡、网口、光模块的属性可能来自带内(BMA)或带外协议,排查时应先确认数据来源,再分别验证对应链路。

步骤一:分析属性来源

来源典型属性示例
带内(BMA)IPv4/IPv6、驱动名称/版本、Bond/Bridge、部分光模块基本信息与诊断信息、OS 侧链路状态等
带外MAC 地址、链路状态、芯片/光模块温度、功率、偏置电流、带宽/速率能力、LLDP 等

可参考 mdb_interface 接口定义及组件 README.md 中各属性的获取方式;同一属性若带内、带外均有上报,需以代码实现中的更新优先级为准(例如部分网口属性 BMA 优先级更高)。

步骤二:带内属性不符合预期

  1. 确认 host_agent 组件运行正常,SMS 通道畅通
  2. 检查 host_agent 推送给 network_adapter 的 BMA 资源是否上树、是否有更新(上树/修改/下树)
  3. 查看 bma/handles/ 下对应 handler 日志(如 handler_eth.lua、handler_optical.lua)
  4. 在主机侧确认驱动、网口、光模块等带内信息本身是否正确

步骤三:带外属性不符合预期

  1. 确认网卡 Model 与 hardware_config/ 协议配置匹配,且支持该属性的带外采集
  2. 检查 mctpd(MCTP)或 hwproxy(SMBus/I2C)通信是否正常,日志中是否有读写失败
  3. 查看网卡/网口/光模块初始化及周期采集日志(如 c_network_adapter init start、NCSI/SMBus 相关错误)

步骤四:仍无法定位

对比 D-Bus 当前属性值与带内/带外原始数据,确认是采集未更新、解析错误,还是北向展示映射问题。

Q4:如何适配新型号网卡? ​

答:适配步骤:

  1. 在 hardware_config/ 目录下创建新型号协议配置文件
  2. 在 CSR 中配置 NetworkAdapter 对象,设置正确的 Model、VendorID、DeviceID 等
  3. 确认带外通信通道(MCTP Endpoint 或 SMBus Chip)配置正确
  4. 验证带外信息获取和 NCSI 功能(如适用)