1 /* 2 * Copyright (C) 2016 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 CONTEXT_HUB_H 18 #define CONTEXT_HUB_H 19 20 #include <stdint.h> 21 #include <sys/cdefs.h> 22 #include <sys/types.h> 23 24 #include <hardware/hardware.h> 25 26 /** 27 * This header file defines the interface of a Context Hub Implementation to 28 * the Android service exposing Context hub capabilities to applications. 29 * The Context hub is expected to a low power compute domain with the following 30 * defining charecteristics - 31 * 32 * 1) Access to sensors like accelerometer, gyroscope, magenetometer. 33 * 2) Access to radios like GPS, Wifi, Bluetooth etc. 34 * 3) Access to low power audio sensing. 35 * 36 * Implementations of this HAL can add additional sensors not defined by the 37 * Android API. Such information sources shall be private to the implementation. 38 * 39 * The Context Hub HAL exposes the construct of code download. A piece of binary 40 * code can be pushed to the context hub through the supported APIs. 41 * 42 * This version of the HAL designs in the possibility of multiple context hubs. 43 */ 44 45 __BEGIN_DECLS 46 47 /*****************************************************************************/ 48 49 #define CONTEXT_HUB_HEADER_MAJOR_VERSION 1 50 #define CONTEXT_HUB_HEADER_MINOR_VERSION 0 51 #define CONTEXT_HUB_DEVICE_API_VERSION \ 52 HARDWARE_DEVICE_API_VERSION(CONTEXT_HUB_HEADER_MAJOR_VERSION, \ 53 CONTEXT_HUB_HEADER_MINOR_VERSION) 54 55 #define CONTEXT_HUB_DEVICE_API_VERSION_1_0 HARDWARE_DEVICE_API_VERSION(1, 0) 56 57 /** 58 * The id of this module 59 */ 60 #define CONTEXT_HUB_MODULE_ID "context_hub" 61 62 /** 63 * Name of the device to open 64 */ 65 #define CONTEXT_HUB_HARDWARE_POLL "ctxt_poll" 66 67 /** 68 * Memory types for code upload. Device-specific. At least HUB_MEM_TYPE_MAIN must be supported 69 */ 70 #define HUB_MEM_TYPE_MAIN 0 71 #define HUB_MEM_TYPE_SECONDARY 1 72 #define HUB_MEM_TYPE_TCM 2 73 74 75 #define HUB_MEM_TYPE_FIRST_VENDOR 0x80000000ul 76 77 #define NANOAPP_VENDORS_ALL 0xFFFFFFFFFF000000ULL 78 #define NANOAPP_VENDOR_ALL_APPS 0x0000000000FFFFFFULL 79 80 #define NANOAPP_VENDOR(name) \ 81 (((uint64_t)(name)[0] << 56) | \ 82 ((uint64_t)(name)[1] << 48) | \ 83 ((uint64_t)(name)[2] << 40) | \ 84 ((uint64_t)(name)[3] << 32) | \ 85 ((uint64_t)(name)[4] << 24)) 86 87 /* 88 * generates the NANOAPP ID from vendor id and app seq# id 89 */ 90 #define NANO_APP_ID(vendor, seq_id) \ 91 (((uint64_t)(vendor) & NANOAPP_VENDORS_ALL) | ((uint64_t)(seq_id) & NANOAPP_VENDOR_ALL_APPS)) 92 93 struct hub_app_name_t { 94 uint64_t id; 95 }; 96 97 /** 98 * Other memory types (likely not writeable, informational only) 99 */ 100 #define HUB_MEM_TYPE_BOOTLOADER 0xfffffffful 101 #define HUB_MEM_TYPE_OS 0xfffffffeul 102 #define HUB_MEM_TYPE_EEDATA 0xfffffffdul 103 #define HUB_MEM_TYPE_RAM 0xfffffffcul 104 105 /** 106 * Types of memory blocks on the context hub 107 * */ 108 #define MEM_FLAG_READ 0x1 // Memory can be written to 109 #define MEM_FLAG_WRITE 0x2 // Memory can be written to 110 #define MEM_FLAG_EXEC 0x4 // Memory can be executed from 111 112 /** 113 * The following structure defines each memory block in detail 114 */ 115 struct mem_range_t { 116 uint32_t total_bytes; 117 uint32_t free_bytes; 118 uint32_t type; // HUB_MEM_TYPE_* 119 uint32_t mem_flags; // MEM_FLAG_* 120 }; 121 122 #define NANOAPP_SIGNED_FLAG 0x1 123 #define NANOAPP_ENCRYPTED_FLAG 0x2 124 #define NANOAPP_MAGIC (((uint32_t)'N' << 0) | ((uint32_t)'A' << 8) | ((uint32_t)'N' << 16) | ((uint32_t)'O' << 24)) 125 126 // The binary format below is in little endian format 127 struct nano_app_binary_t { 128 uint32_t header_version; // 0x1 for this version 129 uint32_t magic; // "NANO" 130 struct hub_app_name_t app_id; // App Id contains vendor id 131 uint32_t app_version; // Version of the app 132 uint32_t flags; // Signed, encrypted 133 uint64_t hw_hub_type; // which hub type is this compiled for 134 uint32_t reserved[2]; // Should be all zeroes 135 uint8_t custom_binary[0]; // start of custom binary data 136 }; 137 138 struct hub_app_info { 139 struct hub_app_name_t app_name; 140 uint32_t version; 141 uint32_t num_mem_ranges; 142 struct mem_range_t mem_usage[2]; // Apps could only have RAM and SHARED_DATA 143 }; 144 145 /** 146 * Following enum defines the types of sensors that a hub may declare support 147 * for. Declaration for support would mean that the hub can access and process 148 * data from that particular sensor type. 149 */ 150 151 typedef enum { 152 CONTEXT_SENSOR_RESERVED, // 0 153 CONTEXT_SENSOR_ACCELEROMETER, // 1 154 CONTEXT_SENSOR_GYROSCOPE, // 2 155 CONTEXT_SENSOR_MAGNETOMETER, // 3 156 CONTEXT_SENSOR_BAROMETER, // 4 157 CONTEXT_SENSOR_PROXIMITY_SENSOR, // 5 158 CONTEXT_SENSOR_AMBIENT_LIGHT_SENSOR, // 6 159 160 CONTEXT_SENSOR_GPS = 0x100, // 0x100 161 // Reserving this space for variants on GPS 162 CONTEXT_SENSOR_WIFI = 0x200, // 0x200 163 // Reserving this space for variants on WIFI 164 CONTEXT_SENSOR_AUDIO = 0x300, // 0x300 165 // Reserving this space for variants on Audio 166 CONTEXT_SENSOR_CAMERA = 0x400, // 0x400 167 // Reserving this space for variants on Camera 168 CONTEXT_SENSOR_BLE = 0x500, // 0x500 169 170 CONTEXT_SENSOR_MAX = 0xffffffff, //make sure enum size is set 171 } context_sensor_e; 172 173 /** 174 * Sensor types beyond CONTEXT_HUB_TYPE_PRIVATE_SENSOR_BASE are custom types 175 */ 176 #define CONTEXT_HUB_TYPE_PRIVATE_SENSOR_BASE 0x10000 177 178 /** 179 * The following structure describes a sensor 180 */ 181 struct physical_sensor_description_t { 182 uint32_t sensor_type; // From the definitions above eg: 100 183 const char *type_string; // Type as a string. eg: "GPS" 184 const char *name; // Identifier eg: "Bosch BMI160" 185 const char *vendor; // Vendor : eg "STM" 186 uint32_t version; // Version : eg 0x1001 187 uint32_t fifo_reserved_count; // Batching possible in hardware. Please 188 // note that here hardware does not include 189 // the context hub itself. Thus, this 190 // definition may be different from say the 191 // number advertised in the sensors HAL 192 // which allows for batching in a hub. 193 uint32_t fifo_max_count; // maximum number of batchable events. 194 uint64_t min_delay_ms; // in milliseconds, corresponding to highest 195 // sampling freq. 196 uint64_t max_delay_ms; // in milliseconds, corresponds to minimum 197 // sampling frequency 198 float peak_power_mw; // At max frequency & no batching, power 199 // in milliwatts 200 }; 201 202 struct connected_sensor_t { 203 uint32_t sensor_id; // identifier for this sensor 204 205 /* This union may be extended to other sensor types */ 206 union { 207 struct physical_sensor_description_t physical_sensor; 208 }; 209 }; 210 211 struct hub_message_t { 212 struct hub_app_name_t app_name; /* To/From this nanoapp */ 213 uint32_t message_type; 214 uint32_t message_len; 215 const void *message; 216 }; 217 218 /** 219 * Definition of a context hub. A device may contain more than one low 220 * power domain. In that case, please add an entry for each hub. However, 221 * it is perfectly OK for a device to declare one context hub and manage 222 * them internally as several 223 */ 224 225 struct context_hub_t { 226 const char *name; // descriptive name eg: "Awesome Hub #1" 227 const char *vendor; // hub hardware vendor eg: "Qualcomm" 228 const char *toolchain; // toolchain to make binaries eg:"gcc ARM" 229 uint32_t platform_version; // Version of the hardware : eg 0x20 230 uint32_t toolchain_version; // Version of the toolchain : eg: 0x484 231 uint32_t hub_id; // a device unique id for this hub 232 233 float peak_mips; // Peak MIPS platform can deliver 234 float stopped_power_draw_mw; // if stopped, retention power, milliwatts 235 float sleep_power_draw_mw; // if sleeping, retention power, milliwatts 236 float peak_power_draw_mw; // for a busy CPUm power in milliwatts 237 238 const struct connected_sensor_t *connected_sensors; // array of connected sensors 239 uint32_t num_connected_sensors; // number of connected sensors 240 241 const struct hub_app_name_t os_app_name; /* send msgs here for OS functions */ 242 uint32_t max_supported_msg_len; // This is the maximum size of the message that can 243 // be sent to the hub in one chunk (in bytes) 244 }; 245 246 /** 247 * Definitions of message payloads, see hub_messages_e 248 */ 249 250 struct status_response_t { 251 int32_t result; // 0 on success, < 0 : error on failure. > 0 for any descriptive status 252 }; 253 254 struct apps_enable_request_t { 255 struct hub_app_name_t app_name; 256 }; 257 258 struct apps_disable_request_t { 259 struct hub_app_name_t app_name; 260 }; 261 262 struct load_app_request_t { 263 struct nano_app_binary_t app_binary; 264 }; 265 266 struct unload_app_request_t { 267 struct hub_app_name_t app_name; 268 }; 269 270 struct query_apps_request_t { 271 struct hub_app_name_t app_name; 272 }; 273 274 /** 275 * CONTEXT_HUB_APPS_ENABLE 276 * Enables the specified nano-app(s) 277 * 278 * Payload : apps_enable_request_t 279 * 280 * Response : status_response_t 281 * On receipt of a successful response, it is 282 * expected that 283 * 284 * i) the app is executing and able to receive 285 * any messages. 286 * 287 * ii) the system should be able to respond to an 288 * CONTEXT_HUB_QUERY_APPS request. 289 * 290 */ 291 292 /** 293 * CONTEXT_HUB_APPS_DISABLE 294 * Stops the specified nano-app(s) 295 * 296 * Payload : apps_disable_request_t 297 * 298 * Response : status_response_t 299 * On receipt of a successful response, 300 * i) No further events are delivered to the 301 * nanoapp. 302 * 303 * ii) The app should not show up in a 304 * CONTEXT_HUB_QUERY_APPS request. 305 */ 306 307 /** 308 * CONTEXT_HUB_LOAD_APP 309 * Loads a nanoApp. Upon loading the nanoApp's init method is 310 * called. 311 * 312 * 313 * Payload : load_app_request_t 314 * 315 * Response : status_response_t On receipt of a successful 316 * response, it is expected that 317 * i) the app is executing and able to receive 318 * messages. 319 * 320 * ii) the system should be able to respond to a 321 * CONTEXT_HUB_QUERY_APPS. 322 */ 323 324 /** 325 * CONTEXT_HUB_UNLOAD_APP 326 * Unloads a nanoApp. Before the unload, the app's deinit method 327 * is called. 328 * 329 * Payload : unload_app_request_t. 330 * 331 * Response : status_response_t On receipt of a 332 * successful response, it is expected that 333 * i) No further events are delivered to the 334 * nanoapp. 335 * 336 * ii) the system does not list the app in a 337 * response to a CONTEXT_HUB_QUERY_APPS. 338 * 339 * iii) Any resources used by the app should be 340 * freed up and available to the system. 341 */ 342 343 /** 344 * CONTEXT_HUB_QUERY_APPS Queries for status of apps 345 * 346 * Payload : query_apps_request_t 347 * 348 * Response : struct hub_app_info[] 349 */ 350 351 /** 352 * CONTEXT_HUB_QUERY_MEMORY Queries for memory regions on the 353 * hub 354 * 355 * Payload : NULL 356 * 357 * Response : struct mem_range_t[] 358 */ 359 360 /** 361 * CONTEXT_HUB_OS_REBOOT 362 * Reboots context hub OS, restarts all the nanoApps. 363 * No reboot notification is sent to nanoApps; reboot happens immediately and 364 * unconditionally; all volatile FW state and any data is lost as a result 365 * 366 * Payload : none 367 * 368 * Response : status_response_t 369 * On receipt of a successful response, it is 370 * expected that 371 * 372 * i) system reboot has completed; 373 * status contains reboot reason code (platform-specific) 374 * 375 * Unsolicited response: 376 * System may send unsolicited response at any time; 377 * this should be interpreted as FW reboot, and necessary setup 378 * has to be done (same or similar to the setup done on system boot) 379 */ 380 381 /** 382 * All communication between the context hubs and the Context Hub Service is in 383 * the form of messages. Some message types are distinguished and their 384 * Semantics shall be well defined. 385 * Custom message types should be defined starting above 386 * CONTEXT_HUB_PRIVATE_MSG_BASE 387 */ 388 389 typedef enum { 390 CONTEXT_HUB_APPS_ENABLE = 1, // Enables loaded nano-app(s) 391 CONTEXT_HUB_APPS_DISABLE = 2, // Disables loaded nano-app(s) 392 CONTEXT_HUB_LOAD_APP = 3, // Load a supplied app 393 CONTEXT_HUB_UNLOAD_APP = 4, // Unload a specified app 394 CONTEXT_HUB_QUERY_APPS = 5, // Query for app(s) info on hub 395 CONTEXT_HUB_QUERY_MEMORY = 6, // Query for memory info 396 CONTEXT_HUB_OS_REBOOT = 7, // Request to reboot context HUB OS 397 } hub_messages_e; 398 399 #define CONTEXT_HUB_TYPE_PRIVATE_MSG_BASE 0x00400 400 401 /** 402 * A callback registers with the context hub service to pass messages 403 * coming from the hub to the service/clients. 404 */ 405 typedef int context_hub_callback(uint32_t hub_id, const struct hub_message_t *rxed_msg, void *cookie); 406 407 408 /** 409 * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM 410 * and the fields of this data structure must begin with hw_module_t 411 * followed by module specific information. 412 */ 413 struct context_hub_module_t { 414 struct hw_module_t common; 415 416 /** 417 * Enumerate all available hubs.The list is returned in "list". 418 * @return result : number of hubs in list or error (negative) 419 * 420 * This method shall be called at device bootup. 421 */ 422 int (*get_hubs)(struct context_hub_module_t* module, const struct context_hub_t ** list); 423 424 /** 425 * Registers a callback for the HAL implementation to communicate 426 * with the context hub service. 427 * @return result : 0 if successful, error code otherwise 428 */ 429 int (*subscribe_messages)(uint32_t hub_id, context_hub_callback cbk, void *cookie); 430 431 /** 432 * Send a message to a hub 433 * @return result : 0 if successful, error code otherwise 434 */ 435 int (*send_message)(uint32_t hub_id, const struct hub_message_t *msg); 436 437 }; 438 439 __END_DECLS 440 441 #endif // CONTEXT_HUB_SENSORS_INTERFACE_H 442