1.. _module-pw_chre: 2 3======= 4pw_chre 5======= 6.. pigweed-module:: 7 :name: pw_chre 8 9The `Context Hub Runtime Environment <https://source.android.com/docs/core/interaction/contexthub>`_ 10(CHRE) is Android's platform for developing always-on applications called 11nanoapps. These nanoapps run on a vendor-specific processor which is more power 12efficient. Nanoapps use the CHRE API, which is standardized across platforms, 13allowing them to be code-compatible across devices. 14 15This module implements a Pigweed backend to CHRE. In order to use this module, 16``dir_pw_third_party_chre`` must point to the directory to the CHRE library. 17 18----------- 19Get started 20----------- 21 22To integrate ``pw_chre`` with your project: 23 24- Call the initialization functions and start the event loop. 25- Handle messages from the application processor and connect them through to 26 the CHRE runtime. 27- Implement the functions in ``pw_chre/host_link``. This is how CHRE sends 28 messages to the application processor. 29 30 31``$pw_chre:chre_example`` runs the CHRE environment using ``pw_system``. 32This also loads several static example nanoapps from the CHRE codebase by 33compiling them into the executable. This can be a helpful reference. 34 35CHRE is implemented using the following Pigweed modules for functionality: 36 37- ``pw_chrono:system_timer``: implements getting monotonic time 38- ``pw_log``: implements logging to the application processor 39- ``pw_assert``: implements crash handling 40- ``pw_sync``: implements mutual exclusion primitives 41- ``malloc/free``: implements virtual memory allocation 42 (This may be eventually replaced with a pigweed module) 43 44---------------------- 45Current implementation 46---------------------- 47 48As mentioned at the top of this document, ``pw_chre`` is extremely experimental. 49Only a few parts of CHRE have been tested. There are likely to be bugs and 50unimplemented behavior. The lists below track the current state and will 51be updated as things change. 52 53Supported and tested behavior: 54 55- Loading static nanoapps. 56- The following sample nanoapps have been run: 57 - hello_world 58 - debug_dump_world 59 - timer_world 60 - unload_tester 61 - message_world 62 - spammer 63- Logging from a nanoapp. 64- Allocating memory (although it uses malloc/free). 65- Sending messages to/from the AP. 66 67Features not implemented, but likely to be implemented in the future: 68 69- Context Hub Qualification Test Suite (CHQTS). 70- Some simulated PALS for testing (based off of CHRE's linux simulated PALs). 71- Power Management APIs, e.g: waking the host AP and flushing messages. 72- Instructions around implementing a PAL. 73- Instructions around building and testing a nanoapp. 74- Dynamically loading nanoapps. 75 76Features that would be nice to have: 77 78- A plug-and-play implementation of AP <-> MCU flatbuffer message communication. 79- Pigweed defined facades for each PAL. 80- PAL implementations using Pigweed functionality (i.e: implementing bluetooth 81 via ``pw_bluetooth``). 82- Pigweed defined facades for core CHRE functionality, such as clock selection, 83 memory management, cache management. 84- A protobuf implementation of CHRE's flatbuffer API. 85- Cmake and Bazel build system integration. 86 87------------- 88API reference 89------------- 90.. doxygennamespace:: pw::chre 91 :members: 92 93------------- 94Porting Guide 95------------- 96The ``pw_chre`` module has completed the steps outlined for `creating a new CHRE platform`_ . 97 98.. _Creating a new CHRE platform: https://android.googlesource.com/platform/system/chre/+/refs/heads/main/doc/porting_guide.md#recommended-steps-for-porting-chre 99 100The ``pw_chre`` module still needs to be configured correctly on a new platform. 101You ``pw_chre`` user is responsible for: 102 103- Starting a thread for CHRE's event loop and calling the correct APIs. 104- Forwarding messages to/from the Application Processor (AP). 105 106----------------------------- 107Adding Optional Feature Areas 108----------------------------- 109However, ``pw_chre`` users will likely want to implement their own 110Platform Abstraction Layers (PALs). For more information see this 111`implementation guide <https://android.googlesource.com/platform/system/chre/+/refs/heads/main/doc/porting_guide.md#implementing-optional-feature-areas-e_g_pals>`_. 112 113.. list-table:: List of PALs 114 :widths: 1 1 115 :header-rows: 1 116 117 * - PAL Name 118 - Pigweed implementation available 119 * - Audio 120 - ❌ 121 * - Bluetooth 122 - ❌ 123 * - GNSS 124 - ❌ 125 * - Sensor 126 - ❌ 127 * - Wifi 128 - ❌ 129 * - WWAN 130 - ❌ 131 132 133For more information on a specific PAL see 134`the PAL headers <https://cs.android.com/android/platform/superproject/+/main:system/chre/pal/include/chre/pal/>`_ 135or the `Linux reference PAL implementations <https://cs.android.com/android/platform/superproject/+/main:system/chre/platform/linux/>`_. 136