Update documentation for initialize()
Updates the documentation for the initialize() function and defines
the requirements for using the Event FMQ's writeBlocking function
which requires both a read and write notification.
Also adds requirement for the Sensors HAL to cleanup active sensor
requests and direct connections whenever initialize is called.
Bug: 120857563
Test: Builds
Change-Id: I11c8f7404d27e9ab21f9314523faebc1970b9f0c
diff --git a/sensors/2.0/ISensors.hal b/sensors/2.0/ISensors.hal
index 939bf73..1685a0a 100644
--- a/sensors/2.0/ISensors.hal
+++ b/sensors/2.0/ISensors.hal
@@ -77,11 +77,20 @@
* framework. The Event FMQ is created using the eventQueueDescriptor.
* Data may only be written to the Event FMQ. Data must not be read from
* the Event FMQ since the framework is the only reader. Upon receiving
- * sensor events, the HAL should write the sensor events to the Event FMQ.
+ * sensor events, the HAL writes the sensor events to the Event FMQ.
+ *
* Once the HAL is finished writing sensor events to the Event FMQ, the HAL
- * must call the Event FMQ's EventFlag wake() function with the
- * EventQueueFlagBits::READ_AND_PROCESS mask which notifies the framework
- * that sensor events are available to be read and processed.
+ * must notify the framework that sensor events are available to be read and
+ * processed. This is accomplished by either:
+ * 1) Calling the Event FMQ’s EventFlag::wake() function with
+ EventQueueFlagBits::READ_AND_PROCESS
+ * 2) Setting the write notification in the Event FMQ’s writeBlocking()
+ * function to EventQueueFlagBits::READ_AND_PROCESS.
+ *
+ * If the Event FMQ’s writeBlocking() function is used, the read
+ * notification must be set to EventQueueFlagBits::EVENTS_READ in order to
+ * be notified and unblocked when the framework has successfully read events
+ * from the Event FMQ.
*
* The Wake Lock FMQ is used by the framework to notify the HAL when it is
* safe to release its wake_lock. When the framework receives WAKE_UP events
@@ -110,6 +119,10 @@
* any outstanding wake_locks held as a result of WAKE_UP events should be
* released.
*
+ * All active sensor requests and direct channels must be closed and
+ * properly cleaned up when initialize is called in order to ensure that the
+ * HAL and framework's state is consistent (e.g. after a runtime restart).
+ *
* initialize must be thread safe and prevent concurrent calls
* to initialize from simultaneously modifying state.
*