sensors/1.0/ISensors.hal

   1 /*
   2  * Copyright (C) 2016 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@1.0;
  18
  19 interface ISensors {
  20     /**
  21      * Enumerate all available (static) sensors.
  22      */
  23     getSensorsList() generates (vec<SensorInfo> list);
  24
  25     /**
  26      * Place the module in a specific mode. The following modes are defined
  27      *
  28      *  SENSOR_HAL_NORMAL_MODE - Normal operation. Default state of the module.
  29      *
  30      *  SENSOR_HAL_DATA_INJECTION_MODE - Loopback mode.
  31      *    Data is injected for the supported sensors by the sensor service in
  32      *    this mode.
  33      *
  34      * @return OK on success
  35      *         BAD_VALUE if requested mode is not supported
  36      *         PERMISSION_DENIED if operation is not allowed
  37      */
  38     setOperationMode(OperationMode mode) generates (Result result);
  39
  40     /**
  41      * Activate/de-activate one sensor.
  42      *
  43      * After sensor de-activation, existing sensor events that have not
  44      * been picked up by poll() must be abandoned immediately so that
  45      * subsequent activation will not get stale sensor events (events
  46      * that are generated prior to the latter activation).
  47      *
  48      * @param  sensorHandle is the handle of the sensor to change.
  49      * @param  enabled set to true to enable, or false to disable the sensor.
  50      *
  51      * @return result OK on success, BAD_VALUE if sensorHandle is invalid.
  52      */
  53     activate(int32_t sensorHandle, bool enabled) generates (Result result);
  54
  55     /**
  56      * Generate a vector of sensor events containing at most "maxCount"
  57      * entries.
  58      *
  59      * Additionally a vector of SensorInfos is returned for any dynamic sensors
  60      * connected as notified by returned events of type DYNAMIC_SENSOR_META.
  61      *
  62      * If there is no sensor event when this function is being called, block
  63      * until there are sensor events available.
  64      *
  65      * @param  maxCount max number of samples can be returned, must be > 0.
  66      *         Actual number of events returned in data must be <= maxCount
  67      *         and > 0.
  68      * @return result OK on success or BAD_VALUE if maxCount <= 0.
  69      * @return data vector of Event contains sensor events.
  70      * @return dynamicSensorsAdded vector of SensorInfo contains dynamic sensor
  71      *         added. Each element corresponds to a dynamic sensor meta events
  72      *         in data.
  73      */
  74     poll(int32_t maxCount)
  75         generates (
  76                 Result result,
  77                 vec<Event> data,
  78                 vec<SensorInfo> dynamicSensorsAdded);
  79
  80     /**
  81      * Sets a sensor’s parameters, including sampling frequency and maximum
  82      * report latency. This function can be called while the sensor is
  83      * activated, in which case it must not cause any sensor measurements to
  84      * be lost: transitioning from one sampling rate to the other cannot cause
  85      * lost events, nor can transitioning from a high maximum report latency to
  86      * a low maximum report latency.
  87      * See the Batching sensor results page for details:
  88      * http://source.android.com/devices/sensors/batching.html
  89      *
  90      * @param  sensorHandle handle of sensor to be changed.
  91      * @param  samplingPeriodNs specifies sensor sample period in nanoseconds.
  92      * @param  maxReportLatencyNs allowed delay time before an event is sampled
  93      *         to time of report.
  94      * @return result OK on success, BAD_VALUE if any parameters are invalid.
  95      */
  96     batch(int32_t sensorHandle,
  97           int64_t samplingPeriodNs,
  98           int64_t maxReportLatencyNs) generates (Result result);
  99
 100     /**
 101      * Trigger a flush of internal FIFO.
 102      *
 103      * Flush adds a FLUSH_COMPLETE metadata event to the end of the "batch mode"
 104      * FIFO for the specified sensor and flushes the FIFO.  If the FIFO is empty
 105      * or if the sensor doesn't support batching (FIFO size zero), return
 106      * SUCCESS and add a trivial FLUSH_COMPLETE event added to the event stream.
 107      * This applies to all sensors other than one-shot sensors. If the sensor
 108      * is a one-shot sensor, flush must return BAD_VALUE and not generate any
 109      * flush complete metadata.  If the sensor is not active at the time flush()
 110      * is called, flush() return BAD_VALUE.
 111      *
 112      * @param   sensorHandle handle of sensor to be flushed.
 113      * @return  result OK on success and BAD_VALUE if sensorHandle is invalid.
 114      */
 115     flush(int32_t sensorHandle) generates (Result result);
 116
 117     /**
 118      * Inject a single sensor event or push operation environment parameters to
 119      * device.
 120      *
 121      * When device is in NORMAL mode, this function is called to push operation
 122      * environment data to device. In this operation, Event is always of
 123      * SensorType::AdditionalInfo type. See operation evironment parameters
 124      * section in AdditionalInfoType.
 125      *
 126      * When device is in DATA_INJECTION mode, this function is also used for
 127      * injecting sensor events.
 128      *
 129      * Regardless of OperationMode, injected SensorType::ADDITIONAL_INFO
 130      * type events should not be routed back to poll() function.
 131      *
 132      * @see AdditionalInfoType
 133      * @see OperationMode
 134      * @param   event sensor event to be injected
 135      * @return  result OK on success; PERMISSION_DENIED if operation is not
 136      *          allowed; INVALID_OPERATION, if this functionality is
 137      *          unsupported; BAD_VALUE if sensor event cannot be injected.
 138      */
 139     injectSensorData(Event event) generates (Result result);
 140
 141     /**
 142      * Register direct report channel.
 143      *
 144      * Register a direct channel with supplied shared memory information. Upon
 145      * return, the sensor hardware is responsible for resetting the memory
 146      * content to initial value (depending on memory format settings).
 147      *
 148      * @param   mem shared memory info data structure.
 149      * @return  result OK on success; BAD_VALUE if shared memory information is
 150      *          not consistent; NO_MEMORY if shared memory cannot be used by
 151      *          sensor system; INVALID_OPERATION if functionality is not
 152      *          supported.
 153      * @return  channelHandle a positive integer used for referencing registered
 154      *          direct channel (>0) in configureDirectReport and
 155      *          unregisterDirectChannel if result is OK, -1 otherwise.
 156      */
 157     registerDirectChannel(SharedMemInfo mem)
 158             generates (Result result, int32_t channelHandle);
 159
 160     /**
 161      * Unregister direct report channel.
 162      *
 163      * Unregister a direct channel previously registered using
 164      * registerDirectChannel, and remove all active sensor report configured in
 165      * still active sensor report configured in the direct channel.
 166      *
 167      * @param   channelHandle handle of direct channel to be unregistered.
 168      * @return  result OK if direct report is supported; INVALID_OPERATION
 169      *          otherwise.
 170      */
 171     unregisterDirectChannel(int32_t channelHandle) generates (Result result);
 172
 173     /**
 174      * Configure direct sensor event report in direct channel.
 175      *
 176      * This function start, modify rate or stop direct report of a sensor in a
 177      * certain direct channel.
 178      *
 179      * @param   sensorHandle handle of sensor to be configured. When combined
 180      *          with STOP rate, sensorHandle can be -1 to denote all active
 181      *          sensors in the direct channel specified by channel Handle.
 182      * @param   channelHandle handle of direct channel to be configured.
 183      * @param   rate rate level, see RateLevel enum.
 184      *
 185      * @return  result OK on success; BAD_VALUE if parameter is invalid (such as
 186      *          rate level is not supported by sensor, channelHandle does not
 187      *          exist, etc); INVALID_OPERATION if functionality is not
 188      *          supported.
 189      * @return  reportToken positive integer to identify multiple sensors of
 190      *          the same type in a single direct channel. Ignored if rate is
 191      *          STOP. See SharedMemFormat.
 192      */
 193     configDirectReport(
 194             int32_t sensorHandle, int32_t channelHandle, RateLevel rate)
 195             generates (Result result, int32_t reportToken);
 196 };