SGL内存格式接口

（SGL相关接口暂时pending，等确定实现后再进行评审）

/* SGL buffers, inner details are not cared about by users */
struct wd_sgl;

/* SGL Memory pool creating parameters */
struct wd_sglpool_setup {
__u32 slice_num;/* Total number of SGEs with buffer slices */
__u16 sgl_num;/* Total number of sgl with entries and buffers */
__u16 align_size;/* SGE data buffer startging address align size */
__u32 buf_size;/* memory size of entry buffer */
struct wd_mm_br br;/* memory from user if don't use WD memory */
};

函数原型	void wd_sglpool_create(struct wd_queue q, struct wd_sglpool_setup *setup);
函数功能	基于用户提供的规格与内存创建SGL池
输入说明	q：Warpdrive算法队列 setup：用户给出的规格与内存
输出说明	setup->slice_num:仅当使用WD默认内存时为输出，即实际创建的slice数目，当数目小于用户要求数量的90%时，创建sglpool将失败。
返回值说明	非NULL：SGL池 NULL：失败
使用说明	在使用WD默认内存创建SGL池时，如果对slice_num数量有严格要求，请配置setup的slice_num比实际需求高15%。在使用外部内存时，要求用户可提供struct wd_mm_ops，即ops可以满足创建池的内存大小要求，且dma map/unmap操作在该内存范围内适用，若属于直接物理地址DMA，则要求该内存范围内物理地址连续。
注意事项	如果用户没有指定内存，那么默认使用wd预留内存进行池的创建。在使用WD默认内存创建池时，struct wd_sglpool_setup中slice_num为输入输出参数。

函数原型	void wd_sglpool_destroy(void *pool);
函数功能	销毁SGL池
输入说明	pool：需要销毁的SGL池。
输出说明	无
返回值说明	无
使用说明	无
注意事项	无

函数原型	struct wd_sgl wd_alloc_sgl(void pool, __u32 size);
函数功能	从Warpdrive SGL内存池中分配SGL缓冲区
输入说明	pool：SGL池 size：SGL buffers的整体size大小
输出说明	无
返回值说明	非NULL：一个SGL链buffer的首个SGL地址 NULL：申请失败
使用说明	支持多线程
注意事项	无

函数原型	void wd_free_sgl(void pool, struct wd_sgl sgl);
函数功能	释放SGL缓冲区到曲速引擎SGL内存池
输入说明	pool：SGL池 sgl：一个SGL链buffer的首个SGL地址
输出说明	无
返回值说明	无
使用说明	支持多线程
注意事项	无

函数原型	void wd_sgl_last_entry(struct wd_sgl sgl);
函数功能	获取SGL最后一个条目的起始地址
输入说明	sgl：一个SGL链
输出说明	无
返回值说明	非NULL：SGL中最后一个条目的起始地址 NULL：无entry在SGL中
使用说明	支持多线程
注意事项	无

函数原型	void wd_sgl_entry(struct wd_sgl sgl, int num);
函数功能	获取SGL中第num个条目的起始地址
输入说明	sgl：一个SGL链 Num：第num个条目，0表示第一个条目
输出说明	无
返回值说明	非NULL：SGL中第num个条目的起始地址 NULL：num超过SGL的范围
使用说明	支持多线程
注意事项	无

函数原型	void wd_sgl_iova_map(struct wd_sgl sgl);
函数功能	获取SGL缓冲区的iova
输入说明	sgl：一个sgl的地址
输出说明	无
返回值说明	非NULL：返回sgl的iova地址 NULL：map失败
使用说明	支持多线程
注意事项	目前为了支持no-iommu与iommu-passthrough场景的接口

函数原型	int wd_sgl_entry_bsize(struct wd_sgl sgl, size_t size);
函数功能	获取SGL的缓冲区大小
输入说明	sgl：一个sgl的地址
输出说明	size：SGL条目所指向的单个缓冲区的大小
返回值说明	0：获取成功其他：获取失败
使用说明	支持多线程
注意事项	维测接口

函数原型	int wd_sgl_bsize(struct wd_sgl sgl, size_t size);
函数功能	获取SGL的总缓冲区大小
输入说明	sgl：一个sgl的地址
输出说明	size：一个SGL所描述的所有缓冲区的总大小
返回值说明	0: success Other: fail
使用说明	支持多线程
注意事项	无

函数原型	void wd_sgl_iova_unmap(void pool, void sgl_iova, struct wd_sgl *sgl);
函数功能	将SGL的I/O虚拟地址与其物理地址解除映射
输入说明	pool：SGL池 sgl_iova：一个sgl的iova地址 sgl：一个sgl的地址
输出说明	无
返回值说明	无
使用说明	支持多线程
注意事项	目前为了支持no-iommu与iommu-passthrough场景的接口，no-iommu模式下无任何操作

函数原型	int wd_get_free_sgl_num(void *pool);
函数功能	获取内存池中空闲的SGL缓冲区的数量
输入说明	pool： SGL池
输出说明	无
返回值说明	空闲SGL缓冲区的数量
使用说明	支持多线程
注意事项	维测接口

函数原型	int wd_alloc_sgl_failures(void *pool);
函数功能	获取内存池分配失败的次数
输入说明	pool：SGL池
输出说明	无
返回值说明	分配失败的次数
使用说明	支持多线程
注意事项	维测接口

父主题： WD数据存储格式与内存接口