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 * Definitions and methods for the versioning of the Context Hub Runtime 22 * Environment. 23 * 24 * The CHRE API versioning pertains to all the chre_*.h files and chre.h. 25 */ 26 27 28 #include <stdint.h> 29 30 #ifdef __cplusplus 31 extern "C" { 32 #endif 33 34 35 /** 36 * Value for version 0.1 of the Context Hub Runtime Environment API interface. 37 * 38 * This is a legacy version. Version 1.0 is considered the first official 39 * version of the API. 40 * 41 * @see CHRE_API_VERSION 42 */ 43 #define CHRE_API_VERSION_0_1 UINT32_C(0x00010000) 44 45 /** 46 * Value for version 1.0 of the Context Hub Runtime Environment API interface. 47 * 48 * The version of the CHRE API which shipped with the Android Nougat release. 49 * 50 * @see CHRE_API_VERSION 51 */ 52 #define CHRE_API_VERSION_1_0 UINT32_C(0x01000000) 53 54 /** 55 * Major and Minor Version of this Context Hub Runtime Environment API. 56 * 57 * The major version changes when there is an incompatible API change. 58 * 59 * The minor version changes when there is an addition in functionality 60 * in a backwards-compatible manner. 61 * 62 * We define the version number as an unsigned 32-bit value. The most 63 * significant byte is the Major Version. The second-most significant byte 64 * is the Minor Version. The two least significant bytes are the Patch 65 * Version. The Patch Version is not defined by this header API, but 66 * is provided by a specific CHRE implementation (see chreGetVersion()). 67 * 68 * Note that version numbers can always be numerically compared with 69 * expected results, so 1.0.0 < 1.0.4 < 1.1.0 < 2.0.300 < 3.5.0. 70 */ 71 #define CHRE_API_VERSION CHRE_API_VERSION_1_0 72 73 74 /** 75 * Get the API version the CHRE implementation was compiled against. 76 * 77 * This is not necessarily the CHRE_API_VERSION in the header the nanoapp was 78 * built against, and indeed may not have even appeared in the context_hub_os.h 79 * header which this nanoapp was built against. 80 * 81 * By definition, this will have the two least significant bytes set to 0, 82 * and only contain the major and minor version number. 83 * 84 * @returns The API version. 85 */ 86 uint32_t chreGetApiVersion(void); 87 88 /** 89 * Get the version of this CHRE implementation. 90 * 91 * By definition, ((chreGetApiVersion() & UINT32_C(0xFFFF0000)) == 92 * (chreGetVersion() & UINT32_C(0xFFFF0000))). 93 * 94 * The Patch Version, in the lower two bytes, only have meaning in context 95 * of this specific platform ID. It is increased by the platform every time 96 * a backwards-compatible bug fix is released. 97 * 98 * @returns The version. 99 * 100 * @see chreGetPlatformId() 101 */ 102 uint32_t chreGetVersion(void); 103 104 /** 105 * Get the Platform ID of this CHRE. 106 * 107 * The most significant five bytes are the vendor ID as set out by the 108 * NANOAPP_VENDOR convention in context_hub.h, as used by nanoapp IDs. 109 * 110 * The least significant three bytes are set by the vendor, but must be 111 * unique for each different CHRE implementation/hardware that the vendor 112 * supplies. 113 * 114 * The idea is that in the case of known bugs in the field, a new nanoapp could 115 * be shipped with a workaround that would use this value, and chreGetVersion(), 116 * to have code that can conditionally work around the bug on a buggy version. 117 * Thus, we require this uniqueness to allow such a setup to work. 118 * 119 * @returns The platform ID. 120 */ 121 uint64_t chreGetPlatformId(void); 122 123 124 #ifdef __cplusplus 125 } 126 #endif 127 128 #endif /* _CHRE_VERSION_H_ */ 129 130