---
title: SGL内存格式接口
description: "（SGL相关接口暂时pending，等确定实现后再进行评审）"
url: https://www.hikunpeng.com/document/detail/zh/kunpengboostkithistory/252RC1/accel/kunpengaccel_17_0040.html
sourcePath: /source/zh/kunpengboostkithistory/252RC1/accel/kunpengaccel_17_0040.html
indexId: a945dd9c193911b4be9b5a637ff954ac6f34d8f26a05398437a5b7b5778ca67272
---
# 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：成功 Other：失败 |
| 使用说明 | 支持多线程 |
| 注意事项 | 无 |


| 函数原型 | 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池 |
| 输出说明 | 无 |
| 返回值说明 | 分配失败的次数 |
| 使用说明 | 支持多线程 |
| 注意事项 | 维测接口 |