1VIXL: ARMv8 Runtime Code Generation Library, Development Version 2================================================================ 3 4Contents: 5 6 * Overview 7 * Licence 8 * Requirements 9 * Known limitations 10 * Bug reports 11 * Usage 12 13 14Overview 15======== 16 17VIXL contains three components. 18 19 1. Programmatic **assemblers** to generate A64, A32 or T32 code at runtime. The 20 assemblers abstract some of the constraints of each ISA; for example, most 21 instructions support any immediate. 22 2. **Disassemblers** that can print any instruction emitted by the assemblers. 23 3. A **simulator** that can simulate any instruction emitted by the A64 24 assembler. The simulator allows generated code to be run on another 25 architecture without the need for a full ISA model. 26 27The VIXL git repository can be found [on 'https://git.linaro.org'][vixl]. 28 29Changes from previous versions of VIXL can be found in the 30[Changelog](doc/changelog.md). 31 32 33Licence 34======= 35 36This software is covered by the licence described in the [LICENCE](LICENCE) 37file. 38 39 40Requirements 41============ 42 43To build VIXL the following software is required: 44 45 1. Python 2.7 46 2. SCons 2.0 47 3. GCC 4.8+ or Clang 4.0+ 48 49A 64-bit host machine is required, implementing an LP64 data model. VIXL has 50been tested using GCC on AArch64 Debian, GCC and Clang on amd64 Ubuntu 51systems. 52 53To run the linter and code formatting stages of the tests, the following 54software is also required: 55 56 1. Git 57 2. [Google's `cpplint.py`][cpplint] 58 3. clang-format-4.0 59 4. clang-tidy-4.0 60 61Refer to the 'Usage' section for details. 62 63Note that in Ubuntu 18.04, clang-tidy-4.0 will only work if the clang-4.0 64package is also installed. 65 66 67Known Limitations 68================= 69 70VIXL was developed for JavaScript engines so a number of features from A64 were 71deemed unnecessary: 72 73 * Limited rounding mode support for floating point. 74 * Limited support for synchronisation instructions. 75 * Limited support for system instructions. 76 * A few miscellaneous integer and floating point instructions are missing. 77 78The VIXL simulator supports only those instructions that the VIXL assembler can 79generate. The `doc` directory contains a 80[list of supported A64 instructions](doc/aarch64/supported-instructions-aarch64.md). 81 82The VIXL simulator was developed to run on 64-bit amd64 platforms. Whilst it 83builds and mostly works for 32-bit x86 platforms, there are a number of 84floating-point operations which do not work correctly, and a number of tests 85fail as a result. 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 128Security Considerations 129----------------------- 130 131VIXL allows callers to generate any code they want. The generated code is 132arbitrary, and can therefore call back into any other component in the process. 133As with any self-modifying code, vulnerabilities in the client or in VIXL itself 134could lead to arbitrary code generation. 135 136For performance reasons, VIXL's Assembler only performs debug-mode checking of 137instruction operands (such as immediate field encodability). This can minimise 138code-generation overheads for advanced compilers that already model instructions 139accurately, and might consider the Assembler's checks to be redundant. The 140Assembler should only be used directly where encodability is independently 141checked, and where fine control over all generated code is required. 142 143The MacroAssembler synthesises multiple-instruction sequences to support _some_ 144unencodable operand combinations. The MacroAssembler can provide a useful safety 145check in cases where the Assembler's precision is not required; an unexpected 146unencodable operand should result in a macro with the correct behaviour, rather 147than an invalid instruction. 148 149In general, the MacroAssembler handles operands which are likely to vary with 150user-supplied data, but does not usually handle inputs which are likely to be 151easily covered by tests. For example, move-immediate arguments are likely to be 152data-dependent, but register types (e.g. `x` vs `w`) are not. 153 154We recommend that _all_ users use the MacroAssembler, using `ExactAssemblyScope` 155to invoke the Assembler when specific instruction sequences are required. This 156approach is recommended even in cases where a compiler can model the 157instructions precisely, because, subject to the limitations described above, it 158offers an additional layer of protection against logic bugs in instruction 159selection. 160 161Bug reports 162=========== 163 164Bug reports may be sent to vixl@arm.com. Please provide any steps required to 165recreate a bug, along with build environment and host system information. 166 167 168Usage 169===== 170 171Running all Tests 172----------------- 173 174The helper script `tools/test.py` will build and run every test that is provided 175with VIXL, in both release and debug mode. It is a useful script for verifying 176that all of VIXL's dependencies are in place and that VIXL is working as it 177should. 178 179By default, the `tools/test.py` script runs a linter to check that the source 180code conforms with the code style guide, and to detect several common errors 181that the compiler may not warn about. This is most useful for VIXL developers. 182The linter has the following dependencies: 183 184 1. Git must be installed, and the VIXL project must be in a valid Git 185 repository, such as one produced using `git clone`. 186 2. `cpplint.py`, [as provided by Google][cpplint], must be available (and 187 executable) on the `PATH`. 188 189It is possible to tell `tools/test.py` to skip the linter stage by passing 190`--nolint`. This removes the dependency on `cpplint.py` and Git. The `--nolint` 191option is implied if the VIXL project is a snapshot (with no `.git` directory). 192 193Additionally, `tools/test.py` tests code formatting using `clang-format-4.0`, 194and performs static analysis using `clang-tidy-4.0`. If you don't have these 195tools, disable the test using `--noclang-format` or `--noclang-tidy`, 196respectively. 197 198Also note that the tests for the tracing features depend upon external `diff` 199and `sed` tools. If these tools are not available in `PATH`, these tests will 200fail. 201 202Getting Started 203--------------- 204 205We have separate guides for introducing VIXL, depending on what architecture you 206are targeting. A guide for working with AArch32 can be found 207[here][getting-started-aarch32], while the AArch64 guide is 208[here][getting-started-aarch64]. Example source code is provided in the 209[examples](examples) directory. You can build examples with either `scons 210aarch32_examples` or `scons aarch64_examples` from the root directory, or use 211`scons --help` to get a detailed list of available build targets. 212 213 214 215 216[cpplint]: http://google-styleguide.googlecode.com/svn/trunk/cpplint/cpplint.py 217 "Google's cpplint.py script." 218 219[vixl]: https://git.linaro.org/arm/vixl.git 220 "The VIXL repository at 'https://git.linaro.org'." 221 222[getting-started-aarch32]: doc/aarch32/getting-started-aarch32.md 223 "Introduction to VIXL for AArch32." 224 225[getting-started-aarch64]: doc/aarch64/getting-started-aarch64.md 226 "Introduction to VIXL for AArch64." 227