Aravind Akella | 462eae3 | 2014-03-14 19:00:45 -0700 | [diff] [blame] | 1 | /* |
| 2 | * Copyright (C) 2014 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 | /* |
| 18 | * Activity Recognition HAL. The goal is to provide low power, low latency, always-on activity |
| 19 | * recognition implemented in hardware (i.e. these activity recognition algorithms/classifers |
| 20 | * should NOT be run on the AP). By low power we mean that this may be activated 24/7 without |
| 21 | * impacting the battery drain speed (goal in order of 1mW including the power for sensors). |
| 22 | * This HAL does not specify the input sources that are used towards detecting these activities. |
| 23 | * It has one monitor interface which can be used to batch activities for always-on |
| 24 | * activity_recognition and if the latency is zero, the same interface can be used for low latency |
| 25 | * detection. |
| 26 | */ |
| 27 | |
| 28 | #ifndef ANDROID_ACTIVITY_RECOGNITION_INTERFACE_H |
| 29 | #define ANDROID_ACTIVITY_RECOGNITION_INTERFACE_H |
| 30 | |
| 31 | #include <hardware/hardware.h> |
| 32 | |
| 33 | __BEGIN_DECLS |
| 34 | |
| 35 | #define ACTIVITY_RECOGNITION_HEADER_VERSION 1 |
| 36 | #define ACTIVITY_RECOGNITION_API_VERSION_0_1 HARDWARE_DEVICE_API_VERSION_2(0, 1, ACTIVITY_RECOGNITION_HEADER_VERSION) |
| 37 | |
| 38 | #define ACTIVITY_RECOGNITION_HARDWARE_MODULE_ID "activity_recognition" |
| 39 | #define ACTIVITY_RECOGNITION_HARDWARE_INTERFACE "activity_recognition_hw_if" |
| 40 | |
| 41 | /* |
Aravind Akella | 871b748 | 2014-05-27 17:19:52 -0700 | [diff] [blame] | 42 | * Define types for various activities. Multiple activities may be active at the same time and |
| 43 | * sometimes none of these activities may be active. |
| 44 | * |
| 45 | * Each activity has a corresponding type. Only activities that are defined here should use |
| 46 | * android.activity_recognition.* prefix. OEM defined activities should not use this prefix. |
| 47 | * Activity type of OEM-defined activities should start with the reverse domain name of the entity |
| 48 | * defining the activity. |
| 49 | * |
| 50 | * When android introduces a new activity type that can potentially replace an OEM-defined activity |
| 51 | * type, the OEM must use the official activity type on versions of the HAL that support this new |
| 52 | * official activity type. |
| 53 | * |
| 54 | * Example (made up): Suppose Google's Glass team wants to detect nodding activity. |
| 55 | * - Such an activity is not officially supported in android L |
| 56 | * - Glass devices launching on L can implement a custom activity with |
| 57 | * type = "com.google.glass.nodding" |
| 58 | * - In M android release, if android decides to define ACITIVITY_TYPE_NODDING, those types |
| 59 | * should replace the Glass-team-specific types in all future launches. |
| 60 | * - When launching glass on the M release, Google should now use the official activity type |
| 61 | * - This way, other applications can use this activity. |
Aravind Akella | 462eae3 | 2014-03-14 19:00:45 -0700 | [diff] [blame] | 62 | */ |
| 63 | |
Aravind Akella | 871b748 | 2014-05-27 17:19:52 -0700 | [diff] [blame] | 64 | #define ACTIVITY_TYPE_IN_VEHICLE "android.activity_recognition.in_vehicle" |
Aravind Akella | 462eae3 | 2014-03-14 19:00:45 -0700 | [diff] [blame] | 65 | |
Aravind Akella | 871b748 | 2014-05-27 17:19:52 -0700 | [diff] [blame] | 66 | #define ACTIVITY_TYPE_ON_BICYCLE "android.activity_recognition.on_bicycle" |
Aravind Akella | 462eae3 | 2014-03-14 19:00:45 -0700 | [diff] [blame] | 67 | |
Aravind Akella | 871b748 | 2014-05-27 17:19:52 -0700 | [diff] [blame] | 68 | #define ACTIVITY_TYPE_WALKING "android.activity_recognition.walking" |
Aravind Akella | 462eae3 | 2014-03-14 19:00:45 -0700 | [diff] [blame] | 69 | |
Aravind Akella | 871b748 | 2014-05-27 17:19:52 -0700 | [diff] [blame] | 70 | #define ACTIVITY_TYPE_RUNNING "android.activity_recognition.running" |
Aravind Akella | 462eae3 | 2014-03-14 19:00:45 -0700 | [diff] [blame] | 71 | |
Aravind Akella | 871b748 | 2014-05-27 17:19:52 -0700 | [diff] [blame] | 72 | #define ACTIVITY_TYPE_STILL "android.activity_recognition.still" |
Aravind Akella | 462eae3 | 2014-03-14 19:00:45 -0700 | [diff] [blame] | 73 | |
Aravind Akella | 871b748 | 2014-05-27 17:19:52 -0700 | [diff] [blame] | 74 | #define ACTIVITY_TYPE_TILTING "android.activity_recognition.tilting" |
Aravind Akella | 462eae3 | 2014-03-14 19:00:45 -0700 | [diff] [blame] | 75 | |
| 76 | /* Values for activity_event.event_types. */ |
| 77 | enum { |
| 78 | /* |
| 79 | * A flush_complete event which indicates that a flush() has been successfully completed. This |
| 80 | * does not correspond to any activity/event. An event of this type should be added to the end |
| 81 | * of a batch FIFO and it indicates that all the events in the batch FIFO have been successfully |
| 82 | * reported to the framework. An event of this type should be generated only if flush() has been |
| 83 | * explicitly called and if the FIFO is empty at the time flush() is called it should trivially |
| 84 | * return a flush_complete_event to indicate that the FIFO is empty. |
| 85 | * |
| 86 | * A flush complete event should have the following parameters set. |
Aravind Akella | 871b748 | 2014-05-27 17:19:52 -0700 | [diff] [blame] | 87 | * activity_event_t.event_type = ACTIVITY_EVENT_FLUSH_COMPLETE |
| 88 | * activity_event_t.activity = 0 |
Aravind Akella | 462eae3 | 2014-03-14 19:00:45 -0700 | [diff] [blame] | 89 | * activity_event_t.timestamp = 0 |
| 90 | * activity_event_t.reserved = 0 |
| 91 | * See (*flush)() for more details. |
| 92 | */ |
Aravind Akella | 871b748 | 2014-05-27 17:19:52 -0700 | [diff] [blame] | 93 | ACTIVITY_EVENT_FLUSH_COMPLETE = 0, |
Aravind Akella | 462eae3 | 2014-03-14 19:00:45 -0700 | [diff] [blame] | 94 | |
| 95 | /* Signifies entering an activity. */ |
Aravind Akella | 871b748 | 2014-05-27 17:19:52 -0700 | [diff] [blame] | 96 | ACTIVITY_EVENT_ENTER = 1, |
Aravind Akella | 462eae3 | 2014-03-14 19:00:45 -0700 | [diff] [blame] | 97 | |
| 98 | /* Signifies exiting an activity. */ |
Aravind Akella | 871b748 | 2014-05-27 17:19:52 -0700 | [diff] [blame] | 99 | ACTIVITY_EVENT_EXIT = 2 |
Aravind Akella | 462eae3 | 2014-03-14 19:00:45 -0700 | [diff] [blame] | 100 | }; |
| 101 | |
| 102 | /* |
| 103 | * Each event is a separate activity with event_type indicating whether this activity has started |
Aravind Akella | 153c40c | 2014-05-07 12:01:43 -0700 | [diff] [blame] | 104 | * or ended. Eg event: (event_type="enter", activity="ON_FOOT", timestamp) |
Aravind Akella | 462eae3 | 2014-03-14 19:00:45 -0700 | [diff] [blame] | 105 | */ |
| 106 | typedef struct activity_event { |
Aravind Akella | 871b748 | 2014-05-27 17:19:52 -0700 | [diff] [blame] | 107 | /* One of the ACTIVITY_EVENT_* constants defined above. */ |
Aravind Akella | 462eae3 | 2014-03-14 19:00:45 -0700 | [diff] [blame] | 108 | uint32_t event_type; |
| 109 | |
Aravind Akella | 871b748 | 2014-05-27 17:19:52 -0700 | [diff] [blame] | 110 | /* |
| 111 | * Index of the activity in the list returned by get_supported_activities_list. If this event |
| 112 | * is a flush complete event, this should be set to zero. |
| 113 | */ |
Aravind Akella | 153c40c | 2014-05-07 12:01:43 -0700 | [diff] [blame] | 114 | uint32_t activity; |
Aravind Akella | 462eae3 | 2014-03-14 19:00:45 -0700 | [diff] [blame] | 115 | |
| 116 | /* Time at which the transition/event has occurred in nanoseconds using elapsedRealTimeNano. */ |
| 117 | int64_t timestamp; |
| 118 | |
| 119 | /* Set to zero. */ |
| 120 | int32_t reserved[4]; |
| 121 | } activity_event_t; |
| 122 | |
| 123 | typedef struct activity_recognition_module { |
Stewart Miles | 84d3549 | 2014-05-01 09:03:27 -0700 | [diff] [blame] | 124 | /** |
| 125 | * Common methods of the activity recognition module. This *must* be the first member of |
| 126 | * activity_recognition_module as users of this structure will cast a hw_module_t to |
| 127 | * activity_recognition_module pointer in contexts where it's known the hw_module_t |
| 128 | * references an activity_recognition_module. |
| 129 | */ |
Aravind Akella | 462eae3 | 2014-03-14 19:00:45 -0700 | [diff] [blame] | 130 | hw_module_t common; |
| 131 | |
| 132 | /* |
Aravind Akella | 871b748 | 2014-05-27 17:19:52 -0700 | [diff] [blame] | 133 | * List of all activities supported by this module including OEM defined activities. Each |
| 134 | * activity is represented using a string defined above. Each string should be null terminated. |
| 135 | * The index of the activity in this array is used as a "handle" for enabling/disabling and |
| 136 | * event delivery. |
| 137 | * Return value is the size of this list. |
Aravind Akella | 462eae3 | 2014-03-14 19:00:45 -0700 | [diff] [blame] | 138 | */ |
| 139 | int (*get_supported_activities_list)(struct activity_recognition_module* module, |
Aravind Akella | 871b748 | 2014-05-27 17:19:52 -0700 | [diff] [blame] | 140 | char const* const* *activity_list); |
Aravind Akella | 462eae3 | 2014-03-14 19:00:45 -0700 | [diff] [blame] | 141 | } activity_recognition_module_t; |
| 142 | |
| 143 | struct activity_recognition_device; |
| 144 | |
| 145 | typedef struct activity_recognition_callback_procs { |
| 146 | // Callback for activity_data. This is guaranteed to not invoke any HAL methods. |
| 147 | // Memory allocated for the events can be reused after this method returns. |
| 148 | // events - Array of activity_event_t s that are reported. |
| 149 | // count - size of the array. |
Aravind Akella | 153c40c | 2014-05-07 12:01:43 -0700 | [diff] [blame] | 150 | void (*activity_callback)(const struct activity_recognition_callback_procs* procs, |
Aravind Akella | 462eae3 | 2014-03-14 19:00:45 -0700 | [diff] [blame] | 151 | const activity_event_t* events, int count); |
| 152 | } activity_recognition_callback_procs_t; |
| 153 | |
| 154 | typedef struct activity_recognition_device { |
Stewart Miles | 84d3549 | 2014-05-01 09:03:27 -0700 | [diff] [blame] | 155 | /** |
| 156 | * Common methods of the activity recognition device. This *must* be the first member of |
| 157 | * activity_recognition_device as users of this structure will cast a hw_device_t to |
| 158 | * activity_recognition_device pointer in contexts where it's known the hw_device_t |
| 159 | * references an activity_recognition_device. |
| 160 | */ |
Aravind Akella | 462eae3 | 2014-03-14 19:00:45 -0700 | [diff] [blame] | 161 | hw_device_t common; |
| 162 | |
| 163 | /* |
| 164 | * Sets the callback to invoke when there are events to report. This call overwrites the |
| 165 | * previously registered callback (if any). |
| 166 | */ |
| 167 | void (*register_activity_callback)(const struct activity_recognition_device* dev, |
| 168 | const activity_recognition_callback_procs_t* callback); |
| 169 | |
| 170 | /* |
Aravind Akella | 153c40c | 2014-05-07 12:01:43 -0700 | [diff] [blame] | 171 | * Activates monitoring of activity transitions. Activities need not be reported as soon as they |
| 172 | * are detected. The detected activities are stored in a FIFO and reported in batches when the |
| 173 | * "max_batch_report_latency" expires or when the batch FIFO is full. The implementation should |
| 174 | * allow the AP to go into suspend mode while the activities are detected and stored in the |
| 175 | * batch FIFO. Whenever events need to be reported (like when the FIFO is full or when the |
| 176 | * max_batch_report_latency has expired for an activity, event pair), it should wake_up the AP |
| 177 | * so that no events are lost. Activities are stored as transitions and they are allowed to |
| 178 | * overlap with each other. Each (activity, event_type) pair can be activated or deactivated |
| 179 | * independently of the other. The HAL implementation needs to keep track of which pairs are |
| 180 | * currently active and needs to detect only those pairs. |
| 181 | * |
Chengu Wang | eb1bd05 | 2015-12-02 13:00:41 -0800 | [diff] [blame] | 182 | * At the first detection after this function gets called, the hardware should know whether the |
| 183 | * user is in the activity. |
| 184 | * - If event_type is ACTIVITY_EVENT_ENTER and the user is in the activity, then an |
| 185 | * (ACTIVITY_EVENT_ENTER, activity) event should be added to the FIFO. |
| 186 | * - If event_type is ACTIVITY_EVENT_EXIT and the user is not in the activity, then an |
| 187 | * (ACTIVITY_EVENT_EXIT, activity) event should be added to the FIFO. |
| 188 | * For example, suppose get_supported_activities_list contains on_bicyle and running, and the |
| 189 | * user is biking. Consider the following four calls that could happen in any order. |
| 190 | * - When enable_activity_event(on_bicycle, ACTIVITY_EVENT_ENTER) is called, |
| 191 | * (ACTIVITY_EVENT_ENTER, on_bicycle) should be added to the FIFO. |
| 192 | * - When enable_activity_event(on_bicycle, ACTIVITY_EVENT_EXIT) is called, nothing should be |
| 193 | * added to the FIFO. |
| 194 | * - When enable_activity_event(running, ACTIVITY_EVENT_ENTER) is called, nothing should be |
| 195 | * added to the FIFO. |
| 196 | * - When enable_activity_event(running, ACTIVITY_EVENT_EXIT) is called, |
| 197 | * (ACTIVITY_EVENT_EXIT, running) should be added to the FIFO. |
| 198 | * |
Aravind Akella | 871b748 | 2014-05-27 17:19:52 -0700 | [diff] [blame] | 199 | * activity_handle - Index of the specific activity that needs to be detected in the list |
| 200 | * returned by get_supported_activities_list. |
Chengu Wang | eb1bd05 | 2015-12-02 13:00:41 -0800 | [diff] [blame] | 201 | * event_type - Specific transition of the activity that needs to be detected. It should be |
| 202 | * either ACTIVITY_EVENT_ENTER or ACTIVITY_EVENT_EXIT. |
Aravind Akella | 153c40c | 2014-05-07 12:01:43 -0700 | [diff] [blame] | 203 | * max_batch_report_latency_ns - a transition can be delayed by at most |
| 204 | * “max_batch_report_latency” nanoseconds. |
Aravind Akella | 462eae3 | 2014-03-14 19:00:45 -0700 | [diff] [blame] | 205 | * Return 0 on success, negative errno code otherwise. |
| 206 | */ |
Aravind Akella | 153c40c | 2014-05-07 12:01:43 -0700 | [diff] [blame] | 207 | int (*enable_activity_event)(const struct activity_recognition_device* dev, |
Aravind Akella | 871b748 | 2014-05-27 17:19:52 -0700 | [diff] [blame] | 208 | uint32_t activity_handle, uint32_t event_type, int64_t max_batch_report_latency_ns); |
Aravind Akella | 153c40c | 2014-05-07 12:01:43 -0700 | [diff] [blame] | 209 | |
| 210 | /* |
Chengu Wang | eb1bd05 | 2015-12-02 13:00:41 -0800 | [diff] [blame] | 211 | * Disables detection of a specific (activity, event_type) pair. All the (activity, event_type) |
| 212 | * events in the FIFO are discarded. |
Aravind Akella | 153c40c | 2014-05-07 12:01:43 -0700 | [diff] [blame] | 213 | */ |
| 214 | int (*disable_activity_event)(const struct activity_recognition_device* dev, |
Aravind Akella | 871b748 | 2014-05-27 17:19:52 -0700 | [diff] [blame] | 215 | uint32_t activity_handle, uint32_t event_type); |
Aravind Akella | 462eae3 | 2014-03-14 19:00:45 -0700 | [diff] [blame] | 216 | |
| 217 | /* |
| 218 | * Flush all the batch FIFOs. Report all the activities that were stored in the FIFO so far as |
| 219 | * if max_batch_report_latency had expired. This shouldn't change the latency in any way. Add |
| 220 | * a flush_complete_event to indicate the end of the FIFO after all events are delivered. |
Chengu Wang | eb1bd05 | 2015-12-02 13:00:41 -0800 | [diff] [blame] | 221 | * activity_callback should be called before this function returns successfully. |
Aravind Akella | 871b748 | 2014-05-27 17:19:52 -0700 | [diff] [blame] | 222 | * See ACTIVITY_EVENT_FLUSH_COMPLETE for more details. |
Aravind Akella | 462eae3 | 2014-03-14 19:00:45 -0700 | [diff] [blame] | 223 | * Return 0 on success, negative errno code otherwise. |
| 224 | */ |
| 225 | int (*flush)(const struct activity_recognition_device* dev); |
| 226 | |
| 227 | // Must be set to NULL. |
Aravind Akella | 153c40c | 2014-05-07 12:01:43 -0700 | [diff] [blame] | 228 | void (*reserved_procs[16 - 4])(void); |
Aravind Akella | 462eae3 | 2014-03-14 19:00:45 -0700 | [diff] [blame] | 229 | } activity_recognition_device_t; |
| 230 | |
| 231 | static inline int activity_recognition_open(const hw_module_t* module, |
| 232 | activity_recognition_device_t** device) { |
| 233 | return module->methods->open(module, |
| 234 | ACTIVITY_RECOGNITION_HARDWARE_INTERFACE, (hw_device_t**)device); |
| 235 | } |
| 236 | |
| 237 | static inline int activity_recognition_close(activity_recognition_device_t* device) { |
| 238 | return device->common.close(&device->common); |
| 239 | } |
| 240 | |
| 241 | __END_DECLS |
| 242 | |
| 243 | #endif // ANDROID_ACTIVITY_RECOGNITION_INTERFACE_H |