OpenVX框架分析：用户内核
定义用户内核，这是一种用新视觉功能扩展OpenVX的方法。 用户内核可以由OpenVX加载，并作为节点或即时函数（如果客户端提供接口）包含在图形中。用户内核通常将在与高级操作系统/CPU兼容的目标上加载和执行，而不是在远程处理器或其他加速器上。
图 13.用户内核安装的调用顺序
图 14.使用用户内核进行图形验证和释放的调用序列
图 15.使用用户内核执行图形的调用序列
在第一次图形验证期间，实现将执行以下操作序列：
1）初始化本地数据节点属性
①如果VX_KERNEL_LOCAL_DATA_SIZE==0，则将VX_NODE_LOCAL_ATA_SIZE设置为0，并将VX_NODE_LOCAL_DATA\uPTR设置为NULL。
②如果VX_KERNEL_LOCAL_DATA_SIZE！=0，将VX_NODE_LOCAL_DATA_SIZE设置为VX_KERNEL_LOCAL_DATA\uSIZE，并将VX_NODE_LOCAL_DATA _PTR设置为VX_ KERNEL-LOCAL_DATA_ IZE字节的缓冲区的地址。
2）调用vx_kernel_validate_f回调。
3）调用vx_kernel_initialize_f回调（如果不是NULL）：
①如果VX_KERNEL_LOCAL_DATA_SIZE==0，则允许回调设置VX_NODE_LOCAL_ATA_SIZE和VX_NODE-LOCAL_DATA_PTR。
②如果VX_KERNEL_LOCAL_DATA_SIZE！=0，则回调设置VX_NODE_LOCAL_DATA_SIZE或VX_NODE-LOCAL_DATA_PTR属性的任何尝试都将生成错误。
4）提供应用程序请求的缓冲区（可选）
如果VX_KERNEL_LOCAL_DATA_SIZE==0且VX_NODE_LOCAL_DATA _SIZE！=0，并且VX_NODE_LOCAL_DATA_PTR==NULL，则该实现将VX_NODE-LOCAL_DATA-PTR设置为VX_NODE_NOCAL_DATA_SIZE字节的缓冲区的地址。
在节点销毁时，实现将执行以下操作序列：
1）调用vx_kernel_deinitialize_f回调（如果不是NULL）：如果vx_NODE_LOCAL_DATA_PTR是由实现较早设置的，则回调设置vx_NODE-LOCAL_DATA-PTR属性的任何尝试都将生成错误。
2）如果VX_NODE_LOCAL_DATA_PTR是由实现提前设置的，则在VX_kernel_deinitialize_f回调完成后，应用程序不得再使用指向内存。
如果在最后一次节点验证后发生以下任何更改，则用户节点需要重新验证：
1）VX_NODE_BORDER节点属性已修改。
2）至少有一个节点参数被具有不同元数据的数据对象替换，或者被可选参数的0引用替换，或者由于可选而被设置为以前未设置的数据对象。
节点重新验证可以由应用程序，通过调用将执行完整图形验证的vxVerifyGraph明确触发。否则，它将在下一次图形执行时自动触发。
在用户节点重新验证期间，将发生以下操作序列：
1）调用vx_kernel_deinitialize_f回调（如果不是NULL）：如果vx_NODE_LOCAL_DATA_PTR是由OpenVX实现较早设置的，则回调设置vx_NODE-LOCAL_DATA-PTR属性的任何尝试都将产生错误。
2）如果需要，重新初始化本地数据节点属性如果VX_KERNEL_local_data_SIZE==0：
①将VX_NODE_LOCAL_DATA_PTR设置为NULL。
②将VX_NODE_LOCAL_DATA_SIZE设置为0。
3）调用vx_kernel_validate_f回调。
4）调用vx_kernel_initialize_f回调（如果不是NULL）：
①如果VX_KERNEL_LOCAL_DATA_SIZE==0，则允许回调设置VX_NODE_LOCAL_ATA_SIZE和VX_NODE-LOCAL_DATA_PTR。
②如果VX_KERNEL_LOCAL_DATA_SIZE为！=0，则回调设置VX_NODE_LOCAL_DATA_SIZE或VX_NODE-LOCAL_DATA_PTR属性的任何尝试都将生成错误。
5）提供应用程序请求的缓冲区（可选）
如果VX_KERNEL_LOCAL_DATA_SIZE==0且VX_NODE_LOCAL_DATA _SIZE！=0，并且VX_NODE_LOCAL_DATA_PTR==NULL，则OpenVX实现将VX_NODE-LOCAL_DATA-PTR设置为VX_NODE_NOCAL_DATA_SIZE字节的缓冲区的地址。
当OpenVX实现设置VX_NODE_LOCAL_DATA_PTR时，缓冲区内的数据在内核执行之间不会持久存在。
类型定义
vx_kernel_deinitialize_f
vx_kernel_f
vx_kernel_image_valid_rectangle_f
vx_kernel_initialize_f
vx_kernel_validate_f
vx_meta_format
vx_publish_kernels_f
vx_unpublish_kernels_f
枚举
vx_meta_valid_rect_attribute_e
功能
vxAddParameterToKernel
vxAddUserKernel
vxAllocateUserKernelId
vxAllocateUserKernelLibraryId
vxFinalizeKernel
vxLoadKernels
vxRemoveKernel
vxSetKernelAttribute
vxSetMetaFormatAttribute
vxQueryMetaFormatAttribute
vxSetMetaFormatFromReference
vxUnloadKernels
vxRegisterKernelLibrary
7.6.1. 类型定义
vx_kernel_deinitialize_f
指向内核去初始化程序的指针。如果主机代码要求在节点垃圾收集期间调用，以取消初始化数据，则在不为NULL时调用此函数。 typedef vx_status (*vx_kernel_deinitialize_f)( vx_node node, const vx_reference *parameters, vx_uint32 num); 参数 [in] node - 包含此内核的节点的句柄。 [in] parameters - 参数引用的数组。 [in] num - 参数的数量。vx_kernel_f
指向主机端内核的指针。 typedef vx_status (*vx_kernel_f)( vx_node node, const vx_reference *parameters, vx_uint32 num); 参数 [in] node - 包含此内核的节点的句柄。 [in] parameters - 参数引用的数组。 [in] num - 参数的数量。vx_kernel_image_valid_rectangle_f
用户定义的回调函数，用于设置输出图像的有效矩形。 typedef vx_status (*vx_kernel_image_valid_rectangle_f)( vx_node node, vx_uint32 index, const vx_rectangle_t* const input_valid[], vx_rectangle_t* const output_valid[]); VX_meta_format对象中的VX_VALID_RECT_CALLBACK属性，应在用户节点的输出验证器期间设置为所需的回调。回调不得调用vxGetValidRegionImage或 vxSetImageValidRectangle。相反，所有输入图像的有效矩形的阵列被提供给回调，以计算输出有效矩形。用户节点的输出可以是金字塔，或者仅仅是图像。如果它只是一个图像，则与该输出相关联的输出数组，只有一个元素。如果输出是金字塔，则阵列大小等于金字塔级别的数量。传递给回调的数组内存分配由框架管理，应用程序不得分配或解除分配这些指针。 如果以下情况之一为真，则回调函数vx_kernel_image_valid_rectangle_f的行为是实现定义的： 用户节点的输入自变量之一是金字塔或图像阵列。 用户节点的输入或输出参数都是金字塔数组。 参数 [inout] node - 正在验证的节点的句柄。 [in] index - 应为其设置有效区域的输出参数的索引。 [in] input_valid - 指向输入图像或包含在图像容器（例如金字塔）中，图像的有效区域阵列的指针。提供顺序与内核声明的参数列表相同。 [out] output_valid - 应在图形处理后为输出图像或图像容器（例如金字塔）设置的有效区域阵列。阵列的长度应等于图像容器的大小（例如，金字塔中的级别数）。对于简单的输出图像，阵列大小总是1。每个矩形提供一个图像的有效区域。阵列存储器分配由框架管理。 返回：描述参数验证状态的错误代码。vx_kernel_initialize_f
指向内核初始值设定项的指针。如果主机代码要求在所有参数都经过验证后调用以初始化数据，则在不为NULL时调用此函数。 typedef vx_status (*vx_kernel_initialize_f)( vx_node node, const vx_reference *parameters, vx_uint32 num); 参数 [in] node - 包含此内核的节点的句柄。 [in] parameters - 参数引用的数组。 [in] num - 参数的数量。vx_kernel_validate_f
用户自定义内核节点参数验证函数。该函数只需要填写元数据结构。 typedef vx_status (*vx_kernel_validate_f)( vx_node node, const vx_reference parameters[], vx_uint32 num, vx_meta_format metas[]); 注意 对于整组参数，此函数调用一次。 参数 [in] node - 正在验证的节点的句柄。 [in] parameters - 要验证的参数数组。 [in] num - 要验证的参数数。 [in] metas - 指向系统保存的结构引用的预分配数组的指针。系统仅为输出参数预分配多个vx_meta_format结构，这些结构由与参数相同的索引索引。验证函数填写正确的类型、格式和维度，供系统用于创建内存或对照现有内存进行检查。 返回：描述参数验证状态的错误代码。vx_meta_format
输出验证函数使用此对象，来指定预期输出数据对象的元数据。 typedef struct _vx_meta_format *vx_meta_format;注意
当用户节点的实际输出对象是虚拟时，通过vx_meta_format对象提供的信息，允许OpenVX框架在对象创建时，应用程序未指定元数据时，自动创建数据对象。
vx_publish_kernels_f
由vxLoadKernels加载和由vxUnloadKernels卸载的模块，vxPublishKernels输入功能的类型。 typedef vx_status (*vx_publish_kernels_f)(vx_context context); 参数 [in] context - 必须添加对上下文内核的引用。vx_unpublish_kernels_f
由vxLoadKernels加载和由vxUnloadKernels卸载的，vxUnpublishKernels条目功能的类型。 typedef vx_status (*vx_unpublish_kernels_f)(vx_context context); 参数 [in] context - 添加了对上下文内核的引用。7.6.2. 枚举
vx_meta_valid_rect_attribute_e
元有效矩形属性。 enum vx_meta_valid_rect_attribute_e { VX_VALID_RECT_CALLBACK = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_META_FORMAT) + 0x1, }; 枚举 数 VX_VALID_RECT_CALLBACK- 输出参数验证期间的有效矩形回调。 .7.6.3. 函数
vxAddParameterToKernel
允许用户设置自定义内核的签名。 vx_status vxAddParameterToKernel( vx_kernel kernel, vx_uint32 index, vx_enum dir, vx_enum data_type, vx_enum state); 参数 [in] kernel - 对添加vxAddUserKernel的内核的引用。 [in] index - 要添加的参数的索引。 [in] dir - 参数的方向。这必须是VX_INPUT或VX_OUTPUT。 [in] data_type - 参数的类型。这必须是vx_type_e中的一个值。 [in] state - 参数的状态（必需或不需要）。这必须是vx_parameter_state_e中的值。 返回：一个vx_status_e枚举值。 返回值 VX_SUCCESS- 参数在内核上设置成功，任何其他值表示失败。 VX_ERROR_INVALID_REFERENCE- 内核不是有效的vx_kernel引用。 VX_ERROR_INVALID_PARAMETERS- 如果该参数由于任何原因无效。 前提： vxAddUserKernelvxAddUser内核
允许用户在运行时，将自定义内核添加到上下文中。 vx_kernel vxAddUserKernel( vx_context context, const vx_char name[VX_MAX_KERNEL_NAME], vx_enum enumeration, vx_kernel_f func_ptr, vx_uint32 numParams, vx_kernel_validate_f validate, vx_kernel_initialize_f init, vx_kernel_deinitialize_f deinit); 参数 [in] context - 必须添加内核的上下文引用。 [in] name - 用于匹配内核的字符串。 [in] enumeration - 客户端要使用的内核的枚举值。 [in] func_ptr - 要调用的进程本地函数指针。 [in] numParams - 此内核的参数数。 [in] validate - 指向vx_kernel_validate_f的指针，用于验证此内核的参数。 [in] init - 内核初始化函数。 [in] deinit - 内核取消初始化函数。 返回：vx_kernel引用。应使用vxGetStatus检查，阻止成功创建的任何可能错误。vxAllocateUserKernelId
将用户定义的内核枚举分配并注册到上下文中。分配的枚举来自为0的动态分配保留的4096个枚举的可用池。 vx_status vxAllocateUserKernelId( vx_context context, vx_enum* pKernelEnumId); 参数 [in] context - 对实现上下文的引用。 [out] pKernelEnumId - 返回用户定义内核的vx_enum的指针。 返回值 VX_SUCCESS- 没有错误，任何其他值都表示失败。 VX_ERROR_INVALID_REFERENCE- 如果上下文不是有效的VX_context引用。 VX_ERROR_NO_RESOURCES- 枚举已用尽。vxAllocateUserKernelLibraryId
将用户定义的内核库ID分配并注册到上下文。 vx_status vxAllocateUserKernelLibraryId( vx_context context, vx_enum* pLibraryId); 分配的库ID来自为动态分配保留的可用库ID池（1..255）。用户内核库开发人员可以使用返回的libraryId，在头文件中指定单个内核枚举ID，如下所示： #define MY_KERNEL_ID1(libraryId) (VX_KERNEL_BASE(VX_ID_USER,libraryId) + 0); #define MY_KERNEL_ID2(libraryId) (VX_KERNEL_BASE(VX_ID_USER,libraryId) + 1); #define MY_KERNEL_ID3(libraryId) (VX_KERNEL_BASE(VX_ID_USER,libraryId) + 2); 参数 [in] context - 对实现上下文的引用。 [out] pLibraryId - 指向用户内核库Id的vx_enum的指针。 返回值 VX_SUCCESS- 没有错误，任何其他值都表示失败。 VX_ERROR_NO_RESOURCES- 枚举已用尽。vxFinalize内核
在将所有参数添加到内核中，并且内核准备好使用后调用此API。注意，在调用vxFinalizeKernel之后，对vxAddUserKernel创建的内核的引用仍然有效。如果出现错误，则OpenVX的客户端无法使用内核。通常，这是由于请求的参数数量与给定的参数数量不匹配造成的。 vx_status vxFinalizeKernel( vx_kernel kernel); 参数 [in] kernel - 对vxAddUserKernel中加载的内核的引用。 返回：vx_status_e枚举。 返回值 VX_SUCCESS- 没有错误，任何其他值都表示失败。 VX_ERROR_INVALID_REFERENCE- 内核不是有效的VX_kernel引用。 前提条件：vxAddUserKernel和vxAddParameterToKernelvxLoad内核
将一个称为模块的内核库加载到上下文中。 vx_status vxLoadKernels( vx_context context, const vx_char* module); 模块必须是一个动态库，按照惯例，具有两个导出的函数，分别命名为vxPublishKernels和vxUnpublishKernels。 vxPublishKernels的类型必须为vx_publish_kernels_f，并且必须通过为每个新内核调用vxAddUserKernel将内核添加到上下文中。vxPublishKernels由vxLoadKernels调用。 vxUnpublishKernels的类型必须为vx_unpublish_kernels_f，并且必须通过为vxPublishKernels添加的每个内核调用vxRemoveKernel来从上下文中删除内核。vxUnpublishKernels由vxUnloadKernels调用。 注意 当对加载的内核的所有引用都被释放时，模块可以被自动卸载。 参数 [in] context - context-内核必须添加到上下文引用。 [in] module - 要加载的模块的简称。在有特定模块命名约定的系统上，传递的名称应忽略这些约定。例如：libxyz.so应该作为xyz传递，并且实现将执行平台所需的正确操作。 注意 此 API 使用系统预定义的模块路径。 返回：vx_status_e枚举。 返回值 VX_SUCCESS- 没有错误，任何其他值都表示失败。 VX_ERROR_INVALID_REFERENCE- 上下文不是有效的VX_context引用。 VX_ERROR_INVALID_PARAMETERS- 如果任何其他参数不正确。 参考：vxRegisterKernelLibrary、vxGetKernelByNamevxRemove内核
从其上下文中删除自定义内核并释放它。 vx_status vxRemoveKernel( vx_kernel kernel); 参数 [in] kernel - 对要删除的内核的引用。从vxAddUserKernel返回。 注意 不能删除基础标准中列举的任何内核；只能删除通过vxAddUserKernel添加的内核。 返回：vx_status_e枚举。该函数将对内核创建时提供的内存资源的完全控制权，返回给应用程序。 返回值 VX_SUCCESS- 没有错误，任何其他值都表示失败。 VX_ERROR_INVALID_REFERENCE- 内核不是有效的VX_kernel引用。 VX_ERROR_INVALID_PARAMETERS- 如果传入了基本内核。 VX_FAILURE- 如果应用程序尚未释放对内核对象的所有引用，或者如果应用程序未释放对使用此内核的节点的所有引用，或者如果应用软件未释放对具有使用此内核节点的图的所有引用。vxSetKernelAttribute
设置内核属性。 vx_status vxSetKernelAttribute( vx_kernel kernel, vx_enum attribute, const void* ptr, vx_size size); 参数 [in] kernel - 对内核的引用。 [in] attribute - 属性的枚举。参考vx_kernel_attribute_e。 [in] ptr - 向读取属性的位置的指针。 [in] size - ptr指示的数据区域的大小（以字节为单位）。 注意 将内核传递给vxFinalizeKernel后，不能更改任何属性。 返回：vx_status_e枚举。 返回值 VX_SUCCESS- 没有错误，任何其他值都表示失败。 VX_ERROR_INVALID_REFERENCE- 内核不是有效的VX_kernel引用。 VX_ERROR_NOT_SUPPORTED- 如果属性不可设置。vxSetMetaFormat属性
此功能允许用户在内核输出验证器中，设置vx_meta_format对象的属性。 vx_status vxSetMetaFormatAttribute( vx_meta_format meta, vx_enum attribute, const void* ptr, vx_size size); vx_meta_format对象包含两种类型的信息：数据对象元数据和定义图像的有效区域，如何更改的一些特定信息。 可以设置的元数据属性，列在vxQueryMetaFormatAttribute中。 参数 [in] meta - 对要设置vx_meta_format结构的引用。 [in] attribute - 使用定义此对象元数据的数据对象属性子集，或vx_meta_format中的属性。 [in] ptr - 要在元格式对象上设置的值的输入指针。 [in] size - ptr指向的对象的大小（以字节为单位）。 返回：vx_status_e枚举。 返回值 VX_SUCCESS- 设置了属性，任何其他值都表示失败。 VX_ERROR_INVALID_REFERENCE- meta不是有效的VX_meta_format引用。 VX_ERROR_INVALID_PARAMETERS- 所需类型的大小不正确。 VX_ERROR_NOT_SUPPORTED- 元格式对象不支持对象属性。 VX_ERROR_INVALID_TYPE- 属性类型与已知的元格式类型不匹配。vxQueryMetaFormatAttribute
此函数允许用户在内核参数中，查询vx_meta_format对象的属性。 vx_status vxQueryMetaFormatAttribute( vx_meta_format meta, vx_enum attribute, void* ptr, vx_size size); vx_meta_format对象包含两种类型的信息：数据对象元数据和定义图像的有效区域，如何更改的一些特定信息。 可以查询的元数据属性由该列表标识：- vx_image：VX_IMAGE_FORMAT,VX_IMAGE_HEIGHT，VX_IMAGE_WIDTH
- vx_array：VX_ARRAY_CAPACITY，VX_ARRAY_ITEMTYPE
- vx_pyramid：VX_PYRAMID_FORMAT，VX_PYRAMID_HEIGHT，VX_PYRAMID_WIDTH，VX_PYRAMID_LEVELS，VX_PYRAMID_SCALE
- vx_scalar：VX_SCALAR_TYPE
- vx_matrix：VX_MATRIX_TYPE，VX_MATRIX_ROWS，VX_MATRIX_COLUMNS
- vx_distribution：VX_DISTRIBUTION_BINS，VX_DISTRIBUTION_OFFSET，VX_DISTRIBUTION_RANGE
- vx_remap：VX_REMAP_SOURCE_WIDTH，VX_REMAP_SOURCE_HEIGHT，VX_REMAP_DESTINATION_WIDTH，VX_REMAP_DESTINATION_HEIGHT
- vx_lut：VX_LUT_TYPE，VX_LUT_COUNT
- vx_threshold：VX_THRESHOLD_TYPE，VX_THRESHOLD_INPUT_FORMAT，VX_THRESHOLD_INPUT_FORMAT
- vx_object_array：VX_OBJECT_ARRAY_NUMITEMS，VX_OBJECT_ARRAY_ITEMTYPE
- vx_tensor：VX_TENSOR_NUMBER_OF_DIMS，VX_TENSOR_DIMS，VX_TENSOR_DATA_TYPE，VX_TENSOR_FIXED_POINT_POSITION
- VX_VALID_RECT_CALLBACK
vxSetMetaFormatFromReference
从示例数据对象引用中设置元格式对象。 vx_status vxSetMetaFormatFromReference( vx_meta_format meta, vx_reference exemplar); 此函数根据示例的元数据设置vx_meta_format对象。 参数 [in] meta - 要设置的 meta 格式对象。 [in] exemplar - 示例数据对象。 返回：vx_status_e枚举。 返回值 VX_SUCCESS- 元格式设置正确，任何其他值表示失败。 VX_ERROR_INVALID_REFERENCE- VX_ERROR_INVALID_REFERENCE-meta不是有效的VX_meta_format引用，或者范例不是有效的VX_REFERENCE引用。vxUnloadKernels
使用vxLoadKernels函数，从模块加载的OpenVX上下文中卸载所有内核。 vx_status vxUnloadKernels( vx_context context, const vx_char* module); 内核卸载是通过调用模块的vxUnpublishKernels导出函数来执行的。 注意 vxUnpublishKernels在vxLoadKernels的描述中进行了定义。 参数 [in] context - 必须删除内核对上下文的引用。 [in] module - 要卸载的模块的简称。在有特定模块命名约定的系统上，传递的名称应忽略这些约定。例如：libxyz.so应该作为xyz传递，并且实现将执行平台所需的正确操作。 注意 此 API使用系统预定义的模块路径。 返回：vx_status_e枚举。 返回值 VX_SUCCESS- 没有错误，任何其他值都表示失败。 VX_ERROR_INVALID_REFERENCE- 上下文不是有效的VX_context引用。 VX_ERROR_INVALID_PARAMETERS- 如果任何其他参数不正确。 参阅： vxLoadKernelsvxRegisterKernelLibrary
在上下文中向内核注册模块。 vx_status vxRegisterKernelLibrary( vx_context context, const vx_char* module, vx_publish_kernels_f publish, vx_unpublish_kernels_f unpublish); 如果模块不是动态库，则此函数使用模块名称，注册适当的发布和取消发布函数，因此可以调用vxLoadKernels和vxUnloadKernels。 参数 [in] context - 对上下文的引用。 [in] module - 要注册的模块的简称。 [in] publish - 用于从vxLoadKernels加载的模块的入口功能。 [in] unpublish - 从vxUnloadKernels卸载模块的入口功能。 返回：vx_status_e枚举。 返回值 VX_SUCCESS- 无错误；任何其他值表示故障。 VX_ERROR_INVALID_REFERENCE- 上下文不是有效的VX_context引用。 VX_ERROR_INVALID_PARAMETERS- 如果任何其他参数不正确。 参见：vxLoadKernels，vxUnloadKernels 参考文献链接 https://registry.khronos.org/OpenVX/specs/1.3.1/html/OpenVX_Specification_1_3_1.html 标签：kernel,OpenVX,框架,VX,meta,内核,vx,DATA From： https://www.cnblogs.com/wujianming-110117/p/18286857