Revamp documentation am: 7f23a87057 am: 9e5212c67b
Original change: https://googleplex-android-review.googlesource.com/c/platform/system/chre/+/12063633
Change-Id: If1f9a9b5f6d5f4eba7decdc1851eeba3ab9edfdf
diff --git a/README.md b/README.md
index a945aaa..b8eb497 100644
--- a/README.md
+++ b/README.md
@@ -1,233 +1,99 @@
# Context Hub Runtime Environment (CHRE)
-## Build Instructions
+This project contains the AOSP reference implementation of the Context Hub
+Runtime Environment (CHRE), which is Android’s platform for developing always-on
+applications, called *nanoapps*. CHRE runs in a vendor-specific processor that
+is independent of the main applications processor that runs Android. This
+enables CHRE and its nanoapps to be more power-efficient for use cases that
+require frequent background processing of contextual data, like sensor inputs.
+Nanoapps are written to the CHRE API, which is standardized across all
+platforms, enabling them to be code-compatible across different devices.
-Build targets are arranged in the form of a variant triple consisting of:
+The CHRE reference implementation (“CHRE framework”) is designed to be portable
+across hardware and software platforms. While Android does not require a
+particular implementation (only compliance to the contracts given in the CHRE
+API) using the reference implementation helps to reduce the work needed to
+support CHRE, while also ensuring more consistent behavior for scenarios that
+can be difficult to enforce via testing.
-``vendor_arch_variant``
+## Navigating the docs
-The vendor is the provider of the CHRE implementation (ex: google, qcom). The
-arch is the CPU architecture (ie: hexagonv60, x86, cm4). The variant is the
-target platform (ie: slpi, nanohub, linux, googletest).
+Use the navigation bar at the top and/or the links below to move through the
+documentation. Raw files can also be found in the `/doc` folder.
-A debug build can be obtained by appending ``_debug`` to the variant triple. As
-an example:
+* Documentation related to the CHRE framework:
+ * [Framework Overview](/doc/framework_overview.md)
+ * [Porting Guide](/doc/porting_guide.md)
+ * [Build System](/doc/framework_build.md)
+ * [Debugging](/doc/framework_debugging.md)
+ * [Testing](/doc/framework_testing.md)
+ * [Vendor Extensions](/doc/vendor_extensions.md)
+* Documentation related to nanoapps:
+ * [Nanoapp Overview](/doc/nanoapp_overview.md)
+ * [Developer Guide](/doc/nanoapp_developer_guide.md)
+ * [Interacting with Nanoapps](/doc/nanoapp_clients.md)
+* General documentation:
+ * [Compatibility Design](/doc/compatibility.md)
+ * [Contributing](/doc/contributing.md)
-``make google_hexagonv62_slpi``
-``make google_hexagonv62_slpi_debug``
+The CHRE API and PAL API are also extensively documented using Doxygen syntax.
+Run `doxygen` in the same folder as `Doxyfile` to generate a browseable HTML
+version of the documentation.
-### Linux
+## Navigating the code
-CHRE is compatible with Linux as a simulator.
+This repository (system/chre) contains an assortment of code, structured as
+follows:
-#### Linux Build/Run
+- ``apps/``: Public nanoapp source code, including sample nanoapps intended to
+ showcase how to use the CHRE APIs, and test nanoapps used to validate API
+ functionality
+- ``build/``: Files related to CHRE’s Makefile-based build system, which
+ supports building the CHRE framework and nanoapps using a configurable
+ toolchain
+- ``chpp/``: Context Hub Peripheral Protocol (CHPP) source code - see the nested
+ README and associated documentation for details
+- ``chre_api/``: Contains the official definition of the CHRE API (current and
+ past versions), which all CHRE implementations must adhere to
+- ``core/``: Common CHRE framework code, which is applicable to every platform
+ (contrast to ``platform/``)
+- ``doc/``: Contains documentation for the CHRE framework and associated topics
+- ``external/``: Code developed primarily outside of AOSP which (can be)
+ leveraged by CHRE, and is potentially customized for CHRE (e.g. flatbuffers)
+- ``host/``: Reference code which supports the CHRE implementation, but runs on
+ the applications processor (“host”), for example the Context Hub HAL
+- ``java/``: Java test code used in conjunction with test nanoapps
+- ``pal/``: The binary-stable Platform Abstraction Layer (PAL) C API definitions
+ and tests (these PALs may optionally be used by the platform implementation)
+- ``platform/``: Code related to the implementation of CHRE on a particular
+ platform/device (compare to ``core/``), divided into sub-folders as follows:
+ - ``platform/include``: The interface between common code in ``core/`` and
+ platform-specific code implemented elsewhere in ``platform/``
+ - ``platform/shared``: Code that may apply to multiple platforms, but is not
+ necessarily applicable to _all_ platforms (as in ``core/``). For example,
+ multiple platforms may choose to use the binary-stable PAL interface - this
+ folder contains source files translating from the C++ platform abstractions
+ to the C PAL APIs.
+ - ``platform/<platform_name>``: Code specific to the platform indicated by
+ ``platform_name``
+- ``util/``: Utility code that is not platform-specific, but not part of the
+ core framework implementation. Includes code that is usable by nanoapps.
+- ``variant/``: Code/configuration that is specific to a particular device (more
+ detail on variants can be found below). For example, multiple generations of a
+ given chip may use the same platform code, but the code may be configured on a
+ per-device basis in the build via ``variant.mk``.
-The simulator has system dependencies:
+Code related to CHRE also exists in other parts of the Android tree, including:
-- TCLAP
- - Command-line argument parsing.
-- libsndfile
- - WAV file parsing for audio support.
+- ``hardware/interfaces/contexthub/``: The Context Hub HAL definition
+- ``frameworks/base/core/java/android/hardware/location/ContextHub*.java``: The
+ APIs used by privileged apps to interact with CHRE and nanoapps
+- ``frameworks/base/services/core/java/com/android/server/location/ContextHub*.java``:
+ The Context Hub service implementation in system server
-These are the commands to install these dependencies for Ubuntu:
+# Have Questions?
- sudo apt-get install libtclap-dev
- sudo apt-get install libsndfile1-dev
-
-The build target for x86 linux is ``google_x86_linux``. You can build/run the
-simulator with the following command:
-
- ./run_sim.sh
-
-#### Linux Unit Tests
-
-You can run all unit tests with the following command. Pass arguments to this
-script and they are passed to the gtest framework. (example:
-``--gtest_filter=DynamicVector.*``)
-
- ./run_tests.sh
-
-### CHRE Simulator for Android
-
-CHRE is also compatible with Android as a simulator.
-
-This is not intended to be a production implementation but is suitable for
-testing CHRE nanoapps on the applications processor where Android runs. It uses
-Android NDK APIs to interact with the system.
-
-### SLPI Hexagon
-
-First, setup paths to the Hexagon Tools (v8.x.x), SDK (v3.0), and SLPI source
-tree, for example:
-
- export HEXAGON_TOOLS_PREFIX=~/Qualcomm/HEXAGON_Tools/8.0
- export HEXAGON_SDK_PREFIX=~/Qualcomm/Hexagon_SDK/3.0
- export SLPI_PREFIX=~/Qualcomm/msm8998/slpi_proc
-
-Then use the provided Makefiles to build:
-
- make google_hexagonv62_slpi -j
-
-## Directory Structure
-
-The CHRE project is organized as follows:
-
-- ``chre_api``
- - The stable API exposed to nanoapps
-- ``core``
- - Common code that applies to all CHRE platforms, most notably event
- management.
-- ``pal``
- - An abstraction layer that implementers must supply to access
- device-specific functionality (such as GPS and Wi-Fi). The PAL is a C API
- which allows it to be implemented using a vendor-supplied library.
-- ``platform``
- - Contains the system interface that all plaforms must implement, along with
- implementations for individual platforms. This includes the implementation
- of the CHRE API.
- - ``platform/shared``
- - Contains code that will apply to multiple platforms, but not
- necessarily all.
- - ``platform/linux``
- - This directory contains the canonical example for running CHRE on
- desktop machines, primarily for simulation and testing.
-- ``apps``
- - A small number of sample applications are provided. These are intended to
- guide developers of new applications and help implementers test basic
- functionality quickly.
- - This is reference code and is not required for the CHRE to function.
-- ``util``
- - Contains data structures used throughout CHRE and common utility code.
-- ``variant/simulator``
- - Contains the CHRE variant for the simulator. This is a good example to
- start from when porting to new devices. Variants are explained in more
- detail below.
-
-Within each of these directories, you may find a ``tests`` subdirectory
-containing tests written against the googletest framework.
-
-### Platform Directory Structure
-
-The platform directory contains an interface that common code under ``core``
-leverages to implement the runtime. All platforms are required to implement the
-interface provided in ``platform/include``.
-
-The following gives a more detailed explanation of the directory structure.
-
-- ``platform`` - The top-level directory for platform-specific code.
- - ``include`` - The interface that platforms are required to implement.
- - ``shared`` - Code that may be shared by more than one platform but not
- necessarily required for all.
- - ``slpi`` - The implementation of the common interface for the SLPI and any
- SLPI-specific code.
- - ``linux`` - The implementation of the common interface for the simulator
- running on Linux and any simulator-specific code.
-
-Common CHRE code that is expected to run across all platforms is located in
-``core``. This code must have a stable way to access the platform-specific
-implementation of the common platform API. This is handled by providing a stable
-include path and changing the search path for the platform implementation. Here
-is an example directory layout:
-
-- ``platform``
- - ``<platform_name>``
- - ``include``
- - ``chre``
- - ``target_platform``
-
-The build system will add ``platform/<platform_name>/include`` to the include
-search path allowing common code to find the implementation of the platform
-interface. Here is an example of core code including a platform-specific header
-in this way:
-
-``#include "chre/target_platform/log.h"``
-
-When building for the linux platform, the file is included from:
-
-``platform/linux/include/chre/target_platform/log.h``
-
-## Supplied Nanoapps
-
-This project includes a number of nanoapps that serve as both examples of how to
-use CHRE, debugging tools and can perform some useful function.
-
-All nanoapps in the ``apps`` directory are placed in a namespace when built
-statically with this CHRE implementation. When compiled as standalone nanoapps,
-there is no outer namespace on their entry points. This allows testing various
-CHRE subsystems without requiring dynamic loading and allows these nanoapps to
-coexist within a CHRE binary. Refer to ``apps/hello_world/hello_world.cc`` for
-a minimal example.
-
-### FeatureWorld
-
-Any of the nanoapps that end with the term World are intended to test some
-feature of the system. The HelloWorld nanoapp simply exercises logging
-functionality, TimerWorld exercises timers and WifiWorld uses wifi, for example.
-These nanoapps log all results via chreLog which makes them effective tools when
-bringing up a new CHRE implementation.
-
-### ImuCal
-
-This nanoapp implements IMU calibration.
-
-## Porting CHRE
-
-This codebase is intended to be ported to a variety of operating systems. If you
-wish to port CHRE to a new OS, refer to the ``platform`` directory. An example of
-the Linux port is provided under ``platform/linux``.
-
-There are notes regarding initialization under
-``platform/include/chre/platform/init.h`` that will also be helpful.
-
-### Important Considerations
-
-Platforms are required to implement support for invoking the constructors and
-destructors of global, non-POD types at load and unload time, respectively. This
-is required for both the runtime and nanoapps.
-
-## Coding conventions
-
-There are many well-established coding standards within Google. The official
-C++ style guide is used with the exception of Android naming conventions for
-methods and variables. This means 2 space indents, camelCase method names, an
-mPrefix on class members and so on. Style rules that are not specified in the
-Android style guide are inherited from Google.
-
-## CHRE Variants
-
-A CHRE variant allows injecting additional source files into the build on a
-per-device basis. This can be used to inject:
-
-* A version string
- * Set to ``undefined`` if not specified
-* A static nanoapp list
- * Empty if left undefined
-* Additional static nanoapp includes
- * Vendor-specific nanoapps could be specified in the variant
-
-Export the ``CHRE_VARIANT_MK_INCLUDES`` containing the mk files that you wish to
-be included the CHRE variant build. Refer to ``run_sim.sh`` and the
-``variant/simulator`` subdirectory for an example as used by the simulator.
-
-* [Google C++ Style][1]
-
-[1]: https://google.github.io/styleguide/cppguide.html
-
-### Use of C++
-
-This project uses C++11, but with two main caveats:
-
- 1. General considerations for using C++ in an embedded environment apply. This
- means avoiding language features that can impose runtime overhead should
- be avoided, due to the relative scarcity of memory and CPU resources, and
- power considerations. Examples include RTTI, exceptions, overuse of dynamic
- memory allocation, etc. Refer to existing literature on this topic
- including this [Technical Report on C++ Performance][2] and so on.
- 2. Support of C++ standard libraries are not generally expected to be
- extensive or widespread in the embedded environments where this code will
- run. That means that things like <thread> and <mutex> should not be used,
- in favor of simple platform abstractions that can be implemented directly
- with less effort (potentially using those libraries if they are known to be
- available).
-
-[2]: http://www.open-std.org/jtc1/sc22/wg21/docs/TR18015.pdf
+If you’re unable to find the answers you’re looking for in CHRE documentation
+or are looking for specific guidance for your platform, device, or nanoapp,
+please reach out to the CHRE team via your TAM or through the [Google Issue
+Tracker](https://developers.google.com/issue-tracker).
diff --git a/doc/compatibility.md b/doc/compatibility.md
new file mode 100644
index 0000000..a62c10c
--- /dev/null
+++ b/doc/compatibility.md
@@ -0,0 +1,218 @@
+# 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.
diff --git a/doc/contributing.md b/doc/contributing.md
new file mode 100644
index 0000000..f5de7af
--- /dev/null
+++ b/doc/contributing.md
@@ -0,0 +1,10 @@
+# Contributing to CHRE
+
+It is encouraged that vendors implementing CHRE for their platforms contribute
+their code back to the open source project when possible as this will help
+provide more reference code for others and give the CHRE team better insight
+into the various use cases of users of the project.
+
+Anyone can upload patches to the Android Open Source Project (AOSP) and have
+the CHRE team review them using [these
+instructions](https://source.android.com/setup/contribute/submit-patches).
diff --git a/doc/framework_build.md b/doc/framework_build.md
new file mode 100644
index 0000000..2548449
--- /dev/null
+++ b/doc/framework_build.md
@@ -0,0 +1,149 @@
+# CHRE Framework Build System
+
+[TOC]
+
+The CHRE build system is based on Make, and uses a set of Makefiles that allow
+building the CHRE framework for a variety of hardware and software architectures
+and variants (e.g. different combinations of CPU and OS/underlying system). It
+is also flexible to different build toolchains (though LLVM/Clang or GCC are
+recommended), by abstracting out key operations to a few Make or environment
+variables. While the CHRE framework source code may be integrated into another
+build system, it can be beneficial to leverage the existing build system to
+reduce maintenance burden when the CHRE framework is updated. Additionally, it
+should be possible to build nanoapps from the CHRE build system (to have
+commonality across devices), and the CHRE framework build shares configuration
+with the nanoapp build.
+
+By default, the output of the build is linked into both a static archive
+`libchre.a` and a shared library `libchre.so`, though generally only one of the
+two is used, depending on the target device details.
+
+## Design
+
+The CHRE build system was originally designed around the philosophy that a
+vanilla invocation of `make` or `make all` should build any given nanoapp for
+all targets. This allows for efficient use of the job scheduler in the Make
+build system for multi-threaded builds and also promotes a level of separation
+of concerns between targets (this is not enforced by any Make language
+construct, merely convention). In practice, the CHRE build system is rarely used
+to build multiple targets with one invocation of Make. However, the design goal
+is carried forward for the variant support and separation of concerns between
+targets.
+
+All variant-specific compiler and linker flags are held under variables that
+only apply to their specific target. This encourages developers to avoid leaking
+build details between targets. This is important because not all compiler or
+linker flags are compatible with all toolchains. For example: if a target uses a
+compiler that does not support `-Wdouble-promotion`, but this were to be
+enforced for all builds, then by definition this target would not compatible
+with the CHRE build. The goal is for the CHRE build to be as flexible as
+possible.
+
+### Build Template
+
+The CHRE build system is implemented using template meta-programming techniques.
+A build template is used to create Make rules for tasks that are common to all
+targets. This includes compiling C/C++/assembly sources, linking, nanoapp header
+generation, etc. The rationale behind this approach is to reduce boilerplate
+when adding support for a new build target.
+
+The build template is located at `build/build_template.mk`, and is documented
+with all the variables used to generate build targets, like `TARGET_CFLAGS`.
+
+## Build Targets (Variants)
+
+Compiling the framework for different devices is done by specifying the build
+target when invoking `make`. Conventionally, build targets consist of three
+parts: (software) vendor, architecture and variant and follow the
+`<vendor>_<arch>_<variant>` pattern. A “vendor” is typically the company that
+created the CHRE implementation, which may bring with it some details related to
+nanoapp compatibility, for example the Nanoapp Support Library from the same
+vendor may be required. The “arch” field refers to the Instruction Set
+Architecture (ISA) and related compiler configuration to create a binary for the
+target processor. The “variant” is primarily related to the underlying platform
+software that the CHRE framework builds on top of, such as the combination of
+operating system and other software needed to select the appropriate combination
+of code in the `platform/` folder, but can also define other attributes of the
+build, such as the target memory region for the binary. If a vendor,
+architecture, or variant consist of multiple words or components, then they
+should be separated by a hyphen and not an underscore.
+
+For example, if we assume that a fictional company named Aperture developed its
+own CHRE framework implementation, targeting a CPU family called Potato, and a
+collection of platform software called GladOS/Cake, then a suitable build target
+name would be `aperture_potato_glados-cake`.
+
+The build target may optionally have `_debug` appended, which is a common suffix
+which enables `-g` and any additional target-specific debug flags.
+
+### Creating a New Build Target
+
+#### Architecture Support
+
+The architecture-specific portion of the build deals with mainly the build
+toolchain, and its associated flags.
+
+It is easiest to check if the architecture is currently listed in `build/arch`,
+and if it is, _Hooray! You're (almost) done_. It is still worthwhile to quickly
+read through to know how the build is layered.
+
+CHRE expects the build toolchain to be exported via Makefile variables,
+specifically the compiler (`TARGET_CC`), archiver (`TARGET_AR`), and the linker
+(`TARGET_LD`). Architecture specific compiler and linker flags are passed in via
+the `TARGET_CFLAGS` and `TARGET_LDFLAGS` respectively. Additional
+architecture-specific configuration is possible - refer to existing files under
+`build/arch` and `build/build_template.mk` for details.
+
+#### Build Target Makefile
+
+Makefiles for each build target can be found at
+`build/variant/<target_name>.mk`. These files are included at the end of the
+top-level Makefile, and has the responsibility of collecting arguments for the
+build template and invoking it to instantiate build rules. This involves doing
+steps including (not an exhaustive listing):
+
+* Setting the target name and platform ID
+
+* Configuring (if needed) and including the apporpriate `build/arch/*.mk` file
+
+* Collecting sources and flags specific to the platform into
+ `TARGET_VARIANT_SRCS` and `TARGET_CFLAGS`
+
+* Including `build/build_template.mk` to instantiate the build targets - this
+ must be the last step, as the make targets cannot be modified once generated
+
+Refer to existing files under `build/variant` for examples.
+
+## Device Variants
+
+While the build target is primarily concerned with configuring the CHRE build
+for a particular chipset, the same chipset can appear in multiple device
+models/SKUs, potentially with different peripheral hardware, targeted levels of
+feature support, etc. Additionally, a device/chip vendor may wish to provide
+additional build customization outside of the Makefiles contained in the
+system/chre project. The build system supports configuration at this level via
+the device variant makefile, typically named `variant.mk`, which is injected
+into the build by setting the `CHRE_VARIANT_MK_INCLUDES` environment variable
+when invoking the top-level Makefile. Refer to the file
+`variant/android/variant.mk` for an example.
+
+## Platform Sources
+
+The file at `platform/platform.mk` lists sources and flags needed to compile the
+CHRE framework for each supported platform. These must be added to Make
+variables prefixed with the platform name (for example, `SIM_SRCS` for platform
+sources used with the simulator build target), and not `COMMON_SRCS` or other
+common variables, to avoid affecting other build targets.
+
+## Build Artifacts
+
+At the end of a successful build, the following are generated in the `out`
+directory:
+
+* `<build_target>/libchre.so` and `libchre.a`: the resulting CHRE framework
+ binary, built as a dynamic/static library
+
+* `<build_target>_objs/`: Directory with object files and other intermediates
+
+* Depending on the build target, additional intermediates (e.g. `nanopb_gen` for
+ files generated for use with NanoPB)
diff --git a/doc/framework_debugging.md b/doc/framework_debugging.md
new file mode 100644
index 0000000..67f1bbf
--- /dev/null
+++ b/doc/framework_debugging.md
@@ -0,0 +1,68 @@
+# Debugging the CHRE Framework
+
+[TOC]
+
+This section lists the methods that can be used to aid in CHRE framework
+debugging.
+
+## Logging
+
+The CHRE framework invokes the `LOGx()` macros defined in
+`platform/include/chre/platform/log.h` to log information into the system,
+for printf-style debugging. This capability is also exposed to nanoapps via
+`chreLog()`. Although it may not be strictly required, it is strongly
+recommended that the platform implementation directs these log messages to
+Android’s logcat system under the “CHRE” tag, where they will be automatically
+collected in bug reports. These logs must not wake the applications processor
+(AP), so they should be buffered on a best-effort basis and flushed to the AP
+opportunistically when it wakes up.
+
+### Log levels
+
+CHRE framework currently supports four levels, namely Error `LOGE()`, Warning
+` LOGW()`, Info `LOGI()` and Debug `LOGD()`. These correspond to the
+equivalent [logcat
+levels](https://source.android.com/setup/contribute/code-style#log-sparingly).
+Choosing an appropriate level for logs, and logging only the necessary
+information to identify and debug failures can help avoid issues with “log
+spam”, such as log output that is difficult to read, or uninteresting “spammy”
+logs causing useful log messages to be pushed out of limited buffering space.
+
+### Log level filtering
+
+The CHRE framework currently only supports compile-time log level filtering.
+While it’s recommended to leave it at the default setting, the
+`CHRE_MINIMUM_LOG_LEVEL` build flag can be defined to one of the values set
+in `util/include/chre/util/log_common.h` to control which log levels are
+included in the binary.
+
+## Debug Dumps
+
+A debug dump is human-readable text produced on-demand for debugging purposes.
+While `LOGx()` is useful for logging events as they happen, the debug dump is
+a complementary function typically used to output a snapshot of the framework's
+state, history, vital statistics, etc. The debug dump is especially useful for
+information that would be too spammy to log on every change, but is useful to
+diagnose potential issues. The CHRE framework produces a debug dump when
+requested via the Context Hub HAL’s built-in `debug()` method, which is
+automatically collected as part of the bug report process, and can be manually
+triggered via ADB using the following command:
+
+`adb root && adb shell lshal debug android.hardware.contexthub@1.0::IContexthub/default`
+
+`DebugDumpManager` is the framework module responsible for collecting debug
+dumps from the CHRE framework and nanoapps. Refer to the associated
+documentation in the source code for details on this process.
+
+## CHRE_ASSERT and CHRE_ASSERT_LOG
+
+`CHRE_ASSERT()` and `CHRE_ASSERT_LOG()` can be used to help catch
+programmatic errors during development. However, since their use may have
+memory impact, they can be disabled by setting `CHRE_ASSERTIONS_ENABLED` to
+false in the Makefile. In general, assertions should be used sparingly - they
+are best applied to situations that would lead to potentially unrecoverable
+logical errors that are not handled by the code. For comparison, asserting that
+a pointer is not null is generally an anti-pattern (though the current CHRE
+codebase is not free of this), as dereferencing null would produce a crash
+anyways which should have equivalent debuggability as an assertion, among other
+reasons.
diff --git a/doc/framework_overview.md b/doc/framework_overview.md
new file mode 100644
index 0000000..ab9d0b2
--- /dev/null
+++ b/doc/framework_overview.md
@@ -0,0 +1,205 @@
+*** aside
+See also:
+[Porting Guide](/doc/porting_guide.md) |
+[Build System](/doc/framework_build.md) |
+[Debugging](/doc/framework_debugging.md) |
+[Testing](/doc/framework_testing.md) |
+[Vendor Extensions](/doc/vendor_extensions.md)
+***
+
+# CHRE Framework Overview
+
+[TOC]
+
+The CHRE reference implementation (hereafter referred to just as "CHRE" or "the
+CHRE framework") is developed primarily in C++11 using a modular object-oriented
+approach that separates common code from platform-specific code. CHRE is an
+event-based system, so CHRE is built around an event loop which executes nanoapp
+code as well as CHRE system callbacks. Per the CHRE API, nanoapps can’t execute
+in more than one thread at a time, so CHRE is structured around a single thread
+that executes the event loop, although there may be other threads in the system
+that support CHRE. The EventLoopManager is a Singleton object which owns the
+main state of the CHRE framework, including EventLoop and \*Manager classes for
+the various subsystems supported by CHRE.
+
+To get a better understanding of code structure and how it weaves between common
+and platform-specific components, it is helpful to trace the flow through a few
+example scenarios. Note that this is not meant to be an exhaustive list of
+everything that happens in each case (for that, refer to the code itself), but
+rather an overview of key points to serve as an introduction.
+
+## Loading a nanoapp via the HAL
+
+There are multiple ways by which a nanoapp can be loaded (see the relevant
+section below for details), but this example traces the flow for dynamically
+loading a nanoapp that has been passed in via the Context Hub HAL's
+`loadNanoapp()` method.
+
+1. The nanoapp binary reaches the HAL implementation, and it is loaded into the
+ processor where CHRE is running using a platform-specific method. While the
+ path this takes can vary, one common approach is to transmit the binary into
+ CHRE via the platform-specific HostLink implementation, then verify its
+ digital signature, and parse the binary file format (e.g. ELF) to load and
+ link the code.
+
+2. Once the nanoapp code is loaded, the platform code calls
+ `EventLoopManager::deferCallback()` to switch context to the main CHRE thread
+ (if needed), so it can complete loading and starting the nanoapp.
+ `deferCallback()` effectively posts an event to the main event loop which
+ does not get delivered to any nanoapps. Instead, the purpose is to invoke the
+ supplied callback from the CHRE thread once the event is popped off the
+ queue.
+
+3. The (platform-specific) callback finalizes the newly constructed `Nanoapp`
+ object as needed, and passes it to `EventLoop::startNanoapp()` - this marks a
+ transition from platform-specific to common code.
+
+4. `EventLoop` takes ownership of the `Nanoapp` object (which is a composite of
+ common and platform-specific data and functions, as described in the Platform
+ Abstractions section), includes it in the collection of loaded nanoapps to
+ execute in the main event loop, updates `mCurrentNanoapp` to reference the
+ nanoapp it's about to execute, and calls into `PlatformNanoapp::start()`.
+
+5. Since the mechanism of supporting dynamic linkage and position independent
+ code can vary by platform, transferring control from the framework to a
+ nanoapp is considered part of the platform layer. So
+ `PlatformNanoapp::start()` performs any necessary tasks for this, and calls
+ into the `nanoappStart()` function defined in the nanoapp binary.
+
+## Invoking a CHRE API from a nanoapp
+
+Let's assume the nanoapp we've loaded in the previous section calls the
+`chreSensorConfigure()` CHRE API function within `nanoappStart()`:
+
+1. The nanoapp invokes `chreSensorConfigure()` with parameters to enable the
+ accelerometer.
+
+2. The Nanoapp Support Library (NSL) and/or the platform's dynamic linking
+ module are responsible for handling the transition of control from the
+ nanoapp binary to the CHRE framework. This can vary by platform, but we'll
+ assume that control arrives in the `chreSensorConfigure()` implementation in
+ `platform/shared/chre_api_sensor.cc`.
+
+3. `EventLoopManager::validateChreApiCall()` is invoked to confirm that this
+ function is being called from the context of a nanoapp being executed within
+ the event loop (since associating the API call with a specific nanoapp is a
+ requirement of this API and many others, and the majority of the CHRE
+ framework code is only safe to execute from within the main CHRE thread), and
+ fetch a pointer to the current `Nanoapp` (i.e. it retrieves `mCurrentNanoapp`
+ set previosly by `EventLoop`).
+
+4. `SensorManager::setSensorRequest()` (via
+ `EventLoopManager::getSensorRequestManager()`) is called to process the
+ nanoapp’s request - we transition to common code here.
+
+5. The request is validated and combined with other nanoapp requests for the
+ same sensor to determine the effective sensor configuration that should be
+ requested from the platform, and the nanoapp is registered to receive
+ broadcast accelerometer sensor events.
+
+6. `SensorRequestManager` calls into `PlatformSensorManager::configureSensor()`,
+ which performs the necessary operations to actually configure the
+ accelerometer to collect data.
+
+7. Assuming success, the return value propagates back up to the nanoapp, and it
+ continues executing.
+
+## Passing an event to a nanoapp
+
+Following the example from above, let's follow the case where an accelerometer
+sample has been generated and is delivered to the nanoapp for processing.
+
+1. Starting in platform-specific code, likely in a different thread, the
+ accelerometer sample is received from the underlying sensor framework - this
+ typically happens in a different thread than the main CHRE thread, and within
+ the fully platform-specific `PlatformSensorManagerBase` class.
+
+2. As needed, memory is allocated to store the sample while it is being
+ processed, and the data is converted into the CHRE format: `struct
+ chreSensorThreeAxisData`.
+
+3. `SensorRequestManager::handleSensorDataEvent()` is invoked (common code) to
+ distribute the data to nanoapps.
+
+4. `SensorRequestManager` calls into `EventLoop` to post an event containing the
+ sensor data to all nanoapps registered for the broadcast event type
+ associated with accelerometer data, and sets `sensorDataEventFree()` as the
+ callback invoked after the system is done processing the event.
+
+5. `EventLoop` adds this event to its event queue and signals the CHRE thread.
+
+6. Now, within the context of the CHRE thread, once the event loop pops this
+ event off of its queue in `EventLoop::run()`, the `nanoappHandleEvent()`
+ function is invoked (via `PlatformNanoapp`, as with `nanoappStart`) for each
+ nanoapp that should receive the event.
+
+7. Once the event has been processed by each nanoapp, the free callback
+ (`sensorDataEventFree()`), is called to release any memory or do other
+ necessary cleanup actions now that the event is complete.
+
+## Platform Abstractions
+
+CHRE follows the 'compile time polymorphism' paradigm, to allow for the benefits
+of `virtual` functions, while minimizing code size impact on systems with tight
+memory constraints.
+
+Each framework module as described in the previous section is represented by a
+C++ class in `core/`, which serves as the top-level reference to the module and
+defines and implements the common functionality. This common object is then
+composed with platform-specific functionality at compile-time. Using the
+`SensorRequestManager` class as an example, its role is to manage common
+functionality, such as multiplexing sensor requests from all clients into a
+single request made to the platform through the `PlatformSensorManager` class,
+which in turn is responsible for forwarding that request to the underlying
+sensor system.
+
+While `SensorRequestManager` is fully common code, `PlatformSensorManager` is
+defined in a common header file (under `platform/include/chre/platform`), but
+implemented in a platform-specific source file. In other words, it defines the
+interface between common code and platform-specific code.
+
+`PlatformSensorManager` inherits from `PlatformSensorManagerBase`, which is
+defined in a platform-specific header file, which allows for extending
+`PlatformSensorManager` with platform-specific functions and data. This pattern
+applies for all `Platform<Module>` classes, which must be implemented for all
+platforms that support the given module.
+
+Selection of which `PlatformSensorManager` and `PlatformSensorManagerBase`
+implementation is instantiated is controlled by the build system, by setting the
+appropriate include path and source files. This includes the path used to
+resolve include directives appearing in common code but referencing
+platform-specific headers, like `#include
+"chre/target_platform/platform_sensor_manager_base.h"`.
+
+To ensure compatibility across all platforms, common code is restricted in how
+it interacts with platform-specific code - it must always go through a common
+interface with platform-specific implementation, as described above. However,
+platform-specific code is less restricted, and can refer to common code, as well
+as other platform code directly.
+
+## Coding conventions
+
+This project follows the [Google-wide style guide for C++
+code](https://google.github.io/styleguide/cppguide.html), with the exception of
+Android naming conventions for methods and variables. This means 2 space
+indents, camelCase method names, an mPrefix on class members and so on. Style
+rules that are not specified in the Android style guide are inherited from
+Google. Additionally, this project uses clang-format for automatic code
+formatting.
+
+This project uses C++11, but with two main caveats:
+
+1. General considerations for using C++ in an embedded environment apply. This
+ means avoiding language features that can impose runtime overhead, due to the
+ relative scarcity of memory and CPU resources, and power considerations.
+ Examples include RTTI, exceptions, overuse of dynamic memory allocation, etc.
+ Refer to existing literature on this topic including this [Technical Report
+ on C++ Performance](http://www.open-std.org/jtc1/sc22/wg21/docs/TR18015.pdf)
+ and so on.
+
+2. Full support of the C++ standard library is generally not expected to be
+ extensive or widespread in the embedded environments where this code will
+ run. This means things like <thread> and <mutex> should not be used, in
+ favor of simple platform abstractions that can be implemented directly with
+ less effort (potentially using those libraries if they are known to be
+ available).
diff --git a/doc/framework_testing.md b/doc/framework_testing.md
new file mode 100644
index 0000000..01ebfca
--- /dev/null
+++ b/doc/framework_testing.md
@@ -0,0 +1,58 @@
+# Testing the CHRE Framework
+
+[TOC]
+
+The CHRE framework can be tested at various levels to ensure that
+components/modules components are working correctly and API contracts are being
+met. Below are some examples of what the team currently does to verify new
+changes.
+
+## Unit tests
+
+Currently, unit tests exist for various core components and utilities. Since
+platform-specific components likely aren’t compilable/available on a host
+machine, only components that are OS independent can be tested via this path.
+
+In order to write new tests, add a test source file under the test directory in
+the appropriate subdirectory. e.g. `util/tests`. Then, add the file to the
+`GOOGLETEST_SRCS` variable in the appropriate .mk file for that subdir,
+`util/util.mk` for example.
+
+Unit tests can be built and executed using `run_tests.sh`.
+
+## PAL implementation tests
+
+PAL implementation tests verify implementations of PAL interfaces adhere to the
+requirements of that interface, and are intended primarily to support
+development of PAL implementations, typically done by a chip vendor partner.
+Additional setup may be required to integrate with the PAL under test and supply
+necessary dependencies. The source code is in the files under `pal/tests/src`
+and follows the naming scheme `*_pal_impl_test.cc`.
+
+In order to run PAL tests, run: `run_pal_impl_tests.sh`. Note that there are
+also PAL unit tests in the same directory. The unit tests are added to the
+`GOOGLETEST_SRCS` target while PAL tests are added to the
+`GOOGLETEST_PAL_IMPL_SRCS` target.
+
+## FeatureWorld nanoapps
+
+Located under the `apps/` directory, FeatureWorld nanoapps interact with the set
+of CHRE APIs that they are named after, and can be useful during framework
+development for manual verification of a feature area. For example, SensorWorld
+attempts to samples from sensors and outputs to the log. It also offers a
+break-it mode that randomly changes which sensors are being sampled in an
+attempt to point out stress points in the framework or platform implementation.
+
+These apps are usually built into the CHRE framework binary as static nanoapps
+to facilitate easy development. See the Deploying Nanoapps section for more
+information on static nanoapps.
+
+## CHQTS
+
+The Context Hub Qualification Test Suite (CHQTS) tests perform end-to-end
+validation of a CHRE implementation, by using the Java APIs in Android to load
+and interact with test nanoapps which then exercise the CHRE API. While this
+code is nominally integrated in another test suite, the source code is available
+under `java/test/chqts/` for the Java side code and `apps/test/chqts/` for the
+CHQTS-only nanoapp code and `apps/test/common/` for the nanoapp code shared by
+CHQTS and other test suites.
diff --git a/doc/nanoapp_clients.md b/doc/nanoapp_clients.md
new file mode 100644
index 0000000..9d5af0c
--- /dev/null
+++ b/doc/nanoapp_clients.md
@@ -0,0 +1,68 @@
+# Interacting with Nanoapps from Client Code
+
+[TOC]
+
+Code that interacts with a nanoapp, for example within an Android app, is known
+as the *client* of the nanoapp. There are two ways to interact with nanoapps
+from the host (application processor): (1) Java (above the Context Hub HAL, from
+the Android framework or an APK), and (2) native vendor code (beneath the
+Context Hub HAL). Most clients, especially those with a UI component, should use
+the Java method, unless a vendor-partition native implementation is required
+(e.g. if interacting with a nanoapp is used to implement a different HAL, or if
+communication with other beneath-HAL modules is required).
+
+Interaction between nanoapps and clients occur through a flexible message
+passing interface. Refer to the Nanoapp Developer Guide for recommendations on
+how to design a protocol for use with a nanoapp.
+
+## Java APIs
+
+CHRE is exposed to Android apps holding the appropriate permissions through the
+[ContextHubManager](https://android.googlesource.com/platform/frameworks/base/+/master/core/java/android/hardware/location/ContextHubManager.java)
+and the associated
+[ContextHubClient](https://android.googlesource.com/platform/frameworks/base/+/master/core/java/android/hardware/location/ContextHubClient.java)
+system APIs.
+
+To use the above APIs, your application must have access to the
+`ACCESS_CONTEXT_HUB` permission, which is restricted to `signature|privileged`.
+This permission must be declared in the app’s [Android
+Manifest](https://developer.android.com/guide/topics/manifest/uses-permission-element),
+and is only granted to APKs that are signed with the same key as the platform
+(“signature” scope) or are preinstalled in the privileged apps folder *and* are
+present on the [privileged permission
+whitelist](https://source.android.com/devices/tech/config/perms-whitelist).
+
+The recommended flow for Java nanoapp client code is as follows:
+
+1. Retrieve the ContextHubManager object via
+ `Context.getSystemService(ContextHubManager.class)` - this will produce a
+ valid handle if the device supports `FEATURE_CONTEXT_HUB` as indicated by
+ `PackageManager.hasSystemFeature()`
+2. Retrieve a reference to a Context Hub via
+ `ContextHubManager.getContextHubs()`
+3. Confirm that the nanoapp is loaded and retrieve its version number by calling
+ `ContextHubManager.queryNanoApps()`
+4. If the nanoapp was found, create a `ContextHubClient` object through
+ `ContextHubManager.createClient()`. This can be used to communicate with your
+ nanoapp, and receive notifications of system events like reset. Note that the
+ `createClient()` API supports two modes of operation, which define how events
+ and data are passed to the client: direct callback with
+ `ContextHubClientCallback` (requires a persistent process), or
+ `PendingIntent` with `ContextHubIntentEvent` (can start an app’s process when
+ an event occurs). To send messages to the nanoapp, use
+ `ContextHubClient.sendMessageToNanoApp()`.
+
+## Vendor Native
+
+Depending on the details of the platform implementation, you may also be able to
+interact with CHRE directly, beneath the Context Hub HAL, by using socket IPC as
+exposed by the CHRE daemon reference implementation. This approach has some
+advantages, like being able to interact with system nanoapps that are not
+exposed at the Java level, and it can be used with other low-level beneath-HAL
+code. However, it is not suitable for use from native code within an Android
+app.
+
+See `host/common/test/chre_test_client.cc` for an example of how to use this
+interface. Note that SELinux configuration is generally required to whitelist
+access to the CHRE socket.
+
diff --git a/doc/nanoapp_developer_guide.md b/doc/nanoapp_developer_guide.md
new file mode 100644
index 0000000..b7b9491
--- /dev/null
+++ b/doc/nanoapp_developer_guide.md
@@ -0,0 +1,343 @@
+# Nanoapp Developer Guide
+
+[TOC]
+
+Since CHRE is an open platform, anyone can write nanoapps. However, deploying to
+a device requires cooperation of the device manufacturer, because CHRE is a
+security-sensitive trusted environment, similar to other low-level firmware, and
+it typically has tight resource constraints. This section assumes you have a
+basic understanding of what a nanoapp is (if not, see the Nanoapp Overview
+section), and provides some simple instructions to help you get started with
+developing your own nanoapp.
+
+## Getting Started
+
+When starting a new nanoapp, it’s helpful to start with the skeleton of an
+existing nanoapp. The simplest example can be found at `apps/hello_world`. Start
+by copying this folder to the location where you will develop the nanoapp - it
+can be outside of the `system/chre` project, for example in a vendor-specific
+Git repository in the `vendor/` folder of the Android tree.
+
+If you don’t plan to use this nanoapp as a *static nanoapp* (see the Nanoapp
+Overview for details), remove the `hello_world.mk` file and delete the code
+blocks wrapped in `#ifdef CHRE_NANOAPP_INTERNAL`. Rename the remaining files to
+match your nanoapp.
+
+### Picking a Nanoapp ID
+
+Nanoapps are uniquely identified by a 64-bit number. The most significant 5
+bytes of this number are the vendor identifier, and the remaining bytes identify
+the nanoapp within the vendor’s namespace. The vendor identifier is usually
+devised from an ASCII representation of the vendor’s name, for example Google
+uses 0x476F6F676C (“Googl”). The remaining portion of the ID is typically just
+an incrementing value for each nanoapp.
+
+Refer to `system/chre/chre_api/include/chre_api/chre/common.h` and
+`util/include/chre/util/nanoapp/app_id.h` for some examples and utilities.
+
+Be sure to pick a unique nanoapp ID when creating a new nanoapp.
+
+### Picking a Language
+
+CHRE guarantees support for nanoapps written in C99 or C++11, though not all
+standard library functions are supported (see below for details). For a
+device-specific nanoapp, additional programming languages/versions *may* be
+supported, but this can impact portability.
+
+### Building the Nanoapp Binary
+
+While it’s possible to build a nanoapp with a different build system, just as it
+is for the CHRE framework, it’s recommended to use the common build system
+included in this project, as it makes it easy to support a variety of target
+platforms. The rest of this section assumes you are using the CHRE build system
+to create a non-static nanoapp.
+
+Update the `Makefile` in your nanoapp’s directory to:
+
+* Define nanoapp metadata, including:
+ * `NANOAPP_NAME`: sets the output filename of the binary
+ * `NANOAPP_ID`: 64-bit identifier, in hexadecimal format
+ * `NANOAPP_VERSION`: 32-bit version, in hexadecimal format (see versioning
+ section below)
+ * `NANOAPP_NAME_STRING`, `NANOAPP_VENDOR_STRING`: human-readable strings for
+ the name of the nanoapp and vendor, respectively
+ * `NANOAPP_IS_SYSTEM_NANOAPP`: 0 or 1 (see Nanoapp Overview)
+* Populate `COMMON_SRCS` with the C or C++ source files to compile
+* Populate `COMMON_CFLAGS` with compiler flags, like additional include paths
+* Include any additional `.mk` files for vendor extensions, etc. before `app.mk`
+
+Refer to `build/nanoapp/app.mk` for full details.
+
+The nanoapp can then be built using a command like ``OPT_LEVEL=s make
+<build_target> -j`nproc` `` (see the CHRE Framework Build System section for
+details on build targets), which will produce build artifacts at
+`out/<build_target>/<nanoapp_name>.*`.
+
+### Loading onto a Device
+
+Exact steps to load a nanoapp binary can vary by device, but for developing a
+preloaded nanoapp, this typically involves the following steps:
+
+* Perform any needed post-processing of the nanoapp binary to permit it to be
+ loaded (such as signing with a development or production key)
+* Write the binary to the device’s storage (for example, using `adb push`)
+* Update `preloaded_nanoapps.json` or other configuration as needed, so that
+ CHRE knows to load the new nanoapp
+* Restart CHRE to reload all nanoapps, including the new one
+
+## Nanoapp Versioning
+
+While not strictly enforced, nanoapps are recommended to follow the convention
+of the CHRE framework and use [Semantic Versioning](http://semver.org). In the
+case of a nanoapp, the key versioned “API” is considered the interface between
+the client and nanoapp. Nanoapp versions are represented as a 32-bit integer,
+where the most significant byte represents the major version, followed by one
+byte for the minor version, and two bytes for the patch version.
+
+## Using the CHRE API
+
+The CHRE API is the key interface between each nanoapp and the underlying
+system. Refer to the extensive API documentation in the header files at
+`chre_api/include`, as well as usage of the APIs by sample nanoapps. The CHRE
+API is normally included via `#include <chre.h>`.
+
+## Utility Libraries
+
+Some source and header files under `util` are specifically designed to aid in
+nanoapp development, and others were initially created for use in the framework
+but can be leveraged by nanoapps as well. In general, any source and header file
+there that does **not** include a header from `chre/platform` (part of the
+internal CHRE framework implementation details) may be used by a nanoapp, and
+files within a subdirectory called `nanoapp` are specifically targeted for use
+by nanoapps.
+
+This includes `util/include/chre/util/nanoapp/log.h` (meant to be included via
+`#include “chre/util/nanoapp/log.h”`), which provides macros like `LOGD` which
+can be conditionally compiled, include a configurable prefix to help identify
+the sender, and suppress double promotion warnings.
+
+The utilities library also includes a number of container classes, which are
+meant to mimic the C++ standard library, but with a lightweight, CHRE-compatible
+implementation. This includes:
+
+* `chre::DynamicVector`: an `std::vector` analogue
+* `chre::FixedSizeVector`: accessed like `std::vector`, but only uses statically
+ allocated memory
+* `chre::ArrayQueue`: can be used as a circular buffer
+* `chre::UniquePtr`: an `std::unique_ptr` analogue
+* `chre::Optional`: an analogue to `std::optional` from C++17
+* `chre::Singleton`: a container for a statically allocated object with explicit
+ initialization and deinitialization (e.g. enables construction of a global
+ object to be deferred until `nanoappStart()`)
+
+## Interacting with the Host
+
+Nanoapps can interact with one or more clients on the host (applications
+processor) through a flexible binary message-passing interface. For simple
+interactions in cases where the lowest memory footprint is desired, using only
+the built-in message type field with no additional payload, or passing
+hand-rolled packed C-style structures (e.g. using Java’s ByteBuffer on the
+client side) can work, though this approach can be error-prone. Using a
+well-defined serialization format, such as Protocol Buffers (see the Using
+NanoPB section below) or FlatBuffers, is usually a better choice.
+
+There are a few common tips to keep in mind when interacting with the host:
+
+1. Nanoapp binaries are usually updated independently from client code - watch
+out for compatibility issues arising from changes to the messaging protocol, and
+use a serialization format like Protocol Buffers if possible.
+
+2. Nanoapp messages to the host always wake it up if it’s asleep. If this is not
+required, nanoapps are encouraged to batch their messages and opportunistically
+send when the host wakes up for another reason (see
+`chreConfigureHostSleepStateEvents()`).
+
+3. After calling `chreSendMessageToHostEndpoint()`, ownership of the memory
+associated with the message payload is assigned to the framework. Do not modify
+it until the free callback is invoked.
+
+4. Nanoapp messaging should be unicast, unless broadcast messaging is strictly
+necessary. Design the messaging protocol such that the client initiates
+communication, and save the host endpoint ID in the nanoapp to use when sending
+replies.
+
+## Interacting with Other Nanoapps
+
+While most nanoapps are only concerned with providing functionality for a single
+client on the host, it is possible for a nanoapp to provide services to other
+nanoapps within CHRE. Similar to how nanoapps communicate with the host by
+passing *messages*, nanoapps can communicate with one another by passing
+*events* with arbitrary binary payload. Event IDs starting in the range
+`CHRE_EVENT_FIRST_USER_VALUE` are reserved for this purpose.
+
+Typically a nanoapp creates a *nanoapp client library* which other nanoapps can
+include, which presents a simple, expressive API, and handles the implementation
+details of passing events to the target nanoapp, and interpreting incoming
+messages.
+
+Refer to the functions defined in `chre/event.h` for more details.
+
+## Using TensorFlow Lite for Microcontrollers
+
+Many nanoapps use machine learning techniques to accomplish their functionality.
+The CHRE build system has built-in support for integrating [TensorFlow Lite for
+Microcontrollers](https://www.tensorflow.org/lite/microcontrollers) (TFLM) into
+a nanoapp. Sync the TFLM sources, set `TFLM_PATH`, and define `USE_TFLM=true` in
+your Makefile - see `apps/tflm_demo/README` for details and an example nanoapp.
+
+## Using Nanopb
+
+The CHRE build system has integrated support for using
+[Nanopb](https://jpa.kapsi.fi/nanopb/) to provide support for [Protocol
+Buffers](https://developers.google.com/protocol-buffers) in a nanoapp. To
+integrate this into your nanoapp’s Makefile, first install and configure
+dependencies:
+
+* Sync the Nanopb source tree (e.g. from a release on GitHub), and define the
+ `NANOPB_PREFIX` environment variable to its path
+* Download and install the protobuf compiler `protoc` and make it available in
+ your `$PATH`, or set the `PROTOC` environment variable
+
+Then in your nanoapp’s Makefile, populate `NANOPB_SRCS` with the desired
+`.proto` file(s). That’s it! Though some additional options/parameters are
+available - see `build/nanopb.mk` for details.
+
+## Nanoapp Development Best Practices
+
+Even though CHRE aims to provide an environment for low-power and low-latency
+contextual signal processing, these two are often conflicting goals. In
+addition, CHRE is usually implemented in a resource-constrained environment with
+limited memory available.
+
+As it requires collaboration from all nanoapps to optimize their resource usage
+for CHRE to live up to its promises, some best practices are provided here as
+guidance for nanoapp development.
+
+### Memory Efficiency
+
+#### Avoid dynamic heap allocations where possible
+
+As CHRE is designed in a resource-constrained environment, there is no guarantee
+runtime memory allocation will succeed. In addition, dynamic heap allocations
+make it difficult to estimate the memory usage in advance. Developers are
+therefore encouraged to use static allocations where possible.
+
+#### Be careful of stack usage
+
+Unlike Linux’s default stack of 8MB that scales dynamically, CHRE only has a
+fixed stack of limited size (8KB is typical). Ensure you keep any allocations to
+an absolute minimum and any large allocations should go out of scope prior to
+navigating deeper into a stack.
+
+#### Prefer in-place algorithms
+
+Prefer in-place algorithms over out-of-place ones where efficiency allows to
+minimize additional memory requirements.
+
+### Power Efficiency
+
+#### Be opportunistic when possible
+
+Examples include:
+
+* If the host is asleep and doesn’t need to act on a nanoapp message
+ immediately, buffer until it wakes up for another reason.
+* Make a WiFi on-demand scan request only if the WiFi scan monitor doesn’t
+ provide a scan result in time.
+
+#### Batch data at the source where possible
+
+By batching data at the source, it reduces the data delivery frequency and helps
+keep CHRE asleep and improve power efficiency. Clients should make data requests
+with the longest batch interval that still meets the latency requirement.
+Examples include:
+
+* Make a sensor data request with the longest ``latency`` possible.
+* Make an audio data request with the longest ``deliveryInterval`` possible.
+
+### Standard Library Usage
+
+CHRE implementations are only required to support a subset of the standard C and
+C++ libraries, as well as language features requiring run-time support. This
+list is carefully considered to ensure memory usage and implementation
+complexity are minimized. Following these principles, some features are
+explicitly excluded due to their memory and/or extensive OS-level dependencies,
+and others because they are supplanted by more suitable CHRE-specific APIs.
+While not meant to be an exhaustive list and some platforms may differ, the
+following standard library features are not meant to be used by nanoapps:
+
+* C++ exceptions and run-time type information (RTTI)
+* Standard library multi-threading support, including C++11 headers `<thread>`,
+ `<mutex>`, `<atomic>`, `<future>`, etc.
+* C and C++ Standard Input/Output libraries
+* C++ Standard Template Library (STL)
+* C++ Standard Regular Expressions library
+* Dynamic memory allocation (`malloc`, `calloc`, `realloc`, `free`), and
+ libraries that inherently use dynamic allocation, such as `std::unique_ptr`
+* Localization and Unicode character support
+* Date and time libraries
+* Functions that modify normal program flow, including `<setjmp.h>`,
+ `<signal.h>`, `abort`, `std::terminate`, etc.
+* Accessing the host environment, including `system`, `getenv`, etc.
+* POSIX or other libraries not included in the C99 or C++11 language standards
+
+In many cases, equivalent functionality is available from CHRE API functions
+and/or utility libraries. For example, `chreLog` may be used for debug logging,
+where a more traditional program might use `printf`.
+
+## Debugging
+
+Similar to the framework debugging methods, each has its nanoapp counterpart to
+support nanoapp debugging through the framework. Please see the Framework
+Debugging section for reference/context.
+
+### Logging
+
+CHRE API `chreLog()` logs information into the system as part of the CHRE logs.
+Normally this appears in logcat, but some platforms may route it to a different
+logging system (a future version of the CHRE API is expected to make logcat
+logging mandatory).
+
+Nanoapps are encouraged to `#include "chre/util/nanoapp/log.h"` and use the
+`LOGx()` macros defined therein, which requires these additional steps:
+
+* Define `LOG_TAG` to a short, human-readable identifier for your nanoapp, as
+ this gets prepended to logs
+* Define `NANOAPP_MINIMUM_LOG_LEVEL` to a `CHRE_LOG_LEVEL_\*` value in your
+ Makefile for compile time log level filtering - it’s recommended to use
+ `CHRE_LOG_LEVEL_DEBUG` for development, and `CHRE_LOG_LEVEL_INFO` for release
+
+See also the Framework Debugging section for more general guidance on logging in
+CHRE.
+
+### Debug Dump
+
+When running on CHRE v1.4+, nanoapps can also append information to the CHRE
+framework debug dump. Nanoapps interested in using this capability should call
+`chreConfigureDebugDumpEvent(true)` in `nanoappStart()`, then when
+`CHRE_EVENT_DEBUG_DUMP` is received in `nanoappHandleEvent()`, use
+`chreDebugDumpLog()` to write human-readable output to the debug dump, which
+appears in bug reports under the Context Hub HAL debug section. In the reference
+CHRE framework implementation, nanoapp debug dumps have the nanoapp name and ID
+automatically prepended, for example:
+
+```
+Nanoapp debug dumps:
+
+ DebugDumpWorld 0x0123456789000011:
+ Debug event count: 2
+ Total dwell time: 92 us
+```
+
+Refer to the associated CHRE API documentation and Framework Debugging section
+for more information.
+
+### CHRE_ASSERT
+
+To help catch programming errors or other unexpected conditions, nanoapps can
+use the `CHRE_ASSERT` macro provided by `#include "chre/util/nanoapp/assert.h"`.
+Keep in mind that if one nanoapp encounters an assertion failure, it most likely
+will cause a reset of the processor where CHRE is running, impacting other
+functionality (though this can vary by platform). Therefore, assertions are only
+recommended to be used during development. Define the `CHRE_ASSERTIONS_ENABLED`
+variable in your Makefile to `false` to disable assertions at compile time.
diff --git a/doc/nanoapp_overview.md b/doc/nanoapp_overview.md
new file mode 100644
index 0000000..774356f
--- /dev/null
+++ b/doc/nanoapp_overview.md
@@ -0,0 +1,199 @@
+*** 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.
diff --git a/doc/porting_guide.md b/doc/porting_guide.md
new file mode 100644
index 0000000..72d3b1d
--- /dev/null
+++ b/doc/porting_guide.md
@@ -0,0 +1,253 @@
+# CHRE Framework Porting Guide
+
+[TOC]
+
+CHRE achieves portability and extensibility across platforms by defining
+interfaces that the platform needs to implement. These interfaces provide
+dependencies for the common CHRE code that are necessarily platform-specific.
+Additionally, platform code calls into common code to ferry events from
+underlying subsystems to nanoapps.
+
+This section gives an overview of the steps one should take to add support for a
+new platform in the CHRE reference implementation.
+
+## Directory Structure
+
+CHRE platform code can be broadly categorized as follows.
+
+### Platform Interfaces
+
+Files under `platform/include` serve as the interface between common code in
+`core/` and other platform-specific code in `platform/<platform_name>`. These
+files are considered common and should not be modified for the sake of
+supporting an individual platform.
+
+### Shared Platform Code
+
+Located in `platform/shared/`, the code here is part of the platform layer’s
+responsibilities, but is not necessarily specific to only one platform. In other
+words, this code is likely to be re-used by multiple platforms, but it is not
+strictly necessary for a given platform to use it.
+
+### Platform-specific Code
+
+Files under `platform/<platform_name>` are specific to the underlying software
+of a given platform, for example the APIs which are used to access functionality
+like sensors, the operating system, etc. To permit code reuse, the CHRE platform
+layer for a given device may be composed of files from multiple
+`<platform_name>` folders, for example if the same sensor framework is supported
+across multiple OSes, there may be one folder that provides the components that
+are specific to just the OS.
+
+Platform-specific code can be further subdivided into:
+
+* **Source files**: normally included at
+ `platform/<platform_name>/<file_name>.cc`, but may appear in a subdirectory
+
+* **Headers which are includable by common code**: these are placed at
+ `platform/<platform_name>/include/chre/target_platform/<file_name>.h`, and are
+ included by *Platform Interfaces* found in `platform/include` and provide
+ inline or base class definitions, such as `mutex_base_impl.h` and
+ `platform_sensor_base.h` respectively, or required macros
+
+* **Fully platform-specific headers**: these typically appear at
+ `platform/<platform_name>/include/chre/platform/<platform_name/<file_name>.h`
+ and may only be included by other platform-specific code
+
+## Open Sourcing
+
+Partners who add support for a new platform are recommended to upstream their
+code to
+[AOSP](https://source.android.com/setup/contribute#contribute-to-the-code).
+This helps ensure that details of your platform are considered by the team that
+maintains the core framework, so any changes that break compilation are
+addressed in a timely fashion, and enables you to receive useful code review
+feedback to improve the quality of your CHRE implementation. Please reach out
+via your TAM to help organize this effort.
+
+If some parts of a platform’s CHRE implementation must be kept closed source,
+then it is recommended to be kept in a separate Git project (under vendor/ in
+the Android tree). This vendor-private code can be integrated with the main CHRE
+build system through the `CHRE_VARIANT_MK_INCLUDES` variable. See the build
+system documentation for more details.
+
+## Recommended Steps for Porting CHRE
+
+When starting to add support for a new platform in the CHRE framework, it’s
+recommended to break the task into manageable chunks, to progressively add more
+functionality until the full desired feature set is achieved. An existing
+platform implementation can be referenced to create empty stubs, and then
+proceed to add implementations piece by piece, testing along the way.
+
+CHRE provides various test nanoapps in `apps/` that exercise a particular
+feature that the platform provides. These are selectively compiled into the
+firmware statically via a `static_nanoapps.cc` source file.
+
+With this in mind, it is recommended to follow this general approach:
+
+1. Create a new platform with only empty stubs, with optional features (like
+ `CHRE_GNSS_SUPPORT_ENABLED`) disabled at build-time
+
+2. Work on updating the build system to add a new build target and achieve
+ successful compilation and linking (see the build system documentation for
+ details)
+
+3. Implement base primitives from `platform/include`, including support for
+ mutexes, condition variables, atomics, time, timers, memory allocation, and
+ logging
+
+4. Add initialization code to start the CHRE thread
+
+5. Add static nanoapp initialization support (usually this is just a copy/paste
+ from another platform)
+
+6. Confirm that the ‘hello world’ nanoapp produces the expected log message (if
+ it does, huzzah!)
+
+7. Complete any remaining primitives, like assert
+
+8. Implement host link and the daemon/HAL on the host (AP) side, and validate it
+ with a combination of the message world nanoapp and the host-side test code
+ found at `host/common/test/chre_test_client.cc`
+
+At this stage, the core functionality has been enabled, and further steps should
+include enabling dynamic loading (described in its own section below), and the
+desired optional feature areas, like sensors (potentially via their respective
+PALs, described in the next section).
+
+## Implementing the Context Hub HAL
+
+The Context Hub HAL (found in the Android tree under
+`hardware/interfaces/contexthub`) defines the interface between Android and the
+underlying CHRE implementation, but as CHRE is implemented on a different
+processor from the HAL, the HAL is mostly responsible for relaying messages to
+CHRE. This project includes an implementation of the Context Hub HAL under
+`host/hal_generic` which pairs with the CHRE framework reference implementation.
+It converts between HAL API calls and serialized flatbuffers messages, using the
+host messaging protocol defined under `platform/shared` (platform
+implementations are able to choose a different protocol if desired, but would
+require a new HAL implementation), and passes the messages to and from the CHRE
+daemon over a socket. The CHRE daemon is in turn responsible for communicating
+directly with CHRE, including common functionality like relaying messages to and
+from nanoapps, as well as device-specific functionality as needed. Some examples
+of CHRE functionality that are typically implemented with support from the CHRE
+daemon include:
+
+* Loading preloaded nanoapps at startup
+* Passing log messages from CHRE into Android logcat
+* Determining the offset between `chreGetTime()` and Android’s
+ `SystemClock.elapsedRealtimeNanos()` for use with
+ `chreGetEstimatedHostTimeOffset()`
+* Coordination with the SoundTrigger HAL for audio functionality
+* Exposing CHRE functionality to other vendor-specific components (e.g. via
+ `chre::SocketClient`)
+
+When adding support for a new platform, a new HAL implementation and/or daemon
+implementation on the host side may be required. Refer to code in the `host/`
+directory for examples.
+
+## Implementing Optional Feature Areas (e.g. PALs)
+
+CHRE provides groups of functionality called *feature areas* which are
+considered optional from the perspective of the CHRE API, but may be required to
+support a desired nanoapp. CHRE feature areas include sensors, GNSS, audio, and
+others. There are two ways by which this functionality can be exposed to the
+common CHRE framework code: via the `Platform<Module>` C++ classes, or the C PAL
+(Platform Abstraction Layer) APIs. It may not be necessary to implement all of
+the available feature areas, and they can instead be disabled if they won’t be
+implemented.
+
+The Platform C++ Classes and PAL APIs have extensive documentation in their
+header files, including details on requirements. Please refer to the headers for
+precise implementation details.
+
+### Platform C++ Classes vs. PAL APIs
+
+Each feature area includes one or more `Platform<Module>` classes which the
+common framework code directly interacts with. These classes may be directly
+implemented to provide the given functionality, or the shim to the PAL APIs
+included in the `shared` platform directory may be used. PALs provide a C API
+which is suitable for use as a binary interface, for example between two dynamic
+modules/libraries, and it also allows for the main CHRE to platform-specific
+translation to be implemented in C, which may be preferable in some cases.
+
+Note that the PAL APIs are binary-stable, in that it’s possible for the CHRE
+framework to work with a module that implements a different minor version of the
+PAL API, full backwards compatibility (newer CHRE framework to older PAL) is not
+guaranteed, and may not be possible due to behavioral changes in the CHRE API.
+While it is possible for a PAL implementation to simultaneously support multiple
+versions of the PAL API, it is generally recommended to ensure the PAL API
+version matches between the framework and PAL module, unless the source control
+benefits of a common PAL binary are desired.
+
+This level of compatibility is not provided for the C++ `Platform<Module>`
+classes, as the CHRE framework may introduce changes that break compilation. If
+a platform implementation is included in AOSP, then it is possible for the
+potential impact to be evaluated and addressed early.
+
+### Disabling Feature Areas
+
+If a feature area is not supported, setting the make variable
+`CHRE_<name>_SUPPORT_ENABLED` to false in the variant makefile will avoid
+inclusion of common code for that feature area. Note that it must still be
+possible for the associated CHRE APIs to be called by nanoapps without crashing
+- these functions must return an appropriate response indicating the lack of
+ support (refer to `platform/shared/chre_api_<name>.cc` for examples).
+
+### Implementing Platform C++ Classes
+
+As described in the CHRE Framework Overview section, CHRE abstracts common code
+from platform-specific code at compile time by inheriting through
+`Platform<Module>` and `Platform<Module>Base` classes. Platform-specific code
+may retrieve a reference to other objects in CHRE via
+`EventLoopManagerSingleton::get()`, which returns a pointer to the
+`EventLoopManager` object which contains all core system state. Refer to the
+`Platform<Module>` header file found in `platform/include`, and implementation
+examples from other platforms for further details.
+
+### Implementing PALs
+
+PAL implementations must only use the callback and system APIs provided in
+`open()` to call into the CHRE framework, as the other functions in the CHRE
+framework do not have a stable API.
+
+If a PAL implementation is provided as a dynamic module in binary form, it can
+be linked into the CHRE framework at build time by adding it to
+`TARGET_SO_LATE_LIBS` in the build variant’s makefile - see the build system
+documentation for more details.
+
+### PAL Verification
+
+There are several ways to test the PAL implementation beyond manual testing.
+Some of them are listed below in increasing order of the amount of checks run by
+the tests.
+
+1. Use the FeatureWorld apps provided under the `apps` directory to exercise
+the various PAL APIs and verify the CHRE API requirements are being met
+
+2. Assuming the platform PAL implementations utilize CHPP and can communicate
+from the host machine to the target chipset, execute `run_pal_impl_tests.sh` to
+run basic sanity checks on the PAL
+
+3. Execute tests (see Testing section for details)
+
+## Dynamic Loading Support
+
+CHRE requires support for runtime loading and unloading of nanoapp binaries.
+There are several advantages to this approach:
+
+* Decouples nanoapp binaries from the underlying system - can maintain and
+ deploy a single nanoapp binary across multiple devices, even if they support
+ different versions of Android or the CHRE API
+
+* Makes it possible to update nanoapps without requiring a system reboot,
+ particularly on platforms where CHRE runs as part of a statically compiled
+ firmware
+
+* Enables advanced capabilities, like staged rollouts and targeted A/B testing
+
+While dynamic loading is a responsibility of the platform implementation and may
+already be a part of the underlying OS/system capabilities, the CHRE team is
+working on a reference implementation for a future release. Please reach out via
+your TAM if you are interested in integrating this reference code prior to its
+public release.
diff --git a/doc/vendor_extensions.md b/doc/vendor_extensions.md
new file mode 100644
index 0000000..68c2136
--- /dev/null
+++ b/doc/vendor_extensions.md
@@ -0,0 +1,135 @@
+# 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.
diff --git a/navbar.md b/navbar.md
new file mode 100644
index 0000000..82d0d3f
--- /dev/null
+++ b/navbar.md
@@ -0,0 +1,3 @@
+* [Home](/README.md)
+* [Framework Docs](/doc/framework_overview.md)
+* [Nanoapp Docs](/doc/nanoapp_overview.md)