API指南

规格约束

• cache初始化传入容量大小，当前最大256TiB，不支持动态修改。
• cache_line_size支持8k/16k/32k/64k，推荐使用8k。
• ocf会创建io_worker_num个队列，一个io_worker对应一个ocf队列对submission_queue/completion_queue。
• region_id全局唯一，一个slot对应一个core，最多支持511个core，一个core逻辑空间最大4096TiB，最多承载128K个32GiB region。Slot下所有region放在slot对应core。设备空间下，region_id重映射一个remap_id，region在core上对应的区间为remap_id*32GiB ~ (remap_id+1)*32GiB。
• 同一个slot调用的ocf_get/ocf_put/ocf_invalid/ocf_lookup要求在一个线程中。

对外接口

初始化

函数定义

ocf模块初始化。接口类型为同步接口。

实现方法

int ocf_init(struct ocf_config *cfg);

参数说明

返回值

• STATE_SUCCESS：初始化成功。
• STATE_PARAM_INVALID：cfg内部参数非法，例如cache_line_size不是支持的类型。
• STATE_FAIL：ocf初始化失败，例如ocf已经进行过初始化；ocf上下文初始化/cache初始化等流程失败。

退出

函数定义

ocf模块注销接口。接口类型为同步接口。

实现方法

void ocf_exit();

参数说明

无入参

返回值

无返回值

创建core

函数定义

当前ocf core和slot一 一对应，新增slot时，通过该接口创建对应的ocf core资源。接口类型为异步接口。

实现方法

int ocf_add_core(uint32_t slot_id);

参数说明

返回值

• STATE_SUCCESS：ocf core创建成功。
• STATE_OCF_UNAVAILABLE：ocf不可用，例如未进行初始化，或正在恢复中。
• STATE_CORE_EXIST：slot对应的core已经创建。
• STATE_MEM_ALLOC_ERR：内存不足或内存申请失败。
• STATE_FAIL：core创建流程失败。

删除core

函数定义

当前ocf core和slot一 一对应，迁出或删除slot时，通过该接口释放对应的ocf core资源。释放时，ocf内部会对core在cache的映射做失效来确保slot在ocf中的缓存清除。接口类型为异步接口。

实现方法

int ocf_remove_core(uint32_t slot_id);

参数说明

返回值

• STATE_SUCCESS：ocf core移除成功。
• STATE_OCF_UNAVAILABLE：ocf不可用，未进行初始化或正在做恢复中。
• STATE_CORE_CREATING：slot对应的core正在创建，不能删除。
• STATE_MEM_ALLOC_ERR：内存不足或内存申请失败。

region cache失效

函数定义

region删除时，调用该接口来清除cache中的region数据。接口类型为异步接口。

实现方法

int ocf_remove_region(uint32_t slot_id, uint32_t region_id);

参数说明

返回值

• STATE_SUCCESS，数据清除成功。
• STATE_OCF_UNAVAILABLE，ocf不可用。
• STATE_MEM_ALLOC_ERR，申请失败。

提交读请求

函数定义

将读请求提交到ocf队列，接口类型为异步接口。

请求说明：region指定区间数据在cache中读取。

实现方法

int ocf_get(struct req_context *cxt);

参数说明

返回值

• STATE_SUCCESS，请求提交ocf队列成功。
• STATE_OCF_UNAVAILABLE，ocf不可用。
• STATE_PARAM_INVALID，ctx为空指针或者ctx内部参数设置不合法。
• STATE_CORE_NOT_EXIST，slot对应core不存在，请求提交失败。
• STATE_MEM_ALLOC_ERR，内存申请失败。

提交写请求

函数定义

将写请求提交到ocf队列，异步接口。

请求类型：将region指定区间数据刷新到cache。

实现方法

int ocf_put(struct req_context *cxt);

参数说明

返回值

• STATE_SUCCESS，请求提交ocf队列成功。
• STATE_OCF_UNAVAILABLE，ocf不可用。
• STATE_PARAM_INVALID，ctx为空指针或者ctx内部参数设置不合法。
• STATE_CORE_NOT_EXIST，slot对应core不存在，请求提交失败。
• STATE_MEM_ALLOC_ERR，内存申请失败。

提交失效请求

函数定义

将失效请求提交到ocf队列，异步接口。

请求类型：region部分区间数据在cache中删除。

实现方法

int ocf_invalid(struct req_context *ctx);

参数说明

返回值

• STATE_SUCCESS，请求提交ocf队列成功。
• STATE_OCF_UNAVAILABLE，ocf不可用。
• STATE_PARAM_INVALID，ctx为空指针或者ctx内部参数设置不合法。
• STATE_CORE_NOT_EXIST，slot对应core不存在，请求提交失败。
• STATE_MEM_ALLOC_ERR，内存申请失败。

提交查询请求

函数定义

将查询请求提交到ocf队列，异步接口。

请求类型：查询region指定区间数据在cache是否全命中。

实现方法

int ocf_lookup(struct req_context *cxt);

参数说明

返回值

• STATE_SUCCESS，请求提交ocf队列成功。
• STATE_OCF_UNAVAILABLE，ocf不可用。
• STATE_PARAM_INVALID，ctx为空指针或者ctx内部参数设置不合法。
• STATE_CORE_NOT_EXIST，slot对应core不存在，请求提交失败。
• STATE_MEM_ALLOC_ERR，内存申请失败。

轮询

函数定义

触发已完成请求的回调，接口类型取决于执行回调接口的类型。

实现方法

int ocf_poll(uint32_t io_worker_id, uint32_t max_num);

参数说明

返回值

• STATE_SUCCESS，请求提交ocf队列成功。
• STATE_OCF_UNAVAILABLE，ocf不可用。
• STATE_PARAM_INVALID，io_worker_id值异常。

获取ocf cache/core映射

函数定义

获取ocf cache/core及其映射等信息，同步接口。

实现方法

struct ocf_dump_info *ocf_dump_cache_core_info()；

参数说明

无入参

返回值

• NULL，查询失败。
• 非NULL，返回的结构体指针，结构体中包含查询信息的字符串，表示查询成功。

获取region_id和remap_id映射

函数定义

获取region_id和remap_id的映射，同步接口。

实现方法

struct ocf_dump_info *ocf_dump_region_info()；

参数说明

无入参

返回值

• NULL，查询失败。
• 非NULL，返回的结构体指针，结构体中包含查询信息的字符串，表示查询成功。

获取ocf内部处理IO的各项计数

函数定义

ocf内部处理IO的各项计数，同步接口。

实现方法

struct ocf_dump_info *ocf_dump_cache_stats()；

参数说明

无入参

返回值

• NULL，查询失败。
• 非NULL，返回的结构体指针，结构体中包含查询信息的字符串，表示查询成功。

查询ocf当前状态

函数定义

查询ocf当前状态（用于确认ocf是否可用），同步接口。

实现方法

struct ocf_dump_info *ocf_dump_status()；

参数说明

无入参

返回值

• NULL，查询失败。
• 非NULL，返回的结构体指针，结构体中包含查询信息的字符串，表示查询成功。

释放ocf_dump_info结构体内存

函数定义

释放ocf_dump_info结构体内存，同步接口。

实现方法

void ocf_release_dump_info(struct ocf_dump_info *info)；

参数说明

返回值

无

结构体

struct ocf_config {
  uint64_t cache_capacity;    // 缓存大小，单位Byte，chunk大小整倍数
  uint16_t io_worker_num;     // 外部会提交请求的线程的数量
  uint16_t core_num;          // 分配给ocf线程使用的核数
  uint64_t cache_line_size;   // 当前按8k
  uint64_t chunk_pool_id;     // 用于cache存储数据的chunk层pool
  uint128_t core_mask;        // 表示分配给ocf具体的核id集合
  log_print_func log_print;   // 日志打印函数
};

struct req_context {
  void *req_identifier;   //请求标识，索引到req上下文
  uint32_t io_worker_id; // 索引sq
  uint32_t slot_id;      // 索引ocf core
  uint64_t region_id;    // 用于计算core offset
  uint64_t offset;       // region内偏移，用于计算core offset
  uint64_t len;          // 请求长度
  char* buffer;          // 读写请求使用的buffer
  int (cb)(int32_t ret, voidctx); // 请求完成回调
  char internal[40];       // ocf内部使用，无需设置
};

struct ocf_dump_info {
  char *buf;
  size_t len;
};

错误码

#define STATE_SUCCESS 0
/error code for ocf processing result after request submission/
#define STATE_FAIL -1
#define STATE_MISS -2
#define STATE_CHUNK_TIMEOUT -3
#define STATE_CHUNK_UNAVAILABLE -4
/error code when submitting request/
#define STATE_CORE_EXIST -1000
#define STATE_CORE_NOT_EXIST -1001
#define STATE_CORE_CREATING -1002
#define STATE_PARAM_INVALID -1003
#define STATE_MEM_ALLOC_ERR -1004
#define STATE_TOO_MANY_REGION -1005
#define STATE_OCF_UNAVAILABLE -1006

修订记录