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 #define SENSOR_STRING_TYPE_HEAD_TRACKER "android.sensor.head_tracker"
190 #define SENSOR_STRING_TYPE_ACCELEROMETER_LIMITED_AXES "android.sensor.accelerometer_limited_axes"
191 #define SENSOR_STRING_TYPE_GYROSCOPE_LIMITED_AXES "android.sensor.gyroscope_limited_axes"
192 #define SENSOR_STRING_TYPE_ACCELEROMETER_LIMITED_AXES_UNCALIBRATED "android.sensor.accelerometer_limited_axes_uncalibrated"
193 #define SENSOR_STRING_TYPE_GYROSCOPE_LIMITED_AXES_UNCALIBRATED "android.sensor.gyroscope_limited_axes_uncalibrated"
194 #define SENSOR_STRING_TYPE_HEADING "android.sensor.heading"
195
196 /**
197 * Values returned by the accelerometer in various locations in the universe.
198 * all values are in SI units (m/s^2)
199 */
200 #define GRAVITY_SUN (275.0f)
201 #define GRAVITY_EARTH (9.80665f)
202
203 /** Maximum magnetic field on Earth's surface */
204 #define MAGNETIC_FIELD_EARTH_MAX (60.0f)
205
206 /** Minimum magnetic field on Earth's surface */
207 #define MAGNETIC_FIELD_EARTH_MIN (30.0f)
208
209 struct sensor_t;
210
211 /**
212 * sensor event data
213 */
214 typedef struct {
215 union {
216 float v[3];
217 struct {
218 float x;
219 float y;
220 float z;
221 };
222 struct {
223 float azimuth;
224 float pitch;
225 float roll;
226 };
227 };
228 int8_t status;
229 uint8_t reserved[3];
230 } sensors_vec_t;
231
232 /**
233 * uncalibrated accelerometer, gyroscope and magnetometer event data
234 */
235 typedef struct {
236 union {
237 float uncalib[3];
238 struct {
239 float x_uncalib;
240 float y_uncalib;
241 float z_uncalib;
242 };
243 };
244 union {
245 float bias[3];
246 struct {
247 float x_bias;
248 float y_bias;
249 float z_bias;
250 };
251 };
252 } uncalibrated_event_t;
253
254 /**
255 * Meta data event data
256 */
257 typedef struct meta_data_event {
258 int32_t what;
259 int32_t sensor;
260 } meta_data_event_t;
261
262 /**
263 * Dynamic sensor meta event. See the description of SENSOR_TYPE_DYNAMIC_SENSOR_META type for
264 * details.
265 */
266 typedef struct dynamic_sensor_meta_event {
267 int32_t connected;
268 int32_t handle;
269 const struct sensor_t * sensor; // should be NULL if connected == false
270 uint8_t uuid[16]; // UUID of a dynamic sensor (using RFC 4122 byte order)
271 // For UUID 12345678-90AB-CDEF-1122-334455667788 the uuid field
272 // should be initialized as:
273 // {0x12, 0x34, 0x56, 0x78, 0x90, 0xAB, 0xCD, 0xEF, 0x11, ...}
274 } dynamic_sensor_meta_event_t;
275
276 /**
277 * Heart rate event data
278 */
279 typedef struct {
280 // Heart rate in beats per minute.
281 // Set to 0 when status is SENSOR_STATUS_UNRELIABLE or ..._NO_CONTACT
282 float bpm;
283 // Status of the sensor for this reading. Set to one SENSOR_STATUS_...
284 // Note that this value should only be set for sensors that explicitly define
285 // the meaning of this field. This field is not piped through the framework
286 // for other sensors.
287 int8_t status;
288 } heart_rate_event_t;
289
290 typedef struct {
291 int32_t type; // type of payload data, see additional_info_type_t
292 int32_t serial; // sequence number of this frame for this type
293 union {
294 // for each frame, a single data type, either int32_t or float, should be used.
295 int32_t data_int32[14];
296 float data_float[14];
297 };
298 } additional_info_event_t;
299
300 typedef struct {
301 float rx;
302 float ry;
303 float rz;
304 float vx;
305 float vy;
306 float vz;
307 int32_t discontinuity_count;
308 } head_tracker_event_t;
309
310 /**
311 * limited axes imu event data
312 */
313 typedef struct {
314 union {
315 float calib[3];
316 struct {
317 float x;
318 float y;
319 float z;
320 };
321 };
322 union {
323 float supported[3];
324 struct {
325 float x_supported;
326 float y_supported;
327 float z_supported;
328 };
329 };
330 } limited_axes_imu_event_t;
331
332 /**
333 * limited axes uncalibrated imu event data
334 */
335 typedef struct {
336 union {
337 float uncalib[3];
338 struct {
339 float x_uncalib;
340 float y_uncalib;
341 float z_uncalib;
342 };
343 };
344 union {
345 float bias[3];
346 struct {
347 float x_bias;
348 float y_bias;
349 float z_bias;
350 };
351 };
352 union {
353 float supported[3];
354 struct {
355 float x_supported;
356 float y_supported;
357 float z_supported;
358 };
359 };
360 } limited_axes_imu_uncalibrated_event_t;
361
362 /**
363 * Heading event data
364 */
365 typedef struct {
366 float heading;
367 float accuracy;
368 } heading_event_t;
369
370 /**
371 * Union of the various types of sensor data
372 * that can be returned.
373 */
374 typedef struct sensors_event_t {
375 /* must be sizeof(struct sensors_event_t) */
376 int32_t version;
377
378 /* sensor identifier */
379 int32_t sensor;
380
381 /* sensor type */
382 int32_t type;
383
384 /* reserved */
385 int32_t reserved0;
386
387 /* time is in nanosecond */
388 int64_t timestamp;
389
390 union {
391 union {
392 float data[16];
393
394 /* acceleration values are in meter per second per second (m/s^2) */
395 sensors_vec_t acceleration;
396
397 /* magnetic vector values are in micro-Tesla (uT) */
398 sensors_vec_t magnetic;
399
400 /* orientation values are in degrees */
401 sensors_vec_t orientation;
402
403 /* gyroscope values are in rad/s */
404 sensors_vec_t gyro;
405
406 /* temperature is in degrees centigrade (Celsius) */
407 float temperature;
408
409 /* distance in centimeters */
410 float distance;
411
412 /* light in SI lux units */
413 float light;
414
415 /* pressure in hectopascal (hPa) */
416 float pressure;
417
418 /* relative humidity in percent */
419 float relative_humidity;
420
421 /* uncalibrated gyroscope values are in rad/s */
422 uncalibrated_event_t uncalibrated_gyro;
423
424 /* uncalibrated magnetometer values are in micro-Teslas */
425 uncalibrated_event_t uncalibrated_magnetic;
426
427 /* uncalibrated accelerometer values are in meter per second per second (m/s^2) */
428 uncalibrated_event_t uncalibrated_accelerometer;
429
430 /* heart rate data containing value in bpm and status */
431 heart_rate_event_t heart_rate;
432
433 /* this is a special event. see SENSOR_TYPE_META_DATA above.
434 * sensors_meta_data_event_t events are all reported with a type of
435 * SENSOR_TYPE_META_DATA. The handle is ignored and must be zero.
436 */
437 meta_data_event_t meta_data;
438
439 /* dynamic sensor meta event. See SENSOR_TYPE_DYNAMIC_SENSOR_META type for details */
440 dynamic_sensor_meta_event_t dynamic_sensor_meta;
441
442 /*
443 * special additional sensor information frame, see
444 * SENSOR_TYPE_ADDITIONAL_INFO for details.
445 */
446 additional_info_event_t additional_info;
447
448 /* vector describing head orientation (added for legacy code support only) */
449 head_tracker_event_t head_tracker;
450
451 /*
452 * limited axes imu event, See
453 * SENSOR_TYPE_GYROSCOPE_LIMITED_AXES and
454 * SENSOR_TYPE_ACCELEROMETER_LIMITED_AXES for details.
455 */
456 limited_axes_imu_event_t limited_axes_imu;
457
458 /*
459 * limited axes imu uncalibrated event, See
460 * SENSOR_TYPE_GYROSCOPE_LIMITED_AXES_UNCALIBRATED and
461 * SENSOR_TYPE_ACCELEROMETER_LIMITED_AXES_UNCALIBRATED for details.
462 */
463 limited_axes_imu_uncalibrated_event_t limited_axes_imu_uncalibrated;
464
465 /* heading data containing value in degrees and its accuracy */
466 heading_event_t heading;
467 };
468
469 union {
470 uint64_t data[8];
471
472 /* step-counter */
473 uint64_t step_counter;
474 } u64;
475 };
476
477 /* Reserved flags for internal use. Set to zero. */
478 uint32_t flags;
479
480 uint32_t reserved1[3];
481 } sensors_event_t;
482
483
484 /* see SENSOR_TYPE_META_DATA */
485 typedef sensors_event_t sensors_meta_data_event_t;
486
487
488 /**
489 * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM
490 * and the fields of this data structure must begin with hw_module_t
491 * followed by module specific information.
492 */
493 struct sensors_module_t {
494 struct hw_module_t common;
495
496 /**
497 * Enumerate all available sensors. The list is returned in "list".
498 * return number of sensors in the list
499 */
500 int (*get_sensors_list)(struct sensors_module_t* module,
501 struct sensor_t const** list);
502
503 /**
504 * Place the module in a specific mode. The following modes are defined
505 *
506 * 0 - Normal operation. Default state of the module.
507 * 1 - Loopback mode. Data is injected for the supported
508 * sensors by the sensor service in this mode.
509 * return 0 on success
510 * -EINVAL if requested mode is not supported
511 * -EPERM if operation is not allowed
512 */
513 int (*set_operation_mode)(unsigned int mode);
514 };
515
516 struct sensor_t {
517
518 /* Name of this sensor.
519 * All sensors of the same "type" must have a different "name".
520 */
521 const char* name;
522
523 /* vendor of the hardware part */
524 const char* vendor;
525
526 /* version of the hardware part + driver. The value of this field
527 * must increase when the driver is updated in a way that changes the
528 * output of this sensor. This is important for fused sensors when the
529 * fusion algorithm is updated.
530 */
531 int version;
532
533 /* handle that identifies this sensors. This handle is used to reference
534 * this sensor throughout the HAL API.
535 */
536 int handle;
537
538 /* this sensor's type. */
539 int type;
540
541 /* maximum range of this sensor's value in SI units */
542 float maxRange;
543
544 /* smallest difference between two values reported by this sensor */
545 float resolution;
546
547 /* rough estimate of this sensor's power consumption in mA */
548 float power;
549
550 /* this value depends on the reporting mode:
551 *
552 * continuous: minimum sample period allowed in microseconds
553 * on-change : 0
554 * one-shot :-1
555 * special : 0, unless otherwise noted
556 */
557 int32_t minDelay;
558
559 /* number of events reserved for this sensor in the batch mode FIFO.
560 * If there is a dedicated FIFO for this sensor, then this is the
561 * size of this FIFO. If the FIFO is shared with other sensors,
562 * this is the size reserved for that sensor and it can be zero.
563 */
564 uint32_t fifoReservedEventCount;
565
566 /* maximum number of events of this sensor that could be batched.
567 * This is especially relevant when the FIFO is shared between
568 * several sensors; this value is then set to the size of that FIFO.
569 */
570 uint32_t fifoMaxEventCount;
571
572 /* type of this sensor as a string.
573 *
574 * If type is OEM specific or sensor manufacturer specific type
575 * (>=SENSOR_TYPE_DEVICE_PRIVATE_BASE), this string must be defined with reserved domain of
576 * vendor/OEM as a prefix, e.g. com.google.glass.onheaddetector
577 *
578 * For sensors of Android defined types, Android framework will override this value. It is ok to
579 * leave it pointing to an empty string.
580 */
581 const char* stringType;
582
583 /* permission required to see this sensor, register to it and receive data.
584 * Set to "" if no permission is required. Some sensor types like the
585 * heart rate monitor have a mandatory require_permission.
586 * For sensors that always require a specific permission, like the heart
587 * rate monitor, the android framework might overwrite this string
588 * automatically.
589 */
590 const char* requiredPermission;
591
592 /* This value is defined only for continuous mode and on-change sensors. It is the delay between
593 * two sensor events corresponding to the lowest frequency that this sensor supports. When lower
594 * frequencies are requested through batch()/setDelay() the events will be generated at this
595 * frequency instead. It can be used by the framework or applications to estimate when the batch
596 * FIFO may be full.
597 *
598 * NOTE: 1) period_ns is in nanoseconds where as maxDelay/minDelay are in microseconds.
599 * continuous, on-change: maximum sampling period allowed in microseconds.
600 * one-shot, special : 0
601 * 2) maxDelay should always fit within a 32 bit signed integer. It is declared as 64 bit
602 * on 64 bit architectures only for binary compatibility reasons.
603 * Availability: SENSORS_DEVICE_API_VERSION_1_3
604 */
605 #ifdef __LP64__
606 int64_t maxDelay;
607 #else
608 int32_t maxDelay;
609 #endif
610
611 /* Flags for sensor. See SENSOR_FLAG_* above. Only the least significant 32 bits are used here.
612 * It is declared as 64 bit on 64 bit architectures only for binary compatibility reasons.
613 * Availability: SENSORS_DEVICE_API_VERSION_1_3
614 */
615 #ifdef __LP64__
616 uint64_t flags;
617 #else
618 uint32_t flags;
619 #endif
620
621 /* reserved fields, must be zero */
622 void* reserved[2];
623 };
624
625 /**
626 * Shared memory information for a direct channel
627 */
628 struct sensors_direct_mem_t {
629 int type; // enum SENSOR_DIRECT_MEM_...
630 int format; // enum SENSOR_DIRECT_FMT_...
631 size_t size; // size of the memory region, in bytes
632 const struct native_handle *handle; // shared memory handle, which is interpreted differently
633 // depending on type
634 };
635
636 /**
637 * Direct channel report configuration
638 */
639 struct sensors_direct_cfg_t {
640 int rate_level; // enum SENSOR_DIRECT_RATE_...
641 };
642
643 /*
644 * sensors_poll_device_t is used with SENSORS_DEVICE_API_VERSION_0_1
645 * and is present for backward binary and source compatibility.
646 * See the Sensors HAL interface section for complete descriptions of the
647 * following functions:
648 * http://source.android.com/devices/sensors/index.html#hal
649 */
650 struct sensors_poll_device_t {
651 struct hw_device_t common;
652 int (*activate)(struct sensors_poll_device_t *dev,
653 int sensor_handle, int enabled);
654 int (*setDelay)(struct sensors_poll_device_t *dev,
655 int sensor_handle, int64_t sampling_period_ns);
656 int (*poll)(struct sensors_poll_device_t *dev,
657 sensors_event_t* data, int count);
658 };
659
660 /*
661 * struct sensors_poll_device_1 is used in HAL versions >= SENSORS_DEVICE_API_VERSION_1_0
662 */
663 typedef struct sensors_poll_device_1 {
664 union {
665 /* sensors_poll_device_1 is compatible with sensors_poll_device_t,
666 * and can be down-cast to it
667 */
668 struct sensors_poll_device_t v0;
669
670 struct {
671 struct hw_device_t common;
672
673 /* Activate/de-activate one sensor.
674 *
675 * sensor_handle is the handle of the sensor to change.
676 * enabled set to 1 to enable, or 0 to disable the sensor.
677 *
678 * Before sensor activation, existing sensor events that have not
679 * been picked up by poll() should be abandoned so that application
680 * upon new activation request will not get stale events.
681 * (events that are generated during latter activation or during
682 * data injection mode after sensor deactivation)
683 *
684 * Return 0 on success, negative errno code otherwise.
685 */
686 int (*activate)(struct sensors_poll_device_t *dev,
687 int sensor_handle, int enabled);
688
689 /**
690 * Set the events's period in nanoseconds for a given sensor.
691 * If sampling_period_ns > max_delay it will be truncated to
692 * max_delay and if sampling_period_ns < min_delay it will be
693 * replaced by min_delay.
694 */
695 int (*setDelay)(struct sensors_poll_device_t *dev,
696 int sensor_handle, int64_t sampling_period_ns);
697
698 /**
699 * Write an array of sensor_event_t to data. The size of the
700 * available buffer is specified by count. Returns number of
701 * valid sensor_event_t.
702 *
703 * This function should block if there is no sensor event
704 * available when being called. Thus, return value should always be
705 * positive.
706 */
707 int (*poll)(struct sensors_poll_device_t *dev,
708 sensors_event_t* data, int count);
709 };
710 };
711
712
713 /*
714 * Sets a sensor’s parameters, including sampling frequency and maximum
715 * report latency. This function can be called while the sensor is
716 * activated, in which case it must not cause any sensor measurements to
717 * be lost: transitioning from one sampling rate to the other cannot cause
718 * lost events, nor can transitioning from a high maximum report latency to
719 * a low maximum report latency.
720 * See the Batching sensor results page for details:
721 * http://source.android.com/devices/sensors/batching.html
722 */
723 int (*batch)(struct sensors_poll_device_1* dev,
724 int sensor_handle, int flags, int64_t sampling_period_ns,
725 int64_t max_report_latency_ns);
726
727 /*
728 * Flush adds a META_DATA_FLUSH_COMPLETE event (sensors_event_meta_data_t)
729 * to the end of the "batch mode" FIFO for the specified sensor and flushes
730 * the FIFO.
731 * If the FIFO is empty or if the sensor doesn't support batching (FIFO size zero),
732 * it should return SUCCESS along with a trivial META_DATA_FLUSH_COMPLETE event added to the
733 * event stream. This applies to all sensors other than one-shot sensors.
734 * If the sensor is a one-shot sensor, flush must return -EINVAL and not generate
735 * any flush complete metadata.
736 * If the sensor is not active at the time flush() is called, flush() should return
737 * -EINVAL.
738 */
739 int (*flush)(struct sensors_poll_device_1* dev, int sensor_handle);
740
741 /*
742 * Inject a single sensor sample to be to this device.
743 * data points to the sensor event to be injected
744 * return 0 on success
745 * -EPERM if operation is not allowed
746 * -EINVAL if sensor event cannot be injected
747 */
748 int (*inject_sensor_data)(struct sensors_poll_device_1 *dev, const sensors_event_t *data);
749
750 /*
751 * Register/unregister direct report channel.
752 *
753 * A HAL declares support for direct report by setting non-NULL values for both
754 * register_direct_channel and config_direct_report.
755 *
756 * This function has two operation modes:
757 *
758 * Register: mem != NULL, register a channel using supplied shared memory information. By the
759 * time this function returns, sensors must finish initializing shared memory content
760 * (format dependent, see SENSOR_DIRECT_FMT_*).
761 * Parameters:
762 * mem points to a valid struct sensors_direct_mem_t.
763 * channel_handle is ignored.
764 * Return value:
765 * A handle of channel (>0, <INT32_MAX) when success, which later can be referred in
766 * unregister or config_direct_report call, or error code (<0) when failed
767 * Unregister: mem == NULL, unregister a previously registered channel.
768 * Parameters:
769 * mem set to NULL
770 * channel_handle contains handle of channel to be unregistered
771 * Return value:
772 * 0, even if the channel_handle is invalid, in which case it will be a no-op.
773 */
774 int (*register_direct_channel)(struct sensors_poll_device_1 *dev,
775 const struct sensors_direct_mem_t* mem, int channel_handle);
776
777 /*
778 * Configure direct sensor event report in direct channel.
779 *
780 * Start, modify rate or stop direct report of a sensor in a certain direct channel. A special
781 * case is setting sensor handle -1 to stop means to stop all active sensor report on the
782 * channel specified.
783 *
784 * A HAL declares support for direct report by setting non-NULL values for both
785 * register_direct_channel and config_direct_report.
786 *
787 * Parameters:
788 * sensor_handle sensor to be configured. The sensor has to support direct report
789 * mode by setting flags of sensor_t. Also, direct report mode is only
790 * defined for continuous reporting mode sensors.
791 * channel_handle channel handle to be configured.
792 * config direct report parameters, see sensor_direct_cfg_t.
793 * Return value:
794 * - when sensor is started or sensor rate level is changed: return positive identifier of
795 * sensor in specified channel if successful, otherwise return negative error code.
796 * - when sensor is stopped: return 0 for success or negative error code for failure.
797 */
798 int (*config_direct_report)(struct sensors_poll_device_1 *dev,
799 int sensor_handle, int channel_handle, const struct sensors_direct_cfg_t *config);
800
801 /*
802 * Reserved for future use, must be zero.
803 */
804 void (*reserved_procs[5])(void);
805
806 } sensors_poll_device_1_t;
807
808
809 /** convenience API for opening and closing a device */
810
sensors_open(const struct hw_module_t * module,struct sensors_poll_device_t ** device)811 static inline int sensors_open(const struct hw_module_t* module,
812 struct sensors_poll_device_t** device) {
813 return module->methods->open(module,
814 SENSORS_HARDWARE_POLL, TO_HW_DEVICE_T_OPEN(device));
815 }
816
sensors_close(struct sensors_poll_device_t * device)817 static inline int sensors_close(struct sensors_poll_device_t* device) {
818 return device->common.close(&device->common);
819 }
820
sensors_open_1(const struct hw_module_t * module,sensors_poll_device_1_t ** device)821 static inline int sensors_open_1(const struct hw_module_t* module,
822 sensors_poll_device_1_t** device) {
823 return module->methods->open(module,
824 SENSORS_HARDWARE_POLL, TO_HW_DEVICE_T_OPEN(device));
825 }
826
sensors_close_1(sensors_poll_device_1_t * device)827 static inline int sensors_close_1(sensors_poll_device_1_t* device) {
828 return device->common.close(&device->common);
829 }
830
831 __END_DECLS
832
833 #endif // ANDROID_SENSORS_INTERFACE_H
834