NameDateSize

..11-Jun-20184 KiB

.gitignore11-Jun-20184

Android.bp11-Jun-20182.2 KiB

apps/11-Jun-20184 KiB

ash/11-Jun-20184 KiB

build/11-Jun-20184 KiB

bundle_chre.sh11-Jun-2018335

chre_api/11-Jun-20184 KiB

core/11-Jun-20184 KiB

external/11-Jun-20184 KiB

host/11-Jun-20184 KiB

Makefile11-Jun-20183.3 KiB

NOTICE11-Jun-201812 KiB

pal/11-Jun-20184 KiB

platform/11-Jun-20184 KiB

README.md11-Jun-20188.3 KiB

run_sim.sh11-Jun-2018327

run_tests.sh11-Jun-2018247

util/11-Jun-20184 KiB

variant/11-Jun-20184 KiB

README.md

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