Skip to content

Bazel Rules And Macros

check_sha256sum_frozen

check_sha256sum_frozen(name, src, frozen_file, sha256sum)

Produces a frozen file if the sha256sum checksum of a source file matches a user-defined checksum.

As projects cut releases or freeze, it's important to know that generated (e.g. Verilog) code is never changing without having to actually check in the generated artifact. This rule performs a checksum of a generated file as an integrity check. Users might use this rule to help enable confidence that there is neither:

  • non-determinism in the toolchain, nor
  • an accidental dependence on a non-released toolchain (e.g. an accidental dependence on top-of-tree, where the toolchain is constantly changing)

Say there was a codegen rule producing my_output.v, a user might instantiate something like:

check_sha256sum_frozen(
    name = "my_output_checksum",
    src = ":my_output.v",
    sha256sum = "d1bc8d3ba4afc7e109612cb73acbdddac052c93025aa1f82942edabb7deb82a1",
    frozen_file = "my_output.frozen.x",
)

... and then take a dependency on my_output.frozen.v in the surrounding project, knowing that it had been checksum-verified.

Taking a dependence on my_output.v directly may also be ok if the :my_output_checksum target is also built (e.g. via the same wildcard build request), but taking a dependence on the output .frozen.v file ensures that the checking is an integral part of the downstream build-artifact-creation process.

At its core, this rule ensure that the contents of a file does not change by verifying that it matches a given checksum. Typically, this rule is used to control the build process. The rule serves as a trigger on rules depending on its output (the frozen file). When the validation of the sha256sum succeed, rules depending on the frozen file are built/executed. When the validation of the sha256sum fails, rules depending on the frozen file are not built/executed.

In the example below, when the validation of the sha256sum for target 'generated_file_sha256sum_frozen' succeeds, target 'generated_file_dslx' is built. However, when the validation of the sha256sum for target 'generated_file_sha256sum_frozen' fails, target 'generated_file_dslx' is not built.

Examples:

  1. A simple example.
    check_sha256sum_frozen(
        name = "generated_file_sha256sum_frozen",
        src = ":generated_file.x",
        sha256sum = "6522799f7b64dbbb2a31eb2862052b8988e78821d8b61fff7f508237a9d9f01d",
        frozen_file = "generated_file.frozen.x",
    )
    
    dslx_library(
        name = "generated_file_dslx",
        src = ":generated_file.frozen.x",
    )
    

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
src The source file. Label required
frozen_file The frozen output file. Label required
sha256sum The sha256sum of the source file. String required

check_sha256sum_test

check_sha256sum_test(name, src, sha256sum)

Validates the sha256sum checksum of a source file with a user-defined checksum.

This rule is typically used to ensure that the contents of a file is unchanged.

Examples:

  1. A simple example.
    check_sha256sum_test(
        name = "generated_file_sha256sum_test",
        src = ":generated_file.x",
        sha256sum = "6522799f7b64dbbb2a31eb2862052b8988e78821d8b61fff7f508237a9d9f01d",
    )
    

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
src The source file. Label required
sha256sum The sha256sum of the source file. String required

proto_data

proto_data(name, src, proto_name, protobin_file)

Converts a proto text with a xlscc.HLSBlock message to a proto binary.

This rules is used in conjunction with the (e.g. xls_cc_ir and xls_cc_verilog) rules and xls_cc_* (e.g. xls_cc_ir_macro and xls_cc_verilog_macro) macros.

Examples:

  1. A simple example.
    proto_data(
        name = "packet_selector_block_pb",
        src = "packet_selector.textproto",
    )
    

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
src The source file. Label required
proto_name The name of the message type in the .proto files that 'src' file represents. String optional "xlscc.HLSBlock"
protobin_file The name of the output file to write binary proto to. If not specified, the target name of the bazel rule followed by a .protobin extension is used. Label optional None

xls_benchmark_verilog

xls_benchmark_verilog(name, verilog_target)

Computes and prints various metrics about a Verilog target.

Example:

xls_benchmark_verilog(
    name = "a_benchmark",
    verilog_target = "a_verilog_target",
)

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
verilog_target The verilog target to benchmark. Label optional None

xls_delay_model_generation

xls_delay_model_generation(name, samples_file, standard_cells)

Builds a script to generate an XLS delay model for one PDK corner.

This rule gathers the locations of the required dependencies (Yosys, OpenSTA, helper scripts, and cell libraries) and generates a wrapper script that invokes "run_timing_characterization" with the dependency locations provided as args.

Any extra runtime args will get passed in to the "run_timing_characterization" script (e.g. "--debug" or "--quick_run").

The script must be "run" from the root of the workspace to perform the timing characterization. The output textproto will be produced in the current directory (which, as just stated, must be the root of the workspace).

Currently, only a subset of XLS operators are characterized, including most arithmetic, logical, and shift operators. However, many common operators such as "concat", "bit_slice", and "encode" are missing, and so the delay model that is currently produced should be considered INCOMPLETE.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
samples_file Proto providing sample points. Label optional None
standard_cells Target for the PDK; will use the target's default corner. Label optional None

xls_dslx_library

xls_dslx_library(name, deps, srcs, warnings_as_errors)

A build rule that parses and type checks DSLX source files.

Examples:

  1. A collection of DSLX source files.

    xls_dslx_library(
        name = "files_123_dslx",
        srcs = [
            "file_1.x",
            "file_2.x",
            "file_3.x",
        ],
    )
    
  2. Dependency on other xls_dslx_library targets.

    xls_dslx_library(
        name = "a_dslx",
        srcs = ["a.x"],
    )
    
    # Depends on target a_dslx.
    xls_dslx_library(
        name = "b_dslx",
        srcs = ["b.x"],
        deps = [":a_dslx"],
    )
    
    # Depends on target a_dslx.
    xls_dslx_library(
        name = "c_dslx",
        srcs = ["c.x"],
        deps = [":a_dslx"],
    )
    

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps Dependency targets for the rule. List of labels optional []
srcs Source files for the rule. Files must have a '.x' extension. List of labels optional []
warnings_as_errors Whether warnings are errors within this library definition. Boolean optional False

xls_dslx_opt_ir_test

xls_dslx_opt_ir_test(name, benchmark_ir_args, dep, dslx_test_args, input_validator,
                     input_validator_expr, ir_equivalence_args, ir_eval_args,
                     scheduling_options_proto, top)

A build rule that tests a xls_dslx_opt_ir target.

Executes the test commands for the following rules in the order presented:

  1. xls_dslx_test
  2. xls_ir_equivalence_test
  3. xls_eval_ir_test
  4. xls_benchmark_ir

Examples:

  1. A simple example.
    xls_dslx_opt_ir(
        name = "a_opt_ir",
        srcs = ["a.x"],
        dslx_top = "a",
    )
    
    xls_dslx_opt_ir_test(
        name = "a_opt_ir_test",
        dep = ":a_opt_ir",
    )
    

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
benchmark_ir_args Arguments of the benchmark IR tool. For details on the arguments, refer to the benchmark_main application at //xls/tools/benchmark_main.cc. Dictionary: String -> String optional {}
dep The xls_dslx_opt_ir target to test. Label optional None
dslx_test_args Arguments of the DSLX interpreter executable. For details on the arguments, refer to the interpreter_main application at //xls/dslx/interpreter_main.cc. Dictionary: String -> String optional {}
input_validator The DSLX library defining the input validator for this test. Mutually exclusive with "input_validator_expr". Label optional None
input_validator_expr The expression to validate an input for the test function. Mutually exclusive with "input_validator". String optional ""
ir_equivalence_args Arguments of the IR equivalence tool. For details on the arguments, refer to the check_ir_equivalence_main application at //xls/tools/check_ir_equivalence_main.cc. The 'function' argument is not assigned using this attribute. Dictionary: String -> String optional {}
ir_eval_args Arguments of the IR interpreter. For details on the arguments, refer to the eval_ir_main application at //xls/tools/eval_ir_main.cc.The 'top' argument is not assigned using this attribute. Dictionary: String -> String optional {"random_inputs": "100", "optimize_ir": "true"}
scheduling_options_proto Protobuf filename of scheduling arguments to the benchmark IR tool. For details on the arguments, refer to the benchmark_main application at //xls/tools/benchmark_main.cc. Label optional None
top The (mangled) name of the entry point. See get_mangled_ir_symbol. Defines the 'top' argument of the IR tool/application. String optional ""

xls_dslx_prove_quickcheck_test

xls_dslx_prove_quickcheck_test(name, deps, srcs, library, test_filter)

Attempts to prove DSLX quickcheck properties with a SAT solver.

Examples:

  1. xls_dslx_prove_quickcheck_test on DSLX source files.

    # Assume a xls_dslx_library target bc_dslx is present.
    xls_dslx_prove_quickcheck_test(
        name = "e_dslx_quickcheck_test",
        srcs = [
            "d.x",
            "e.x",
        ],
        deps = [":bc_dslx"],
    )
    
  2. xls_dslx_prove_quickcheck_test on a xls_dslx_library.

    xls_dslx_library(
        name = "b_dslx",
        srcs = ["b.x"],
        deps = [":a_dslx"],
    )
    
    xls_dslx_prove_quickcheck_test(
        name = "b_dslx_test",
        library = "b_dslx",
    )
    

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps Dependency targets for the files in the 'srcs' attribute. This attribute is mutually exclusive with the 'library' attribute. List of labels optional []
srcs Source files for the rule. The files must have a '.x' extension. This attribute is mutually exclusive with the 'library' attribute. List of labels optional []
library A DSLX library target where the direct (non-transitive) files of the target are tested. This attribute is mutually exclusive with the 'srcs' and 'deps' attribute. Label optional None
test_filter Regex to select quickcheck tests to run. String optional ""

xls_dslx_test

xls_dslx_test(name, deps, srcs, dslx_test_args, library)

A dslx test executes the tests and quick checks of a DSLX source file.

Examples:

  1. xls_dslx_test on DSLX source files.

    # Assume a xls_dslx_library target bc_dslx is present.
    xls_dslx_test(
        name = "e_dslx_test",
        srcs = [
            "d.x",
            "e.x",
        ],
        deps = [":bc_dslx"],
    )
    
  2. xls_dslx_test on a xls_dslx_library.

    xls_dslx_library(
        name = "b_dslx",
        srcs = ["b.x"],
        deps = [":a_dslx"],
    )
    
    xls_dslx_test(
        name = "b_dslx_test",
        library = "b_dslx",
    )
    

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps Dependency targets for the files in the 'srcs' attribute. This attribute is mutually exclusive with the 'library' attribute. List of labels optional []
srcs Source files for the rule. The files must have a '.x' extension. This attribute is mutually exclusive with the 'library' attribute. List of labels optional []
dslx_test_args Arguments of the DSLX interpreter executable. For details on the arguments, refer to the interpreter_main application at //xls/dslx/interpreter_main.cc. Dictionary: String -> String optional {}
library A DSLX library target where the direct (non-transitive) files of the target are tested. This attribute is mutually exclusive with the 'srcs' and 'deps' attribute. Label optional None

xls_eval_ir_test

xls_eval_ir_test(name, src, input_validator, input_validator_expr, ir_eval_args, top)

Executes the IR interpreter on an IR file.

Examples:

  1. A file as the source.

    xls_eval_ir_test(
        name = "a_eval_ir_test",
        src = "a.ir",
    )
    
  2. An xls_ir_opt_ir target as the source.

    xls_ir_opt_ir(
        name = "a_opt_ir",
        src = "a.ir",
    )
    
    
    xls_eval_ir_test(
        name = "a_eval_ir_test",
        src = ":a_opt_ir",
    )
    

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
src The IR source file for the rule. A single source file must be provided. The file must have a '.ir' extension. Label required
input_validator The DSLX library defining the input validator for this test. Mutually exclusive with "input_validator_expr". Label optional None
input_validator_expr The expression to validate an input for the test function. Mutually exclusive with "input_validator". String optional ""
ir_eval_args Arguments of the IR interpreter. For details on the arguments, refer to the eval_ir_main application at //xls/tools/eval_ir_main.cc.The 'top' argument is not assigned using this attribute. Dictionary: String -> String optional {"random_inputs": "100", "optimize_ir": "true"}
top The (mangled) name of the entry point. See get_mangled_ir_symbol. Defines the 'top' argument of the IR tool/application. String optional ""

xls_ir_equivalence_test

xls_ir_equivalence_test(name, ir_equivalence_args, src_0, src_1, top)

Executes the equivalence tool on two IR files.

Examples:

  1. A file as the source.

    xls_ir_equivalence_test(
        name = "ab_ir_equivalence_test",
        src_0 = "a.ir",
        src_1 = "b.ir",
    )
    
  2. A target as the source.

    xls_dslx_ir(
        name = "b_ir",
        srcs = ["b.x"],
    )
    
    xls_ir_equivalence_test(
        name = "ab_ir_equivalence_test",
        src_0 = "a.ir",
        src_1 = ":b_ir",
    )
    

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
ir_equivalence_args Arguments of the IR equivalence tool. For details on the arguments, refer to the check_ir_equivalence_main application at //xls/tools/check_ir_equivalence_main.cc. The 'function' argument is not assigned using this attribute. Dictionary: String -> String optional {}
src_0 An IR source file for the rule. A single source file must be provided. The file must have a '.ir' extension. Label required
src_1 An IR source file for the rule. A single source file must be provided. The file must have a '.ir' extension. Label required
top The (mangled) name of the entry point. See get_mangled_ir_symbol. Defines the 'top' argument of the IR tool/application. String optional ""

xls_ir_verilog_fdo

xls_ir_verilog_fdo(name, src, outs, block_ir_file, codegen_args, codegen_options_proto,
                   module_sig_file, schedule_file, schedule_ir_file, scheduling_options_proto,
                   sta_tool, standard_cells, verilog_file, verilog_line_map_file, yosys_tool)

A build rule that generates a Verilog file from an IR file using FDO (feedback-directed optimization). Codegen args to activate FDO and provide required dependencies are automatically provided. Default values for FDO parameters are provided but can be overridden in "codegen_args {...}".

In FDO mode, the codegen_arg "clock_period_ps" MUST be provided.

Example:

```
xls_ir_verilog_fdo(
    name = "a_verilog",
    src = "a.ir",
    codegen_args = {
        "clock_period_ps": "750",
        "fdo_iteration_number": "5",
        ...
    },
)
```

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
src The IR source file for the rule. A single source file must be provided. The file must have a '.ir' extension. Label required
outs The list of generated files. List of strings optional []
block_ir_file The filename of block-level IR file generated during codegen. If not specified, the basename of the Verilog file followed by a .block.ir extension is used. Label optional None
codegen_args Arguments of the codegen tool. For details on the arguments, refer to the codegen_main application at //xls/tools/codegen_main.cc. Dictionary: String -> String optional {}
codegen_options_proto Filename of a protobuf with arguments of the codegen tool. For details on the arguments, refer to the codegen_main application at //xls/tools/codegen_main.cc. Label optional None
module_sig_file The filename of module signature of the generated Verilog file. If not specified, the basename of the Verilog file followed by a .sig.textproto extension is used. Label optional None
schedule_file The filename of schedule of the generated Verilog file.If not specified, the basename of the Verilog file followed by a .schedule.textproto extension is used. Label optional None
schedule_ir_file The filename of scheduled IR file generated during scheduled. If not specified, the basename of the Verilog file followed by a .schedule.opt.ir extension is used. Label optional None
scheduling_options_proto Filename of a protobuf with scheduling options arguments of the codegen tool. For details on the arguments, refer to the codegen_main application at //xls/tools/codegen_main.cc. Label optional None
sta_tool - Label optional "@org_theopenroadproject//:opensta"
standard_cells - Label optional "@com_google_skywater_pdk_sky130_fd_sc_hd//:sky130_fd_sc_hd"
verilog_file The filename of Verilog file generated. The filename must have a v extension. Label required
verilog_line_map_file The filename of line map for the generated Verilog file.If not specified, the basename of the Verilog file followed by a .verilog_line_map.textproto extension is used. Label optional None
yosys_tool - Label optional "//third_party/yosys"

cc_xls_ir_jit_wrapper

cc_xls_ir_jit_wrapper(name, src, jit_wrapper_args, wrapper_type, kwargs)

Invokes the JIT wrapper generator and compiles the result as a cc_library.

The macro invokes the JIT wrapper generator on an IR source file. The generated source files are the inputs to a cc_library with its target name identical to this macro.

PARAMETERS

Name Description Default Value
name The name of the cc_library target. none
src The path to the IR file. none
jit_wrapper_args Arguments of the JIT wrapper tool. Note: argument 'output_name' cannot be defined. {}
wrapper_type The type of XLS construct to wrap. Must be one of 'BLOCK', 'FUNCTION', or 'PROC'. You should use the exported FUNCTION_WRAPPER_TYPE, BLOCK_WRAPPER_TYPE, or PROC_WRAPPER_TYPE symbols. Defaults to FUNCTION_WRAPPER_TYPE for compatibility. "FUNCTION"
kwargs Keyword arguments. Named arguments. none

get_mangled_ir_symbol

get_mangled_ir_symbol(module_name, function_name, parametric_values, is_implicit_token,
                      is_proc_next)

Returns the mangled IR symbol for the module/function combination.

"Mangling" is the process of turning nicely namedspaced symbols into "grosser" (mangled) flat (non hierarchical) symbol, e.g. that lives on a package after IR conversion. To retrieve/execute functions that have been IR converted, we use their mangled names to refer to them in the IR namespace.

PARAMETERS

Name Description Default Value
module_name The DSLX module name that the function is within. none
function_name The DSLX function name within the module. none
parametric_values Any parametric values used for instantiation (e.g. for a parametric entry point that is known to be instantiated in the IR converted module). This is generally for more advanced use cases like internals testing. The argument is mutually exclusive with argument 'is_proc_next'. None
is_implicit_token A boolean flag denoting whether the symbol contains an implicit token. The argument is mutually exclusive with argument 'is_proc_next'. False
is_proc_next A boolean flag denoting whether the symbol is a next proc function. The argument is mutually exclusive with arguments: 'parametric_values' and 'is_implicit_token'. False

RETURNS

The "mangled" symbol string.

xls_benchmark_ir

xls_benchmark_ir(name, src, synthesize, codegen_args, benchmark_ir_args, standard_cells, tags,
                 ir_tags, synth_tags, kwargs)

Executes the benchmark tool on an IR file.

Examples:

  1. A file as the source.

    xls_benchmark_ir(
        name = "a_benchmark",
        src = "a.ir",
    )
    
  2. An xls_ir_opt_ir target as the source.

    xls_ir_opt_ir(
        name = "a_opt_ir",
        src = "a.ir",
    )
    
    
    xls_benchmark_ir(
        name = "a_benchmark",
        src = ":a_opt_ir",
    )
    

    Args: name: A unique name for this target. src: The IR source file for the rule. A single source file must be provided. The file must have a '.ir' extension. synthesize: Add a synthesis benchmark in addition to the IR benchmark. codegen_args: Arguments of the codegen tool. For details on the arguments, refer to the codegen_main application at //xls/tools/codegen_main.cc. benchmark_ir_args: Arguments of the benchmark IR tool. For details on the arguments, refer to the benchmark_main application at //xls/tools/benchmark_main.cc. standard_cells: Label for the PDK (possibly specifying a non-default corner), with the assumption that $location will return the timing (Liberty) library for the PDK corner. Unused if synthesize == False. tags: Tags for IR and synthesis benchmark targets. ir_tags: Tags for the IR benchmark target only. synth_tags: Tags for the synthesis and synthesis benchmark targets. Unused if synthesize == False. **kwargs: Keyword arguments for the IR benchmark target only.

PARAMETERS

Name Description Default Value
name

-

none
src

-

none
synthesize

-

True
codegen_args

-

{}
benchmark_ir_args

-

{}
standard_cells

-

None
tags

-

None
ir_tags

-

None
synth_tags

-

None
kwargs

-

none

xls_dslx_cpp_type_library

xls_dslx_cpp_type_library(name, src, namespace)

Creates a cc_library target for transpiled DSLX types.

This macros invokes the DSLX-to-C++ transpiler and compiles the result as a cc_library with its target name identical to this macro.

PARAMETERS

Name Description Default Value
name The name of the eventual cc_library. none
src The DSLX file whose types to compile as C++. none
namespace The C++ namespace to generate the code in (e.g., foo::bar). None

xls_dslx_fmt_test

xls_dslx_fmt_test(name, src, opportunistic_postcondition)

Creates a test target that confirms src is auto-formatted.

PARAMETERS

Name Description Default Value
name Name of the (diff) test target this will emit. none
src Source file to auto-format. none
opportunistic_postcondition Flag that checks whether the output text is highly similar to the input text. Note that sometimes this /can/ flag an error for some set of valid auto-formattings, so is intended primarily for use as a development/debugging tool. False

xls_dslx_ir

xls_dslx_ir(name, dslx_top, srcs, deps, library, ir_conv_args, enable_generated_file,
            enable_presubmit_generated_file, kwargs)

A macro that instantiates a build rule converting a DSLX source file to an IR file.

The macro instantiates a rule that converts a DSLX source file to an IR file. The macro also instantiates the 'enable_generated_file_wrapper' function. The generated files are listed in the outs attribute of the rule.

Example:

An IR conversion with a top entity defined.

```
# Assume a xls_dslx_library target bc_dslx is present.
xls_dslx_ir(
    name = "d_ir",
    srcs = ["d.x"],
    deps = [":bc_dslx"],
    dslx_top = "d",
)
```

PARAMETERS

Name Description Default Value
name The name of the rule. none
dslx_top The top entity to perform the IR conversion. none
srcs Top level source files for the conversion. Files must have a '.x' extension. There must be single source file. None
deps Dependency targets for the files in the 'srcs' argument. None
library A DSLX library target where the direct (non-transitive) files of the target are tested. This argument is mutually exclusive with the 'srcs' and 'deps' arguments. None
ir_conv_args Arguments of the IR conversion tool. For details on the arguments, refer to the ir_converter_main application at //xls/dslx/ir_convert/ir_converter_main.cc. Note: the 'top' argument is not assigned using this attribute. {}
enable_generated_file See 'enable_generated_file' from 'enable_generated_file_wrapper' function. True
enable_presubmit_generated_file See 'enable_presubmit_generated_file' from 'enable_generated_file_wrapper' function. False
kwargs Keyword arguments. Named arguments. none

xls_dslx_opt_ir

xls_dslx_opt_ir(name, dslx_top, srcs, deps, library, ir_conv_args, opt_ir_args,
                enable_generated_file, enable_presubmit_generated_file, kwargs)

A macro that instantiates a build rule generating an optimized IR file from a DSLX source file.

The macro instantiates a build rule that generates an optimized IR file from a DSLX source file. The build rule executes the core functionality of following macros:

  1. xls_dslx_ir (converts a DSLX file to an IR), and,
  2. xls_ir_opt_ir (optimizes the IR).

The macro also instantiates the 'enable_generated_file_wrapper' function. The generated files are listed in the outs attribute of the rule.

Examples:

  1. A simple example.
    # Assume a xls_dslx_library target bc_dslx is present.
    xls_dslx_opt_ir(
        name = "d_opt_ir",
        srcs = ["d.x"],
        deps = [":bc_dslx"],
        dslx_top = "d",
    )
    

PARAMETERS

Name Description Default Value
name The name of the rule. none
dslx_top The top entity to perform the IR conversion. none
srcs Top level source files for the conversion. Files must have a '.x' extension. There must be single source file. None
deps Dependency targets for the files in the 'srcs' argument. None
library A DSLX library target where the direct (non-transitive) files of the target are tested. This argument is mutually exclusive with the 'srcs' and 'deps' arguments. None
ir_conv_args Arguments of the IR conversion tool. For details on the arguments, refer to the ir_converter_main application at //xls/dslx/ir_convert/ir_converter_main.cc. Note: the 'top' argument is not assigned using this attribute. {}
opt_ir_args Arguments of the IR optimizer tool. For details on the arguments, refer to the opt_main application at //xls/tools/opt_main.cc. Note: the 'top' argument is not assigned using this attribute. {}
enable_generated_file See 'enable_generated_file' from 'enable_generated_file_wrapper' function. True
enable_presubmit_generated_file See 'enable_presubmit_generated_file' from 'enable_generated_file_wrapper' function. False
kwargs Keyword arguments. Named arguments. none

xls_dslx_verilog

xls_dslx_verilog(name, dslx_top, verilog_file, srcs, deps, library, ir_conv_args, opt_ir_args,
                 codegen_args, enable_generated_file, enable_presubmit_generated_file, kwargs)

A macro that instantiates a build rule generating a Verilog file from a DSLX source file and tests the build.

The macro instantiates a build rule that generates a Verilog file from a DSLX source file. The build rule executes the core functionality of following macros:

  1. xls_dslx_ir (converts a DSLX file to an IR),
  2. xls_ir_opt_ir (optimizes the IR), and,
  3. xls_ir_verilog (generated a Verilog file).

The macro also instantiates a 'build_test' testing that the build rule generating a Verilog file. If the build is not successful, an error is produced when executing a test command on the target.

Examples:

  1. A simple example.
    # Assume a xls_dslx_library target bc_dslx is present.
    xls_dslx_verilog(
        name = "d_verilog",
        srcs = ["d.x"],
        deps = [":bc_dslx"],
        codegen_args = {
            "pipeline_stages": "1",
        },
        dslx_top = "d",
    )
    

PARAMETERS

Name Description Default Value
name The name of the rule. none
dslx_top The top entity to perform the IR conversion. none
verilog_file The filename of Verilog file generated. The filename must have a '.v' extension. none
srcs Top level source files for the conversion. Files must have a '.x' extension. There must be single source file. None
deps Dependency targets for the files in the 'srcs' argument. None
library A DSLX library target where the direct (non-transitive) files of the target are tested. This argument is mutually exclusive with the 'srcs' and 'deps' arguments. None
ir_conv_args Arguments of the IR conversion tool. For details on the arguments, refer to the ir_converter_main application at //xls/dslx/ir_convert/ir_converter_main.cc. Note: the 'top' argument is not assigned using this attribute. {}
opt_ir_args Arguments of the IR optimizer tool. For details on the arguments, refer to the opt_main application at //xls/tools/opt_main.cc. Note: the 'top' argument is not assigned using this attribute. {}
codegen_args Arguments of the codegen tool. For details on the arguments, refer to the codegen_main application at //xls/tools/codegen_main.cc. {}
enable_generated_file See 'enable_generated_file' from 'enable_generated_file_wrapper' function. True
enable_presubmit_generated_file See 'enable_presubmit_generated_file' from 'enable_generated_file_wrapper' function. False
kwargs Keyword arguments. Named arguments. none

xls_ir_cc_library

xls_ir_cc_library(name, src, top, namespaces)

Invokes the AOT compiles the input IR into a cc_library.

Example:

xls_ir_opt_ir(
    name "foo",
    ...
)

xls_ir_cc_library_macro(
    name = "foo_cc",
    src = ":foo.opt.ir",
    top = "bar",
    namespaces = "a,b,c",
)

This will produce a cc_library that will execute the fn bar from the foo IR file. The call itself will be inside the namespace a::b::c.

PARAMETERS

Name Description Default Value
name The name of the resulting library. none
src The path to the IR file to compile. none
top The entry point in the IR file of interest. None
namespaces A comma-separated list of namespaces into which the generated code should go. ""

xls_ir_opt_ir

xls_ir_opt_ir(name, src, opt_ir_args, enable_generated_file, enable_presubmit_generated_file,
              debug_srcs, kwargs)

A macro that instantiates a build rule optimizing an IR file.

The macro instantiates a build rule that optimizes an IR file. The macro also instantiates the 'enable_generated_file_wrapper' function. The generated files are listed in the outs attribute of the rule.

Examples:

  1. A simple example.

    xls_ir_opt_ir(
        name = "a_opt_ir",
        src = "a.ir",
    )
    
  2. Optimizing an IR file with a top entity defined.

    xls_ir_opt_ir(
        name = "a_opt_ir",
        src = "a.ir",
        opt_ir_args = {
            "inline_procs" : "true",
        },
    )
    

PARAMETERS

Name Description Default Value
name The name of the rule. none
src The IR source file. A single source file must be provided. The file must have a '.ir' extension. none
opt_ir_args Arguments of the IR optimizer tool. For details on the arguments, refer to the opt_main application at //xls/tools/opt_main.cc. Note: the 'top' argument is not assigned using this attribute. {}
enable_generated_file See 'enable_generated_file' from 'enable_generated_file_wrapper' function. True
enable_presubmit_generated_file See 'enable_presubmit_generated_file' from 'enable_generated_file_wrapper' function. False
debug_srcs List of additional source files for debugging info. Allows opt_main to correctly display lines from original source file (e.g. the .cc file before the xlscc pass) when an error occurs. []
kwargs Keyword arguments. Named arguments. none

xls_ir_verilog

xls_ir_verilog(name, src, verilog_file, codegen_args, codegen_options_proto,
               scheduling_options_proto, enable_generated_file, enable_presubmit_generated_file,
               kwargs)

A macro that instantiates a build rule generating a Verilog file from an IR file and tests the build.

The macro instantiates a build rule that generate a Verilog file from an IR file, and a 'build_test' testing that the build rule generating a Verilog file. If the build is not successful, an error is produced when executing a test command on the target.

Example:

```
xls_ir_verilog(
    name = "a_verilog",
    src = "a.ir",
    codegen_args = {
        "pipeline_stages": "1",
        ...
    },
)
```

PARAMETERS

Name Description Default Value
name The name of the rule. none
src The IR source file. A single source file must be provided. The file must have a '.ir' extension. none
verilog_file The filename of Verilog file generated. The filename must have a '.v' or '.sv', extension. none
codegen_args Arguments of the codegen tool. For details on the arguments, refer to the codegen_main application at //xls/tools/codegen_main.cc. {}
codegen_options_proto Filename of a protobuf with arguments of the codegen tool. For details on the arguments, refer to the codegen_main application at //xls/tools/codegen_main.cc. None
scheduling_options_proto Filename of a protobuf with scheduling options arguments of the codegen tool. For details on the arguments, refer to the codegen_main application at //xls/tools/codegen_main.cc. None
enable_generated_file See 'enable_generated_file' from 'enable_generated_file_wrapper' function. True
enable_presubmit_generated_file See 'enable_presubmit_generated_file' from 'enable_generated_file_wrapper' function. False
kwargs Keyword arguments. Named arguments. none

xls_synthesis_metrics

xls_synthesis_metrics(name, srcs, kwargs)

Gather per-pipeline-stage metrics from log files.

Gather per-stage post-synth metrics from the provided logs (from Yosys or OpenSTA) and save them in a "DesignStats" textproto. Recognized metrics from Yosys log: Total cell area (um^2). Logic levels Cell count Flop count Recognized metrics from OpenSTA log: Critical path delay (ps) Critical path start point Critical path end point

PARAMETERS

Name Description Default Value
name Output "DesignStats" textproto will be <name>.textproto none
srcs Targets from which log files will be scanned. For post-synth, use "synthesize_rtl" and "run_opensta" targets. none
kwargs Accepts add'l keyword arguments. Passed to native.genrule(). none