|
|
# Extending CHRE with Vendor-specific Functionality
|
|
|
|
|
|
[TOC]
|
|
|
|
|
|
The CHRE framework is easily extensible with no modifications to the core
|
|
|
framework. Depending on the goals of the new API, one or more of the following
|
|
|
steps must be performed. At a high-level, to add a new vendor-specific API to
|
|
|
CHRE, one must:
|
|
|
|
|
|
1. Define new APIs in a header that can be referenced by both platform CHRE
|
|
|
framework code and vendor-specific nanoapps.
|
|
|
|
|
|
2. Expose the new APIs from the framework to nanoapps, and connect them to a new
|
|
|
module to provide the desired functionality
|
|
|
|
|
|
3. Integrate the new module with existing CHRE framework features, e.g. the
|
|
|
event subsystem, to provide complete functionality that fits within the
|
|
|
existing CHRE conventions
|
|
|
|
|
|
It's best to refer to existing standard CHRE API feature areas, such as
|
|
|
`chre/wifi.h` and `WifiRequestManager`, and follow a similar design where
|
|
|
possible.
|
|
|
|
|
|
## Defining the API
|
|
|
|
|
|
To prevent collision with future common CHRE API definitions, vendor extensions
|
|
|
must not use the plain ‘chre’ prefix followed by a capitalized letter. Instead,
|
|
|
it’s recommended to prefix the APIs with the vendor’s name as lowercase. For
|
|
|
example, if your company name is XYZ Semiconductor and you’re defining a new
|
|
|
‘widget’ API, it’s recommended to use a naming scheme like
|
|
|
`chrexyzWidget<FunctionName>()`, and included indirectly via `#include
|
|
|
<chre_xyz.h>` or directly via `<chre_xyz/widget.h>`. The equivalent C++
|
|
|
namespace would be `::chre::xyz`.
|
|
|
|
|
|
There are reserved ranges for vendor/implementation-specific event types
|
|
|
(starting from `CHRE_EVENT_INTERNAL_EXTENDED_FIRST_EVENT`), and other cases
|
|
|
where vendors may wish or need to define a custom value in an existing field. To
|
|
|
prevent collision with future versions of the CHRE API, vendor extensions must
|
|
|
only use values within vendor-reserved ranges. If you would like to add a new
|
|
|
value to an existing field for a vendor extension and a vendor-reserved range
|
|
|
does not already exist, please reach out to the CHRE team for guidance -
|
|
|
solutions may involve creating a new reserved range in the common CHRE API, or
|
|
|
providing advice on a different method of defining the API.
|
|
|
|
|
|
Vendors can only add on to the CHRE API - existing APIs must not be changed. Do
|
|
|
not modify core CHRE definitions, for example by adding on fields to common
|
|
|
structures, re-using event types, repurposing fields that are reserved for
|
|
|
future use, etc.
|
|
|
|
|
|
It’s recommended that any vendor extensions consider compatibility when
|
|
|
designing it - see the Compatibility section for API design guidelines.
|
|
|
|
|
|
If this API is intended to be open-sourced, it should be added to
|
|
|
`platform/<platform_name>/extensions/include`. Otherwise, it’s suggested that
|
|
|
the API be placed outside of the CHRE tree, in a separate Git project under
|
|
|
`vendor/` in the Android tree, to avoid potential conflicts when upgrading to a
|
|
|
new version of CHRE.
|
|
|
|
|
|
### Build Customization
|
|
|
|
|
|
As part of the CHRE framework build system, the `CHRE_VARIANT_MK_INCLUDES`
|
|
|
environment variable can be used to inject an external `.mk` file into the
|
|
|
top-level build without any source code changes in the system/chre project.
|
|
|
Alternatively, if open sourcing, the `platform.mk` file should contain the
|
|
|
additions needed to support the new vendor API. Refer to the CHRE framework
|
|
|
build documentation for further details.
|
|
|
|
|
|
To expose the new functionality to nanoapps, it’s recommended to create a single
|
|
|
`.mk` file that adds the necessary `COMMON_CFLAGS` entries (and potentially
|
|
|
other build configuration). For example, create a `chrexyz.mk` file which
|
|
|
nanoapps should include in their Makefile prior to including
|
|
|
`$(CHRE_PREFIX)/build/nanoapp/app.mk`.
|
|
|
|
|
|
## Threading Model
|
|
|
|
|
|
Interactions with a nanoapp always happen from within the CHRE thread that runs
|
|
|
the EventLoop, so vendor extension code does not need to worry about race
|
|
|
conditions due to multiple nanoapps calling into APIs, and likewise nanoapps do
|
|
|
not need to worry about race conditions in its callbacks/handlers. However, it
|
|
|
is common for a platform module to receive data in a callback on another thread.
|
|
|
In that case, it is recommended to use `EventLoopManager::deferCallback()` to
|
|
|
pass the incoming data to the CHRE thread for processing, as opposed to using
|
|
|
mutexes or other synchronization primitives, to avoid multithreading-related
|
|
|
issues that can arise in rare conditions. Further, note that most of the core
|
|
|
CHRE functionality is only safe to call from within the CHRE thread (other than
|
|
|
posting an event, or methods that are explicitly marked as thread-safe).
|
|
|
|
|
|
## Initialization
|
|
|
|
|
|
Since the new API will not be part of the core framework, it won’t be attached
|
|
|
to `EventLoopManager` or initialized as part of `chre::init()` or
|
|
|
`EventLoopManagerSingleton::get()->lateInit()`, since vendor-extension APIs are
|
|
|
by definition not part of the common code. Instead, a separate singleton object
|
|
|
should be created, for example `chre::xyz::VendorExtensionManager`, and
|
|
|
platform-specific initialization code should invoke any necessary initialization
|
|
|
**after** `chre::init` is called, but **before** loading any static nanoapps or
|
|
|
invoking `EventLoop::run()` to ensure that nanoapps don’t begin interacting with
|
|
|
the API before its state is ready.
|
|
|
|
|
|
## Handling Nanoapp API Calls
|
|
|
|
|
|
Calls from a nanoapp into the CHRE framework first arrive in platform-specific
|
|
|
code (refer to the Framework Overview documentation for details). The first step
|
|
|
once an API call reaches the framework is usually to call
|
|
|
`EventLoopManager::validateChreApiCall(__func__)`. This fetches a pointer to the
|
|
|
`Nanoapp` object associated with the nanoapp that invoked the API, which will
|
|
|
fail if the API is called outside of the EventLoop thread context (see the
|
|
|
Threading Model above). From this point, the vendor extension singleton should
|
|
|
be used to invoke the appropriate functionality.
|
|
|
|
|
|
## Sending Events to Nanoapps
|
|
|
|
|
|
Vendor extension APIs that need to pass data to a nanoapp asynchronously should
|
|
|
use the event susbsystem, using the vendor-reserved event type range (starting
|
|
|
at `CHRE_EVENT_INTERNAL_EXTENDED_FIRST_EVENT` and extending to
|
|
|
`CHRE_EVENT_INTERNAL_LAST_EVENT`). Event types for a given vendor extension
|
|
|
should be globally unique and stable over time.
|
|
|
|
|
|
Synchronous API calls that can potentially block for periods greater than a few
|
|
|
milliseconds are discouraged, as these can prevent other nanoapps from
|
|
|
executing, and/or cause the pending event queue to grow excessively during
|
|
|
periods of high activity. Refer to the GNSS and WWAN APIs for design patterns
|
|
|
related to passing data to a nanoapp asynchronously, using custom event payloads
|
|
|
and/or `chreAsyncResult`.
|
|
|
|
|
|
Events can either be unicast to a nanoapp identified by its instance ID
|
|
|
(`Nanoapp::getInstanceId()`), or broadcast to all nanoapps registered for the
|
|
|
given event type - see `Nanoapp::registerForBroadcastEvent()` and
|
|
|
`Nanoapp::unregisterForBroadcastEvent()`.
|
|
|
|
|
|
Use `EventLoop::postEventOrDie()` or `EventLoop::postLowPriorityEventOrFree()`
|
|
|
(via `EventLoopManagerSingleton::get()->getEventLoop()`) to pass events to
|
|
|
nanoapps, depending on what error handling is desired in the case that the event
|
|
|
cannot be posted to the queue. Any memory referenced by `eventData` must not be
|
|
|
modified until `freeCallback` is invoked.
|
