20. 共享Buffer管理（预留，暂不支持）

【免费下载链接】runtime本项目提供CANN运行时组件和维测功能组件。项目地址: https://gitcode.com/cann/runtime

本章节描述预留的共享 Buffer 管理接口（当前版本暂不支持）。

• aclError aclrtAllocBuf(aclrtMbuf *buf, size_t size)：申请指定大小的共享Buffer。
• aclError aclrtFreeBuf(aclrtMbuf buf)：释放通过aclrtAllocBuf接口申请的共享Buffer。
• aclError aclrtGetBufData(const aclrtMbuf buf, void **dataPtr, size_t *size)：获取共享Buffer的数据区指针和数据区长度，用户可以使用此指针填入数据。
• aclError aclrtSetBufUserData(aclrtMbuf buf, const void *dataPtr, size_t size, size_t offset)：设置共享Buffer的私有数据区数据，从用户内存拷贝到共享Buffer的私有数据区的指定偏移位置，用于设置控制信息作为上下文传递。
• aclError aclrtGetBufUserData(const aclrtMbuf buf, void *dataPtr, size_t size, size_t offset)：获取共享Buffer的私有数据区数据，偏移offset后，拷贝至用户申请的内存区域。
• aclError aclrtGetBufDataLen(aclrtMbuf buf, size_t *len)：获取共享Buffer中有效数据的长度。
• aclError aclrtSetBufDataLen(aclrtMbuf buf, size_t len)：设置共享Buffer中有效数据的长度。
• aclError aclrtCopyBufRef(const aclrtMbuf buf, aclrtMbuf *newBuf)：对共享Buffer数据区的引用拷贝，创建并返回一个新的Mbuf管理结构指向相同的数据区。
• aclError aclrtAppendBufChain(aclrtMbuf headBuf, aclrtMbuf buf)：将共享Buffer添加到Mbuf链表中。
• aclError aclrtGetBufFromChain(aclrtMbuf headBuf, uint32_t index, aclrtMbuf *buf)：从Mbuf链表中获取第index个共享Buffer。
• aclError aclrtGetBufChainNum(aclrtMbuf headBuf, uint32_t *num)：从Mbuf链表中获取共享Buffer的个数。

aclrtAllocBuf

aclError aclrtAllocBuf(aclrtMbuf *buf, size_t size)

功能说明

申请指定大小的共享Buffer。

参数说明

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

aclrtFreeBuf

aclError aclrtFreeBuf(aclrtMbuf buf)

功能说明

释放通过aclrtAllocBuf接口申请的共享Buffer。

参数说明

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

aclrtGetBufData

aclError aclrtGetBufData(const aclrtMbuf buf, void **dataPtr, size_t *size)

功能说明

获取共享Buffer的数据区指针和数据区长度，用户可以使用此指针填入数据。

接口调用顺序：调用aclrtAllocBuf或aclrtCopyBufRef接口申请到共享Buffer后，因此需由用户调用aclrtGetBufData接口获取共享Buffer的内存指针及长度后，再自行向内存中填充有效数据，然后再调用aclrtSetBufDataLen接口设置共享Buffer中有效数据的长度，且长度必须小于aclrtGetBufData获取到的size大小。

参数说明

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

aclrtSetBufUserData

aclError aclrtSetBufUserData(aclrtMbuf buf, const void *dataPtr, size_t size, size_t offset)

功能说明

设置共享Buffer的私有数据区数据，从用户内存拷贝到共享Buffer的私有数据区的指定偏移位置，用于设置控制信息作为上下文传递。当前默认私有数据区大小是96Byte，offset+size必须小于或等于96Byte，否则返回报错。

参数说明

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

aclrtGetBufUserData

aclError aclrtGetBufUserData(const aclrtMbuf buf, void *dataPtr, size_t size, size_t offset)

功能说明

获取共享Buffer的私有数据区数据，偏移offset后，拷贝至用户申请的内存区域。当前默认私有数据区大小是96Byte，offset+size必须小于或等于96Byte，否则返回报错。

参数说明

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

aclrtGetBufDataLen

aclError aclrtGetBufDataLen(aclrtMbuf buf, size_t *len)

功能说明

获取共享Buffer中有效数据的长度。

通过aclrtSetBufDataLen接口设置共享Buffer中有效数据的长度后，可调用本接口获取有效数据的长度，否则，通过本接口获取到的长度为0。

参数说明

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

aclrtSetBufDataLen

aclError aclrtSetBufDataLen(aclrtMbuf buf, size_t len)

功能说明

设置共享Buffer中有效数据的长度。

接口调用顺序：调用aclrtAllocBuf或aclrtCopyBufRef接口申请到共享Buffer后，因此需由用户调用aclrtGetBufData接口获取共享Buffer的内存指针及长度后，再自行向内存中填充有效数据，然后再调用aclrtSetBufDataLen接口设置共享Buffer中有效数据的长度，且长度必须小于aclrtGetBufData获取到的size大小。

参数说明

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

aclrtCopyBufRef

aclError aclrtCopyBufRef(const aclrtMbuf buf, aclrtMbuf *newBuf)

功能说明

对共享Buffer数据区的引用拷贝，创建并返回一个新的Mbuf管理结构指向相同的数据区。

参数说明

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

aclrtAppendBufChain

aclError aclrtAppendBufChain(aclrtMbuf headBuf, aclrtMbuf buf)

功能说明

将共享Buffer添加到Mbuf链表中。共享Buffer链最大支持128个共享Buffer。共享Buffer可通过aclrtAllocBuf或aclrtCopyBufRef接口申请获得。

参数说明

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

aclrtGetBufFromChain

aclError aclrtGetBufFromChain(aclrtMbuf headBuf, uint32_t index, aclrtMbuf *buf)

功能说明

从Mbuf链表中获取第index个共享Buffer。

参数说明

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

aclrtGetBufChainNum

aclError aclrtGetBufChainNum(aclrtMbuf headBuf, uint32_t *num)

功能说明

从Mbuf链表中获取共享Buffer的个数。

参数说明

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

【免费下载链接】runtime本项目提供CANN运行时组件和维测功能组件。项目地址: https://gitcode.com/cann/runtime