Android : Camera之CHI API

1.Qualcomm Spectra 2xx相机驱动程序有五个关键的可定制组件，使OEM能够充分利用CHI进行相机应用开发：

• CHI Override 模块补充了Google HAL3接口，允许符合HAL3标准的相机应用程序直接控制图像处理流水线的生成、引擎选择和多帧控制等。
• CHI pipeline  旨在将任意的计算管道构造用于图像处理，管道可以由QTI或扩展节点提供的ISP（FF-ISP）固定功能模块组成，由摄像机驱动程序堆栈外部控制。对于Camera2/HAL3实现，可以利用XML文件指定与现有Camera2/HAL3 use case 的拓扑图，然后通过程序直接调用CHI来实现pipeline。
• CHI节点扩展是CHI的进一步扩展，提供了方便的hooks方法来简化CPU，GPU（通过OpenCL，OpenGL ES或Vulkan），或 DSP（通过OpenDSP，FastCV™软件开发套件或自定义编程）上的额外处理。 自定义节点可以指定私有供应商标记，用于被应用使用以及 与CHI FF-ISP节点或其他扩展节点交互。
• CHI统计信息覆盖（包括3A）机制允许覆盖任何QTI的默认值统计算法，且无需改驱动程序。外部统计算法可以存储私有数据，也可以由自定义节点访问。
• CHI传感器XML允许设备制造商为其特定硬件配置参数，包括相机模块，图像传感器， 执行器，电子可擦除可编程只读存储器（EEPROM）和 闪存组件。

2.关键术语：

Use case：相机管道的特定配置，实现了良好的定义的功能，例如，带有ZSL的20 MP快照和2k上的预览显示是就是一个用例。 CHI API允许开发者在底层硬件的限制范围内自行配置use case，并且不需要修改驱动。
Session：相机管道被创建开始处理图像到被销毁的过程，称之为会话，同时可以存在多个会话。
Request ：请求处理从图像传感器中提取的数据帧，或从内存中提取的数据帧，驱动处理结果必须返回到相机应用程序。
Sub-request ：将单个HAL3请求分解为多个CHI子请求操作，子请求的结果不会从驱动程序中返回出去，而是合并为单个结果给原始请求。子请求一般用于启用Camera2的某些功能，例如HDR、多帧后处理等。
Stream：具有相同大小和格式的缓冲区序列，用于处理图像数据。可以将不同类型的多个stream指定为输入和输出到camera pipeline。stream是定义Camera2 / HAL3 use case的关键组成部分。
Per-session settings：影响相机管道处理的设置， 会话开始后就无法被更改。例如， 允许图像稳定处理。
Per-request settings：影响各个请求的设置。例如，设置手动曝光值。
Topology：有向无环图（DAG）由一系列处理节点和一组链接组成，它描述了那些正在被节点处理的缓冲区。拓扑通过XML文件指定。
Engine：用于处理数据的硬件。 如Spectra ISP，Snapdragon CPU， Adreno和DSP 是CHI API可用的引擎示例。
Node：像机管道中的逻辑功能块（节点），节点链接在一起形成拓扑。在初始版本中 CHI API，ISP外部的所有节点都通过CPU代码通过本地API（OpenCL和FastCV之类的引擎）调用，Chi API可以在将来扩展到允许在不重用本地api的情况下缓存和重用硬件命令。
Pipeline：启用数据操作的唯一上下文。每个管道都可以维护自己的状态跨多个请求，而不受其他管道的影响。管道利拓扑结构定义Engine使用和数据处理流程。
Statistics：包括3A算法，用于自动控制图像传感器和相机ISP实现更好的图像质量。这些特定领域的算法被处理成为CHI API的专用部分。
Live stream：从图像传感器接收数据的处理进程，不能修改之前请求的任何数据。如果处理速率和传感器数据传输不匹配则会移至Offline stream。
Offline stream：不从图像传感器直接获取数据处理的进程，在Chi API中，Offline stream可以与Live stream成对存在而不造成额外的延迟，处理结果可以返回到相机。

二、CHI 体系结构模式

1.基本拓扑关系图

2.Chi 硬件接口
谷歌HAL3的扩展接口，允许通过请求调整拓扑结构和低延迟控制，一些使用特性如下:

• 自定义ZSL
• 多帧请求生成 和 处理
• 图像稳定
• 低延迟后处理

3.Chi 节点接口

CHI驱动程序提供默认节点来启用相机use cases。oem厂商可以在现有的CHI驱动上添加功能，以获得独特的相机体验。这是一个简单而强大的接口，可以在相机pipeline中无缝添加图像处理功能。

(1)Data 传递给应用程序(2)Data 传递到加工管道(3)Inter-node 沟通使用发布和订阅机制ChiNode1 ↔ ChiNode2 使用 Android tags/ChiVendorTagsChiNode1 ↔ ExtNode1 使用 Android tags/ChiVendorTags / ExtCompVendorTagsExtNode1 ↔ ExtNode2 使用 Android tags/ChiVendorTags/ExtCompVendorTags

<vendor> —— 对应厂商定义的节点模块。例如，节点由QTI提供，则命名为< QTI >。<category> —— 模块类型，有效值为 <node> 和 <stats>。<algorithm> - so对应的独有算法名。示例：

• QTI提供的3A算法命名为：com.qti.3a.aec.so

• QTI提供的高通®Clear Sight™相机功能后处理节点命名为：com.qti.node.clearsight.so

<UsecaseDef> ：根标记，属性必须定义。如: <UsecaseDef xmlns:xsi=http://www.w3.org/2001/XMLSchema-instancexsi:noNamespaceSchemaLocation="topology.xsd"> <Usecase> ：用例，代表一种功能特性（如：ZSL），tags存在于<Usecase> </Usecase>之间如下： <UsecaseName> - Value field. Exactly 1 tag is required. <Targets> - Exactly 1 is required. <StreamConfigMode> - Value field. Exactly 1 is required. <SystemwideSetting> - Exactly 1 is required. <Topology> - At least 1 is required.<Targets> ：流的列表，包括用例执行的格式和大小范围。这里列出的流对应于传入HAL3的configure_streams () API，通过tag值找到匹配的<Usecase>。 <Target> and <SystemwideSettings> 用于从XML中选择一个<Usecase>。Valid tag: <TargetName> - Value field. Exactly 1 is required. <TargetDirection> - Value field. Exactly 1 is required. <TargetFormat> - Value field. At least 1 is required. <Range> - Exactly 1 is required. <Range> ： 缓冲区的分辨率范围。Valid tag: <MinW> - Value field. Exactly 1 required. <MinH> - Value Field. Exactly 1 required. <MaxW> - Value Field. Exactly 1 required.  <MaxH> - Value Field. Exactly 1 required. 一个Target示例：(当驱动程序处理configure_streams()时，如果有一个输出流的缓冲区格式是YUV420NV12且分辨率小于等于1080p时，就会匹配到如下Target。)

<SystemwideSettings> ： 会话组的设定，与<targets>结合使用定义了use case的键值，这些设置对应于Android属性。Valid tag: <Setting> - At least 1 is required. <Setting> ： 设置说明，用于选择对应的use case。Valid tag: <SettingName> - Value field. Exactly 1 is required. <SettingDataType> - Value field. Exactly 1 is required <SettingMatch> - Value field. Exactly 1 is required 示例：

<Topology> ：描述了驱动对每个节点的顺序和依赖关系的解析，以处理上层请求。

Valid tag:

 <TopologyName> - Value field. Exactly 1 is required.
 <TopologyNodesList> - Exactly 1 is required.
 <PortLinkage> - At least 1 is required.

<TopologyNodesList> ：包含在Topology中的Node列表，形成处理框架。

Valid tag:
 <Node> - At least 1 is required.

<Node> ： 单个处理逻辑块，用于告诉驱动如何来处理一个请求。Valid tags: <NodeProperty> - Optional. Several properties allowed. <NodeName> - Value field. Exactly 1 is required. <NodeId> - Value field. Exactly 1 is required. <NodeInstance> - Value field. Exactly 1 is required. <NodeInstanceId> - Value field. Exactly 1 is required.例子：

驱动程序根据nodeId解析节点类型，对于所有自定义节点该字段的值为255，并带有一个NodeProperty来告知驱动程序切确的自定义节点类型。如下：

<NodePortLinkage> ： 描述节点列表以及它们如何相互连接。Valid tags: <SourceNode> - Value field. Exactly 1 is required. <SourceNodeInstance> - Value field. Exactly 1 is required. <Link> - At least 1 is required.<Link> ：单个node之间的连接。Valid tags: <SrcPort> - Exactly 1 is required. <DstPort> - At least 1 is required. <BufferProperties> - Optional.<SrcPort> ：一个节点的输出端口，该节点输出的图像数据到<DstPort>被使用修改，从<SrcPort>到<DstPort>可以有一对多的关系。Valid tags: <PortName> - Value field. Exactly 1 is required. <PortId> - Value field. Exactly 1 is required. <NodeName> - Value field. Exactly 1 is required. <NodeId> - Value field. Exactly 1 is required. <NodeInstance> - Value field. Exactly 1 is required. <NodeInstanceId> - Value field. Exactly 1 is required.

<DstPort> ：接收从<SrcPort>节点的输出数据。Valid tags <PortName> - Value field. Exactly 1 is required. <PortId> - Value field. Exactly 1 is required. <NodeName> - Value field. Exactly 1 is required. <NodeId> - Value field. Exactly 1 is required. <NodeInstance> - Value field. Exactly 1 is required. <NodeInstanceId> - Value field. Exactly 1 is required. <BufferProperties> ：输入/输出缓冲区的属性。Valid tags: <BatchMode> - Value field. Exactly 1 is required. <BufferFormat> - Value field. Exactly 1 is required. <BufferQueueDepth> - Value field. Exactly 1 is required. <BufferHeap> - Value field. Exactly 1 is required. <BufferFlags> - Value field. Exactly 1 is required<UsecaseName>：任何字符串可以定义一个用例名称；例如，指定此流输出缓冲区由名为“NodeXYZ”的节点生成，则在<Link>标签内相应配置:

<TargetName>：用于指定输出端口对应的缓冲区。

》》》以下标签指定了封装标签要用的值，不能在其中嵌入额外的标签：

<UsecaseName> ：用于标识 Use case 的字符串。

Valid value:
 Any string that is a valid C variable

例子：<UsecaseName>UsecasePreview</UsecaseName>

<TargetName> : 该字串用于映射流的输出缓冲区到拓扑中节点的输出端口，其中<TargetName>包含的字符串用于关联节点的输出端口与此流的输出缓冲区。

Valid value:
 Any string that is a valid C variable, however, there must be a matching string name in the <PortName> of any <DstPort> which is a sink port.

 例子：<TargetName>TARGET_BUFFER_PREVIEW</TargetName>

<TargetDirection>：此标签用于指定流的方向(或流类型)，即它是否是输入流、输出流或双向流。

Valid values: TargetOutput TargetInput TargetBidirectional 例子：<TargetDirection>TargetOutput</TargetDirection>

<TargetFormat>：此标签指定与流关联的缓冲区的格式。允许指定多个标签指定，如果其中一种格式与configure_streams()中给出的配置匹配，就认为与对应的use case相匹配。Valid values: Jpeg Y8 Y16 YUV420NV12 YUV420NV21 YUV422NV16 Blob RawYUV8BIT RawQCOM RawMIPI RawPlain16 RawMeta8BIT UBWCTP10 UBWCNV12 UBWCNV124R 例子:<TargetFormat>YUV420NV12</TargetFormat><MinW> ：缓冲区的最小宽度。由<Range>标记使用。Valid value: Unsigned 32-bit integer, which must be less than <MaxW>. <MinH> ：缓冲区的最小高度。由<Range>标记使用。Valid value: Unsigned 32-bit integer, which must be less than <MaxH>.<MaxW> ：缓冲区的最大宽度。由<Range>标记使用。Valid value: Unsigned 32-bit integer, which must be greater than <MinW>. <MaxH> ：缓冲区的最大高度。由<Range>标记使用。Valid value: Unsigned 32-bit integer, which must be greater than <MinH>.<TopologyName> ：拓扑的名称。Valid value: Any string<NodeName>：字符串描述的节点名称。Valid value: Any string that is a valid C variable. <NodeId>：标识节点的ID，用于将节点的端口彼此链接。<NodeInstance>：字符串以描述节点实例的名称。Valid value: Any string that is a valid C variable. <NodeInstanceId>：标识节点唯一实例的ID，用于节点之间的端口连接。Valid value: Unsigned 32-bit integer, which must correspond to a unique instantiation of a node of the same engine type. <SettingName>：描述设置名称的字符串。<SettingDataType>:描述变量类型的字符串。Valid values: INT UINT FLOAT BOOL STRING <SettingMatch>：描述配置变量类型的字符串。Valid value: Any valid string, which is a valid constant for the <SettingMatch> tag.<SourceNode>：用于标识节点资源的ID，用于将节点的端口彼此链接。<SourceNodeInstance>：用于标识节点的唯一实例的ID，用于将节点的端口链接到彼此。Valid value: Unsigned 32-bit integer, which must correspond to a unique instantiation of a node of the same engine type.<PortName> ：描述端口名称的字符串。Valid value: Any string that is a valid C variable.<PortId> ：端口的ID,用于各端口之间的连接。<BatchMode>：确定是否需要批处理。一般来说，只有在HFR中才需要该模式，使ISP在单个硬件提交中处理多帧，一般适用于无法离线操作的链接。Valid value: 0 to disable batch mode, 1 to enable it. <BufferFormat>：缓冲区类型。Valid values: Jpeg Y8 Y16 YUV420NV12 YUV420NV21 YUV422NV16 Blob RawYUV8BIT RawQCOM RawMIPI RawPlain16 RawMeta8BIT UBWCTP10 UBWCNV12 UBWCNV124R示例:<BufferFormat>YUV420NV12</BufferFormat>><BufferQueueDepth> 一个链接允许创建的最大缓冲区数量。Valid values: 32 bit-unsigned integer.<BufferHeap>：允许在camera ISP之外分配缓存的堆。Valid values: System Ion DSP EGL <BufferFlags>：描述缓冲区的信息，例如设置MemFlagWriteAccess表示节点可写入。Valid values: MemFlagHw MemFlagProtected MemFlagCmdBuffer MemFlagUMDAccess MemFlagCache MemFlagPacketBuffer MemFlagKMDAccess <NodePropertyValue>：节点属性值，包含对应要加载的so模块，如：com.company.node.hdvideo

 能够创建 和 管理 多个 会话 和 相关 的 管道 ZSL 快照需要一 个实时的RAW pipelien和一个离线会话。 MFNR 需要额外的离线会话用于预过滤、混合、再过滤阶段。 能够控制整个会话的各请求和结果传输。 能够在应答framework请求的响应内部生成请求。 能够记录所有内部结果并生成最终的framework应答。 能够管理ZSL队列缓冲区 (图像和元数据)。 能够控制 inter-session buffer, fence, 和 metadata 联系。 能够支持锚帧选择逻辑。

void chi_hal_override_entry (const chi_hal_ops_t *ops, ///< [in]chi_hal_callback_ops_t *callbacks) ///< [in | out]{...// Store the hal opsQtiChiOverride::m_chiOps = *ops;...// Export the callback function pointerscallbacks->chi_initialize_override_session = QtiChiOverride::InitializeOverrideSession;callbacks->chi_finalize_override_session = QtiChiOverride::QtiChiExtFinalizeOverrideSession;...// Optional callback function pointers can be NULL}