1VIXL: AArch64 Runtime Code Generation Library Version 1.4
2=========================================================
3
4Contents:
5
6 * Requirements
7 * Overview
8 * Known limitations
9 * Usage
10
11
12Requirements
13============
14
15To build VIXL the following software is required:
16
17 1. Python 2.7
18 2. SCons 2.0
19 3. GCC 4.4+
20
21A 64-bit host machine is required, implementing an LP64 data model. VIXL has
22only been tested using GCC on Ubuntu systems.
23
24To run the linter stage of the tests, the following software is also required:
25
26 1. Git
27 2. [Google's `cpplint.py`][cpplint]
28
29Refer to the 'Usage' section for details.
30
31
32Overview
33========
34
35VIXL is made of three components.
36
37 1. A programmatic assembler to generate A64 code at runtime. The assembler
38    abstracts some of the constraints of the A64 ISA, for example most
39    instructions support any immediate.
40 2. A disassembler which can print any instruction emitted by the assembler.
41 3. A simulator which can simulate any instruction emitted by the assembler.
42    The simulator allows generated code to be run on another architecture
43    without the need for a full ISA model.
44
45The VIXL git repository can be found [on GitHub][vixl]. Changes from previous
46versions of VIXL can be found in the [Changelog](doc/changelog.md).
47
48
49Known Limitations
50=================
51
52VIXL was developed to target JavaScript engines so a number of features from A64
53were deemed unnecessary:
54
55 * No Advanced SIMD support.
56 * Limited rounding mode support for floating point.
57 * Limited support for synchronisation instructions.
58 * Limited support for system instructions.
59 * A few miscellaneous integer and floating point instructions are missing.
60
61The VIXL simulator supports only those instructions that the VIXL assembler can
62generate. The `doc` directory contains a
63[list of supported instructions](doc/supported-instructions.md).
64
65The VIXL simulator was developed to run on 64-bit amd64 platforms. Whilst it
66builds and mostly works for 32-bit x86 platforms, there are a number of
67floating-point operations which do not work correctly, and a number of tests
68fail as a result.
69
70Usage
71=====
72
73
74Running all Tests
75-----------------
76
77The helper script `tools/presubmit.py` will build and run every test that is
78provided with VIXL, in both release and debug mode. It is a useful script for
79verifying that all of VIXL's dependencies are in place and that VIXL is working
80as it should.
81
82By default, the `tools/presubmit.py` script runs a linter to check that the
83source code conforms with the code style guide, and to detect several common
84errors that the compiler may not warn about. This is most useful for VIXL
85developers. The linter has the following dependencies:
86
87 1. Git must be installed, and the VIXL project must be in a valid Git
88    repository, such as one produced using `git clone`.
89 2. `cpplint.py`, [as provided by Google][cpplint], must be available (and
90    executable) on the `PATH`. Only revision 104 has been tested with VIXL.
91
92It is possible to tell `tools/presubmit.py` to skip the linter stage by passing
93`--nolint`. This removes the dependency on `cpplint.py` and Git. The `--nolint`
94option is implied if the VIXL project is a snapshot (with no `.git` directory).
95
96
97Building and Running the Benchmarks
98-----------------------------------
99
100There are two very basic benchmarks provided with VIXL:
101
102 1. bench\_dataop, emitting adds
103 2. bench\_branch, emitting branches
104
105To build one benchmark: `scons target=bench_xxx`, then run it as
106`./bench_xxx_sim <number of iterations>`. The benchmarks do not report a
107figure; they should be timed using the `time` command.
108
109
110Getting Started
111---------------
112
113A short introduction to using VIXL can be found [here](doc/getting-started.md).
114Example source code is provided in the `examples` directory. Build this using
115`scons target=examples` from the root directory.
116
117
118
119[cpplint]: https://google-styleguide.googlecode.com/svn-history/r104/trunk/cpplint/cpplint.py
120           "Google's cpplint.py script."
121
122[vixl]: https://github.com/armvixl/vixl
123        "The VIXL repository on GitHub."
124