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. Version 1.0 is considered the first official 38 * version of the API. 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 * The version of the CHRE API which 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 * The 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 * Major and Minor Version of this Context Hub Runtime Environment API. 65 * 66 * The major version changes when there is an incompatible API change. 67 * 68 * The minor version changes when there is an addition in functionality 69 * in a backwards-compatible manner. 70 * 71 * We define the version number as an unsigned 32-bit value. The most 72 * significant byte is the Major Version. The second-most significant byte 73 * is the Minor Version. The two least significant bytes are the Patch 74 * Version. The Patch Version is not defined by this header API, but 75 * is provided by a specific CHRE implementation (see chreGetVersion()). 76 * 77 * Note that version numbers can always be numerically compared with 78 * expected results, so 1.0.0 < 1.0.4 < 1.1.0 < 2.0.300 < 3.5.0. 79 */ 80 #define CHRE_API_VERSION CHRE_API_VERSION_1_1 81 82 /** 83 * Utility macro to extract only the API major version of a composite CHRE 84 * version. 85 * 86 * @param version A uint32_t version, e.g. the value returned by 87 * chreGetApiVersion() 88 * 89 * @returns The API major version in the least significant byte, e.g. 0x01 90 */ 91 #define CHRE_EXTRACT_MAJOR_VERSION(version) \ 92 (((version) & UINT32_C(0xFF000000)) >> 24) 93 94 /** 95 * Utility macro to extract only the API minor version of a composite CHRE 96 * version. 97 * 98 * @param version A uint32_t version, e.g. the CHRE_API_VERSION constant 99 * 100 * @returns The API minor version in the least significant byte, e.g. 0x01 101 */ 102 #define CHRE_EXTRACT_MINOR_VERSION(version) \ 103 (((version) & UINT32_C(0x00FF0000)) >> 16) 104 105 /** 106 * Utility macro to extract only the API minor version of a composite CHRE 107 * version. 108 * 109 * @param version A complete uint32_t version, e.g. the value returned by 110 * chreGetVersion() 111 * 112 * @returns The implementation patch version in the least significant two bytes, 113 * e.g. 0x0123, with all other bytes set to 0 114 */ 115 #define CHRE_EXTRACT_PATCH_VERSION(version) ((version) & UINT32_C(0xFFFF)) 116 117 118 /** 119 * Get the API version the CHRE implementation was compiled against. 120 * 121 * This is not necessarily the CHRE_API_VERSION in the header the nanoapp was 122 * built against, and indeed may not have even appeared in the context_hub_os.h 123 * header which this nanoapp was built against. 124 * 125 * By definition, this will have the two least significant bytes set to 0, 126 * and only contain the major and minor version number. 127 * 128 * @returns The API version. 129 */ 130 uint32_t chreGetApiVersion(void); 131 132 /** 133 * Get the version of this CHRE implementation. 134 * 135 * By definition, ((chreGetApiVersion() & UINT32_C(0xFFFF0000)) == 136 * (chreGetVersion() & UINT32_C(0xFFFF0000))). 137 * 138 * The Patch Version, in the lower two bytes, only have meaning in context 139 * of this specific platform ID. It is increased by the platform every time 140 * a backwards-compatible bug fix is released. 141 * 142 * @returns The version. 143 * 144 * @see chreGetPlatformId() 145 */ 146 uint32_t chreGetVersion(void); 147 148 /** 149 * Get the Platform ID of this CHRE. 150 * 151 * The most significant five bytes are the vendor ID as set out by the 152 * NANOAPP_VENDOR convention in the original context hub HAL header file 153 * (context_hub.h), also used by nanoapp IDs. 154 * 155 * The least significant three bytes are set by the vendor, but must be 156 * unique for each different CHRE implementation/hardware that the vendor 157 * supplies. 158 * 159 * The idea is that in the case of known bugs in the field, a new nanoapp could 160 * be shipped with a workaround that would use this value, and chreGetVersion(), 161 * to have code that can conditionally work around the bug on a buggy version. 162 * Thus, we require this uniqueness to allow such a setup to work. 163 * 164 * @returns The platform ID. 165 * 166 * @see CHRE_EXTRACT_VENDOR_ID 167 */ 168 uint64_t chreGetPlatformId(void); 169 170 171 #ifdef __cplusplus 172 } 173 #endif 174 175 #endif /* _CHRE_VERSION_H_ */ 176 177