This software is covered by the licence described in the LICENCE file.
Contributions, as pull requests or via other means, are accepted under the terms of the same LICENCE.
To build VIXL the following software is required:
A 64-bit host machine is required, implementing an LP64 data model. VIXL has been tested using GCC on AArch64 Debian, GCC and Clang on amd64 Ubuntu systems.
To run the linter and code formatting stages of the tests, the following software is also required:
Refer to the ‘Usage’ section for details.
Note that in Ubuntu 18.04, clang-tidy-4.0 will only work if the clang-4.0 package is also installed.
|Feature||VIXL CPUFeatures Flag||Notes|
|BTI||kBTI||Per-page enabling not supported|
|PAuth||kPAuth, kPAuthGeneric||Not ERETAA, ERETAB|
Enable generating code for an architecture feature by combining a flag with the MacroAssembler's defaults. For example, to generate code for SVE, use
See the cpu features header file for more information.
The VIXL simulator supports only those instructions that the VIXL assembler can generate. The
doc directory contains a list of supported A64 instructions.
The VIXL simulator was developed to run on 64-bit amd64 platforms. Whilst it builds and mostly works for 32-bit x86 platforms, there are a number of floating-point operations which do not work correctly, and a number of tests fail as a result.
Your project's build system must define
-DVIXL_DEBUG) when using a VIXL library that has been built with debug enabled.
Some classes defined in VIXL header files contain fields that are only present in debug builds, so if
VIXL_DEBUG is defined when the library is built, but not defined for the header files included in your project, you will see runtime failures.
All exclusive-access instructions are supported, but the simulator cannot accurately simulate their behaviour as described in the ARMv8 Architecture Reference Manual.
__sync_synchronize()is used for this purpose.
The simulator tries to be strict, and implements the following restrictions that the ARMv8 ARM allows:
Instructions affected by these limitations:
VIXL allows callers to generate any code they want. The generated code is arbitrary, and can therefore call back into any other component in the process. As with any self-modifying code, vulnerabilities in the client or in VIXL itself could lead to arbitrary code generation.
For performance reasons, VIXL‘s Assembler only performs debug-mode checking of instruction operands (such as immediate field encodability). This can minimise code-generation overheads for advanced compilers that already model instructions accurately, and might consider the Assembler’s checks to be redundant. The Assembler should only be used directly where encodability is independently checked, and where fine control over all generated code is required.
The MacroAssembler synthesises multiple-instruction sequences to support some unencodable operand combinations. The MacroAssembler can provide a useful safety check in cases where the Assembler's precision is not required; an unexpected unencodable operand should result in a macro with the correct behaviour, rather than an invalid instruction.
In general, the MacroAssembler handles operands which are likely to vary with user-supplied data, but does not usually handle inputs which are likely to be easily covered by tests. For example, move-immediate arguments are likely to be data-dependent, but register types (e.g.
w) are not.
We recommend that all users use the MacroAssembler, using
ExactAssemblyScope to invoke the Assembler when specific instruction sequences are required. This approach is recommended even in cases where a compiler can model the instructions precisely, because, subject to the limitations described above, it offers an additional layer of protection against logic bugs in instruction selection.
Bug reports may be made in the Issues section of GitHub, or sent to email@example.com. Please provide any steps required to recreate a bug, along with build environment and host system information.
The helper script
tools/test.py will build and run every test that is provided with VIXL, in both release and debug mode. It is a useful script for verifying that all of VIXL's dependencies are in place and that VIXL is working as it should.
By default, the
tools/test.py script runs a linter to check that the source code conforms with the code style guide, and to detect several common errors that the compiler may not warn about. This is most useful for VIXL developers. The linter has the following dependencies:
cpplint.py, as provided by Google, must be available (and executable) on the
It is possible to tell
tools/test.py to skip the linter stage by passing
--nolint. This removes the dependency on
cpplint.py and Git. The
--nolint option is implied if the VIXL project is a snapshot (with no
tools/test.py tests code formatting using
clang-format-4.0, and performs static analysis using
clang-tidy-4.0. If you don't have these tools, disable the test using
Also note that the tests for the tracing features depend upon external
sed tools. If these tools are not available in
PATH, these tests will fail.
We have separate guides for introducing VIXL, depending on what architecture you are targeting. A guide for working with AArch32 can be found here, while the AArch64 guide is here. Example source code is provided in the examples directory. You can build examples with either
scons aarch32_examples or
scons aarch64_examples from the root directory, or use
scons --help to get a detailed list of available build targets.