1VIXL: ARMv8 Runtime Code Generation Library 6.2.0 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 GitHub][vixl]. 28 29Build and Test Status 30--------------------- 31 32 * [](https://ci.linaro.org/job/linaro-art-vixlpresubmit/) Simulator 33 * [](https://ci.linaro.org/job/linaro-art-vixlpresubmit-native-armv8/) Native 34 * [](https://ci.linaro.org/job/linaro-art-vixlpresubmit-macos/) MacOS 35 36 37Licence 38======= 39 40This software is covered by the licence described in the [LICENCE](LICENCE) 41file. 42 43Contributions, as pull requests or via other means, are accepted under the terms 44of the same [LICENCE](LICENCE). 45 46Requirements 47============ 48 49To build VIXL the following software is required: 50 51 1. Python 2.7 52 2. SCons 2.0 53 3. GCC 4.8+ or Clang 4.0+ 54 55A 64-bit host machine is required, implementing an LP64 data model. VIXL has 56been tested using GCC on AArch64 Debian, GCC and Clang on amd64 Ubuntu 57systems. 58 59To run the linter and code formatting stages of the tests, the following 60software is also required: 61 62 1. Git 63 2. [Google's `cpplint.py`][cpplint] 64 3. clang-format-4.0 65 4. clang-tidy-4.0 66 67Refer to the 'Usage' section for details. 68 69Note that in Ubuntu 18.04, clang-tidy-4.0 will only work if the clang-4.0 70package is also installed. 71 72Supported Arm Architecture Features 73=================================== 74 75| Feature | VIXL CPUFeatures Flag | Notes | 76|------------|-----------------------|---------------------------------| 77| BTI | kBTI | Per-page enabling not supported | 78| DotProd | kDotProduct | | 79| FCMA | kFcma | | 80| FHM | kFHM | | 81| FP16 | kFPHalf, kNEONHalf | | 82| FRINTTS | kFrintToFixedSizedInt | | 83| FlagM | kFlagM | | 84| FlagM2 | kAXFlag | | 85| I8MM | kI8MM | | 86| JSCVT | kJSCVT | | 87| LOR | kLORegions | | 88| LRCPC | kRCpc | | 89| LRCPC2 | kRCpcImm | | 90| LSE | kAtomics | | 91| PAuth | kPAuth, kPAuthGeneric | Not ERETAA, ERETAB | 92| RAS | kRAS | | 93| RDM | kRDM | | 94| SVE | kSVE | | 95| SVE2 | kSVE2 | | 96| SVEBitPerm | kSVEBitPerm | | 97| SVEF32MM | kSVEF32MM | | 98| SVEF64MM | kSVEF64MM | | 99| SVEI8MM | kSVEI8MM | | 100 101Enable generating code for an architecture feature by combining a flag with 102the MacroAssembler's defaults. For example, to generate code for SVE, use 103`masm.GetCPUFeatures()->Combine(CPUFeatures::kSVE);`. 104 105See [the cpu features header file](src/cpu-features.h) for more information. 106 107 108Known Limitations 109================= 110 111VIXL was developed for JavaScript engines so a number of features from A64 were 112deemed unnecessary: 113 114 * Limited rounding mode support for floating point. 115 * Limited support for synchronisation instructions. 116 * Limited support for system instructions. 117 * A few miscellaneous integer and floating point instructions are missing. 118 119The VIXL simulator supports only those instructions that the VIXL assembler can 120generate. The `doc` directory contains a 121[list of supported A64 instructions](doc/aarch64/supported-instructions-aarch64.md). 122 123The VIXL simulator was developed to run on 64-bit amd64 platforms. Whilst it 124builds and mostly works for 32-bit x86 platforms, there are a number of 125floating-point operations which do not work correctly, and a number of tests 126fail as a result. 127 128Debug Builds 129------------ 130 131Your project's build system must define `VIXL_DEBUG` (eg. `-DVIXL_DEBUG`) 132when using a VIXL library that has been built with debug enabled. 133 134Some classes defined in VIXL header files contain fields that are only present 135in debug builds, so if `VIXL_DEBUG` is defined when the library is built, but 136not defined for the header files included in your project, you will see runtime 137failures. 138 139Exclusive-Access Instructions 140----------------------------- 141 142All exclusive-access instructions are supported, but the simulator cannot 143accurately simulate their behaviour as described in the ARMv8 Architecture 144Reference Manual. 145 146 * A local monitor is simulated, so simulated exclusive loads and stores execute 147 as expected in a single-threaded environment. 148 * The global monitor is simulated by occasionally causing exclusive-access 149 instructions to fail regardless of the local monitor state. 150 * Load-acquire, store-release semantics are approximated by issuing a host 151 memory barrier after loads or before stores. The built-in 152 `__sync_synchronize()` is used for this purpose. 153 154The simulator tries to be strict, and implements the following restrictions that 155the ARMv8 ARM allows: 156 157 * A pair of load-/store-exclusive instructions will only succeed if they have 158 the same address and access size. 159 * Most of the time, cache-maintenance operations or explicit memory accesses 160 will clear the exclusive monitor. 161 * To ensure that simulated code does not depend on this behaviour, the 162 exclusive monitor will sometimes be left intact after these instructions. 163 164Instructions affected by these limitations: 165 `stxrb`, `stxrh`, `stxr`, `ldxrb`, `ldxrh`, `ldxr`, `stxp`, `ldxp`, `stlxrb`, 166 `stlxrh`, `stlxr`, `ldaxrb`, `ldaxrh`, `ldaxr`, `stlxp`, `ldaxp`, `stlrb`, 167 `stlrh`, `stlr`, `ldarb`, `ldarh`, `ldar`, `clrex`. 168 169Security Considerations 170----------------------- 171 172VIXL allows callers to generate any code they want. The generated code is 173arbitrary, and can therefore call back into any other component in the process. 174As with any self-modifying code, vulnerabilities in the client or in VIXL itself 175could lead to arbitrary code generation. 176 177For performance reasons, VIXL's Assembler only performs debug-mode checking of 178instruction operands (such as immediate field encodability). This can minimise 179code-generation overheads for advanced compilers that already model instructions 180accurately, and might consider the Assembler's checks to be redundant. The 181Assembler should only be used directly where encodability is independently 182checked, and where fine control over all generated code is required. 183 184The MacroAssembler synthesises multiple-instruction sequences to support _some_ 185unencodable operand combinations. The MacroAssembler can provide a useful safety 186check in cases where the Assembler's precision is not required; an unexpected 187unencodable operand should result in a macro with the correct behaviour, rather 188than an invalid instruction. 189 190In general, the MacroAssembler handles operands which are likely to vary with 191user-supplied data, but does not usually handle inputs which are likely to be 192easily covered by tests. For example, move-immediate arguments are likely to be 193data-dependent, but register types (e.g. `x` vs `w`) are not. 194 195We recommend that _all_ users use the MacroAssembler, using `ExactAssemblyScope` 196to invoke the Assembler when specific instruction sequences are required. This 197approach is recommended even in cases where a compiler can model the 198instructions precisely, because, subject to the limitations described above, it 199offers an additional layer of protection against logic bugs in instruction 200selection. 201 202Bug reports 203=========== 204 205Bug reports may be made in the Issues section of GitHub, or sent to 206vixl@arm.com. Please provide any steps required to recreate a bug, along with 207build environment and host system information. 208 209Usage 210===== 211 212Running all Tests 213----------------- 214 215The helper script `tools/test.py` will build and run every test that is provided 216with VIXL, in both release and debug mode. It is a useful script for verifying 217that all of VIXL's dependencies are in place and that VIXL is working as it 218should. 219 220By default, the `tools/test.py` script runs a linter to check that the source 221code conforms with the code style guide, and to detect several common errors 222that the compiler may not warn about. This is most useful for VIXL developers. 223The linter has the following dependencies: 224 225 1. Git must be installed, and the VIXL project must be in a valid Git 226 repository, such as one produced using `git clone`. 227 2. `cpplint.py`, [as provided by Google][cpplint], must be available (and 228 executable) on the `PATH`. 229 230It is possible to tell `tools/test.py` to skip the linter stage by passing 231`--nolint`. This removes the dependency on `cpplint.py` and Git. The `--nolint` 232option is implied if the VIXL project is a snapshot (with no `.git` directory). 233 234Additionally, `tools/test.py` tests code formatting using `clang-format-4.0`, 235and performs static analysis using `clang-tidy-4.0`. If you don't have these 236tools, disable the test using `--noclang-format` or `--noclang-tidy`, 237respectively. 238 239Also note that the tests for the tracing features depend upon external `diff` 240and `sed` tools. If these tools are not available in `PATH`, these tests will 241fail. 242 243Getting Started 244--------------- 245 246We have separate guides for introducing VIXL, depending on what architecture you 247are targeting. A guide for working with AArch32 can be found 248[here][getting-started-aarch32], while the AArch64 guide is 249[here][getting-started-aarch64]. Example source code is provided in the 250[examples](examples) directory. You can build examples with either `scons 251aarch32_examples` or `scons aarch64_examples` from the root directory, or use 252`scons --help` to get a detailed list of available build targets. 253 254 255 256 257[cpplint]: https://github.com/google/styleguide/tree/gh-pages/cpplint 258 "Google's cpplint.py script." 259 260[vixl]: https://github.com/Linaro/vixl 261 "The VIXL repository on GitHub." 262 263[getting-started-aarch32]: doc/aarch32/getting-started-aarch32.md 264 "Introduction to VIXL for AArch32." 265 266[getting-started-aarch64]: doc/aarch64/getting-started-aarch64.md 267 "Introduction to VIXL for AArch64." 268