# Services

## Attribute Service

All Sensors may publish a series of attributes, where each is a key-value pair. The key is an enum value uniquely identifying the attribute, while the value is an Protocol Buffer encoded message of type sns\_std\_attr. These are attributes of the Sensor, not of the Sensor Instance, and hence cannot contain client-specific information. Most attributes are expected to be published at boot-up, but Sensors are permitted to publish updated attributes later, if the state of the system changes. All clients of active Sensor Instances, as well as any client who previously registered for attribute information, will receive an update with the new values. Some attributes are to be used solely by the Framework, others are intended to be used by the Sensor client, and some will be used by both. Note that these attributes will be seen and shared between Sensor objects. External clients may receive a supersubset of this list, depending on the design of the QMI proxy module (i.e. some attributes may be filtered-out, while others, such as the maximum batch size, may be added-in). However, all clients will receive the same list, no filtering is performed on a per-client basis. The Framework shall define a list of “standard” attributes IDs (sns\_std\_sensor\_attr\_id). These will be well known “keys” distributed by Qualcomm.

- struct sns\_attribute\_service

    - The attribute service. Can be obtained from sns\_service\_managere::getService.

Public Members

- [sns\_service](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv411sns_service) service

    - Service information.

- const struct [sns\_attribute\_service\_api](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv425sns_attribute_service_api) \*api

    - Public API provided by the Framework to be used by the Sensor.

- struct sns\_attribute\_service\_api

    - API made available to Sensors, to manage their published attributes.

Public Members

- uint32\_t struct\_len

    - Length of [sns\_attribute\_service\_api](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#structsns__attribute__service__api) structure.

- [sns\_rc](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv46sns_rc) (\*publish\_attribute)([sns\_attribute\_service](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv421sns_attribute_service) \*service, struct [sns\_sensor](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv410sns_sensor) \*sensor, void const \*attribute, uint32\_t attribute\_len, sns\_attribute\_id attribute\_id, bool completed)

    - Publish a new or updated attribute. Set completed flag to true, once a complete set of attributes has been published. This does not preclude updating attributes again in the future. Standard attribute types are defined in sns\_std\_sensor\_attr\_id.

- Param service:

    - **[out]** Attribute service reference.

- Param sensor:

    - **[in]** Whose attributes to publish.

- Param attribute:

    - **[in]** Encoded attribute (sns\_std\_attr) to publish.

- Param completed:

    - **[in]** Whether this is the last attribute in this publish set.

- Return:

    - sns\_rc , SNS\_RC\_SUCCESS Success, Any other value Failure.

## Diag Service

Manages Diagnostic Services for Sensors and Sensor Instances.

Defines

- \_\_FILENAME\_\_

    - Find the base filename using **FILE** macro. Fall back to generic run-time computation for other compilers.

Enums

- enum sns\_diag\_sensor\_state\_log

    - Types of sensor state logs.

*Values:*

- enumerator SNS\_DIAG\_SENSOR\_STATE\_LOG\_INTERNAL

    - Internal sensor state logs.

- enumerator SNS\_DIAG\_SENSOR\_STATE\_LOG\_RAW

    - Raw state logs for drivers

- enumerator SNS\_DIAG\_SENSOR\_STATE\_LOG\_INTERRUPT

    - Sensor interrupt state logs.

- enum sns\_message\_priority

    - Priority levels for debug messages.

*Values:*

- enumerator SNS\_LOW

    - Low Priority levels for debug messages.

- enumerator SNS\_MED

    - Medium priority levels for debug messages.

- enumerator SNS\_HIGH

    - High priority levels for debug messages.

- enumerator SNS\_ERROR

    - Error debug messages.

- enumerator SNS\_FATAL

    - Fatal error debug messages.

- struct sns\_diag\_service

    - The Diagnostics Manager. Will be obtained from [sns\_service\_manager::get\_service](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#structsns__service__manager_1a68895be9b0bd143f457977468a580e81).

Public Members

- [sns\_service](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv411sns_service) service

    - Service information.

- const struct [sns\_diag\_service\_api](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv420sns_diag_service_api) \*api

    - Public api provided by the framework to be used by the sensor.

- struct sns\_diag\_service\_api

    - Diag Service APIs.

Public Members

- uint32\_t struct\_len

    - Length of [sns\_diag\_service\_api](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#structsns__diag__service__api) structure.

- uint32\_t (\*get\_max\_log\_size)([sns\_diag\_service](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv416sns_diag_service) const \*service)

    - Get max supported log packet size.

- Param service:

    - **[in]** Diag Service reference.

- Return:

    - - uint32\_t Maximum size of a log packet supported by the Framework (bytes).

- void \*(\*alloc\_log)([sns\_diag\_service](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv416sns_diag_service) \*service, struct [sns\_sensor\_instance](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv419sns_sensor_instance) \*instance, struct [sns\_sensor\_uid](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv414sns_sensor_uid) const \*sensor\_uid, uint32\_t log\_size, [sns\_diag\_sensor\_state\_log](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv425sns_diag_sensor_state_log) log\_type)

    - Allocate memory for a log packet Memory allocated by this function is used to store log packet information and is returned as part of sns\_diag\_encode\_log\_cb for encoding. Only a single outstanding allocation for log packet memory is allowed per log type as defined in sns\_diag\_sensor\_state\_log.

- Param service:

    - **[in]** Diag Service.

- Param instance:

    - **[in]** Instance pointer of the sensor.

- Param sensor\_uid:

    - **[in]** UID of sensor for which log packet is being created.

- Param log\_size:

    - **[in]** Requested size in bytes to store log packet information.

- Param log\_type:

    - **[in]** Type of log packet.

- Return:

    - - void\* Allocated memory pointer of a log packet for an instance;
- NULL if out of memory or logging disabled for this sensor.

- [sns\_rc](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv46sns_rc) (\*submit\_log)([sns\_diag\_service](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv416sns_diag_service) \*service, struct [sns\_sensor\_instance](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv419sns_sensor_instance) \*instance, struct [sns\_sensor\_uid](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv414sns_sensor_uid) const \*sensor\_uid, uint32\_t log\_size, void \*log, [sns\_diag\_sensor\_state\_log](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv425sns_diag_sensor_state_log) log\_type, uint32\_t encoded\_log\_size, sns\_diag\_encode\_log\_cb encode\_log\_cb)

    - Submit a log packet.

- Param service:

    - **[in]** This diag instance.

- Param instance:

    - **[in]** Instance pointer of the sensor submitting the log.

- Param sensor\_uid:

    - **[in]** UID of the sensor submitting the log.

- Param log\_size:

    - **[in]** Size of the log packet information in bytes.

- Param log:

    - **[in]** Pointer to the log packet information.

- Param log\_type:

    - **[in]** Type of log.

- Param encoded\_log\_size:

    - **[in]** Size of the encoded log in bytes.

- Param encode\_log\_cb:

    - **[in]** Function used to encode log.

- Return:

    - - SNS\_RC\_NOT\_AVAILABLE If the log packet is currently disabled.
- SNS\_RC\_INVALID\_TYPE If the suid is not recognized.
- SNS\_RC\_SUCCESS log Packet was successfully submitted.

- void (\*sensor\_printf\_v2)([sns\_diag\_service](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv416sns_diag_service) \*service, struct [sns\_sensor](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv410sns_sensor) \*sensor, struct sns\_msg\_const\_type const \*msg\_struct, uint32\_t nargs, ...)

    - printf() style function for printing a debug message from sensor. Limited printf formatting support (only 32-bit int argument supported).

- Param service:

    - **[in]** This diag service instance.

- Param sensor:

    - **[in]** Pointer to the sensor printing this message.

- Param msgs\_struct:

    - **[in]** Diag-defined static const msg\_v2/v4\_const\_type for the message.

- Param nargs:

    - **[in]** Number of arguments included in “…”.

- Return:

    - - None.

- void (\*sensor\_inst\_printf\_v2)([sns\_diag\_service](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv416sns_diag_service) \*service, struct [sns\_sensor\_instance](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv419sns_sensor_instance) \*instance, struct sns\_msg\_const\_type const \*msg\_struct, uint32\_t nargs, ...)

    - printf()-like function for printing a debug message from sensor instance. limited printf formatting support (only 32-bit int argument supported).

- Param service:

    - **[in]** This diag service instance.

- Param sensor:

    - **[in]** Instance pointer to the sensor instance printing this message.

- Param diag:

    - **[in]** Defined static const msg\_v2/v4\_const\_type for the message.

- Param number:

    - **[in]** Number of arguments included in “…”.

- Return:

    - - None.

## Event Service

Handles the storage of all Sensor events. The ThreadManager is notified when new events are available for processing.

- struct sns\_event\_service

    - The Event Service. Will be obtained from [sns\_service\_manager::get\_service](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#structsns__service__manager_1a68895be9b0bd143f457977468a580e81).

Public Members

- [sns\_service](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv411sns_service) service

    - Service information.

- const struct [sns\_event\_service\_api](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv421sns_event_service_api) \*api

    - Public API provided by the Framework to be used by the Sensor.

- struct sns\_event\_service\_api

    - Event Service APIs.

Public Members

- uint32\_t struct\_len

    - Length of [sns\_event\_service\_api](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#structsns__event__service__api) structure.

- uint32\_t (\*get\_max\_event\_size)([sns\_event\_service](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv417sns_event_service) const \*service)

    - Get the maximum event size supported by the Framework.

- Param service:

    - **[in]** Event Service reference.

- Return:

    - - uint32\_t The maximum event size supported by the Framework.

- struct [sns\_sensor\_event](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv416sns_sensor_event) \*(\*alloc\_event)([sns\_event\_service](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv417sns_event_service) \*service, struct [sns\_sensor\_instance](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv419sns_sensor_instance) \*instance, uint32\_t event\_len)

    - Allocate an empty event buffer. Output will not be sent to clients until publish\_event is called. alloc\_event may not be called again until publish\_event is called. From whichever Sensor Instance API called alloc\_event, within that same function block publish\_event must be called. If the function block returns without doing so, the Framework will free the buffer and return it to the pool.

Note

An output Event may consist of multiple logical samples. These samples will be consumed individually and sequentially by the client.

- Param service:

    - **[in]** Event Service reference.

- Param instance:

    - **[in]** Sensor Instance which will form/publish the event.

- Param event\_len:

    - **[in]** Buffer space to allocate for the Event.

- Return:

    - - sns\_sensor\_event\* All allocations are guaranteed to succeed unless event\_len exceeds get\_max\_buffer\_size().

- [sns\_rc](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv46sns_rc) (\*publish\_event)([sns\_event\_service](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv417sns_event_service) \*service, struct [sns\_sensor\_instance](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv419sns_sensor_instance) \*instance, struct [sns\_sensor\_event](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv416sns_sensor_event) \*event, struct [sns\_sensor\_uid](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv414sns_sensor_uid) const \*sensor\_uid)

    - Publish an event, previously allocated by alloc\_event, to all registered clients. Client may specify the SUID of the data being sent. This SUID must match the SUID of the Sensor to which a client sent its enable request. Must be called within the same block as alloc\_event.

- Param service:

    - **[in]** Event Service reference.

- Param instance:

    - **[in]** Sensor Instance which formed the event.

- Param event:

    - **[in]** Event to publish to all registered clients.

- Param sensor\_uid:

    - **[in]** SUID of this published data, if set to NULL, framework determines suid from instance parameter.

- Return:

    - - SNS\_RC\_SUCCESS Success.
- Any other value Failure.

- [sns\_rc](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv46sns_rc) (\*publish\_error)([sns\_event\_service](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv417sns_event_service) \*service, struct [sns\_sensor\_instance](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv419sns_sensor_instance) \*instance, [sns\_rc](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv46sns_rc) reason)

    - Publish a generic error event. This event will be delivered to all active clients. Upon receipt, the Framework will destroy this Sensor Instance, and all associated state. This is a helper function; an error event could also be generated and published using the alloc\_event/publish\_event API.

- Param service:

    - **[in]** Event Service reference.

- Param instance:

    - **[in]** Sensor Instance.

- Param reason:

    - **[in]** - SNS\_RC\_INVALID\_STATE: The Sensor Instance entered an invalid state.

- SNS\_RC\_NOT\_AVAILABLE: A software and/or hardware dependency has been lost.

- Return:

    - - SNS\_RC\_SUCCESS Success.
- Any other value Failure.

## File Service

Service for sensor file service management.

- struct sns\_file\_service

    - The Sensor File Service. Will be obtained from [sns\_service\_manager::get\_service](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#structsns__service__manager_1a68895be9b0bd143f457977468a580e81).

Public Members

- [sns\_service](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv411sns_service) service

    - Service information.

- struct [sns\_file\_service\_api](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv420sns_file_service_api) \*api

    - Public api provided by the framework to be used by the sensor.

- struct sns\_file\_service\_api

    - public state used by the Framework for the sensor file service.

Public Members

- uint32\_t struct\_len

    - Length of [sns\_file\_service\_api](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#structsns__file__service__api) structure.

- FILE \*(\* fopen )(const char \*restrict filename, const char \*restrict mode)

    - Opens the file whose name is the string pointed to by filename and assosiates a stream with it.

- Param filename:

    - **[in]** Absolute path of file to open.

- Param mode:

    - **[in]** What open mode to use.

- Return:

    - - FILE\* The associated file stream.

- size\_t (\*fwrite)(void const \*ptr, size\_t size, size\_t count, FILE \*stream)

    - Attempts to write the buffer pointed to by ptr whose size is specified by size upto n elements specifed by count, to the file\_handle.

- Param ptr:

    - **[in]** Pointer to the buffer.

- Param size:

    - **[in]** Size of the data type.

- Param count:

    - **[in]** Number of elements to be written.

- Param stream:

    - **[in]** The file stream to which to write.

- Return:

    - - size\_t The number of elements successfully written.

- size\_t (\*fread)(void \*ptr, size\_t size, size\_t count, FILE \*stream)

    - Attempts to read size n elements specified by count from the buffer ptr, each size bytes long, from the file\_handle.

- Param ptr:

    - **[in]** Pointer to the buffer.

- Param size:

    - **[in]** Size of the data type.

- Param count:

    - **[in]** Number of elements to be read.

- Param stream:

    - **[in]** The file stream from which to read.

- Return:

    - - size\_t The number of elements successfully read.

- int (\*fclose)(FILE \*stream)

    - Closes the file pointed by stream.

- Param stream:

    - **[in]** The file stream.

- Return:

    - - 0 if successful
- EOF otherwise.

- int (\*fsize)(const char \*path, off\_t \*size)

    - Gets the size of the file.

- Param path:

    - **[in]** Absolute path of file.

- Param size:

    - **[in]** Destination for the file size.

- Return:

    - - SNS\_RC\_SUCCESS Success.
- Any other value Failure.

## GPIO service

Provides a synchronous API to read/write from/to output GPIO pins.

- struct sns\_gpio\_service

    - The GPIO service. Can be obtained from [sns\_service\_manager::get\_service](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#structsns__service__manager_1a68895be9b0bd143f457977468a580e81).

Public Members

- [sns\_service](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv411sns_service) service

    - Service information.

- const struct [sns\_gpio\_service\_api](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv420sns_gpio_service_api) \*api

    - Public API provided by the Service to be used by the Sensor.

- struct sns\_gpio\_service\_api

    - API made available to Sensors.

Public Members

- uint32\_t struct\_len

    - Length of [sns\_gpio\_service\_api](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#structsns__gpio__service__api) structure.

- [sns\_rc](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv46sns_rc) (\*read\_gpio)(uint32\_t gpio, bool is\_chip\_pin, sns\_gpio\_state \*state)

    - Read current state of a general purpose input pin.

- Param gpio:

    - **[in]** GPIO pin to read.

- Param is\_chip\_pin:

    - **[in]** True if GPIO is chip level; false otherwise

- Param state:

    - **[out]** Current gpio state.

- Return:

    - - SNS\_RC\_SUCCESS Success.
- Any other value Failure.

- [sns\_rc](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv46sns_rc) (\*write\_gpio)(uint32\_t gpio, bool is\_chip\_pin, sns\_gpio\_drive\_strength drive\_strength, sns\_gpio\_pull\_type pull, sns\_gpio\_state state)

    - Write a value to a general purpose output pin.

- Param gpio:

    - **[in]** GPIO pin to write to.

- Param is\_chip\_pin:

    - **[in]** True if GPIO is chip level; false otherwise

- Param drive\_strength:

    - **[in]** Drive strength config.

- Param pull:

    - **[in]** Pull type config.

- Param state:

    - **[in]** Output state to set for the gpio.

- Return:

    - - SNS\_RC\_SUCCESS Success.
- Any other value Failure.

## Island service

Provides a synchronous API to request island mode exit.

- struct sns\_island\_service

    - The island service. Can be obtained from sns\_service\_managere::getService.

Public Members

- [sns\_service](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv411sns_service) service

    - Service information.

- struct [sns\_island\_service\_api](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv422sns_island_service_api) \*api

    - Public API provided by the Service to be used by the Sensor.

- struct sns\_island\_service\_api

    - API made available to Sensors.

Public Members

- uint32\_t struct\_len

    - Length of [sns\_island\_service\_api](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#structsns__island__service__api) structure.

- [sns\_rc](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv46sns_rc) (\*sensor\_island\_exit)([sns\_island\_service](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv418sns_island_service) \*service, struct [sns\_sensor](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv410sns_sensor) const \*sensor)

    - Request exit from island mode available to a Sensor.

Note

: Sensors typically use this service API to request island mode exit from an island mode function before calling a normal mode function. The normal mode function should be called only if this API returns SNS\_RC\_SUCCESS. Typical uses are:

1. Physical sensor self-test:

    - handling timer/interrupt events for self-test execution.
2. Handling registry sensor events.

- Param service:

    - **[in]** Island service reference.

- Param sensor:

    - **[in]** Sensor reference that is requesting island exit. NULL if an instance is requesting island exit.

- Return:

    - - SNS\_RC\_SUCCESS Success.
- Any other value Failure.

- [sns\_rc](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv46sns_rc) (\*sensor\_instance\_island\_exit)([sns\_island\_service](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv418sns_island_service) \*service, struct [sns\_sensor\_instance](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv419sns_sensor_instance) const \*instance)

    - Request exit from island mode available to a Sensor Instance.

Note

Sensor Instances typically use this service API to request island mode exit from an island mode function before calling a normal mode function. The normal mode function should be called only if this API returns SNS\_RC\_SUCCESS. Typical uses are:

1. Physical sensor self-test:

    - handling timer/interrupt events for self-test execution.
2. Handling registry sensor events.

- Param service:

    - **[in]** Island service reference.

- Param instance:

    - **[in]** Sensor instance reference that is requesting island exit. NULL if a sensor is requesting island exit.

- Return:

    - - SNS\_RC\_SUCCESS Success.
- Any other value Failure.

- [sns\_rc](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv46sns_rc) (\*island\_log\_trace)([sns\_island\_service](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv418sns_island_service) \*service, uint64\_t user\_defined\_id)

    - Generates a log packet of the sns\_island\_trace\_log type and commits it.

Note

This API must be used for debug only. Typical use of this API is to confirm if a line of code is executing in island mode. All calls to this debug API should be disabled by default and only enabled using registry config or compile switches when necessary for debug.

- Param service:

    - **[in]** Island service reference.

- Param user\_defined\_id:

    - **[in]** The value to be added to the cookie field in the log packet.

- Return:

    - - SNS\_RC\_SUCCESS Success.
- Any other value Failure.

## Memory Service

Service for sensor memory management.

Defines

- SNS\_MEMORY\_SERVICE\_VERSION

    - Version comments 1 Initial version 2 Added support for API: “register\_island\_memory\_vote\_cb()” 3 New API support for allocating memory in island 4 Garbage collection implemented 5 Added new API to query memory pool information.

======================== Version History ===================================

- SNS\_MAX\_MEM\_POOL\_NAME\_LEN

    - Maximum character length of the memory pool name.

- struct sns\_memory\_service

    - The Sensor Memory Manager. Will be obtained from [sns\_service\_manager::get\_service](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#structsns__service__manager_1a68895be9b0bd143f457977468a580e81).

Public Members

- [sns\_service](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv411sns_service) service

    - Service information.

- const struct [sns\_memory\_service\_api](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv422sns_memory_service_api) \*api

    - Public api provided by the framework to be used by the sensor.

- struct sns\_memory\_service\_api

    - Sensor Memory Service APIs.

Public Members

- uint32\_t struct\_len

    - Length of [sns\_memory\_service\_api](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#structsns__memory__service__api) structure.

- void \*(\*malloc)(struct [sns\_sensor\_instance](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv419sns_sensor_instance) \*instance, size\_t size)

    - Allocates memory from big image memory and returns a pointer to it.

- Param instance:

    - **[in]** Sensor Instance.

- Param size:

    - **[in]** Number of bytes required.

- Return:

    - - void\* Pointer to the memory if successful.
- NULL If alloc failed.

- void (\*free)(struct [sns\_sensor\_instance](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv419sns_sensor_instance) \*instance, void \*ptr)

    - Frees a block of memory.

- Param instance:

    - **[in]** Sensor Instance.

- Param ptr:

    - **[in]** Pointer to memory block to be freed.

- Return:

    - - None.

- void (\*register\_island\_memory\_vote\_cb)([sns\_sensor](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv410sns_sensor) \*const sensor, sns\_island\_memory\_vote\_cb cb)

    - Register callback function to vote for sensor island memory pool. Sensor framework calls this registered callback function for an island sensor in following scenarios, 1) Before delivering first request to the sensor. 2) After removal of all requests on a sensor. Sensor can deregister the callback function by passing “sns\_island\_memory\_vote\_cb” parameter as NULL.

- Param Sensor:

    - **[in]** Sensor pointer.

- Param cb:

    - **[in]** Sensor callback function of type “sns\_island\_memory\_vote\_cb”.

- Return:

    - - None.

- void \*(\*malloc\_island)(struct [sns\_sensor\_instance](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv419sns_sensor_instance) \*instance, size\_t size)

    - Allocates memory from island memory.

- Param instance:

    - **[in]** Sensor Instance.

- Param size:

    - **[in]** Number of bytes required.

- Return:

    - - void\* Pointer to the memory if successful.
- NULL if alloc failed.

- [sns\_rc](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv46sns_rc) (\*get\_memory\_pool\_name)(struct [sns\_sensor](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv410sns_sensor) \*sensor, char \*dst\_buffer, size\_t dst\_size)

    - Returns name of the memory pool where sensor is allocated.

- Param sensor:

    - **[in]** Sensor pointer.

- Param dst\_buffer:

    - **[inout]** Destination character buffer pointer.

- Param dst\_size:

    - **[in]** Size of the destination buffer in bytes.

- Return:

    - - SNS\_RC\_SUCCESS Success.
- SNS\_RC\_INVALID\_VALUE Either sensor/dst\_buffer is null or not enough memory in the pool.
- SNS\_RC\_NOT\_SUPPORTED Unsupported memory segment.

- void \*(\*sensor\_malloc)(struct [sns\_sensor](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv410sns_sensor) \*sensor, size\_t size)

    - Allocates memory from big image memory and returns a pointer to it.

- Param sensor:

    - **[in]** Sensor pointer.

- Param size:

    - **[in]** Number of bytes required.

- Return:

    - - void\* Pointer to the memory if successful.
- NULL If alloc failed.

- void (\*sensor\_free)(struct [sns\_sensor](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv410sns_sensor) \*sensor, void \*ptr)

    - Frees a block of memory.

- Param sensor:

    - **[in]** Sensor pointer.

- Param ptr:

    - **[in]** Pointer to memory block to be freed.

- Return:

    - - None.

- void \*(\*sensor\_malloc\_island)(struct [sns\_sensor](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv410sns_sensor) \*sensor, size\_t size)

    - Allocates memory from island memory when sensor is coming from island. otherwise, memory will be allocated in the big image.

- Param sensor:

    - **[in]** Sensor pointer.

- Param size:

    - **[in]** Number of bytes required.

- Param heap\_id:

    - **[in]** Heap to allocate from .

- Return:

    - - void\* Pointer to the memory if successful.
- NULL if alloc failed.

## Power Manager Service

Service for sensor power management.

Defines

- SNS\_POWER\_MGR\_SERVICE\_VERSION

    - Version comments 1 Initial version with mcps voting api support.

======================== Version History ===================================

- struct sns\_power\_mgr\_service

    - The Sensor Power Manager. Will be obtained from [sns\_service\_manager::get\_service](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#structsns__service__manager_1a68895be9b0bd143f457977468a580e81).

Public Members

- [sns\_service](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv411sns_service) service

    - Service information.

- const struct [sns\_power\_mgr\_service\_api](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv425sns_power_mgr_service_api) \*api

    - Public api provided by the framework to be used by the sensor.

- struct sns\_power\_mgr\_service\_api

    - The Sensor Power Manager APIs.

Public Members

- uint32\_t struct\_len

    - Length of [sns\_power\_mgr\_service\_api](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#structsns__power__mgr__service__api) structure.

- [sns\_rc](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv46sns_rc) (\*sns\_register\_client)(char \*client\_name, sns\_power\_mgr\_handle \*\*handle)

    - Register sensor client with sensor power manager service.

Note

This API is not supported in island.

- Param client\_name:

    - **[in]** Ptr to the client name. The max size is 32 char.

- Param handle:

    - **[inout]** Handle returned by power manager service

- Return:

    - - SNS\_RC\_INVALID\_VALUE Input parameters are invalid.
- SNS\_RC\_FAILED Client registration failed.
- SNS\_RC\_SUCCESS Action succeeded.

- [sns\_rc](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv46sns_rc) (\*sns\_deregister\_client)(sns\_power\_mgr\_handle \*\*handle)

    - De-register sensor client with sensor power manager service.

Note

This API is not supported in island.

- Param handle:

    - **[inout]** Reference to the handle.

- Return:

    - - SNS\_RC\_INVALID\_VALUE Passed in handle is invalid.
- SNS\_RC\_SUCCESS Handle is freed.

- [sns\_rc](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv46sns_rc) (\*sns\_update\_mcps\_vote)(sns\_power\_mgr\_handle \*handle, int16\_t mcps)

    - Vote for MCPS( Million cycles per sec ) requirement Note: This API is not supported in island.

- Param handle:

    - **[inout]** Handle returned by power manager service.

- Param mcps:

    - **[in]** Requested mcps.

- Return:

    - - SNS\_RC\_INVALID\_VALUE Input parameters are invalid.
- SNS\_RC\_SUCCESS Action succeeded.

## Power Rail Service

Power rail management API.

Defines

- RAIL\_NUMBER\_MAX

    - 

- RAIL\_NAME\_STRING\_SIZE\_MAX

    - 

- INVALID\_GPIONUM

    - Defining initial gpio number of local rail.

- GPIO\_NUMBER\_STRING\_SIZE\_MAX

    - Maximum possible size of gpio number.

- DUMMY\_SENSOR\_VDD

    - Define a dummy rail for OEMs that use external rails for their sensors. Dummy rail config is required so island mode block/unblock logic still works for those OEMs. Turning the dummy rail on at init also ensures that GDSC is voted on during startup.

- SNS\_PWR\_RAIL\_VDD

    - 

- SNS\_LOCAL\_ELDO

    - Defines prefix of local eLDO rail that is compared with the prefix of the local rail name before declaring rail as valid.

- SNS\_REMOTE\_ELDO

    - Defines prefix of remote eLDO rail that is compared with the prefix of the remote rail name before declaring rail as valid.

Enums

- enum sns\_power\_rail\_state

    - Power rail states provided by this service.

*Values:*

- enumerator SNS\_RAIL\_OFF

    - OFF state. Must be used when there are no active Sensors Instances.

- enumerator SNS\_RAIL\_ON\_LPM

    - Low Power Mode. Must be used as an ON state when sensor power requirement is < 10 mA. This spec is based on chipset’s pmic document.

- enumerator SNS\_RAIL\_ON\_NPM

    - Normal Power Mode. Must be used as an ON state when sensor power requirement is >= 10 mA. This spec is based on chipset’s pmic document.

- struct sns\_rail\_name

    - Rail name definition.

Public Members

- char name[RAIL\_NAME\_STRING\_SIZE\_MAX]

    -

- struct sns\_rail\_config

    - Rail configuration definition.

Public Members

- [sns\_power\_rail\_state](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv420sns_power_rail_state) rail\_vote

    - Overall vote for all sensor rails. At any time, all rails for a sensor can have a single state from sns\_power\_rail\_state.

- uint8\_t num\_of\_rails

    - Number of rails in [sns\_rail\_name](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#structsns__rail__name) array.

- [sns\_rail\_name](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv413sns_rail_name) rails[RAIL\_NUMBER\_MAX]

    - Array of rail names. These are power rails connected to the sensor HW.

- struct sns\_pwr\_rail\_service

    - Sensors Power Rail Service type definitions.

Public Members

- [sns\_service](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv411sns_service) service

    - Service information.

- struct [sns\_pwr\_rail\_service\_api](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv424sns_pwr_rail_service_api) \*api

    - Public API provided by the Service to be used by the Sensor.

- struct sns\_pwr\_rail\_service\_api

    - Sensors Power Rail Service APIs.

Public Members

- size\_t struct\_len

    - Length of [sns\_pwr\_rail\_service\_api](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#structsns__pwr__rail__service__api) structure.

- [sns\_rc](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv46sns_rc) (\*sns\_register\_power\_rails)([sns\_pwr\_rail\_service](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv420sns_pwr_rail_service) \*service, [sns\_rail\_config](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv415sns_rail_config) const \*rail\_config)

    - Register power rails for a physical sensor. All physical sensors typically have one or more power rails that supply power to the sensor hardware. Power rail configuration for all sensors shall be defined in the non-volatile registry. After the sensor driver fetches rail information from the registry, it shall register all rails using this API. Rail registration must happen only once for any rail.

- Param service:

    - **[in]** Power rail service reference.

- Param rail\_config:

    - **[in]** Rail config being registered.

- Return:

    - - SNS\_RC\_SUCCESS Success.
- Any other value Failure.

- [sns\_rc](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv46sns_rc) (\*sns\_vote\_power\_rail\_update)([sns\_pwr\_rail\_service](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv420sns_pwr_rail_service) \*service, struct [sns\_sensor](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv410sns_sensor) const \*sensor, [sns\_rail\_config](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv415sns_rail_config) const \*rails\_config, sns\_time \*rail\_on\_timestamp)

    - Vote for a power rail status change. Each physical sensor driver uses this API to turn it’s sensors power rails ON when there is an active client request. It is also the driver’s responsibility to vote for power rails OFF when all clients requests are disabled (i.e. there are no Sensors Instances present).

- Param service:

    - **[in]** Power rail service reference.

- Param sensor:

    - **[in]** Sensor requesting rail update.

- Param rails\_config:

    - **[in]** Rails and their status change vote.

- Param rail\_on\_timestamp:

    - **[out]** Timestamp in ticks when the rail was turned ON. When the rails are being turned OFF, the client can choose not to get rail\_on\_timestamp information.

- Return:

    - - SNS\_RC\_SUCCESS Success.
- Any other value Failure.

## Registration Service

Registration service provides functionality to sensors to register new sensors within the same library.

- struct sns\_registration\_service

    - [sns\_registration\_service](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#structsns__registration__service).

Public Members

- [sns\_service](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv411sns_service) service

    - Service information.

- struct [sns\_registration\_service\_api](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv428sns_registration_service_api) \*api

    - Public api provided by the framework to be used by the sensor.

- struct sns\_registration\_service\_api

    - API made available to Sensors.

Public Members

- uint32\_t struct\_len

    - Length of [sns\_registration\_service\_api](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#structsns__registration__service__api) structure.

- [sns\_rc](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv46sns_rc) (\*sns\_sensor\_create)(const [sns\_sensor](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv410sns_sensor) \*sensor, uint32\_t state\_len, struct [sns\_sensor\_api](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv414sns_sensor_api) const \*sensor\_api, struct [sns\_sensor\_instance\_api](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv423sns_sensor_instance_api) const \*instance\_api)

    - Allocate and initialize a Sensor in the same library of requesting sensor.

- Param sensor:

    - **[in]** Sensor reference that is requesting creation of new sensor. This values should never be NULL.

- Param state\_len:

    - **[in]** Size to be allocated for [sns\_sensor::state](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#structsns__sensor_1ad056c99f0c996594fc7ae930fb52986f).

- Param sensor\_api:

    - **[in]** Sensor API implemented by the Sensor developer.

- Param instance\_api:

    - **[in]** Sensor Instance API; by the Sensor developer.

- Return:

    - - SNS\_RC\_POLICY State\_len too large.
- SNS\_RC\_NOT\_AVAILABLE Sensor UID is already in-use.
- SNS\_RC\_FAILED Sensor initialization failed.
- SNS\_RC\_SUCCESS Success.

## Service Manager

Synchronous services provided by the Framework.

Enums

- enum sns\_service\_type

    - Enumeration of Services provided by the Framework. Some of these are core services which will be provided in every variation of the Framework. Others are target or version specific. Clients must query to determine if a particular service is available on the system.

*Values:*

- enumerator SNS\_STREAM\_SERVICE

    - This service provides stream processing capabilities.

- enumerator SNS\_ATTRIBUTE\_SERVICE

    - This service manages attributes associated with sensors.

- enumerator SNS\_DYNAMIC\_BUFFER\_SERVICE

    - This service offers dynamic buffer management.

- enumerator SNS\_EVENT\_SERVICE

    - This service handles events generated by sensors.

- enumerator SNS\_POWER\_RAIL\_SERVICE

    - This service manages power rails.

- enumerator SNS\_DIAG\_SERVICE

    - This service provides diagnostic information.

- enumerator SNS\_SYNC\_COM\_PORT\_SERVICE

    - This service facilitates synchronous communication over serial ports.

- enumerator SNS\_GPIO\_SERVICE

    - This service controls General Purpose Input/Output (GPIO) pins.

- enumerator SNS\_ISLAND\_SERVICE

    - This service manages Island sections of the system.

- enumerator SNS\_REGISTRATION\_SERVICE

    - This service handles sensor registrations.

- enumerator SNS\_POWER\_MGR\_SERVICE

    - This service manages power management policies.

- enumerator SNS\_MEMORY\_SERVICE

    - This service provides memory management functionalities.

- enumerator SNS\_FILE\_SERVICE

    - This service handles file operations.

- enumerator SNS\_SFE\_SERVICE

    - This service handles SFE operations.

- enumerator SNS\_SERVICE\_TYPE\_LENGTH

    - A placeholder member indicating the number of service types defined in this enumeration.

- struct sns\_service

    - Service attributes. New fields cannot be added without a Framework major revision.

Public Members

- uint16\_t version

    - Version number of this service; incremented only when new functionality is added to the service. Backward compatibility shall be maintained for all services.

- [sns\_service\_type](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv416sns_service_type) type

    - Type of serive.

Provides access to all service objects. Sensors must query for the needed service each time they need it; the Framework reserves the right to move a service into/out of island mode, and pointers kept to it may break. It would be appropriate within sns\_sensor::init to query for all required services, to ensure the Sensor is capable of operating.

- struct sns\_service\_manager

    - Service Manager APIs.

Public Members

- uint32\_t struct\_len

    - Length of [sns\_service\_manager](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#structsns__service__manager) structure.

- [sns\_service](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv411sns_service) \*(\*get\_service)(struct [sns\_service\_manager](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv419sns_service_manager) \*manager, [sns\_service\_type](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv416sns_service_type) service)

    - Query the Framework for a particular service.

- Param manager:

    - **[in]** Reference to the Service Manager.

- Param service:

    - **[in]** Service for which to query.

- Return:

    - - sns\_service\* Service reference; shall be casted by the client to the appropriate service object.
- NULL If not present.

## Stream Service

Manages stream requests from Sensors or Sensor Instances.

- struct sns\_stream\_service

    - The Stream Manager. Will be obtained from [sns\_service\_manager::get\_service](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#structsns__service__manager_1a68895be9b0bd143f457977468a580e81).

Public Members

- [sns\_service](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv411sns_service) service

    - Service information.

- const struct [sns\_stream\_service\_api](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv422sns_stream_service_api) \*api

    - Public api provided by the framework to be used by the sensor.

- struct sns\_stream\_service\_api

    - The Stream Service APIs.

Public Members

- uint32\_t struct\_len

    - Length of [sns\_stream\_service\_api](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#structsns__stream__service__api) structure.

- [sns\_rc](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv46sns_rc) (\*create\_sensor\_stream)([sns\_stream\_service](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv418sns_stream_service) \*service, struct [sns\_sensor](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv410sns_sensor) \*sensor, [sns\_sensor\_uid](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv414sns_sensor_uid) sensor\_uid, struct [sns\_data\_stream](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv415sns_data_stream) \*\*data\_stream)

    - Initialize a new stream to be used by a Sensor.

- Param service:

    - **[in]** Stream Service reference.

- Param sensor:

    - **[in]** The Sensor requesting the stream.

- Param sensor\_uid:

    - **[in]** To whom to make the connection.

- Param data\_stream:

    - **[out]** Stream reference allocated by the Framework.

- Return:

    - - SNS\_RC\_SUCCESS Success.
- Any other value Failure.

- [sns\_rc](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv46sns_rc) (\*create\_sensor\_instance\_stream)([sns\_stream\_service](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv418sns_stream_service) \*service, struct [sns\_sensor\_instance](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv419sns_sensor_instance) \*instance, [sns\_sensor\_uid](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv414sns_sensor_uid) sensor\_uid, struct [sns\_data\_stream](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv415sns_data_stream) \*\*data\_stream)

    - Initialize a new stream to be used by a Sensor Instance.

- Param service:

    - **[in]** Stream Service reference.

- Param sensor:

    - **[in]** The Sensor Instance requesting the stream.

- Param sensor\_uid:

    - **[in]** To whom to make the connection.

- Param data\_stream:

    - **[out]** Stream reference allocated by the Framework.

- Return:

    - - SNS\_RC\_SUCCESS Success.
- SNS\_RC\_POLICY The Sensor has exceeded the maximum stream count.
- SNS\_RC\_NOT\_AVAILABLE The given SUID is not presently available.
- Any other value Failure.

- [sns\_rc](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv46sns_rc) (\*remove\_stream)([sns\_stream\_service](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv418sns_stream_service) \*service, struct [sns\_data\_stream](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv415sns_data_stream) \*data\_stream)

    - Remove a stream created by create\_sensor\_stream/ create\_sensor\_instance\_stream.

- Param service:

    - **[in]** Stream Service reference.

- Param data\_stream:

    - **[in]** Data Stream to remove and free.

- Return:

    - - SNS\_RC\_SUCCESS Success.
- Any other value Failure.

## Sync Com Port Service

Manages sync com port service.

Defines

- COM\_PORT\_ENABLE\_DEBUG

    - 

- COM\_PORT\_PRINTF(prio, sensor, ...)

    - Printf() like function for logging purposes.

- struct sns\_sync\_com\_port\_service

    - The Sync Com Port Service Manager. Will be obtained from [sns\_service\_manager::get\_service](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#structsns__service__manager_1a68895be9b0bd143f457977468a580e81).

Public Members

- [sns\_service](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv411sns_service) service

    - Service information.

- struct [sns\_sync\_com\_port\_service\_api](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv429sns_sync_com_port_service_api) const \*api

    - Public api provided by the framework to be used by the sensor.

- struct sns\_sync\_com\_port\_version

    - Com port version struct.

Public Members

- uint16\_t major

    - Major version number.

- uint16\_t minor

    - Minor version number.

- struct sns\_sync\_com\_port\_service\_api

    - The Sync Com Port Service APIs.

Public Members

- size\_t struct\_len

    - Length of [sns\_sync\_com\_port\_service\_api](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#structsns__sync__com__port__service__api) structure.

- [sns\_rc](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv46sns_rc) (\*sns\_scp\_register\_com\_port)([sns\_com\_port\_config](https://docs.qualcomm.com/doc/80-P9361-100/topic/pal.html#_CPPv419sns_com_port_config) const \*com\_config, sns\_sync\_com\_port\_handle \*\*port\_handle)

    - Registers a bus COM port with the Synchronous COM Port (SCP) utility. Each physical sensor shall register with the SCP before any SCP API can be used. Note that this does not open a COM port.

- Param com\_config:

    - **[in]** COM port config for the bus.

- Param port\_handle:

    - **[out]** Port handle for the bus.

- Return:

    - - SNS\_RC\_SUCCESS Success.
- SNS\_RC\_INVALID\_VALUE Input parameters are invalid.
- Any other value Failure.

- [sns\_rc](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv46sns_rc) (\*sns\_scp\_deregister\_com\_port)(sns\_sync\_com\_port\_handle \*\*port\_handle)

    - Deregisters a bus COM port with the Synchronous COM Port (SCP) utility and sets the port handle to NULL. This will power off and close the com port, if powered on or open.

- Param port\_handle:

    - **[in]** Reference to the port handle.

- Return:

    - - SNS\_RC\_SUCCESS Success.
- SNS\_RC\_INVALID\_VALUE Passed in port handle is invalid.
- Any other value Failure.

- [sns\_rc](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv46sns_rc) (\*sns\_scp\_get\_version)([sns\_sync\_com\_port\_version](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#_CPPv425sns_sync_com_port_version) \*version)

    - Get the version of the Synchronous COM Port API.

- Param version:

    - **[out]** Version of this API.

- Return:

    - - SNS\_RC\_SUCCESS Success.
- SNS\_RC\_INVALID\_VALUE version parameter is NULL.
- Any other value Failure.

- [sns\_rc](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv46sns_rc) (\*sns\_scp\_open)(sns\_sync\_com\_port\_handle \*port\_handle)

    - Opens a new COM port with bus configuration com\_config. The bus is powered ON after this function returns successfully. Each physical sensor driver that needs access to a communication bus (I2C/SPI/I3C/UART) shall use this API typically in initialization routine. The physical sensor driver must save port handle for future use of the bus.

- Param port\_handle:

    - **[in]** Port handle for the bus.

- Return:

    - - SNS\_RC\_SUCCESS Success.
- SNS\_RC\_INVALID\_VALUE requested bus and/or port handle are invalid.
- Any other value Failure.

- [sns\_rc](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv46sns_rc) (\*sns\_scp\_close)(sns\_sync\_com\_port\_handle \*port\_handle)

    - Closes and powers off the COM port. The physical sensor driver would typically close the port when it’s being un-installed or unloaded. This operation is valid only on a port that has been successfully opened using [sns\_scp\_open()](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#structsns__sync__com__port__service__api_1ad486757902acf45c534aaaf55ebc795c). Once a bus is closed, it shall not be accessed by the driver.

- Param port\_handle:

    - **[in]** Port handle for the bus.

- Return:

    - - SNS\_RC\_SUCCESS Success.
- SNS\_RC\_INVALID\_VALUE passed in port handle is invalid.
- Any other value Failure.

- [sns\_rc](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv46sns_rc) (\*sns\_scp\_update\_bus\_power)(sns\_sync\_com\_port\_handle \*port\_handle, bool power\_bus\_on)

    - Updates bus power status to ON or OFF. Typically, a physical sensor driver shall turn bus power ON before initiating a series of COM transfers. It shall turn bus power off after to save power. A COM port cannot be used unless it is in power ON state. It is required for all device drivers to turn the bus OFF when not in use. This operation is valid only on a port that has been successfully opened using [sns\_scp\_open()](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#structsns__sync__com__port__service__api_1ad486757902acf45c534aaaf55ebc795c).

- Param port\_handle:

    - **[in]** Port handle for the bus.

- Param power\_bus\_on:

    - **[in]** true to power ON. false to power OFF.

- Return:

    - - SNS\_RC\_SUCCESS Success.
- SNS\_RC\_INVALID\_VALUE passed in port handle is invalid.
- Any other value Failure.

- [sns\_rc](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv46sns_rc) (\*sns\_scp\_register\_rw)(sns\_sync\_com\_port\_handle \*port\_handle, [sns\_port\_vector](https://docs.qualcomm.com/doc/80-P9361-100/topic/pal.html#_CPPv415sns_port_vector) \*vectors, int32\_t num\_vectors, bool save\_write\_time, uint32\_t \*xfer\_bytes)

    - Read and/or write multiple registers. This is a vectored API. It can be used for: 1) Read single/multiple registers in the same transfer. 2) Write to single/multiple register in same transfer. 3) Write to and read from single/multiple registers in same transfer. This operation is valid only on a port that has been successfully opened using [sns\_scp\_open()](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#structsns__sync__com__port__service__api_1ad486757902acf45c534aaaf55ebc795c).

- Param port\_handle:

    - **[in]** Port handle for the bus.

- Param vectors:

    - **[in]** An array of register read/write operations.

- Param num\_vectors:

    - **[in]** Number of elements in vectors array.

- Param save\_write\_time:

    - **[in]** True if time of the bus write transaction must be saved. If there are multiple write vectors then this will only save the time of the last write vector.

- Param xfer\_bytes:

    - **[out]** Total number of bytes read & written for all registers in this vectored transfer. May be NULL.

- Return:

    - - SNS\_RC\_SUCCESS Success.
- SNS\_RC\_INVALID\_VALUE passed in port handle is invalid.
- Any other value Failure.

- [sns\_rc](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv46sns_rc) (\*sns\_scp\_register\_rw\_ex)(sns\_sync\_com\_port\_handle \*port\_handle, [sns\_com\_port\_config\_ex](https://docs.qualcomm.com/doc/80-P9361-100/topic/pal.html#_CPPv422sns_com_port_config_ex) \*com\_port\_ex, [sns\_port\_vector](https://docs.qualcomm.com/doc/80-P9361-100/topic/pal.html#_CPPv415sns_port_vector) \*vectors, int32\_t num\_vectors, bool save\_write\_time, uint32\_t \*xfer\_bytes)

    - Read and/or write multiple registers. This is a vectored API. It can be used for: 1) Read single/multiple registers in the same transfer. 2) Write to single/multiple register in same transfer. 3) Write to and read from single/multiple registers in same transfer. 4) This is the updated API which also handles the advanced COM Port configuration parameters in [sns\_com\_port\_config\_ex](https://docs.qualcomm.com/doc/80-P9361-100/topic/pal.html#structsns__com__port__config__ex). This operation is valid only on a port that has been successfully opened using [sns\_scp\_open()](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#structsns__sync__com__port__service__api_1ad486757902acf45c534aaaf55ebc795c).

- Param port\_handle:

    - **[in]** Port handle for the bus.

- Param com\_port\_ex:

    - **[in]** Structure with Extended COM Port Parameters.

- Param vectors:

    - **[in]** An array of register read/write operations.

- Param num\_vectors:

    - **[in]** Number of elements in vectors array.

- Param save\_write\_time:

    - **[in]** True if time of the bus write transaction must be saved. If there are multiple write vectors then this will only save the time of the last write vector.

- Param xfer\_bytes:

    - **[out]** Total number of bytes read & written for all registers in this vectored transfer. May be NULL.

- Return:

    - - SNS\_RC\_SUCCESS Success.
- SNS\_RC\_INVALID\_VALUE passed in port handle is invalid.
- Any other value Failure.

- [sns\_rc](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv46sns_rc) (\*sns\_scp\_simple\_rw)(sns\_sync\_com\_port\_handle \*port\_handle, bool is\_write, bool save\_write\_time, uint8\_t \*buffer, uint32\_t bytes, uint32\_t \*xfer\_bytes)

    - Read/write operation directly to the slave. This operation is valid only on a port that has been successfully opened using [sns\_scp\_open()](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#structsns__sync__com__port__service__api_1ad486757902acf45c534aaaf55ebc795c).

Note

Cause for specific error returns:

- SNS\_RC\_INVALID\_VALUE - passed in port handle is invalid.
- SNS\_RC\_NOT\_AVAILABLE - action not supported

- Param port\_handle:

    - **[in]** Port handle

- Param is\_write:

    - **[in]** True for write operation else false.

- Param save\_write\_time:

    - **[in]** True if time of the bus write transaction must be saved.

- Param buffer:

    - **[out]** Buffer for read/write operation.

- Param bytes:

    - **[in]** Number of bytes to read/write

- Param xfer\_bytes:

    - **[out]** Total bytes actually read/written.

- Return:

    - - SNS\_RC\_SUCCESS Success.
- SNS\_RC\_INVALID\_VALUE passed in port handle is invalid.
- SNS\_RC\_NOT\_AVAILABLE action not supported.
- Any other value Failure.

- [sns\_rc](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv46sns_rc) (\*sns\_scp\_get\_write\_time)(sns\_sync\_com\_port\_handle \*port\_handle, sns\_time \*write\_time)

    - Gets the timestamp for most recent write operation. This API must be called only when save\_write\_time is ‘true’ for the most recent write operation on the bus. It is typically used for S4S mode of operation to get the start time when the ST command is sent to the physical sensor. For I2C and I3C, the timestamp is when the START condition occurs for the write transfer. For SPI, the timestamp is an instance during the write transfer. This operation is valid only on a port that has been successfully opened using [sns\_scp\_open()](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#structsns__sync__com__port__service__api_1ad486757902acf45c534aaaf55ebc795c).

Note

Cause for specific error returns:

- SNS\_RC\_INVALID\_VALUE - passed in port handle is invalid.

- Param port\_handle:

    - **[in]** Port handle for the bus.

- Param write\_time:

    - **[out]** System timestamp in ticks.

- Return:

    - - SNS\_RC\_SUCCESS Success.
- SNS\_RC\_INVALID\_VALUE passed in port handle is invalid.
- Any other value Failure.

- [sns\_rc](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv46sns_rc) (\*sns\_scp\_issue\_ccc)(sns\_sync\_com\_port\_handle \*port\_handle, [sns\_sync\_com\_port\_ccc](https://docs.qualcomm.com/doc/80-P9361-100/topic/pal.html#_CPPv421sns_sync_com_port_ccc) ccc\_cmd, uint8\_t \*buffer, uint32\_t bytes, uint32\_t \*xfer\_bytes)

    - Issues a direct I3C Common Command Code (CCC) to a slave. See Mipi Alliance Specificiation for I3C for more detailed information. This API will either send or receive a direct CCC to a specified slave. If the device is not I3C, this function will return an error. All CCC commands save write time, so “sns\_scp\_get\_write\_time” may be called later to get the transfer time on the bus.

Note

Cause for specific error returns:

- SNS\_RC\_NOT\_SUPPORTED - CCC is not supported on this bus
- SNS\_RC\_INVALID\_VALUE - invalid handle, unsupported CCC, or wrong buffer size for CCC.

- Param port\_handle:

    - **[in]** Port handle.

- Param ccc\_cmd:

    - **[in]** CCC command to issue. Read or write will depend on command.

- Param buffer:

    - **[out]** Buffer for read/write operation. May be NULL if cmd has no data.

- Param bytes:

    - **[in]** Size of the buffer May be 0.

- Param xfer\_bytes:

    - **[out]** Total bytes actually read/written.

- Return:

    - - SNS\_RC\_SUCCESS Success.
- SNS\_RC\_NOT\_SUPPORTED CCC is not supported on this bus
- SNS\_RC\_INVALID\_VALUE invalid handle, unsupported CCC, or wrong buffer size for CCC.
- Any other value Failure.

- [sns\_rc](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv46sns_rc) (\*sns\_scp\_rw)(sns\_sync\_com\_port\_handle \*port\_handle, uint8\_t \*read\_buffer, uint32\_t read\_len\_bytes, const uint8\_t \*write\_buffer, uint32\_t write\_len\_bytes, uint8\_t bits\_per\_word)

    - Full duplex read / write operation directly to the slave. This operation is valid only on a port that has been successfully opened using [sns\_scp\_open()](https://docs.qualcomm.com/doc/80-P9361-100/topic/service.html#structsns__sync__com__port__service__api_1ad486757902acf45c534aaaf55ebc795c) and supports full duplex transfers.

Note

Cause for specific error returns:

- SNS\_RC\_INVALID\_VALUE - passed in port handle is invalid.
- SNS\_RC\_NOT\_AVAILABLE - action not supported.

- Param port\_handle:

    - **[in]** Port handle.

- Param read\_buffer:

    - **[in]** Pointer to the read buffer.

- Param read\_len\_bytes:

    - **[in]** Length of the read buffer.

- Param write\_buffer:

    - **[in]** Pointer to the write buffer.

- Param write\_len\_bytes:

    - **[in]** Length of the write buffer.

- Param bits\_per\_word:

    - **[in]** SPI basic transaction unit size, usually 8 or 32 bit.

- Return:

    - - SNS\_RC\_SUCCESS Success.
- SNS\_RC\_INVALID\_VALUE Passed in port handle is invalid.
- SNS\_RC\_NOT\_AVAILABLE Action not supported.
- Any other value Failure.

- [sns\_rc](https://docs.qualcomm.com/doc/80-P9361-100/topic/sensor_api.html#_CPPv46sns_rc) (\*sns\_scp\_get\_dynamic\_addr)([sns\_com\_port\_config](https://docs.qualcomm.com/doc/80-P9361-100/topic/pal.html#_CPPv419sns_com_port_config) const \*com\_config, uint32\_t mipi\_manufacturer\_id, [sns\_com\_port\_i3c\_slaves](https://docs.qualcomm.com/doc/80-P9361-100/topic/pal.html#_CPPv423sns_com_port_i3c_slaves) \*list, uint32\_t \*num\_slaves)

    - Get the list of slaves matching the input Manufacturer ID (MIPI(R))

- Param com\_config:

    - **[in]** Com port configuration structure.

- Param mipi\_manufacturer\_id:

    - **[in]** Manufacturer ID assigned by MIPI(R) alliance. This ID uniquely identifies each vendor.

- Param list:

    - **[out]** List of slaves matching the input Manufacturer ID (assigned by the MIPI(R) Alliance).

- Param num\_slaves:

    - **[out]** Actual number of slaves matching the input manufacturer id.

- Return:

    - - SNS\_RC\_SUCCESS Success.
- SNS\_RC\_NOT\_AVAILABLE Action not supported.
- Any other value Failure.

Last Published: Jul 14, 2025

[Previous Topic
sns\_watchdog\_voter\_info()](https://docs.qualcomm.com/bundle/publicresource/80-P9361-100/topics/fwutils.md) [Next Topic
Message](https://docs.qualcomm.com/bundle/publicresource/80-P9361-100/topics/index_message.md)