# QSH architecture Describes the QSH unified event-driven framework. Note - To continue reading about the APIs or set up sensor information, see [QSH APIs](https://docs.qualcomm.com/doc/80-70018-7/topic/qsh_api_reference.html#qsh-api-reference). - Source code of the low-power application digital signal processor (aDSP), including the QSH framework, is available only to licensed users with authorized access. To upgrade your access, go to: [www.qualcomm.com/support/working-with-qualcomm](https://www.qualcomm.com/support/working-with-qualcomm). QSH, also known as Qualcomm® Snapdragon™ sensor core (SSC), 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 clients and provides a simple interface to access sensor data. The following table describes the terms used in the QSH framework: Table : QSH terminology | **Item** | **Description** | | --- | --- | | Sensor |

Produces a single type of data; for example, accelerometer, gyroscope, timer, interrupt, and rotation vector

Handles asynchronous data

Publishes mandatory and custom attributes, and manages its instances

| | Sensor instance |

Runs at a specific configuration, publishes output data events, and can be created per client request or shared among multiple requests

Physical sensors usually share a single instance

| | Sensor unique identifier (SUID) | A unique 128‑bit ID for each sensor | | Service | A module that provides a synchronous interface for common utilities | | Data stream | A unique connection between a client and data source | | Request | A configuration message that a client sends to a sensor (see `sns_request.h` file) | | Event | Asynchronous output data message that a sensor instance generates (see `sns_sensor_event.h` file) | | Nanopb | A small code-size protocol buffer implemented in ANSI C | The following figure shows the QSH architecture: **Figure: QSH architecture** 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 [QSH APIs](https://docs.qualcomm.com/doc/80-70018-7/topic/qsh_api_reference.html#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. It’s responsible for the following: Table : Client manager functions | Function | Description | | --- | --- | | Translate incoming requests | The client manager takes incoming requests and translates them into a format that the QSH can understand. | | Translate outgoing indications | The client manager receives event messages from the QSH and translates these event messages into outgoing indications in a format that is understandable outside the QSH. | | Guarantees batching options | 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 as the client has specified, ensuring compliance with the criteria. | - **Service manager**: QSH offers synchronous services through its service manager. The sensor and sensor instance APIs use a callback to connect to this service manager. The `adsp_proc/qsh_platform/inc/sns_service.h` file lists the services available in the QSH, also referred as QSH services. The following table describes the key QSH services that are essential for device drivers. Table : QSH services | QSH service | Description | | --- | --- | | Stream service |

Allows creating and removing a data stream with a sensor.

See the adsp_proc/qsh_platform/inc/sns_data_stream.h file for data stream API to send requests and receive events over the data streams.

| | Attribute service |

Allows a sensor to publish sensor attributes or capabilities.

All standard attribute IDs and expected value type are defined in the sns_std_sensor.proto file.

All attribute values must be in the nanopb-encoded format.

For more information about the API, see the adsp_proc/qsh_platform/inc/services/sns_attribute_service.h file.

| | Diagnostic service |

Provides debug message and data log packet services, and defines standard log packet IDs.

For more information about the API, see the adsp_proc/qsh_platform/inc/services/sns_diag_service.h file.

| | Event service |

Allows to publish output events from source sensor instances.

For more information about the API, see the adsp_proc/qsh_platform/inc/services/sns_event_service.h file.

| | Power rail service |

Available to the physical sensors to register and vote for the power rails (ON/OFF).

For more information about the API, see the adsp_proc/qsh_platform/inc/services/sns_pwr_rail_service.h file.

| | Synchronous COM port (SCP) service |

Available to the physical sensors to register/deregister the COM port and perform synchronous transfers over the COM port.

For more information about the API, see the adsp_proc/qsh_platform/inc/services/sns_sync_com_port_service.h file.

| | GPIO service |

Available to the physical sensors to read/write the GPIO value.

Effectively abstracts a low-level CoreBSP layer for controlling the GPIOs.

For more information about the API, see the adsp_proc/qsh_platform/inc/services/sns_gpio_service.h file.

| | Island service |

Available to the physical sensors to request for island exit.

When an application must access DDR or nonisland resources, the application code can use the island service.

For more information about the API, see the adsp_proc/qsh_platform/inc/services/sns_island_service.h file.

| | File system service |

Available to the physical sensors for the file service management.

The abstract file system is a part of an application processor stack and can be available for local access from a low-power processor.

For more information about the API, see the adsp_proc/qsh_platform/inc/services/sns_file_service.h file.

| - **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 | Platform sensor | Description | | --- | --- | | Registry sensor |

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.

For more information about the registry sensor, see Configure sensors in Qualcomm Linux Sensors Guide - Addendum.

>
>
> Note
>
>
> [Qualcomm Linux Sensors Guide - Addendum](https://docs.qualcomm.com/bundle/resource/topics/80-70018-7A/overview.html) is available to licensed developers with authorized access.

The registry sensor API is documented in the adsp_proc/qsh_api/pb/sns_registry.proto file.

| | Timer sensor |

The timer sensor in the QSH offers 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.

The timer sensor API is documented in the adsp_proc/qsh_platform/api/public_sns/sns_timer.proto file.

| | Interrupt sensor |

The interrupt sensor in the QSH offers an interface to register interrupts. Sensors that require interrupts must create a data stream, send requests, and read delivered data events.

The interrupt sensor API is documented in the adsp_proc/qsh_platform/api/public_sns/sns_interrupt.proto file.

| | Asynchronous COM port (ASCP) sensor |

The ASCP sensor in the QSH offers an interface for asynchronous read and write operations over a communication port.

Sensors that require this feature must create a data stream, send requests, and read delivered data events.

The ASCP sensor API is documented in the adsp_proc/qsh_platform/api/public_sns/sns_async_com_port.proto file.

>
>
> Note
>
>
> The ASCP sensor is typically used by physical sensor drivers to read large FIFO. | | SUID lookup sensor |

The SUID lookup sensor in the QSH provides an API to obtain the SUID of dependent sensors. Its own SUID is available using the sns_get_suid_lookup() function in the sns_sensor_util.h file.

The adsp_proc/qsh_api/pb/sns_suid.proto file documents the SUID lookup sensor API.

| | Test sensor |

The test sensor customizes and runs sensor-specific use cases.

The test sensor is available in the adsp_proc/qsh_platform/sensors/test directory.

| - **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 utilities: Table : QSH utilities | QSH utility | Description | | --- | --- | | Nanopb encode/decode |

Provides common encode/decode helper functions for all the sensors. For example, encode/decode sns_request messages, encode and publish/decode data events.

Asynchronous COM port nanopb utilities are available for physical sensor drivers.

| | Sensor utils |

Provides common functionalities, such as finding a sensor instance and getting the SUID of a SUID lookup sensor.

| | Attribute utils |

Provides helper functions that encode and publish a sensor attribute.

| | Memory utils |

Provides helper functions for efficient memory management and allocation.

| | Math utils |

Offers a collection of mathematical functions and operations such as matrix, FFT, and IIR filter.

| | Printf utils |

Includes helper functions to format and print data.

| ## Sensor and sensor instances QSH divides the sensor implementation in two logical units: sensor and sensor instance. - Sensors are producers or 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 sends 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: - Accelerometer and gyroscope - Proximity and ambient light ### Communication among sensors Every algorithm and sensor driver within the QSH framework is called a sensor, with the standard QSH APIs. Information exchange across these sensors is necessary for any real use case. All communication to, from, and among the sensors is performed through the request and event messages over data streams. The message payloads are defined in the protocol buffer format, using the nanopb generator, encoder, and decoder. The message payload length, message ID, and timestamp (for events) are communicated within the metadata managed by the QSH framework. The following figure shows the communication between the data client and the data source, using the data stream: **Figure: Sensor communication between client and source** - The client sends request messages to enable, disable, and reconfigure a sensor. Request messages are always addressed to a specific SUID. After the target sensor receives the request message, it sends the request to the sensor instance for proper handling. - Sensor instances send event messages asynchronously to their registered clients, which can be other sensors or sensor instances. ### Nanopb protocol buffer in QSH The QSH uses nanopb protocol buffer for the following reasons: - All the request and event messages that are exchanged between the sensors. - A sensor or sensor instance must encode the payload (if present) for all requests it sends to its dependents. - A sensor or sensor instance must decode the payload (if present) for all requests it receives. - A sensor or sensor instance must encode the payload (if present) for all events it publishes. - A sensor or sensor instance must decode the payload (if present) for all events it receives from its dependents. > > > Note > > > Certain requests or events don’t have a message body. In this case, decoding or encoding the payload isn’t expected, and the sensor processes these messages based on their message ID. - Representing the attribute data - All attribute values are in the nanopb-encoded format. - Diagnostic log packet payload - All payloads in the diagnostic log packets are in the nanopb-encoded format. Note For more information about protocol buffers, see [Protocol-buffers](https://developers.google.com/protocol-buffers/) and [nanopb](https://jpa.kapsi.fi/nanopb/). ### Sensor API messages The following files refer the API messages, which contain the message definitions, and allow communication between sensors: - The `.proto` files contain the protocol buffer message definitions and documentation that allow communication between sensors. - The following table lists the API standard message defined in the `/build-qcom-wayland/workspace/sources/sensinghub/sensing-hub/apis/proto/sns_std_*.proto` file: Table : Standard proto files | File | Description | | --- | --- | | `sns_std.proto` | This file includes standard definitions, such as:

>
>
>

Message ID

Request message

Batching specification

An attribute request and event

An error event

| | `sns_std_sensor.proto` | This file includes definitions, such as:

>
>
>

Message IDs for request and event APIs of standard sensors

Streaming and event messages

Sensor sample status types

Standard attribute IDs

Common attribute types

A physical sensor configuration event message

| | `sns_std_type.proto` | This file includes common API-type definitions, such as:

>
>
>

SUID messages

Attribute events and value messages

Common error types

| | `sns_std_event_gated_sensor.proto` | This file includes the API for event gated sensors, encompassing the configuration message ID and API documentation. | - Physical sensor-specific API definitions and documentation are present in the sensor-specific `.proto` files. For example, `sns_accel.proto`, `sns_proximity.proto` and `sns_motion_detect.proto`. - The QSH platform sensor API definitions and documentation are present in the `adsp_proc/qsh_platform/api/` directory. For example, `sns_timer.proto`, `sns_interrupt.proto`, and `sns_async_com_port.proto`. - The following proto files defines the framework-related APIs for SUID, registry, and diagnostics: - `sns_suid.proto` - `sns_registry.proto` - `sns_diag.proto` Next steps - [QSH APIs](https://docs.qualcomm.com/doc/80-70018-7/topic/qsh_api_reference.html#qsh-api-reference) Last Published: Apr 08, 2025 [Previous Topic Features](https://docs.qualcomm.com/bundle/publicresource/80-70018-7/topics/supported_features.md) [Next Topic QSH APIs](https://docs.qualcomm.com/bundle/publicresource/80-70018-7/topics/qsh_api_reference.md)