> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 架构

如果你已熟悉 Qualcomm® 感知中枢（QSH）的术语、架构和组件，并打算使用 QSH API 或设置传感器信息，请参阅 [Qualcomm® 感知中枢 API](./qsh_api_reference)。

QSH 也称为 Qualcomm® Snapdragon™ 传感器核心（SSC），它为驱动和算法提供了统一的事件驱动框架。QSH 为基于硬件和基于软件的传感器提供相同的一组 API。此外，QSH 支持异步总线传输，并且可以针对新的或自定义的驱动功能进行扩展。QSH 由以下组件组成：

* QSH 客户端 API
* 传感器 API
* 核心框架
* 预先实现的平台传感器
* 供应商实现的传感器
* 测试模块

QSH 为外部客户端应用程序提供服务，并提供访问传感器数据的接口。下表描述了 QSH 框架中使用的术语：

**表：QSH 术语**

<table>
  <thead><tr><th>术语</th><th>描述</th></tr></thead>

  <tbody>
    <tr><td>传感器（Sensor）</td><td><ul><li>产生单一类型的数据，例如加速度计、陀螺仪、定时器、中断和旋转矢量。</li><li>处理异步数据。</li><li>发布必需属性和自定义属性，并管理其实例。</li></ul></td></tr>
    <tr><td>传感器实例（Sensor instance）</td><td><ul><li>以特定配置运行，发布输出数据事件，可以按客户端请求创建，也可以在多个请求之间共享。</li><li>物理传感器通常共享单个实例。</li></ul></td></tr>
    <tr><td>传感器唯一标识符（SUID）</td><td>每个传感器的唯一 128 位 ID。</td></tr>
    <tr><td>服务（Service）</td><td>为常用实用程序提供同步接口的模块。</td></tr>
    <tr><td>数据流（Data stream）</td><td>客户端与数据源之间的唯一连接。</td></tr>
    <tr><td>请求（Request）</td><td>客户端发送给传感器的配置消息（参见 <code>sns\_request.h</code> 文件）。</td></tr>
    <tr><td>事件（Event）</td><td>传感器实例生成的异步输出数据消息（参见 <code>sns\_sensor\_event.h</code> 文件）。</td></tr>
    <tr><td>Nanopb</td><td>用 ANSI C 实现的小代码体积协议缓冲区（protocol buffer）。</td></tr>
  </tbody>
</table>

下图显示了 QSH 架构：

<div className="flex flex-col items-center gap-2">
  <img src="https://mintcdn.com/qualcomm-prod/h7j64QujhJHkLxyj/Technologies/Sensors/media/qcs6490/qsh-architecture.svg?fit=max&auto=format&n=h7j64QujhJHkLxyj&q=85&s=c59b0dc183eba0220e494f467815bdd3" alt="图：QSH 架构" width="721" height="752" data-path="Technologies/Sensors/media/qcs6490/qsh-architecture.svg" />

  <p className="text-sm text-gray-700">图：QSH 架构</p>
</div>

QSH 框架包括以下组件：

* 应用处理器软件模块

  * 客户端应用程序：它包含 *application main()* 或*入口函数*，在应用处理器侧与 QSH 客户端 API 交互。
  * QSH 客户端 API：它提供高层 API 来访问 QSH 提供的服务。它通过抽象系统复杂性并专注于应用逻辑来简化应用开发。有关更多信息，请参阅 [Qualcomm® 感知中枢 API](./qsh_api_reference)。

* 低功耗处理器软件模块

  * 客户端管理器：客户端管理器负责低功耗处理器与应用处理器之间的所有通信。下表描述了客户端管理器的关键功能：

**表：客户端管理器功能**

<table>
  <thead><tr><th>功能</th><th>描述</th></tr></thead>

  <tbody>
    <tr><td>转换传入请求</td><td>客户端管理器接收传入请求，并将其转换为 QSH 能够理解的 nanopb 协议缓冲区格式。有关更多信息，请参阅 <a href="./nanopb_protocol_buffer_in_qsh">QSH 中的 Nanopb 协议缓冲区</a>。</td></tr>
    <tr><td>转换传出指示</td><td>客户端管理器从 QSH 接收事件消息，并将这些事件消息转换为 QSH 外部可理解的 nanopb 协议格式的传出指示。有关更多信息，请参阅 <a href="./nanopb_protocol_buffer_in_qsh">QSH 中的 Nanopb 协议缓冲区</a>。</td></tr>
    <tr><td>保证批处理选项</td><td>如果客户端指定了某些批处理（本地存储/累积）选项，客户端管理器会确保满足这些批处理选项。客户端管理器检查数据是否按照客户端指定的方式进行分组和发送，从而确保符合相应标准。</td></tr>
  </tbody>
</table>

* 服务管理器：QSH 通过服务管理器提供同步服务。传感器和传感器实例使用回调连接到服务管理器。

`adsp_proc/qsh_platform/inc/sns_service.h` 文件列出了 QSH 服务。构建过程会下载 `adsp_proc` 仓库。有关更多信息，请参阅[软件构建文档](https://dragonwingdocs.qualcomm.com/Key-Documents/Firmware-Guide/build-firmware)。下表描述了对设备驱动至关重要的关键 QSH 服务。

**表：QSH 服务**

<table>
  <thead><tr><th>QSH 服务</th><th>描述</th></tr></thead>

  <tbody>
    <tr><td>流服务（Stream service）</td><td><ul><li>此服务允许传感器创建和删除数据流。</li><li>有关通过数据流发送请求和接收事件的数据流的更多信息，请参阅 <code>adsp\_proc/qsh\_platform/inc/sns\_data\_stream.h</code> 文件。</li></ul></td></tr>
    <tr><td>属性服务（Attribute service）</td><td><ul><li>此服务允许传感器发布传感器属性或能力。</li><li>所有标准属性 ID 和预期值类型都在 <code>sns\_std\_sensor.proto</code> 文件中定义。</li><li>所有属性值都必须采用 nanopb 编码格式。有关更多信息，请参阅 <a href="./nanopb_protocol_buffer_in_qsh">QSH 中的 Nanopb 协议缓冲区</a>。</li><li>有关属性服务的更多信息，请参阅 <code>adsp\_proc/qsh\_platform/inc/services/sns\_attribute\_service.h</code> 文件。</li></ul></td></tr>
    <tr><td>诊断服务（Diagnostic service）</td><td><ul><li>此服务提供调试消息和数据日志数据包服务，并定义标准日志数据包 ID。</li><li>有关诊断服务的更多信息，请参阅 <code>adsp\_proc/qsh\_platform/inc/services/sns\_diag\_service.h</code> 文件。</li></ul></td></tr>
    <tr><td>事件服务（Event service）</td><td><ul><li>此服务允许传感器发布来自源传感器实例的输出事件。</li><li>有关事件服务的更多信息，请参阅 <code>adsp\_proc/qsh\_platform/inc/services/sns\_event\_service.h</code> 文件。</li></ul></td></tr>
    <tr><td>电源轨服务（Power rail service）</td><td><ul><li>此服务帮助物理传感器注册并投票决定打开或关闭电源轨。</li><li>有关电源轨服务的更多信息，请参阅 <code>adsp\_proc/qsh\_platform/inc/services/sns\_pwr\_rail\_service.h</code> 文件。</li></ul></td></tr>
    <tr><td>同步 COM 端口（SCP）服务</td><td><ul><li>供物理传感器注册或注销 COM 端口，并通过 COM 端口执行同步传输。</li><li>有关 SCP 服务的更多信息，请参阅 <code>adsp\_proc/qsh\_platform/inc/services/sns\_sync\_com\_port\_service.h</code> 文件。</li></ul></td></tr>
    <tr><td>通用 IO（GPIO）服务</td><td><ul><li>供物理传感器读取或写入 GPIO 值。</li><li>有效地抽象了用于控制 GPIO 的低层 CoreBSP 层。</li><li>有关 GPIO 服务的更多信息，请参阅 <code>adsp\_proc/qsh\_platform/inc/services/sns\_gpio\_service.h</code> 文件。</li></ul></td></tr>
    <tr><td>孤岛服务（Island service）</td><td><ul><li>供物理传感器请求退出孤岛模式（island mode）。</li><li>当应用程序必须访问 DDR 或仅在正常模式下可用的非孤岛资源时，应用程序代码可以使用孤岛服务。</li><li>有关孤岛服务的更多信息，请参阅 <code>adsp\_proc/qsh\_platform/inc/services/sns\_island\_service.h</code> 文件。</li></ul></td></tr>
    <tr><td>文件系统服务（File system service）</td><td><ul><li>供物理传感器用于文件服务管理。</li><li>抽象文件系统是应用处理器软件栈的一部分，可供低功耗处理器进行本地访问。</li><li>有关文件系统服务的更多信息，请参阅 <code>adsp\_proc/qsh\_platform/inc/services/sns\_file\_service.h</code> 文件。</li></ul></td></tr>
  </tbody>
</table>

* 平台传感器：QSH 提供某些内置传感器，用于平台或硬件特定的抽象，供其他传感器和传感器实例使用。下表描述了平台传感器：

**表：平台传感器**

<table>
  <thead><tr><th>平台传感器</th><th>描述</th></tr></thead>

  <tbody>
    <tr><td>注册表传感器（Registry sensor）</td><td><ul><li>QSH 中的注册表传感器为传感器提供从持久性内存访问注册表数据的接口。它允许传感器创建数据流、发送请求、接收数据事件、订阅更新以及删除不需要的数据流。</li><li>有关注册表传感器的更多信息，请参阅<a href="https://docs.qualcomm.com/doc/80-80023-7A/topic/configuration_customization.html">配置传感器</a>。</li><li>有关注册表传感器 API 的更多信息，请参阅 <code>adsp\_proc/qsh\_api/pb/sns\_registry.proto</code> 文件。</li></ul></td></tr>
    <tr><td>定时器传感器（Timer sensor）</td><td><ul><li>QSH 中的定时器传感器具有用于启动周期性或一次性定时器的接口。需要定时器的传感器必须创建数据流、发送请求并读取交付的数据事件。</li><li>有关定时器传感器 API 的更多信息，请参阅 <code>adsp\_proc/qsh\_platform/api/public\_sns/sns\_timer.proto</code> 文件。</li></ul></td></tr>
    <tr><td>中断传感器（Interrupt sensor）</td><td><ul><li>QSH 中的中断传感器具有用于注册中断的接口。需要中断的传感器必须创建数据流、发送请求并读取交付的数据事件。</li><li>有关中断传感器 API 的更多信息，请参阅 <code>adsp\_proc/qsh\_platform/api/public\_sns/sns\_interrupt.proto</code> 文件。</li></ul></td></tr>
    <tr><td>异步 COM 端口（ASCP）传感器</td><td><ul><li>QSH 中的 ASCP 传感器具有通过通信端口进行异步读写操作的接口。</li><li>需要此功能的传感器必须创建数据流、发送请求并读取交付的数据事件。</li><li>有关 ASCP 传感器 API 的更多信息，请参阅 <code>adsp\_proc/qsh\_platform/api/public\_sns/sns\_async\_com\_port.proto</code> 文件。</li><li>ASCP 传感器通常由物理传感器驱动用来读取大容量先进先出（FIFO）数据。</li></ul></td></tr>
    <tr><td>SUID 查找传感器（SUID lookup sensor）</td><td><ul><li>QSH 中的 SUID 查找传感器提供用于获取依赖传感器 SUID 的 API。其自身的 SUID 可通过 <code>sns\_sensor\_util.h</code> 文件中的 <code>sns\_get\_suid\_lookup()</code> 函数获取。</li><li>有关 SUID 查找传感器 API 的更多信息，请参阅 <code>adsp\_proc/qsh\_api/pb/sns\_suid.proto</code> 文件。</li></ul></td></tr>
    <tr><td>测试传感器（Test sensor）</td><td><ul><li>测试传感器用于定制和运行特定于传感器的用例。</li><li>测试传感器位于 <code>adsp\_proc/qsh\_platform/sensors/test</code> 目录中。</li></ul></td></tr>
  </tbody>
</table>

* QSH 实用工具：QSH 为传感器和传感器实例提供了多个辅助实用工具。所有实用工具都位于 `adsp_proc/qsh_platform/inc/utils` 目录中。下表描述了关键的 QSH 实用工具：

**表：QSH 实用工具**

<table>
  <thead><tr><th>QSH 实用工具</th><th>描述</th></tr></thead>

  <tbody>
    <tr><td>Nanopb 编码/解码</td><td><ul><li>为所有传感器提供通用的编码和解码辅助函数。例如，编码和解码 <code>sns\_request</code> 消息、编码并发布以及解码数据事件。</li><li>物理传感器驱动可使用异步 COM 端口 nanopb 实用工具。</li></ul></td></tr>
    <tr><td>传感器实用工具（Sensor utils）</td><td><ul><li>为传感器提供通用功能，例如查找传感器实例和获取 SUID 查找传感器的 SUID。</li></ul></td></tr>
    <tr><td>属性实用工具（Attribute utils）</td><td><ul><li>提供对传感器属性进行编码和发布的辅助函数。</li></ul></td></tr>
    <tr><td>内存实用工具（Memory utils）</td><td><ul><li>提供用于高效内存管理和分配的辅助函数。</li></ul></td></tr>
    <tr><td>数学实用工具（Math utils）</td><td><ul><li>提供一组数学函数和运算，例如矩阵、快速傅里叶变换（FFT）和无限脉冲响应（IIR）滤波器。</li></ul></td></tr>
    <tr><td>Printf 实用工具（Printf utils）</td><td><ul><li>包含用于格式化和打印数据的辅助函数。</li></ul></td></tr>
  </tbody>
</table>

* 操作系统抽象（OSA）为操作系统服务提供统一接口，抽象平台特定的实现。

**表：操作系统抽象（OSA）**

<table>
  <thead><tr><th>操作系统抽象（OSA）</th><th>描述</th></tr></thead>

  <tbody>
    <tr><td>线程管理</td><td><ul><li>为线程的创建、删除和管理提供抽象。</li><li>包括线程同步原语（互斥锁、信号量、条件变量）。</li><li>实现与平台无关的多线程传感器框架执行。</li></ul></td></tr>
    <tr><td>信号处理</td><td><ul><li>抽象操作系统信号的注册和传递机制。</li><li>提供信号属性配置和信号掩码管理。</li><li>在传感器框架中实现事件驱动的任务调度。</li></ul></td></tr>
    <tr><td>互斥与同步</td><td><ul><li>为临界区提供互斥原语。</li><li>抽象平台特定的锁机制。</li><li>确保对共享资源的线程安全访问。</li></ul></td></tr>
  </tbody>
</table>

* 平台抽象层（PAL）为传感器驱动和框架组件提供硬件及平台特定的抽象。

**表：平台抽象层（PAL）**

<table>
  <thead><tr><th>平台抽象层（PAL）</th><th>描述</th></tr></thead>

  <tbody>
    <tr><td>GPIO 抽象</td><td><ul><li>提供与平台无关的 GPIO 引脚控制。</li><li>抽象 GPIO 配置、读取和写入操作。</li><li>实现传感器中断和控制信号处理。</li></ul></td></tr>
    <tr><td>I<sup>2</sup>C/SPI 总线抽象</td><td><ul><li>抽象通信总线操作（I<sup>2</sup>C、SPI）。</li><li>提供带有平台特定实现的读/写操作。</li><li>实现跨不同平台的物理传感器通信。</li></ul></td></tr>
    <tr><td>中断处理</td><td><ul><li>抽象中断注册和处理机制。</li><li>提供中断启用/禁用和优先级管理。</li><li>实现由传感器中断驱动的数据采集。</li></ul></td></tr>
    <tr><td>时钟与电源管理</td><td><ul><li>抽象时钟配置和电源域管理。</li><li>提供平台特定的时钟门控和电源状态控制。</li><li>为传感器子系统实现高效的电源管理。</li></ul></td></tr>
    <tr><td>寄存器访问</td><td><ul><li>提供抽象的寄存器读/写操作。</li><li>抽象内存映射 I/O 和寄存器访问模式。</li><li>实现跨不同 SoC 实现的硬件控制。</li></ul></td></tr>
    <tr><td>UART/串行通信</td><td><ul><li>抽象用于调试和数据日志记录的串行端口操作。</li><li>提供与平台无关的串行通信。</li><li>为传感器驱动实现异步 COM 端口操作。</li></ul></td></tr>
  </tbody>
</table>

## 传感器与传感器实例

QSH 将传感器实现划分为两个逻辑单元：传感器和传感器实例。

* 传感器是异步数据的生产者、消费者，或生产者与消费者的组合。

  * 每个传感器可以拥有一个或多个传感器实例。
  * 向传感器请求数据会导致创建传感器实例或共享现有的传感器实例。

* 传感器按需创建传感器实例。

  * 传感器管理其对应实例的生命周期和配置，并向其客户端发送配置更新和初始状态事件。
  * 每个传感器实例以特定的客户端配置运行。
  * 物理传感器的传感器实例对传感器硬件进行编程，使其以所需的配置运行。
  * 供应商必须以尽可能少的传感器实例来满足所有客户端请求。
  * 传感器实例生成数据流并将其发送给所有活动的客户端。

* 多个传感器可以共享和配置单个传感器实例。这种操作模式常见于硬件传感器的组合驱动（combo driver），例如：

  * 加速度计和陀螺仪
  * 接近传感器和环境光传感器

**后续步骤**

* [消息](./sensor_api_messages)