1VIXL: ARMv8 Runtime Code Generation Library, Development Version
2================================================================
3
4Contents:
5
6 * Overview
7 * Licence
8 * Requirements
9 * Known limitations
10 * Usage
11
12
13Overview
14========
15
16VIXL contains three components.
17
18 1. Programmatic **assemblers** to generate A64, A32 or T32 code at runtime. The
19    assemblers abstract some of the constraints of each ISA; for example, most
20    instructions support any immediate.
21 2. **Disassemblers** that can print any instruction emitted by the assemblers.
22 3. A **simulator** that can simulate any instruction emitted by the A64
23    assembler. The simulator allows generated code to be run on another
24    architecture without the need for a full ISA model.
25
26The VIXL git repository can be found [on 'https://git.linaro.org'][vixl].
27
28Changes from previous versions of VIXL can be found in the
29[Changelog](doc/changelog.md).
30
31
32Licence
33=======
34
35This software is covered by the licence described in the [LICENCE](LICENCE)
36file.
37
38
39Requirements
40============
41
42To build VIXL the following software is required:
43
44 1. Python 2.7
45 2. SCons 2.0
46 3. GCC 4.8+ or Clang 3.4+
47
48A 64-bit host machine is required, implementing an LP64 data model. VIXL has
49been tested using GCC on AArch64 Debian, GCC and Clang on amd64 Ubuntu
50systems.
51
52To run the linter and code formatting stages of the tests, the following
53software is also required:
54
55 1. Git
56 2. [Google's `cpplint.py`][cpplint]
57 3. clang-format-3.8
58
59Refer to the 'Usage' section for details.
60
61
62Known Limitations for AArch64 code generation
63=============================================
64
65VIXL was developed for JavaScript engines so a number of features from A64 were
66deemed unnecessary:
67
68 * Limited rounding mode support for floating point.
69 * Limited support for synchronisation instructions.
70 * Limited support for system instructions.
71 * A few miscellaneous integer and floating point instructions are missing.
72
73The VIXL simulator supports only those instructions that the VIXL assembler can
74generate. The `doc` directory contains a
75[list of supported A64 instructions](doc/aarch64/supported-instructions-aarch64.md).
76
77The VIXL simulator was developed to run on 64-bit amd64 platforms. Whilst it
78builds and mostly works for 32-bit x86 platforms, there are a number of
79floating-point operations which do not work correctly, and a number of tests
80fail as a result.
81
82VIXL may not build using Clang 3.7, due to a compiler warning. A workaround is
83to disable conversion of warnings to errors, or to delete the offending
84`return` statement reported and rebuild. This problem will be fixed in the next
85release.
86
87Debug Builds
88------------
89
90Your project's build system must define `VIXL_DEBUG` (eg. `-DVIXL_DEBUG`)
91when using a VIXL library that has been built with debug enabled.
92
93Some classes defined in VIXL header files contain fields that are only present
94in debug builds, so if `VIXL_DEBUG` is defined when the library is built, but
95not defined for the header files included in your project, you will see runtime
96failures.
97
98Exclusive-Access Instructions
99-----------------------------
100
101All exclusive-access instructions are supported, but the simulator cannot
102accurately simulate their behaviour as described in the ARMv8 Architecture
103Reference Manual.
104
105 * A local monitor is simulated, so simulated exclusive loads and stores execute
106   as expected in a single-threaded environment.
107 * The global monitor is simulated by occasionally causing exclusive-access
108   instructions to fail regardless of the local monitor state.
109 * Load-acquire, store-release semantics are approximated by issuing a host
110   memory barrier after loads or before stores. The built-in
111   `__sync_synchronize()` is used for this purpose.
112
113The simulator tries to be strict, and implements the following restrictions that
114the ARMv8 ARM allows:
115
116 * A pair of load-/store-exclusive instructions will only succeed if they have
117   the same address and access size.
118 * Most of the time, cache-maintenance operations or explicit memory accesses
119   will clear the exclusive monitor.
120    * To ensure that simulated code does not depend on this behaviour, the
121      exclusive monitor will sometimes be left intact after these instructions.
122
123Instructions affected by these limitations:
124  `stxrb`, `stxrh`, `stxr`, `ldxrb`, `ldxrh`, `ldxr`, `stxp`, `ldxp`, `stlxrb`,
125  `stlxrh`, `stlxr`, `ldaxrb`, `ldaxrh`, `ldaxr`, `stlxp`, `ldaxp`, `stlrb`,
126  `stlrh`, `stlr`, `ldarb`, `ldarh`, `ldar`, `clrex`.
127
128
129Usage
130=====
131
132Running all Tests
133-----------------
134
135The helper script `tools/test.py` will build and run every test that is provided
136with VIXL, in both release and debug mode. It is a useful script for verifying
137that all of VIXL's dependencies are in place and that VIXL is working as it
138should.
139
140By default, the `tools/test.py` script runs a linter to check that the source
141code conforms with the code style guide, and to detect several common errors
142that the compiler may not warn about. This is most useful for VIXL developers.
143The linter has the following dependencies:
144
145 1. Git must be installed, and the VIXL project must be in a valid Git
146    repository, such as one produced using `git clone`.
147 2. `cpplint.py`, [as provided by Google][cpplint], must be available (and
148    executable) on the `PATH`.
149
150It is possible to tell `tools/test.py` to skip the linter stage by passing
151`--nolint`. This removes the dependency on `cpplint.py` and Git. The `--nolint`
152option is implied if the VIXL project is a snapshot (with no `.git` directory).
153
154Additionally, `tools/test.py` tests code formatting using `clang-format-3.8`.
155If you don't have `clang-format-3.8`, disable the test using the
156`--noclang-format` option.
157
158Also note that the tests for the tracing features depend upon external `diff`
159and `sed` tools. If these tools are not available in `PATH`, these tests will
160fail.
161
162Getting Started
163---------------
164
165We have separate guides for introducing VIXL, depending on what architecture you
166are targeting. A guide for working with AArch32 can be found
167[here][getting-started-aarch32], while the AArch64 guide is
168[here][getting-started-aarch64]. Example source code is provided in the
169[examples](examples) directory. You can build examples with either `scons
170aarch32_examples` or `scons aarch64_examples` from the root directory, or use
171`scons --help` to get a detailed list of available build targets.
172
173
174
175
176[cpplint]: http://google-styleguide.googlecode.com/svn/trunk/cpplint/cpplint.py
177           "Google's cpplint.py script."
178
179[vixl]: https://git.linaro.org/arm/vixl.git
180        "The VIXL repository at 'https://git.linaro.org'."
181
182[getting-started-aarch32]: doc/aarch32/getting-started-aarch32.md
183                           "Introduction to VIXL for AArch32."
184
185[getting-started-aarch64]: doc/aarch64/getting-started-aarch64.md
186                           "Introduction to VIXL for AArch64."
187