1# Context Hub Runtime Environment (CHRE)
2
3This project contains the AOSP reference implementation of the Context Hub
4Runtime Environment (CHRE), which is Android’s platform for developing always-on
5applications, called *nanoapps*. CHRE runs in a vendor-specific processor that
6is independent of the main applications processor that runs Android. This
7enables CHRE and its nanoapps to be more power-efficient for use cases that
8require frequent background processing of contextual data, like sensor inputs.
9Nanoapps are written to the CHRE API, which is standardized across all
10platforms, enabling them to be code-compatible across different devices.
11
12The CHRE reference implementation (“CHRE framework”) is designed to be portable
13across hardware and software platforms. While Android does not require a
14particular implementation (only compliance to the contracts given in the CHRE
15API) using the reference implementation helps to reduce the work needed to
16support CHRE, while also ensuring more consistent behavior for scenarios that
17can be difficult to enforce via testing.
18
19## Navigating the docs
20
21Use the navigation bar at the top and/or the links below to move through the
22documentation. Raw files can also be found in the `/doc` folder.
23
24* Documentation related to the CHRE framework:
25  * [Framework Overview](/doc/framework_overview.md)
26  * [Porting Guide](/doc/porting_guide.md)
27  * [Build System](/doc/framework_build.md)
28  * [Debugging](/doc/framework_debugging.md)
29  * [Testing](/doc/framework_testing.md)
30  * [Vendor Extensions](/doc/vendor_extensions.md)
31* Documentation related to nanoapps:
32  * [Nanoapp Overview](/doc/nanoapp_overview.md)
33  * [Developer Guide](/doc/nanoapp_developer_guide.md)
34  * [Interacting with Nanoapps](/doc/nanoapp_clients.md)
35* General documentation:
36  * [Compatibility Design](/doc/compatibility.md)
37  * [Contributing](/doc/contributing.md)
38
39The CHRE API and PAL API are also extensively documented using Doxygen syntax.
40Run `doxygen` in the same folder as `Doxyfile` to generate a browseable HTML
41version of the documentation.
42
43## Navigating the code
44
45This repository (system/chre) contains an assortment of code, structured as
46follows:
47
48- ``apps/``: Public nanoapp source code, including sample nanoapps intended to
49  showcase how to use the CHRE APIs, and test nanoapps used to validate API
50  functionality
51- ``build/``: Files related to CHRE’s Makefile-based build system, which
52  supports building the CHRE framework and nanoapps using a configurable
53  toolchain
54- ``chpp/``: Context Hub Peripheral Protocol (CHPP) source code - see the nested
55  README and associated documentation for details
56- ``chre_api/``: Contains the official definition of the CHRE API (current and
57  past versions), which all CHRE implementations must adhere to
58- ``core/``: Common CHRE framework code, which is applicable to every platform
59  (contrast to ``platform/``)
60- ``doc/``: Contains documentation for the CHRE framework and associated topics
61- ``external/``: Code developed primarily outside of AOSP which (can be)
62  leveraged by CHRE, and is potentially customized for CHRE (e.g. flatbuffers)
63- ``host/``: Reference code which supports the CHRE implementation, but runs on
64  the applications processor (“host”), for example the Context Hub HAL
65- ``java/``: Java test code used in conjunction with test nanoapps
66- ``pal/``: The binary-stable Platform Abstraction Layer (PAL) C API definitions
67  and tests (these PALs may optionally be used by the platform implementation)
68- ``platform/``: Code related to the implementation of CHRE on a particular
69  platform/device (compare to ``core/``), divided into sub-folders as follows:
70   - ``platform/include``: The interface between common code in ``core/`` and
71     platform-specific code implemented elsewhere in ``platform/``
72   - ``platform/shared``: Code that may apply to multiple platforms, but is not
73     necessarily applicable to _all_ platforms (as in ``core/``). For example,
74     multiple platforms may choose to use the binary-stable PAL interface - this
75     folder contains source files translating from the C++ platform abstractions
76     to the C PAL APIs.
77   - ``platform/<platform_name>``: Code specific to the platform indicated by
78     ``platform_name``
79- ``util/``: Utility code that is not platform-specific, but not part of the
80  core framework implementation. Includes code that is usable by nanoapps.
81- ``variant/``: Code/configuration that is specific to a particular device (more
82  detail on variants can be found below). For example, multiple generations of a
83  given chip may use the same platform code, but the code may be configured on a
84  per-device basis in the build via ``variant.mk``.
85
86Code related to CHRE also exists in other parts of the Android tree, including:
87
88- ``hardware/interfaces/contexthub/``: The Context Hub HAL definition
89- ``frameworks/base/core/java/android/hardware/location/ContextHub*.java``: The
90  APIs used by privileged apps to interact with CHRE and nanoapps
91- ``frameworks/base/services/core/java/com/android/server/location/ContextHub*.java``:
92  The Context Hub service implementation in system server
93
94# Have Questions?
95
96If you’re unable to find the answers you’re looking for in CHRE documentation
97or are looking for specific guidance for your platform, device, or nanoapp,
98please reach out to the CHRE team via your TAM or through the [Google Issue
99Tracker](https://developers.google.com/issue-tracker).
100