Docs | Quick Start 
XLS implements a High Level Synthesis (HLS) toolchain which produces synthesizable designs (Verilog and SystemVerilog) from flexible, high-level descriptions of functionality. It is fully Open Source: Apache 2 licensed and developed via GitHub.
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.
In effect, XLS enables the rapid development of hardware IP that also runs as efficient host software via "software style" methodology. A single XLS source program runs at native speeds for use in host software or a simulator, but that source can also be used to generate hardware block output -- the XLS tools' correctness ensures (and provides tools to help formally verify) that they are functionally identical.
XLS is used inside of Google for generating feed-forward pipelines from "building block" routines / libraries that can be easily retargeted, reused, and composed in a latency-insensitive manner.
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 still 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, and letting us know what you think!
curl -O https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh -p conda-env/ -b
source conda-env/bin/activate
conda install --yes -c litex-hub xls
interpreter_main --version
ir_converter_main --version
opt_main --version
codegen_main --versionCurrently, XLS must be built from source using the Bazel build system.
Note: Binary distributions of the XLS library are not currently available, but we hope to enable them via continuous integration, see this issue.
The following instructions are for the Ubuntu 20.04 (Focal Fossa) and Ubuntu 22.04 (Jammy Jellyfish) Linux distributions.
We start by assuming Bazel has been installed. On an average 8-core VM, a full initial build (including the C++ frontend) may take up to 6 hours. A build without the C++ frontend may take about 2 hours. Please see the two corresponding command lines below:
~$ git clone https://github.com/google/xls.git
~$ cd xls
~/xls$ # Follow the bazel install instructions:
~/xls$ # https://bazel.build/install/ubuntu
~/xls$ # Afterwards we observe:
~/xls$ bazel --version
bazel 5.2.0
~/xls$ # Note we're going to tell Ubuntu that `/usr/bin/env python` is actually python3
~/xls$ # here, since that is not the case by default on Ubuntu 20.04.
~/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++ frontend, which is not needed to get started,
~/xls$ # use this command line:
~/xls$ bazel test -c opt -- //xls/... -//xls/contrib/xlscc/...
~/xls$ # To build everything, including the C++ frontend:
~/xls$ bazel test -c opt -- //xls/...The build needs Python3 to be available. If your python3 binary is at an
unusual location, you can tell bazel by providing a command line flag
--repo_env PYTHON_BIN_PATH=/path/to/python3 for bazel to find python3.
Reference build/test environment setups are also provided via Dockerfiles:
~$ git clone https://github.com/google/xls.git
~$ cd xls
~/xls$ # Several Dockerfiles are available to choose from:
~/xls$ docker build . -f Dockerfile-ubuntu-20.04 # Performs optimized build and test.
~/xls$ docker build . -f Dockerfile-ubuntu-20.10
~/xls$ docker build . -f Dockerfile-ubuntu-22.04Navigating 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 todocsvia 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 inxls/delay_model/modelsand 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, and anything else - should go to the xls-dev mailing list.
The following are contributors to the XLS project, see our contributing documentation and good first issues!
- Albert Magyar
- Amin Kalantar
- Balint Christian
- Blaok
- Brandon Jiang
- Brian Searls
- Chen-hao Chang
- Chris Drake
- Chris Leary
- Dan Killebrew
- Derek Lockhart
- Eric Astor
- Ethan Mahintorabi
- Felix Zhu
- Georges Rotival
- Hans Montero
- Iliyan Malchev
- Johan Euphrosine
- Jonathan Bailey
- Josh Varga
- Julian Viera
- Kevin Harlley
- Leonardo Romor
- Manav Kohli
- Mark Heffernan
- Paul Rigge
- Per Grön
- Ravi Nanavati
- Rebecca Chen (Pytype)
- Remy Goldschmidt
- Robert Hundt
- Rob Springer
- Sameer Agarwal
- Sean Purser-Haskell
- Ted Hong
- Ted Xie
- Vincent Mirian