/* * Copyright (C) 2016 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ #ifndef CONTEXT_HUB_H #define CONTEXT_HUB_H #include #include #include #include /** * This header file defines the interface of a Context Hub Implementation to * the Android service exposing Context hub capabilities to applications. * The Context hub is expected to a low power compute domain with the following * defining charecteristics - * * 1) Access to sensors like accelerometer, gyroscope, magenetometer. * 2) Access to radios like GPS, Wifi, Bluetooth etc. * 3) Access to low power audio sensing. * * Implementations of this HAL can add additional sensors not defined by the * Android API. Such information sources shall be private to the implementation. * * The Context Hub HAL exposes the construct of code download. A piece of binary * code can be pushed to the context hub through the supported APIs. * * This version of the HAL designs in the possibility of multiple context hubs. */ __BEGIN_DECLS /*****************************************************************************/ #define CONTEXT_HUB_HEADER_MAJOR_VERSION 1 #define CONTEXT_HUB_HEADER_MINOR_VERSION 0 #define CONTEXT_HUB_DEVICE_API_VERSION \ HARDWARE_DEVICE_API_VERSION(CONTEXT_HUB_HEADER_MAJOR_VERSION, \ CONTEXT_HUB_HEADER_MINOR_VERSION) #define CONTEXT_HUB_DEVICE_API_VERSION_1_0 HARDWARE_DEVICE_API_VERSION(1, 0) /** * The id of this module */ #define CONTEXT_HUB_MODULE_ID "context_hub" /** * Name of the device to open */ #define CONTEXT_HUB_HARDWARE_POLL "ctxt_poll" /** * Memory types for code upload. Device-specific. At least HUB_MEM_TYPE_MAIN must be supported */ #define HUB_MEM_TYPE_MAIN 0 #define HUB_MEM_TYPE_SECONDARY 1 #define HUB_MEM_TYPE_TCM 2 #define HUB_MEM_TYPE_FIRST_VENDOR 0x80000000ul #define NANOAPP_VENDORS_ALL 0xFFFFFFFFFF000000ULL #define NANOAPP_VENDOR_ALL_APPS 0x0000000000FFFFFFULL #define NANOAPP_VENDOR(name) \ (((uint64_t)(name)[0] << 56) | \ ((uint64_t)(name)[1] << 48) | \ ((uint64_t)(name)[2] << 40) | \ ((uint64_t)(name)[3] << 32) | \ ((uint64_t)(name)[4] << 24)) /* * generates the NANOAPP ID from vendor id and app seq# id */ #define NANO_APP_ID(vendor, seq_id) \ (((uint64_t)(vendor) & NANOAPP_VENDORS_ALL) | ((uint64_t)(seq_id) & NANOAPP_VENDOR_ALL_APPS)) struct hub_app_name_t { uint64_t id; }; /** * Other memory types (likely not writeable, informational only) */ #define HUB_MEM_TYPE_BOOTLOADER 0xfffffffful #define HUB_MEM_TYPE_OS 0xfffffffeul #define HUB_MEM_TYPE_EEDATA 0xfffffffdul #define HUB_MEM_TYPE_RAM 0xfffffffcul /** * Types of memory blocks on the context hub * */ #define MEM_FLAG_READ 0x1 // Memory can be written to #define MEM_FLAG_WRITE 0x2 // Memory can be written to #define MEM_FLAG_EXEC 0x4 // Memory can be executed from /** * The following structure defines each memory block in detail */ struct mem_range_t { uint32_t total_bytes; uint32_t free_bytes; uint32_t type; // HUB_MEM_TYPE_* uint32_t mem_flags; // MEM_FLAG_* }; #define NANOAPP_SIGNED_FLAG 0x1 #define NANOAPP_ENCRYPTED_FLAG 0x2 #define NANOAPP_MAGIC (((uint32_t)'N' << 0) | ((uint32_t)'A' << 8) | ((uint32_t)'N' << 16) | ((uint32_t)'O' << 24)) // The binary format below is in little endian format struct nano_app_binary_t { uint32_t header_version; // 0x1 for this version uint32_t magic; // "NANO" struct hub_app_name_t app_id; // App Id contains vendor id uint32_t app_version; // Version of the app uint32_t flags; // Signed, encrypted uint64_t hw_hub_type; // which hub type is this compiled for uint32_t reserved[2]; // Should be all zeroes uint8_t custom_binary[0]; // start of custom binary data }; struct hub_app_info { struct hub_app_name_t app_name; uint32_t version; uint32_t num_mem_ranges; struct mem_range_t mem_usage[2]; // Apps could only have RAM and SHARED_DATA }; /** * Following enum defines the types of sensors that a hub may declare support * for. Declaration for support would mean that the hub can access and process * data from that particular sensor type. */ typedef enum { CONTEXT_SENSOR_RESERVED, // 0 CONTEXT_SENSOR_ACCELEROMETER, // 1 CONTEXT_SENSOR_GYROSCOPE, // 2 CONTEXT_SENSOR_MAGNETOMETER, // 3 CONTEXT_SENSOR_BAROMETER, // 4 CONTEXT_SENSOR_PROXIMITY_SENSOR, // 5 CONTEXT_SENSOR_AMBIENT_LIGHT_SENSOR, // 6 CONTEXT_SENSOR_GPS = 0x100, // 0x100 // Reserving this space for variants on GPS CONTEXT_SENSOR_WIFI = 0x200, // 0x200 // Reserving this space for variants on WIFI CONTEXT_SENSOR_AUDIO = 0x300, // 0x300 // Reserving this space for variants on Audio CONTEXT_SENSOR_CAMERA = 0x400, // 0x400 // Reserving this space for variants on Camera CONTEXT_SENSOR_BLE = 0x500, // 0x500 CONTEXT_SENSOR_MAX = 0xffffffff, //make sure enum size is set } context_sensor_e; /** * Sensor types beyond CONTEXT_HUB_TYPE_PRIVATE_SENSOR_BASE are custom types */ #define CONTEXT_HUB_TYPE_PRIVATE_SENSOR_BASE 0x10000 /** * The following structure describes a sensor */ struct physical_sensor_description_t { uint32_t sensor_type; // From the definitions above eg: 100 const char *type_string; // Type as a string. eg: "GPS" const char *name; // Identifier eg: "Bosch BMI160" const char *vendor; // Vendor : eg "STM" uint32_t version; // Version : eg 0x1001 uint32_t fifo_reserved_count; // Batching possible in hardware. Please // note that here hardware does not include // the context hub itself. Thus, this // definition may be different from say the // number advertised in the sensors HAL // which allows for batching in a hub. uint32_t fifo_max_count; // maximum number of batchable events. uint64_t min_delay_ms; // in milliseconds, corresponding to highest // sampling freq. uint64_t max_delay_ms; // in milliseconds, corresponds to minimum // sampling frequency float peak_power_mw; // At max frequency & no batching, power // in milliwatts }; struct connected_sensor_t { uint32_t sensor_id; // identifier for this sensor /* This union may be extended to other sensor types */ union { struct physical_sensor_description_t physical_sensor; }; }; struct hub_message_t { struct hub_app_name_t app_name; /* To/From this nanoapp */ uint32_t message_type; uint32_t message_len; const void *message; }; /** * Definition of a context hub. A device may contain more than one low * power domain. In that case, please add an entry for each hub. However, * it is perfectly OK for a device to declare one context hub and manage * them internally as several */ struct context_hub_t { const char *name; // descriptive name eg: "Awesome Hub #1" const char *vendor; // hub hardware vendor eg: "Qualcomm" const char *toolchain; // toolchain to make binaries eg:"gcc ARM" uint32_t platform_version; // Version of the hardware : eg 0x20 uint32_t toolchain_version; // Version of the toolchain : eg: 0x484 uint32_t hub_id; // a device unique id for this hub float peak_mips; // Peak MIPS platform can deliver float stopped_power_draw_mw; // if stopped, retention power, milliwatts float sleep_power_draw_mw; // if sleeping, retention power, milliwatts float peak_power_draw_mw; // for a busy CPUm power in milliwatts const struct connected_sensor_t *connected_sensors; // array of connected sensors uint32_t num_connected_sensors; // number of connected sensors const struct hub_app_name_t os_app_name; /* send msgs here for OS functions */ uint32_t max_supported_msg_len; // This is the maximum size of the message that can // be sent to the hub in one chunk (in bytes) }; /** * Definitions of message payloads, see hub_messages_e */ struct status_response_t { int32_t result; // 0 on success, < 0 : error on failure. > 0 for any descriptive status }; struct apps_enable_request_t { struct hub_app_name_t app_name; }; struct apps_disable_request_t { struct hub_app_name_t app_name; }; struct load_app_request_t { struct nano_app_binary_t app_binary; }; struct unload_app_request_t { struct hub_app_name_t app_name; }; struct query_apps_request_t { struct hub_app_name_t app_name; }; /** * CONTEXT_HUB_APPS_ENABLE * Enables the specified nano-app(s) * * Payload : apps_enable_request_t * * Response : status_response_t * On receipt of a successful response, it is * expected that * * i) the app is executing and able to receive * any messages. * * ii) the system should be able to respond to an * CONTEXT_HUB_QUERY_APPS request. * */ /** * CONTEXT_HUB_APPS_DISABLE * Stops the specified nano-app(s) * * Payload : apps_disable_request_t * * Response : status_response_t * On receipt of a successful response, * i) No further events are delivered to the * nanoapp. * * ii) The app should not show up in a * CONTEXT_HUB_QUERY_APPS request. */ /** * CONTEXT_HUB_LOAD_APP * Loads a nanoApp. Upon loading the nanoApp's init method is * called. * * * Payload : load_app_request_t * * Response : status_response_t On receipt of a successful * response, it is expected that * i) the app is executing and able to receive * messages. * * ii) the system should be able to respond to a * CONTEXT_HUB_QUERY_APPS. */ /** * CONTEXT_HUB_UNLOAD_APP * Unloads a nanoApp. Before the unload, the app's deinit method * is called. * * Payload : unload_app_request_t. * * Response : status_response_t On receipt of a * successful response, it is expected that * i) No further events are delivered to the * nanoapp. * * ii) the system does not list the app in a * response to a CONTEXT_HUB_QUERY_APPS. * * iii) Any resources used by the app should be * freed up and available to the system. */ /** * CONTEXT_HUB_QUERY_APPS Queries for status of apps * * Payload : query_apps_request_t * * Response : struct hub_app_info[] */ /** * CONTEXT_HUB_QUERY_MEMORY Queries for memory regions on the * hub * * Payload : NULL * * Response : struct mem_range_t[] */ /** * CONTEXT_HUB_OS_REBOOT * Reboots context hub OS, restarts all the nanoApps. * No reboot notification is sent to nanoApps; reboot happens immediately and * unconditionally; all volatile FW state and any data is lost as a result * * Payload : none * * Response : status_response_t * On receipt of a successful response, it is * expected that * * i) system reboot has completed; * status contains reboot reason code (platform-specific) * * Unsolicited response: * System may send unsolicited response at any time; * this should be interpreted as FW reboot, and necessary setup * has to be done (same or similar to the setup done on system boot) */ /** * All communication between the context hubs and the Context Hub Service is in * the form of messages. Some message types are distinguished and their * Semantics shall be well defined. * Custom message types should be defined starting above * CONTEXT_HUB_PRIVATE_MSG_BASE */ typedef enum { CONTEXT_HUB_APPS_ENABLE = 1, // Enables loaded nano-app(s) CONTEXT_HUB_APPS_DISABLE = 2, // Disables loaded nano-app(s) CONTEXT_HUB_LOAD_APP = 3, // Load a supplied app CONTEXT_HUB_UNLOAD_APP = 4, // Unload a specified app CONTEXT_HUB_QUERY_APPS = 5, // Query for app(s) info on hub CONTEXT_HUB_QUERY_MEMORY = 6, // Query for memory info CONTEXT_HUB_OS_REBOOT = 7, // Request to reboot context HUB OS } hub_messages_e; #define CONTEXT_HUB_TYPE_PRIVATE_MSG_BASE 0x00400 /** * A callback registers with the context hub service to pass messages * coming from the hub to the service/clients. */ typedef int context_hub_callback(uint32_t hub_id, const struct hub_message_t *rxed_msg, void *cookie); /** * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM * and the fields of this data structure must begin with hw_module_t * followed by module specific information. */ struct context_hub_module_t { struct hw_module_t common; /** * Enumerate all available hubs.The list is returned in "list". * @return result : number of hubs in list or error (negative) * * This method shall be called at device bootup. */ int (*get_hubs)(struct context_hub_module_t* module, const struct context_hub_t ** list); /** * Registers a callback for the HAL implementation to communicate * with the context hub service. * @return result : 0 if successful, error code otherwise */ int (*subscribe_messages)(uint32_t hub_id, context_hub_callback cbk, void *cookie); /** * Send a message to a hub * @return result : 0 if successful, error code otherwise */ int (*send_message)(uint32_t hub_id, const struct hub_message_t *msg); }; __END_DECLS #endif // CONTEXT_HUB_SENSORS_INTERFACE_H