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:

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
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:

A simple example.

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

ATTRIBUTES

Name	Description	Type	Mandatory
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:

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_dslx_library

xls_dslx_library(name, deps, srcs, warnings_as_errors)

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

Examples:

A collection of DSLX source files.

xls_dslx_library(
    name = "files_123_dslx",
    srcs = [
        "file_1.x",
        "file_2.x",
        "file_3.x",
    ],
)

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:

xls_dslx_test
xls_ir_equivalence_test
xls_eval_ir_test
xls_benchmark_ir

Examples:

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_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:

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"],
)

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:

A file as the source.

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

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:

A file as the source.

xls_ir_equivalence_test(
    name = "ab_ir_equivalence_test",
    src_0 = "a.ir",
    src_1 = "b.ir",
)

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, 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.	`{}`
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:

A file as the source.

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

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_delay_model_generation

xls_delay_model_generation(name, standard_cells, samples_file, kwargs)

Generate an XLS delay model for one PDK corner.

This macro 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.

PARAMETERS

Name	Description	Default Value
name	Used as basename for both the script and the output textproto.	none
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.	none
samples_file	Path to proto providing sample points.	none
kwargs	Accepts add'l keyword arguments. Passed to native.genrule().	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:

xls_dslx_ir (converts a DSLX file to an IR), and,
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:

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:

xls_dslx_ir (converts a DSLX file to an IR),
xls_ir_opt_ir (optimizes the IR), and,
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:

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:

A simple example.

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

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