1 VIXL: ARMv8 Runtime Code Generation Library, Development Version 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. 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 26 The VIXL git repository can be found [on 'https://git.linaro.org'][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 and code formatting stages of the tests, the following 53 software is also required: 54 55 1. Git 56 2. [Google's `cpplint.py`][cpplint] 57 3. clang-format-3.6 58 59 Refer to the 'Usage' section for details. 60 61 62 Known Limitations for AArch64 code generation 63 ============================================= 64 65 VIXL was developed for JavaScript engines so a number of features from A64 were 66 deemed 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 73 The VIXL simulator supports only those instructions that the VIXL assembler can 74 generate. The `doc` directory contains a 75 [list of supported A64 instructions](doc/aarch64/supported-instructions-aarch64.md). 76 77 The VIXL simulator was developed to run on 64-bit amd64 platforms. Whilst it 78 builds and mostly works for 32-bit x86 platforms, there are a number of 79 floating-point operations which do not work correctly, and a number of tests 80 fail as a result. 81 82 VIXL may not build using Clang 3.7, due to a compiler warning. A workaround is 83 to 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 85 release. 86 87 Debug Builds 88 ------------ 89 90 Your project's build system must define `VIXL_DEBUG` (eg. `-DVIXL_DEBUG`) 91 when using a VIXL library that has been built with debug enabled. 92 93 Some classes defined in VIXL header files contain fields that are only present 94 in debug builds, so if `VIXL_DEBUG` is defined when the library is built, but 95 not defined for the header files included in your project, you will see runtime 96 failures. 97 98 Exclusive-Access Instructions 99 ----------------------------- 100 101 All exclusive-access instructions are supported, but the simulator cannot 102 accurately simulate their behaviour as described in the ARMv8 Architecture 103 Reference 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 113 The simulator tries to be strict, and implements the following restrictions that 114 the 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 123 Instructions 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 129 Usage 130 ===== 131 132 Running all Tests 133 ----------------- 134 135 The helper script `tools/test.py` will build and run every test that is provided 136 with VIXL, in both release and debug mode. It is a useful script for verifying 137 that all of VIXL's dependencies are in place and that VIXL is working as it 138 should. 139 140 By default, the `tools/test.py` script runs a linter to check that the source 141 code conforms with the code style guide, and to detect several common errors 142 that the compiler may not warn about. This is most useful for VIXL developers. 143 The 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 150 It 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` 152 option is implied if the VIXL project is a snapshot (with no `.git` directory). 153 154 Additionally, `tools/test.py` tests code formatting using `clang-format-3.6`. 155 If you don't have `clang-format-3.6`, disable the test using the 156 `--noclang-format` option. 157 158 Also note that the tests for the tracing features depend upon external `diff` 159 and `sed` tools. If these tools are not available in `PATH`, these tests will 160 fail. 161 162 Getting Started 163 --------------- 164 165 We have separate guides for introducing VIXL, depending on what architecture you 166 are 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 170 aarch32_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
