Lines Matching refs:a
5 Compatibility is an important attribute of CHRE, which is accomplished through a
9 * **Code compatibility**, which means that a nanoapp can be recompiled to run on
10 a new platform without needing any code changes. CHRE provides this
11 cross-device compatibility for all nanoapps which are written in a supported
16 * **Binary compatibility**, which means that a nanoapp binary which has been
17 compiled against a particular version of the CHRE API can run on a CHRE
18 framework implementation which was compiled against a different version of the
20 *not* mean that a nanoapp compiled against one version of the CHRE API can be
21 compiled against a different version of the CHRE API without compiler errors -
31 The CHRE API is a native C API that defines the interface between a nanoapp and
39 incremented when new features and changes are introduced in a backwards
40 compatible way, and the major version is only incremented on a
59 introduction, for example as indicated by a capabilities flag (an exception
60 exists if it has no impact on the regular functionality of a nanoapp, for
61 example a feature that only aids in debugging)
63 * Fields within a structure must not be reordered - new fields may only be
65 a structure
66 * When reclaiming a reserved field, the default value of 0 must indicate a
68 * Arguments to a function must not be added or removed - introduce a new
75 This is where we want a nanoapp compiled against e.g. v1.2 to run on a CHRE v1.1
76 or older implementation. This is done through a combination of runtime feature
80 Runtime feature discovery involves a nanoapp querying for the support of a
82 for a specific sensor in `chreSensorFindDefault()`), which allows it determine
85 the platform it is running on. If a nanoapp has a hard requirement on some
89 However, a CHRE implementation cannot anticipate all future API changes and
90 automatically provide compatibility. So the NSL serves as a transparent shim
92 example, a nanoapp compiled against v1.2 must be able to reference and call
93 `chreConfigureHostSleepStateEvents()` when running on a CHRE v1.1 or earlier,
94 although such a function call would have no effect in that case. Typical dynamic
97 it in a condition that first checks the CHRE version. In
102 Along similar lines, if new fields are added to the end of a structure without
103 repurposing a reserved field in an update to the CHRE API, as was the case with
110 very slight), they can be disabled if it is known that a nanoapp will never run
111 on an older CHRE version. This may be the case for a nanoapp developed for a
114 introduced. For example, if a new hardware family first added support for the
119 all available versions. This means that if the first API supported by a target
120 device is v1.0, then a nanoapp compiled against API v1.4 must have NSL support
125 Conversely, this is where we want a nanoapp compiled against e.g. v1.1 to run
127 kind of compatibility, so it must be ensured through a combination of careful
130 Similar to how Android apps have a “target SDK” attribute, nanoapps have a
134 by the nanoapp with information about a given sensor. In CHRE API v1.1, this
135 structure was extended with a new field, `minInterval`. Therefore, the framework
139 To avoid carrying forward compatibility code indefinitely, it is permitted for a
141 API minor version that is 2 or more generations older. For example, a CHRE v1.4
142 implementation may reject attempts to load a nanoapp compiled against CHRE API
149 CHRE does not define a standard Application Binary Interface (ABI) - this is
150 left as a platform responsibility in order to provide maximum flexibility.
152 maintained with nanoapps, by choosing a design that provides this property. For
153 example, if a syscall-like approach is used (with the help of the NSL) to call
155 (e.g. in a statically linked monolithic firmware image), syscall IDs and their
166 at the same version except for limited periods during development. However, a
167 PAL implementation can simultaneously support multiple PAL API versions from a
173 In general, nanoapp compilation may be broken in a minor update (given
174 sufficient justification - this is not a light decision to make, considering the
175 downstream impact to nanoapp developers), but deprecation of functionality at a
176 binary level occurs over a minimum of 2 years (minor versions). The general
177 process for deprecating a function in the CHRE API is as follows:
179 * In a new minor version `N` of the CHRE API, the function is marked with
180 `@deprecated`, with a description of the recommended alternative, and ideally
184 * Depending on the severity of impact, the function may also be tagged with a
185 compiler attribute to generate a warning (e.g. `CHRE_DEPRECATED`) that may
188 them to update. If not considered a high severity issue and compatibility is
194 CHRE `N-1` or older, or a suitable alternative must be devised. Likewise,
208 For example, if a function is marked deprecated in `N`, and becomes a
209 compilation-breaking error in `N+2`, then a CHRE implementation at `N+4` may
210 remove the deprecated functionality only if it rejects a nanoapp built against
213 compatibility in a fragmented, unpredictable, or hidden way, for example by
214 replacing the deprecated function with a stub that does nothing. If it is
217 but otherwise this must be a blanket ban of all nanoapps compiled against the