You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
227 lines
8.6 KiB
227 lines
8.6 KiB
VIXL: ARMv8 Runtime Code Generation Library, Development Version
|
|
================================================================
|
|
|
|
Contents:
|
|
|
|
* Overview
|
|
* Licence
|
|
* Requirements
|
|
* Known limitations
|
|
* Bug reports
|
|
* Usage
|
|
|
|
|
|
Overview
|
|
========
|
|
|
|
VIXL contains three components.
|
|
|
|
1. Programmatic **assemblers** to generate A64, A32 or T32 code at runtime. The
|
|
assemblers abstract some of the constraints of each ISA; for example, most
|
|
instructions support any immediate.
|
|
2. **Disassemblers** that can print any instruction emitted by the assemblers.
|
|
3. A **simulator** that can simulate any instruction emitted by the A64
|
|
assembler. The simulator allows generated code to be run on another
|
|
architecture without the need for a full ISA model.
|
|
|
|
The VIXL git repository can be found [on 'https://git.linaro.org'][vixl].
|
|
|
|
Changes from previous versions of VIXL can be found in the
|
|
[Changelog](doc/changelog.md).
|
|
|
|
|
|
Licence
|
|
=======
|
|
|
|
This software is covered by the licence described in the [LICENCE](LICENCE)
|
|
file.
|
|
|
|
|
|
Requirements
|
|
============
|
|
|
|
To build VIXL the following software is required:
|
|
|
|
1. Python 2.7
|
|
2. SCons 2.0
|
|
3. GCC 4.8+ or Clang 4.0+
|
|
|
|
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:
|
|
|
|
1. Git
|
|
2. [Google's `cpplint.py`][cpplint]
|
|
3. clang-format-4.0
|
|
4. clang-tidy-4.0
|
|
|
|
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.
|
|
|
|
|
|
Known Limitations
|
|
=================
|
|
|
|
VIXL was developed for JavaScript engines so a number of features from A64 were
|
|
deemed unnecessary:
|
|
|
|
* Limited rounding mode support for floating point.
|
|
* Limited support for synchronisation instructions.
|
|
* Limited support for system instructions.
|
|
* A few miscellaneous integer and floating point instructions are missing.
|
|
|
|
The VIXL simulator supports only those instructions that the VIXL assembler can
|
|
generate. The `doc` directory contains a
|
|
[list of supported A64 instructions](doc/aarch64/supported-instructions-aarch64.md).
|
|
|
|
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.
|
|
|
|
Debug Builds
|
|
------------
|
|
|
|
Your project's build system must define `VIXL_DEBUG` (eg. `-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.
|
|
|
|
Exclusive-Access Instructions
|
|
-----------------------------
|
|
|
|
All exclusive-access instructions are supported, but the simulator cannot
|
|
accurately simulate their behaviour as described in the ARMv8 Architecture
|
|
Reference Manual.
|
|
|
|
* A local monitor is simulated, so simulated exclusive loads and stores execute
|
|
as expected in a single-threaded environment.
|
|
* The global monitor is simulated by occasionally causing exclusive-access
|
|
instructions to fail regardless of the local monitor state.
|
|
* Load-acquire, store-release semantics are approximated by issuing a host
|
|
memory barrier after loads or before stores. The built-in
|
|
`__sync_synchronize()` is used for this purpose.
|
|
|
|
The simulator tries to be strict, and implements the following restrictions that
|
|
the ARMv8 ARM allows:
|
|
|
|
* A pair of load-/store-exclusive instructions will only succeed if they have
|
|
the same address and access size.
|
|
* Most of the time, cache-maintenance operations or explicit memory accesses
|
|
will clear the exclusive monitor.
|
|
* To ensure that simulated code does not depend on this behaviour, the
|
|
exclusive monitor will sometimes be left intact after these instructions.
|
|
|
|
Instructions affected by these limitations:
|
|
`stxrb`, `stxrh`, `stxr`, `ldxrb`, `ldxrh`, `ldxr`, `stxp`, `ldxp`, `stlxrb`,
|
|
`stlxrh`, `stlxr`, `ldaxrb`, `ldaxrh`, `ldaxr`, `stlxp`, `ldaxp`, `stlrb`,
|
|
`stlrh`, `stlr`, `ldarb`, `ldarh`, `ldar`, `clrex`.
|
|
|
|
Security Considerations
|
|
-----------------------
|
|
|
|
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. `x` vs `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
|
|
===========
|
|
|
|
Bug reports may be sent to vixl@arm.com. Please provide any steps required to
|
|
recreate a bug, along with build environment and host system information.
|
|
|
|
|
|
Usage
|
|
=====
|
|
|
|
Running all Tests
|
|
-----------------
|
|
|
|
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:
|
|
|
|
1. Git must be installed, and the VIXL project must be in a valid Git
|
|
repository, such as one produced using `git clone`.
|
|
2. `cpplint.py`, [as provided by Google][cpplint], must be available (and
|
|
executable) on the `PATH`.
|
|
|
|
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 `.git` directory).
|
|
|
|
Additionally, `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 `--noclang-format` or `--noclang-tidy`,
|
|
respectively.
|
|
|
|
Also note that the tests for the tracing features depend upon external `diff`
|
|
and `sed` tools. If these tools are not available in `PATH`, these tests will
|
|
fail.
|
|
|
|
Getting Started
|
|
---------------
|
|
|
|
We have separate guides for introducing VIXL, depending on what architecture you
|
|
are targeting. A guide for working with AArch32 can be found
|
|
[here][getting-started-aarch32], while the AArch64 guide is
|
|
[here][getting-started-aarch64]. Example source code is provided in the
|
|
[examples](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.
|
|
|
|
|
|
|
|
|
|
[cpplint]: http://google-styleguide.googlecode.com/svn/trunk/cpplint/cpplint.py
|
|
"Google's cpplint.py script."
|
|
|
|
[vixl]: https://git.linaro.org/arm/vixl.git
|
|
"The VIXL repository at 'https://git.linaro.org'."
|
|
|
|
[getting-started-aarch32]: doc/aarch32/getting-started-aarch32.md
|
|
"Introduction to VIXL for AArch32."
|
|
|
|
[getting-started-aarch64]: doc/aarch64/getting-started-aarch64.md
|
|
"Introduction to VIXL for AArch64."
|