| /* |
| * 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 <stdint.h> |
| #include <sys/cdefs.h> |
| #include <sys/types.h> |
| |
| #include <hardware/hardware.h> |
| |
| /** |
| * 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_VERSION 1 |
| #define CONTEXT_HUB_DEVICE_API_VERSION_1_0 HARDWARE_DEVICE_API_VERSION_2(1, 0, CONTEXT_HUB_HEADER_VERSION) |
| |
| /** |
| * 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 |
| |
| |
| /** |
| * 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_* |
| }; |
| |
| |
| /** |
| * App names may be strings, bytes, uints, etc. This caovers all types of app names |
| */ |
| struct hub_app_name_t { |
| uint32_t app_name_len; |
| const void *app_name; |
| }; |
| |
| struct hub_app_info { |
| const struct hub_app_name_t *name; |
| uint32_t version; |
| uint32_t num_mem_ranges; |
| const struct mem_range_t *mem_usage; |
| }; |
| |
| /** |
| * 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; |
| }; |
| }; |
| |
| |
| |
| /** |
| * Messages of this length or less must be supported by all implementations, |
| * longer lengths are supported up to max_supported_msg_len. This is exposed |
| * to third party apps, and since we do not know their msg data formats we |
| * cannot fragment for them. Our own messages are allowed to be bigger and |
| * this HAL will fragment as needed. "Our own" messages are messaegs defined |
| * in this file. |
| */ |
| #define HUB_REQUIRED_SUPPORTED_MSG_LEN 128 |
| |
| struct hub_message_t { |
| const struct hub_app_name_t *app; /* 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 |
| |
| uint32_t max_supported_msg_len; |
| const struct hub_app_name_t *os_app_name; /* send msgs here for OS functions */ |
| }; |
| |
| /** |
| * 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, // 1: Enables the loaded nano-apps |
| CONTEXT_HUB_APPS_DISABLE, // 2: Disables any loaded nano-apps |
| 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 apps info on hub (gets struct hub_app_info[]) |
| CONTEXT_HUB_QUERY_MEMORY, // 5: Query for memory info (gets struct mem_range_t[]) |
| CONTEXT_HUB_LOAD_OS, // 6: Load up OS update |
| } hub_messages_e; |
| |
| #define CONTEXT_HUB_TYPE_PRIVATE_MSG_BASE 0x10000 |
| |
| |
| /** |
| * 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 |