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