1 /* 2 * Copyright (C) 2018 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 17 package android.hardware.sensors@2.0; 18 19 import @1.0::Event; 20 import @1.0::OperationMode; 21 import @1.0::RateLevel; 22 import @1.0::Result; 23 import @1.0::SensorInfo; 24 import @1.0::SharedMemInfo; 25 import @2.0::ISensorsCallback; 26 27 interface ISensors { 28 /** 29 * Enumerate all available (static) sensors. 30 * 31 * The SensorInfo for each sensor returned by getSensorsList must be stable 32 * from the initial call to getSensorsList after a device boot until the 33 * entire system restarts. The SensorInfo for each sensor must not change 34 * between subsequent calls to getSensorsList, even across restarts of the 35 * HAL and its dependencies (for example, the sensor handle for a given 36 * sensor must not change across HAL restarts). 37 */ 38 getSensorsList() generates (vec<SensorInfo> list); 39 40 /** 41 * Place the module in a specific mode. The following modes are defined 42 * 43 * SENSOR_HAL_NORMAL_MODE - Normal operation. Default state of the module. 44 * 45 * SENSOR_HAL_DATA_INJECTION_MODE - Loopback mode. 46 * Data is injected for the supported sensors by the sensor service in 47 * this mode. 48 * 49 * @return OK on success 50 * BAD_VALUE if requested mode is not supported 51 * PERMISSION_DENIED if operation is not allowed 52 */ 53 setOperationMode(OperationMode mode) generates (Result result); 54 55 /** 56 * Activate/de-activate one sensor. 57 * 58 * After sensor de-activation, existing sensor events that have not 59 * been written to the event queue must be abandoned immediately so that 60 * subsequent activations do not get stale sensor events (events 61 * that are generated prior to the latter activation). 62 * 63 * @param sensorHandle is the handle of the sensor to change. 64 * @param enabled set to true to enable, or false to disable the sensor. 65 * @return result OK on success, BAD_VALUE if sensorHandle is invalid. 66 */ 67 activate(int32_t sensorHandle, bool enabled) generates (Result result); 68 69 /** 70 * Initialize the Sensors HAL's Fast Message Queues (FMQ) and callback. 71 * 72 * The Fast Message Queues (FMQ) that are used to send data between the 73 * framework and the HAL. The callback is used by the HAL to notify the 74 * framework of asynchronous events, such as a dynamic sensor connection. 75 * 76 * The Event FMQ is used to transport sensor events from the HAL to the 77 * framework. The Event FMQ is created using the eventQueueDescriptor. 78 * Data may only be written to the Event FMQ. Data must not be read from 79 * the Event FMQ since the framework is the only reader. Upon receiving 80 * sensor events, the HAL writes the sensor events to the Event FMQ. 81 * 82 * Once the HAL is finished writing sensor events to the Event FMQ, the HAL 83 * must notify the framework that sensor events are available to be read and 84 * processed. This is accomplished by either: 85 * 1) Calling the Event FMQs EventFlag::wake() function with 86 EventQueueFlagBits::READ_AND_PROCESS 87 * 2) Setting the write notification in the Event FMQs writeBlocking() 88 * function to EventQueueFlagBits::READ_AND_PROCESS. 89 * 90 * If the Event FMQs writeBlocking() function is used, the read 91 * notification must be set to EventQueueFlagBits::EVENTS_READ in order to 92 * be notified and unblocked when the framework has successfully read events 93 * from the Event FMQ. 94 * 95 * The Wake Lock FMQ is used by the framework to notify the HAL when it is 96 * safe to release its wake_lock. When the framework receives WAKE_UP events 97 * from the Event FMQ and the framework has acquired a wake_lock, the 98 * framework must write the number of WAKE_UP events processed to the Wake 99 * Lock FMQ. When the HAL reads the data from the Wake Lock FMQ, the HAL 100 * decrements its current count of unprocessed WAKE_UP events and releases 101 * its wake_lock if the current count of unprocessed WAKE_UP events is 102 * zero. It is important to note that the HAL must acquire the wake lock and 103 * update its internal state regarding the number of outstanding WAKE_UP 104 * events _before_ posting the event to the Wake Lock FMQ, in order to avoid 105 * a race condition that can lead to loss of wake lock synchronization with 106 * the framework. 107 * 108 * The framework must use the WakeLockQueueFlagBits::DATA_WRITTEN value to 109 * notify the HAL that data has been written to the Wake Lock FMQ and must 110 * be read by HAL. 111 * 112 * The ISensorsCallback is used by the HAL to notify the framework of 113 * asynchronous events, such as a dynamic sensor connection. 114 * 115 * The name of any wake_lock acquired by the Sensors HAL for WAKE_UP events 116 * must begin with "SensorsHAL_WAKEUP". 117 * 118 * If WAKE_LOCK_TIMEOUT_SECONDS has elapsed since the most recent WAKE_UP 119 * event was written to the Event FMQ without receiving a message on the 120 * Wake Lock FMQ, then any held wake_lock for WAKE_UP events must be 121 * released. 122 * 123 * If either the Event FMQ or the Wake Lock FMQ is already initialized when 124 * initialize is invoked, then both existing FMQs must be discarded and the 125 * new descriptors must be used to create new FMQs within the HAL. The 126 * number of outstanding WAKE_UP events should also be reset to zero, and 127 * any outstanding wake_locks held as a result of WAKE_UP events should be 128 * released. 129 * 130 * All active sensor requests and direct channels must be closed and 131 * properly cleaned up when initialize is called in order to ensure that the 132 * HAL and framework's state is consistent (e.g. after a runtime restart). 133 * 134 * initialize must be thread safe and prevent concurrent calls 135 * to initialize from simultaneously modifying state. 136 * 137 * @param eventQueueDescriptor Fast Message Queue descriptor that is used to 138 * create the Event FMQ which is where sensor events are written. The 139 * descriptor is obtained from the framework's FMQ that is used to read 140 * sensor events. 141 * @param wakeLockDescriptor Fast Message Queue descriptor that is used to 142 * create the Wake Lock FMQ which is where wake_lock events are read 143 * from. The descriptor is obtained from the framework's FMQ that is 144 * used to write wake_lock events. 145 * @param sensorsCallback sensors callback that receives asynchronous data 146 * from the Sensors HAL. 147 * @return result OK on success; BAD_VALUE if descriptor is invalid (such 148 * as null) 149 */ 150 @entry 151 @callflow(next = {"getSensorsList"}) 152 initialize(fmq_sync<Event> eventQueueDescriptor, 153 fmq_sync<uint32_t> wakeLockDescriptor, 154 ISensorsCallback sensorsCallback) 155 generates 156 (Result result); 157 158 /** 159 * Sets a sensors parameters, including sampling frequency and maximum 160 * report latency. This function can be called while the sensor is 161 * activated, in which case it must not cause any sensor measurements to 162 * be lost: transitioning from one sampling rate to the other cannot cause 163 * lost events, nor can transitioning from a high maximum report latency to 164 * a low maximum report latency. 165 * 166 * @param sensorHandle handle of sensor to be changed. 167 * @param samplingPeriodNs specifies sensor sample period in nanoseconds. 168 * @param maxReportLatencyNs allowed delay time before an event is sampled 169 * to time of report. 170 * @return result OK on success, BAD_VALUE if any parameters are invalid. 171 */ 172 batch(int32_t sensorHandle, 173 int64_t samplingPeriodNs, 174 int64_t maxReportLatencyNs) 175 generates ( 176 Result result); 177 178 /** 179 * Trigger a flush of internal FIFO. 180 * 181 * Flush adds a FLUSH_COMPLETE metadata event to the end of the "batch mode" 182 * FIFO for the specified sensor and flushes the FIFO. If the FIFO is empty 183 * or if the sensor doesn't support batching (FIFO size zero), return 184 * SUCCESS and add a trivial FLUSH_COMPLETE event added to the event stream. 185 * This applies to all sensors other than one-shot sensors. If the sensor 186 * is a one-shot sensor, flush must return BAD_VALUE and not generate any 187 * flush complete metadata. If the sensor is not active at the time flush() 188 * is called, flush() return BAD_VALUE. 189 * 190 * @param sensorHandle handle of sensor to be flushed. 191 * @return result OK on success and BAD_VALUE if sensorHandle is invalid. 192 */ 193 flush(int32_t sensorHandle) generates (Result result); 194 195 /** 196 * Inject a single sensor event or push operation environment parameters to 197 * device. 198 * 199 * When device is in NORMAL mode, this function is called to push operation 200 * environment data to device. In this operation, Event is always of 201 * SensorType::AdditionalInfo type. See operation evironment parameters 202 * section in AdditionalInfoType. 203 * 204 * When device is in DATA_INJECTION mode, this function is also used for 205 * injecting sensor events. 206 * 207 * Regardless of OperationMode, injected SensorType::ADDITIONAL_INFO 208 * type events should not be routed back to the sensor event queue. 209 * 210 * @see AdditionalInfoType 211 * @see OperationMode 212 * @param event sensor event to be injected 213 * @return result OK on success; PERMISSION_DENIED if operation is not 214 * allowed; INVALID_OPERATION, if this functionality is unsupported; 215 * BAD_VALUE if sensor event cannot be injected. 216 */ 217 injectSensorData(Event event) generates (Result result); 218 219 /** 220 * Register direct report channel. 221 * 222 * Register a direct channel with supplied shared memory information. Upon 223 * return, the sensor hardware is responsible for resetting the memory 224 * content to initial value (depending on memory format settings). 225 * 226 * @param mem shared memory info data structure. 227 * @return result OK on success; BAD_VALUE if shared memory information is 228 * not consistent; NO_MEMORY if shared memory cannot be used by sensor 229 * system; INVALID_OPERATION if functionality is not supported. 230 * @return channelHandle a positive integer used for referencing registered 231 * direct channel (>0) in configureDirectReport and 232 * unregisterDirectChannel if result is OK, -1 otherwise. 233 */ 234 registerDirectChannel(SharedMemInfo mem) 235 generates (Result result, 236 int32_t channelHandle); 237 238 /** 239 * Unregister direct report channel. 240 * 241 * Unregister a direct channel previously registered using 242 * registerDirectChannel, and remove all active sensor report configured in 243 * still active sensor report configured in the direct channel. 244 * 245 * @param channelHandle handle of direct channel to be unregistered. 246 * @return result OK if direct report is supported; INVALID_OPERATION 247 * otherwise. 248 */ 249 unregisterDirectChannel(int32_t channelHandle) generates (Result result); 250 251 /** 252 * Configure direct sensor event report in direct channel. 253 * 254 * This function start, modify rate or stop direct report of a sensor in a 255 * certain direct channel. 256 * 257 * @param sensorHandle handle of sensor to be configured. When combined 258 * with STOP rate, sensorHandle can be -1 to denote all active sensors 259 * in the direct channel specified by channel Handle. 260 * @param channelHandle handle of direct channel to be configured. 261 * @param rate rate level, see RateLevel enum. 262 * @return result OK on success; BAD_VALUE if parameter is invalid (such as 263 * rate level is not supported by sensor, channelHandle does not exist, 264 * etc); INVALID_OPERATION if functionality is not supported. 265 * @return reportToken positive integer to identify multiple sensors of 266 * the same type in a single direct channel. Ignored if rate is STOP. 267 * See SharedMemFormat. 268 */ 269 configDirectReport( 270 int32_t sensorHandle, 271 int32_t channelHandle, 272 RateLevel rate 273 ) generates ( 274 Result result, 275 int32_t reportToken); 276 }; 277
