1 VIXL: AArch64 Runtime Code Generation Library Version 1.12 2 ========================================================== 3 4 Contents: 5 6 * Overview 7 * Licence 8 * Requirements 9 * Known limitations 10 * Usage 11 12 13 Overview 14 ======== 15 16 VIXL 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 26 The VIXL git repository can be found [on GitHub][vixl]. 27 28 Changes from previous versions of VIXL can be found in the 29 [Changelog](doc/changelog.md). 30 31 32 Licence 33 ======= 34 35 This software is covered by the licence described in the [LICENCE](LICENCE) 36 file. 37 38 39 Requirements 40 ============ 41 42 To 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 48 A 64-bit host machine is required, implementing an LP64 data model. VIXL has 49 been tested using GCC on AArch64 Debian, GCC and Clang on amd64 Ubuntu 50 systems. 51 52 To 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 57 Refer to the 'Usage' section for details. 58 59 60 Known Limitations 61 ================= 62 63 VIXL was developed for JavaScript engines so a number of features from A64 were 64 deemed 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 71 The VIXL simulator supports only those instructions that the VIXL assembler can 72 generate. The `doc` directory contains a 73 [list of supported instructions](doc/supported-instructions.md). 74 75 The VIXL simulator was developed to run on 64-bit amd64 platforms. Whilst it 76 builds and mostly works for 32-bit x86 platforms, there are a number of 77 floating-point operations which do not work correctly, and a number of tests 78 fail as a result. 79 80 Debug Builds 81 ------------ 82 83 Your project's build system must define `VIXL_DEBUG` (eg. `-DVIXL_DEBUG`) 84 when using a VIXL library that has been built with debug enabled. 85 86 Some classes defined in VIXL header files contain fields that are only present 87 in debug builds, so if `VIXL_DEBUG` is defined when the library is built, but 88 not defined for the header files included in your project, you will see runtime 89 failures. 90 91 Exclusive-Access Instructions 92 ----------------------------- 93 94 All exclusive-access instructions are supported, but the simulator cannot 95 accurately simulate their behaviour as described in the ARMv8 Architecture 96 Reference 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 106 The simulator tries to be strict, and implements the following restrictions that 107 the 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 116 Instructions 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 122 Usage 123 ===== 124 125 Running all Tests 126 ----------------- 127 128 The helper script `tools/test.py` will build and run every test that is provided 129 with VIXL, in both release and debug mode. It is a useful script for verifying 130 that all of VIXL's dependencies are in place and that VIXL is working as it 131 should. 132 133 By default, the `tools/test.py` script runs a linter to check that the source 134 code conforms with the code style guide, and to detect several common errors 135 that the compiler may not warn about. This is most useful for VIXL developers. 136 The 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 143 It 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` 145 option is implied if the VIXL project is a snapshot (with no `.git` directory). 146 147 148 Building and Running the Benchmarks 149 ----------------------------------- 150 151 There 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 157 Build 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 160 with an iteration count argument, for example `./bench-dataop_sim 10000000`. The 161 benchmarks do not report a result; time them using the UNIX `time` command. 162 163 Build 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 166 the same way as the simulator versions. 167 168 169 Getting Started 170 --------------- 171 172 A short introduction to using VIXL can be found [here](doc/getting-started.md). 173 Example source code is provided in the [examples](examples) directory. You can 174 build 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 178 Using VIXL 179 ---------- 180 181 In addition to [getting started](doc/getting-started.md) and the 182 [examples](examples), you can find documentation and guides on various topics 183 that 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
