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 // LINT.IfChange
371 /**
372 * Union of the various types of sensor data
373 * that can be returned.
374 * This type needs to remain identical to ASensorEvent.
375 */
376 typedef struct sensors_event_t {
377 /* must be sizeof(struct sensors_event_t) */
378 int32_t version;
379
380 /* sensor identifier */
381 int32_t sensor;
382
383 /* sensor type */
384 int32_t type;
385
386 /* reserved */
387 int32_t reserved0;
388
389 /* time is in nanosecond */
390 int64_t timestamp;
391
392 union {
393 union {
394 float data[16];
395
396 /* acceleration values are in meter per second per second (m/s^2) */
397 sensors_vec_t acceleration;
398
399 /* magnetic vector values are in micro-Tesla (uT) */
400 sensors_vec_t magnetic;
401
402 /* orientation values are in degrees */
403 sensors_vec_t orientation;
404
405 /* gyroscope values are in rad/s */
406 sensors_vec_t gyro;
407
408 /* temperature is in degrees centigrade (Celsius) */
409 float temperature;
410
411 /* distance in centimeters */
412 float distance;
413
414 /* light in SI lux units */
415 float light;
416
417 /* pressure in hectopascal (hPa) */
418 float pressure;
419
420 /* relative humidity in percent */
421 float relative_humidity;
422
423 /* uncalibrated gyroscope values are in rad/s */
424 uncalibrated_event_t uncalibrated_gyro;
425
426 /* uncalibrated magnetometer values are in micro-Teslas */
427 uncalibrated_event_t uncalibrated_magnetic;
428
429 /* uncalibrated accelerometer values are in meter per second per second (m/s^2) */
430 uncalibrated_event_t uncalibrated_accelerometer;
431
432 /* heart rate data containing value in bpm and status */
433 heart_rate_event_t heart_rate;
434
435 /* this is a special event. see SENSOR_TYPE_META_DATA above.
436 * sensors_meta_data_event_t events are all reported with a type of
437 * SENSOR_TYPE_META_DATA. The handle is ignored and must be zero.
438 */
439 meta_data_event_t meta_data;
440
441 /* dynamic sensor meta event. See SENSOR_TYPE_DYNAMIC_SENSOR_META type for details */
442 dynamic_sensor_meta_event_t dynamic_sensor_meta;
443
444 /*
445 * special additional sensor information frame, see
446 * SENSOR_TYPE_ADDITIONAL_INFO for details.
447 */
448 additional_info_event_t additional_info;
449
450 /* vector describing head orientation (added for legacy code support only) */
451 head_tracker_event_t head_tracker;
452
453 /*
454 * limited axes imu event, See
455 * SENSOR_TYPE_GYROSCOPE_LIMITED_AXES and
456 * SENSOR_TYPE_ACCELEROMETER_LIMITED_AXES for details.
457 */
458 limited_axes_imu_event_t limited_axes_imu;
459
460 /*
461 * limited axes imu uncalibrated event, See
462 * SENSOR_TYPE_GYROSCOPE_LIMITED_AXES_UNCALIBRATED and
463 * SENSOR_TYPE_ACCELEROMETER_LIMITED_AXES_UNCALIBRATED for details.
464 */
465 limited_axes_imu_uncalibrated_event_t limited_axes_imu_uncalibrated;
466
467 /* heading data containing value in degrees and its accuracy */
468 heading_event_t heading;
469 };
470
471 union {
472 uint64_t data[8];
473
474 /* step-counter */
475 uint64_t step_counter;
476 } u64;
477 };
478
479 /* Reserved flags for internal use. Set to zero. */
480 uint32_t flags;
481
482 uint32_t reserved1[3];
483 } sensors_event_t;
484 // LINT.ThenChange(frameworks/native/include/android/sensor.h)
485
486
487 /* see SENSOR_TYPE_META_DATA */
488 typedef sensors_event_t sensors_meta_data_event_t;
489
490
491 /**
492 * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM
493 * and the fields of this data structure must begin with hw_module_t
494 * followed by module specific information.
495 */
496 struct sensors_module_t {
497 struct hw_module_t common;
498
499 /**
500 * Enumerate all available sensors. The list is returned in "list".
501 * return number of sensors in the list
502 */
503 int (*get_sensors_list)(struct sensors_module_t* module,
504 struct sensor_t const** list);
505
506 /**
507 * Place the module in a specific mode. The following modes are defined
508 *
509 * 0 - Normal operation. Default state of the module.
510 * 1 - Loopback mode. Data is injected for the supported
511 * sensors by the sensor service in this mode.
512 * return 0 on success
513 * -EINVAL if requested mode is not supported
514 * -EPERM if operation is not allowed
515 */
516 int (*set_operation_mode)(unsigned int mode);
517 };
518
519 struct sensor_t {
520
521 /* Name of this sensor.
522 * All sensors of the same "type" must have a different "name".
523 */
524 const char* name;
525
526 /* vendor of the hardware part */
527 const char* vendor;
528
529 /* version of the hardware part + driver. The value of this field
530 * must increase when the driver is updated in a way that changes the
531 * output of this sensor. This is important for fused sensors when the
532 * fusion algorithm is updated.
533 */
534 int version;
535
536 /* handle that identifies this sensors. This handle is used to reference
537 * this sensor throughout the HAL API.
538 */
539 int handle;
540
541 /* this sensor's type. */
542 int type;
543
544 /* maximum range of this sensor's value in SI units */
545 float maxRange;
546
547 /* smallest difference between two values reported by this sensor */
548 float resolution;
549
550 /* rough estimate of this sensor's power consumption in mA */
551 float power;
552
553 /* this value depends on the reporting mode:
554 *
555 * continuous: minimum sample period allowed in microseconds
556 * on-change : 0
557 * one-shot :-1
558 * special : 0, unless otherwise noted
559 */
560 int32_t minDelay;
561
562 /* number of events reserved for this sensor in the batch mode FIFO.
563 * If there is a dedicated FIFO for this sensor, then this is the
564 * size of this FIFO. If the FIFO is shared with other sensors,
565 * this is the size reserved for that sensor and it can be zero.
566 */
567 uint32_t fifoReservedEventCount;
568
569 /* maximum number of events of this sensor that could be batched.
570 * This is especially relevant when the FIFO is shared between
571 * several sensors; this value is then set to the size of that FIFO.
572 */
573 uint32_t fifoMaxEventCount;
574
575 /* type of this sensor as a string.
576 *
577 * If type is OEM specific or sensor manufacturer specific type
578 * (>=SENSOR_TYPE_DEVICE_PRIVATE_BASE), this string must be defined with reserved domain of
579 * vendor/OEM as a prefix, e.g. com.google.glass.onheaddetector
580 *
581 * For sensors of Android defined types, Android framework will override this value. It is ok to
582 * leave it pointing to an empty string.
583 */
584 const char* stringType;
585
586 /* permission required to see this sensor, register to it and receive data.
587 * Set to "" if no permission is required. Some sensor types like the
588 * heart rate monitor have a mandatory require_permission.
589 * For sensors that always require a specific permission, like the heart
590 * rate monitor, the android framework might overwrite this string
591 * automatically.
592 */
593 const char* requiredPermission;
594
595 /* This value is defined only for continuous mode and on-change sensors. It is the delay between
596 * two sensor events corresponding to the lowest frequency that this sensor supports. When lower
597 * frequencies are requested through batch()/setDelay() the events will be generated at this
598 * frequency instead. It can be used by the framework or applications to estimate when the batch
599 * FIFO may be full.
600 *
601 * NOTE: 1) period_ns is in nanoseconds where as maxDelay/minDelay are in microseconds.
602 * continuous, on-change: maximum sampling period allowed in microseconds.
603 * one-shot, special : 0
604 * 2) maxDelay should always fit within a 32 bit signed integer. It is declared as 64 bit
605 * on 64 bit architectures only for binary compatibility reasons.
606 * Availability: SENSORS_DEVICE_API_VERSION_1_3
607 */
608 #ifdef __LP64__
609 int64_t maxDelay;
610 #else
611 int32_t maxDelay;
612 #endif
613
614 /* Flags for sensor. See SENSOR_FLAG_* above. Only the least significant 32 bits are used here.
615 * It is declared as 64 bit on 64 bit architectures only for binary compatibility reasons.
616 * Availability: SENSORS_DEVICE_API_VERSION_1_3
617 */
618 #ifdef __LP64__
619 uint64_t flags;
620 #else
621 uint32_t flags;
622 #endif
623
624 /* reserved fields, must be zero */
625 void* reserved[2];
626 };
627
628 /**
629 * Shared memory information for a direct channel
630 */
631 struct sensors_direct_mem_t {
632 int type; // enum SENSOR_DIRECT_MEM_...
633 int format; // enum SENSOR_DIRECT_FMT_...
634 size_t size; // size of the memory region, in bytes
635 const struct native_handle *handle; // shared memory handle, which is interpreted differently
636 // depending on type
637 };
638
639 /**
640 * Direct channel report configuration
641 */
642 struct sensors_direct_cfg_t {
643 int rate_level; // enum SENSOR_DIRECT_RATE_...
644 };
645
646 /*
647 * sensors_poll_device_t is used with SENSORS_DEVICE_API_VERSION_0_1
648 * and is present for backward binary and source compatibility.
649 * See the Sensors HAL interface section for complete descriptions of the
650 * following functions:
651 * http://source.android.com/devices/sensors/index.html#hal
652 */
653 struct sensors_poll_device_t {
654 struct hw_device_t common;
655 int (*activate)(struct sensors_poll_device_t *dev,
656 int sensor_handle, int enabled);
657 int (*setDelay)(struct sensors_poll_device_t *dev,
658 int sensor_handle, int64_t sampling_period_ns);
659 int (*poll)(struct sensors_poll_device_t *dev,
660 sensors_event_t* data, int count);
661 };
662
663 /*
664 * struct sensors_poll_device_1 is used in HAL versions >= SENSORS_DEVICE_API_VERSION_1_0
665 */
666 typedef struct sensors_poll_device_1 {
667 union {
668 /* sensors_poll_device_1 is compatible with sensors_poll_device_t,
669 * and can be down-cast to it
670 */
671 struct sensors_poll_device_t v0;
672
673 struct {
674 struct hw_device_t common;
675
676 /* Activate/de-activate one sensor.
677 *
678 * sensor_handle is the handle of the sensor to change.
679 * enabled set to 1 to enable, or 0 to disable the sensor.
680 *
681 * Before sensor activation, existing sensor events that have not
682 * been picked up by poll() should be abandoned so that application
683 * upon new activation request will not get stale events.
684 * (events that are generated during latter activation or during
685 * data injection mode after sensor deactivation)
686 *
687 * Return 0 on success, negative errno code otherwise.
688 */
689 int (*activate)(struct sensors_poll_device_t *dev,
690 int sensor_handle, int enabled);
691
692 /**
693 * Set the events's period in nanoseconds for a given sensor.
694 * If sampling_period_ns > max_delay it will be truncated to
695 * max_delay and if sampling_period_ns < min_delay it will be
696 * replaced by min_delay.
697 */
698 int (*setDelay)(struct sensors_poll_device_t *dev,
699 int sensor_handle, int64_t sampling_period_ns);
700
701 /**
702 * Write an array of sensor_event_t to data. The size of the
703 * available buffer is specified by count. Returns number of
704 * valid sensor_event_t.
705 *
706 * This function should block if there is no sensor event
707 * available when being called. Thus, return value should always be
708 * positive.
709 */
710 int (*poll)(struct sensors_poll_device_t *dev,
711 sensors_event_t* data, int count);
712 };
713 };
714
715
716 /*
717 * Sets a sensor’s parameters, including sampling frequency and maximum
718 * report latency. This function can be called while the sensor is
719 * activated, in which case it must not cause any sensor measurements to
720 * be lost: transitioning from one sampling rate to the other cannot cause
721 * lost events, nor can transitioning from a high maximum report latency to
722 * a low maximum report latency.
723 * See the Batching sensor results page for details:
724 * http://source.android.com/devices/sensors/batching.html
725 */
726 int (*batch)(struct sensors_poll_device_1* dev,
727 int sensor_handle, int flags, int64_t sampling_period_ns,
728 int64_t max_report_latency_ns);
729
730 /*
731 * Flush adds a META_DATA_FLUSH_COMPLETE event (sensors_event_meta_data_t)
732 * to the end of the "batch mode" FIFO for the specified sensor and flushes
733 * the FIFO.
734 * If the FIFO is empty or if the sensor doesn't support batching (FIFO size zero),
735 * it should return SUCCESS along with a trivial META_DATA_FLUSH_COMPLETE event added to the
736 * event stream. This applies to all sensors other than one-shot sensors.
737 * If the sensor is a one-shot sensor, flush must return -EINVAL and not generate
738 * any flush complete metadata.
739 * If the sensor is not active at the time flush() is called, flush() should return
740 * -EINVAL.
741 */
742 int (*flush)(struct sensors_poll_device_1* dev, int sensor_handle);
743
744 /*
745 * Inject a single sensor sample to be to this device.
746 * data points to the sensor event to be injected
747 * return 0 on success
748 * -EPERM if operation is not allowed
749 * -EINVAL if sensor event cannot be injected
750 */
751 int (*inject_sensor_data)(struct sensors_poll_device_1 *dev, const sensors_event_t *data);
752
753 /*
754 * Register/unregister direct report channel.
755 *
756 * A HAL declares support for direct report by setting non-NULL values for both
757 * register_direct_channel and config_direct_report.
758 *
759 * This function has two operation modes:
760 *
761 * Register: mem != NULL, register a channel using supplied shared memory information. By the
762 * time this function returns, sensors must finish initializing shared memory content
763 * (format dependent, see SENSOR_DIRECT_FMT_*).
764 * Parameters:
765 * mem points to a valid struct sensors_direct_mem_t.
766 * channel_handle is ignored.
767 * Return value:
768 * A handle of channel (>0, <INT32_MAX) when success, which later can be referred in
769 * unregister or config_direct_report call, or error code (<0) when failed
770 * Unregister: mem == NULL, unregister a previously registered channel.
771 * Parameters:
772 * mem set to NULL
773 * channel_handle contains handle of channel to be unregistered
774 * Return value:
775 * 0, even if the channel_handle is invalid, in which case it will be a no-op.
776 */
777 int (*register_direct_channel)(struct sensors_poll_device_1 *dev,
778 const struct sensors_direct_mem_t* mem, int channel_handle);
779
780 /*
781 * Configure direct sensor event report in direct channel.
782 *
783 * Start, modify rate or stop direct report of a sensor in a certain direct channel. A special
784 * case is setting sensor handle -1 to stop means to stop all active sensor report on the
785 * channel specified.
786 *
787 * A HAL declares support for direct report by setting non-NULL values for both
788 * register_direct_channel and config_direct_report.
789 *
790 * Parameters:
791 * sensor_handle sensor to be configured. The sensor has to support direct report
792 * mode by setting flags of sensor_t. Also, direct report mode is only
793 * defined for continuous reporting mode sensors.
794 * channel_handle channel handle to be configured.
795 * config direct report parameters, see sensor_direct_cfg_t.
796 * Return value:
797 * - when sensor is started or sensor rate level is changed: return positive identifier of
798 * sensor in specified channel if successful, otherwise return negative error code.
799 * - when sensor is stopped: return 0 for success or negative error code for failure.
800 */
801 int (*config_direct_report)(struct sensors_poll_device_1 *dev,
802 int sensor_handle, int channel_handle, const struct sensors_direct_cfg_t *config);
803
804 /*
805 * Reserved for future use, must be zero.
806 */
807 void (*reserved_procs[5])(void);
808
809 } sensors_poll_device_1_t;
810
811
812 /** convenience API for opening and closing a device */
813
sensors_open(const struct hw_module_t * module,struct sensors_poll_device_t ** device)814 static inline int sensors_open(const struct hw_module_t* module,
815 struct sensors_poll_device_t** device) {
816 return module->methods->open(module,
817 SENSORS_HARDWARE_POLL, TO_HW_DEVICE_T_OPEN(device));
818 }
819
sensors_close(struct sensors_poll_device_t * device)820 static inline int sensors_close(struct sensors_poll_device_t* device) {
821 return device->common.close(&device->common);
822 }
823
sensors_open_1(const struct hw_module_t * module,sensors_poll_device_1_t ** device)824 static inline int sensors_open_1(const struct hw_module_t* module,
825 sensors_poll_device_1_t** device) {
826 return module->methods->open(module,
827 SENSORS_HARDWARE_POLL, TO_HW_DEVICE_T_OPEN(device));
828 }
829
sensors_close_1(sensors_poll_device_1_t * device)830 static inline int sensors_close_1(sensors_poll_device_1_t* device) {
831 return device->common.close(&device->common);
832 }
833
834 __END_DECLS
835
836 #endif // ANDROID_SENSORS_INTERFACE_H
837