RAID管理库接口文档说明书

[changxingOpenUBMC (changdexing)]

RAID管理库接口文档

概述

本文档描述了管理RAID卡的接口说明，指导新增管理不同RAID卡需要实现的适配层接口，使得BMC的存储模块可以动态加载已实现本文接口的库来管理RAID卡。

读者对象

本文中涉及的接口主要是研发人员使用，指导研发人员按照接口定义实现RAID卡管理库。

修改记录

文档版本	发布日期	修改说明
01	2025-2-26	第一次创建文档
02	2025-3-20	新增部分接口说明

基本信息

• 动态库名称: libsml_custom_base.so
• 版本: 1.0.0

---

1. 结构体定义

1.1 SML_CTRL_OOB_INFO_S结构体定义

typedef gint32 (*I2C_WRITE_FUNC)(guint8 obj_index, guint8* pWritebuf, guint8 write_length);
typedef gint32 (*I2C_WRITEREAD_FUNC)(guint8 obj_index, guint8* pWritebuf, guint8 write_length,
    guint8* pReadbuf, guint8 read_length);
typedef gint32 (*MCTP_WRITEREAD_FUNC)(guint8 obj_index, guint32 request_length, const guint8 *request,
    guint32 *response_length, guint8 *response, guint32 timeout);

// -----------------注册RAID管理时需要的数据
typedef struct tag_sml_register_ctrl_oob_info {
    guint8  i_controller_index; // RAID控制器的索引号，从0开始
    guint8  i_controller_typeid; // RAID控制器的类型编号
    union {
        struct {
            guint8  eid;
            guint16 phy_addr;
            MCTP_WRITEREAD_FUNC mctp_writeread_func;
        } over_mctp;
        struct {
            I2C_WRITE_FUNC i2c_write_func;         // 注册的I2CWrite回调接口
            I2C_WRITEREAD_FUNC i2c_writeread_func; // 注册的I2CWriteRead回调接口
        } over_i2c;
    } register_info;

    guint8  i_oob_operate;
    guint8  i_oob_interface_type;
} SML_CTRL_OOB_INFO_S;

1.2 SML_CTRL_PD_LIST_S结构体定义

#define SML_MAX_PHYSICAL_DRIVES           256

// -----------------RAID控制器管理的PD列表
typedef struct tag_sml_ctrl_pd_list {
    guint8  i_controller_index; // RAID控制器的索引号，从0开始
    guint16 o_pd_count;
    guint16 o_pd_deviceIDs[SML_MAX_PHYSICAL_DRIVES];
    guint8  o_pd_slot_num[SML_MAX_PHYSICAL_DRIVES];
    guint16 o_pd_enclosure_id[SML_MAX_PHYSICAL_DRIVES];
} SML_CTRL_PD_LIST_S;

1.3 SML_CTRL_LD_LIST_S结构体定义

#define SML_MAX_LOGIC_DRIVES              240

// -----------------RAID控制器管理的LD列表
typedef struct tag_sml_ctrl_ld_list {
    guint8  i_controller_index; // RAID控制器的索引号，从0开始
    guint16 o_ld_count;
    guint16  o_ld_targetIDs[SML_MAX_LOGIC_DRIVES];
} SML_CTRL_LD_LIST_S;

1.4 SML_CTRL_ARRAY_LIST_S结构体定义

#define SML_MAX_ARRAY                     128

// ------------控制器Array列表
typedef struct tag_sml_ctrl_array_list {
    guint8  i_controller_index; // RAID控制器的索引号，从0开始
    guint8  o_array_count; // 获取到的Array个数
    guint16 o_array_refs[SML_MAX_ARRAY]; // Array ID列表
} SML_CTRL_ARRAY_LIST_S;

1.5 SML_CTRL_BOOTABLE_DEVICES_S结构体定义

#define SML_MAX_BOOTABLE_DEVICES          8

typedef struct tag_sml_ctrl_boot_devices {
    guint8 i_controller_index; // RAID控制器的索引号，从0开始
    guint32 o_bootable_devices[SML_MAX_BOOTABLE_DEVICES];
} SML_CTRL_BOOTABLE_DEVICES_S;

1.6 SML_CTRL_SAS_ADDR_S结构体定义

#define SML_SAS_ADDR_LENGTH               32

// -----------------SAS地址
typedef struct tag_sml_ctrl_sas_addr {
    guint8  i_controller_index; // RAID控制器的索引号，从0开始
    gchar   o_sas_addr[SML_SAS_ADDR_LENGTH];
} SML_CTRL_SAS_ADDR_S;

1.7 SML_CTRL_OPERTATION_S结构体定义

// ------------对RAID控制器执行操作
typedef struct tag_sml_ctrl_operation {
    guint8  i_controller_index; // RAID控制器的索引号，从0开始
    /*
    i_operation                                        i_param_ptr
    CTRL_OPERATION_DISABLE_COPYBACK      = 0,          guint8* disable 1:禁止copyback 0:使能copyback
    CTRL_OPERATION_ENABLE_SMART_COPYBACK = 1,          guint8* enable  1:使能SMART copyback 0:禁止SMART copyback
    CTRL_OPERATION_ENABLE_JBOD           = 2,          guint8* enable  1:使能JBOD 0:禁止JBOD
    CTRL_OPERATION_RESTORE_DEFAULT       = 3,          无参数
    CTRL_OPERATION_SET_BIOS_BOOT_MODE    = 4,          guint8* 参考SML_CTRL_BIOS_BOOT_MODE_E
    */
    guint16 i_operation;
    gpointer i_param_ptr;
    guint32 i_param_size;
} SML_CTRL_OPERTATION_S;

1.8 SML_CTRL_HEALTH_STATUS_S结构体定义

// -----------------RAID的健康状态
typedef struct tag_sml_ctrl_health_status {
    guint8  i_controller_index; // RAID控制器的索引号，从0开始
    guint16  o_health_status_code;
    /*
    bit0: 1- 内存有可纠正错误
    bit1: 1- 内存有不可纠正错误
    bit2: 1- 内存有ECC错误达到阈值
    bit3: 1- NVRAM有不可纠正错误
    bit4: reserved
    bit5: 1- pg信号异常
    bit6: 1- 内部模块检测故障（导致IO停止）
    bit7: 1- 内部模块参考时钟故障
    bit8: 1- 内部电源电压故障
    bit9: 1- 内部备电模块电容故障
    bit10: 1- 内部flash模块故障
    bit11-15: reserved
    */
    guint16  o_hw_err;
    guint8  o_clk_err;
    guint8  o_power_err;
    guint8  o_capacity_err;
    guint8  o_flash_err;
    guint8  o_err_change;
} SML_CTRL_HEALTH_STATUS_S;

1.9 SML_LD_TARGET_S结构体定义

// ------------删除指定的逻辑盘/设置指定逻辑盘为启动盘
typedef struct tag_sml_ld_target {
    guint8  i_controller_index; // RAID控制器的索引号，从0开始
    guint16  i_target_id; // 指定的逻辑盘ID
    gpointer i_param_ptr; // 扩展参数指针（如指定启动优先级）
    guint32 i_param_size; // 扩展参数大小
} SML_LD_TARGET_S;

1.10 SML_RAID_ON_EXISTED_ARRAY_PARAM_S结构体定义

#define SML_LD_NAME_LENGTH 128
#define SML_ERR_SHORT_BRIEF_LEN 128
#define SML_MAX_SPAN_DEPTH                16

// ------------创建逻辑盘的公共属性参数
typedef struct tag_sml_create_ld_common_properties {
    guint32 capacity;                  // 容量大小, MB为单位
    gchar ld_name[SML_LD_NAME_LENGTH]; // 逻辑盘的名称，以'\0'结束的ASCII字符串
    guint8 strip_size;                 // 条带大小 64K/128K/256K/512K/1024K(7~11)
    guint8 read_policy;                // 读策略 Read Ahead/No Read Ahead/ Adaptive Read Ahead
    guint8 write_policy;               // 写策略 Write Through/Write Back/Write caching ok if bad BBU
    guint8 io_policy;                  // IO策略 Direct IO/Cached IO
    guint8 access_policy;              // 访问策略 Read Write/Read Only/Blocked
    guint8 disk_cache_policy;          // 硬盘缓存策略 Unchanged/Enable/Disable
    guint8 init_state;                 // 初始化状态 No Init/Quick Init/Full Init
    guint8 accelerator;
} SML_CREATE_LD_COMMON_PROPERTIES_S;

// ------------创建逻辑盘返回的参数
typedef struct tag_sml_create_ld_return_param {
    gint32 err_code;                                    // 创建逻辑盘返回的错误码
    gchar err_short_brief[SML_ERR_SHORT_BRIEF_LEN + 1]; // 错误简短描述
    guint16 ld_target_id;                                // 新创建的逻辑盘ID，创建成功才可用
    guint8 array_count;                                 // 创建使用的Array个数，创建成功才可用
    guint16 array_refs[SML_MAX_SPAN_DEPTH]; // 创建使用的Array ID，可能为新建，也可能是已有的Array，创建成功才可用
} SML_CREATE_LD_RETURN_PARAM_S;

// ------------在现有Array上创建逻辑盘
typedef struct tag_sml_raid_on_existed_array_param {
    guint8  i_controller_index; // RAID控制器的索引号，从0开始
    guint16 i_array_ref; // 存在空闲空间的Array ID
    guint8  i_block_index;
    guint8  i_raid_level;
    guint8  i_span_depth;
    SML_CREATE_LD_COMMON_PROPERTIES_S i_props; // 创建时用到的逻辑盘属性

    SML_CREATE_LD_RETURN_PARAM_S o_ret_param; // 返回参数
} SML_RAID_ON_EXISTED_ARRAY_PARAM_S;

1.11 SML_RAID_ON_NEW_ARRAY_PARAM_S结构体定义

// ------------在新的Array上创建逻辑盘
typedef struct tag_sml_raid_on_new_array_param {
    guint8  i_controller_index; // RAID控制器的索引号，从0开始
    guint8  i_span_depth; // span的个数
    guint8  i_num_drive_per_span; // 每个span的硬盘数
    guint16 i_pd_sel[SML_MAX_PHYSICAL_DRIVES]; // 选择的硬盘列表，总的硬盘数=span的个数x每个span的硬盘数
    guint8  i_raid_level; // RAID级别:0/1/5/6/10/50/60

    SML_CREATE_LD_COMMON_PROPERTIES_S i_props; // 创建时用到的逻辑盘属性

    SML_CREATE_LD_RETURN_PARAM_S o_ret_param; // 返回参数
} SML_RAID_ON_NEW_ARRAY_PARAM_S;

1.12 SML_LD_SSCD_CACHING_ENABLE_S结构体定义

// ------------设置普通逻辑盘是否关联到CacheCade逻辑盘
typedef struct tag_sml_ld_sscd_caching_enable {
    guint8  i_controller_index; // RAID控制器的索引号，从0开始
    guint16  i_target_id; // 逻辑盘ID
    guint8  o_sscd_caching_enable; // 是否有关联到cachecade LD
} SML_LD_SSCD_CACHING_ENABLE_S;

1.13 SML_SSCD_ASSOCIATED_LD_LIST_S结构体定义

// ------------获取指定CacheCade LD关联的逻辑盘ID列表
typedef struct tag_sml_sscd_associated_ld_list {
    guint8  i_controller_index; // RAID控制器的索引号，从0开始
    guint16  i_sscd_id; // CacheCade逻辑盘ID
    guint8  o_ld_count; // 关联的逻辑盘个数
    guint16  o_ld_ids[SML_MAX_LOGIC_DRIVES]; // 关联的逻辑盘ID列表
} SML_SSCD_ASSOCIATED_LD_LIST_S;

2. 接口定义

2.1 sml_register_controller接口定义

• 接口名称：gint32 sml_register_controller(SML_CTRL_OOB_INFO_S *ctrl)
• 接口说明：APP向SML注册RAID控制器的管理信息，SML会初始化对应的全局数据，并
  根据注册信息调用第三方的初始化接口
• 入参说明：

  参数	参数说明	取值
  ctrl	控制器信息

• 返回值说明：

  返回值	返回值说明	取值
  注册结果	注册成功或失败	0：成功、其他错误码：失败

• 举例说明：

  gint32 sml_register_controller(SML_CTRL_OOB_INFO_S *ctrl)
  {
       return 0;
  }
  

2.2 sml_unregister_controller接口定义

• 接口名称：gint32 sml_unregister_controller(SML_CTRL_OOB_INFO_S* ctrl)
• 接口说明：APP通知SML退出RAID控制器的管理，SML会清除全局数据，并调用第三方的
  清理接口
• 入参说明：

  参数	参数说明	取值
  ctrl	控制器信息

• 返回值说明：

  返回值	返回值说明	取值
  注册结果	注册成功或失败	0：成功、其他错误码：失败

• 举例说明：

  gint32 sml_unregister_controller(SML_CTRL_OOB_INFO_S *ctrl)
  {
       return 0;
  }
  

2.3 sml_get_ctrl_pd_list接口定义

• 接口名称：gint32 sml_get_ctrl_pd_list(SML_CTRL_PD_LIST_S *pd_list)
• 接口说明：APP向SML获取RAID控制器的PD列表
• 入参说明：

  参数	参数说明	取值
  pd_list	获取到的PD列表

• 返回值说明：

  返回值	返回值说明	取值
  获取结果	获取成功或失败	0：成功、其他错误码：失败

• 举例说明：

  gint32 sml_get_ctrl_pd_list(SML_CTRL_PD_LIST_S *pd_list)
  {
       return 0;
  }
  

2.4 sml_get_ctrl_ld_list接口定义

• 接口名称：gint32 sml_get_ctrl_ld_list(SML_CTRL_LD_LIST_S* ld_list)
• 接口说明：APP向SML获取RAID控制器的LD列表
• 入参说明：

  参数	参数说明	取值
  ld_list	获取到的LD列表

• 返回值说明：

  返回值	返回值说明	取值
  获取结果	获取成功或失败	0：成功、其他错误码：失败

• 举例说明：

  gint32 sml_get_ctrl_ld_list(SML_CTRL_LD_LIST_S* ld_list)
  {
       return 0;
  }
  

2.5 sml_get_ctrl_array_list接口定义

• 接口名称：gint32 sml_get_ctrl_array_list(SML_CTRL_ARRAY_LIST_S* ctrl)
• 接口说明：APP通过SML获取指定RAID控制器下的array列表
• 入参说明：

  参数	参数说明	取值
  ld_list	获取到的array列表

• 返回值说明：

  返回值	返回值说明	取值
  获取结果	获取成功或失败	0：成功、其他错误码：失败

• 举例说明：

  gint32 sml_get_ctrl_array_list(SML_CTRL_ARRAY_LIST_S* ctrl)
  {
       return 0;
  }
  

2.6 sml_get_ctrl_boot_devices接口定义

• 接口名称：gint32 sml_get_ctrl_boot_devices(SML_CTRL_BOOTABLE_DEVICES_S *boot_devices)
• 接口说明：APP通过SML获取指定RAID控制器的启动盘
• 入参说明：

  参数	参数说明	取值
  boot_devices	获取的RAID控制器的启动盘

• 返回值说明：

  返回值	返回值说明	取值
  获取结果	获取成功或失败	0：成功、其他错误码：失败

• 举例说明：

  gint32 sml_get_ctrl_boot_devices(SML_CTRL_BOOTABLE_DEVICES_S *boot_devices)
  {
       return 0;
  }
  

2.7 sml_get_ctrl_sas_addr接口定义

• 接口名称：gint32 sml_get_ctrl_sas_addr(SML_CTRL_SAS_ADDR_S *sas_addr)
• 接口说明：APP向SML获取RAID控制器的SAS地址
• 入参说明：

  参数	参数说明	取值
  sas_addr	获取的RAID控制器的SAS地址

• 返回值说明：

  返回值	返回值说明	取值
  获取结果	获取成功或失败	0：成功、其他错误码：失败

• 举例说明：

  gint32 sml_get_ctrl_sas_addr(SML_CTRL_SAS_ADDR_S* ctrl)
  {
       return 0;
  }
  

2.8 sml_ctrl_operation接口定义

• 接口名称：gint32 sml_ctrl_operation(SML_CTRL_OPERTATION_S *ctrl_opertation)
• 接口说明：APP通过SML对PD执行操作
• 入参说明：

  参数	参数说明	取值
  ctrl_opertation	对PD执行操作

• 返回值说明：

  返回值	返回值说明	取值
  获取结果	获取成功或失败	0：成功、其他错误码：失败

• 举例说明：

  gint32 sml_ctrl_operation(SML_CTRL_OPERTATION_S *ctrl_opertation)
  {
       return 0;
  }
  

2.9 sml_get_ctrl_health_status接口定义

• 接口名称：gint32 sml_get_ctrl_health_status(SML_CTRL_HEALTH_STATUS_S *health_status)
• 接口说明：APP向SML获取RAID控制器的健康状态
• 入参说明：

  参数	参数说明	取值
  health_status	获取RAID控制器的健康状态

• 返回值说明：

  返回值	返回值说明	取值
  获取结果	获取成功或失败	0：成功、其他错误码：失败

• 举例说明：

  gint32 sml_get_ctrl_health_status(SML_CTRL_HEALTH_STATUS_S *health_status)
  {
       return 0;
  }
  

2.10 sml_dump_ctrl_single_log接口定义

• 接口名称：gint32 sml_dump_ctrl_single_log(guint8 ctrl_id, const gchar *src_dir, guint8 log_type, const gchar *log_name)
• 接口说明：
• 入参说明：

  参数	参数说明	取值

• 返回值说明：

  返回值	返回值说明	取值
  获取结果	获取成功或失败	0：成功、其他错误码：失败

• 举例说明：

  gint32 sml_dump_ctrl_single_log(guint8 ctrl_id, const gchar *src_dir, guint8 log_type, const gchar *log_name)
  {
       return 0;
  }
  

2.11 sml_set_ld_boot_priority接口定义

• 接口名称：gint32 sml_set_ld_boot_priority(SML_LD_TARGET_S *ld)
• 接口说明：APP通过SML执行设置指定逻辑盘为启动盘的命令
• 入参说明：

  参数	参数说明	取值
  ld

• 返回值说明：

  返回值	返回值说明	取值
  获取结果	获取成功或失败	0：成功、其他错误码：失败

• 举例说明：

  gint32 sml_set_ld_boot_priority(SML_LD_TARGET_S *ld)
  {
       return 0;
  }
  

2.12 sml_set_ld_delete接口定义

• 接口名称：gint32 sml_set_ld_delete(SML_LD_TARGET_S *ld)
• 接口说明：APP通过SML执行删除指定逻辑盘的命令
• 入参说明：

  参数	参数说明	取值
  ld

• 返回值说明：

  返回值	返回值说明	取值
  获取结果	获取成功或失败	0：成功、其他错误码：失败

• 举例说明：

  gint32 sml_set_ld_delete(SML_LD_TARGET_S *ld)
  {
       return 0;
  }
  

2.13 sml_create_ld_on_existed_array接口定义

• 接口名称：gint32 sml_create_ld_on_existed_array(SML_RAID_ON_EXISTED_ARRAY_PARAM_S *config)
• 接口说明：APP通过SML执行删除指定逻辑盘的命令
• 入参说明：

  参数	参数说明	取值
  config

• 返回值说明：

  返回值	返回值说明	取值
  获取结果	获取成功或失败	0：成功、其他错误码：失败

• 举例说明：

  gint32 sml_create_ld_on_existed_array(SML_RAID_ON_EXISTED_ARRAY_PARAM_S *config)
  {
       return 0;
  }
  

2.14 sml_create_ld_on_new_array接口定义

• 接口名称：gint32 sml_create_ld_on_new_array(SML_RAID_ON_NEW_ARRAY_PARAM_S* config)
• 接口说明：APP通过SML执行在新的阵列上创建逻辑盘的命令
• 入参说明：

  参数	参数说明	取值
  config

• 返回值说明：

  返回值	返回值说明	取值
  获取结果	获取成功或失败	0：成功、其他错误码：失败

• 举例说明：

  gint32 sml_create_ld_on_new_array(SML_RAID_ON_NEW_ARRAY_PARAM_S* config)
  {
       return 0;
  }
  

2.15 sml_get_ld_sscd_caching_enable接口定义

• 接口名称：gint32 sml_get_ld_sscd_caching_enable(SML_LD_SSCD_CACHING_ENABLE_S* ld)
• 接口说明：APP通过SML获取指定LD是否关联了CacheCade LD
• 入参说明：

  参数	参数说明	取值
  ld

• 返回值说明：

  返回值	返回值说明	取值
  获取结果	获取成功或失败	0：成功、其他错误码：失败

• 举例说明：

  gint32 sml_get_ld_sscd_caching_enable(SML_LD_SSCD_CACHING_ENABLE_S* ld)
  {
       return 0;
  }
  

2.16 sml_get_sscd_associated_ld_list接口定义

• 接口名称：gint32 sml_get_sscd_associated_ld_list(SML_SSCD_ASSOCIATED_LD_LIST_S* ld)
• 接口说明：APP通过SML获取指定LD是否关联了CacheCade LD
• 入参说明：

  参数	参数说明	取值
  ld

• 返回值说明：

  返回值	返回值说明	取值
  获取结果	获取成功或失败	0：成功、其他错误码：失败

• 举例说明：

  gint32 sml_get_sscd_associated_ld_list(SML_SSCD_ASSOCIATED_LD_LIST_S* ld)
  {
       return 0;
  }
  

[zybwh (张雨博)]

请添加各结构体、接口的使用方式，以及各结构体、接口的介绍