Home | History | Annotate | Download | only in hardware
      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