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