|
|
# Design for Compatibility
|
|
|
|
|
|
[TOC]
|
|
|
|
|
|
Compatibility is an important attribute of CHRE, which is accomplished through a
|
|
|
combination of thoughtful API and framework design. When we refer to
|
|
|
compatibility within the scope of CHRE, there are two main categories:
|
|
|
|
|
|
* **Code compatibility**, which means that a nanoapp can be recompiled to run on
|
|
|
a new platform without needing any code changes. CHRE provides this
|
|
|
cross-device compatibility for all nanoapps which are written in a supported
|
|
|
programming language (C99 or C++11), and reference only the standard CHRE APIs
|
|
|
and mandatory standard library elements (or have these standard library
|
|
|
functions statically linked into their binary).
|
|
|
|
|
|
* **Binary compatibility**, which means that a nanoapp binary which has been
|
|
|
compiled against a particular version of the CHRE API can run on a CHRE
|
|
|
framework implementation which was compiled against a different version of the
|
|
|
API. This is also called *cross-version compatibility*. Note that this does
|
|
|
*not* mean that a nanoapp compiled against one version of the CHRE API can be
|
|
|
compiled against a different version of the CHRE API without compiler errors -
|
|
|
although rare, compile-time breakages are permitted with sufficient
|
|
|
justification, since nanoapp developers can update their code at the time they
|
|
|
migrate to the new API version.
|
|
|
|
|
|
This section provides an overview of the mechanisms used to ensure
|
|
|
compatibility.
|
|
|
|
|
|
## CHRE API
|
|
|
|
|
|
The CHRE API is a native C API that defines the interface between a nanoapp and
|
|
|
any underlying CHRE implementation to provide cross-platform and cross-version
|
|
|
compatibility. It is designed to be supportable even in very memory-constrained
|
|
|
environments (total system memory in the hundreds of kilobytes range), and is
|
|
|
thoroughly documented to clearly indicate the intended behavior.
|
|
|
|
|
|
The CHRE API follows [semantic versioning](https://semver.org) principles to
|
|
|
maintain binary compatibility. In short, this means that the minor version is
|
|
|
incremented when new features and changes are introduced in a backwards
|
|
|
compatible way, and the major version is only incremented on a
|
|
|
compatibility-breaking change. One key design goal of the CHRE API is to avoid
|
|
|
major version changes if at all possible, through use of
|
|
|
compatibility-preserving code in the framework and Nanoapp Support Library
|
|
|
(NSL).
|
|
|
|
|
|
Minor version updates to the CHRE API typically occur alongside each Android
|
|
|
release, but the CHRE version and Android version are not intrinsically related.
|
|
|
Nanoapps should be compiled against the latest version to be able to use any
|
|
|
newly added features, though nanoapp binaries are compatible across minor
|
|
|
version changes.
|
|
|
|
|
|
### API Compatibility Design Principles
|
|
|
|
|
|
API design principles applied within CHRE to ensure compatibility include the
|
|
|
following (not an exhaustive list). These are recommended to be followed for any
|
|
|
vendor-specific API extensions as well.
|
|
|
|
|
|
* Functionality must not be removed unless it was optional at the time of
|
|
|
introduction, for example as indicated by a capabilities flag (an exception
|
|
|
exists if it has no impact on the regular functionality of a nanoapp, for
|
|
|
example a feature that only aids in debugging)
|
|
|
* Reserved fields must be set to 0 by the sender and ignored by the recipient
|
|
|
* Fields within a structure must not be reordered - new fields may only be
|
|
|
introduced by reclaiming reserved fields (preferred), or adding to the end of
|
|
|
a structure
|
|
|
* When reclaiming a reserved field, the default value of 0 must indicate a
|
|
|
property that is guaranteed to hold for previous API versions, or “unknown”
|
|
|
* Arguments to a function must not be added or removed - introduce a new
|
|
|
function instead
|
|
|
* The meaning of constants (e.g. event types) must never be changed, but may be
|
|
|
deprecated and eventually replaced
|
|
|
|
|
|
## Binary Backward Compatibility and the NSL
|
|
|
|
|
|
This is where we want a nanoapp compiled against e.g. v1.2 to run on a CHRE v1.1
|
|
|
or older implementation. This is done through a combination of runtime feature
|
|
|
discovery, and compatibility behaviors included in the Nanoapp Support Library
|
|
|
(NSL).
|
|
|
|
|
|
Runtime feature discovery involves a nanoapp querying for the support of a
|
|
|
feature (e.g. RTT support indicated in `chreWifiGetCapabilities()`, or querying
|
|
|
for a specific sensor in `chreSensorFindDefault()`), which allows it determine
|
|
|
whether the associated functionality is expected to work. The nanoapp may also
|
|
|
query `chreGetApiVersion()` to find out the version of the CHRE API supported by
|
|
|
the platform it is running on. If a nanoapp has a hard requirement on some
|
|
|
missing functionality, it may choose to return false from `nanoappStart()` to
|
|
|
abort initialization.
|
|
|
|
|
|
However, a CHRE implementation cannot anticipate all future API changes and
|
|
|
automatically provide compatibility. So the NSL serves as a transparent shim
|
|
|
which is compiled into the nanoapp binary to ensure this compatibility. For
|
|
|
example, a nanoapp compiled against v1.2 must be able to reference and call
|
|
|
`chreConfigureHostSleepStateEvents()` when running on a CHRE v1.1 or earlier,
|
|
|
although such a function call would have no effect in that case. Typical dynamic
|
|
|
linking approaches would find an unsatisfied dependency and fail to load the
|
|
|
nanoapp, even if it does not actually call the function, for example by wrapping
|
|
|
it in a condition that first checks the CHRE version. In
|
|
|
`platform/shared/nanoapp/nanoapp_support_lib_dso.cc`, this is supported by
|
|
|
intercepting CHRE API function calls and either calling through to the
|
|
|
underlying platform if it’s supported, or replacing it with stub functionality.
|
|
|
|
|
|
Along similar lines, if new fields are added to the end of a structure without
|
|
|
repurposing a reserved field in an update to the CHRE API, as was the case with
|
|
|
`bearing_accuracy` in `chreGnssLocationEvent`, the nanoapp must be able to
|
|
|
reference the new field without reading uninitialized memory. This is enabled by
|
|
|
the NSL, which can intercept the event, and copy it into the new, larger
|
|
|
structure, and set the new fields to their default values.
|
|
|
|
|
|
Since these NSL compatibility behaviors carry some amount of overhead (even if
|
|
|
very slight), they can be disabled if it is known that a nanoapp will never run
|
|
|
on an older CHRE version. This may be the case for a nanoapp developed for a
|
|
|
specific device, for example. The NSL may also limit its compatibility range
|
|
|
based on knowledge of the API version at which support for given hardware was
|
|
|
introduced. For example, if a new hardware family first added support for the
|
|
|
CHRE framework at API v1.1, then NSL support for v1.0 is unnecessary.
|
|
|
|
|
|
Outside of these cases, the NSL must provide backwards compatibility for at
|
|
|
least 3 previous versions, and is strongly recommended to provide support for
|
|
|
all available versions. This means that if the first API supported by a target
|
|
|
device is v1.0, then a nanoapp compiled against API v1.4 must have NSL support
|
|
|
for v1.1 through v1.4, and should ideally also support v1.0.
|
|
|
|
|
|
## Binary Forward Compatibility and Framework Requirements
|
|
|
|
|
|
Conversely, this is where we want a nanoapp compiled against e.g. v1.1 to run
|
|
|
against CHRE v1.2 or later implementations. The NSL cannot directly provide this
|
|
|
kind of compatibility, so it must be ensured through a combination of careful
|
|
|
CHRE API design, and compatibility behaviors in the CHRE framework.
|
|
|
|
|
|
Similar to how Android apps have a “target SDK” attribute, nanoapps have a
|
|
|
“target API version” which indicates the version of the CHRE API they were
|
|
|
compiled against. The framework can inspect this value and provide compatibility
|
|
|
behavior as needed. For example, `chreGetSensorInfo()` populates memory provided
|
|
|
by the nanoapp with information about a given sensor. In CHRE API v1.1, this
|
|
|
structure was extended with a new field, `minInterval`. Therefore, the framework
|
|
|
must check if the nanoapp’s target API is v1.1 or later before writing this
|
|
|
field.
|
|
|
|
|
|
To avoid carrying forward compatibility code indefinitely, it is permitted for a
|
|
|
CHRE implementation to reject compatibility with nanoapps compiled against an
|
|
|
API minor version that is 2 or more generations older. For example, a CHRE v1.4
|
|
|
implementation may reject attempts to load a nanoapp compiled against CHRE API
|
|
|
v1.2, but it must ensure compatibility with v1.3. However, providing the full
|
|
|
range of compatibility generally does not require significant effort on behalf
|
|
|
of the CHRE implementation, so this is recommended for maximum flexibility.
|
|
|
|
|
|
## ABI Stability
|
|
|
|
|
|
CHRE does not define a standard Application Binary Interface (ABI) - this is
|
|
|
left as a platform responsibility in order to provide maximum flexibility.
|
|
|
However, CHRE implementations must ensure that binary compatibility is
|
|
|
maintained with nanoapps, by choosing a design that provides this property. For
|
|
|
example, if a syscall-like approach is used (with the help of the NSL) to call
|
|
|
from position-independent nanoapp code into fixed-position CHRE API functions
|
|
|
(e.g. in a statically linked monolithic firmware image), syscall IDs and their
|
|
|
calling conventions must remain stable. It is not acceptable to require all
|
|
|
nanoapps to be recompiled to be able to work with an updated CHRE
|
|
|
implementation.
|
|
|
|
|
|
## CHRE PALs
|
|
|
|
|
|
Since the PAL APIs are largely based on the CHRE APIs, they benefit from many of
|
|
|
the compatibility efforts by default. Overall, binary compatibility in the CHRE
|
|
|
PAL APIs are less involved than the CHRE APIs, because we expect CHRE and CHRE
|
|
|
PAL implementations to be built into the vendor image together, and usually run
|
|
|
at the same version except for limited periods during development. However, a
|
|
|
PAL implementation can simultaneously support multiple PAL API versions from a
|
|
|
single codebase by adapting its behavior based on the `requestedApiVersion`
|
|
|
parameter in the \*GetApi method, e.g. `chrePalWifiGetApi()`.
|
|
|
|
|
|
## Deprecation Strategy
|
|
|
|
|
|
In general, nanoapp compilation may be broken in a minor update (given
|
|
|
sufficient justification - this is not a light decision to make, considering the
|
|
|
downstream impact to nanoapp developers), but deprecation of functionality at a
|
|
|
binary level occurs over a minimum of 2 years (minor versions). The general
|
|
|
process for deprecating a function in the CHRE API is as follows:
|
|
|
|
|
|
* In a new minor version `N` of the CHRE API, the function is marked with
|
|
|
`@deprecated`, with a description of the recommended alternative, and ideally
|
|
|
the justification for the deprecation, so nanoapp developers know why it's
|
|
|
important to update.
|
|
|
|
|
|
* Depending on the severity of impact, the function may also be tagged with a
|
|
|
compiler attribute to generate a warning (e.g. `CHRE_DEPRECATED`) that may
|
|
|
be ignored. Or, version `N` or later, an attribute or other method may be
|
|
|
used to break compilation of nanoapps using the deprecated function, forcing
|
|
|
them to update. If not considered a high severity issue and compatibility is
|
|
|
easy to maintain, it is recommended to break compilation only in version
|
|
|
`N+2` or later.
|
|
|
|
|
|
* Binary compatibility at this stage must be maintained. For example the NSL
|
|
|
should map the new functionality to the deprecated function when running on
|
|
|
CHRE `N-1` or older, or a suitable alternative must be devised. Likewise,
|
|
|
CHRE must continue to provide the deprecated function to support nanoapps
|
|
|
built against `N-1`.
|
|
|
|
|
|
* Impacts to binary compatibility on the CHRE side may occur 2 versions after
|
|
|
the function is made compilation-breaking for nanoapps, since forward
|
|
|
compatibility is guaranteed for 2 minor versions. If done, the nanoapp must be
|
|
|
rejected at load time.
|
|
|
|
|
|
* Impacts to binary compatibility on the nanoapp side may occur 4 versions after
|
|
|
the function is marked deprecated (at `N+4`), since backward compatibility is
|
|
|
guaranteed for 4 minor versions. If done, the NSL must cause `nanoappStart()`
|
|
|
to return false on version `N` or older.
|
|
|
|
|
|
For example, if a function is marked deprecated in `N`, and becomes a
|
|
|
compilation-breaking error in `N+2`, then a CHRE implementation at `N+4` may
|
|
|
remove the deprecated functionality only if it rejects a nanoapp built against
|
|
|
`N+1` or older at load time. Likewise, the NSL can remove compatibility code for
|
|
|
the deprecated function at `N+4`. CHRE and NSL implementations must not break
|
|
|
compatibility in a fragmented, unpredictable, or hidden way, for example by
|
|
|
replacing the deprecated function with a stub that does nothing. If it is
|
|
|
possible for CHRE and/or the NSL to detect only nanoapps that use the deprecated
|
|
|
functionality, then it is permissible to block loading of only those nanoapps,
|
|
|
but otherwise this must be a blanket ban of all nanoapps compiled against the
|
|
|
old API version.
|
