DOCA Core
介绍
DOCA Core库只支持beta版。
DOCA Core对象为应用程序开发人员提供了与各种DOCA库交互的统一的接口。DOCA Core API和对象为应用程序提供了一个标准化的流程和构建，同时隐藏了软硬件内部实现细节。DOCA Core旨在保持性能的同时提供适当的抽象。
DOCA Core对于DPU和CPU安装具有相同的API(头文件)，但是如果该CPU没有实现该API，则该API调用可能会返回DOCA_ERROR_NOT_SUPPORTED。但，Windows和Linux的除外，因为DOCA Core在Windows和Linux安装之间确实存在API差异。
DOCA Core向应用程序编写者公开了C语言API，用户必须根据其应用程序所需的DOCA Core组件包含要使用的正确头文件。
DOCA Core可分为以下几个软件模块:
|
DOCA Core模块 |
说明 |
|
General |
l DOCA Core枚举和基本的数据结构 l 头文件：DOCA_error.h、DOCA_types.h |
|
Device操作 |
l 查询设备信息(主机端和DPU)和Device capability(例如，设备的PCIe BDF地址) n 在DPU上 u Get local DPU devices u Get representors list (表示host local devices) n 在host上 u Get local devices u Query device capabilities and library capabilities u Open and use the selected device representor u Relevant entities – DOCA_devinfo, DOCA_devinfo_rep, DOCA_dev, DOCA_dev_rep n 头文件：DOCA_dev.h |
|
内存管理 |
l 处理应用程序使用的优化过的内存池，并支持在DOCA库之间共享资源(同时隐藏与硬件相关的技术) l Data buffer服务(例如，支持SGL) l 将主机内存映射到DPU以便直接访问 l 相关实体：DOCA_buff, doca_mmap, DOCA_buf_inventory, DOCA_buf_array, DOCA_bufpool l 头文件：doc_buf_h, doc_buf_inventory .h, doc_mmap .h, doc_buf_array .h, doc_bufpool .h |
|
处理引擎与任务执行 |
l 支持向DOCA库提交任务并跟踪任务进度(支持轮询模式和事件驱动模式) l 相关实体：doc_ctx, doc_task, doc_event, doc_event_handle_t, doc_pe l 头文件：doc_ctx .h |
|
Sync event |
l 用于同步不同的处理器（例如：DPU和主机） l 头文件： DOCA_dpa_sync_event.h, DOCA_sync_event.h |
前提条件
在DPU target和主机侧支持DOCA Core对象，两者必须满足以下前提条件：
1. DOCA version 2.0.2或更高
2. NVIDIA BlueField软件版本4.0.2或更高
3. NVIDIA BlueField-3固件版本32.37.1000或更高
4. NVIDIA BlueField-2固件版本24.37.1000或更高
架构
以下章节将介绍DOCA Core各个软件模块的架构。
General
所有的Core对象都遵循相同的流程，在之后的快路径中不用再分配，流程如下：
1. 创建对象实例（如：doca_mmap_create）
2. 配置实例（如：doca_mmap_set_memory_range）
3. 启动实例（如：doca_mmap_start）
在实例启动后，可以在数据路径中安全的使用，不用再分配，当实例完成后，必须停止和destroy掉（doca_mmap_stop, doca_mmap_destroy）
Core对象可以被重新配置和重新启动（如：create->configure->start->stop->configure->start），对象是否支持该功能请阅读该对象相关的头文件。
DOCA_error_t
所有DOCA API都会返回类型为DOCA_error_t的状态码。
typedef enum DOCA_error {
DOCA_SUCCESS,
DOCA_ERROR_UNKNOWN,
DOCA_ERROR_NOT_PERMITTED, /**< Operation not permitted */
DOCA_ERROR_IN_USE, /**< Resource already in use */
DOCA_ERROR_NOT_SUPPORTED, /**< Operation not supported */
DOCA_ERROR_AGAIN, /**< Resource temporarily unavailable, try again */
DOCA_ERROR_INVALID_VALUE, /**< Invalid input */
DOCA_ERROR_NO_MEMORY, /**< Memory allocation failure */
DOCA_ERROR_INITIALIZATION, /**< Resource initialization failure */
DOCA_ERROR_TIME_OUT, /**< Timer expired waiting for resource */
DOCA_ERROR_SHUTDOWN, /**< Shut down in process or completed */
DOCA_ERROR_CONNECTION_RESET, /**< Connection reset by peer */
DOCA_ERROR_CONNECTION_ABORTED, /**< Connection aborted */
DOCA_ERROR_CONNECTION_INPROGRESS, /**< Connection in progress */
DOCA_ERROR_NOT_CONNECTED, /**< Not Connected */
DOCA_ERROR_NO_LOCK, /**< Unable to acquire required lock */
DOCA_ERROR_NOT_FOUND, /**< Resource Not Found */
DOCA_ERROR_IO_FAILED, /**< Input/Output Operation Failed */
DOCA_ERROR_BAD_STATE, /**< Bad State */
DOCA_ERROR_UNSUPPORTED_VERSION, /**< Unsupported version */
DOCA_ERROR_OPERATING_SYSTEM, /**< Operating system call failure */
DOCA_ERROR_DRIVER, /**< DOCA Driver call failure */
DOCA_ERROR_UNEXPECTED, /**< An unexpected scenario was detected */
DOCA_ERROR_ALREADY_EXIST, /**< Resource already exist */
DOCA_ERROR_FULL, /**< No more space in resource */
DOCA_ERROR_EMPTY, /**< No entry is available in resource */
DOCA_ERROR_IN_PROGRESS, /**< Operation is in progress */
DOCA_ERROR_TOO_BIG, /**< Requested operation too big to be contained */
} DOCA_error_t;
更多详细信息请参考DOCA_error.h。
通用数据结构和枚举
以下数据结构对于所有的DOCA API都适用。
union DOCA_data {
void *ptr;
uint64_t u64;
};
enum DOCA_access_flags {
DOCA_ACCESS_LOCAL_READ_ONLY = 0,
DOCA_ACCESS_LOCAL_READ_WRITE = (1 << 0),
DOCA_ACCESS_RDMA_READ = (1 << 1),
DOCA_ACCESS_RDMA_WRITE = (1 << 2),
DOCA_ACCESS_RDMA_ATOMIC = (1 << 3),
DOCA_ACCESS_DPU_READ_ONLY = (1 << 4),
DOCA_ACCESS_DPU_READ_WRITE = (1 << 5),
};
enum DOCA_pci_func_type {
DOCA_PCI_FUNC_PF = 0, /* physical function */
DOCA_PCI_FUNC_VF, /* virtual function */
DOCA_PCI_FUNC_SF, /* sub function */
};
更多信息请参考DOCA_types.h。
DOCA Device
Local Device and Representor
先决条件
对于representors模型，BlueField必须工作在DPU模式下。
拓扑结构
DOCA device代表一个由软件或硬件实现的处理单元。DOCA device公开了其属性以便于应用程序选择正确的设备。DOCA Core支持两种类型的设备：
Local device：在本地系统（DPU或host）中公开的真实的设备，可以执行DOCA库的处理任务。
Representor device： local device的代表，local device通常在host上(SF除外)，而representor device总是在DPU端(主机端设备在DPU上的代理)。
上图表示一个DPU（图右侧）连接到一个host（图左侧）。Host有两个PF，PF0和PF1。PF0有两个VF，VF0和VF1。PF1只有一个VF，VF1。通过DOCA SDK API，用户可以获取到这五个设备，这五个设备是host上的local device。
在DPU端，对于每一个host function（PF或VF）都有一个一对一的representor device（例如：hpf0是host device pf0的representor device）。每个SF也有一个一对一的representor device，SF及其representor device都位于DPU中。
如果用户在DPU端查询local device，会获取到两个设备，即：pf0和pf1，它们是以下设备的父设备：
l 7个representor device
n 5个前缀为hpf的representor device，host到DPU的5个箭头指向的设备，即：hpf0、hpf0vf0、hpf0vf1、hpf1、hpf1vf0；
n 2个SF device的representor device，即：pf0sf0、pf1sf0；
l 2个local SF device，即：p0s0和p1s0
也就是说，pf0是hpf0、hpf0vf0、hpf0vf1、p0s0、pf0sf0的父设备，pf1是hpf1、hpf1vf0、p1s0、pf1sf0的父设备。
如上图所示，虚线风格成了两部分，上半部分表示DPU设备p0，下半部分表示DPU设备p1，p0和p1负责创建所有其它local device，host PF（pf0、pf1），host VF（pf0vf0、pf0vf1、pf1vf0），DPU SF（p0s0、p1s0）。所以，p0和p1是所有设备的父设备，也可以访问每个function的representor（通过DOCA_devinfo_rep_list_create）。
Local device和representor device的映射关系
|
host侧的local device |
DPU侧的representor device |
DPU侧的device |
|
pf0 |
hpf0 |
p0 |
|
pf0vf0 |
hpf0vf0 |
|
|
pf0vf1 |
hpf0vf1 |
|
|
pf1 |
hpf1 |
p1 |
|
pf1vf0 |
hpf1vf0 |
使用doca_mmap_export_dpu()选择host侧的local device，使用doca_mmap_create_from_export()选择DPU侧的device。
SF与VF的区别
VF是SR-IOV标准中定义的，VF共享PF的资源，由PF创建和分配。SF（scalable function或sub-function）是Mellanox DPU系列产品提供的一种轻量级的function，具有独立的function和资源。VF和SF都有一个parent function，即PF。SF可以单个进行部署，而VF需要整体一起使能。SF因为没有全部实现PCI配置空间、寄存器和复位，所以比较轻量级。多个SF可以共享MSI-X向量，减少了硬件和中断控制器的中断数量。SF主要用于容器，当创建容器的时候，就可以SF对应的netdevice分配给容器使用。SF可以从DPU以云原生方式部署，这避免了在representor设置中的跨系统同步。换句话说，在将SF热插到host之前，管理员可以完全设置SF、它的representor、QoS、SF所需的参数。
device discovery
为了使用DOCA库和DOCA Core对象，应用程序必须打开DPU或host上的device。如上图所示，通常有多个设备可用。应用程序可以根据device capabilities和DOCA Core API来选择打开哪个设备。流程如下：
1. 获取Device列表；
2. 根据某些capability和属性来选择一个DOCA_devinfo，上图根据PCI地址来选择；
3. 一旦找到符合要求的DOCA_devinfo，就打开DOCA_dev；
4. 在打开了DOCA_dev后，就可以关闭DOCA_devinfo，DOCA_dev可以继续使用；
5. 最后关闭DOCA_dev。
representor device discovery
为了和DOCA 库和DOCA Core对象一起工作，一些应用程序必须打开并使用DPU上的representor device。在打开并使用representor device之前，需要工具来选择representor device。DOCA Core API提供了丰富的Device capability以便应用程序选择正确的Device对（Device及其representor device）。
1. 在DPU端，应用程序获取某个local Device的representor Device列表；
2. 根据某些属性来选择一个DOCA_devinfo_rep，上图根据PCI地址来选择；
3. 一旦找到符合要求的DOCA_devinfo_rep，就打开DOCA_dev_rep；
4. 在打开了DOCA_dev_rep后，就可以关闭DOCA_devinfo_rep，DOCA_dev_rep可以继续使用；
5. 最后关闭DOCA_dev_rep。
需要注意的是，representor device的属性存在缓存，因此当representor device的任何属性动态改变后，需要重新获取representor device列表才能感知新的改动。
DOCA Memory Subsystem
DOCA内存子系统旨在优化性能，同时保持最小的内存占用作为主要设计目标。DOCA内存有如下两个主要组件：
l DOCA_buf：data buffer的描述符，不是实际的data buffer，只是拥有data buffer的metadata；
l doca_mmap：DOCA_buf指向的data buffer pool，应用程序将内存作为单个内存区域提供，并为某些设备提供访问它的权限。
doca_mmap作为data buffer的pool，也有个实体叫DOCA_buf_inventory，作为DOCA_buf的pool。与所有DOCA实体一样，DOCA内存子系统对象是不透明的，只能由DOCA SDK实例化。
下图所示，显示了DOCA内存子系统的各个模块：
在图中，有两个DOCA_buf_inventory。每个DOCA_buf都指向一个memory buffer，而memory buffer又是doca_mmap的一部分，DOCAo_mmap是一段连续的内存，并且被映射给两个dev。
要求和注意事项
l DOCA内存子系统要求使用池，而不是动态分配：
n DOCA_buf_inventory是DOCA_buf的pool
n doca_mmap是data memory的pool
l doca_mmap中的内存可以映射给一个或多个dev；
l dev访问内存有权限限制；
l DOCA_buf不是实际的data buffer，包含的是描述的data buffer相关信息，即：metadata；
l 内存映射和dev的使用（如：mr）对应用程序是隐藏了实现细节的。
doca_mmap
doca_mmap不仅仅是一个数据缓冲区，因为它向应用程序开发人员隐藏了许多细节(例如，RDMA技术，设备处理等)，为软件提供了适当的抽象。doca_mmap是在主机和DPU之间共享内存的最佳方式，这样DPU就可以直接访问主机内存，主机也可以直接访问DPU内存。后续，doca_mmap映射的内存简称mmap。
local mmap
这是doca_mmap的基本类型，它将本地内存映射到本地设备。
1. 应用程序创建doca_mmap；
2. 应用程序使用doc_mmap_set_memrange设置mmap的内存范围；
3. 应用程序添加dev，授予dev访问内存区域的权限；
4. 应用程序可以使用doc_mmap_set_permissions指定设备对该内存的访问权限；
5. 如果mmap仅在本地使用，则必须指定DOCA_ACCESS_LOCAL_*；
6. 如果mmap是在主机上创建，但是要与DPU共享，那么必须指定DOCA_ACCESS_PCI_*；
7. 如果mmap是在DPU上创建，但是要与主机共享，那么必须指定DOCA_ACCESS_PCI_*；
8. 如果mmap与远端RDMA target共享，则必须指定DOCA_ACCESS_RDMA_*；
9. 应用程序启动mmap，此后不能再对mmap做修改；
10. 调用doca_mmap_export_pci和主机或DPU共享mmap，调用doca_mmap_export_rdma和RDMA target共享mmap，成功返回一个blob，如果权限不对，export会失败；
11. 如果与远端RDMA target共享mmap，可以使用套接字在带外交换上一步生成的blob；如与DPU共享，建议使用DOCA Comm Channel。
mmap from export
这用于访问主机内存(从DPU)或远端RDMA target的内存。
1. 应用程序接收来自对端的blob；
2. 应用程序调用doca_mmap_create_from_export导入对端定义的mmap。
现在应用程序可以创建DOCA_buf指向这个导入的mmap来直接访问对端的内存。
注意：DPU可以访问同一台机器上的主机导出的内存；如果内存是RDMA导出的，不管内存位于同一台主机还是远程主机还是远程DPU上，DPU都可以访问。但主机只能访问通过RDMA导出的内存，不管这些内存位于远程主机上还是远程DPU上还是同一机器的DPU上。
doca_buf
doca_buf是可由DPU硬件访问的内存，且可以跨不同的DPU加速器使用。doca_buf可以CPU内存、GPU内存、主机内存甚至RDMA内存，创建后的使用方式都是类似的。doca_buf有一个地址和长度来描述一段内存区域。每个buffer还可以指向区域内的某段内存。于是可以将doca_buf分为三个部分:headroom、dataroom和tailroom。如下图所示：
doca_buf的注意事项
l doca_buf有多种创建方式，一旦创建，表现出的行为都一致；
l doca_buf可以是CPU不访问的内存，例如：RDMA内存；
l doca_buf是线程非安全的；
l doca_buf可以是非连续的内存区域（scatter/gather list）；
l doca_buf不拥有也不管理它所引用的数据,释放buffer不会影响它引用的内存。
Headroom
用户空间，用户可以用来保存一些私有信息，所有DOCA库API都会忽略这部分空间。
Dataroom
保存数据或者结果。
Tailroom
可以自由写入的空间。
Buffer as Source
当doca_buf作为源时，源数据就是dataroom。
Buffer as Destination
当doca_buf作为目的时，数据以追加的方式被写到tailroom，数据长度相应的进行增加。
Scatter/Gather List
要在非连续内存区域上执行操作，可以创建一个缓冲区链表，用单个doc_buf指向链表的头部。要创建一个缓冲区链表，用户必须首先单独分配每个缓冲区，然后将它们链接起来。
l doca_buf_chain_list将第二个链表附加到第一个链表尾部形成一个链表；
l doca_buf_unchain_list将指定元素从链表中摘除；
l 一旦创建了列表，就可以使用doc_buf_get_next_in_list()遍历它。一旦到达最后一个元素就返回NULL。
传递一个链表和传递单个buffer是一样的。支持这个特性的DOCA库可以将一个链表组成的内存区域看做一个连续的内存区域。
当使用一个buffer链表作为源时，收集每个buffer中的数据（在dataroom中）聚合成一段连续的数据再做处理。
当使用一个buffer链表作为目的时，数据会被分散写到buffer的tailroom中直到全部写入为止。
Buffer Use Cases
除非另有说明，否则对缓冲区数据进行的操作不是原子性的。一旦缓冲区作为任务的一部分被传递给库，缓冲区的所有权就会转移到库中，直到任务完成。当使用doca_buf作为某个库(例如，doca_dma)的输入时，在处理完成之前，doca_buf必须保持有效且不可修改。写入正在in-flight缓冲区可能会导致异常行为。同样，从in-flight缓冲区读取数据时也不能保证数据的有效性。
Inventory
inventory负责分配doca_buf。inventory有多种类型。最基本的inventory分配doca_buf时无需申请任何系统内存。其它类型的inventory要求buffer地址不能重叠。
l 所有类型的inventory启动后都零分配；
l 申请一个doca buffer需要一个data source和一个inventory；
n data source定义了数据存放的位置，谁可以访问以及访问的权限；
n data source必须由应用程序创建；
l inventory描述了buffer的申请模式，例如：随机访问或pool、可变大小或固定大小、连续或非连续内存；
l 有些inventory需要在分配缓冲区时提供data source和doca_mmap，有些则需要在创建库存时提供；
l 所有类型的inventory都是线程不安全的。
Inventory type
|
Inventory type |
特点 |
使用场景 |
|
doca_buf_inventory |
多个mmap，灵活的地址，灵活的buffer大小 |
多个大小或mmap |
|
doca_buf_array |
单个mmap，固定buffer大小；用户接收一个指向DOCA buf的数组；在DPA场景下，mmap和buffer size不能被用户配置，只能稍后从DPA设置 |
用于在GPU或DPA上创建DOCA buffer |
|
doca_bufpool |
单个mmap，固定buffer大小，地址不受用户控制 |
当buffer地址不重要时用作具有相同特征的buffer pool |
举例
以下步骤展示了如何将主机mmap导出到DPU以供DOCA用于直接访问主机内存(例如，用于DMA)：
1 在主机上创建mmap；添加单个doca_dev到mmap并导出，以便DPU或RDMA端可以访问；
2 导出到DPU或RDMA端（使用mmap描述符输出参数作为doc_mmap_create_from_export的输入）；
DOCA Execution Model
执行模型是基于数据和应用线程的硬件处理的。DOCA不创建内部线程(操作系统的线程)。工作负载由task和event组成。有些任务用于数据传输。最基本的数据传输就是DMA操作，把数据从一个内存位置移动到另外一个内存位置。其它操作允许接收来自网络的数据包，或者源数据的SHA值并将其写到目的地。
举例来说，一份负责数据传输的工作负载分以下三部：
1. 读源数据；
2. 对被读的数据启动操作（由专用的硬件加速器完成）；
3. 写操作的结果到目的地。
每个这样的操作就被叫做任务（doca_task）。任务描述了应用程序想要提交给DOCA(硬件或DPU)的操作。为此，应用程序需要一种与硬件或DPU通信的方法。这就是doca_pe发挥作用的地方。Process engine(PE)是一个单线程对象，用于将任务排队以卸载到DOCA，并最终接收它们的compeletion状态。
Doca_pe引入了三个主要操作:
1. 提交任务;
2. 检查提交任务的进度或状态;
3. 接收任务完成的通知(以回调的形式)。
一个工作负载可以被分成许多不同的任务，这些任务可以在不同的线程上执行;每个线程由不同的PE表示。每个任务必须与某个context相关联，其中context定义要执行的任务类型。
context可以从DOCA SDK中的一些库中获得。例如，要提交DMA任务，可以从doca_dma.h获取DMA context，而可以使用doca_sha.h获取SHA context。每个这样的context允许提交多种任务类型。
任务被认为是异步的，因为一旦应用程序提交任务，DOCA执行引擎(硬件或DPU)将开始处理它，应用程序可以继续执行其他处理，直到硬件完成。为了跟踪哪个任务已经完成，有两种操作模式:轮询模式和事件驱动模式。
要求和注意事项
l 任务提交/执行/API针对性能(延迟)进行了优化；
l DOCA不管理内部线程(操作系统的线程)，进度是通过轮询或者事件驱动的方式来获取；
l 执行任务基本的对象是doc_task，每个任务都是从特定的DOCA context分配的；
l doca_pe表示一个逻辑上的线程，执行提交给PE的应用程序和任务；
l PE不是线程安全的，每个PE由单个应用程序线程管理；
l 与执行相关的元素(例如，doca_pe, doca_ctx, doca_task)是不透明的，应用程序在使用这些元素之前执行最小的初始化或配置；
l 提交给PE的任务可能会执行失败(即使在提交成功之后)；在某些情况下，可以从错误中恢复；某些情况下，只能重新初始化相关对象；
l PE不保证顺序(例如，按一定顺序提交的任务可能会乱序完成)；保序由应用程序自己负责（如：一个任务完成后再提交另外一个任务）；
l PE可以在轮询模式或事件驱动模式下工作，但不能同时在这两种模式下工作；
l 所有DOCA context都支持轮询模式。
DOCA context
DOCA Context (struct doc_ctx)定义并实现了task/event的处理。Context有多种类型。
l Context至少利用了一种DOCA Device功能或硬件加速能力；
l 对于每种task类型能支持它的有且仅有一种context；
l 一个context包含每种task类型支持的inventory；
l Context包含了每个任务类型执行的所有参数（例如：库存大小、加速处理设备）；
l 每个context都需要一个PE的实例来运行其任务，也就是说context必须和PE关联才能执行任务。
下图显示了DOCA Core实体之间的关系：
1. Doca_task与执行任务的相关doc_ctx相关联(在相关doc_dev的帮助下)；
2. Doca_task初始化后，提交给doca_pe执行；
3. Doca_ctxs关联到doca_pe，一旦doc_task排队到doc_pe，它就由与相关联的doc_ctx执行。
下图描述了context的初始化顺序：
配置阶段
在尝试使用doc_ctx_start()启动DOCAcontext之前，必须先配置它。有些配置是强制性的(例如，提供doc_dev)。
l 配置用于启用某些任务或事件、启用默认禁用的feature以及优化性能；
l 配置使用setter函数提供，有关强制性和可选配置及其相应api的列表，请参阅context相关文档；
l 配置在创建context之后和启动之前完成，context一旦启动，就不能再配置它，除非再次停止它。
执行阶段
一旦context配置完成，就可以使用context执行任务。context通过将工作负载卸载给硬件来执行任务，而任务是异步的，因此软件需要轮询任务，直到它们完成。
应用程序采用以下模式中的一种来轮询任务:
l Poll mode
l Notification-driven mode
在此阶段，context和所有DOCA Core对象通过内存池执行零分配。建议应用程序也使用相同的方法。
State Machine
|
State |
说明 |
|
dile |
没有任务执行； 初始化阶段(就在doca_<T>_create(ctx)之后):所有配置api都有效； 重新配置(从stop状态转换过来):部分配置api有效； |
|
starting |
对context是强制性的； |
|
Running |
允许申请和提交任务，且只有此状态允许； 所有配置api被禁止； |
|
Stopping |
任务停止前的准备； 清楚所有未完成的任务； |
下图描述了DOCA context状态的转换：
Internal error
DOCA Context在任何时候都可能遇到一些内部错误。如果状态正处于starting或running状态，则可能导致状态转换到stopping；
停止后，状态可能变为idle状态。但是，如果存在配置问题或错误事件阻止正确转换到starting或running，doc_ctx_start()可能会失败。
DOCA task
任务是可卸载到硬件的(功能或处理)工作负载单元。大多数任务使用NVIDIA BlueField和NVIDIA ConnectX硬件来加速处理任务定义的工作负载。任务是异步的(例如，通过非阻塞doca_task_submit() API提交处理的任务)。
任务完成后，在context中执行预设的completion callback。completion callback是任务的基本属性，类似于用户数据。大多数任务都是由NVIDIA设备硬件执行或加速的IO操作。
Task Properties
任务熟悉分通用属性和特定属性。由于任务的结构是不透明的(即，它的内容不向用户公开)，所以对任务属性的访问由set/get api提供。
以下是通用任务属性:
l Setting completion callback-成功和失败是两个单独的callback；
l Getting/setting user data-用于completion callback；
l Getting task status-在失败完成时获取错误代码。
对于每个任务，只有一个所有者，就是context对象，可以通过doc_task_get_ctx () API来获取通用context对象。
以下是通用的任务api:
l 从CTX(内部/虚拟)inventory中分配和释放；
l 通过setter(或init API)进行配置；
l 提交任务(即，doca_task_submit(task))；
l 完成后，有一组getter来访问任务执行的结果。
Task Lifecycle
每个DOCA任务对象的生命周期:
l DOCA context进入running状态即开始，一旦进入运行状态，应用程序就可以通过调用doc_ <CTX名称>_task_<任务名称>_alloc_init(CTX，…)从CTX获得任务；
l DOCA context进入stopping状态时结束，一旦相关的DOCA context离开running状态，应用程序就不能再分配任务；
从应用程序的角度来看，DOCA context提供了一个虚拟的任务清单。
DOCA Progress Engine
Progress engine(PE)支持在单线程执行环境中异步处理不同类型的多个任务和事件。它是所有基于context的DOCA库的事件循环，其中I/O completion是最常见的事件类型。
PE被设计为线程不安全的(即，它一次只能在一个线程中使用)，但单个操作系统线程可以使用多个PE。用户可以通过将不同的context添加到不同的PE中，并相应地调整每个PE的轮询频率，从而为不同的context分配不同的优先级。另外一种角度看，PE是一个计划执行的工作负载队列。
没有专门的api来添加或在PE上调度工作负载，但可以通过以下方式添加工作负载:
l 向PE添加DOCA context；
l 注册一个DOCA event到probe，在主动probe时执行相关的处理程序。
PE负责调度工作负载(即选择下一个要执行的工作负载)。工作负载执行的顺序与任务提交顺序、事件注册顺序或关联context的顺序无关。多个任务的completion callback可能以不同于任务提交的顺序执行。
PE的初始化流程如下图所示:
在PE被创建并关联到context之后，它可以开始处理提交给context的任务。请参阅context相关文档以查找详细信息，例如可以使用context提交哪些任务。
注意：PE可以关联到多个context。这些context可以是相同类型的，也可以是不同类型的。这允许将不同的任务类型提交到相同的PE，并等待它们从相同的位置/线程完成。
初始化PE后，应用程序可以使用以下模式之一定义事件循环:
l Poll mode
l Notification-driven mode
PE as Event Loop Mode of Operation
任务和事件的所有completion handler都在doca_pe_progress()的context中执行。doca_pe_progress()会循环执行的每个工作负载:
运行选定的工作负载单元。以下情况:
l 任务完成后，执行相关处理程序并中断循环并返回状态；
l 主动探测事件，执行相关处理程序，打破循环并返回状态；
l 后续任务处理完成，打破循环并返回状态。否则，循环结束并返回状态no progress。
Polling mode
在这种模式下，应用程序提交一个任务，然后执行忙等待，以确定任务何时完成。执行顺序如下图所示：
1. 应用程序提交所有任务(一个或多个)并跟踪任务完成的数量，以了解是否完成了所有任务；
2. 应用程序通过不断轮询doc_pe_progress()等待任务完成；
3. 如果doca_pe_progress()返回1，则表示某些任务或事件处理完成；
4. 每次任务或事件处理完成时，都会相应地执行其预设的回调函数；
5. 如果任务执行出错，则执行错误回调函数。
6. 应用程序可以向完成回调函数中添加代码，以跟踪已完成和待处理工作负载的数量。在这种模式下，应用程序总是占用CPU，即使它什么都不做(忙等)。
阻塞模式- Notification Driven
在这种模式下，应用程序提交任务，然后等待接收通知，最后再查询状态。执行顺序如下:
1. 应用程序从doca_pe中获得一个通知句柄，该句柄是一个Linux文件描述符，用于通知应用程序某些工作已经完成；
2. 应用程序用doc_pe_request_notification()告知PE为事件通知模式，之后不允许调用doc_pe_progress()；
3. 应用程序提交任务；
4. 应用程序等待在pe-fd上接收通知(例如，Linux epoll/select)；
5. 应用程序清除接收到的通知，通知PE已接收到信号，并允许PE执行通知处理；
6. 应用程序尝试通过(多次)调用doca_pe_progress()来处理接收到的通知；
请注意：不能保证对doca_pe_progress()的调用将执行任何任务完成/事件处理程序，但是PE可以继续操作。
7. 应用程序处理任务完成或事件处理程序引起的内部状态更改；
8. 重复步骤2-7，直到所有任务完成，所有预期事件都得到处理。
Progress Engine vs Epoll
Linux中的epoll机制和DOCA PE处理在事件驱动架构中的高并发性。这两个系统在等待事件或任务完成时都能有效地管理资源。
DOCA Event
要注册一个事件，用户必须调用doca_<event_type>_reg(pe，…)函数，事件处理程序必须与PE关联。注册事件后，将由doc_pe_progress()函数定期检查该事件，该函数与PE在相同的执行context中运行。如果满足事件条件，则调用处理程序函数。事件不是线程安全的，只能由它们绑定的PE访问。
Error Handling
在一个任务被成功提交后，后续对doca_pe_progress()的调用可能会失败。一旦任务失败，上下文可能会转换到stopping状态，在这种状态下，应用程序必须在销毁或重新启动上下文之前执行完所有in-flight的任务。
下图显示了应用程序如何处理来自doca_pe_progress()的错误:
1. 应用程序轮询doca_pe_progress;
2. 可能发生下列情况:
l 任务失败，调用fail completion callback;
n 由错误的参数或其他致命错误引起;
n 处理程序释放任务和所有相关资源;
l context转换到stopping状态，并调用context state changed handler;
n 由任务失败或其他致命错误引起；
n 在这种状态下，所有in-flight任务都肯定会失败；
n 释放非in-flight的任务；
l context转换到idle状态，并调用context state changed handler;
n 遇到错误并且context没有任何必须由应用程序释放的资源；
n 应用程序可通过再次调用start来恢复context，或者销毁context并退出应用程序。
DOCA Graph Execution
DOCA Graph可以以特定的顺序和依赖关系运行一组操作(任务、用户回调)。DOCA Graph运行在DOCA PE上。DOCA Graph创建的图形实例通过doc_graph_instance_submit提交给PE。
Nodes
DOCA Graph由context、user、sub-graph nodes组成，这些节点可以位于网络中的位置如下：
l 根节点：根节点没有父节点，图可以有一个或多个根节点。当提交图形实例时，所有根节点开始运行；
l 边缘节点：没有子节点的节点，叶子节点；当所有边缘节点完成时，图实例就执行完成；
l 中间节点：有父节点和子节点的节点。
Context Node
Context node运行特定的任务并使用特点的DOCA context(doca_ctx)，context必须在图启动之前关联到PE。任务的生命周期必须大于或等于图实例的生命周期。
User Node
User node运行用户的回调函数，以便在图实例运行期间执行某些操作(例如，调整下一个节点任务数据，比较结果等)。
Sub-graph Node
sub-graph node运行着一个graph的实例。
Using DOCA Graph
1. 使用doc_graph_create创建图；
2. 创建图形节点(例如，doca_graph_node_create_from_ctx)；
3. 使用doc_graph_add_dependency定义依赖项；
l 注意：DOCA graph不支持循环依赖(例如，A => B => A)；
4. 使用doca_graph_start启动图；
5. 使用doc_graph_instance_create创建图形实例；
6. 设置节点数据(例如，doca_graph_instance_set_ctx_node_data)；
7. 使用doc_graph_instance_submit将图实例提交给PE；
8. 调用doca_pe_progress，直到图形回调被调用；
l 进度引擎可以同时运行图形实例和独立的任务。
DOCA Graph Limitations
l 不支持循环依赖；
l 必须至少包含一个context node。
Alternative Data Path
除了DOCA PE将数据路径从CPU卸载到硬件外，另外一些库还支持备选数据路径，可以卸载DPA或GPU。
注意事项:
l 并非所有上下文都支持备选数据路径；
l 配置阶段总是在CPU上完成；
l 数据路径操作总是卸载到硬件上，卸载的对象可以是CPU/DPA/GPU；
l 默认数据路径模式是CPU；
l 每种模式都会引入一组不同的API，以在执行路径中使用；所使用的API对于特定的context实例是互斥的。
DPA
用户必须首先检查DPA上的数据路径是否支持。
要将数据路径模式设置为DPA，需要获取一个DOCA DPA实例，然后使用doc_ctx_set_datapath_on_dpa () 。
使用这种模式启动context之后，就可以使用相关的API获取DPA句柄(例如，doc_rdma_get_dpa_handle())。这个句柄可以用来访问DPA代码中的DPA数据路径API。
GPU
用户必须首先检查是否支持GPU上的数据路径。
如果需要将数据路径模式设置为GPU，需要获取一个DOCA GPU实例，然后使用doc_ctx_set_datapath_on_gpu ()。
context以这种模式启动之后，可以使用相关的API获得GPU句柄(例如，doca_eth_rxq_get_gpu_handle())。这个句柄可以用来访问GPU代码中的GPU数据路径API。
Task and Event批处理
DOCA批处理可以将多个DOCA任务或相同类型的DOCA事件组成一组并将其作为单个单元来处理。批处理的completion需要等待所有项目的completion执行完成才会执行。
批处理的completion以批处理中所有项目的completion为基础，并作为单个completion进行处理。这允许在单个API调用中进行多个DOCA任务初始化/提交和多个DOCA任务/事件completion处理。
Object Life Cycle
大多数DOCA Core对象都有着相同的处理模型:
1. 该对象由DOCA分配，因此对应用程序来说是不透明的(例如，doca_buf_inventory_create, doca_mmap_create)；
2. 应用程序初始化对象并设置所需的属性(例如，doca_mmap_set_memrange)；
3. 对象已启动，不允许更改配置或属性(例如，doca_buf_inventory_start, doca_mmap_start)；
4. 对象被使用；对象被停止和删除(例如，doca_buf_inventory_stop→doca_buf_inventory_destroy, doca_mmap_stop→doca_mmap_destroy)。
下面的过程描述了两台机器(远程机器或主机-DPU)之间的mmap导出机制:
1. Machine1分配内存；
2. Machine1创建mmap；
3. mmap导出到Machine2并ping住内存；
4. Machine2创建导入的mmap，并hold对Machine1内存的引用；
5. Machine2可以使用导入的mmap来分配buffer；
6. Machine2销毁导入的mmap；
7. Machine1销毁导出的mmap；
8. 销毁释放内存。
RDMA bridge
DOCA Core库提供了应用程序使用的模块，同时抽象了依赖于RDMA驱动程序的许多细节。这减少了复杂性，增加了灵活性，特别是对于已经基于rdma-core的应用程序。RDMA bridge允许DOCA SDK和RDMA -core之间的互相转换，可以将基于DOCA的对象转换为基于RDMA -core的对象。
要求和注意事项
对于已经使用rdma-core的应用程序，DOCA Core库可以方便其移植或K对其进行扩展。Bridge允许将DOCA Core对象转换为等价的rdma-core对象。
DOCA Core对象到rdma-core对象的映射
