From 145ffeb7567cab4121782d6dd01753128838405f Mon Sep 17 00:00:00 2001
From: ronan-lashermes <86600116+ronan-lashermes@users.noreply.github.com>
Date: Thu, 9 Nov 2023 15:56:53 +0100
Subject: [PATCH] Add a documentation for CombInit

---
 source/SpinalHDL/Semantic/assignments.rst | 48 +++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/source/SpinalHDL/Semantic/assignments.rst b/source/SpinalHDL/Semantic/assignments.rst
index f25ed382f77..fbb0717fb1c 100644
--- a/source/SpinalHDL/Semantic/assignments.rst
+++ b/source/SpinalHDL/Semantic/assignments.rst
@@ -118,3 +118,51 @@ Combinatorial loops
 
 SpinalHDL checks that there are no combinatorial loops (latches) in your design.
 If one is detected, it raises an error and SpinalHDL will print the path of the loop.
+
+CombInit
+--------
+
+The special ``CombInit`` method can be used to "clone" a combinatorial value for latter modification.
+
+.. code-block:: scala
+
+    val a = UInt(8 bits)
+    a := 1
+
+    val b = a
+    when(sel) {
+        b := 2
+        //At this point, a and b are evaluated to 2 : they represent the same set of wire
+    }
+
+    val c = UInt(8 bits)
+    c := 1
+
+    val d = CombInit(c)
+    // Here c and d are evaluated to 1
+    when(sel) {
+        d := 2
+        // At this point c === 1 and d === 2.
+    }
+
+``CombInit`` clones a circuit, and initially drive it with the same input at the cloned value.
+But you can now update the circuit without impacting the initial value.
+
+If we look at the resulting Verilog, ``b`` is not present :
+
+.. code-block:: verilog
+
+    always @(*) begin
+      a = 8'h01;
+      if(sel) begin
+        a = 8'h02;
+      end
+    end
+
+    assign c = 8'h01;
+    always @(*) begin
+      d = c;
+      if(sel) begin
+        d = 8'h02;
+      end
+    end