refine backend compilation folders in tests

change user-guide demos to snippets add custom styles for nested tabs in user guide cache sandbox generated hdl files from Build to DFDocs workflow more snippets in docs docExamples generation checks are now done across all active dialects and through file comparions against reference files in resources remove unused sandbox upload and download steps from workflows now that we have a those files committed inside resources and a way to automatically update them update workflows to ignore certain paths and refine mkdocs watch still hide user guide update documentation paths for generated Verilog and VHDL examples ignore dfhdl_defs.* and dfhdl_pkg.vhd files
DFiantHDL · Feb 5, 2025 · 821d289 · 821d289
1 parent d887db8
commit 821d289
Show file tree

Hide file tree

Showing 148 changed files with 3,166 additions and 1,043 deletions.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -6,12 +6,21 @@ on:
       - main
       - dev
       - scala_opencb
+    paths-ignore:
+      - 'docs/**'
+      - 'docs_overrides/**'
+      - 'mkdocs.yml'  
+      - '.github/workflows/dfdocs.yml'
   pull_request:
     branches: 
       - main
       - dev
       - scala_opencb
-
+    paths-ignore:
+      - 'docs/**'
+      - 'docs_overrides/**'
+      - 'mkdocs.yml'
+      - '.github/workflows/dfdocs.yml'
 jobs:
   build:
     runs-on: ubuntu-latest

diff --git a/.github/workflows/dfdocs.yml b/.github/workflows/dfdocs.yml
@@ -5,10 +5,24 @@ on:
     branches:
       - main
       - dev
+    paths:
+      - 'docs/**'
+      - 'docs_overrides/**'
+      - 'mkdocs.yml'
+      - '.github/workflows/dfdocs.yml'
+      - 'lib/src/test/scala/docExamples/**'
+      - 'lib/src/test/resources/ref/**'
   pull_request:
     branches: 
       - main
       - dev
+    paths:
+      - 'docs/**'
+      - 'docs_overrides/**'
+      - 'mkdocs.yml'
+      - '.github/workflows/dfdocs.yml'
+      - 'lib/src/test/scala/docExamples/**'
+      - 'lib/src/test/resources/ref/**'
 
 jobs:
   build:

diff --git a/build.sbt b/build.sbt
@@ -1,4 +1,5 @@
 commands += DFHDLCommands.quickTestSetup
+commands += DFHDLCommands.docExamplesRefUpdate
 
 // format: off
 val projectName = "dfhdl"

diff --git a/docs/css/user-guide.css b/docs/css/user-guide.css
@@ -0,0 +1,4 @@
+/* different styles for tabs inside tabs */
+html.js-focus-visible.js body div.md-container main.md-main div.md-main__inner.md-grid div.md-content article.md-content__inner.md-typeset div.admonition div.tabbed-set.tabbed-alternate div.tabbed-content div.tabbed-block div.tabbed-set.tabbed-alternate div.tabbed-labels.tabbed-labels--linked label a {
+  font-size: smaller;
+}
diff --git a/docs/user-guide/connectivity/index.md b/docs/user-guide/connectivity/index.md
@@ -117,17 +117,7 @@ The DFHDL code below implements a two-bits left shifter design named `LeftShift2
 <div class="grid" markdown>
 
 ```scala
-import dfhdl.*
-//optionally set the default backend configuration option
-//(can be overridden by the top-app CLI)
-given options.CompilerOptions.Backend = backends.verilog
-/** A two-bits left shifter */
-@top class LeftShift2 extends RTDesign:
-  /** bits input */
-  val iBits = Bits(8) <> IN
-  /** bits output */
-  val oBits = Bits(8) <> OUT
-  oBits := iBits << 2
+--8<-- "lib/src/test/scala/docExamples/ugdemos/demo1/LeftShift2.scala:3"
 ```
 
 ```hdelk width=100%
@@ -151,64 +141,21 @@ children = [
 This design is also a top-app design, since it's annotated with `@top`. This means that we have an executable Scala program that compiles the design and generates a Verilog or VHDL backend code. The backend configuration option can be set via a CLI argument, or alternatively, be set via an implicit backend setting like in the code above. The `@top` annotation captures the [implicit/given](https://docs.scala-lang.org/scala3/book/ca-context-parameters.html#given-instances-implicit-definitions-in-scala-2){target="_blank"} options within its scope and feeds them to the top-app CLI program as default to run when no CLI arguments are given.
 
 /// tab | Generated Verilog
-
 ```verilog
-/* A two-bits left shifter */
-`default_nettype none
-`timescale 1ns/1ps
-`include "LeftShift2_defs.svh"
-
-module LeftShift2(
-  /* bits input */
-  input  wire logic [7:0] iBits,
-  /* bits output */
-  output      logic [7:0] oBits
-);
-  `include "dfhdl_defs.svh"
-  assign oBits = iBits << 2;
-endmodule
+--8<-- "lib/src/test/resources/ref/docExamples.ugdemos.demo1.LeftShift2Spec/verilog.sv2009/hdl/LeftShift2.sv"
 ```
 ///
 
 /// tab | Generated VHDL
 ```vhdl
--- A two-bits left shifter 
-library ieee;
-use ieee.std_logic_1164.all;
-use ieee.numeric_std.all;
-use work.dfhdl_pkg.all;
-use work.LeftShift2_pkg.all;
-
-entity LeftShift2 is
-port (
-  -- bits input 
-  iBits : in  std_logic_vector(7 downto 0);
-  -- bits output 
-  oBits : out std_logic_vector(7 downto 0)
-);
-end LeftShift2;
-
-architecture LeftShift2_arch of LeftShift2 is
-begin
-  oBits <= slv_sll(iBits, 2);
-end LeftShift2_arch;
+--8<-- "lib/src/test/resources/ref/docExamples.ugdemos.demo1.LeftShift2Spec/vhdl.v2008/hdl/LeftShift2.vhd"
 ```
 ///
 
 /// details | Runnable example
     type: dfhdl
 ```scastie
-import dfhdl.*
-//optionally set the default backend configuration option
-//(can be overridden by the top-app CLI)
-given options.CompilerOptions.Backend = backends.verilog
-/** A two-bits left shifter */
-@top class LeftShift2 extends RTDesign:
-  /** bits input */
-  val iBits = Bits(8) <> IN
-  /** bits output */
-  val oBits = Bits(8) <> OUT
-  oBits := iBits << 2
+--8<-- "lib/src/test/scala/docExamples/ugdemos/demo1/LeftShift2.scala:3"
 ```
 ///
 ///
@@ -236,17 +183,7 @@ The DFHDL code below implements a basic left shifter design named `LeftShiftBasi
 <div class="grid" markdown>
 
 ```scala
-/** A basic left shifter */
-@top class LeftShiftBasic(
-    val width: Int = 8,
-) extends RTDesign:
-  /** bits input */
-  val iBits = Bits(width)       <> IN
-  /** requested shift */
-  val shift = UInt.until(width) <> IN
-  /** bits output */
-  val oBits = Bits(width)       <> OUT
-  oBits := iBits << shift  
+--8<-- "lib/src/test/scala/docExamples/ugdemos/demo2/LeftShiftBasic.scala:6"
 ```
 
 ```hdelk width=90%
@@ -271,70 +208,21 @@ children = [
 </div>
 
 /// tab | Generated Verilog
-
 ```verilog
-/* A basic left shifter */
-`default_nettype none
-`timescale 1ns/1ps
-`include "LeftShiftBasic_defs.svh"
-
-module LeftShiftBasic(
-  /* bits input */
-  input  wire logic [7:0] iBits,
-  /* requested shift */
-  input  wire logic [2:0] shift,
-  /* bits output */
-  output      logic [7:0] oBits
-);
-  `include "dfhdl_defs.svh"
-  assign oBits = iBits << shift;
-endmodule
+--8<-- "lib/src/test/resources/ref/docExamples.ugdemos.demo2.LeftShiftBasicSpec/verilog.sv2009/hdl/LeftShiftBasic.sv"
 ```
 ///
 
 /// tab | Generated VHDL
 ```vhdl
--- A basic left shifter 
-library ieee;
-use ieee.std_logic_1164.all;
-use ieee.numeric_std.all;
-use work.dfhdl_pkg.all;
-use work.LeftShiftBasic_pkg.all;
-
-entity LeftShiftBasic is
-port (
-  -- bits input 
-  iBits : in  std_logic_vector(7 downto 0);
-  -- requested shift 
-  shift : in  unsigned(2 downto 0);
-  -- bits output 
-  oBits : out std_logic_vector(7 downto 0)
-);
-end LeftShiftBasic;
-
-architecture LeftShiftBasic_arch of LeftShiftBasic is
-begin
-  oBits <= slv_sll(iBits, to_integer(shift));
-end LeftShiftBasic_arch;
+--8<-- "lib/src/test/resources/ref/docExamples.ugdemos.demo2.LeftShiftBasicSpec/vhdl.v2008/hdl/LeftShiftBasic.vhd"
 ```
 ///
 
 /// details | Runnable example
     type: dfhdl
 ```scastie
-import dfhdl.*
-given options.CompilerOptions.Backend = backends.verilog
-/** A basic left shifter */
-@top class LeftShiftBasic(
-    val width: Int = 8,
-) extends RTDesign:
-  /** bits input */
-  val iBits = Bits(width)       <> IN
-  /** requested shift */
-  val shift = UInt.until(width) <> IN
-  /** bits output */
-  val oBits = Bits(width)       <> OUT
-  oBits := iBits << shift  
+--8<-- "lib/src/test/scala/docExamples/ugdemos/demo2/LeftShiftBasic.scala:3"
 ```
 ///
 ///
@@ -345,21 +233,7 @@ The DFHDL code below implements a generic left shifter design named `LeftShiftGe
 <div class="grid" markdown>
 
 ```scala
-/** A generic left shifter 
-  *   
-  * @param width
-  *   the width of the input and output bits
-  */
-@top class LeftShiftGen(
-    val width: Int <> CONST = 8,
-) extends RTDesign:
-  /** bits input */
-  val iBits = Bits(width)       <> IN
-  /** requested shift */
-  val shift = UInt.until(width) <> IN
-  /** bits output */
-  val oBits = Bits(width)       <> OUT
-  oBits := iBits << shift  
+--8<-- "lib/src/test/scala/docExamples/ugdemos/demo3/LeftShiftGen.scala:6"
 ```
 
 ```hdelk width=90%
@@ -384,84 +258,21 @@ children = [
 </div>
 
 /// tab | Generated Verilog
-
 ```verilog
-/* A generic left shifter 
-     
-   @param width
-     the width of the input and output bits
-  */
-`default_nettype none
-`timescale 1ns/1ps
-`include "LeftShiftGen_defs.svh"
-
-module LeftShiftGen#(parameter int width = 8)(
-  /* bits input */
-  input  wire logic [width - 1:0]         iBits,
-  /* requested shift */
-  input  wire logic [$clog2(width) - 1:0] shift,
-  /* bits output */
-  output      logic [width - 1:0]         oBits
-);
-  `include "dfhdl_defs.svh"
-  assign oBits = iBits << shift;
-endmodule
+--8<-- "lib/src/test/resources/ref/docExamples.ugdemos.demo3.LeftShiftGenSpec/verilog.sv2009/hdl/LeftShiftGen.sv"
 ```
 ///
 
 /// tab | Generated VHDL
 ```vhdl
--- A generic left shifter 
---   
--- @param width
---   the width of the input and output bits
-library ieee;
-use ieee.std_logic_1164.all;
-use ieee.numeric_std.all;
-use work.dfhdl_pkg.all;
-use work.LeftShiftGen_pkg.all;
-
-entity LeftShiftGen is
-generic (
-  width : integer := 8
-);
-port (
-  -- bits input 
-  iBits : in  std_logic_vector(width - 1 downto 0);
-  -- requested shift 
-  shift : in  unsigned(clog2(width) - 1 downto 0);
-  -- bits output 
-  oBits : out std_logic_vector(width - 1 downto 0)
-);
-end LeftShiftGen;
-
-architecture LeftShiftGen_arch of LeftShiftGen is
-begin
-  oBits <= slv_sll(iBits, to_integer(shift));
-end LeftShiftGen_arch;
+--8<-- "lib/src/test/resources/ref/docExamples.ugdemos.demo3.LeftShiftGenSpec/vhdl.v2008/hdl/LeftShiftGen.vhd"
 ```
 ///
 
 /// details | Runnable example
     type: dfhdl
 ```scastie
-import dfhdl.*
-given options.CompilerOptions.Backend = backends.verilog
-/** A generic left shifter 
-  *   
-  * @param width
-  *   the width of the input and output bits
-  */
-@top class LeftShiftGen(
-    val width: Int <> CONST = 8,
-) extends RTDesign:
-  /** bits input */
-  val iBits = Bits(width)       <> IN
-  /** requested shift */
-  val shift = UInt.until(width) <> IN
-  /** bits output */
-  val oBits = Bits(width)       <> OUT
-  oBits := iBits << shift  
+--8<-- "lib/src/test/scala/docExamples/ugdemos/demo3/LeftShiftGen.scala:3"
 ```
 ///
 ///

diff --git a/lib/src/test/resources/ref/docExamples.ALUSpec/verilog.sv2009/hdl/ALU.sv b/lib/src/test/resources/ref/docExamples.ALUSpec/verilog.sv2009/hdl/ALU.sv
@@ -0,0 +1,33 @@
+`default_nettype none
+`timescale 1ns/1ps
+`include "ALU_defs.svh"
+
+module ALU(
+  input  wire logic [31:0]  op1,
+  input  wire logic [31:0]  op2,
+  input  wire t_enum_ALUSel aluSel,
+  output      logic [31:0]  aluOut
+);
+  `include "dfhdl_defs.svh"
+  logic [4:0]  shamt;
+  logic [31:0] outCalc;
+  always_comb
+  begin
+    case (aluSel)
+      ALUSel_ADD:   outCalc = op1 + op2;
+      ALUSel_SUB:   outCalc = op1 - op2;
+      ALUSel_AND:   outCalc = op1 & op2;
+      ALUSel_OR:    outCalc = op1 | op2;
+      ALUSel_XOR:   outCalc = op1 ^ op2;
+      ALUSel_SLT:   outCalc = {{(32-1){1'b0}}, {$signed(op1) < $signed(op2)}};
+      ALUSel_SLTU:  outCalc = {{(32-1){1'b0}}, {op1 < op2}};
+      ALUSel_SLL:   outCalc = op1 << shamt;
+      ALUSel_SRL:   outCalc = op1 >> shamt;
+      ALUSel_SRA:   outCalc = {$signed(op1) >>> shamt};
+      ALUSel_COPY1: outCalc = op1;
+      default:      outCalc = 32'h????????;
+    endcase
+  end
+  assign shamt  = op2[4:0];
+  assign aluOut = outCalc;
+endmodule