Skip to content

Latest commit

 

History

History
99 lines (77 loc) · 3.84 KB

interpreters.md

File metadata and controls

99 lines (77 loc) · 3.84 KB

Interpreters

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

[TOC]

DSLX

The DSLX interpreter (//xls/dslx:cpp_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:interpreter_main
./bazel-bin/xls/dslx/interpreter/interpreter_main \
  ./xls/examples/adler32.x

These two methods are equivalent.

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.