1*** aside 2See also: [Nanoapp Developer Guide](/doc/nanoapp_developer_guide.md) | 3[Interacting with Nanoapps](/doc/nanoapp_clients.md) 4*** 5 6# Nanoapp Overview 7 8[TOC] 9 10Nanoapps are applications written in C or C++ which run in CHRE, to leverage 11low-power hardware. Typically, nanoapps integrate with a component on the 12Android side, such as a privileged APK, in order to provide complete end-to-end 13functionality of the target feature. This Android-side component is referred to 14as the nanoapp’s “client”. Since nanoapps are not limited to the same power 15constraints that Android apps are, they can process inputs, like sensor data, 16much more frequently while the device’s screen is off. 17 18Nanoapps are abstracted from the underlying platform details by the CHRE API, 19which is standardized across all CHRE implementations. This means that a nanoapp 20is *code compatible* across devices - its source code does not need to be 21changed to run on different hardware, but it *may* need to be recompiled. The 22CHRE API also provides binary compatibility guarantees across minor versions, so 23a nanoapp does not need to be recompiled to run on a device that exposes a newer 24or older version of the CHRE API. These properties help provide for the maximum 25reuse of code across devices. 26 27Due to system security and resource constraints of the platforms that CHRE 28targets, only device OEMs and their trusted partners are able to create 29nanoapps. In other words, the system only runs nanoapps that possess a digital 30signature that is trusted in advance by the device manufacturer, and APKs must 31hold a special privileged/same-signature permission (`ACCESS_CONTEXT_HUB`) to be 32able to interact with nanoapps and the Context Hub in general. However, this 33does not mean that third-party APKs cannot benefit from CHRE - nanoapps can be 34used to power APIs available for use by any Android app. 35 36## Methods for Loading a Nanoapp 37 38While nanoapps are nominally dynamically loadable modules, they can be loaded 39into a device through a few methods, each of which has pros and cons elaborated 40below. 41 42### Static Nanoapps 43 44Static nanoapps are, as the name suggests, statically compiled into the CHRE 45framework binary. Static nanoapps are automatically initialized after the CHRE 46framework completes its initialization during the boot process. 47 48Static nanoapps typically aren’t used in production, because this monolithic 49approach has downsides in terms of version control, updatability, etc., but it 50can be useful during CHRE development and bring-up of new devices, especially 51before dynamic loading functionality is enabled. For example, the FeatureWorld 52nanoapps (described later) are typically built as static nanoapps. 53 54Static nanoapps are typically unconditionally compiled as part of the framework 55build (via `apps/apps.mk`), but then stripped out by the linker if unreferenced 56(using the `--gc-sections` option, or equivalent). Static nanoapps are 57referenced only if their initialization function appears in the 58`kStaticNanoappList` array, which by default is empty, but can be overridden by 59the device variant makefile, as in `variant/simulator/` for example. 60 61Some boilerplate is needed to enable nanoapp to be built as a static nanoapp - 62see the code wrapped in `#ifdef CHRE_NANOAPP_INTERNAL` in 63`apps/hello_world/hello_world.cc`. 64 65### Preloaded Nanoapps 66 67Preloaded nanoapps are built as a separate binary from the CHRE framework, but 68included in the vendor partition of an overall device image (hence they are 69“preloaded” onto the device). The binaries associated with a preloaded nanoapp 70(usually a `.so` and a `.napp_header` file) are checked in to the Android tree 71as a “prebuilt” binary, and integrated into the Android build system so as to 72appear in the resulting device image, for example using `$(BUILD_PREBUILT)` in 73Android.mk, or `prebuilt_dsp` or `prebuilt_firmware` in Android.bp. 74 75While the mechanism for loading prebuilt nanoapps is platform-specific, the CHRE 76framework generally follows these steps at boot time: 77 781. When CHRE starts up, the CHRE daemon process running on the AP reads the 79 configuration file `/vendor/etc/chre/preloaded_nanoapps.json`, which contains 80 the list of nanoapps that should be automatically loaded. 81 822. For each nanoapp in the JSON file, the CHRE daemon reads the `.napp_header` 83 from storage, and sends a message to CHRE requesting it to load the nanoapp. 84 853. The platform layer of the CHRE framework handles the requests by loading, 86 authenticating, linking, and starting the nanoapp. 87 884. CHRE initialization proceeds (it is important for all preloaded nanoapps to 89 be included at the first moment list query command can be processed, to 90 avoid race conditions leading to clients believing that a preloaded nanoapp 91 is missing). 92 93This path is most commonly used to deploy nanoapps to production, as the entire 94device software can be validated together without external dependencies, while 95also preserving the ability to update nanoapps independent from other components 96in the system. 97 98### Fully Dynamic Nanoapps 99 100At the binary level, a preloaded nanoapp and fully dynamic nanoapp are 101identical. The key difference is where they are stored and how they are 102initially loaded into CHRE, and potentially how metadata is handled. In most 103cases, preloaded nanoapps will use a separate `.napp_header` file with metadata 104and `.so` file for the actual binary, a fully dynamic nanoapp has the header 105prepended to the binary, and carries the `.napp` file type suffix. In other 106words, the command `cat my_nanoapp.napp_header my_nanoapp.so > my_nanoapp.napp` 107can be used to create a fully dynamic nanoapp file from these components. 108 109Instead of being stored on the device filesystem, fully dynamic nanoapps can be 110loaded at any time after initialization using the 111`ContextHubManager.loadNanoApp()` Java API. This allows nanoapps to be 112updated/delivered by an APK, outside of a full Android system update (OTA). 113 114This mechanism is used to dynamically load and unload test nanoapps, but can 115also be used for production nanoapps. 116 117## Other Nanoapp Types 118 119Some platforms support loading nanoapps into multiple tiers of memory, for 120example low-power tightly coupled memory (TCM, usually SRAM), versus a 121higher-power but higher-capacity memory bank (such as DRAM). This distinction is 122normally made at the build target variant level. 123 124CHRE also supports the concept of a *system nanoapp*, which is a nanoapp whose 125purpose is to accomplish some low-level, device-specific functionality that is 126purely beneath the HAL level. System nanoapps are therefore hidden from the 127nanoapp list at the HAL. This property is controlled by setting the 128`NANOAPP_IS_SYSTEM_NANOAPP` variable in the nanoapp Makefile. 129 130## Example AOSP Nanoapps 131 132Some basic nanoapps can be found in the `apps/` folder, which are used for test 133purposes, as well as to demonstrate how to use the CHRE APIs. 134 135### FeatureWorld Nanoapps 136 137The *FeatureWorld* nanoapps each exercise a part of the CHRE API, and print 138results/output to `chreLog`. An overview of a few of the key FeatureWorld 139nanoapps is given below: 140 141* `hello_world`: While not technically a FeatureWorld nanoapp, it’s generally 142 the first nanoapp to be tried, and it simply outputs a log message when it 143 starts and ends, and upon any event received. 144 145* `message_world`: Exercises host messaging functionality. Typically used in 146 conjunction with `host/common/test/chre_test_client.cc` (see 147 `sendMessageToNanoapp()` in that file). 148 149* `sensor_world`: Enables sensors and prints the samples it receives. This 150 nanoapp is typically customized prior to executing, for example to control 151 which sensors it will enable. It also supports a “break it” mode which 152 stresses the system by enabling/disabling sensors frequently. 153 154* `host_awake_world`: Used to help validate functionality used for 155 opportunistically sending messages to the AP when it is awake. 156 157### Stress Test Nanoapps 158 159These nanoapps help stress test the CHRE framework. They include: 160 161* `audio_stress_test`: Repeatedly enables and disables an audio source, 162 verifying that it continues to provide data as expected. 163 164* `sensor_world`: Contains a “break it” mode which repeatedly enables, disables, 165 and reconfigures sensors. 166 167* `spammer`: Sends a constant stream of messages and events to stress test the 168 queueing system. 169 170* `unload_tester`: Used in conjunction with the spammer nanoapp to verify that 171 unloading a nanoapp with pending events/messages completes successfully. Note 172 that this nanoapp references internal framework functions (e.g. 173 `EventLoopManager::deferCallback()`) to accomplish its functionality, which is 174 generally only permissible for testing purposes. 175 176### Power Test 177 178The `power_test` nanoapp is intended to be used in conjunction with special 179hardware that directly measures the power usage of the system and/or its 180components. This nanoapp is intended to be used with its host-side client, 181`chre_power_test_client`, to create some activity at the CHRE API level which 182can then be measured. For example, running `./chre_power_test_client wifi enable 1835000000000` will configure the `power_test` nanoapp to request a WiFi scan every 1845 seconds - the power monitoring equipment can then be used to determine the 185power cost of performing a WiFi scan from CHRE. Typically this is done after 186unloading all other nanoapps in the system (which can be done via 187`./chre_power_test_client unloadall`), and disabling all other functionality, to 188get a clean power trace of purely the functionality exercised by the 189`power_test` nanoapp. 190 191Refer to `chre_power_test_client.cc` for more details, including a full listing 192of all supported commands. 193 194### Nanoapps Used with Java-based Test Suites 195 196Nanoapps under `apps/test` are associated with a test suite, for example Context 197Hub Qualification Test Suite (CHQTS), which is used to test that a given device 198upholds the requirements of the CHRE API. Much of the host-side Java code 199associated with these nanoapps can be found in the `java/` folder. 200