Skip to content

Interpreters

XLS provides a several interpreters to assist in design validation across our functional stack, from input DSLX down to the netlist level.

DSLX

The DSLX interpreter (//xls/dslx:interpreter_main) operates on DSLX .x files that contain both the design and unit tests to execute (present as #![test] annotated functions).

The adler32 example demonstrates this: the design is encapsulated in the main, adler32_seq, and mod functions, and the samples are present in the test adler32_one_char (note that unit-style tests/interpretations of adler32_seq and mod could also be present).

Interpreter targets are automatically generated for dslx_test() targets, so no special declarations are necessary to wrap DSLX code.

To invoke these samples, execute the following:

bazel build -c opt //xls/examples:adler32_dslx_test
./bazel-bin/xls/examples/adler32_dslx_test

To execute directly via the interpreter, you can instead run:

$ bazel build -c opt //xls/dslx/interpreter_main
$ ./bazel-bin/xls/dslx/interpreter_main \
    ./xls/examples/adler32.x

These two methods are equivalent.

Execution comparison

The DSL interpreter provides a flag, --compare, to implicitly compare its run results to those of the IR-converted DSL functions. This helps "spot check" consistency between IR and DSL execution (in addition to other methods used in more generally in XLS, like the fuzzer).

The user may compare DSL execution to IR interpreter execution, IR JIT execution, or not perform IR comparison at all.

$ ./bazel-bin/xls/dslx/interpreter_main \
    ./xls/examples/adler32.x --compare=jit
$ ./bazel-bin/xls/dslx/interpreter_main \
    ./xls/examples/adler32.x --compare=interpreter
$ ./bazel-bin/xls/dslx/interpreter_main \
    ./xls/examples/adler32.x --compare=none

IR

XLS provides two means of evaluating IR - interpretation and native host compilation (the JIT). Both are invoked in nearly the same way, via the eval_ir_main tool.

eval_ir_main supports a wide number of use cases, but the most common end-user case will be to run a sample through a design. To evaluate a sample (1.0 + 2.5) on the floating-point adder, one would run the following:

bazel build -c opt //xls/tools:eval_ir_main
./bazel-bin/xls/tools/eval_ir_main \
  --input '(bits[1]: 0x0, bits[8]:0x7F, bits[23]:0x0); (bits[1]: 0x0, bits[8]:0x80, bits[23]:0x200000)' \
  ./xls/modules/fpadd_2x32.x

By default, this runs via the JIT. To use the interpreter, add the --use_llvm_jit=false flag to the invocation.

eval_ir_main supports a broad set of options and modes of execution. Refer to its [very thorough] --help documentation for full details.

Netlists

Finally, compiled netlists can also be interpreted against input samples via the aptly-named netlist_interpreter_main tool. This tool currently only supports single sample evaluation (as illustrated in the IR section above):

bazel build -c opt //xls/tools:netlist_interpreter_main
./bazel-bin/xls/tools/netlist_interpreter_main \
  --netlist <path to netlist>
  --module  <module to evaluate>
  --cell_library[_proto] <path to the module's cell library [proto]>
  --inputs  <input sample, as above>

As XLS does not currently provide an sample/example netlist (TODO(rspringer)), concrete values can't [yet] be provided here. The --cell_library flag merits extra discussion, though.

During netlist compilation, a cell library is provided to indicate the individual logic cells available for the design, and these cells are referenced in the output netlist. The interpreter needs a description of these cells' behaviors/functions, so the cell library must be provided here, as well. Many cell libraries are very large (> 1GB), and can thus incur significant processing overhead at startup, so we also accept pre-processed cell libraries, as CellLibraryProto messages, that contain much-abridged cell descriptions. The function_extractor_main tool can automatically perform this extraction for Liberty-formatted cell library descriptions.