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 _CHRE_VERSION_H_ 18 #define _CHRE_VERSION_H_ 19 20 /** 21 * @file 22 * Definitions and methods for the versioning of the Context Hub Runtime 23 * Environment. 24 * 25 * The CHRE API versioning pertains to all header files in the CHRE API. 26 */ 27 28 #include <stdint.h> 29 30 #ifdef __cplusplus 31 extern "C" { 32 #endif 33 34 /** 35 * Value for version 0.1 of the Context Hub Runtime Environment API interface. 36 * 37 * This is a legacy version of the CHRE API. Version 1.0 is considered the first 38 * official CHRE API version. 39 * 40 * @see CHRE_API_VERSION 41 */ 42 #define CHRE_API_VERSION_0_1 UINT32_C(0x00010000) 43 44 /** 45 * Value for version 1.0 of the Context Hub Runtime Environment API interface. 46 * 47 * This version of the CHRE API shipped with the Android Nougat release. 48 * 49 * @see CHRE_API_VERSION 50 */ 51 #define CHRE_API_VERSION_1_0 UINT32_C(0x01000000) 52 53 /** 54 * Value for version 1.1 of the Context Hub Runtime Environment API interface. 55 * 56 * This version of the CHRE API shipped with the Android O release. It adds 57 * initial support for new GNSS, WiFi, and WWAN modules. 58 * 59 * @see CHRE_API_VERSION 60 */ 61 #define CHRE_API_VERSION_1_1 UINT32_C(0x01010000) 62 63 /** 64 * Value for version 1.2 of the Context Hub Runtime Environment API interface. 65 * 66 * This version of the CHRE API shipped with the Android P release. It adds 67 * initial support for the new audio module. 68 * 69 * @see CHRE_API_VERSION 70 */ 71 #define CHRE_API_VERSION_1_2 UINT32_C(0x01020000) 72 73 /** 74 * Value for version 1.3 of the Context Hub Runtime Environment API interface. 75 * 76 * This version of the CHRE API shipped with the Android Q release. It adds 77 * support for GNSS location altitude/speed/bearing accuracy. It also adds step 78 * detect as a standard CHRE sensor and supports bias event delivery and sensor 79 * data flushing. 80 * 81 * @see CHRE_API_VERSION 82 */ 83 #define CHRE_API_VERSION_1_3 UINT32_C(0x01030000) 84 85 /** 86 * Value for version 1.4 of the Context Hub Runtime Environment API interface. 87 * 88 * This version of the CHRE API shipped with the Android R release. It adds 89 * support for collecting debug dump information from nanoapps, receiving L5 90 * GNSS measurements, determining if a sensor supports passive requests, 91 * receiving 5G cell info, and deprecates chreSendMessageToHost. 92 * 93 * @see CHRE_API_VERSION 94 */ 95 #define CHRE_API_VERSION_1_4 UINT32_C(0x01040000) 96 97 /** 98 * Value for version 1.5 of the Context Hub Runtime Environment API interface. 99 * 100 * This version of the CHRE API shipped with the Android S release. It adds 101 * support for multiple sensors of the same type, permissions for sensitive CHRE 102 * APIs / data usage, ability to receive user settings updates, step counter and 103 * hinge angle sensors, improved WiFi scan preferences to support power 104 * optimization, new WiFi security types, increased the lower bound for the 105 * maximum CHRE to host message size, and increased GNSS measurements in 106 * chreGnssDataEvent. 107 * 108 * @see CHRE_API_VERSION 109 */ 110 #define CHRE_API_VERSION_1_5 UINT32_C(0x01050000) 111 112 /** 113 * Value for version 1.6 of the Context Hub Runtime Environment API interface. 114 * 115 * This version of the CHRE API is shipped with the Android T release. It adds 116 * support for BLE scanning, subscribing to the WiFi NAN discovery engine, 117 * subscribing to host endpoint notifications, requesting metadata for a host 118 * endpoint ID, nanoapps publishing RPC services they support, and limits the 119 * nanoapp instance ID size to INT16_MAX. 120 * 121 * @see CHRE_API_VERSION 122 */ 123 #define CHRE_API_VERSION_1_6 UINT32_C(0x01060000) 124 125 /** 126 * Value for version 1.7 of the Context Hub Runtime Environment API interface. 127 * 128 * This version of the CHRE API is shipped with a post-launch update to the 129 * Android T release. It adds the BLE flush API. 130 * 131 * @see CHRE_API_VERSION 132 */ 133 #define CHRE_API_VERSION_1_7 UINT32_C(0x01070000) 134 135 /** 136 * Value for version 1.8 of the Context Hub Runtime Environment API interface. 137 * 138 * This version of the CHRE API is shipped with the Android U release. 139 * 140 * @note This version of the CHRE API has not been finalized yet, and is 141 * currently considered a preview that is subject to change. 142 * 143 * @see CHRE_API_VERSION 144 */ 145 #define CHRE_API_VERSION_1_8 UINT32_C(0x01080000) 146 147 /** 148 * Major and Minor Version of this Context Hub Runtime Environment API. 149 * 150 * The major version changes when there is an incompatible API change. 151 * 152 * The minor version changes when there is an addition in functionality 153 * in a backwards-compatible manner. 154 * 155 * We define the version number as an unsigned 32-bit value. The most 156 * significant byte is the Major Version. The second-most significant byte 157 * is the Minor Version. The two least significant bytes are the Patch 158 * Version. The Patch Version is not defined by this header API, but 159 * is provided by a specific CHRE implementation (see chreGetVersion()). 160 * 161 * Note that version numbers can always be numerically compared with 162 * expected results, so 1.0.0 < 1.0.4 < 1.1.0 < 2.0.300 < 3.5.0. 163 */ 164 #define CHRE_API_VERSION CHRE_API_VERSION_1_8 165 166 /** 167 * Utility macro to extract only the API major version of a composite CHRE 168 * version. 169 * 170 * @param version A uint32_t version, e.g. the value returned by 171 * chreGetApiVersion() 172 * 173 * @return The API major version in the least significant byte, e.g. 0x01 174 */ 175 #define CHRE_EXTRACT_MAJOR_VERSION(version) \ 176 (uint32_t)(((version) & UINT32_C(0xFF000000)) >> 24) 177 178 /** 179 * Utility macro to extract only the API minor version of a composite CHRE 180 * version. 181 * 182 * @param version A uint32_t version, e.g. the CHRE_API_VERSION constant 183 * 184 * @return The API minor version in the least significant byte, e.g. 0x01 185 */ 186 #define CHRE_EXTRACT_MINOR_VERSION(version) \ 187 (uint32_t)(((version) & UINT32_C(0x00FF0000)) >> 16) 188 189 /** 190 * Utility macro to extract only the API minor version of a composite CHRE 191 * version. 192 * 193 * @param version A complete uint32_t version, e.g. the value returned by 194 * chreGetVersion() 195 * 196 * @return The implementation patch version in the least significant two bytes, 197 * e.g. 0x0123, with all other bytes set to 0 198 */ 199 #define CHRE_EXTRACT_PATCH_VERSION(version) (uint32_t)((version) & UINT32_C(0xFFFF)) 200 201 /** 202 * Get the API version the CHRE implementation was compiled against. 203 * 204 * This is not necessarily the CHRE_API_VERSION in the header the nanoapp was 205 * built against, and indeed may not have even appeared in the context_hub_os.h 206 * header which this nanoapp was built against. 207 * 208 * By definition, this will have the two least significant bytes set to 0, 209 * and only contain the major and minor version number. 210 * 211 * @return The API version. 212 */ 213 uint32_t chreGetApiVersion(void); 214 215 /** 216 * Get the version of this CHRE implementation. 217 * 218 * By definition, ((chreGetApiVersion() & UINT32_C(0xFFFF0000)) == 219 * (chreGetVersion() & UINT32_C(0xFFFF0000))). 220 * 221 * The Patch Version, in the lower two bytes, only have meaning in context 222 * of this specific platform ID. It is increased by the platform every time 223 * a backwards-compatible bug fix is released. 224 * 225 * @return The version. 226 * 227 * @see chreGetPlatformId() 228 */ 229 uint32_t chreGetVersion(void); 230 231 /** 232 * Get the Platform ID of this CHRE. 233 * 234 * The most significant five bytes are the vendor ID as set out by the 235 * NANOAPP_VENDOR convention in the original context hub HAL header file 236 * (context_hub.h), also used by nanoapp IDs. 237 * 238 * The least significant three bytes are set by the vendor, but must be 239 * unique for each different CHRE implementation/hardware that the vendor 240 * supplies. 241 * 242 * The idea is that in the case of known bugs in the field, a new nanoapp could 243 * be shipped with a workaround that would use this value, and chreGetVersion(), 244 * to have code that can conditionally work around the bug on a buggy version. 245 * Thus, we require this uniqueness to allow such a setup to work. 246 * 247 * @return The platform ID. 248 * 249 * @see CHRE_EXTRACT_VENDOR_ID 250 */ 251 uint64_t chreGetPlatformId(void); 252 253 #ifdef __cplusplus 254 } 255 #endif 256 257 #endif /* _CHRE_VERSION_H_ */ 258