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