> ## 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.

# Architecture

If you're familiar with the Qualcomm® sensing hub (QSH) terminology, architecture, and components, and intend to work with QSH APIs or set up sensor information, then see [Qualcomm® sensing hub APIs](./qsh_api_reference).

QSH is also known as Qualcomm® Snapdragon™ sensor core (SSC) that offers a unified event-driven framework for drivers and algorithms. QSH supports the same set of APIs for both the hardware-based and software-based sensors. Additionally, QSH supports asynchronous bus transfer and is extendable for new or custom driver features. QSH consists of the following components:

* QSH client APIs
* Sensor APIs
* Core framework
* Pre-implemented platform sensors
* Vendor-implemented sensors
* Test modules

QSH serves external client applications and provides an interface to access sensor data. The following table describes the terms used in the QSH framework:

**Table : QSH terminology**

<table>
  <thead><tr><th>Term</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td>Sensor</td><td><ul><li>Produces a single type of data, for example, accelerometer, gyroscope, timer, interrupt, and rotation vector.</li><li>Handles asynchronous data.</li><li>Publishes mandatory and custom attributes, and manages its instances.</li></ul></td></tr>
    <tr><td>Sensor instance</td><td><ul><li>Runs at a specific configuration, publishes output data events, and can be created per client request or shared among multiple requests.</li><li>Physical sensors usually share a single instance.</li></ul></td></tr>
    <tr><td>Sensor unique identifier (SUID)</td><td>A unique 128-bit ID for each sensor.</td></tr>
    <tr><td>Service</td><td>A module that provides a synchronous interface for common utilities.</td></tr>
    <tr><td>Data stream</td><td>A unique connection between a client and data source.</td></tr>
    <tr><td>Request</td><td>A configuration message that a client sends to a sensor (see <code>sns\_request.h</code> file).</td></tr>
    <tr><td>Event</td><td>Asynchronous output data message that a sensor instance generates (see <code>sns\_sensor\_event.h</code> file).</td></tr>
    <tr><td>Nanopb</td><td>A small code-size protocol buffer implemented in ANSI C.</td></tr>
  </tbody>
</table>

The following figure shows the QSH architecture:

<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="Figure : QSH architecture" width="721" height="752" data-path="Technologies/Sensors/media/qcs6490/qsh-architecture.svg" />

  <p className="text-sm text-gray-700">Figure: QSH architecture</p>
</div>

The QSH framework includes the following components:

* Application processor software modules

  * Client application: It has the *application main()* or *entry function* that interacts with the QSH client APIs on the application processor side.
  * QSH client APIs: It offers high-level APIs to access services offered by QSH. It simplifies application development by abstracting system complexities and focusing on the application logic. For more information, see [Qualcomm® sensing hub APIs](./qsh_api_reference).

* Low-power processor software modules

  * Client manager: The client manager is in charge of all communications of the low-power processor with the application processor. The following table describes key functionality of the client manager:

**Table : Client manager functions**

<table>
  <thead><tr><th>Function</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td>Translate incoming requests</td><td>The client manager takes incoming requests and translates them into the nanopb protocol buffer format that the QSH can understand. For more information, see <a href="./nanopb_protocol_buffer_in_qsh">Nanopb Protocol Buffer In QSH</a>.</td></tr>
    <tr><td>Translate outgoing indications</td><td>The client manager receives event messages from the QSH and translates these event messages into outgoing indications in the nanopb protocol format that's understandable outside the QSH. For more information, see <a href="./nanopb_protocol_buffer_in_qsh">Nanopb Protocol Buffer In QSH</a>.</td></tr>
    <tr><td>Guarantees batching options</td><td>If a client specifies certain batching (store/accumulate locally) options, the client manager ensures that they meet the batching options. The client manager checks that the data is grouped and sent in the same way that the client has specified, ensuring compliance with the criteria.</td></tr>
  </tbody>
</table>

* Service manager: QSH offers synchronous services through service manager. The sensor and sensor instance use a callback to connect to the service manager.

The `adsp_proc/qsh_platform/inc/sns_service.h` file lists the QSH services. The build process downloads the `adsp_proc` repository. For more information, see [Software build documentation](https://dragonwingdocs.qualcomm.com/Key-Documents/Firmware-Guide/build-firmware). The following table describes the key QSH services that are essential for device drivers.

**Table : QSH services**

<table>
  <thead><tr><th>QSH service</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td>Stream service</td><td><ul><li>This service allows a sensor to create and remove a data stream.</li><li>For more information about the data stream to send requests and receive events over the data streams, see the <code>adsp\_proc/qsh\_platform/inc/sns\_data\_stream.h</code> file.</li></ul></td></tr>
    <tr><td>Attribute service</td><td><ul><li>This service allows a sensor to publish sensor attributes or capabilities.</li><li>All standard attribute IDs and expected value types are defined in the <code>sns\_std\_sensor.proto</code> file.</li><li>All attribute values must be in the nanopb-encoded format. For more information, see <a href="./nanopb_protocol_buffer_in_qsh">Nanopb Protocol Buffer In QSH</a>.</li><li>For more information about the attribute service, see the <code>adsp\_proc/qsh\_platform/inc/services/sns\_attribute\_service.h</code> file.</li></ul></td></tr>
    <tr><td>Diagnostic service</td><td><ul><li>This service provides debug message and data log packet services, and defines standard log packet IDs.</li><li>For more information about the diagnostic service, see the <code>adsp\_proc/qsh\_platform/inc/services/sns\_diag\_service.h</code> file.</li></ul></td></tr>
    <tr><td>Event service</td><td><ul><li>This service allows a sensor to publish output events from the source sensor instances.</li><li>For more information about the event service, see the <code>adsp\_proc/qsh\_platform/inc/services/sns\_event\_service.h</code> file.</li></ul></td></tr>
    <tr><td>Power rail service</td><td><ul><li>This service helps the physical sensors to register and vote for turning the power rails On or Off.</li><li>For more information about the power rail service, see the <code>adsp\_proc/qsh\_platform/inc/services/sns\_pwr\_rail\_service.h</code> file.</li></ul></td></tr>
    <tr><td>Synchronous COM port (SCP) service</td><td><ul><li>Available to the physical sensors to register or deregister the COM port and perform synchronous transfers over the COM port.</li><li>For more information about the SCP service, see the <code>adsp\_proc/qsh\_platform/inc/services/sns\_sync\_com\_port\_service.h</code> file.</li></ul></td></tr>
    <tr><td>General purpose IO (GPIO) service</td><td><ul><li>Available to the physical sensors to read or write the GPIO value.</li><li>Effectively abstracts a low-level CoreBSP layer for controlling the GPIOs.</li><li>For more information about the GPIO service, see the <code>adsp\_proc/qsh\_platform/inc/services/sns\_gpio\_service.h</code> file.</li></ul></td></tr>
    <tr><td>Island service</td><td><ul><li>Available to the physical sensors to request for exiting from the island mode.</li><li>When an application must access DDR or non-island resources that are available in normal mode, the application code can use the island service.</li><li>For more information about the island service, see the <code>adsp\_proc/qsh\_platform/inc/services/sns\_island\_service.h</code> file.</li></ul></td></tr>
    <tr><td>File system service</td><td><ul><li>Available to the physical sensors for the file service management.</li><li>The abstract file system is a part of an application processor stack and is available for local access from a low-power processor.</li><li>For more information about the file system service, see the <code>adsp\_proc/qsh\_platform/inc/services/sns\_file\_service.h</code> file.</li></ul></td></tr>
  </tbody>
</table>

* Platform sensor: QSH provides certain built-in sensors for platform or hardware-specific abstraction that other sensors and sensor instances can use. The following table describes the platform sensors:

**Table : Platform sensors**

<table>
  <thead><tr><th>Platform sensor</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td>Registry sensor</td><td><ul><li>The registry sensor in QSH provides an interface for sensors to access registry data from persistent memory. It allows sensors to create a data stream, send requests, receive data events, subscribe to updates, and remove unnecessary data streams.</li><li>For more information about the registry sensor, see <a href="https://docs.qualcomm.com/doc/80-80023-7A/topic/configuration_customization.html">Configure sensors</a>.</li><li>For more information about the registry sensor API, see the <code>adsp\_proc/qsh\_api/pb/sns\_registry.proto</code> file.</li></ul></td></tr>
    <tr><td>Timer sensor</td><td><ul><li>The timer sensor in the QSH has an interface to initiate periodic or one-shot timers. Sensors that require timers must create a data stream, send requests, and read delivered data events.</li><li>For more information about the timer sensor API, see the <code>adsp\_proc/qsh\_platform/api/public\_sns/sns\_timer.proto</code> file.</li></ul></td></tr>
    <tr><td>Interrupt sensor</td><td><ul><li>The interrupt sensor in the QSH has an interface to register interrupts. Sensors that require interrupts must create a data stream, send requests, and read delivered data events.</li><li>For more information about the interrupt sensor API, see the <code>adsp\_proc/qsh\_platform/api/public\_sns/sns\_interrupt.proto</code> file.</li></ul></td></tr>
    <tr><td>Asynchronous COM port (ASCP) sensor</td><td><ul><li>The ASCP sensor in the QSH has an interface for asynchronous read and write operations over a communication port.</li><li>Sensors that require this feature must create a data stream, send requests, and read delivered data events.</li><li>For more information about the ASCP sensor API, see the <code>adsp\_proc/qsh\_platform/api/public\_sns/sns\_async\_com\_port.proto</code> file.</li><li>The ASCP sensor is typically used by physical sensor drivers to read large first-in-first-out (FIFO).</li></ul></td></tr>
    <tr><td>SUID lookup sensor</td><td><ul><li>The SUID lookup sensor in the QSH provides an API to obtain the SUID of dependent sensors. Its own SUID is available using the <code>sns\_get\_suid\_lookup()</code> function in the <code>sns\_sensor\_util.h</code> file.</li><li>For more information about the SUID lookup sensor API, see the <code>adsp\_proc/qsh\_api/pb/sns\_suid.proto</code> file.</li></ul></td></tr>
    <tr><td>Test sensor</td><td><ul><li>The test sensor customizes and runs sensor-specific use cases.</li><li>The test sensor is available in the <code>adsp\_proc/qsh\_platform/sensors/test</code> directory.</li></ul></td></tr>
  </tbody>
</table>

* QSH utilities: QSH provides several helper utilities for sensors and sensor instances. All the utilities are available in the `adsp_proc/qsh_platform/inc/utils` directory. The following table describes the key QSH utilities:

**Table : QSH utilities**

<table>
  <thead><tr><th>QSH utility</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td>Nanopb encode/decode</td><td><ul><li>Provides common encode and decode helper functions for all the sensors. For example, encode and decode <code>sns\_request</code> messages, encode and publish, and decode data events.</li><li>Asynchronous COM port nanopb utilities are available for physical sensor drivers.</li></ul></td></tr>
    <tr><td>Sensor utils</td><td><ul><li>Provides common functionalities for sensors, such as finding a sensor instance and getting the SUID of a SUID lookup sensor.</li></ul></td></tr>
    <tr><td>Attribute utils</td><td><ul><li>Provides helper functions that encode and publish a sensor attribute.</li></ul></td></tr>
    <tr><td>Memory utils</td><td><ul><li>Provides helper functions for efficient memory management and allocation.</li></ul></td></tr>
    <tr><td>Math utils</td><td><ul><li>Offers a collection of mathematical functions and operations, such as matrix, fast Fourier transform (FFT), and infinite impulse response (IIR) filter.</li></ul></td></tr>
    <tr><td>Printf utils</td><td><ul><li>Includes helper functions to format and print data.</li></ul></td></tr>
  </tbody>
</table>

* OS abstraction (OSA) provides a unified interface to operating system services, abstracting platform-specific implementations.

**Table : OS abstraction (OSA)**

<table>
  <thead><tr><th>OS abstraction (OSA)</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td>Thread management</td><td><ul><li>Provides abstractions for thread creation, deletion, and management.</li><li>Includes thread synchronization primitives (mutexes, semaphores, condition variables).</li><li>Enables platform-independent multi-threaded sensor framework execution.</li></ul></td></tr>
    <tr><td>Signal handling</td><td><ul><li>Abstracts OS signal registration and delivery mechanisms.</li><li>Provides signal attributes configuration and signal mask management.</li><li>Enables event-driven task scheduling in the sensor framework.</li></ul></td></tr>
    <tr><td>Mutex and Synchronization</td><td><ul><li>Provides mutual exclusion primitives for critical sections.</li><li>Abstracts platform-specific locking mechanisms.</li><li>Ensures thread-safe access to shared resources.</li></ul></td></tr>
  </tbody>
</table>

* Platform abstraction layer (PAL) provides hardware and platform-specific abstractions for sensor drivers and framework components.

**Table : Platform abstraction layer (PAL)**

<table>
  <thead><tr><th>Platform abstraction layer (PAL)</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td>GPIO abstraction</td><td><ul><li>Provides platform-independent GPIO pin control.</li><li>Abstracts GPIO configuration, read, and write operations.</li><li>Enables sensor interrupt and control signal handling.</li></ul></td></tr>
    <tr><td>I<sup>2</sup>C/SPI bus abstraction</td><td><ul><li>Abstracts communication bus operations (I<sup>2</sup>C, SPI).</li><li>Provides read/write operations with platform-specific implementations.</li><li>Enables physical sensor communication across different platforms.</li></ul></td></tr>
    <tr><td>Interrupt handling</td><td><ul><li>Abstracts interrupt registration and handling mechanisms.</li><li>Provides interrupt enable/disable and priority management.</li><li>Enables sensor interrupt-driven data acquisition.</li></ul></td></tr>
    <tr><td>Clock and Power management</td><td><ul><li>Abstracts clock configuration and power domain management.</li><li>Provides platform-specific clock gating and power state control.</li><li>Enables efficient power management for sensor subsystems.</li></ul></td></tr>
    <tr><td>Register access</td><td><ul><li>Provides abstracted register read/write operations.</li><li>Abstracts memory-mapped I/O and register access patterns.</li><li>Enables hardware control across different SoC implementations.</li></ul></td></tr>
    <tr><td>UART/Serial communication</td><td><ul><li>Abstracts serial port operations for debug and data logging.</li><li>Provides platform-independent serial communication.</li><li>Enables asynchronous COM port operations for sensor drivers.</li></ul></td></tr>
  </tbody>
</table>

## Sensors and sensor instances

QSH divides the sensor implementation in two logical units: sensor and sensor instance.

* Sensors are producers, consumers, or a combination of producers and consumers of asynchronous data.

  * Each sensor can have one or more sensor instances.
  * Any request to a sensor for data results in the creation of a sensor instance or sharing of an existing sensor instance.

* The sensor creates sensor instances on demand.

  * Sensors manage the lifecycle and configuration of their corresponding instances, and send configuration updates and initial state events to their clients.
  * Each sensor instance operates with a specific client configuration.
  * The sensor instance of a physical sensor programs the sensor hardware to operate at required configuration.
  * Vendors must serve all client requests with a minimal number of sensor instances.
  * The sensor instance generates and sends a stream of data to all the active clients.

* Many sensors can share and configure a single sensor instance. This mode of operation is typical to a combo driver for hardware sensors, such as the following:

  * Accelerometer and gyroscope
  * Proximity and ambient light

**Next steps**

* [Messages](./sensor_api_messages)