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
31extern "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 */
86uint32_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 */
102uint32_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 */
121uint64_t chreGetPlatformId(void);
122
123
124#ifdef __cplusplus
125}
126#endif
127
128#endif  /* _CHRE_VERSION_H_ */
129
130