From 8581bd317111f359a7845b99a930cb83fea0b74d Mon Sep 17 00:00:00 2001
From: Jannis Harder <me@jix.one>
Date: Thu, 28 Sep 2023 18:57:37 +0200
Subject: [PATCH] Add dft/data_diode example

This requires YosysHQ/yosys#3961 and YosysHQ/sby#249 to work
---
 docs/examples/dft/data_diode.sby |  49 ++++++
 docs/examples/dft/data_diode.sv  | 278 +++++++++++++++++++++++++++++++
 2 files changed, 327 insertions(+)
 create mode 100644 docs/examples/dft/data_diode.sby
 create mode 100644 docs/examples/dft/data_diode.sv

diff --git a/docs/examples/dft/data_diode.sby b/docs/examples/dft/data_diode.sby
new file mode 100644
index 00000000..32092d2c
--- /dev/null
+++ b/docs/examples/dft/data_diode.sby
@@ -0,0 +1,49 @@
+[tasks]
+diode
+direct
+
+[options]
+mode prove
+
+diode: expect pass
+direct: expect fail
+
+fst on
+
+[engines]
+smtbmc
+
+[script]
+diode: read -define USE_DIODE
+
+verific -sv data_diode.sv
+
+hierarchy -top top
+
+# $overwrite_tag currently requires these two passes directly after importing
+# the design. Otherwise the target signals of $overwrite_tag cannot be properly
+# resolved nor can `dft_tag -overwrite-only` itself detect this situation to
+# report it as an error.
+flatten
+dft_tag -overwrite-only
+
+# Then the design can be prepared as usual
+prep
+
+# And finally the tagging logic can be resolved, which requires converting all
+# FFs into simple D-FFs. Here, if this isn't done `dft_tag` will produce
+# warnings and tell you to run the required passes.
+async2sync
+dffunmap
+dft_tag -tag-public
+
+# The `Unhandled cell` warnings produced by `dft_tag` mean that there is no
+# bit-precise tag propagation model for the listed cell. The cell in question
+# will still propagate tags, but `dft_tag` will use a generic model that
+# assumes all inputs can propagate to all outputs independent of the value of
+# other inputs on the same cell. For built-in logic cells this is a sound
+# over-approximation, but may produce more false-positives than a bit-precise
+# approximation would.
+
+[files]
+data_diode.sv
diff --git a/docs/examples/dft/data_diode.sv b/docs/examples/dft/data_diode.sv
new file mode 100644
index 00000000..fa053a21
--- /dev/null
+++ b/docs/examples/dft/data_diode.sv
@@ -0,0 +1,278 @@
+// Simple sync FIFO implementation using an extra bit in the read and write
+// pointers to distinguish the completely full and completely empty case.
+module fifo #(
+    DEPTH_BITS = 4,
+    WIDTH = 8
+) (
+    input wire clk,
+    input wire rst,
+
+    input wire             in_valid,
+    input wire [WIDTH-1:0] in_data,
+    output reg             in_ready,
+
+    output reg             out_valid,
+    output reg [WIDTH-1:0] out_data,
+    input wire             out_ready
+);
+
+    reg [WIDTH-1:0] buffer [1<<DEPTH_BITS];
+
+    reg [DEPTH_BITS:0] write_addr;
+    reg [DEPTH_BITS:0] read_addr;
+
+    wire in_transfer = in_valid && in_ready;
+    wire out_transfer = out_valid && out_ready;
+
+    wire [DEPTH_BITS:0] write_limit = read_addr ^ (1 << DEPTH_BITS);
+
+    assign in_ready = write_addr != write_limit;
+    assign out_valid = read_addr != write_addr;
+
+    assign out_data = buffer[read_addr[DEPTH_BITS-1:0]];
+
+    always @(posedge clk) begin
+        if (rst) begin
+            read_addr <= 0;
+            write_addr <= 0;
+        end else begin
+            if (in_transfer) begin
+                buffer[write_addr[DEPTH_BITS-1:0]] <= in_data;
+                write_addr <= write_addr + 1'b1;
+            end
+
+            if (out_transfer) begin
+                read_addr <= read_addr + 1'b1;
+            end
+        end
+    end
+
+endmodule
+
+// This module sends some data and should not be able to receive any
+// information back, even under the assumption that it can trick the other side
+// into performing unintended operations that would attempt to establish a
+// covert channel.
+module untrusted_module (
+    input wire clk,
+    input wire rst,
+
+    input wire en,
+
+    output reg        out_valid,
+    output reg [31:0] out_data,
+    input wire        out_ready
+);
+
+    reg [31:0] lfsr;
+
+    always @(posedge clk) begin
+        if (rst) begin
+            lfsr <= '1;
+        end else if (en && out_valid && out_ready) begin
+            lfsr <= (lfsr << 1) ^ (lfsr[31] ? 32'h04C11DB7 : 0);
+        end
+    end
+
+    assign out_valid = out_ready && en;
+    assign out_data = lfsr;
+
+endmodule
+
+// This module receives data and contains secret data. It should guard this
+// secret data even if there are bugs in this module's implementations that the
+// other side could exploit in an attempt to establish a covert channel to
+// exfiltrate the secrets.
+module secret_storing_module (
+    input wire clk,
+    input wire rst,
+
+    input wire en,
+    output reg [31:0] counter,
+
+    input wire        in_valid,
+    input wire [31:0] in_data,
+    output reg        in_ready
+);
+
+    reg [3:0] busy;
+
+    always @(posedge clk) begin
+        if (rst) begin
+            counter <= '0;
+            busy <= '0;
+        end else if (en) begin
+            if (busy) begin
+                busy <= busy - 4'b1;
+            end else if (in_valid && in_ready) begin
+                busy <= counter[3:0];
+                counter <= counter + in_data;
+            end
+        end
+    end
+
+    assign in_ready = en && !busy;
+
+endmodule
+
+
+// This data diode wraps a FIFO, but ensures that there is no backwards data
+// flow via the handshaking signals. Instead it limits the sender to send with
+// a fixed rate and only notifies the receiver
+module data_diode #(
+    DEPTH_BITS = 4,
+    WIDTH = 8,
+    RATE = 2
+) (
+    input wire clk,
+    input wire rst,
+
+    input wire             in_valid,
+    input wire [WIDTH-1:0] in_data,
+    output reg             in_ready,
+
+    output reg             out_valid,
+    output reg [WIDTH-1:0] out_data,
+    input wire             out_ready,
+
+    output reg overflow
+);
+    reg [$clog2(RATE):0] delay;
+    wire fifo_ready;
+
+    always @(posedge clk) begin
+        if (rst) begin
+            delay <= 0;
+            overflow <= 0;
+        end else begin
+            if (in_valid && in_ready) begin
+                if (!fifo_ready) begin
+                    overflow <= 1;
+                end
+                delay <= RATE - 1;
+            end else if (delay) begin
+                delay <= delay - 1'b1;
+            end
+        end
+    end
+
+    assign in_ready = !delay;
+
+    fifo #(.DEPTH_BITS(DEPTH_BITS), .WIDTH(WIDTH)) fifo (
+        .clk(clk),
+        .rst(rst),
+
+        .in_valid(in_valid),
+        .in_data(in_data),
+        .in_ready(fifo_ready),
+
+        .out_valid(out_valid),
+        .out_data(out_data),
+        .out_ready(out_ready)
+    );
+
+endmodule
+
+// The top module either connects the untrusted and secret storing modules
+// directly or via the data diode.
+module top(
+    input wire clk,
+    input wire rst,
+
+    input wire source_en,
+    input wire sink_en,
+
+`ifdef USE_DIODE
+    output reg overflow,
+`endif
+    output reg [31:0] counter
+
+);
+
+    wire        source_valid;
+    wire [31:0] source_data;
+    wire        source_ready;
+
+    wire        sink_valid;
+    wire [31:0] sink_data;
+    wire        sink_ready;
+
+    untrusted_module source (
+        .clk(clk),
+        .rst(rst),
+        .en(source_en),
+
+        .out_valid(source_valid),
+        .out_data(source_data),
+        .out_ready(source_ready)
+    );
+
+`ifdef USE_DIODE
+    data_diode #(.WIDTH(32)) data_diode (
+        .clk(clk),
+        .rst(rst),
+
+        .in_valid(source_valid),
+        .in_data(source_data),
+        .in_ready(source_ready),
+
+        .out_valid(sink_valid),
+        .out_data(sink_data),
+        .out_ready(sink_ready),
+
+        .overflow(overflow)
+    );
+`else
+    fifo #(.WIDTH(32)) fifo (
+        .clk(clk),
+        .rst(rst),
+
+        .in_valid(source_valid),
+        .in_data(source_data),
+        .in_ready(source_ready),
+
+        .out_valid(sink_valid),
+        .out_data(sink_data),
+        .out_ready(sink_ready)
+    );
+`endif
+
+    secret_storing_module sink (
+        .clk(clk),
+        .rst(rst),
+        .en(sink_en),
+
+        .in_valid(sink_valid),
+        .in_data(sink_data),
+        .in_ready(sink_ready),
+
+        .counter(counter)
+    );
+endmodule
+
+// We can inject a tag into signals of a module by binding a checker that
+// contains an `$overwrite_tag` item.
+checker mark_secret(counter);
+    $overwrite_tag("secret", counter);
+endchecker
+
+bind secret_storing_module mark_secret counter_is_secret(counter);
+
+// We cen inject a check for a tag by binding a checker that has an assertion
+// that uses `$get_tag`.
+//
+// When using a direct connection, this assertion will fail as there is a
+// covert channel via the FIFO's handshaking signals. When the data-diode is
+// used, we are able to prove the absance of such a covert channel.
+checker leak_check(clk, signal);
+   secret_leaked: assert property (@(posedge clk) !$get_tag("secret", signal));
+endchecker
+
+bind untrusted_module leak_check leak_check(clk, out_ready);
+
+
+checker initial_reset(clk, rst);
+    assume property (@(posedge clk) $initstate |-> rst);
+endchecker
+
+bind top initial_reset initial_reset(clk, rst);