背景
当发生硬盘故障时，支持运维人员、网管通过redfish和ipmi接口通过CPLD对指定物理盘槽位进行上下电控制，而当前redfish和ipmi接口没对应的属性或命令字，因此需要新增redfish属性和ipmi命令字，用于查询和设置指定物理盘槽位的上下电状态。同时，需要新增资源协作接口属性用于表示物理盘槽位的上下电状态，以及新增资源协作接口方法，用于设置指定物理盘槽位的上下电状态
关联ISSUE
[需求]: 支持双主机场景对指定物理盘上下电-storage-AtomGit | GitCode
整体方案
（1）根据硬盘背板CPLD给出的SMC命令字在CSR配置用于读写物理盘槽位电源状态的Accessor；
（2）资源协作接口新增表示硬盘上下电状态的属性以及设置物理盘槽位电源状态的方法；
（3）redfish接口新增属性用于表示物理盘槽位电源状态，新增Action用于设置物理盘槽位的电源状态；
（4）ipmi接口新增命令字用于查询和设置指定物理盘槽位的电源状态；
评审点
评审点1： 资源协作接口bmc.kepler.Systems.Storage.Drive新增属性和方法
评审点2： redfish Drive资源新增属性SlotPowerState，用于表示物理盘槽位的电源状态
评审点3： redfish Drive资源新增Action，用于设置物理盘槽位的电源状态
评审点4： 新增ipmi接口命令字，用于查询指定物理盘槽位的电源状态
评审点5： 新增ipmi接口命令字，用于设置指定物理盘槽位的电源状态
详细描述
评审点1：资源协作接口bmc.kepler.Systems.Storage.Drive新增属性和方法
变更描述 ：资源协作接口bmc.kepler.Systems.Storage.Drive下新增属性SlotPowerState
接口链接 ：AtomGit | GitCode - 全球开发者的开源社区,开源代码托管平台
属性评审点
| 变更类型 | 属性名称 | 签名 | 只读 | 变化通知 | 属性描述 | 访问权限 | 属性来源 | 持久化类型 | 变更影响 | ||
|---|---|---|---|---|---|---|---|---|---|---|---|
| 新增 | SlotPowerState | y | true | true | 表示物理盘槽位的电源状态，0：下电，1：上电，默认值255 | Read: ReadOnly | 根据CPLD提供的smc命令字从寄存器读取，资源协作接口、北向接口设置 | 不持久化 | 新增属性，无影响 |
方法评审点
| 变更类型 | 方法名称 | 请求签名 | 请求参数描述 | 响应签名 | 响应参数描述 | 方法描述 | 访问权限 | 变更影响 | ||
|---|---|---|---|---|---|---|---|---|---|---|
| 新增 | SetSlotPowerState | s | SlotPowerState：要对物理盘槽位执行的上下电操作，“ForceOff”：强制下电，“ForceOn”：强制上电 | – | – | 设置物理盘槽位的电源状态 | PowerMgmt | 新增方法，无影响 |
新增方法而不是直接写属性SlotPowerState，是为了便于对物理盘槽位是否支持上下电操作的条件进行判断，如是否支持写入Accessor对象、参数合法性等。
该方法可能返回的错误原因如下：
- 向对应的Accessor对象写入值进行复位或上下电操作时，写入操作返回了失败
- 入参取值或类型错误
发生以上错误时，方法返回错误信息如下。以下错误信息均来自与base.json文件中的已有定义：
向对应的Accessor对象写入值进行复位或上下电操作时，写入操作返回了失败
"InternalError": {
"Description": "Indicates that the request failed for an unknown internal error but that the service is still operational.",
"Message": "The request failed due to an internal service error. The service is still operational.",
"Severity": "Critical",
"NumberOfArgs": 0,
"Resolution": "Resubmit the request. If the problem persists, consider resetting the service.",
"HttpStatusCode": 500,
"IpmiCompletionCode": "0xFF",
"SnmpStatusCode": 5,
"TraceDepth": 0
}
入参取值或类型错误
"PropertyValueNotInList": {
"Description": "Indicates that a property was given the correct value type but the value of that property was not supported. This values not in an enumeration",
"Message": "The value %1 for the property %2 is not in the list of acceptable values.",
"Severity": "Warning",
"NumberOfArgs": 2,
"ParamTypes": [
"string",
"string"
],
"Resolution": "Choose a value from the enumeration list that the implementation can support and resubmit the request if the operation failed.",
"HttpStatusCode": 400,
"IpmiCompletionCode": "0xC9",
"SnmpStatusCode": 10,
"TraceDepth": 0
},
"PropertyValueTypeError": {
"Description": "Indicates that a property was given the wrong value type, such as when a number is supplied for a property that requires a string.",
"Message": "The value %1 for the property %2 is of a different type than the property can accept.",
"Severity": "Warning",
"NumberOfArgs": 2,
"ParamTypes": [
"string",
"string"
],
"Resolution": "Correct the value for the property in the request body and resubmit the request if the operation failed.",
"HttpStatusCode": 400,
"IpmiCompletionCode": "0xFF",
"SnmpStatusCode": 7,
"TraceDepth": 0
},
评审点2：redfish Drive资源新增属性SlotPowerState，用于表示物理盘槽位的电源状态
资源URI：/redfish/v1/Chassis/{ChassisId}/Drives/{DriveId}
资源版本：Drive.v1_21_0
属性列表：
| 属性名 | 类型 | 示例/默认值/取值约束 | readonly | 易变属性 | 实现PATCH | 操作权限 | 描述 |
|---|---|---|---|---|---|---|---|
| Oem | object | / | / | / | / | / | 厂商自定义资源 |
| openUBMC | object | / | / | / | / | / | 厂商标志 |
| SlotPowerState | string,null | 枚举值：“On”、“Off”，默认值为null | true | 否 | 否 | 读：ReadOnly | 表示物理盘槽位的电源状态 |
Schema定义：
"SlotPowerState": {
"description": "The power state of this drive slot.",
"longDescription": "This property shall contain the power state of this drive slot.",
"readonly": true,
"enum": [
"On",
"Off"
],
"enumDescriptions": {
"On": "The drive slot is powered on.",
"Off": "The drive slot is powered off."
},
"type": [
"string",
"null"
]
}
响应样例：
{
"@odata.context": "/redfish/v1/$metadata#Drive.Drive",
"@odata.id":"/redfish/v1/Chassis/1/Drives/HDDPlaneDisk1",
"@odata.type":"#Drive.v1_21_0.Drive",
"Id":"#Drive.v1_21_0.Drive",
"Name": "Disk1",
...
"Oem": {
"openUBMC": {
"DriveID": 1,
...
"SlotPowerState": "On"
}
},
...
"Actions": {
"#Drive.Reset": {
"target": "/redfish/v1/Chassis/1/Drives/HDDPlaneDisk1/Actions/Drive.Reset",
"@Redfish.ActionInfo": "/redfish/v1/Chassis/1/Drives/HDDPlaneDisk1/ResetActionInfo"
}
}
}
评审点3：redfish Drive 资源新增Action
资源URI：/redfish/v1/Chassis/{ChassisId}/Drives/{DriveId}/Actions/Drive.Reset
资源版本：Drive.v1_21_0
操作权限：PowerMgmt
输入参数：
| 参数名 | 类型 | 必填 | 示例/取值约束 | 描述 |
|---|---|---|---|---|
| ResetType | string | 是 | 枚举值：“ForceOn”、“ForceOff” | 上下电操作类型，“ForceOn”：强制上电，“ForceOff”：强制下电 |
ActionInfo： /redfish/v1/Chassis/{ChassisId}/Drives/{DriveId}/ResetActionInfo
Schema定义：
{
"$id": "http://redfish.dmtf.org/schemas/v1/Drive.v1_21_0.json",
"$ref": "#/definitions/Drive",
"$schema": "http://redfish.dmtf.org/schemas/v1/redfish-schema-v1.json",
"copyright": "Copyright 2014-2024 DMTF. For the full DMTF copyright policy, see http://www.dmtf.org/about/policies/copyright",
"definitions": {
"Actions": {
"additionalProperties": false,
"description": "The available actions for this resource.",
"longDescription": "This type shall contain the available actions for this resource.",
"patternProperties": {
"^([a-zA-Z_][a-zA-Z0-9_]*)?@(odata|Redfish|Message)\\.[a-zA-Z_][a-zA-Z0-9_]*$": {
"description": "This property shall specify a valid odata or Redfish property.",
"type": [
"array",
"boolean",
"integer",
"number",
"null",
"object",
"string"
]
}
},
"properties": {
"#Drive.Reset": {
"$ref": "#/definitions/Reset"
}
},
"type": "object"
},
"Reset": {
"additionalProperties": false,
"description": "This action resets this drive.",
"longDescription": "This action shall reset this drive.",
"parameters": {
"ResetType": {
"$ref": "http://redfish.dmtf.org/schemas/v1/Resource.json#/definitions/ResetType",
"description": "The type of reset.",
"longDescription": "This parameter shall contain the type of reset. The service can accept a request without the parameter and perform an implementation-specific default reset."
}
},
"patternProperties": {
"^([a-zA-Z_][a-zA-Z0-9_]*)?@(odata|Redfish|Message)\\.[a-zA-Z_][a-zA-Z0-9_]*$": {
"description": "This property shall specify a valid odata or Redfish property.",
"type": [
"array",
"boolean",
"integer",
"number",
"null",
"object",
"string"
]
}
},
"properties": {
"target": {
"description": "Link to invoke action",
"format": "uri-reference",
"type": "string"
},
"title": {
"description": "Friendly action name",
"type": "string"
}
},
"type": "object",
"versionAdded": "v1_7_0"
},
"Drive": {
"additionalProperties": false,
"description": "The `Drive` schema represents a single physical drive for a system, including links to associated volumes. It also describes the location, such as a slot, socket, or bay, where a unit can be installed, by populating a resource instance with an absent state if a unit is not present.",
"longDescription": "This resource shall represent a drive or other physical storage medium for a Redfish implementation. It may also represent a location, such as a slot, socket, or bay, where a unit may be installed, but the `State` property within the `Status` property contains `Absent`.",
"patternProperties": {
"^([a-zA-Z_][a-zA-Z0-9_]*)?@(odata|Redfish|Message)\\.[a-zA-Z_][a-zA-Z0-9_]*$": {
"description": "This property shall specify a valid odata or Redfish property.",
"type": [
"array",
"boolean",
"integer",
"number",
"null",
"object",
"string"
]
}
},
"properties": {
"Actions": {
"$ref": "#/definitions/Actions",
"description": "The available actions for this resource.",
"longDescription": "This property shall contain the available actions for this resource."
}
},
"required": [
"@odata.id",
"@odata.type",
"Id",
"Name"
],
"type": "object"
}
},
"language": "en",
"owningEntity": "DMTF",
"release": "2024.4",
"title": "#Drive.v1_21_0.Drive"
}
http://redfish.dmtf.org/schemas/v1/Resource.json#/definitions/ResetType :
"ResetType": {
"enum": [
"On",
"ForceOff",
"GracefulShutdown",
"GracefulRestart",
"ForceRestart",
"Nmi",
"ForceOn",
"PushPowerButton",
"PowerCycle",
"Suspend",
"Pause",
"Resume",
"FullPowerCycle"
],
"enumDescriptions": {
"ForceOff": "Turn off the unit immediately (non-graceful shutdown).",
"ForceOn": "Turn on the unit immediately.",
"ForceRestart": "Shut down immediately and non-gracefully and restart the unit.",
"FullPowerCycle": "Full power cycle the unit immediately (non-graceful). Behaves like removing utility lines, followed by restoring utility lines to the resource.",
"GracefulRestart": "Shut down gracefully and restart the unit.",
"GracefulShutdown": "Shut down gracefully and power off.",
"Nmi": "Generate a diagnostic interrupt, which is usually an NMI on x86 systems, to stop normal operations, complete diagnostic actions, and, typically, halt the system.",
"On": "Turn on the unit.",
"Pause": "Pause execution on the unit but do not remove power. This is typically a feature of virtual machine hypervisors.",
"PowerCycle": "Power cycle the unit immediately (non-graceful). Behaves like a power removal, followed by a power restore to the resource.",
"PushPowerButton": "Simulate the pressing of the physical power button on this unit.",
"Resume": "Resume execution on the paused unit. This is typically a feature of virtual machine hypervisors.",
"Suspend": "Write the state of the unit to disk before powering off. This allows for the state to be restored when powered back on."
},
"enumLongDescriptions": {
"ForceOff": "This value shall indicate the resource will transition to a power off state. The transition will start immediately. Upon successful completion, the `PowerState` property, if supported, shall contain the value `Off`.",
"ForceOn": "This value shall indicate the resource will transition to a power on state. The transition will start immediately. Upon successful completion, the `PowerState` property shall contain the value `On`.",
"ForceRestart": "This value shall indicate the resource will transition to a power on state, after transiting through a restart. The transition will start immediately. Upon successful completion, the `PowerState` property, if supported, shall contain the value `On`.",
"FullPowerCycle": "This value shall indicate the resource will perform a full power cycle as if utility lines to the resource are removed and restored. The transition will start immediately. This is different from `PowerCycle` in that it's as close to a true power cycle as possible. For example, removing AC power cables from an enclosure and then restoring the AC power cables. If currently in the power on state, the resource will transition to a power off state, then transition to a power on state. If currently in the power off state, the resource will transition to a power on state. Upon successful completion, the `PowerState` property, if supported, shall contain the value `On`. If a service supports this value but there are no other distinct power cycle flows, the service shall support `PowerCycle` as an alias to `FullPowerCycle`. This type of reset may cause the manager providing the Redfish service to power cycle. If the manager providing the Redfish service is affected by this type of reset, the service shall send the action response before resetting to prevent client timeouts.",
"GracefulRestart": "This value shall indicate the resource will transition to a power on state, after transiting through a restart. The transition will start after first performing tasks to safely shut down the resource. For example, when shutting down a computer system, the host operating system is allowed to safely shut down processes and close connections. Upon successful completion, the `PowerState` property, if supported, shall contain the value `On`.",
"GracefulShutdown": "This value shall indicate the resource will transition to a power off state. The transition will start after first performing tasks to safely shut down the resource. For example, when shutting down a computer system, the host operating system is allowed to safely shut down processes and close connections. Upon successful completion, the `PowerState` property, if supported, shall contain the value `Off`.",
"Nmi": "This value shall indicate the resource will generate a diagnostic interrupt.",
"On": "This value shall indicate the resource will transition to a power on state. Upon successful completion, the `PowerState` property, if supported, shall contain the value `On`.",
"Pause": "This value shall indicate the resource will transition to a paused state. Upon successful completion, the `PowerState` property, if supported, shall contain the value `Paused`.",
"PowerCycle": "This value shall indicate the resource will perform a power cycle. The transition will start immediately. This is different from `FullPowerCycle` in that it typically performs localized power sequencing of the resource while external power is still present. For example, turning DC voltage regulators off and then turning DC voltage regulators back on. If currently in the power on state, the resource will transition to a power off state, then transition to a power on state. If currently in the power off state, the resource will transition to a power on state. Upon successful completion, the `PowerState` property, if supported, shall contain the value `On`.",
"PushPowerButton": "This value shall indicate the resource will behave as if the physical power button is pressed. The behavior of pressing the physical power button may be dependent on the state of the unit and the behavior may be configurable.",
"Resume": "This value shall indicate the resource will transition to a power on state. Upon successful completion, the `PowerState` property, if supported, shall contain the value `On`.",
"Suspend": "This value shall indicate the resource will have any state information written to persistent memory and then transition to a power off state. Upon successful completion, the `PowerState` property, if supported, shall contain the value `Off`."
},
"enumVersionAdded": {
"FullPowerCycle": "v1_21_0",
"Pause": "v1_13_0",
"PowerCycle": "v1_4_0",
"Resume": "v1_13_0",
"Suspend": "v1_13_0"
},
"type": "string"
}
评审点4：新增ipmi接口命令字，用于查询指定物理盘槽位的电源状态
命令名称： Get Storage Configurations
命令说明： 用于查询指定物理盘槽位的电源状态
命令权限： ReadOnly
是否锁定之后可以访问： 是
是否有敏感数据： 否
命令样式：
- 请求：
ipmitool raw 0x30 0x93 <ManufacturerID> 0x3d <Reserve> <ParameterSelector><SetSelector><BlockSelector><ExternSelector><ReadingOffset><ReadingLength> - 响应：
<ManufacturerID><Reserve><Data>
命令请求参数：
| 字节顺序 | 域取值说明 |
|---|---|
| NetFn | 30h |
| Cmd | 93h |
| 1:3 | Manufacturer ID，LB Byte first。长度固定 3 个字节，例如，某厂家ID时 2011，对应十六进制为0x0007DB，则字节序为第1个字节为 DBh，第二个字节为 07h，第三个字节为 00h。 |
| 4 | SubCmd，固定为 3Dh |
| 5 | Reserve,保留 |
| 6 | Parameter Selector，1Ch，用于查询指定物理盘槽位的电源状态 |
| 7 | Set Selector，不涉及，填0xFF |
| 8 | Block Selector，物理盘槽位ID |
| 9 | Extern Selector，不涉及，填0xFF |
| 10:11 | Reading Offset，获取参数的偏移 |
| 12 | Reading Length，获取参数的长度 |
命令响应参数：
| 字节顺序 | 域取值说明 |
|---|---|
| 1 | Completion Code，完成码 |
| 2:4 | Manufacturer ID，LB Byte first。长度固定 3 个字节，例如，某厂家ID时 2011，对应十六进制为0x0007DB，则字节序为第1个字节为 DBh，第二个字节为 07h，第三个字节为 00h。 |
| 5 | [7:1]：Reserve 0：0-last frame，1-casecade frame |
| 6:N | Data，data1：用于查询指定物理盘槽位的电源状态，0：下电，1：上电，255：UNKNOWN |
命令示例：
样例1： 查询槽位为1的物理盘电源状态
- 请求：
ipmitool raw 0x30 0x93 0xdb 0x07 0x00 0x3d 0x00 0x1c 0xff 0x01 0xff 0x00 0x00 0x01 - 响应：
db 07 00 00 01
评审点5：新增ipmi接口命令字，用于设置指定物理盘槽位的电源状态
命令名称： Set Storage Configurations
命令说明： 用于设置指定物理盘槽位的电源状态
命令权限： PowerMgmt
是否锁定之后可以访问： 否
是否有敏感数据： 否
命令样式：
- 请求：
ipmitool raw 0x30 0x93 <ManufacturerID> 0x3e <Reserve> <ParameterSelector><SetSelector><BlockSelector><ExternSelector><Reserve><WritingOffset><WritingLength><Data> - 响应：
<ManufacturerID><Reserve>
命令请求参数：
| 字节顺序 | 域取值说明 |
|---|---|
| NetFn | 30h |
| Cmd | 93h |
| 1:3 | Manufacturer ID，LB Byte first。长度固定 3 个字节，例如，某厂家ID时 2011，对应十六进制为0x0007DB，则字节序为第1个字节为 DBh，第二个字节为 07h，第三个字节为 00h。 |
| 4 | SubCmd，固定为 3Eh |
| 5 | Reserve,保留 |
| 6 | Parameter Selector，1Ch，设置指定物理盘槽位的电源状态 |
| 7 | Set Selector，不涉及，填0xFF |
| 8 | Block Selector，物理盘槽位ID |
| 9 | Extern Selector，不涉及，填0xFF |
| 10 | [7:1]：Reserve 0：0-last frame，1-casecade frame |
| 11:12 | Writing Offset，设置参数的偏移 |
| 13 | Writing Length，设置参数的长度 |
| 14 | Data，data1：用于设置指定物理盘槽位的电源状态，0：下电，1：上电 |
命令响应参数：
| 字节顺序 | 域取值说明 |
|---|---|
| 1 | Completion Code，完成码 |
| 2:4 | Manufacturer ID，LB Byte first。长度固定 3 个字节，例如，某厂家ID时 2011，对应十六进制为0x0007DB，则字节序为第1个字节为 DBh，第二个字节为 07h，第三个字节为 00h。 |
| 5:8 | 预留 |
| 9:N | Data，不涉及 |
命令示例：
样例1： 对槽位为1的物理盘进行上电操作
- 请求：
ipmitool raw 0x30 0x93 0xdb 0x07 0x00 0x3e 0x00 0x1c 0xff 0x01 0xff 0x00 0x00 0x00 0x01 0x01 - 响应：
db 07 00 00 00 00 00
评审结论
通过，具体结论如下：
- 同意在资源协作接口bmc.kepler.Systems.Storage.Drive下新增以下属性SlotPowerState和方法SetSlotPowerState：
- SlotPowerState：表征物理盘槽位的电源状态；属性签名为 y，只读，读权限为ReadOnly，属性变化时发送变更通知，不持久化；
- SetSlotPowerState：表征设置物理盘槽位的电源状态；请求签名为 s，无响应，操作权限为 PowerMgmt。
- 同意在redfish资源/redfish/v1/Chassis/{ChassisId}/Drives/{DriveId}下新增Oem属性SlotPowerState：表示物理盘槽位的电源状态，权限：ReadOnly，类型：string/null
- 同意新增redfish标准接口/redfish/v1/Chassis/{ChassisId}/Drives/{DriveId}/Actions/Drive.Reset，操作类型为 POST，权限为 PowerMgmt，入参类型为 string，入参属性ResetType为枚举值（ForceOff、ForceOn），功能为操作物理盘槽位的上下电;
- 同意在获取存储配置（NetFn：30h，CMD：93h，Sub Command：3Dh）的IPMI命令的Parameter Selector参数中新增参数取值28，表征获取物理盘槽位的电源状态。
- 同意在设置存储配置（NetFn：30h，CMD：93h，Sub Command：3Eh）的IPMI命令的Parameter Selector参数中新增参数取值28，表征设置物理盘槽位的电源状态。
遗留问题
- 确认用于设置指定物理盘槽位电源状态的资源协作接口方法SetSlotPowerState、redfish Action操作和ipmi命令的访问权限
结论：已确认用于设置指定物理盘槽位电源状态的资源协作接口方法SetSlotPowerState、redfish Action操作和ipmi命令的访问权限为PowerMgmt。
