【已评审】支持引用同对象不同接口方案评审

Interface SIG Interface评审
1

背景说明

业务场景中频繁存在访问Chip方法的场景，且这些方法是挂在不同interface下面的，举例如下：

  • Cpld对象下的Read/Write方法在bmc.kepler.Chip.BlockIO接口下，SetLockStatus方法在bmc.kepler.Chip接口下
{
    "Cpld": {
        "package":"Cpld",
        "path": "/bmc/kepler/Chip/Cpld/:Id",
        "interfaces": [
            "bmc.kepler.Chip.BlockIO",
            "bmc.kepler.Chip",
            "bmc.kepler.Chip.JtagTarget",
            "bmc.kepler.Release.TraceChip"
        ]
    }
}

{
    "bmc.kepler.Chip.BlockIO": {
        "properties": {},
        "methods": {
            "Read": {
                "req": {
                    "Offset": {
                    },
                    "Length": {
                    }
                },
                "rsp": {
                    "OutData": {
                    }
                },
                "description": "按字节读取从芯片的offset偏移位置读取指定长度内容"
            },
            "Write": {
                "req": {
                    "Offset": {
                    },
                    "InData": {
                    }
                },
                "description": "按字节将指定内容写入芯片的offset偏移位置"
            }
        }
    }
}

{
    "bmc.kepler.Chip": {
        "properties": {
            "LockStatus": {
                "description": "硬件通道锁定状态，0表示未锁定，1表示锁定"
            }
        },
        "methods": {
            "SetAccessibility": {
                "req": {
                    "Status": {
                    },
                    "DisableDuration": {
                    }
                },
                "description": "设置芯片可访问状态: true:使能访问芯片， false:禁止访问芯片，禁止时长，单位: 秒，取值范围: [1, 1800]"
            },
            "SetLockStatus": {
                "req": {
                    "OpType": {
                    },
                    "LockTime": {
                    }
                },
                "rsp": {
                    "ResultCode": {
                    }
                },
                "description": "设置芯片锁定状态，optype为1，表示加锁，0表示解释"
            }
        }
    }
}

详细描述

针对以上场景，有如下两种实现方案：

方案一（已有机制支持）

通过refInterface语法配置接口引用，从而指明引用对象是在哪个接口下，有几个接口就配置几个属性承载；

  • 对应model.json配置样例如下：
"LogicFirmware": {
    "properties": {
        "UpgradeChip": {
            "usage": [
                "CSR"
            ],
            "baseType": "U8[]",
            "refInterface": "bmc.kepler.Chip.BlockIO"
        },
        "UpgradeLockChip": {
            "usage": [
                "CSR"
            ],
            "baseType": "U8[]",
            "refInterface": "bmc.kepler.Chip"
        }
    }
}
  • 对应CSR配置样例如下：
"LogicFirmware_SEU_1": {
    "UpgradeChip": "#/Cpld_1",
    "UpgradeLockChip": "#/Cpld_1"
}
  • 使用样例：
local logic_fw_obj = xxx

logic_fw_obj.UpgradeChip:Write(xx)
logic_fw_obj.UpgradeLockChip:SetLockStatus(xx)
方案优缺点：
  • 优点：属性已绑定对象接口，编码时通过属性名即可区分用途，不需要额外指定接口，理解和开发成本低；
  • 缺点：引用同一个对象的多个接口时，需要在模型中添加多个属性来绑定不同接口，并且需要在各产品所有对象的CSR配置中添加属性配置，配置和维护成本高；

方案二（需要新增机制）

新增MDS语法：通过refInterfaces语法配置引用多个接口，从而使用一个属性就可以承载多个接口下的对象，可以极大的减少CSR配置工作量和出错的风险；

  • 对应model.json配置样例如下：
"LogicFirmware": {
    "properties": {
        "UpgradeChip": {
            "usage": [
                "CSR"
            ],
            "baseType": "U8[]",
            "refInterfaces": [
                "bmc.kepler.Chip",
                "bmc.kepler.Chip.BlockIO"
            ]
        }
    }
}
  • 对应CSR配置样例如下：
"LogicFirmware_SEU_1": {
    "UpgradeChip": "#/Cpld_1"
}
  • 使用样例：
local logic_fw_obj = xxx
local logic_upgrade_chip = logic_fw_obj.UpgradeChip["bmc.kepler.Chip.BlockIO"]
local logic_lock_chip = logic_fw_obj.UpgradeChip["bmc.kepler.Chip"]

logic_upgrade_chip:Write(xx)
logic_lock_chip:SetLockStatus(xx)
方案优缺点：
  • 优点：扩展友好，引用同一对象多个接口时，只需要在MDS模型中原有属性下添加新的接口即可，不需要新增属性，也不需要批量修改CSR配置，配置和维护成本低、验证工作量小；
  • 缺点：开发者在使用时，需要使用指定接口来调用方法或获取属性，开发者需要理解refInterface和refInterfaces的区别；

评审点

是否新增支持方案二，即新增refInterfaces关键字描述引用的接口列表，简化多接口引用的配置复杂度

评审结论

通过，具体结论如下：

同意新增 refInterfaces关键字描述引用的接口列表，简化多接口引用的配置复杂度。需要补充约束：refInterfaces下挂interface必须是在相同path下，自动生成代码增加约束检查。