1# Context Hub Runtime Environment (CHRE)
2
3## Build Instructions
4
5Build targets are arranged in the form of a variant triple consisting of:
6
7``vendor_arch_variant``
8
9The vendor is the provider of the CHRE implementation (ex: google, qcom). The
10arch is the CPU architecture (ie: hexagonv60, x86, cm4). The variant is the
11target platform (ie: slpi, nanohub, linux, googletest).
12
13A debug build can be obtained by appending ``_debug`` to the variant triple. As
14an example:
15
16``make google_hexagonv62_slpi``
17``make google_hexagonv62_slpi_debug``
18
19### Linux
20
21CHRE is compatible with Linux as a simulator.
22
23#### Linux Build/Run
24
25The simulator has system dependencies:
26
27- TCLAP
28    - Command-line argument parsing.
29- libsndfile
30    - WAV file parsing for audio support.
31
32These 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
37The build target for x86 linux is ``google_x86_linux``. You can build/run the
38simulator with the following command:
39
40    ./run_sim.sh
41
42#### Linux Unit Tests
43
44You can run all unit tests with the following command. Pass arguments to this
45script 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
52CHRE is also compatible with Android as a simulator.
53
54This is not intended to be a production implementation but is suitable for
55testing CHRE nanoapps on the applications processor where Android runs. It uses
56Android NDK APIs to interact with the system.
57
58### SLPI Hexagon
59
60First, setup paths to the Hexagon Tools (v8.x.x), SDK (v3.0), and SLPI source
61tree, 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
67Then use the provided Makefiles to build:
68
69    make google_hexagonv62_slpi -j
70
71## Directory Structure
72
73The 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
106Within each of these directories, you may find a ``tests`` subdirectory
107containing tests written against the googletest framework.
108
109### Platform Directory Structure
110
111The platform directory contains an interface that common code under ``core``
112leverages to implement the runtime. All platforms are required to implement the
113interface provided in ``platform/include``.
114
115The 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
126Common 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
128implementation of the common platform API. This is handled by providing a stable
129include path and changing the search path for the platform implementation. Here
130is an example directory layout:
131
132- ``platform``
133    - ``<platform_name>``
134        - ``include``
135            - ``chre``
136                - ``target_platform``
137
138The build system will add ``platform/<platform_name>/include`` to the include
139search path allowing common code to find the implementation of the platform
140interface. Here is an example of core code including a platform-specific header
141in this way:
142
143``#include "chre/target_platform/log.h"``
144
145When 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
151This project includes a number of nanoapps that serve as both examples of how to
152use CHRE, debugging tools and can perform some useful function.
153
154All nanoapps in the ``apps`` directory are placed in a namespace when built
155statically with this CHRE implementation. When compiled as standalone nanoapps,
156there is no outer namespace on their entry points. This allows testing various
157CHRE subsystems without requiring dynamic loading and allows these nanoapps to
158coexist within a CHRE binary. Refer to ``apps/hello_world/hello_world.cc`` for
159a minimal example.
160
161### FeatureWorld
162
163Any of the nanoapps that end with the term World are intended to test some
164feature of the system. The HelloWorld nanoapp simply exercises logging
165functionality, TimerWorld exercises timers and WifiWorld uses wifi, for example.
166These nanoapps log all results via chreLog which makes them effective tools when
167bringing up a new CHRE implementation.
168
169### ImuCal
170
171This nanoapp implements IMU calibration.
172
173## Porting CHRE
174
175This codebase is intended to be ported to a variety of operating systems. If you
176wish to port CHRE to a new OS, refer to the ``platform`` directory. An example of
177the Linux port is provided under ``platform/linux``.
178
179There are notes regarding initialization under
180``platform/include/chre/platform/init.h`` that will also be helpful.
181
182### Important Considerations
183
184Platforms are required to implement support for invoking the constructors and
185destructors of global, non-POD types at load and unload time, respectively. This
186is required for both the runtime and nanoapps.
187
188## Coding conventions
189
190There are many well-established coding standards within Google. The official
191C++ style guide is used with the exception of Android naming conventions for
192methods and variables. This means 2 space indents, camelCase method names, an
193mPrefix on class members and so on. Style rules that are not specified in the
194Android style guide are inherited from Google.
195
196## CHRE Variants
197
198A CHRE variant allows injecting additional source files into the build on a
199per-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
208Export the ``CHRE_VARIANT_MK_INCLUDES`` containing the mk files that you wish to
209be 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
218This 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