#xl-synth #xls #bindings #ir #dylib #value

xlsynth

Accelerated Hardware Synthesis (XLS/XLSynth) via Rust

101 releases

new 0.0.115 Apr 11, 2025
0.0.105 Mar 31, 2025
0.0.54 Dec 18, 2024
0.0.42 Nov 19, 2024
0.0.16 Jul 8, 2024

#75 in Audio

Download history 80/week @ 2024-12-22 67/week @ 2024-12-29 371/week @ 2025-01-05 373/week @ 2025-01-12 192/week @ 2025-01-19 722/week @ 2025-01-26 4145/week @ 2025-02-02 3613/week @ 2025-02-09 3783/week @ 2025-02-16 7365/week @ 2025-02-23 2577/week @ 2025-03-02 7727/week @ 2025-03-09 7634/week @ 2025-03-16 794/week @ 2025-03-23 990/week @ 2025-03-30 664/week @ 2025-04-06

10,723 downloads per month
Used in 3 crates

Apache-2.0

300KB
7.5K SLoC

XLS (AKA XLSynth) Rust Crate

Rust bindings to the functionality in the "Accelerated Hardware Synthesis" library.

use xlsynth::{DslxToIrPackageResult, IrValue, IrPackage, IrFunction, XlsynthError};

fn sample() -> Result<IrValue, XlsynthError> {
    let converted: DslxToIrPackageResult = xlsynth::convert_dslx_to_ir(
        "fn id(x: u32) -> u32 { x }",
        std::path::Path::new("/memfile/sample.x"),
        &xlsynth::DslxConvertOptions::default())?;
    assert!(converted.warnings.is_empty());
    let package: IrPackage = converted.ir;
    let mangled = xlsynth::mangle_dslx_name("sample", "id")?;
    let f: IrFunction = package.get_function(&mangled)?;
    let mol: IrValue = IrValue::make_ubits(32, 42)?;

    // Use the IR interpreter.
    let interp_result: IrValue = f.interpret(&[mol.clone()])?;

    // Use the IR JIT.
    let jit = xlsynth::IrFunctionJit::new(&f)?;
    let jit_result: xlsynth::RunResult = jit.run(&[mol])?;
    assert_eq!(jit_result.value, interp_result);

    Ok(jit_result.value)
}

fn main() {
    assert_eq!(sample().unwrap(), IrValue::make_ubits(32, 42).unwrap());
}

Project Structure

The xlsynth crate builds on top of the shared library libxls.{so,dylib} releases created in https://github.com/xlsynth/xlsynth/releases/ -- this is the underlying C/C++ core.

  • xlsynth-sys: wraps the shared library with Rust FFI bindings
  • xlsynth: provides Rust objects for interacting with core facilities; this includes:
    • DSLX parsing/typechecking, conversion to XLS IR
    • IR building
    • JIT compilation and IR interpretation
    • Creating Verilog AST directly for tools that need to do so
    • Building Rust and SystemVerilog bridges for interacting with XLS/DSLX artifacts
  • sample-usage: demonstrates use of the APIs provided by the xlsynth crate
  • xlsynth-estimator: Rust implementation of the XLS IR operation-level delay estimation methodology
  • xlsynth-g8r: experimental XLS IR to gate mapping library

Example Use

This shows sample use of the driver program which integrates XLS functionality for command line use:

echo 'fn f(x: u32, y: u32) -> u32 { x + y }' > /tmp/add.x
cargo run -p xlsynth-driver -- dslx2ir --dslx_input_file /tmp/add.x --dslx_top f > /tmp/add.ir
cargo run -p xlsynth-driver -- ir2gates /tmp/add.ir

Installing In Custom Environments

By default the crate attempts to download the shared library and DSLX standard library that it needs for out-of-the-box operation. However, this can also be specified manually at build time with the following environment variables:

cargo clean
export XLS_DSO_PATH=$HOME/opt/xlsynth/lib/libxls-v0.0.173-ubuntu2004.so
export DSLX_STDLIB_PATH=$HOME/opt/xlsynth/latest/xls/dslx/stdlib/
cargo build -vv -p xlsynth-sys |& grep "Using XLS_DSO_PATH"
export LD_LIBRARY_PATH=$HOME/opt/xlsynth/lib/:$LD_LIBRARY_PATH
cargo test --workspace

Development Notes

The xlsynth Rust crate leverages a dynamic library with XLS' core functionality (i.e. libxls.so / libxls.dylib).

The DSO is built and released for multiple platforms via GitHub actions at xlsynth/xlsynth/releases.

The version that this crate expects is described in xlsynth-sys/build.rs as RELEASE_LIB_VERSION_TAG. By default, this crate pulls the dynamic library from the targeted release.

To link against a local version of the public API, instead of a released version, supply the DEV_XLS_DSO_WORKSPACE environment variable pointing at the workspace root where the built shared library resides; e.g.

$ export DEV_XLS_DSO_WORKSPACE=$HOME/proj/xlsynth/
$ ls $DEV_XLS_DSO_WORKSPACE/bazel-bin/xls/public/libxls.* | egrep '(.dylib|.so)$'
/home/cdleary/proj/xlsynth//bazel-bin/xls/public/libxls.so
$ cargo clean  # Make sure we pick up the new env var.
$ cargo test -vv |& grep -i "DSO from workspace"
[xlsynth-sys ...] cargo:info=Using DSO from workspace: ...

Where in ~/proj/xlsynth/ (the root of the xlsynth workspace) we build the DSO with

bazel build -c opt //xls/public:libxls.so

Pre-Commit

The pre-commit tool is used to help with local checks before PRs are created:

sudo apt-get install pre-commit
pre-commit install
pre-commit run --all-files

This pre-commit step is also run as part of continuous integration.

Dependencies

~1–4MB
~65K SLoC