XLS provides a several interpreters to assist in design validation across our functional stack, from input DSLX down to the netlist level.
The DSLX interpreter (
//xls/dslx:interpreter_main) operates on
.x files that contain both the design and unit tests to execute (present
#[test] annotated functions).
The adler32 example
demonstrates this: the design is encapsulated in the
mod functions, and the samples are present in the test
(note that unit-style tests/interpretations of
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.
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
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 add function in
one would run the following:
bazel build -c opt //xls/tools:eval_ir_main ./bazel-bin/xls/tools/eval_ir_main \ --input '(bits: 0x0, bits:0x7F, bits:0x0); (bits: 0x0, bits:0x80, bits:0x200000)' \ ./bazel-bin/xls/dslx/stdlib/float32_add.opt.ir
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.
Finally, compiled netlists can also be interpreted against input samples via the
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
messages, that contain much-abridged cell descriptions. The
tool can automatically perform this extraction for
cell library descriptions.