/* * Copyright (C) 2012 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ #ifndef ANDROID_SENSORS_INTERFACE_H #define ANDROID_SENSORS_INTERFACE_H #include #include #include #include #include #include "sensors-base.h" __BEGIN_DECLS /*****************************************************************************/ #define SENSORS_HEADER_VERSION 1 #define SENSORS_MODULE_API_VERSION_0_1 HARDWARE_MODULE_API_VERSION(0, 1) #define SENSORS_DEVICE_API_VERSION_0_1 HARDWARE_DEVICE_API_VERSION_2(0, 1, SENSORS_HEADER_VERSION) #define SENSORS_DEVICE_API_VERSION_1_0 HARDWARE_DEVICE_API_VERSION_2(1, 0, SENSORS_HEADER_VERSION) #define SENSORS_DEVICE_API_VERSION_1_1 HARDWARE_DEVICE_API_VERSION_2(1, 1, SENSORS_HEADER_VERSION) #define SENSORS_DEVICE_API_VERSION_1_2 HARDWARE_DEVICE_API_VERSION_2(1, 2, SENSORS_HEADER_VERSION) #define SENSORS_DEVICE_API_VERSION_1_3 HARDWARE_DEVICE_API_VERSION_2(1, 3, SENSORS_HEADER_VERSION) #define SENSORS_DEVICE_API_VERSION_1_4 HARDWARE_DEVICE_API_VERSION_2(1, 4, SENSORS_HEADER_VERSION) /** * Please see the Sensors section of source.android.com for an * introduction to and detailed descriptions of Android sensor types: * http://source.android.com/devices/sensors/index.html */ /** * The id of this module */ #define SENSORS_HARDWARE_MODULE_ID "sensors" /** * Name of the sensors device to open */ #define SENSORS_HARDWARE_POLL "poll" /** * Sensor handle is greater than 0 and less than INT32_MAX. * * **** Deprecated **** * Defined values below are kept for code compatibility. Note sensor handle can be as large as * INT32_MAX. */ #define SENSORS_HANDLE_BASE 0 #define SENSORS_HANDLE_BITS 31 #define SENSORS_HANDLE_COUNT (1ull<=SENSOR_TYPE_DEVICE_PRIVATE_BASE), this string must be defined with reserved domain of * vendor/OEM as a prefix, e.g. com.google.glass.onheaddetector * * For sensors of Android defined types, Android framework will override this value. It is ok to * leave it pointing to an empty string. */ const char* stringType; /* permission required to see this sensor, register to it and receive data. * Set to "" if no permission is required. Some sensor types like the * heart rate monitor have a mandatory require_permission. * For sensors that always require a specific permission, like the heart * rate monitor, the android framework might overwrite this string * automatically. */ const char* requiredPermission; /* This value is defined only for continuous mode and on-change sensors. It is the delay between * two sensor events corresponding to the lowest frequency that this sensor supports. When lower * frequencies are requested through batch()/setDelay() the events will be generated at this * frequency instead. It can be used by the framework or applications to estimate when the batch * FIFO may be full. * * NOTE: 1) period_ns is in nanoseconds where as maxDelay/minDelay are in microseconds. * continuous, on-change: maximum sampling period allowed in microseconds. * one-shot, special : 0 * 2) maxDelay should always fit within a 32 bit signed integer. It is declared as 64 bit * on 64 bit architectures only for binary compatibility reasons. * Availability: SENSORS_DEVICE_API_VERSION_1_3 */ #ifdef __LP64__ int64_t maxDelay; #else int32_t maxDelay; #endif /* Flags for sensor. See SENSOR_FLAG_* above. Only the least significant 32 bits are used here. * It is declared as 64 bit on 64 bit architectures only for binary compatibility reasons. * Availability: SENSORS_DEVICE_API_VERSION_1_3 */ #ifdef __LP64__ uint64_t flags; #else uint32_t flags; #endif /* reserved fields, must be zero */ void* reserved[2]; }; /** * Shared memory information for a direct channel */ struct sensors_direct_mem_t { int type; // enum SENSOR_DIRECT_MEM_... int format; // enum SENSOR_DIRECT_FMT_... size_t size; // size of the memory region, in bytes const struct native_handle *handle; // shared memory handle, which is interpreted differently // depending on type }; /** * Direct channel report configuration */ struct sensors_direct_cfg_t { int rate_level; // enum SENSOR_DIRECT_RATE_... }; /* * sensors_poll_device_t is used with SENSORS_DEVICE_API_VERSION_0_1 * and is present for backward binary and source compatibility. * See the Sensors HAL interface section for complete descriptions of the * following functions: * http://source.android.com/devices/sensors/index.html#hal */ struct sensors_poll_device_t { struct hw_device_t common; int (*activate)(struct sensors_poll_device_t *dev, int sensor_handle, int enabled); int (*setDelay)(struct sensors_poll_device_t *dev, int sensor_handle, int64_t sampling_period_ns); int (*poll)(struct sensors_poll_device_t *dev, sensors_event_t* data, int count); }; /* * struct sensors_poll_device_1 is used in HAL versions >= SENSORS_DEVICE_API_VERSION_1_0 */ typedef struct sensors_poll_device_1 { union { /* sensors_poll_device_1 is compatible with sensors_poll_device_t, * and can be down-cast to it */ struct sensors_poll_device_t v0; struct { struct hw_device_t common; /* Activate/de-activate one sensor. * * sensor_handle is the handle of the sensor to change. * enabled set to 1 to enable, or 0 to disable the sensor. * * Before sensor activation, existing sensor events that have not * been picked up by poll() should be abandoned so that application * upon new activation request will not get stale events. * (events that are generated during latter activation or during * data injection mode after sensor deactivation) * * Return 0 on success, negative errno code otherwise. */ int (*activate)(struct sensors_poll_device_t *dev, int sensor_handle, int enabled); /** * Set the events's period in nanoseconds for a given sensor. * If sampling_period_ns > max_delay it will be truncated to * max_delay and if sampling_period_ns < min_delay it will be * replaced by min_delay. */ int (*setDelay)(struct sensors_poll_device_t *dev, int sensor_handle, int64_t sampling_period_ns); /** * Write an array of sensor_event_t to data. The size of the * available buffer is specified by count. Returns number of * valid sensor_event_t. * * This function should block if there is no sensor event * available when being called. Thus, return value should always be * positive. */ int (*poll)(struct sensors_poll_device_t *dev, sensors_event_t* data, int count); }; }; /* * Sets a sensor’s parameters, including sampling frequency and maximum * report latency. This function can be called while the sensor is * activated, in which case it must not cause any sensor measurements to * be lost: transitioning from one sampling rate to the other cannot cause * lost events, nor can transitioning from a high maximum report latency to * a low maximum report latency. * See the Batching sensor results page for details: * http://source.android.com/devices/sensors/batching.html */ int (*batch)(struct sensors_poll_device_1* dev, int sensor_handle, int flags, int64_t sampling_period_ns, int64_t max_report_latency_ns); /* * Flush adds a META_DATA_FLUSH_COMPLETE event (sensors_event_meta_data_t) * to the end of the "batch mode" FIFO for the specified sensor and flushes * the FIFO. * If the FIFO is empty or if the sensor doesn't support batching (FIFO size zero), * it should return SUCCESS along with a trivial META_DATA_FLUSH_COMPLETE event added to the * event stream. This applies to all sensors other than one-shot sensors. * If the sensor is a one-shot sensor, flush must return -EINVAL and not generate * any flush complete metadata. * If the sensor is not active at the time flush() is called, flush() should return * -EINVAL. */ int (*flush)(struct sensors_poll_device_1* dev, int sensor_handle); /* * Inject a single sensor sample to be to this device. * data points to the sensor event to be injected * return 0 on success * -EPERM if operation is not allowed * -EINVAL if sensor event cannot be injected */ int (*inject_sensor_data)(struct sensors_poll_device_1 *dev, const sensors_event_t *data); /* * Register/unregister direct report channel. * * A HAL declares support for direct report by setting non-NULL values for both * register_direct_channel and config_direct_report. * * This function has two operation modes: * * Register: mem != NULL, register a channel using supplied shared memory information. By the * time this function returns, sensors must finish initializing shared memory content * (format dependent, see SENSOR_DIRECT_FMT_*). * Parameters: * mem points to a valid struct sensors_direct_mem_t. * channel_handle is ignored. * Return value: * A handle of channel (>0, methods->open(module, SENSORS_HARDWARE_POLL, TO_HW_DEVICE_T_OPEN(device)); } static inline int sensors_close(struct sensors_poll_device_t* device) { return device->common.close(&device->common); } static inline int sensors_open_1(const struct hw_module_t* module, sensors_poll_device_1_t** device) { return module->methods->open(module, SENSORS_HARDWARE_POLL, TO_HW_DEVICE_T_OPEN(device)); } static inline int sensors_close_1(sensors_poll_device_1_t* device) { return device->common.close(&device->common); } __END_DECLS #endif // ANDROID_SENSORS_INTERFACE_H