1/*
2 * Copyright (C) 2020 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.hardware.sensors@2.1;
18
19import @1.0::Result;
20import @2.0::ISensors;
21import @2.1::ISensorsCallback;
22
23interface ISensors extends @2.0::ISensors {
24    /**
25     * Enumerate all available (static) sensors.
26     *
27     * The SensorInfo for each sensor returned by getSensorsList must be stable
28     * from the initial call to getSensorsList after a device boot until the
29     * entire system restarts. The SensorInfo for each sensor must not change
30     * between subsequent calls to getSensorsList, even across restarts of the
31     * HAL and its dependencies (for example, the sensor handle for a given
32     * sensor must not change across HAL restarts).
33     */
34    getSensorsList_2_1() generates (vec<SensorInfo> list);
35
36    /**
37     * Initialize the Sensors HAL's Fast Message Queues (FMQ) and callback.
38     *
39     * The Fast Message Queues (FMQ) that are used to send data between the
40     * framework and the HAL. The callback is used by the HAL to notify the
41     * framework of asynchronous events, such as a dynamic sensor connection.
42     *
43     * The Event FMQ is used to transport sensor events from the HAL to the
44     * framework. The Event FMQ is created using the eventQueueDescriptor.
45     * Data may only be written to the Event FMQ. Data must not be read from
46     * the Event FMQ since the framework is the only reader. Upon receiving
47     * sensor events, the HAL writes the sensor events to the Event FMQ.
48     *
49     * Once the HAL is finished writing sensor events to the Event FMQ, the HAL
50     * must notify the framework that sensor events are available to be read and
51     * processed. This is accomplished by either:
52     *     1) Calling the Event FMQ’s EventFlag::wake() function with
53              EventQueueFlagBits::READ_AND_PROCESS
54     *     2) Setting the write notification in the Event FMQ’s writeBlocking()
55     *        function to EventQueueFlagBits::READ_AND_PROCESS.
56     *
57     * If the Event FMQ’s writeBlocking() function is used, the read
58     * notification must be set to EventQueueFlagBits::EVENTS_READ in order to
59     * be notified and unblocked when the framework has successfully read events
60     * from the Event FMQ.
61     *
62     * The Wake Lock FMQ is used by the framework to notify the HAL when it is
63     * safe to release its wake_lock. When the framework receives WAKE_UP events
64     * from the Event FMQ and the framework has acquired a wake_lock, the
65     * framework must write the number of WAKE_UP events processed to the Wake
66     * Lock FMQ. When the HAL reads the data from the Wake Lock FMQ, the HAL
67     * decrements its current count of unprocessed WAKE_UP events and releases
68     * its wake_lock if the current count of unprocessed WAKE_UP events is
69     * zero. It is important to note that the HAL must acquire the wake lock and
70     * update its internal state regarding the number of outstanding WAKE_UP
71     * events _before_ posting the event to the Wake Lock FMQ, in order to avoid
72     * a race condition that can lead to loss of wake lock synchronization with
73     * the framework.
74     *
75     * The framework must use the WakeLockQueueFlagBits::DATA_WRITTEN value to
76     * notify the HAL that data has been written to the Wake Lock FMQ and must
77     * be read by HAL.
78     *
79     * The ISensorsCallback is used by the HAL to notify the framework of
80     * asynchronous events, such as a dynamic sensor connection.
81     *
82     * The name of any wake_lock acquired by the Sensors HAL for WAKE_UP events
83     * must begin with "SensorsHAL_WAKEUP".
84     *
85     * If WAKE_LOCK_TIMEOUT_SECONDS has elapsed since the most recent WAKE_UP
86     * event was written to the Event FMQ without receiving a message on the
87     * Wake Lock FMQ, then any held wake_lock for WAKE_UP events must be
88     * released.
89     *
90     * If either the Event FMQ or the Wake Lock FMQ is already initialized when
91     * initialize is invoked, then both existing FMQs must be discarded and the
92     * new descriptors must be used to create new FMQs within the HAL. The
93     * number of outstanding WAKE_UP events should also be reset to zero, and
94     * any outstanding wake_locks held as a result of WAKE_UP events should be
95     * released.
96     *
97     * All active sensor requests and direct channels must be closed and
98     * properly cleaned up when initialize is called in order to ensure that the
99     * HAL and framework's state is consistent (e.g. after a runtime restart).
100     *
101     * initialize must be thread safe and prevent concurrent calls
102     * to initialize from simultaneously modifying state.
103     *
104     * @param eventQueueDescriptor Fast Message Queue descriptor that is used to
105     *     create the Event FMQ which is where sensor events are written. The
106     *     descriptor is obtained from the framework's FMQ that is used to read
107     *     sensor events.
108     * @param wakeLockDescriptor Fast Message Queue descriptor that is used to
109     *     create the Wake Lock FMQ which is where wake_lock events are read
110     *     from. The descriptor is obtained from the framework's FMQ that is
111     *     used to write wake_lock events.
112     * @param sensorsCallback sensors callback that receives asynchronous data
113     *     from the Sensors HAL.
114     * @return result OK on success; BAD_VALUE if descriptor is invalid (such
115     *     as null)
116     */
117    @entry
118    @callflow(next = {"getSensorsList"})
119    initialize_2_1(fmq_sync<Event> eventQueueDescriptor,
120                   fmq_sync<uint32_t> wakeLockDescriptor,
121                   ISensorsCallback sensorsCallback)
122        generates
123              (Result result);
124
125    /**
126     * Inject a single sensor event or push operation environment parameters to
127     * device.
128     *
129     * When device is in NORMAL mode, this function is called to push operation
130     * environment data to device. In this operation, Event is always of
131     * SensorType::AdditionalInfo type. See operation evironment parameters
132     * section in AdditionalInfoType.
133     *
134     * When device is in DATA_INJECTION mode, this function is also used for
135     * injecting sensor events.
136     *
137     * Regardless of OperationMode, injected SensorType::ADDITIONAL_INFO
138     * type events should not be routed back to the sensor event queue.
139     *
140     * @see AdditionalInfoType
141     * @see OperationMode
142     * @param event sensor event to be injected
143     * @return result OK on success; PERMISSION_DENIED if operation is not
144     *     allowed; INVALID_OPERATION, if this functionality is unsupported;
145     *     BAD_VALUE if sensor event cannot be injected.
146     */
147    injectSensorData_2_1(Event event) generates (Result result);
148};
149