Bedrock-RTL

High quality and composable RTL libraries in SystemVerilog

Overview

Bedrock-RTL is a collection of reusable, composable SystemVerilog building blocks. It is for designers who want to assemble common hardware functions from well-tested libraries instead of starting each one from scratch.

• Synthesizable RTL libraries for common functions, including AMBA components, arbiters, clock-domain crossings, FIFOs, flow control, memory helpers, and counters.
• SystemVerilog macros for registers, assertions, gate wrappers, assignments, and other small building blocks.
• Assertions and formal-verification support that check both module behavior and how modules are connected.
• Bazel rules and test helpers for elaboration, lint, simulation, and formal verification.

Design approach

The design style favors correct-by-construction interfaces: make valid use clear, catch invalid parameters at elaboration time, and check integration assumptions in the design itself. The libraries aim to make correct designs easier to build and integration mistakes easier to find.

Assertions are a normal part of integration, not an optional afterthought. Define BR_ASSERT_ON when you integrate Bedrock modules so that public and integration checks are active. Bedrock leaves its internal implementation checks off by default for user designs. See Assertions for the available controls.

Integrate Bedrock-RTL

You can use Bedrock-RTL with Bazel or use its SystemVerilog sources directly. In both cases, pin the revision you depend on.

Use Bazel

Add Bedrock-RTL to your project's MODULE.bazel. This example uses the Bazel module system and pins a Git commit:

MODULE.bazel

module(name = "your-project")

bazel_dep(name = "bedrock-rtl", version = "0.0.1")
git_override(
    module_name = "bedrock-rtl",
    commit = <fill_in_git_commit_sha>,
    remote = "https://github.com/xlsynth/bedrock-rtl",
)

rules_hdl_extension = use_extension("@bedrock-rtl//dependency_support/rules_hdl:extension.bzl", "rules_hdl_extension")
use_repo(rules_hdl_extension, "rules_hdl")

If your root module must redirect the rules_hdl wrapper, load its extension from the root dependency instead:

bazel_dep(name = "rules_hdl", version = "0.0.0", repo_name = "rules_hdl_wrapper_module")

# Add an override only when your root module supplies the rules_hdl wrapper.
local_path_override(
    module_name = "rules_hdl",
    path = "<path-to-rules-hdl-wrapper>",
)

rules_hdl_extension = use_extension("@rules_hdl_wrapper_module//:extension.bzl", "rules_hdl_extension")
use_repo(rules_hdl_extension, "rules_hdl")

Only the root module can apply module overrides. If rules_hdl is available from your configured Bazel registries, no override is needed.

Then suppose your design contains this SystemVerilog module, datapath_join.sv:

datapath_join.sv

// An example design using two Bedrock-RTL modules: br_flow_reg_fwd and br_flow_join.
//
// Joins two or more equal-width datapaths into a single output datapath.
// Uses ready/valid protocol on all flows.
// Push-side is registered.

`include "br_asserts.svh"

module datapath_join #(
    parameter int NumFlows = 2,  // must be at least 2
    parameter int WidthPerFlow = 32  // must be at least 1
) (
    input logic clk,
    input logic rst,
    output logic [NumFlows-1:0] push_ready,
    input logic [NumFlows-1:0] push_valid,
    input logic [NumFlows-1:0][WidthPerFlow-1:0] push_data,
    input logic pop_ready,
    output logic pop_valid,
    output logic [(NumFlows*WidthPerFlow)-1:0] pop_data
);

  `BR_ASSERT_STATIC(numflows_gte_2_a, NumFlows >= 2)
  `BR_ASSERT_STATIC(widthperflow_gte_1_a, WidthPerFlow >= 1)

  logic [NumFlows-1:0] inter_ready;
  logic [NumFlows-1:0] inter_valid;
  logic [NumFlows-1:0][WidthPerFlow-1:0] inter_data;

  for (genvar i = 0; i < NumFlows; i++) begin : gen_regs
    br_flow_reg_fwd #(
        .Width(WidthPerFlow)
    ) br_flow_reg_fwd (
        .clk,
        .rst,
        .push_ready(push_ready[i]),
        .push_valid(push_valid[i]),
        .push_data (push_data[i]),
        .pop_ready (inter_ready[i]),
        .pop_valid (inter_valid[i]),
        .pop_data  (inter_data[i])
    );
  end

  br_flow_join #(
      .NumFlows(NumFlows)
  ) br_flow_join (
      .clk,
      .rst,
      .push_ready(inter_ready),
      .push_valid(inter_valid),
      .pop_ready (pop_ready),
      .pop_valid (pop_valid)
  );

  assign pop_data = inter_data;  // direct concat

endmodule : datapath_join

Its BUILD.bazel can declare the Bedrock dependencies and add an open-source elaboration test:

BUILD.bazel

load("@bedrock-rtl//bazel:verilog.bzl", "verilog_elab_test")
load("@rules_hdl//verilog:providers.bzl", "verilog_library")

package(default_visibility = ["//visibility:private"])

verilog_library(
    name = "datapath_join",
    srcs = ["datapath_join.sv"],
    deps = [
        "@bedrock-rtl//flow/rtl:br_flow_join",
        "@bedrock-rtl//flow/rtl:br_flow_reg_fwd",
        "@bedrock-rtl//macros:br_asserts",
    ],
)

verilog_elab_test(
    name = "datapath_join_elab_test",
    tool = "slang",
    defines = ["BR_ASSERT_ON"],
    deps = [":datapath_join"],
)

This example uses Slang, which is part of the public toolchain. Add lint or multi-tool test suites when your project configures the required tool plugins; see DEVELOPING.md.

Clone the sources and generate a file list

If your project does not use Bazel, clone Bedrock-RTL at the revision you want and generate a file list for a library target. This command uses bazel query, so install Bazel 9.1.0 first.

git clone https://github.com/xlsynth/bedrock-rtl.git
cd bedrock-rtl
git checkout <pinned-commit>
./generate_filelist.sh //arb/rtl:br_arb_fixed

The generated .f file contains the target's transitive SystemVerilog sources and headers, and starts with the required macros include directory. Its paths are relative to the Bedrock-RTL checkout, so run your simulator or synthesis tool from that checkout, or convert the paths for your own flow. Choose the library target for the module you use; its name is listed in the library's BUILD.bazel file.

Explore the libraries

• RTL Libraries lists the public modules, packages, and formal libraries.
• SystemVerilog Macros documents the register, gate, assignment, and helper macros.
• Assertions explains public, integration, implementation, and formal assertion controls.
• Bazel Verilog Rules documents the rules supplied by this repository. The verilog_library rule itself comes from rules_hdl.
• Scripts describes the repository's report-generation scripts.

For repository development, see DEVELOPING.md. For pull-request requirements, see CONTRIBUTING.md.