Page-1

# Architecture Source: [https://docs.qualcomm.com/doc/80-70014-7/topic/architecture.html](https://docs.qualcomm.com/doc/80-70014-7/topic/architecture.html) Note: Source code of the low-power processor (aDSP), including the QSH framework is available only for the Authorized users. To upgrade your access, go to: [www.qualcomm.com/support/working-with-qualcomm](https://www.qualcomm.com/support/working-with-qualcomm). Note: To continue reading about the APIs and/or set up sensor information, skip directly to [Interfaces](https://docs.qualcomm.com/bundle/publicresource/topics/80-70014-7/qsh_api_reference.html). The QSH synonymous with the Qualcomm® Snapdragon™ sensors core (SSC), offers a unified event-driven framework for drivers and algorithms. The QSH supports the same set of APIs for both the hardware-based and software-based sensors. Additionally, the QSH supports asynchronous bus transfer and is easily extendable for new or custom driver features. The QSH consists of various components that include the QSH client APIs, sensor APIs, a core framework, pre-implemented platform sensors, vendor-implemented sensors, and the test modules. It serves external clients and provides a simple interface to access the sensor data. Figure : QSH architecture The following table lists the QSH terminology to understand the QSH framework and its usage. 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 sent by a client to a sensor (see
`sns_request.h` file) | | Event | Asynchronous output data message generated by a sensor instance
(see `sns_sensor_event.h` file) | | Nanopb | Nanopb is a small code-size protocol buffer implemented in ANSI
C | The following resources give an in-depth information on the QSH architecture: - **Application processor software modules** - **Application processor**: The block contains the *application main() or entry function* that interacts with the QSH client APIs on the application processor side. - **QSH client APIs**: The block offers high-level APIs to access services offered by the QSH. It simplifies application development by abstracting system complexities and enables it to focus on the application logic. For more information, see [Interfaces](https://docs.qualcomm.com/bundle/publicresource/topics/80-70014-7/qsh_api_reference.html). - **Low-power processor software modules** - **Client manager**: The block is in charge of all communications of the low-power processor with the application processor. The client manager is responsible for the following: - Translates incoming requests: The client manager takes incoming requests and translates them into a format that the QSH can understand. - Translates outgoing indications: When the client manager receives event messages from the QSH, the client manager translates these event messages into outgoing indications in a format that can be understood outside the QSH. - Guarantees batching options: If a client specifies certain batching (store/accumulate locally) options, then the client manager ensures that the batching options are met. This means it checks that the data is grouped and sent in the way that the client has specified. - **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 services available in the QSH, also referred as QSH services, are listed in the `adsp_proc/qsh_platform/inc/sns_service.h` file. The following table describes the key QSH services that are essential for device drivers. Table : QSH services | QSH service | Description | | --- | --- | | Stream service |

The stream service provides the ability to
create and remove 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 |

The attribute service allows a sensor to publish
its 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 on the API, see the
adsp_proc/qsh_platform/inc/services/sns_attribute_service.h
file.

| | Diagnostic service |

The diagnostic service provides debug message
and data log packet services, and defines standard
log packet IDs.

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

| | Event service |

The event service provides the ability to
publish output events from source sensor
instances.

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

| | Power rail service |

The power rail service is available to the
physical sensors to register and vote for the
power rails (ON/OFF).

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

| | Synchronous COM port (SCP) service |

The SCP service is available to the physical
sensors to register/deregister the COM port and
perform synchronous transfers over the COM
port.

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

| | GPIO service |

The GPIO service is available to the physical
sensors to read/write the GPIO value.

The service effectively abstracts a low-level
CoreBSP layer for controlling the GPIOs.

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

| | Island service |

The island service is available to the physical
sensors to request for island exit.

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

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

| | File system service |

The file system service is 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 on the API, see the
adsp_proc/qsh_platform/inc/services/sns_file_service.h
file.

| - **Platform sensor**: QSH provides some built-in sensors for platform or hardware-specific abstraction that can be used by other sensors and sensor instances. The following table describes the platform sensors. Table : Platform sensors | Platform sensor | Description | | --- | --- | | Registry sensor |

The registry sensor in the 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 on the registry sensor, see
Configure in Qualcomm Linux
Sensors Guide - Addendum.

Note: Qualcomm Linux
Sensors Guide - Addendum is accessible only
to the Authorized users.

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 for registering interrupts. Sensors
requiring 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/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 the 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 via the
sns_get_suid_lookup() function in
the sns_sensor_util.h file.

The SUID lookup sensor API is documented in the
adsp_proc/qsh_api/pb/sns_suid.proto
file.

| | Test sensor | A test sensor is available in the
`adsp_proc/qsh_platform/sensors/test`
directory to customize and run sensor-specific use
cases. | - **QSH utilities**: QSH provides several helper utilities for sensors and sensor instances. For all available utilities, see `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 functionality, such as finding a sensor
instance and getting the SUID of a SUID lookup
sensor.

| | Attribute utils |

Provides helper function that encodes and publishes a
sensor attribute.

| | Memory, math, and printf utils. | | ## Communication between sensors Source: [https://docs.qualcomm.com/doc/80-70014-7/topic/architecture.html](https://docs.qualcomm.com/doc/80-70014-7/topic/architecture.html) Every algorithm and sensor driver within the QSH framework, is referred to as a sensor with the standard QSH APIs. Information exchange across these sensors is necessary for any real use case. The following resources describe about the communication between these sensors. All communication to, from, and among the sensors is performed through the request and event messages over data streams. Message payloads are defined in the protocol buffer format, using the nanopb generator, encoder, and decoder. Message payload length, message ID, and timestamp (in the case of events) are communicated within metadata managed by the QSH framework. Figure : Sensor communication Request messages are sent to enable, disable, and/or 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 may be other sensors or sensor instances. ### Sensor and sensor instances - Sensors are producers and/or consumers of asynchronous data - Each sensor can have one or more sensor instances - Each sensor instance operates with a specific configuration - Any request to a sensor for data, results in the creation of a sensor instance or sharing of an existing sensor instance - Sensor instances are created on-demand, as determined by the sensor - Sensors fully manage the lifecycle and configuration of their corresponding instances and are responsible for sending configuration updates and initial state events to their clients - Vendors should serve all client requests with as few sensor instances as possible - A stream of data generated by a sensor instance is sent to all the active clients - Multiple sensors can share and configure a single sensor instance ‒ this mode of operation is typically for a combo driver for hardware sensors. Here, the sensors represent the supported data types, and the sensor instance is the sole module that communicates and configures the hardware. ## Nanopb protocol buffer in QSH Source: [https://docs.qualcomm.com/doc/80-70014-7/topic/architecture.html](https://docs.qualcomm.com/doc/80-70014-7/topic/architecture.html) The QSH uses nanopb protocol buffer for: - All the request and event messages exchanged between the sensors - A sensor/sensor instance must encode the payload (if present) for all requests it sends to its dependants. - A sensor/sensor instance must decode the payload (if present) for all requests it receives. - A sensor/sensor instance must encode the payload (if present) for all events it publishes. - A sensor/sensor instance must decode the payload (if present) for all events it receives from its dependants. - Some requests/events do not have a message body. In this case, decoding/encoding the payload is not expected. Such messages are processed by their message ID. - Representing the attribute data - All attribute values are in the nanopb-encoded format - Diag log packet payload - All payloads in the diag log packets are in the nanopb-encoded format For more information on Google protocol buffers and nanopb respectively, see [Protocol-buffers](https://developers.google.com/protocol-buffers/) and [nanopb](https://jpa.kapsi.fi/nanopb/). ## Sensor API messages Source: [https://docs.qualcomm.com/doc/80-70014-7/topic/architecture.html](https://docs.qualcomm.com/doc/80-70014-7/topic/architecture.html) The following API messages are used for communication between sensors: - The `.proto`files contain the following elements for communication between sensors: - Protocol buffer message definitions - Documentation - The following table lists the standard message definitions 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 a message
ID, request message, batching specification, an attribute
request and event, and 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, and 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, and 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`. - 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`. - Framework-related APIs for SUID, registry, and diag are defined in the following proto files: - `sns_suid.proto` - `sns_registry.proto` - `sns_diag.proto` Last Published: Jul 12, 2024 [Previous Topic Features](https://docs.qualcomm.com/bundle/publicresource/80-70014-7/topics/supported_features.md) [Next Topic Interfaces](https://docs.qualcomm.com/bundle/publicresource/80-70014-7/topics/qsh_api_reference.md)