include/hardware/context_hub.h

   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
 125 // The binary format below is in little endian format
 126 struct nano_app_binary_t {
 127     uint32_t header_version;       // 0x1 for this version
 128     uint32_t magic;                // "NANO"
 129     struct hub_app_name_t app_id;  // App Id contains vendor id
 130     uint32_t app_version;          // Version of the app
 131     uint32_t flags;                // Signed, encrypted
 132     uint64_t hw_hub_type;          // which hub type is this compiled for
 133     uint32_t reserved[2];          // Should be all zeroes
 134     uint8_t  custom_binary[0];     // start of custom binary data
 135 };
 136
 137 struct hub_app_info {
 138     struct hub_app_name_t app_name;
 139     uint32_t version;
 140     uint32_t num_mem_ranges;
 141     struct mem_range_t mem_usage[2]; // Apps could only have RAM and SHARED_DATA
 142 };
 143
 144 /**
 145  * Following enum defines the types of sensors that a hub may declare support
 146  * for. Declaration for support would mean that the hub can access and process
 147  * data from that particular sensor type.
 148  */
 149
 150 typedef enum {
 151     CONTEXT_SENSOR_RESERVED,             // 0
 152     CONTEXT_SENSOR_ACCELEROMETER,        // 1
 153     CONTEXT_SENSOR_GYROSCOPE,            // 2
 154     CONTEXT_SENSOR_MAGNETOMETER,         // 3
 155     CONTEXT_SENSOR_BAROMETER,            // 4
 156     CONTEXT_SENSOR_PROXIMITY_SENSOR,     // 5
 157     CONTEXT_SENSOR_AMBIENT_LIGHT_SENSOR, // 6
 158
 159     CONTEXT_SENSOR_GPS = 0x100,          // 0x100
 160     // Reserving this space for variants on GPS
 161     CONTEXT_SENSOR_WIFI = 0x200,         // 0x200
 162     // Reserving this space for variants on WIFI
 163     CONTEXT_SENSOR_AUDIO = 0x300,        // 0x300
 164     // Reserving this space for variants on Audio
 165     CONTEXT_SENSOR_CAMERA = 0x400,       // 0x400
 166     // Reserving this space for variants on Camera
 167     CONTEXT_SENSOR_BLE = 0x500,          // 0x500
 168
 169     CONTEXT_SENSOR_MAX = 0xffffffff,     //make sure enum size is set
 170 } context_sensor_e;
 171
 172 /**
 173  * Sensor types beyond CONTEXT_HUB_TYPE_PRIVATE_SENSOR_BASE are custom types
 174  */
 175 #define CONTEXT_HUB_TYPE_PRIVATE_SENSOR_BASE 0x10000
 176
 177 /**
 178  * The following structure describes a sensor
 179  */
 180 struct physical_sensor_description_t {
 181     uint32_t sensor_type;           // From the definitions above eg: 100
 182     const char *type_string;        // Type as a string. eg: "GPS"
 183     const char *name;               // Identifier eg: "Bosch BMI160"
 184     const char *vendor;             // Vendor : eg "STM"
 185     uint32_t version;               // Version : eg 0x1001
 186     uint32_t fifo_reserved_count;   // Batching possible in hardware. Please
 187                                     // note that here hardware does not include
 188                                     // the context hub itself. Thus, this
 189                                     // definition may be different from say the
 190                                     // number advertised in the sensors HAL
 191                                     // which allows for batching in a hub.
 192     uint32_t fifo_max_count;        // maximum number of batchable events.
 193     uint64_t min_delay_ms;          // in milliseconds, corresponding to highest
 194                                     // sampling freq.
 195     uint64_t max_delay_ms;          // in milliseconds, corresponds to minimum
 196                                     // sampling frequency
 197     float peak_power_mw;            // At max frequency & no batching, power
 198                                     // in milliwatts
 199 };
 200
 201 struct connected_sensor_t {
 202     uint32_t sensor_id;             // identifier for this sensor
 203
 204     /* This union may be extended to other sensor types */
 205     union {
 206         struct physical_sensor_description_t physical_sensor;
 207     };
 208 };
 209
 210 struct hub_message_t {
 211     struct hub_app_name_t app_name; /* To/From this nanoapp */
 212     uint32_t message_type;
 213     uint32_t message_len;
 214     const void *message;
 215 };
 216
 217 /**
 218  * Definition of a context hub. A device may contain more than one low
 219  * power domain. In that case, please add an entry for each hub. However,
 220  * it is perfectly OK for a device to declare one context hub and manage
 221  * them internally as several
 222  */
 223
 224 struct context_hub_t {
 225     const char *name;                // descriptive name eg: "Awesome Hub #1"
 226     const char *vendor;              // hub hardware vendor eg: "Qualcomm"
 227     const char *toolchain;           // toolchain to make binaries eg:"gcc ARM"
 228     uint32_t platform_version;       // Version of the hardware : eg 0x20
 229     uint32_t toolchain_version;      // Version of the toolchain : eg: 0x484
 230     uint32_t hub_id;                 // a device unique id for this hub
 231
 232     float peak_mips;                 // Peak MIPS platform can deliver
 233     float stopped_power_draw_mw;     // if stopped, retention power, milliwatts
 234     float sleep_power_draw_mw;       // if sleeping, retention power, milliwatts
 235     float peak_power_draw_mw;        // for a busy CPUm power in milliwatts
 236
 237     const struct connected_sensor_t *connected_sensors; // array of connected sensors
 238     uint32_t num_connected_sensors;  // number of connected sensors
 239
 240     const struct hub_app_name_t os_app_name; /* send msgs here for OS functions */
 241     uint32_t max_supported_msg_len;  // This is the maximum size of the message that can
 242                                      // be sent to the hub in one chunk (in bytes)
 243 };
 244
 245 /**
 246  * Definitions of message payloads, see hub_messages_e
 247  */
 248
 249 struct status_response_t {
 250     int32_t result; // 0 on success, < 0 : error on failure. > 0 for any descriptive status
 251 };
 252
 253 struct apps_enable_request_t {
 254     struct hub_app_name_t app_name;
 255 };
 256
 257 struct apps_disable_request_t {
 258     struct hub_app_name_t app_name;
 259 };
 260
 261 struct load_app_request_t {
 262     struct nano_app_binary_t app_binary;
 263 };
 264
 265 struct unload_app_request_t {
 266     struct hub_app_name_t app_name;
 267 };
 268
 269 struct query_apps_request_t {
 270     struct hub_app_name_t app_name;
 271 };
 272
 273 /**
 274  * CONTEXT_HUB_APPS_ENABLE
 275  * Enables the specified nano-app(s)
 276  *
 277  * Payload : apps_enable_request_t
 278  *
 279  * Response : status_response_t
 280  *            On receipt of a successful response, it is
 281  *               expected that
 282  *
 283  *               i) the app is executing and able to receive
 284  *                  any messages.
 285  *
 286  *              ii) the system should be able to respond to an
 287  *                  CONTEXT_HUB_QUERY_APPS request.
 288  *
 289  */
 290
 291 /**
 292  * CONTEXT_HUB_APPS_DISABLE
 293  * Stops the specified nano-app(s)
 294  *
 295  * Payload : apps_disable_request_t
 296  *
 297  * Response : status_response_t
 298  *            On receipt of a successful response,
 299  *               i) No further events are delivered to the
 300  *                  nanoapp.
 301  *
 302  *              ii) The app should not show up in a
 303  *                  CONTEXT_HUB_QUERY_APPS request.
 304  */
 305
 306 /**
 307  * CONTEXT_HUB_LOAD_APP
 308  * Loads a nanoApp. Upon loading the nanoApp's init method is
 309  * called.
 310  *
 311  *
 312  * Payload : load_app_request_t
 313  *
 314  * Response : status_response_t On receipt of a successful
 315  *               response, it is expected that
 316  *               i) the app is executing and able to receive
 317  *                  messages.
 318  *
 319  *              ii) the system should be able to respond to a
 320  *                  CONTEXT_HUB_QUERY_APPS.
 321  */
 322
 323 /**
 324  * CONTEXT_HUB_UNLOAD_APP
 325  * Unloads a nanoApp. Before the unload, the app's deinit method
 326  * is called.
 327  *
 328  * Payload : unload_app_request_t.
 329  *
 330  * Response : status_response_t On receipt of a
 331  *            successful response, it is expected that
 332  *               i) No further events are delivered to the
 333  *                  nanoapp.
 334  *
 335  *              ii) the system does not list the app in a
 336  *                  response to a CONTEXT_HUB_QUERY_APPS.
 337  *
 338  *             iii) Any resources used by the app should be
 339  *                  freed up and available to the system.
 340  */
 341
 342 /**
 343  * CONTEXT_HUB_QUERY_APPS Queries for status of apps
 344  *
 345  * Payload : query_apps_request_t
 346  *
 347  * Response : struct hub_app_info[]
 348  */
 349
 350 /**
 351  * CONTEXT_HUB_QUERY_MEMORY Queries for memory regions on the
 352  * hub
 353  *
 354  * Payload : NULL
 355  *
 356  * Response : struct mem_range_t[]
 357  */
 358
 359 /**
 360  * All communication between the context hubs and the Context Hub Service is in
 361  * the form of messages. Some message types are distinguished and their
 362  * Semantics shall be well defined.
 363  * Custom message types should be defined starting above
 364  * CONTEXT_HUB_PRIVATE_MSG_BASE
 365  */
 366
 367 typedef enum {
 368     CONTEXT_HUB_APPS_ENABLE  = 1, // Enables loaded nano-app(s)
 369     CONTEXT_HUB_APPS_DISABLE = 2, // Disables loaded nano-app(s)
 370     CONTEXT_HUB_LOAD_APP     = 3, // Load a supplied app
 371     CONTEXT_HUB_UNLOAD_APP   = 4, // Unload a specified app
 372     CONTEXT_HUB_QUERY_APPS   = 5, // Query for app(s) info on hub
 373     CONTEXT_HUB_QUERY_MEMORY = 6, // Query for memory info
 374 } hub_messages_e;
 375
 376 #define CONTEXT_HUB_TYPE_PRIVATE_MSG_BASE 0x00400
 377
 378 /**
 379  * A callback registers with the context hub service to pass messages
 380  * coming from the hub to the service/clients.
 381  */
 382 typedef int context_hub_callback(uint32_t hub_id, const struct hub_message_t *rxed_msg, void *cookie);
 383
 384
 385 /**
 386  * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM
 387  * and the fields of this data structure must begin with hw_module_t
 388  * followed by module specific information.
 389  */
 390 struct context_hub_module_t {
 391     struct hw_module_t common;
 392
 393     /**
 394      * Enumerate all available hubs.The list is returned in "list".
 395      * @return result : number of hubs in list or error  (negative)
 396      *
 397      * This method shall be called at device bootup.
 398      */
 399     int (*get_hubs)(struct context_hub_module_t* module, const struct context_hub_t ** list);
 400
 401     /**
 402      * Registers a callback for the HAL implementation to communicate
 403      * with the context hub service.
 404      * @return result : 0 if successful, error code otherwise
 405      */
 406     int (*subscribe_messages)(uint32_t hub_id, context_hub_callback cbk, void *cookie);
 407
 408     /**
 409      * Send a message to a hub
 410      * @return result : 0 if successful, error code otherwise
 411      */
 412     int (*send_message)(uint32_t hub_id, const struct hub_message_t *msg);
 413
 414 };
 415
 416 __END_DECLS
 417
 418 #endif  // CONTEXT_HUB_SENSORS_INTERFACE_H