1VIXL: AArch64 Runtime Code Generation Library Version 1.12
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. A programmatic **assembler** to generate A64 code at runtime. The assembler
19    abstracts some of the constraints of the A64 ISA; for example, most
20    instructions support any immediate.
21 2. A **disassembler** that can print any instruction emitted by the assembler.
22 3. A **simulator** that can simulate any instruction emitted by the assembler.
23    The simulator allows generated code to be run on another architecture
24    without the need for a full ISA model.
25
26The VIXL git repository can be found [on GitHub][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 stage of the tests, the following software is also required:
53
54 1. Git
55 2. [Google's `cpplint.py`][cpplint]
56
57Refer to the 'Usage' section for details.
58
59
60Known Limitations
61=================
62
63VIXL was developed for JavaScript engines so a number of features from A64 were
64deemed unnecessary:
65
66 * Limited rounding mode support for floating point.
67 * Limited support for synchronisation instructions.
68 * Limited support for system instructions.
69 * A few miscellaneous integer and floating point instructions are missing.
70
71The VIXL simulator supports only those instructions that the VIXL assembler can
72generate. The `doc` directory contains a
73[list of supported instructions](doc/supported-instructions.md).
74
75The VIXL simulator was developed to run on 64-bit amd64 platforms. Whilst it
76builds and mostly works for 32-bit x86 platforms, there are a number of
77floating-point operations which do not work correctly, and a number of tests
78fail as a result.
79
80Debug Builds
81------------
82
83Your project's build system must define `VIXL_DEBUG` (eg. `-DVIXL_DEBUG`)
84when using a VIXL library that has been built with debug enabled.
85
86Some classes defined in VIXL header files contain fields that are only present
87in debug builds, so if `VIXL_DEBUG` is defined when the library is built, but
88not defined for the header files included in your project, you will see runtime
89failures.
90
91Exclusive-Access Instructions
92-----------------------------
93
94All exclusive-access instructions are supported, but the simulator cannot
95accurately simulate their behaviour as described in the ARMv8 Architecture
96Reference Manual.
97
98 * A local monitor is simulated, so simulated exclusive loads and stores execute
99   as expected in a single-threaded environment.
100 * The global monitor is simulated by occasionally causing exclusive-access
101   instructions to fail regardless of the local monitor state.
102 * Load-acquire, store-release semantics are approximated by issuing a host
103   memory barrier after loads or before stores. The built-in
104   `__sync_synchronize()` is used for this purpose.
105
106The simulator tries to be strict, and implements the following restrictions that
107the ARMv8 ARM allows:
108
109 * A pair of load-/store-exclusive instructions will only succeed if they have
110   the same address and access size.
111 * Most of the time, cache-maintenance operations or explicit memory accesses
112   will clear the exclusive monitor.
113    * To ensure that simulated code does not depend on this behaviour, the
114      exclusive monitor will sometimes be left intact after these instructions.
115
116Instructions affected by these limitations:
117  `stxrb`, `stxrh`, `stxr`, `ldxrb`, `ldxrh`, `ldxr`, `stxp`, `ldxp`, `stlxrb`,
118  `stlxrh`, `stlxr`, `ldaxrb`, `ldaxrh`, `ldaxr`, `stlxp`, `ldaxp`, `stlrb`,
119  `stlrh`, `stlr`, `ldarb`, `ldarh`, `ldar`, `clrex`.
120
121
122Usage
123=====
124
125Running all Tests
126-----------------
127
128The helper script `tools/test.py` will build and run every test that is provided
129with VIXL, in both release and debug mode. It is a useful script for verifying
130that all of VIXL's dependencies are in place and that VIXL is working as it
131should.
132
133By default, the `tools/test.py` script runs a linter to check that the source
134code conforms with the code style guide, and to detect several common errors
135that the compiler may not warn about. This is most useful for VIXL developers.
136The linter has the following dependencies:
137
138 1. Git must be installed, and the VIXL project must be in a valid Git
139    repository, such as one produced using `git clone`.
140 2. `cpplint.py`, [as provided by Google][cpplint], must be available (and
141    executable) on the `PATH`.
142
143It is possible to tell `tools/test.py` to skip the linter stage by passing
144`--nolint`. This removes the dependency on `cpplint.py` and Git. The `--nolint`
145option is implied if the VIXL project is a snapshot (with no `.git` directory).
146
147
148Building and Running the Benchmarks
149-----------------------------------
150
151There are three very basic benchmarks provided with VIXL:
152
153 1. bench-dataop, emitting adds
154 2. bench-branch, emitting branches
155 3. bench-branch-link, emitting branch-links
156
157Build these benchmarks using `scons bench-dataop`, `scons bench-branch` and
158`scons bench-branch-link`. This will produce binaries called
159`bench-dataop_sim`, `bench-branch_sim` and `bench-branch-link_sim`. Run these
160with an iteration count argument, for example `./bench-dataop_sim 10000000`. The
161benchmarks do not report a result; time them using the UNIX `time` command.
162
163Build the benchmarks natively for execution on an AArch64 target using `scons
164<benchmark name> simulator=off`. This will produce binaries called
165`bench-dataop`, `bench-branch` and `bench-branch-link`. Run and time these in
166the same way as the simulator versions.
167
168
169Getting Started
170---------------
171
172A short introduction to using VIXL can be found [here](doc/getting-started.md).
173Example source code is provided in the [examples](examples) directory. You can
174build all the examples with `scons examples` from the root directory, or use
175`scons --help` to get a detailed list of available build targets.
176
177
178Using VIXL
179----------
180
181In addition to [getting started](doc/getting-started.md) and the
182[examples](examples), you can find documentation and guides on various topics
183that may be helpful [here](doc/topics/index.md).
184
185
186
187
188
189[cpplint]: http://google-styleguide.googlecode.com/svn/trunk/cpplint/cpplint.py
190           "Google's cpplint.py script."
191
192[vixl]: https://github.com/armvixl/vixl
193        "The VIXL repository on GitHub."
194