1 # Context Hub Runtime Environment (CHRE) 2 3 ## Build Instructions 4 5 Build targets are arranged in the form of a variant triple consisting of: 6 7 ``vendor_arch_variant`` 8 9 The vendor is the provider of the CHRE implementation (ex: google, qcom). The 10 arch is the CPU architecture (ie: hexagonv60, x86, cm4). The variant is the 11 target platform (ie: slpi, nanohub, linux, googletest). 12 13 A debug build can be obtained by appending ``_debug`` to the variant triple. As 14 an example: 15 16 ``make google_hexagonv62_slpi`` 17 ``make google_hexagonv62_slpi_debug`` 18 19 ### Linux 20 21 CHRE is compatible with Linux as a simulator. 22 23 #### Linux Build/Run 24 25 The simulator has system dependencies: 26 27 - TCLAP 28 - Command-line argument parsing. 29 - libsndfile 30 - WAV file parsing for audio support. 31 32 These are the commands to install these dependencies for Ubuntu: 33 34 sudo apt-get install libtclap-dev 35 sudo apt-get install libsndfile1-dev 36 37 The build target for x86 linux is ``google_x86_linux``. You can build/run the 38 simulator with the following command: 39 40 ./run_sim.sh 41 42 #### Linux Unit Tests 43 44 You can run all unit tests with the following command. Pass arguments to this 45 script and they are passed to the gtest framework. (example: 46 ``--gtest_filter=DynamicVector.*``) 47 48 ./run_tests.sh 49 50 ### CHRE Simulator for Android 51 52 CHRE is also compatible with Android as a simulator. 53 54 This is not intended to be a production implementation but is suitable for 55 testing CHRE nanoapps on the applications processor where Android runs. It uses 56 Android NDK APIs to interact with the system. 57 58 ### SLPI Hexagon 59 60 First, setup paths to the Hexagon Tools (v8.x.x), SDK (v3.0), and SLPI source 61 tree, for example: 62 63 export HEXAGON_TOOLS_PREFIX=~/Qualcomm/HEXAGON_Tools/8.0 64 export HEXAGON_SDK_PREFIX=~/Qualcomm/Hexagon_SDK/3.0 65 export SLPI_PREFIX=~/Qualcomm/msm8998/slpi_proc 66 67 Then use the provided Makefiles to build: 68 69 make google_hexagonv62_slpi -j 70 71 ## Directory Structure 72 73 The CHRE project is organized as follows: 74 75 - ``chre_api`` 76 - The stable API exposed to nanoapps 77 - ``core`` 78 - Common code that applies to all CHRE platforms, most notably event 79 management. 80 - ``pal`` 81 - An abstraction layer that implementers must supply to access 82 device-specific functionality (such as GPS and Wi-Fi). The PAL is a C API 83 which allows it to be implemented using a vendor-supplied library. 84 - ``platform`` 85 - Contains the system interface that all plaforms must implement, along with 86 implementations for individual platforms. This includes the implementation 87 of the CHRE API. 88 - ``platform/shared`` 89 - Contains code that will apply to multiple platforms, but not 90 necessarily all. 91 - ``platform/linux`` 92 - This directory contains the canonical example for running CHRE on 93 desktop machines, primarily for simulation and testing. 94 - ``apps`` 95 - A small number of sample applications are provided. These are intended to 96 guide developers of new applications and help implementers test basic 97 functionality quickly. 98 - This is reference code and is not required for the CHRE to function. 99 - ``util`` 100 - Contains data structures used throughout CHRE and common utility code. 101 - ``variant/simulator`` 102 - Contains the CHRE variant for the simulator. This is a good example to 103 start from when porting to new devices. Variants are explained in more 104 detail below. 105 106 Within each of these directories, you may find a ``tests`` subdirectory 107 containing tests written against the googletest framework. 108 109 ### Platform Directory Structure 110 111 The platform directory contains an interface that common code under ``core`` 112 leverages to implement the runtime. All platforms are required to implement the 113 interface provided in ``platform/include``. 114 115 The following gives a more detailed explanation of the directory structure. 116 117 - ``platform`` - The top-level directory for platform-specific code. 118 - ``include`` - The interface that platforms are required to implement. 119 - ``shared`` - Code that may be shared by more than one platform but not 120 necessarily required for all. 121 - ``slpi`` - The implementation of the common interface for the SLPI and any 122 SLPI-specific code. 123 - ``linux`` - The implementation of the common interface for the simulator 124 running on Linux and any simulator-specific code. 125 126 Common CHRE code that is expected to run across all platforms is located in 127 ``core``. This code must have a stable way to access the platform-specific 128 implementation of the common platform API. This is handled by providing a stable 129 include path and changing the search path for the platform implementation. Here 130 is an example directory layout: 131 132 - ``platform`` 133 - ``<platform_name>`` 134 - ``include`` 135 - ``chre`` 136 - ``target_platform`` 137 138 The build system will add ``platform/<platform_name>/include`` to the include 139 search path allowing common code to find the implementation of the platform 140 interface. Here is an example of core code including a platform-specific header 141 in this way: 142 143 ``#include "chre/target_platform/log.h"`` 144 145 When building for the linux platform, the file is included from: 146 147 ``platform/linux/include/chre/target_platform/log.h`` 148 149 ## Supplied Nanoapps 150 151 This project includes a number of nanoapps that serve as both examples of how to 152 use CHRE, debugging tools and can perform some useful function. 153 154 All nanoapps in the ``apps`` directory are placed in a namespace when built 155 statically with this CHRE implementation. When compiled as standalone nanoapps, 156 there is no outer namespace on their entry points. This allows testing various 157 CHRE subsystems without requiring dynamic loading and allows these nanoapps to 158 coexist within a CHRE binary. Refer to ``apps/hello_world/hello_world.cc`` for 159 a minimal example. 160 161 ### FeatureWorld 162 163 Any of the nanoapps that end with the term World are intended to test some 164 feature of the system. The HelloWorld nanoapp simply exercises logging 165 functionality, TimerWorld exercises timers and WifiWorld uses wifi, for example. 166 These nanoapps log all results via chreLog which makes them effective tools when 167 bringing up a new CHRE implementation. 168 169 ### ImuCal 170 171 This nanoapp implements IMU calibration. 172 173 ## Porting CHRE 174 175 This codebase is intended to be ported to a variety of operating systems. If you 176 wish to port CHRE to a new OS, refer to the ``platform`` directory. An example of 177 the Linux port is provided under ``platform/linux``. 178 179 There are notes regarding initialization under 180 ``platform/include/chre/platform/init.h`` that will also be helpful. 181 182 ### Important Considerations 183 184 Platforms are required to implement support for invoking the constructors and 185 destructors of global, non-POD types at load and unload time, respectively. This 186 is required for both the runtime and nanoapps. 187 188 ## Coding conventions 189 190 There are many well-established coding standards within Google. The official 191 C++ style guide is used with the exception of Android naming conventions for 192 methods and variables. This means 2 space indents, camelCase method names, an 193 mPrefix on class members and so on. Style rules that are not specified in the 194 Android style guide are inherited from Google. 195 196 ## CHRE Variants 197 198 A CHRE variant allows injecting additional source files into the build on a 199 per-device basis. This can be used to inject: 200 201 * A version string 202 * Set to ``undefined`` if not specified 203 * A static nanoapp list 204 * Empty if left undefined 205 * Additional static nanoapp includes 206 * Vendor-specific nanoapps could be specified in the variant 207 208 Export the ``CHRE_VARIANT_MK_INCLUDES`` containing the mk files that you wish to 209 be included the CHRE variant build. Refer to ``run_sim.sh`` and the 210 ``variant/simulator`` subdirectory for an example as used by the simulator. 211 212 * [Google C++ Style][1] 213 214 [1]: https://google.github.io/styleguide/cppguide.html 215 216 ### Use of C++ 217 218 This project uses C++11, but with two main caveats: 219 220 1. General considerations for using C++ in an embedded environment apply. This 221 means avoiding language features that can impose runtime overhead should 222 be avoided, due to the relative scarcity of memory and CPU resources, and 223 power considerations. Examples include RTTI, exceptions, overuse of dynamic 224 memory allocation, etc. Refer to existing literature on this topic 225 including this [Technical Report on C++ Performance][2] and so on. 226 2. Support of C++ standard libraries are not generally expected to be 227 extensive or widespread in the embedded environments where this code will 228 run. That means that things like <thread> and <mutex> should not be used, 229 in favor of simple platform abstractions that can be implemented directly 230 with less effort (potentially using those libraries if they are known to be 231 available). 232 233 [2]: http://www.open-std.org/jtc1/sc22/wg21/docs/TR18015.pdf 234