【待评审】支持天池单板CPLD JTAG扫链巡检，新增Redfish接口、IPMI接口、资源协作接口

lisongwei · 2026 年7 月 11 日 01:42

背景

当前CPLD升级流程中，如果由于CSR配置/链路异常等原因导致JTAG链路不通，则会在升级过程中发生异常，返回升级失败。现在期望该异常情况能够在BMC正常运行时提前发现，巡检人员通过执行新增的Redfish接口或是IPMI接口，启动所有单板的CPLD扫链任务。general_hardware组件收到下发的命令后对所有单板执行扫链检测，判断扫链得到的CPLD数量是否与CSR中定义一致。巡检人员可以进一步执行另一个新增的Redfish/IPMI查询接口获取扫链结果，从而验证CSR配置的JTAG升级CPLD芯片与实际硬件扫链结果的一致性。

关联ISSUE

[需求]: 支持天池单板CPLD JTAG扫链巡检

整体方案

框架已提供CPLD的扫链功能，通过调用框架的接口，即可获取当前板卡上CPLD扫链的结果。为了获取所有单板的扫链结果，general_hardware需要在初始化时收集所有CPLD对象的信息，并按照这些对象所在的不同板卡分类维护。

为了对外提供对所有CPLD执行扫链检测的接口，需要在/bmc/kepler/Systems/1/Boards路径下提供一个新增的资源协作接口bmc.kepler.Systems.Board.Diagnose。该接口下提供两个方法：StartCpldJtagScan和GetCpldJtagScanResult。调用StartCpldJtagScan时，组件会启动线程，根据维护的所有CPLD对象信息，启动所有板卡的扫链任务。扫链任务完成后，调用GetCpldJtagScanResult即可获取扫链结果。

同时，作为巡检人员调用以上接口的入口，需要同理新增对应的Redfish接口。新增接口/redfish/v1/Managers/1/DiagnosticService/Actions/DiagnosticService.StartCpldJtagScan用于调用资源协作接口的StartCpldJtagScan方法，启动扫链任务。扫链任务启动后会通过task机制返回一个redfish路径，巡检人员可以通过访问该路径获取扫链结果的信息。

对于IPMI接口，同理需要新增两个接口，分别用于调用资源协作接口中的两个函数的实现内容，分别启动扫链任务和获取结果。

基于以上整体方案设计，需要新增以下接口：

新增资源协作接口bmc.kepler.Systems.Board.Diagnose，该接口下提供方法StartCpldJtagScan和GetCpldJtagScanResult，用于启动扫链任务以及获取扫链结果
Redfish接口DiagnosticService资源下新增Action DiagnosticService.StartCpldJtagScan，用于调用资源协作接口启动扫链任务
新增IPMI接口，用于启动扫链任务
新增IPMI接口，用于获取扫链结果

评审点1：新增资源协作接口bmc.kepler.Systems.Board.Diagnose

接口描述：该接口用于Redfish接口进行访问，从而触发CPLD扫链任务以及获取扫链任务的执行结果。

新增方法

方法名称	请求签名	请求参数描述	响应签名	响应参数描述	方法描述	访问权限
StartCpldJtagScan	a{ss}	Context：方法调用上下文	NA	NA	开始执行对所有CPLD的扫链任务	DiagnoseMgmt
GetCpldJtagScanResult	a{ss}	Context：方法调用上下文	ya{sys}	ScanResult：表示所有单板的扫链结果。取值范围：0（Succeed）、1（Failed）、2（Running）、3（Not started） ScanResultInfo：表示每一个单板的扫链结果，具体展示每个进行扫链的单板名称，扫链结果，失败原因	获取扫链任务执行结果	DiagnoseMgmt

以上方法在运行过程中，可能发生的正常与异常情况，以及对应的行为如下：

StartCpldJtagScan

启动扫链操作时，环境上不存在满足扫链条件的CPLD对象：
发生该情况时，方法会通过error引擎生成ActionNotSupported错误并返回。该错误信息来自于base.json中的已有定义。
启动扫链操作时，部分CPLD对象由于扫链接口调用失败而返回异常：
发生该情况时，本方法StartCpldJtagScan依然返回成功，具体的扫链失败信息后续调用GetCpldJtagScanResult接口时再返回。
成功启动所有CPLD对象的扫链任务：
返回成功。
启动扫链操作时，已经有一个正在运行的扫链任务：
发生该情况时，方法会返回成功，但是方法内部并不会重复启动新的扫链任务

GetCpldJtagScanResult

获取扫链结果时，尚未启动扫链任务：
发生该情况时，获取到ScanResult为"Not started"，ScanResultInfo为空数组。（方法本身不抛出错误）
获取扫链结果时，扫链任务还未全部完成：
发生该情况时，获取到ScanResult为"Running"，ScanResultInfo数组中包含当前各单板的扫链情况。（方法本身不抛出错误）
在所有单板的扫链任务都完成后，获取扫链结果时，部分CPLD对象由于扫链接口调用失败而返回异常：
发生该情况时，获取到ScanResult为"Failed"，ScanResultInfo数组中包含所有执行扫链任务的单板信息，其中发生异常的单板信息中，扫链结果为失败，失败原因记录为扫链接口调用失败。（方法本身不抛出错误）
在所有单板的扫链任务都完成后，获取扫链结果时，部分CPLD对象扫链结果与CSR配置不一致：
发生该情况时，获取到ScanResult为"Failed"，ScanResultInfo数组中包含所有执行扫链任务的单板信息，其中发生异常的单板信息中，扫链结果为失败，失败原因记录为CSR配置与实际不一致。（方法本身不抛出错误）
所有单板的扫链任务均成功，获取扫链结果：
获取到ScanResult为"Succeed"，ScanResultInfo数组中包含所有执行扫链任务的单板信息，扫链结果均为成功。

新增接口影响

路径	新增接口影响	CSR配置影响	持久化影响	其他影响
/bmc/kepler/Systems/:systemid/Boards	对外提供启动CPLD扫链任务以及获取扫链结果的功能	无需CSR配置，无影响	无影响	需要组件实现新增属性和方法

评审点2：DiagnosticService资源新增Action

资源URI：/redfish/v1/Managers/:managerid/DiagnosticService/Actions/DiagnosticService.StartCpldJtagScan
操作权限：DiagnoseMgmt
输入参数：无参数
响应参数：

{
    "@odata.context": "/redfish/v1/$metadata#Task.Task",
    "@odata.type": "#Task.v1_7_4.Task",
    "@odata.id": "/redfish/v1/TaskService/Tasks/1",
    "Id": "1",
    "Name": "Init",
    "Description": "Cpld Jtag Scan Task",
    "TaskState": "Running",
    "TaskStatus": "OK",
    "StartTime": "2000-01-14T07:26:26+00:00",
    "Messages": [],
    "PercentComplete": null,
    "Oem": {
        "Huawei": {
            "TaskPercentage": null
        }
    }
}

ActionInfo：

{
    "@odata.context": "/redfish/v1/$metadata#ActionInfo.ActionInfo",
    "@odata.id": "/redfish/v1/Managers/:managerid/DiagnosticService/Actions/DiagnosticService.StartCpldJtagScan",
    "@odata.type": "#ActionInfo.v1_0_1.ActionInfo",
    "Id": "StartCpldJtagScanActionInfo",
    "Name": "Start Cpld Jtag Scan Action Info",
    "Parameters": [],
    "Oem": {}
}

Schema定义：

"StartCpldJtagScan": {
    "patternProperties": {
        "^([a-zA-Z_][a-zA-Z0-9_]*)?@(odata|Redfish|Message|Privileges)\\.[a-zA-Z_][a-zA-Z0-9_.]+$": {
            "type": [
                "array",
                "boolean",
                "number",
                "null",
                "object",
                "string"
            ],
            "description": "This property shall specify a valid odata or Redfish property."
        }
    },
    "type": "object",
    "additionalProperties": false,
    "properties": {
        "title": {
            "type": "string",
            "description": "Friendly action name"
        },
        "target": {
            "type": "string",
            "format": "uri",
            "description": "Link to invoke action"
        },
        "@Redfish.ActionInfo": {
            "description": "The term can be applied to an action to action to specific a URI to an ActionInfo resource that described the parameters supported by this instance of the action.",
            "type": "string",
            "format": "uri-reference",
            "readonly": true
        }
    },
    "description": "This action starts the cpld scanning task by jtag linkage.",
    "longDescription": "This action shall start the cpld scanning task by jtag linkage."
}

用户可以通过访问回显的task路径，从而获取当前扫链任务的结果。访问task的回显举例如下：

{
    "@odata.context": "/redfish/v1/$metadata#Task.Task",
    "@odata.type": "#Task.v1_7_4.Task",
    "@odata.id": "/redfish/v1/TaskService/Tasks/1",
    "Id": "1",
    "Name": "Cpld Jtag Scan",
    "Description": "Cpld Jtag Scan Task",
    "TaskState": "Running",
    "TaskStatus": "OK",
    "StartTime": "2000-01-14T07:26:26+00:00",
    "Messages": {
        "@odata.type": "#Message.v1_0_0.Message",
        "RelatedProperties": [],
        "Message": "Cpld jtag scan task is running. BCU1CpuBoard1: running. EXU1ExpBoard1: succeed. SEU1DiskBP1: failed, error info: CSR config error.",
        "MessageArgs": [
            "BCU1CpuBoard1: running.",
            "EXU1ExpBoard1: succeed.",
            "SEU1DiskBP1: failed, error info: CSR config error."
        ],
        "Severity": "OK",
        "Resolution": "Wait until the scan task is complete.",
        "MessageSeverity": "OK"
    },
    "PercentComplete": 47,
    "Oem": {
        "Huawei": {
            "TaskPercentage": "47%"
        }
    }
}

属性名	类型	示例/取值约束	readonly	易变属性	实现PATCH	操作权限	描述
Message	string	Cpld jtag scan task is running.	true	否	否	ReadOnly	CPLD扫链的结果
MessageArgs	string array	SEU1DiskBP1: failed. Error info: CSR config error	true	否	否	ReadOnly	CPLD扫链结果的具体信息，展示每个扫链的单板名称，扫链结果，失败原因

评审点3：IPMI新增启动CPLD扫链任务命令

命令名称：StartCpldJtagScan
命令说明：启动CPLD扫链任务
命令权限：DiagnoseMgmt
是否有敏感数据：否
命令样式：

请求：ipmitool raw 0x30 0x93 0xdb 0x07 0x00 0x99
响应：db 07 00 00

命令请求参数：

字节顺序	域取值说明
NetFn	30h
Cmd	93h
1:3	Manufacturer ID，LB Byte first。长度固定 3 个字节，例如，某厂家ID是 2011，对应十六进制为0x0007DB，则字节序为第1个字节为 DBh，第二个字节为 07h，第三个字节为 00h。
4	SubCmd，固定为99h

命令响应参数：

字节顺序	域取值说明
1	Completion Code，可能的取值如下： 00h=【标准完成码】命令执行成功 D5h=【标准完成码】命令不能执行，当前状态不支持该命令或者请求参数
2:4	Manufacturer ID，LB Byte first。长度固定 3 个字节，例如，某厂家ID是 2011，对应十六进制为0x0007DB，则字节序为第1个字节为 DBh，第二个字节为 07h，第三个字节为 00h。
5	Result，扫链任务下发结果，取值如下： 00h=命令下发成功 01h=命令下发失败

评审点4：IPMI新增查询CPLD扫链结果命令

命令名称：GetCpldJtagScanResult
命令说明：获取CPLD扫链结果
命令权限：ReadOnly
是否有敏感数据：否
命令样式：

请求：ipmitool raw 0x30 0x93 0xdb 0x07 0x00 0x9a
响应：db 07 00 00 01 01 00 00