> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs-staging.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>传感器</td><td><ul><li>产生单一类型的数据，例如加速度计、陀螺仪、计时器、中断和旋转矢量。</li><li>处理异步数据。</li><li>发布强制和自定义属性，并管理其实例。</li></ul></td></tr>
    <tr><td>传感器实例</td><td><ul><li>以特定配置运行，发布输出数据事件，可以按客户端请求创建或在多个请求间共享。</li><li>物理传感器通常共享一个实例。</li></ul></td></tr>
    <tr><td>传感器唯一标识符 (SUID)</td><td>每个传感器的唯一 128 位 ID。</td></tr>
    <tr><td>服务</td><td>为常见实用程序提供同步接口的模块。</td></tr>
    <tr><td>数据流</td><td>客户端与数据源之间的唯一连接。</td></tr>
    <tr><td>请求</td><td>客户端发送给传感器的配置消息（参见 <code>sns\_request.h</code> 文件）。</td></tr>
    <tr><td>事件</td><td>传感器实例生成的异步输出数据消息（参见 <code>sns\_sensor\_event.h</code> 文件）。</td></tr>
    <tr><td>Nanopb</td><td>用 ANSI C 实现的一种小代码大小的协议缓冲。</td></tr>
  </tbody>
</table>

下图显示了 QSH 架构：

<div className="flex flex-col items-center gap-2">
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-staging/zh/Technologies/Sensors/media/qcs6490/qsh-architecture.svg" alt="Figure : QSH architecture" />

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

QSH 框架包含以下组件：

* 应用处理器软件模块

  * 客户端应用：它有 *application main()* 或 *entry function*，与应用处理器端的 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>流服务</td><td><ul><li>此服务允许传感器创建和删除数据流。</li><li>有关通过数据流发送请求和接收事件的数据流的更多信息，请参阅 <code>adsp\_proc/qsh\_platform/inc/sns\_data\_stream.h</code> 文件。</li></ul></td></tr>
    <tr><td>属性服务</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>诊断服务</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>事件服务</td><td><ul><li>此服务允许传感器从源传感器实例发布输出事件。</li><li>有关事件服务的更多信息，请参阅 <code>adsp\_proc/qsh\_platform/inc/services/sns\_event\_service.h</code> 文件。</li></ul></td></tr>
    <tr><td>电源轨服务</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 服务</td><td><ul><li>可供物理传感器请求退出 island 模式。</li><li>当应用必须访问在正常模式下可用的 DDR 或非 island 资源时，应用代码可以使用 island 服务。</li><li>有关 island 服务的更多信息，请参阅 <code>adsp\_proc/qsh\_platform/inc/services/sns\_island\_service.h</code> 文件。</li></ul></td></tr>
    <tr><td>文件系统服务</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 传感器</td><td><ul><li>QSH 中的 registry 传感器为传感器提供了从持久内存访问 registry 数据的接口。它允许传感器创建数据流、发送请求、接收数据事件、订阅更新和删除不必要的数据流。</li><li>有关 registry 传感器的更多信息，请参阅 <a href="https://dragonwingdocs.qualcomm.com/Addendum-docs/Sensors/addendum/Configure-sensors">配置传感器</a>。</li><li>有关 registry 传感器 API 的更多信息，请参阅 <code>adsp\_proc/qsh\_api/pb/sns\_registry.proto</code> 文件。</li></ul></td></tr>
    <tr><td>Timer 传感器</td><td><ul><li>QSH 中的 timer 传感器具有启动定期或单次计时器的接口。需要计时器的传感器必须创建数据流、发送请求，并读取传送的数据事件。</li><li>有关 timer 传感器 API 的更多信息，请参阅 <code>adsp\_proc/qsh\_platform/api/public\_sns/sns\_timer.proto</code> 文件。</li></ul></td></tr>
    <tr><td>Interrupt 传感器</td><td><ul><li>QSH 中的 interrupt 传感器具有注册中断的接口。需要中断的传感器必须创建数据流、发送请求，并读取传送的数据事件。</li><li>有关 interrupt 传感器 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 查找传感器</td><td><ul><li>QSH 中的 SUID 查找传感器提供 API 以获取依赖传感器的 SUID。它自身的 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 传感器</td><td><ul><li>Test 传感器自定义并运行传感器特定的用例。</li><li>Test 传感器位于 <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 encode/decode</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 utils</td><td><ul><li>包含格式化和打印数据的辅助函数。</li></ul></td></tr>
  </tbody>
</table>

* OS 抽象 (OSA) 提供了操作系统服务的统一接口，抽象了平台特定的实现。

**表：OS 抽象 (OSA)**

<table>
  <thead><tr><th>OS 抽象 (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>抽象 OS 信号注册和传递机制。</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 将传感器实现划分为两个逻辑单元：传感器和传感器实例。

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

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

* 传感器根据需要创建传感器实例。

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

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

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

**后续步骤**

* [消息](./sensor_api_messages)