*** aside See also: [Nanoapp Developer Guide](/doc/nanoapp_developer_guide.md) | [Interacting with Nanoapps](/doc/nanoapp_clients.md) *** # Nanoapp Overview [TOC] Nanoapps are applications written in C or C++ which run in CHRE, to leverage low-power hardware. Typically, nanoapps integrate with a component on the Android side, such as a privileged APK, in order to provide complete end-to-end functionality of the target feature. This Android-side component is referred to as the nanoapp’s “client”. Since nanoapps are not limited to the same power constraints that Android apps are, they can process inputs, like sensor data, much more frequently while the device’s screen is off. Nanoapps are abstracted from the underlying platform details by the CHRE API, which is standardized across all CHRE implementations. This means that a nanoapp is *code compatible* across devices - its source code does not need to be changed to run on different hardware, but it *may* need to be recompiled. The CHRE API also provides binary compatibility guarantees across minor versions, so a nanoapp does not need to be recompiled to run on a device that exposes a newer or older version of the CHRE API. These properties help provide for the maximum reuse of code across devices. Due to system security and resource constraints of the platforms that CHRE targets, only device OEMs and their trusted partners are able to create nanoapps. In other words, the system only runs nanoapps that possess a digital signature that is trusted in advance by the device manufacturer, and APKs must hold a special privileged/same-signature permission (`ACCESS_CONTEXT_HUB`) to be able to interact with nanoapps and the Context Hub in general. However, this does not mean that third-party APKs cannot benefit from CHRE - nanoapps can be used to power APIs available for use by any Android app. ## Methods for Loading a Nanoapp While nanoapps are nominally dynamically loadable modules, they can be loaded into a device through a few methods, each of which has pros and cons elaborated below. ### Static Nanoapps Static nanoapps are, as the name suggests, statically compiled into the CHRE framework binary. Static nanoapps are automatically initialized after the CHRE framework completes its initialization during the boot process. Static nanoapps typically aren’t used in production, because this monolithic approach has downsides in terms of version control, updatability, etc., but it can be useful during CHRE development and bring-up of new devices, especially before dynamic loading functionality is enabled. For example, the FeatureWorld nanoapps (described later) are typically built as static nanoapps. Static nanoapps are typically unconditionally compiled as part of the framework build (via `apps/apps.mk`), but then stripped out by the linker if unreferenced (using the `--gc-sections` option, or equivalent). Static nanoapps are referenced only if their initialization function appears in the `kStaticNanoappList` array, which by default is empty, but can be overridden by the device variant makefile, as in `variant/simulator/` for example. Some boilerplate is needed to enable nanoapp to be built as a static nanoapp - see the code wrapped in `#ifdef CHRE_NANOAPP_INTERNAL` in `apps/hello_world/hello_world.cc`. ### Preloaded Nanoapps Preloaded nanoapps are built as a separate binary from the CHRE framework, but included in the vendor partition of an overall device image (hence they are “preloaded” onto the device). The binaries associated with a preloaded nanoapp (usually a `.so` and a `.napp_header` file) are checked in to the Android tree as a “prebuilt” binary, and integrated into the Android build system so as to appear in the resulting device image, for example using `$(BUILD_PREBUILT)` in Android.mk, or `prebuilt_dsp` or `prebuilt_firmware` in Android.bp. While the mechanism for loading prebuilt nanoapps is platform-specific, the CHRE framework generally follows these steps at boot time: 1. When CHRE starts up, the CHRE daemon process running on the AP reads the configuration file `/vendor/etc/chre/preloaded_nanoapps.json`, which contains the list of nanoapps that should be automatically loaded. 2. For each nanoapp in the JSON file, the CHRE daemon reads the `.napp_header` from storage, and sends a message to CHRE requesting it to load the nanoapp. 3. The platform layer of the CHRE framework handles the requests by loading, authenticating, linking, and starting the nanoapp. 4. CHRE initialization proceeds (it is important for all preloaded nanoapps to be included at the first moment list query command can be processed, to avoid race conditions leading to clients believing that a preloaded nanoapp is missing). This path is most commonly used to deploy nanoapps to production, as the entire device software can be validated together without external dependencies, while also preserving the ability to update nanoapps independent from other components in the system. ### Fully Dynamic Nanoapps At the binary level, a preloaded nanoapp and fully dynamic nanoapp are identical. The key difference is where they are stored and how they are initially loaded into CHRE, and potentially how metadata is handled. In most cases, preloaded nanoapps will use a separate `.napp_header` file with metadata and `.so` file for the actual binary, a fully dynamic nanoapp has the header prepended to the binary, and carries the `.napp` file type suffix. In other words, the command `cat my_nanoapp.napp_header my_nanoapp.so > my_nanoapp.napp` can be used to create a fully dynamic nanoapp file from these components. Instead of being stored on the device filesystem, fully dynamic nanoapps can be loaded at any time after initialization using the `ContextHubManager.loadNanoApp()` Java API. This allows nanoapps to be updated/delivered by an APK, outside of a full Android system update (OTA). This mechanism is used to dynamically load and unload test nanoapps, but can also be used for production nanoapps. ## Other Nanoapp Types Some platforms support loading nanoapps into multiple tiers of memory, for example low-power tightly coupled memory (TCM, usually SRAM), versus a higher-power but higher-capacity memory bank (such as DRAM). This distinction is normally made at the build target variant level. CHRE also supports the concept of a *system nanoapp*, which is a nanoapp whose purpose is to accomplish some low-level, device-specific functionality that is purely beneath the HAL level. System nanoapps are therefore hidden from the nanoapp list at the HAL. This property is controlled by setting the `NANOAPP_IS_SYSTEM_NANOAPP` variable in the nanoapp Makefile. ## Example AOSP Nanoapps Some basic nanoapps can be found in the `apps/` folder, which are used for test purposes, as well as to demonstrate how to use the CHRE APIs. ### FeatureWorld Nanoapps The *FeatureWorld* nanoapps each exercise a part of the CHRE API, and print results/output to `chreLog`. An overview of a few of the key FeatureWorld nanoapps is given below: * `hello_world`: While not technically a FeatureWorld nanoapp, it’s generally the first nanoapp to be tried, and it simply outputs a log message when it starts and ends, and upon any event received. * `message_world`: Exercises host messaging functionality. Typically used in conjunction with `host/common/test/chre_test_client.cc` (see `sendMessageToNanoapp()` in that file). * `sensor_world`: Enables sensors and prints the samples it receives. This nanoapp is typically customized prior to executing, for example to control which sensors it will enable. It also supports a “break it” mode which stresses the system by enabling/disabling sensors frequently. * `host_awake_world`: Used to help validate functionality used for opportunistically sending messages to the AP when it is awake. ### Stress Test Nanoapps These nanoapps help stress test the CHRE framework. They include: * `audio_stress_test`: Repeatedly enables and disables an audio source, verifying that it continues to provide data as expected. * `sensor_world`: Contains a “break it” mode which repeatedly enables, disables, and reconfigures sensors. * `spammer`: Sends a constant stream of messages and events to stress test the queueing system. * `unload_tester`: Used in conjunction with the spammer nanoapp to verify that unloading a nanoapp with pending events/messages completes successfully. Note that this nanoapp references internal framework functions (e.g. `EventLoopManager::deferCallback()`) to accomplish its functionality, which is generally only permissible for testing purposes. ### Power Test The `power_test` nanoapp is intended to be used in conjunction with special hardware that directly measures the power usage of the system and/or its components. This nanoapp is intended to be used with its host-side client, `chre_power_test_client`, to create some activity at the CHRE API level which can then be measured. For example, running `./chre_power_test_client wifi enable 5000000000` will configure the `power_test` nanoapp to request a WiFi scan every 5 seconds - the power monitoring equipment can then be used to determine the power cost of performing a WiFi scan from CHRE. Typically this is done after unloading all other nanoapps in the system (which can be done via `./chre_power_test_client unloadall`), and disabling all other functionality, to get a clean power trace of purely the functionality exercised by the `power_test` nanoapp. Refer to `chre_power_test_client.cc` for more details, including a full listing of all supported commands. ### Nanoapps Used with Java-based Test Suites Nanoapps under `apps/test` are associated with a test suite, for example Context Hub Qualification Test Suite (CHQTS), which is used to test that a given device upholds the requirements of the CHRE API. Much of the host-side Java code associated with these nanoapps can be found in the `java/` folder.