Merge "Activity Recognition HAL."

1 files changed, 186 insertions, 0 deletions

diff --git a/include/hardware/activity_recognition.h b/include/hardware/activity_recognition.h
new file mode 100644
index 0000000..3d3c1bd
--- /dev/null
+++ b/include/hardware/activity_recognition.h
@@ -0,0 +1,186 @@
+/*
+ * Copyright (C) 2014 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.
+ */
+
+/*
+ * Activity Recognition HAL. The goal is to provide low power, low latency, always-on activity
+ * recognition implemented in hardware (i.e. these activity recognition algorithms/classifers
+ * should NOT be run on the AP). By low power we mean that this may be activated 24/7 without
+ * impacting the battery drain speed (goal in order of 1mW including the power for sensors).
+ * This HAL does not specify the input sources that are used towards detecting these activities.
+ * It has one monitor interface which can be used to batch activities for always-on
+ * activity_recognition and if the latency is zero, the same interface can be used for low latency
+ * detection.
+ */
+
+#ifndef ANDROID_ACTIVITY_RECOGNITION_INTERFACE_H
+#define ANDROID_ACTIVITY_RECOGNITION_INTERFACE_H
+
+#include <hardware/hardware.h>
+
+__BEGIN_DECLS
+
+#define ACTIVITY_RECOGNITION_HEADER_VERSION   1
+#define ACTIVITY_RECOGNITION_API_VERSION_0_1  HARDWARE_DEVICE_API_VERSION_2(0, 1, ACTIVITY_RECOGNITION_HEADER_VERSION)
+
+#define ACTIVITY_RECOGNITION_HARDWARE_MODULE_ID "activity_recognition"
+#define ACTIVITY_RECOGNITION_HARDWARE_INTERFACE "activity_recognition_hw_if"
+
+/*
+ * Define constants for various activity types. Multiple activities may be active at the same time
+ * and sometimes none of these activities may be active.
+ */
+
+/* Reserved. get_supported_activities_list() should not return this activity. */
+#define DETECTED_ACTIVITY_RESERVED          (0)
+
+#define DETECTED_ACTIVITY_IN_VEHICLE        (1)
+
+#define DETECTED_ACTIVITY_ON_BICYCLE        (2)
+
+#define DETECTED_ACTIVITY_WALKING           (3)
+
+#define DETECTED_ACTIVITY_RUNNING           (4)
+
+#define DETECTED_ACTIVITY_STILL             (5)
+
+#define DETECTED_ACTIVITY_TILTING           (6)
+
+/* Values for activity_event.event_types. */
+enum {
+    /*
+     * A flush_complete event which indicates that a flush() has been successfully completed. This
+     * does not correspond to any activity/event. An event of this type should be added to the end
+     * of a batch FIFO and it indicates that all the events in the batch FIFO have been successfully
+     * reported to the framework. An event of this type should be generated only if flush() has been
+     * explicitly called and if the FIFO is empty at the time flush() is called it should trivially
+     * return a flush_complete_event to indicate that the FIFO is empty.
+     *
+     * A flush complete event should have the following parameters set.
+     * activity_event_t.event_type = ACTIVITY_EVENT_TYPE_FLUSH_COMPLETE
+     * activity_event_t.detected_activity = DETECTED_ACTIVITY_RESERVED
+     * activity_event_t.timestamp = 0
+     * activity_event_t.reserved = 0
+     * See (*flush)() for more details.
+     */
+    ACTIVITY_EVENT_TYPE_FLUSH_COMPLETE = 0,
+
+    /* Signifies entering an activity. */
+    ACTIVITY_EVENT_TYPE_ENTER = 1,
+
+    /* Signifies exiting an activity. */
+    ACTIVITY_EVENT_TYPE_EXIT  = 2
+};
+
+/*
+ * Each event is a separate activity with event_type indicating whether this activity has started
+ * or ended. Eg event: (event_type="enter", detected_activity="ON_FOOT", timestamp)
+ */
+typedef struct activity_event {
+    /* One of the ACTIVITY_EVENT_TYPE_* constants defined above. */
+    uint32_t event_type;
+
+    /* Detected Activity. One of DETECTED_ACTIVITY_TYPE_* constants defined above. */
+    int32_t detected_activity;
+
+    /* Time at which the transition/event has occurred in nanoseconds using elapsedRealTimeNano. */
+    int64_t timestamp;
+
+    /* Set to zero. */
+    int32_t reserved[4];
+} activity_event_t;
+
+typedef struct activity_recognition_module {
+    hw_module_t common;
+
+    /*
+     * List of all activities supported by this module. Each activity is represented as an integer.
+     * Each value in the list is one of the DETECTED_ACTIVITY_* constants defined above. Return
+     * value is the size of this list.
+     */
+    int (*get_supported_activities_list)(struct activity_recognition_module* module,
+            int** activity_list);
+} activity_recognition_module_t;
+
+struct activity_recognition_device;
+
+typedef struct activity_recognition_callback_procs {
+    // Callback for activity_data. This is guaranteed to not invoke any HAL methods.
+    // Memory allocated for the events can be reused after this method returns.
+    //    events - Array of activity_event_t s that are reported.
+    //    count  - size of the array.
+    void (*activity_callback)(const struct activity_recognition_device* dev,
+            const activity_event_t* events, int count);
+} activity_recognition_callback_procs_t;
+
+typedef struct activity_recognition_device {
+    hw_device_t common;
+
+    /*
+     * Sets the callback to invoke when there are events to report. This call overwrites the
+     * previously registered callback (if any).
+     */
+    void (*register_activity_callback)(const struct activity_recognition_device* dev,
+            const activity_recognition_callback_procs_t* callback);
+
+    /*
+     * Activates and deactivates monitoring of activity transitions. Activities need not be reported
+     * as soon as they are detected. The detected activities are stored in a FIFO and reported in
+     * batches when the "max_batch_report_latency" expires or when the batch FIFO is full. The
+     * implementation should allow the AP to go into suspend mode while the activities are detected
+     * and stored in the batch FIFO. Whenever events need to be reported (like when the FIFO is full
+     * or when the max_batch_report_latency has expired for an activity, event pair), it should
+     * wake_up the AP so that no events are lost. Activities are stored as transitions and they are
+     * allowed to overlap with each other.
+     * detected_activity - The specific activity that needs to be monitored.
+     * event_type    - Specific transition of the activity that needs to be monitored.
+     * enabled       - Enable/Disable detection of an (detected_activity, event_type) pair. Each
+     *                 pair can be activated or deactivated independently of the other. The HAL
+     *                 implementation needs to keep track of which pairs are currently active
+     *                 and needs to detect only those activities.
+     * max_batch_report_latency - a transition can be delayed by at most
+     *                            “max_batch_report_latency” nanoseconds.
+     * Return 0 on success, negative errno code otherwise.
+     */
+    int (*monitor_activity_event)(const struct activity_recognition_device* dev,
+            int32_t detected_activity, int32_t event_type, int64_t max_batch_report_latency_ns,
+            int32_t enabled);
+
+    /*
+     * Flush all the batch FIFOs. Report all the activities that were stored in the FIFO so far as
+     * if max_batch_report_latency had expired. This shouldn't change the latency in any way. Add
+     * a flush_complete_event to indicate the end of the FIFO after all events are delivered.
+     * See ACTIVITY_EVENT_TYPE_FLUSH_COMPLETE for more details.
+     * Return 0 on success, negative errno code otherwise.
+     */
+    int (*flush)(const struct activity_recognition_device* dev);
+
+    // Must be set to NULL.
+    void (*reserved_procs[4])(void);
+} activity_recognition_device_t;
+
+static inline int activity_recognition_open(const hw_module_t* module,
+        activity_recognition_device_t** device) {
+    return module->methods->open(module,
+            ACTIVITY_RECOGNITION_HARDWARE_INTERFACE, (hw_device_t**)device);
+}
+
+static inline int activity_recognition_close(activity_recognition_device_t* device) {
+    return device->common.close(&device->common);
+}
+
+__END_DECLS
+
+#endif // ANDROID_ACTIVITY_RECOGNITION_INTERFACE_H