Repository files navigation

Docs |Quick Start |Tutorials

Conda packages

XLS implements a High Level Synthesis toolchain that produces synthesizabledesigns (Verilog and SystemVerilog) from flexible, high-level descriptions offunctionality. It is Apache 2 licensed.

XLS (Accelerated HW Synthesis) aims to be the Software Development Kit (SDK) forthe End of Moore's Law (EoML) era. In this "age of specialization", software andhardware engineers must do more co-design across their domain boundaries --collaborate on shared artifacts, understand each other's cost models, and sharetooling/methodology. XLS attempts to leverage automation, software engineers,and machine cycles to accelerate this overall process.

XLS enables the rapid development ofhardware IP that also runs as efficienthost software via "software style" methodology. An XLS design runs at nativespeeds for use in host software or a simulator, but that design can alsogenerate hardware block output -- the XLS tools' correctness ensures (andprovides tools to help formally verify) that they are functionally identical.

XLS supports both (optionally pipelined) functions with pure-wire I/O interfacesandconcurrent processes(orprocs). Procs are stateful, allowing induction over time, and include moregeneral communication interfaces.

XLS is experimental, undergoing rapid development, and not an officiallysupported Google product. Expect bugs and sharp edges. Please help by trying itout, running throughsome tutorials,reporting bugs.

We are early stage and this has some practical effects:

• We welcome your issues and PRs.
  • Please try to lead with an issue. Engage us in conversation if you wish toupstream changes. Sending a PR without back and forth with us in an issuemay be a longer road to success. If you believe your PR is ready and hasnot received a response within two business days, please ping the issuewith what you think are next steps.
• At the current point in its evolution, we regularly improve DSLX withoutconsidering backward compatibility.
  • If you are building a corpus of hardware with XLS, please be thoughtfulabout your process for bringing in new versions of the compiler.

For a more setup-free and environment-independent way of trying out XLS, see ourcolab 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 evaluationenvironment that can run the following interactively:

  • XLS tests
  • XLS→IR conversion
  • IR→Verilog codegen
  • Verilog synthesis via Yosys (using open PDKs ASAP7 and SKY130)
  • Place-and-Route (P&R) via OpenROAD
  • Power/Performance/Area (PPA) metric collection

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 -s -L \  -H"Accept: application/vnd.github+json" \  -H"X-GitHub-Api-Version: 2022-11-28" \  https://api.github.com/repos/google/xls/releases| \  grep -m 1 -o'https://.*/releases/download/.*\.tar\.gz')# 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.gzcd 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), andthe available colab notebooks, XLS must be built from source using the Bazelbuild system.

The following instructions are for the Ubuntu 22.04 (Jammy Jellyfish) Linuxdistribution.

On an average 8-core VM:

• A full initial buildwithout the C++ front-end (e.g. "DSLX only") may takeabout 2 hours,
• Including the C++ front-end may take up to 6 hours.

Please see the two corresponding command lines below -- we start by assumingBazel has been installed:

~$ git clone https://github.com/google/xls.git~$ cd xls~/xls$ # Follow the bazel install instructions to install bazel 7~/xls$ # https://bazel.build/install/ubuntu~/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-dev libtinfo6 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 viaDockerfiles, ifyou have difficulty setting up the (limited set of) dependencies shown above inyour 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 likeccache to improve caching fora 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 fileswhere the results could have been cached locally - or where it might be safe toreuse certain intermediate results, even after abazel clean. To improve this,you can tell Bazel to use a shared "disk cache", storing files persistentlyelsewhere on disk; just create a directory somewhere (e.g.,~/.bazel_disk_cache/), and then run:

echo"build --disk_cache=$(realpath~/.bazel_disk_cache)">>~/.bazelrcecho"test --disk_cache=$(realpath~/.bazel_disk_cache)">>~/.bazelrc

!!! WARNINGBazel does not automate garbage collection of this directory, so itwill grow over time without bounds. You will need to clean it up periodically,either manually or with an automated script.

Alternatively, you can add aremote cachethat takes care of garbage collection for you. This can be hosted on a personalserver or even on the local machine. We've personally had good results withlocalhost instances ofbazel-remote.

Acompile_flags.txt file compatible with clangd and similar tools can becreated by runningxls/dev_tools/make-compilation-db.sh. Follow directions foryour editor to install clangd code completion.

Navigating a new code base can be daunting; the following description provides ahigh-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 forexternal dependencies of XLS.
• docs: Generateddocumentation served via GitHub pages:https://google.github.io/xls/
• docs_src: Markdownfile sources, rendered todocs viamkdocs.
• xls: Project-namedsubdirectory within the repository, in common Bazel-project style.
• build: Buildmacros that create XLS artifacts; e.g. convert DSL to IR, create testtargets for DSL code, etc.
• codegen:Verilog AST (VAST) support to generate Verilog/SystemVerilog operationsand FSMs. VAST is built up by components we callgenerators (e.g.PipelineGenerator, SequentialGenerator for FSMs) in the translation fromXLS IR.
• common: "base"functionality that layers on top of standard library usage. Generally weuseAbseil versions of base constructs whereverpossible.
• contrib/xlscc:Experimental C++ syntax support that targets XLS IR (alternative path toDSLX) developed by a sister team at Google, sharing the same open source/ testing flow as the rest of the XLS project. May be of particularinterest 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 forXLS IR operations on a target backend process. Already-characterizeddescriptions are placed inxls/estimators/delay_model/models and canbe referred to via command line flags.
• dslx: A DSL(called "DSLX") that mimics Rust, while being an immutableexpression-language dataflow DSL with hardware-oriented features; e.g.arbitrary bitwidths, entirely fixed size objects, fully analyzeable callgraph. XLS team has found dataflow DSLs are a good fit to describehardware as compared to languages designed assume von Neumann stylecomputation.
• fuzzer: Awhole-stack multiprocess fuzzer that generates programs at the DSL leveland cross-compares different execution engines (DSL interpreter, IRinterpreter, IR JIT, code-generated-Verilog simulator). Designed so thatit can easily be run on different nodes in a cluster simultaneously andaccumulate shared findings.
• examples:Example computations that are tested and executable through the XLSstack.
• experimental:Artifacts captured from experimental explorations.
• interpreter:Interpreter for XLS IR - useful for debugging and exploration. For casesneeding throughput, consider using the JIT (below).
• ir: XLS IRdefinition, text parser/formatter, and facilities for abstractevaluation.
• jit: LLVM-based JITfor XLS IR. Enables native-speed execution of DSLX and XLS IR programs.
• modules:Hardware building block DSLX "libraries" (outside the DSLX standardlibrary) that may be easily reused or instantiated in a broader design.
• netlist:Libraries that parse/analyze/interpret netlist-level descriptions, asare generally given in simple structural Verilog with an associated celllibrary.
• passes: Passesthat run on the XLS IR as part of optimization, before scheduling / codegeneration.
• scheduling:Scheduling algorithms, determine when operations execute (e.g. whichpipeline stage) in a clocked design.
• simulation:Code that wraps Verilog simulators and generates Verilog testbenches forXLS computations.iverilog iscurrently used to simulate as it supports non-synthesizable testbenchconstructs.
• solvers:Converters from XLS IR into SMT solver input, such that formal proofscan be run on XLS computations; e.g. Logical Equalence Checks betweenXLS IR and a netlist description.Z3is used as the solver engine.
• synthesis:Interface that wraps backend synthesis flows, such that tools can beretargeted e.g. between ASIC and FPGA flows.
• tests:Integration tests that span various top-level components of the XLSproject.
• tools:Many tools that work with the XLSsystem and its libraries in a decomposed way via command lineinterfaces.
• uncore_rtl:Helper RTL that interfaces XLS-generated blocks with device top-levelfor e.g. FPGA experiments.
• visualization:Visualization tools to inspect the XLS compiler/system interactively.SeeIR visualization.

Discussions about XLS - development, debugging, usage, etc:

• Ideally happen in theXLS repo GitHubdiscussions
• But, if you feel email is a better venue for the discussion, there is also anxls-dev mailing list -- please preferGitHub discussions if possible as they are searchable and can beeasily cross-referenced and converted to the issue tracker

The following arecontributors to the XLSproject, see ourcontributing documentation andgood firstissuesif you're interested in contributing, or reach out viaGitHubdiscussions!

• Albert Magyar
• Alex Light
• Amin Kalantar
• Balint Christian
• Blaok
• Brandon Jiang
• Brian Searls
• Chen-hao Chang
• Chris Drake
• Chris Leary
• Conor McCullough
• Dan Killebrew
• Derek Lockhart
• Eric Astor
• Ethan Mahintorabi
• Felix Zhu
• Georges Rotival
• Hanchen Ye
• Hans Montero
• Henner Zeller
• Iliyan Malchev
• Johan Euphrosine
• Jonathan Bailey
• Josh Varga
• Julian Viera
• Kevin Harlley
• Leonardo Romor
• Manav Kohli
• Mark Heffernan
• Paul Rigge
• Per Grön
• Philipp Schilk
• Ravi Nanavati
• Rebecca Chen (Pytype)
• Remy Goldschmidt
• Robert Hundt
• Rob Springer
• Sameer Agarwal
• Sean Purser-Haskell
• Ted Hong
• Ted Xie
• Tim Callahan
• Vincent Mirian