XLS: Accelerated HW Synthesis
Docs | Quick Start | Tutorials
XLS implements a High Level Synthesis toolchain that produces synthesizable designs (Verilog and SystemVerilog) from flexible, high-level descriptions of functionality. It is Apache 2 licensed.
XLS (Accelerated HW Synthesis) aims to be the Software Development Kit (SDK) for the End of Moore's Law (EoML) era. In this "age of specialization", software and hardware engineers must do more co-design across their domain boundaries -- collaborate on shared artifacts, understand each other's cost models, and share tooling/methodology. XLS attempts to leverage automation, software engineers, and machine cycles to accelerate this overall process.
XLS enables the rapid development of hardware IP that also runs as efficient host software via "software style" methodology. An XLS design runs at native speeds for use in host software or a simulator, but that design can also generate hardware block output -- the XLS tools' correctness ensures (and provides tools to help formally verify) that they are functionally identical.
XLS also supports concurrent processes, in Communicating Sequential Processes (CSP) style, that allow pipelines to communicate with each other and induct over time. This feature is still under active development but today supports base use cases.
XLS is experimental, undergoing rapid development, and not an officially supported Google product. Expect bugs and sharp edges. Please help by trying it out, running through some tutorials, reporting bugs.
We are early stage and this has some practical effects:
For a more setup-free and environment-independent way of trying out XLS, see our colab notebooks:
bit.ly/learn-xls: a "learn XLS in Y minutes" style walkthrough in DSLX, our Rust-inspired domain specific language (DSL).
bit.ly/xls-playground: an XLS evaluation environment that can run the following interactively:
The following downloads the latest github repo release binaries for an x64 Linux machine:
# Determine the url of the latest release tarball.
LATEST_XLS_RELEASE_TARBALL_URL=$(curl -L \
-H "Accept: application/vnd.github+json" \
-H "X-GitHub-Api-Version: 2022-11-28" \
https://api.github.com/repos/google/xls/releases | \
python3 -c 'import json; import sys; print(json.load(sys.stdin)[0]["assets"][0]["browser_download_url"])')
# Download the tarball and unpack it, observe the version numbers for each of the included tools.
curl -O -L ${LATEST_XLS_RELEASE_TARBALL_URL}
tar -xzvvf xls-*.tar.gz
cd xls-*/
./interpreter_main --version
./ir_converter_main --version
./opt_main --version
./codegen_main --version
./proto_to_dslx_main --version
Aside from the binary releases (available for x64 Linux as described above), and the available colab notebooks, XLS must be built from source using the Bazel build system.
The following instructions are for the Ubuntu 22.04 (Jammy Jellyfish) Linux distribution.
On an average 8-core VM:
Please see the two corresponding command lines below -- we start by assuming Bazel has been installed:
~$ git clone https://github.com/google/xls.git
~$ cd xls
~/xls$ # Follow the bazel install instructions:
~/xls$ # https://bazel.build/install/ubuntu
~/xls$ # If you do use bazelisk, be aware that documentation here generally uses `bazel`,
~/xls$ # so you may want to alias bazelisk to bazel.
~/xls$ # Afterwards we observe:
~/xls$ bazel --version
bazel 6.4.0
~/xls$ # Note we're going to tell Ubuntu that `/usr/bin/env python` is actually python3
~/xls$ # here, since that has not been the case by default on past Ubuntus.
~/xls$ # This is important. Without this step, you may experience cryptic error messages:
~/xls$ sudo apt install python3-distutils python3-dev libtinfo5 python-is-python3
~/xls$ # Now build/test in optimized build mode.
~/xls$ # If you don't plan on using the C++ front-end, which is not strictly
~/xls$ # needed (i.e. DSLX front-end only), use this command line:
~/xls$ bazel test -c opt -- //xls/... -//xls/contrib/xlscc/...
~/xls$ # To build everything, including the C++ front-end:
~/xls$ bazel test -c opt -- //xls/...
Reference build/test environment setups are also provided via Dockerfile
s, if
you have difficulty setting up the (limited set of) dependencies shown above in
your environment:
~$ git clone https://github.com/google/xls.git
~$ cd xls
~/xls$ docker build . -f Dockerfile-ubuntu-22.04 # Performs optimized build-and-test.
Many programmers are used to using programs like ccache
to improve caching for
a build, but Bazel actually ships with very-high quality caching layers.
In particular, incremental builds are more safe.
However, there are circumstances where Bazel might decide to recompile files
where the results could have been cached locally - or where it might be safe to
reuse certain intermediate results, even after a bazel clean
. To improve this,
you can tell Bazel to use a shared "disk cache", storing files persistently
elsewhere on disk; just create a directory somewhere (e.g.,
~/.bazel_disk_cache/
), and then run:
echo "build --disk_cache=$(realpath ~/.bazel_disk_cache)" >> ~/.bazelrc
echo "test --disk_cache=$(realpath ~/.bazel_disk_cache)" >> ~/.bazelrc
WARNING: Bazel does not automate garbage collection of this directory, so it will grow over time without bounds. You will need to clean it up periodically, either manually or with an automated script.
Alternatively, you can add a remote cache that takes care of garbage collection for you. This can be hosted on a personal server or even on the local machine. We've personally had good results with localhost instances of bazel-remote.
Navigating a new code base can be daunting; the following description provides a high-level view of the important directories and their intended organization / purpose, and correspond to the components in this XLS stack diagram:
dependency_support
:
Configuration files that load, build, and expose Bazel targets for external
dependencies of XLS.
docs
: Generated documentation
served via GitHub pages:
https://google.github.io/xls/
docs_src
: Markdown file
sources, rendered to docs
via
mkdocs.
xls
: Project-named
subdirectory within the repository, in common Bazel-project style.
build
: Build macros
that create XLS artifacts; e.g. convert DSL to IR, create test targets for
DSL code, etc.codegen
: Verilog
AST (VAST) support to generate Verilog/SystemVerilog operations and FSMs.
VAST is built up by components we call generators (e.g.
PipelineGenerator, SequentialGenerator for FSMs) in the translation from XLS
IR.common
: "base"
functionality that layers on top of standard library usage. Generally we use
Abseil versions of base constructs wherever possible.contrib/xlscc
:
Experimental C++ syntax support that targets XLS IR (alternative path to
DSLX) developed by a sister team at Google, sharing the same open source /
testing flow as the rest of the XLS project. May be of particular interest
for teams with existing C++ HLS code bases.data_structures
:
Generic data structures used in XLS that augment standard libraries; e.g.
BDDs, union find, min cut, etc.delay_model
:
Functionality to characterize, describe, and interpolate data delay for
XLS IR operations on a target backend process. Already-characterized
descriptions are placed in xls/delay_model/models
and can be referred to via
command line flags.dslx
: A DSL (called
"DSLX") that mimics Rust, while being an immutable expression-language
dataflow DSL with hardware-oriented features; e.g. arbitrary bitwidths,
entirely fixed size objects, fully analyzeable call graph. XLS team has found
dataflow DSLs are a good fit to describe hardware as compared to languages
designed assume von Neumann style computation.fuzzer
: A
whole-stack multiprocess fuzzer that generates programs at the DSL level and
cross-compares different execution engines (DSL interpreter, IR interpreter,
IR JIT, code-generated-Verilog simulator). Designed so that it can easily be
run on different nodes in a cluster simultaneously and accumulate shared
findings.examples
: Example
computations that are tested and executable through the XLS stack.experimental
:
Artifacts captured from experimental explorations.interpreter
:
Interpreter for XLS IR - useful for debugging and exploration. For cases
needing throughput, consider using the JIT (below).ir
:
XLS IR definition, text parser/formatter, and facilities for abstract
evaluation.jit
:
LLVM-based JIT for XLS IR. Enables native-speed execution of DSLX and XLS IR
programs.modules
:
Hardware building block DSLX "libraries" (outside the DSLX standard library)
that may be easily reused or instantiated in a broader design.netlist
: Libraries
that parse/analyze/interpret netlist-level descriptions, as are
generally given in simple structural Verilog with an associated cell library.passes
: Passes that
run on the XLS IR as part of optimization, before scheduling / code
generation.scheduling
:
Scheduling algorithms, determine when operations execute (e.g. which
pipeline stage) in a clocked design.simulation
:
Code that wraps Verilog simulators and generates Verilog testbenches for XLS
computations. iverilog is
currently used to simulate as it supports non-synthesizable testbench
constructs.solvers
:
Converters from XLS IR into SMT solver input, such that formal proofs can be
run on XLS computations; e.g. Logical Equalence Checks between XLS IR and a
netlist description. Z3 is used as the
solver engine.synthesis
:
Interface that wraps backend synthesis flows, such that tools can be
retargeted e.g. between ASIC and FPGA flows.tests
:
Integration tests that span various top-level components of the XLS project.tools
:
Many tools that work with the XLS
system and its libraries in a decomposed way via command line interfaces.uncore_rtl
:
Helper RTL that interfaces XLS-generated blocks with device top-level for e.g.
FPGA experiments.visualization
:
Visualization tools to inspect the XLS compiler/system interactively. See
IR visualization.Discussions about XLS - development, debugging, usage, etc:
The following are contributors to the XLS project, see our contributing documentation and good first issues if you're interested in contributing, or reach out via GitHub discussions!