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