1 /*
2 * Copyright (C) 2012 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 #ifndef ANDROID_SENSORS_INTERFACE_H
18 #define ANDROID_SENSORS_INTERFACE_H
19
20 #include <stdint.h>
21 #include <sys/cdefs.h>
22 #include <sys/types.h>
23
24 #include <hardware/hardware.h>
25 #include <cutils/native_handle.h>
26
27 #include "sensors-base.h"
28
29 __BEGIN_DECLS
30
31 /*****************************************************************************/
32
33 #define SENSORS_HEADER_VERSION 1
34 #define SENSORS_MODULE_API_VERSION_0_1 HARDWARE_MODULE_API_VERSION(0, 1)
35 #define SENSORS_DEVICE_API_VERSION_0_1 HARDWARE_DEVICE_API_VERSION_2(0, 1, SENSORS_HEADER_VERSION)
36 #define SENSORS_DEVICE_API_VERSION_1_0 HARDWARE_DEVICE_API_VERSION_2(1, 0, SENSORS_HEADER_VERSION)
37 #define SENSORS_DEVICE_API_VERSION_1_1 HARDWARE_DEVICE_API_VERSION_2(1, 1, SENSORS_HEADER_VERSION)
38 #define SENSORS_DEVICE_API_VERSION_1_2 HARDWARE_DEVICE_API_VERSION_2(1, 2, SENSORS_HEADER_VERSION)
39 #define SENSORS_DEVICE_API_VERSION_1_3 HARDWARE_DEVICE_API_VERSION_2(1, 3, SENSORS_HEADER_VERSION)
40 #define SENSORS_DEVICE_API_VERSION_1_4 HARDWARE_DEVICE_API_VERSION_2(1, 4, SENSORS_HEADER_VERSION)
41
42 /**
43 * Please see the Sensors section of source.android.com for an
44 * introduction to and detailed descriptions of Android sensor types:
45 * http://source.android.com/devices/sensors/index.html
46 */
47
48 /**
49 * The id of this module
50 */
51 #define SENSORS_HARDWARE_MODULE_ID "sensors"
52
53 /**
54 * Name of the sensors device to open
55 */
56 #define SENSORS_HARDWARE_POLL "poll"
57
58 /**
59 * Sensor handle is greater than 0 and less than INT32_MAX.
60 *
61 * **** Deprecated ****
62 * Defined values below are kept for code compatibility. Note sensor handle can be as large as
63 * INT32_MAX.
64 */
65 #define SENSORS_HANDLE_BASE 0
66 #define SENSORS_HANDLE_BITS 31
67 #define SENSORS_HANDLE_COUNT (1ull<<SENSORS_HANDLE_BITS)
68
69
70 /*
71 * **** Deprecated *****
72 * flags for (*batch)()
73 * Availability: SENSORS_DEVICE_API_VERSION_1_0
74 * see (*batch)() documentation for details.
75 * Deprecated as of SENSORS_DEVICE_API_VERSION_1_3.
76 * WAKE_UP_* sensors replace WAKE_UPON_FIFO_FULL concept.
77 */
78 enum {
79 SENSORS_BATCH_DRY_RUN = 0x00000001,
80 SENSORS_BATCH_WAKE_UPON_FIFO_FULL = 0x00000002
81 };
82
83 /*
84 * what field for meta_data_event_t
85 */
86 enum {
87 /* a previous flush operation has completed */
88 // META_DATA_FLUSH_COMPLETE = 1,
89 META_DATA_VERSION /* always last, leave auto-assigned */
90 };
91
92 /*
93 * The permission to use for body sensors (like heart rate monitors).
94 * See sensor types for more details on what sensors should require this
95 * permission.
96 */
97 #define SENSOR_PERMISSION_BODY_SENSORS "android.permission.BODY_SENSORS"
98
99 /*
100 * sensor flags legacy names
101 *
102 * please use SENSOR_FLAG_* directly for new implementation.
103 * @see sensor_t
104 */
105
106 #define SENSOR_FLAG_MASK(nbit, shift) (((1<<(nbit))-1)<<(shift))
107 #define SENSOR_FLAG_MASK_1(shift) SENSOR_FLAG_MASK(1, shift)
108
109 /*
110 * Mask and shift for reporting mode sensor flags defined above.
111 */
112 #define REPORTING_MODE_SHIFT SENSOR_FLAG_SHIFT_REPORTING_MODE
113 #define REPORTING_MODE_NBIT (3)
114 #define REPORTING_MODE_MASK SENSOR_FLAG_MASK_REPORTING_MODE
115
116 /*
117 * Mask and shift for data_injection mode sensor flags defined above.
118 */
119 #define DATA_INJECTION_SHIFT SENSOR_FLAG_SHIFT_DATA_INJECTION
120 #define DATA_INJECTION_MASK SENSOR_FLAG_DATA_INJECTION
121
122 /*
123 * Mask and shift for dynamic sensor flag.
124 */
125 #define DYNAMIC_SENSOR_SHIFT SENSOR_FLAG_SHIFT_DYNAMIC_SENSOR
126 #define DYNAMIC_SENSOR_MASK SENSOR_FLAG_DYNAMIC_SENSOR
127
128 /*
129 * Mask and shift for sensor additional information support.
130 */
131 #define ADDITIONAL_INFO_SHIFT SENSOR_FLAG_SHIFT_ADDITIONAL_INFO
132 #define ADDITIONAL_INFO_MASK SENSOR_FLAG_ADDITIONAL_INFO
133
134 /*
135 * Legacy alias of SENSOR_TYPE_MAGNETIC_FIELD.
136 *
137 * Previously, the type of a sensor measuring local magnetic field is named
138 * SENSOR_TYPE_GEOMAGNETIC_FIELD and SENSOR_TYPE_MAGNETIC_FIELD is its alias.
139 * SENSOR_TYPE_MAGNETIC_FIELD is redefined as primary name to avoid confusion.
140 * SENSOR_TYPE_GEOMAGNETIC_FIELD is the alias and is deprecating. New implementation must not use
141 * SENSOR_TYPE_GEOMAGNETIC_FIELD.
142 */
143 #define SENSOR_TYPE_GEOMAGNETIC_FIELD SENSOR_TYPE_MAGNETIC_FIELD
144
145 /*
146 * Sensor string types for Android defined sensor types.
147 *
148 * For Android defined sensor types, string type will be override in sensor service and thus no
149 * longer needed to be added to sensor_t data structure.
150 *
151 * These definitions are going to be removed soon.
152 */
153 #define SENSOR_STRING_TYPE_ACCELEROMETER "android.sensor.accelerometer"
154 #define SENSOR_STRING_TYPE_MAGNETIC_FIELD "android.sensor.magnetic_field"
155 #define SENSOR_STRING_TYPE_ORIENTATION "android.sensor.orientation"
156 #define SENSOR_STRING_TYPE_GYROSCOPE "android.sensor.gyroscope"
157 #define SENSOR_STRING_TYPE_LIGHT "android.sensor.light"
158 #define SENSOR_STRING_TYPE_PRESSURE "android.sensor.pressure"
159 #define SENSOR_STRING_TYPE_TEMPERATURE "android.sensor.temperature"
160 #define SENSOR_STRING_TYPE_PROXIMITY "android.sensor.proximity"
161 #define SENSOR_STRING_TYPE_GRAVITY "android.sensor.gravity"
162 #define SENSOR_STRING_TYPE_LINEAR_ACCELERATION "android.sensor.linear_acceleration"
163 #define SENSOR_STRING_TYPE_ROTATION_VECTOR "android.sensor.rotation_vector"
164 #define SENSOR_STRING_TYPE_RELATIVE_HUMIDITY "android.sensor.relative_humidity"
165 #define SENSOR_STRING_TYPE_AMBIENT_TEMPERATURE "android.sensor.ambient_temperature"
166 #define SENSOR_STRING_TYPE_MAGNETIC_FIELD_UNCALIBRATED "android.sensor.magnetic_field_uncalibrated"
167 #define SENSOR_STRING_TYPE_GAME_ROTATION_VECTOR "android.sensor.game_rotation_vector"
168 #define SENSOR_STRING_TYPE_GYROSCOPE_UNCALIBRATED "android.sensor.gyroscope_uncalibrated"
169 #define SENSOR_STRING_TYPE_SIGNIFICANT_MOTION "android.sensor.significant_motion"
170 #define SENSOR_STRING_TYPE_STEP_DETECTOR "android.sensor.step_detector"
171 #define SENSOR_STRING_TYPE_STEP_COUNTER "android.sensor.step_counter"
172 #define SENSOR_STRING_TYPE_GEOMAGNETIC_ROTATION_VECTOR "android.sensor.geomagnetic_rotation_vector"
173 #define SENSOR_STRING_TYPE_HEART_RATE "android.sensor.heart_rate"
174 #define SENSOR_STRING_TYPE_TILT_DETECTOR "android.sensor.tilt_detector"
175 #define SENSOR_STRING_TYPE_WAKE_GESTURE "android.sensor.wake_gesture"
176 #define SENSOR_STRING_TYPE_GLANCE_GESTURE "android.sensor.glance_gesture"
177 #define SENSOR_STRING_TYPE_PICK_UP_GESTURE "android.sensor.pick_up_gesture"
178 #define SENSOR_STRING_TYPE_WRIST_TILT_GESTURE "android.sensor.wrist_tilt_gesture"
179 #define SENSOR_STRING_TYPE_DEVICE_ORIENTATION "android.sensor.device_orientation"
180 #define SENSOR_STRING_TYPE_POSE_6DOF "android.sensor.pose_6dof"
181 #define SENSOR_STRING_TYPE_STATIONARY_DETECT "android.sensor.stationary_detect"
182 #define SENSOR_STRING_TYPE_MOTION_DETECT "android.sensor.motion_detect"
183 #define SENSOR_STRING_TYPE_HEART_BEAT "android.sensor.heart_beat"
184 #define SENSOR_STRING_TYPE_DYNAMIC_SENSOR_META "android.sensor.dynamic_sensor_meta"
185 #define SENSOR_STRING_TYPE_ADDITIONAL_INFO "android.sensor.additional_info"
186 #define SENSOR_STRING_TYPE_LOW_LATENCY_OFFBODY_DETECT "android.sensor.low_latency_offbody_detect"
187 #define SENSOR_STRING_TYPE_ACCELEROMETER_UNCALIBRATED "android.sensor.accelerometer_uncalibrated"
188 #define SENSOR_STRING_TYPE_HINGE_ANGLE "android.sensor.hinge_angle"
189
190 /**
191 * Values returned by the accelerometer in various locations in the universe.
192 * all values are in SI units (m/s^2)
193 */
194 #define GRAVITY_SUN (275.0f)
195 #define GRAVITY_EARTH (9.80665f)
196
197 /** Maximum magnetic field on Earth's surface */
198 #define MAGNETIC_FIELD_EARTH_MAX (60.0f)
199
200 /** Minimum magnetic field on Earth's surface */
201 #define MAGNETIC_FIELD_EARTH_MIN (30.0f)
202
203 struct sensor_t;
204
205 /**
206 * sensor event data
207 */
208 typedef struct {
209 union {
210 float v[3];
211 struct {
212 float x;
213 float y;
214 float z;
215 };
216 struct {
217 float azimuth;
218 float pitch;
219 float roll;
220 };
221 };
222 int8_t status;
223 uint8_t reserved[3];
224 } sensors_vec_t;
225
226 /**
227 * uncalibrated accelerometer, gyroscope and magnetometer event data
228 */
229 typedef struct {
230 union {
231 float uncalib[3];
232 struct {
233 float x_uncalib;
234 float y_uncalib;
235 float z_uncalib;
236 };
237 };
238 union {
239 float bias[3];
240 struct {
241 float x_bias;
242 float y_bias;
243 float z_bias;
244 };
245 };
246 } uncalibrated_event_t;
247
248 /**
249 * Meta data event data
250 */
251 typedef struct meta_data_event {
252 int32_t what;
253 int32_t sensor;
254 } meta_data_event_t;
255
256 /**
257 * Dynamic sensor meta event. See the description of SENSOR_TYPE_DYNAMIC_SENSOR_META type for
258 * details.
259 */
260 typedef struct dynamic_sensor_meta_event {
261 int32_t connected;
262 int32_t handle;
263 const struct sensor_t * sensor; // should be NULL if connected == false
264 uint8_t uuid[16]; // UUID of a dynamic sensor (using RFC 4122 byte order)
265 // For UUID 12345678-90AB-CDEF-1122-334455667788 the uuid field
266 // should be initialized as:
267 // {0x12, 0x34, 0x56, 0x78, 0x90, 0xAB, 0xCD, 0xEF, 0x11, ...}
268 } dynamic_sensor_meta_event_t;
269
270 /**
271 * Heart rate event data
272 */
273 typedef struct {
274 // Heart rate in beats per minute.
275 // Set to 0 when status is SENSOR_STATUS_UNRELIABLE or ..._NO_CONTACT
276 float bpm;
277 // Status of the sensor for this reading. Set to one SENSOR_STATUS_...
278 // Note that this value should only be set for sensors that explicitly define
279 // the meaning of this field. This field is not piped through the framework
280 // for other sensors.
281 int8_t status;
282 } heart_rate_event_t;
283
284 typedef struct {
285 int32_t type; // type of payload data, see additional_info_type_t
286 int32_t serial; // sequence number of this frame for this type
287 union {
288 // for each frame, a single data type, either int32_t or float, should be used.
289 int32_t data_int32[14];
290 float data_float[14];
291 };
292 } additional_info_event_t;
293
294 /**
295 * Union of the various types of sensor data
296 * that can be returned.
297 */
298 typedef struct sensors_event_t {
299 /* must be sizeof(struct sensors_event_t) */
300 int32_t version;
301
302 /* sensor identifier */
303 int32_t sensor;
304
305 /* sensor type */
306 int32_t type;
307
308 /* reserved */
309 int32_t reserved0;
310
311 /* time is in nanosecond */
312 int64_t timestamp;
313
314 union {
315 union {
316 float data[16];
317
318 /* acceleration values are in meter per second per second (m/s^2) */
319 sensors_vec_t acceleration;
320
321 /* magnetic vector values are in micro-Tesla (uT) */
322 sensors_vec_t magnetic;
323
324 /* orientation values are in degrees */
325 sensors_vec_t orientation;
326
327 /* gyroscope values are in rad/s */
328 sensors_vec_t gyro;
329
330 /* temperature is in degrees centigrade (Celsius) */
331 float temperature;
332
333 /* distance in centimeters */
334 float distance;
335
336 /* light in SI lux units */
337 float light;
338
339 /* pressure in hectopascal (hPa) */
340 float pressure;
341
342 /* relative humidity in percent */
343 float relative_humidity;
344
345 /* uncalibrated gyroscope values are in rad/s */
346 uncalibrated_event_t uncalibrated_gyro;
347
348 /* uncalibrated magnetometer values are in micro-Teslas */
349 uncalibrated_event_t uncalibrated_magnetic;
350
351 /* uncalibrated accelerometer values are in meter per second per second (m/s^2) */
352 uncalibrated_event_t uncalibrated_accelerometer;
353
354 /* heart rate data containing value in bpm and status */
355 heart_rate_event_t heart_rate;
356
357 /* this is a special event. see SENSOR_TYPE_META_DATA above.
358 * sensors_meta_data_event_t events are all reported with a type of
359 * SENSOR_TYPE_META_DATA. The handle is ignored and must be zero.
360 */
361 meta_data_event_t meta_data;
362
363 /* dynamic sensor meta event. See SENSOR_TYPE_DYNAMIC_SENSOR_META type for details */
364 dynamic_sensor_meta_event_t dynamic_sensor_meta;
365
366 /*
367 * special additional sensor information frame, see
368 * SENSOR_TYPE_ADDITIONAL_INFO for details.
369 */
370 additional_info_event_t additional_info;
371 };
372
373 union {
374 uint64_t data[8];
375
376 /* step-counter */
377 uint64_t step_counter;
378 } u64;
379 };
380
381 /* Reserved flags for internal use. Set to zero. */
382 uint32_t flags;
383
384 uint32_t reserved1[3];
385 } sensors_event_t;
386
387
388 /* see SENSOR_TYPE_META_DATA */
389 typedef sensors_event_t sensors_meta_data_event_t;
390
391
392 /**
393 * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM
394 * and the fields of this data structure must begin with hw_module_t
395 * followed by module specific information.
396 */
397 struct sensors_module_t {
398 struct hw_module_t common;
399
400 /**
401 * Enumerate all available sensors. The list is returned in "list".
402 * return number of sensors in the list
403 */
404 int (*get_sensors_list)(struct sensors_module_t* module,
405 struct sensor_t const** list);
406
407 /**
408 * Place the module in a specific mode. The following modes are defined
409 *
410 * 0 - Normal operation. Default state of the module.
411 * 1 - Loopback mode. Data is injected for the supported
412 * sensors by the sensor service in this mode.
413 * return 0 on success
414 * -EINVAL if requested mode is not supported
415 * -EPERM if operation is not allowed
416 */
417 int (*set_operation_mode)(unsigned int mode);
418 };
419
420 struct sensor_t {
421
422 /* Name of this sensor.
423 * All sensors of the same "type" must have a different "name".
424 */
425 const char* name;
426
427 /* vendor of the hardware part */
428 const char* vendor;
429
430 /* version of the hardware part + driver. The value of this field
431 * must increase when the driver is updated in a way that changes the
432 * output of this sensor. This is important for fused sensors when the
433 * fusion algorithm is updated.
434 */
435 int version;
436
437 /* handle that identifies this sensors. This handle is used to reference
438 * this sensor throughout the HAL API.
439 */
440 int handle;
441
442 /* this sensor's type. */
443 int type;
444
445 /* maximum range of this sensor's value in SI units */
446 float maxRange;
447
448 /* smallest difference between two values reported by this sensor */
449 float resolution;
450
451 /* rough estimate of this sensor's power consumption in mA */
452 float power;
453
454 /* this value depends on the reporting mode:
455 *
456 * continuous: minimum sample period allowed in microseconds
457 * on-change : 0
458 * one-shot :-1
459 * special : 0, unless otherwise noted
460 */
461 int32_t minDelay;
462
463 /* number of events reserved for this sensor in the batch mode FIFO.
464 * If there is a dedicated FIFO for this sensor, then this is the
465 * size of this FIFO. If the FIFO is shared with other sensors,
466 * this is the size reserved for that sensor and it can be zero.
467 */
468 uint32_t fifoReservedEventCount;
469
470 /* maximum number of events of this sensor that could be batched.
471 * This is especially relevant when the FIFO is shared between
472 * several sensors; this value is then set to the size of that FIFO.
473 */
474 uint32_t fifoMaxEventCount;
475
476 /* type of this sensor as a string.
477 *
478 * If type is OEM specific or sensor manufacturer specific type
479 * (>=SENSOR_TYPE_DEVICE_PRIVATE_BASE), this string must be defined with reserved domain of
480 * vendor/OEM as a prefix, e.g. com.google.glass.onheaddetector
481 *
482 * For sensors of Android defined types, Android framework will override this value. It is ok to
483 * leave it pointing to an empty string.
484 */
485 const char* stringType;
486
487 /* permission required to see this sensor, register to it and receive data.
488 * Set to "" if no permission is required. Some sensor types like the
489 * heart rate monitor have a mandatory require_permission.
490 * For sensors that always require a specific permission, like the heart
491 * rate monitor, the android framework might overwrite this string
492 * automatically.
493 */
494 const char* requiredPermission;
495
496 /* This value is defined only for continuous mode and on-change sensors. It is the delay between
497 * two sensor events corresponding to the lowest frequency that this sensor supports. When lower
498 * frequencies are requested through batch()/setDelay() the events will be generated at this
499 * frequency instead. It can be used by the framework or applications to estimate when the batch
500 * FIFO may be full.
501 *
502 * NOTE: 1) period_ns is in nanoseconds where as maxDelay/minDelay are in microseconds.
503 * continuous, on-change: maximum sampling period allowed in microseconds.
504 * one-shot, special : 0
505 * 2) maxDelay should always fit within a 32 bit signed integer. It is declared as 64 bit
506 * on 64 bit architectures only for binary compatibility reasons.
507 * Availability: SENSORS_DEVICE_API_VERSION_1_3
508 */
509 #ifdef __LP64__
510 int64_t maxDelay;
511 #else
512 int32_t maxDelay;
513 #endif
514
515 /* Flags for sensor. See SENSOR_FLAG_* above. Only the least significant 32 bits are used here.
516 * It is declared as 64 bit on 64 bit architectures only for binary compatibility reasons.
517 * Availability: SENSORS_DEVICE_API_VERSION_1_3
518 */
519 #ifdef __LP64__
520 uint64_t flags;
521 #else
522 uint32_t flags;
523 #endif
524
525 /* reserved fields, must be zero */
526 void* reserved[2];
527 };
528
529 /**
530 * Shared memory information for a direct channel
531 */
532 struct sensors_direct_mem_t {
533 int type; // enum SENSOR_DIRECT_MEM_...
534 int format; // enum SENSOR_DIRECT_FMT_...
535 size_t size; // size of the memory region, in bytes
536 const struct native_handle *handle; // shared memory handle, which is interpreted differently
537 // depending on type
538 };
539
540 /**
541 * Direct channel report configuration
542 */
543 struct sensors_direct_cfg_t {
544 int rate_level; // enum SENSOR_DIRECT_RATE_...
545 };
546
547 /*
548 * sensors_poll_device_t is used with SENSORS_DEVICE_API_VERSION_0_1
549 * and is present for backward binary and source compatibility.
550 * See the Sensors HAL interface section for complete descriptions of the
551 * following functions:
552 * http://source.android.com/devices/sensors/index.html#hal
553 */
554 struct sensors_poll_device_t {
555 struct hw_device_t common;
556 int (*activate)(struct sensors_poll_device_t *dev,
557 int sensor_handle, int enabled);
558 int (*setDelay)(struct sensors_poll_device_t *dev,
559 int sensor_handle, int64_t sampling_period_ns);
560 int (*poll)(struct sensors_poll_device_t *dev,
561 sensors_event_t* data, int count);
562 };
563
564 /*
565 * struct sensors_poll_device_1 is used in HAL versions >= SENSORS_DEVICE_API_VERSION_1_0
566 */
567 typedef struct sensors_poll_device_1 {
568 union {
569 /* sensors_poll_device_1 is compatible with sensors_poll_device_t,
570 * and can be down-cast to it
571 */
572 struct sensors_poll_device_t v0;
573
574 struct {
575 struct hw_device_t common;
576
577 /* Activate/de-activate one sensor.
578 *
579 * sensor_handle is the handle of the sensor to change.
580 * enabled set to 1 to enable, or 0 to disable the sensor.
581 *
582 * Before sensor activation, existing sensor events that have not
583 * been picked up by poll() should be abandoned so that application
584 * upon new activation request will not get stale events.
585 * (events that are generated during latter activation or during
586 * data injection mode after sensor deactivation)
587 *
588 * Return 0 on success, negative errno code otherwise.
589 */
590 int (*activate)(struct sensors_poll_device_t *dev,
591 int sensor_handle, int enabled);
592
593 /**
594 * Set the events's period in nanoseconds for a given sensor.
595 * If sampling_period_ns > max_delay it will be truncated to
596 * max_delay and if sampling_period_ns < min_delay it will be
597 * replaced by min_delay.
598 */
599 int (*setDelay)(struct sensors_poll_device_t *dev,
600 int sensor_handle, int64_t sampling_period_ns);
601
602 /**
603 * Write an array of sensor_event_t to data. The size of the
604 * available buffer is specified by count. Returns number of
605 * valid sensor_event_t.
606 *
607 * This function should block if there is no sensor event
608 * available when being called. Thus, return value should always be
609 * positive.
610 */
611 int (*poll)(struct sensors_poll_device_t *dev,
612 sensors_event_t* data, int count);
613 };
614 };
615
616
617 /*
618 * Sets a sensor’s parameters, including sampling frequency and maximum
619 * report latency. This function can be called while the sensor is
620 * activated, in which case it must not cause any sensor measurements to
621 * be lost: transitioning from one sampling rate to the other cannot cause
622 * lost events, nor can transitioning from a high maximum report latency to
623 * a low maximum report latency.
624 * See the Batching sensor results page for details:
625 * http://source.android.com/devices/sensors/batching.html
626 */
627 int (*batch)(struct sensors_poll_device_1* dev,
628 int sensor_handle, int flags, int64_t sampling_period_ns,
629 int64_t max_report_latency_ns);
630
631 /*
632 * Flush adds a META_DATA_FLUSH_COMPLETE event (sensors_event_meta_data_t)
633 * to the end of the "batch mode" FIFO for the specified sensor and flushes
634 * the FIFO.
635 * If the FIFO is empty or if the sensor doesn't support batching (FIFO size zero),
636 * it should return SUCCESS along with a trivial META_DATA_FLUSH_COMPLETE event added to the
637 * event stream. This applies to all sensors other than one-shot sensors.
638 * If the sensor is a one-shot sensor, flush must return -EINVAL and not generate
639 * any flush complete metadata.
640 * If the sensor is not active at the time flush() is called, flush() should return
641 * -EINVAL.
642 */
643 int (*flush)(struct sensors_poll_device_1* dev, int sensor_handle);
644
645 /*
646 * Inject a single sensor sample to be to this device.
647 * data points to the sensor event to be injected
648 * return 0 on success
649 * -EPERM if operation is not allowed
650 * -EINVAL if sensor event cannot be injected
651 */
652 int (*inject_sensor_data)(struct sensors_poll_device_1 *dev, const sensors_event_t *data);
653
654 /*
655 * Register/unregister direct report channel.
656 *
657 * A HAL declares support for direct report by setting non-NULL values for both
658 * register_direct_channel and config_direct_report.
659 *
660 * This function has two operation modes:
661 *
662 * Register: mem != NULL, register a channel using supplied shared memory information. By the
663 * time this function returns, sensors must finish initializing shared memory content
664 * (format dependent, see SENSOR_DIRECT_FMT_*).
665 * Parameters:
666 * mem points to a valid struct sensors_direct_mem_t.
667 * channel_handle is ignored.
668 * Return value:
669 * A handle of channel (>0, <INT32_MAX) when success, which later can be referred in
670 * unregister or config_direct_report call, or error code (<0) when failed
671 * Unregister: mem == NULL, unregister a previously registered channel.
672 * Parameters:
673 * mem set to NULL
674 * channel_handle contains handle of channel to be unregistered
675 * Return value:
676 * 0, even if the channel_handle is invalid, in which case it will be a no-op.
677 */
678 int (*register_direct_channel)(struct sensors_poll_device_1 *dev,
679 const struct sensors_direct_mem_t* mem, int channel_handle);
680
681 /*
682 * Configure direct sensor event report in direct channel.
683 *
684 * Start, modify rate or stop direct report of a sensor in a certain direct channel. A special
685 * case is setting sensor handle -1 to stop means to stop all active sensor report on the
686 * channel specified.
687 *
688 * A HAL declares support for direct report by setting non-NULL values for both
689 * register_direct_channel and config_direct_report.
690 *
691 * Parameters:
692 * sensor_handle sensor to be configured. The sensor has to support direct report
693 * mode by setting flags of sensor_t. Also, direct report mode is only
694 * defined for continuous reporting mode sensors.
695 * channel_handle channel handle to be configured.
696 * config direct report parameters, see sensor_direct_cfg_t.
697 * Return value:
698 * - when sensor is started or sensor rate level is changed: return positive identifier of
699 * sensor in specified channel if successful, otherwise return negative error code.
700 * - when sensor is stopped: return 0 for success or negative error code for failure.
701 */
702 int (*config_direct_report)(struct sensors_poll_device_1 *dev,
703 int sensor_handle, int channel_handle, const struct sensors_direct_cfg_t *config);
704
705 /*
706 * Reserved for future use, must be zero.
707 */
708 void (*reserved_procs[5])(void);
709
710 } sensors_poll_device_1_t;
711
712
713 /** convenience API for opening and closing a device */
714
sensors_open(const struct hw_module_t * module,struct sensors_poll_device_t ** device)715 static inline int sensors_open(const struct hw_module_t* module,
716 struct sensors_poll_device_t** device) {
717 return module->methods->open(module,
718 SENSORS_HARDWARE_POLL, TO_HW_DEVICE_T_OPEN(device));
719 }
720
sensors_close(struct sensors_poll_device_t * device)721 static inline int sensors_close(struct sensors_poll_device_t* device) {
722 return device->common.close(&device->common);
723 }
724
sensors_open_1(const struct hw_module_t * module,sensors_poll_device_1_t ** device)725 static inline int sensors_open_1(const struct hw_module_t* module,
726 sensors_poll_device_1_t** device) {
727 return module->methods->open(module,
728 SENSORS_HARDWARE_POLL, TO_HW_DEVICE_T_OPEN(device));
729 }
730
sensors_close_1(sensors_poll_device_1_t * device)731 static inline int sensors_close_1(sensors_poll_device_1_t* device) {
732 return device->common.close(&device->common);
733 }
734
735 __END_DECLS
736
737 #endif // ANDROID_SENSORS_INTERFACE_H
738