qsh-architecture3

# QSH 架构介绍 QSH 统一事件驱动框架。 Note - 要继续了解有关 API 或者设置传感器的信息，请参阅 [QSH API](https://docs.qualcomm.com/doc/80-70018-7SC/topic/qsh_api_reference.html#qsh-api-reference)。 - 低功耗应用数字信号处理器 (aDSP) 的源代码（包括 QSH 框架）仅供具有授权访问权限的许可用户使用。要升级您的访问权限，前往 [www.qualcomm.com/support/working-with-qualcomm](https://www.qualcomm.com/support/working-with-qualcomm)。 QSH，也称为 Qualcomm® Snapdragon™ 传感器核心 (SSC)，为驱动程序和算法提供了一个统一的事件驱动框架。QSH 支持基于硬件和基于软件的传感器的同一组 API。此外，QSH 支持异步总线传输，并且可针对新的或自定义驱动程序功能进行扩展。QSH 由以下组件组成： > > > - QSH 客户端 API > - 传感器 API > - 核心框架 > - 预实现的平台传感器 > - 供应商实现的传感器 > - 测试模块 QSH 为外部客户端提供服务，并提供一个简单的接口来访问传感器数据。下表描述了 QSH 框架中使用的术语：表：QSH 术语 | **项目** | **说明** | | --- | --- | | 传感器 |

生成单一类型数据，例如，加速度计、陀螺仪、定时器、中断、旋转矢量等

处理异步数据

发布必需属性和自定义属性，并管理其实例

| | 传感器实例 |

在特定配置下运行，发布输出数据事件，并且可以按客户端请求创建或在多个请求之间共享

物理传感器通常共享单一实例

| | 传感器唯一标识符 (SUID) | 每个传感器唯一的 128 位 ID | | 服务 | 为通用实用工具提供同步接口的模块 | | 数据流 | 客户端与数据源间的唯一连接 | | 请求 | 客户端发送至传感器的配置消息（请参阅 `sns_request.h` 文件） | | 事件 | 传感器实例生成的异步输出数据消息（请参阅 `sns_sensor_event.h` 文件） | | Nanopb | 用 ANSI C 实现的小代码量协议缓存 | 下图显示了 QSH 架构： **图：QSH 架构** QSH 框架包括以下组件： - **应用处理器软件模块** - **客户端应用**：它包含与应用处理器端的 QSH 客户端 API 交互的*应用 main()* 或*入口函数*。 - **QSH 客户端 API**：它提供高层 API 来访问 QSH 提供的服务。它通过抽象系统复杂性并专注于应用程序逻辑来简化应用程序开发。关于更多信息，请参见 [QSH API](https://docs.qualcomm.com/doc/80-70018-7SC/topic/qsh_api_reference.html#qsh-api-reference)。 - **低功耗处理器软件模块** - **客户端管理器**：客户端管理器负责低功耗处理器与应用处理器的所有通信。它负责以下功能：表：客户端管理器功能 | 功能 | 说明 | | --- | --- | | 转换传入请求 | 客户端管理器接受传入的请求，并将其转换为 QSH 可以理解的格式。 | | 转换传出指示 | 客户端管理器从 QSH 接收事件消息，并将这些事件消息转换为 QSH 外部可理解的格式的传出指示。 | | 保证批处理选项 | 如果客户端指定了特定的批处理（本地存储/累积）选项，则客户端管理器会确保其符合批处理选项。客户端管理器会核查数据是否依照客户端指定的方式进行分组与发送，以此确保符合标准。 | - **服务管理器**：QSH 通过其服务管理器提供同步服务。传感器和传感器实例 API 使用回调连接到此服务管理器。 `adsp_proc/qsh_platform/inc/sns_service.h` 文件列出了 QSH 中可用的服务，也称为 QSH 服务。下表介绍了对设备驱动程序至关重要的关键 QSH 服务。表：QSH 服务 | QSH 服务 | 说明 | | --- | --- | | 流服务 |

允许通过传感器创建和删除数据流。

有关通过数据流发送请求和接收事件的流 API，参见 adsp_proc/qsh_platform/inc/sns_data_stream.h 文件。

| | 属性服务 |

允许传感器发布传感器属性或功能。

所有标准属性 ID 和预期值类型均在 sns_std_sensor.proto 文件中定义。

所有属性值必须采用 nanopb 编码格式。

有关 API 的更多信息，请参阅 adsp_proc/qsh_platform/inc/services/sns_attribute_service.h 文件。

| | 诊断服务 |

提供调试消息和数据日志数据包服务，并定义标准日志数据包 ID。

有关 API 的更多信息，请参阅 adsp_proc/qsh_platform/inc/services/sns_diag_service.h 文件。

| | 事件服务 |

允许从源传感器实例发布输出事件。

有关 API 的更多信息，请参阅 adsp_proc/qsh_platform/inc/services/sns_event_service.h 文件。

| | 电源服务 |

可供物理传感器注册和投票供电域（开/关）。

有关 API 的更多信息，请参阅 adsp_proc/qsh_platform/inc/services/sns_pwr_rail_service.h 文件。

| | 同步 COM 端口 (SCP) 服务 |

可供物理传感器注册/注销 COM 端口以及通过 COM 端口执行同步传输。

有关 API 的更多信息，请参阅 adsp_proc/qsh_platform/inc/services/sns_sync_com_port_service.h 文件。

| | GPIO 服务 |

可供物理传感器读/写 GPIO 值。

有效抽象了一个低层的 CoreBSP 层来控制 GPIO。

有关 API 的更多信息，请参阅 adsp_proc/qsh_platform/inc/services/sns_gpio_service.h 文件。

| | Island 服务 |

可供物理传感器请求 Island 出口。

当应用程序必须访问 DDR 或非 Island 资源时，应用程序代码可以使用 Island 服务。

有关 API 的更多信息，请参阅 adsp_proc/qsh_platform/inc/services/sns_island_service.h 文件。

| | 文件系统服务 |

可供物理传感器使用，用于文件服务管理。

抽象文件系统是应用处理器堆栈的一部分，可用于从低功耗处理器进行本地访问。

有关 API 的更多信息，请参阅 adsp_proc/qsh_platform/inc/services/sns_file_service.h 文件。

| - **平台传感器**：QSH 提供一些内置传感器，用于平台或硬件特定的抽象，这些抽象可由其他传感器和传感器实例使用。下表介绍了平台传感器：表：平台传感器 | 平台传感器 | 说明 | | --- | --- | | 注册表传感器 |

QSH 中的注册表传感器为传感器提供了一个接口，用于从持久内存访问注册表数据。它允许传感器创建数据流、发送请求、接收数据事件、订阅更新以及删除不必要的流。

有关注册表传感器的更多信息，请参阅 Qualcomm Linux Sensors Guide - Addendum 中的 Configure sensors。

>
>
> Note
>
>
> [Qualcomm Linux Sensors Guide - Addendum](https://docs.qualcomm.com/bundle/resource/topics/80-70018-7A/overview.html) 适用于具有授权访问权限的许可开发人员。

注册表传感器 API 记录在 adsp_proc/qsh_api/pb/sns_registry.proto 文件中。

| | 定时器传感器 |

QSH 中的定时器传感器提供了一个接口用于启动周期性或一次性定时器。需要计时器的传感器必须创建数据流、发送请求并读取传递的数据事件。

计时器传感器 API 记录在 adsp_proc/qsh_platform/api/public_sns/sns_timer.proto 文件中。

| | 中断传感器 |

QSH 中的中断传感器提供用于注册中断的接口。需要中断的传感器必须创建一个数据流、发送请求并读取传递的数据事件。

中断传感器 API 记录在 adsp_proc/qsh_platform/api/public_sns/sns_interrupt.proto 文件中。

| | 异步 COM 端口 (ASCP) 传感器 |

QSH 中的 ASCP 传感器为通过通信端口进行异步读/写操作提供了一个接口。

需要此功能的传感器必须创建数据流、发送请求并读取传递的数据事件。

ASCP 传感器 API 记录在 adsp_proc/qsh_platform/api/public_sns/sns_async_com_port.proto 文件中。

>
>
> Note
>
>
> 物理传感器驱动程序通常使用 ASCP 传感器读取大块 FIFO。 | | SUID 查询传感器 |

QSH 中的 SUID 查找传感器提供了一个 API，用于获取相关传感器的 SUID。可通过文件 sns_sensor_util.h 中的 sns_get_suid_lookup() 函数获取其自身的 SUID。

adsp_proc/qsh_api/pb/sns_suid.proto 文件记录了 SUID 查找传感器 API。

| | 测试传感器 |

测试传感器可自定义并运行特定于传感器的用例。

测试传感器位于 adsp_proc/qsh_platform/sensors/test 目录中。

| - **QSH 实用工具**：QSH 为传感器和传感器实例提供了多个帮助程序实用工具。所有实用工具均可以在 `adsp_proc/qsh_platform/inc/utils` 目录中找到。下表介绍了关键工具：表：QSH 实用工具 | QSH 实用工具 | 说明 | | --- | --- | | Nanopb 编码/解码 |

为所有传感器提供通用的编码/解码辅助函数。例如，编码/解码 sns_request 消息、编码和发布/解码数据事件。

异步 COM 端口 nanopb 实用工具可用于物理传感器驱动程序。

| | 传感器实用工具 |

提供常见功能，例如查找传感器实例和获取 SUID 查找传感器的 SUID。

| | 属性实用工具 |

提供用于编码和发布传感器属性的辅助函数。

| | 内存工具 |

提供用于高效内存管理和分配的辅助函数。

| | 数学运算工具 |

提供数学函数和运算的集合，例如矩阵、FFT 和 IIR 滤波器。

| | Printf 工具 |

包含用于格式化和打印数据的辅助函数。

| ## 传感器和传感器实例 QSH 将传感器实现分为两个逻辑单元：传感器和传感器实例。 - 传感器是异步数据的生成者或使用者或二者的组合。 - 每个传感器可以有一个或多个传感器实例。 - 任何传感器数据请求都将创建一个传感器实例或共享一个现有传感器实例。 - 传感器按需创建传感器实例。 - 传感器管理其相应实例的生命周期和配置，并将配置更新以及初始状态事件发送给其客户端。 - 每个传感器实例均使用特定的客户端配置运行。 - 物理传感器的传感器实例对传感器硬件进行编程，使其以所需的配置运行。 - 供应商必须以最少数量的传感器实例处理所有客户端请求。 - 传感器实例生成数据流并发送给所有活动客户端。 - 多个传感器可以共享和配置一个传感器实例，此操作模式通常用于硬件传感器的组合驱动程序，例如： - 加速度计和陀螺仪 - 接近度和环境光 ### 传感器间通信在 QSH 框架内，每个算法和传感器驱动程序都被称为一个传感器，并具有标准的 QSH API。在任何实际用例中，这些传感器之间的信息交换都是必要的。所有传感器之间的通信，包括发送和接收，都是通过数据流上的请求和事件消息进行的。消息净荷使用 nanopb 生成器、编码器和解码器以协议缓冲区格式定义。消息净荷长度、消息 ID 和时间戳（事件）在由 QSH 框架管理的元数据内进行通信。下图展示了数据客户端和数据源之间使用数据流的通信： **图：客户端与源之间的传感器通信** - 客户端发送请求消息，以启用、禁用和重新配置传感器。请求消息始终可寻址到特定的 SUID。当目标传感器接收到请求消息后，就会将其发送至传感器实例进行适当处理。 - 传感器实例会将事件消息异步发送给其已注册的客户端，这些客户端可以是其他传感器或传感器实例。 ### QSH 中的 Nanopb 协议缓存 QSH 使用 nanopb 协议缓存的原因如下： - 传感器之间交换的所有请求和事件消息。 - 传感器或传感器实例必须针对其发送至从属传感器或传感器实例的所有请求的净荷（如果存在）进行编码。 - 传感器或传感器实例必须针对其接收的所有请求的净荷（如果存在）进行解码。 - 传感器或传感器实例必须针对其发布的所有事件的净荷（如果存在）进行编码。 - 传感器或传感器实例必须针对从其从属传感器或传感器实例接收的所有事件的净荷（如果存在）进行解码。 > > > Note > > > 某些请求或事件不含消息主体。在这种情况下，不需要对净荷进行解码或编码，传感器会根据消息 ID 来处理这些消息。 - 表示属性数据 - 所有属性值均采用 nanopb 编码格式。 - 诊断日志数据包净荷 - 诊断日志数据包中的所有净荷均采用 nanopb 编码格式。 Note 有关协议缓存的更多信息，请参阅[协议缓存](https://developers.google.com/protocol-buffers/)和 [nanopb](https://jpa.kapsi.fi/nanopb/)。 ### 传感器 API 消息以下文件引用 API 消息，这些文件包含消息定义，并允许传感器之间进行通信： - `.proto` 文件包含协议缓存消息定义和文档，这使得传感器之间能够进行通信。 - 下表列出了 `/build-qcom-wayland/workspace/sources/sensinghub/sensing-hub/apis/proto/sns_std_*.proto` 文件中定义的 API 标准消息：表：标准原型文件 | 文件 | 说明 | | --- | --- | | `sns_std.proto` | 此文件包含标准定义，例如：

>
>
>

消息 ID

请求消息

批处理规范

属性请求和事件

错误事件

| | `sns_std_sensor.proto` | 此文件包含定义，例如：

>
>
>

请求的消息 ID 以及标准传感器的事件 API

流传输和事件消息

传感器样本状态类型

标准属性 ID

通用属性类型

物理传感器配置事件消息

| | `sns_std_type.proto` | 此文件包含常见的 API 类型定义，例如：

>
>
>

SUID 消息

属性事件和值消息

通用错误类型

| | `sns_std_event_gated_sensor.proto` | 此文件包括事件门控传感器的 API，包括配置消息 ID 和 API 文档。 | - 特定于物理传感器的 API 定义和文档位于传感器特定的 `.proto` 文件中。例如，`sns_accel.proto`，`sns_proximity.proto` 和 `sns_motion_detect.proto`。 - QSH 平台传感器 API 定义和文档位于 `adsp_proc/qsh_platform/api/` 目录中。例如，`sns_timer.proto`，`sns_interrupt.proto` 和 `sns_async_com_port.proto`。 - 以下 proto 文件定义了与 SUID、注册表和诊断相关的框架 API： - `sns_suid.proto` - `sns_registry.proto` - `sns_diag.proto` 后续步骤 - [QSH API](https://docs.qualcomm.com/doc/80-70018-7SC/topic/qsh_api_reference.html#qsh-api-reference) Last Published: Apr 26, 2025 [Previous Topic 功能](https://docs.qualcomm.com/bundle/publicresource/80-70018-7SC/topics/supported_features.md) [Next Topic QSH API](https://docs.qualcomm.com/bundle/publicresource/80-70018-7SC/topics/qsh_api_reference.md)