modules/dbe - lz4 encoder and decoder [DSLX code only]

xls/examples/ram.x

@@ -55,7 +55,7 @@ pub fn ReadWordReq<NUM_PARTITIONS:u32, ADDR_WIDTH:u32>(addr:uN[ADDR_WIDTH]) ->
 }
 
 // Behavior of reads and writes to the same address in the same "tick".
-enum SimultaneousReadWriteBehavior : u2 {
+pub enum SimultaneousReadWriteBehavior : u2 {
   // The read shows the contents at the address before the write.
   READ_BEFORE_WRITE = 0,
   // The read shows the contents at the address after the write.

xls/modules/dbe/BUILD

@@ -0,0 +1,219 @@
+# Copyright 2023 The XLS Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Build rules for XLS DBE/LZ4 algorithm implementation.
+
+load(
+    "//xls/build_rules:xls_build_defs.bzl",
+    "xls_dslx_library",
+    "xls_dslx_ir",
+    "xls_ir_opt_ir",
+    "xls_ir_verilog",
+    "xls_dslx_test",
+)
+
+package(
+    default_applicable_licenses = ["//:license"],
+    default_visibility = ["//xls:xls_users"],
+    licenses = ["notice"],
+)
+
+# ---------------------------------------------------------------------------
+# Common
+# ---------------------------------------------------------------------------
+
+xls_dslx_library(
+    name = "dbe_common_dslx",
+    srcs = [
+        "common.x",
+    ],
+)
+
+xls_dslx_library(
+    name = "dbe_common_test_dslx",
+    srcs = [
+        "common_test.x",
+    ],
+    deps = [
+        ":dbe_common_dslx",
+    ],
+)
+
+# ---------------------------------------------------------------------------
+# LZ4 decoder
+# ---------------------------------------------------------------------------
+
+xls_dslx_library(
+    name = "dbe_lz4_decoder_dslx",
+    srcs = [
+        "lz4_decoder.x"
+    ],
+    deps = [
+        ":dbe_common_dslx",
+        "//xls/examples:ram_dslx",
+    ],
+)
+
+xls_dslx_library(
+    name = "dbe_lz4_decoder_test_dslx",
+    srcs = [
+        "lz4_decoder_test.x"
+    ],
+    deps = [
+        ":dbe_common_test_dslx",
+        ":dbe_lz4_decoder_dslx",
+    ],
+)
+
+xls_dslx_test(
+    name = "dbe_lz4_decoder_dslx_test",
+    dslx_test_args = {
+        "compare": "none",
+    },
+    library = ":dbe_lz4_decoder_test_dslx",
+)
+
+xls_dslx_ir(
+    name = "dbe_lz4_decoder_ir",
+    dslx_top = "decoder",
+    library = "dbe_lz4_decoder_dslx",
+    ir_file = "dbe_lz4_decoder_ir.ir",
+)
+
+xls_ir_opt_ir(
+    name = "dbe_lz4_decoder_opt_ir",
+    src = "dbe_lz4_decoder_ir.ir",
+    top = "__lz4_decoder__decoder__decoder_base_0__16_16_8_next",
+    ram_rewrites = [
+        ":lz4_decoder_ram1r1w_rewrites.textproto",
+    ],
+)
+
+xls_ir_verilog(
+    name = "dbe_lz4_decoder_verilog",
+    src = "dbe_lz4_decoder_opt_ir.opt.ir",
+    verilog_file = "dbe_lz4_decoder.v",
+    codegen_args = {
+        "module_name": "dbe_lz4_decoder",
+        "delay_model": "unit",
+        "pipeline_stages": "3",
+        "reset": "rst",
+        "use_system_verilog": "false",
+        "streaming_channel_data_suffix": "_data",
+        "ram_configurations": "ram_hb:1R1W:{rd_req}:{rd_resp}:{wr_req}:{wr_comp}".format(
+            rd_req = "ram_hb_read_req",
+            rd_resp = "ram_hb_read_resp",
+            wr_req = "ram_hb_write_req",
+            wr_comp = "ram_hb_write_completion",
+        ),
+    },
+)
+
+# ---------------------------------------------------------------------------
+# LZ4 encoder
+# ---------------------------------------------------------------------------
+
+xls_dslx_library(
+    name = "dbe_lz4_encoder_dslx",
+    srcs = [
+        "lz4_encoder.x"
+    ],
+    deps = [
+        ":dbe_common_dslx",
+        "//xls/examples:ram_dslx",
+    ],
+)
+
+xls_dslx_library(
+    name = "dbe_lz4_encoder_test_dslx",
+    srcs = [
+        "lz4_encoder_test.x"
+    ],
+    deps = [
+        ":dbe_common_test_dslx",
+        ":dbe_lz4_encoder_dslx",
+    ],
+)
+
+xls_dslx_test(
+    name = "dbe_lz4_encoder_dslx_test",
+    dslx_test_args = {
+        "compare": "none",
+    },
+    library = ":dbe_lz4_encoder_test_dslx",
+)
+
+#8K hash specialization
+xls_dslx_ir(
+    name = "dbe_lz4_encoder_8k_ir",
+    dslx_top = "encoder_8k",
+    library = "dbe_lz4_encoder_dslx",
+    ir_file = "dbe_lz4_encoder_8k_ir.ir",
+)
+
+xls_ir_opt_ir(
+    name = "dbe_lz4_encoder_8k_opt_ir",
+    src = "dbe_lz4_encoder_8k_ir.ir",
+    top = "__lz4_encoder__encoder_8k__encoder__encoder_base_0__1_4_13_16_16_8_next",
+    ram_rewrites = [
+        ":lz4_encoder_8k_ram1r1w_rewrites.textproto",
+    ],
+)
+
+xls_ir_verilog(
+    name = "dbe_lz4_encoder_8k_verilog",
+    src = "dbe_lz4_encoder_8k_opt_ir.opt.ir",
+    verilog_file = "dbe_lz4_encoder_8k.v",
+    codegen_args = {
+        "module_name": "dbe_lz4_encoder",
+        "delay_model": "unit",
+        "pipeline_stages": "3",
+        "worst_case_throughput": "3",
+        "reset": "rst",
+        "use_system_verilog": "false",
+        "streaming_channel_data_suffix": "_data",
+        "ram_configurations": ",".join([
+            "ram_hb:1R1W:{rd_req}:{rd_resp}:{wr_req}:{wr_comp}".format(
+                rd_req = "ram_hb_read_req",
+                rd_resp = "ram_hb_read_resp",
+                wr_req = "ram_hb_write_req",
+                wr_comp = "ram_hb_write_completion",
+            ),
+            "ram_ht:1R1W:{rd_req}:{rd_resp}:{wr_req}:{wr_comp}".format(
+                rd_req = "ram_ht_read_req",
+                rd_resp = "ram_ht_read_resp",
+                wr_req = "ram_ht_write_req",
+                wr_comp = "ram_ht_write_completion",
+            ),
+        ]),
+    },
+)
+
+# ---------------------------------------------------------------------------
+# Round-trip test
+# ---------------------------------------------------------------------------
+
+xls_dslx_test(
+    name = "dbe_lz4_round_trip_dslx_test",
+    dslx_test_args = {
+        "compare": "none",
+    },
+    srcs = [
+        "lz4_round_trip_test.x"
+    ],
+    deps = [
+        ":dbe_lz4_encoder_test_dslx",
+        ":dbe_lz4_decoder_test_dslx",
+    ]
+)

xls/modules/dbe/common.x

@@ -0,0 +1,77 @@
+// Copyright 2023 The XLS Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import std
+
+pub enum Mark : u4 {
+    // Default initialization value used when marker field is not needed
+    NONE = 0,
+    // Signals end of sequence/block
+    END = 1,
+    // Requests reset of the processing chain
+    RESET = 2,
+
+    _ERROR_FIRST = 8,
+    // Only error marks have values >= __ERROR_FIRST
+    ERROR_BAD_MARK = 8,
+    ERROR_INVAL_CP = 9,
+}
+
+pub fn is_error(mark: Mark) -> bool {
+    (mark as u32) >= (Mark::_ERROR_FIRST as u32)
+}
+
+pub enum TokenKind : u2 {
+    UNMATCHED_SYMBOL = 0,
+    MATCHED_SYMBOL = 1,
+    MATCH = 2,
+    MARKER = 3,
+}
+
+pub struct Token<
+    SYMBOL_WIDTH: u32, MATCH_OFFSET_WIDTH: u32, MATCH_LENGTH_WIDTH: u32
+>{
+    kind: TokenKind,
+    symbol: uN[SYMBOL_WIDTH],
+    match_offset: uN[MATCH_OFFSET_WIDTH],
+    match_length: uN[MATCH_LENGTH_WIDTH],
+    mark: Mark
+}
+
+pub struct PlainData<DATA_WIDTH: u32> {
+    is_marker: bool,
+    data: uN[DATA_WIDTH],
+    mark: Mark,
+}
+
+/// Parameters of a classic LZ4 algorithm
+/// NOTE: CPU LZ4 implementations do not have match length limited to 16 bits,
+/// but 16 bits are more than enough for most real-life use cases, since
+/// matches of more than 64KB are very uncommon.
+pub const LZ4_SYMBOL_WIDTH = u32:8;
+pub const LZ4_MATCH_OFFSET_WIDTH = u32:16;
+pub const LZ4_MATCH_LENGTH_WIDTH = u32:16;
+pub const LZ4_HASH_SYMBOLS = u32:4;
+/// Different hash table sizes
+pub const LZ4_HASH_WIDTH_4K = u32:12;
+pub const LZ4_HASH_WIDTH_8K = u32:13;
+pub const LZ4_HASH_WIDTH_16K = u32:14;
+
+pub type Lz4Token = Token<
+        LZ4_SYMBOL_WIDTH,
+        LZ4_MATCH_OFFSET_WIDTH,
+        LZ4_MATCH_LENGTH_WIDTH
+    >;
+
+pub type Lz4Data = PlainData<LZ4_SYMBOL_WIDTH>;