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 /* 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. 62 */ 63 64 #define ACTIVITY_TYPE_IN_VEHICLE "android.activity_recognition.in_vehicle" 65 66 #define ACTIVITY_TYPE_ON_BICYCLE "android.activity_recognition.on_bicycle" 67 68 #define ACTIVITY_TYPE_WALKING "android.activity_recognition.walking" 69 70 #define ACTIVITY_TYPE_RUNNING "android.activity_recognition.running" 71 72 #define ACTIVITY_TYPE_STILL "android.activity_recognition.still" 73 74 #define ACTIVITY_TYPE_TILTING "android.activity_recognition.tilting" 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. 87 * activity_event_t.event_type = ACTIVITY_EVENT_FLUSH_COMPLETE 88 * activity_event_t.activity = 0 89 * activity_event_t.timestamp = 0 90 * activity_event_t.reserved = 0 91 * See (*flush)() for more details. 92 */ 93 ACTIVITY_EVENT_FLUSH_COMPLETE = 0, 94 95 /* Signifies entering an activity. */ 96 ACTIVITY_EVENT_ENTER = 1, 97 98 /* Signifies exiting an activity. */ 99 ACTIVITY_EVENT_EXIT = 2 100 }; 101 102 /* 103 * Each event is a separate activity with event_type indicating whether this activity has started 104 * or ended. Eg event: (event_type="enter", activity="ON_FOOT", timestamp) 105 */ 106 typedef struct activity_event { 107 /* One of the ACTIVITY_EVENT_* constants defined above. */ 108 uint32_t event_type; 109 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 */ 114 uint32_t activity; 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 { 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 */ 130 hw_module_t common; 131 132 /* 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. 138 */ 139 int (*get_supported_activities_list)(struct activity_recognition_module* module, 140 char const* const* *activity_list); 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. 150 void (*activity_callback)(const struct activity_recognition_callback_procs* procs, 151 const activity_event_t* events, int count); 152 } activity_recognition_callback_procs_t; 153 154 typedef struct activity_recognition_device { 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 */ 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 /* 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 * 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 * 199 * activity_handle - Index of the specific activity that needs to be detected in the list 200 * returned by get_supported_activities_list. 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. 203 * max_batch_report_latency_ns - a transition can be delayed by at most 204 * max_batch_report_latency nanoseconds. 205 * Return 0 on success, negative errno code otherwise. 206 */ 207 int (*enable_activity_event)(const struct activity_recognition_device* dev, 208 uint32_t activity_handle, uint32_t event_type, int64_t max_batch_report_latency_ns); 209 210 /* 211 * Disables detection of a specific (activity, event_type) pair. All the (activity, event_type) 212 * events in the FIFO are discarded. 213 */ 214 int (*disable_activity_event)(const struct activity_recognition_device* dev, 215 uint32_t activity_handle, uint32_t event_type); 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. 221 * activity_callback should be called before this function returns successfully. 222 * See ACTIVITY_EVENT_FLUSH_COMPLETE for more details. 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. 228 void (*reserved_procs[16 - 4])(void); 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 244
