From 4be1c51a6105f07fcce6e71684487de5bc70c66c Mon Sep 17 00:00:00 2001
From: jijing <goco.v@163.com>
Date: Wed, 29 May 2024 10:16:18 +0000
Subject: [PATCH] whenBuilder document

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

diff --git a/source/SpinalHDL/Semantic/when_switch.rst b/source/SpinalHDL/Semantic/when_switch.rst
index a21ff9e2eed..b896a2092e8 100644
--- a/source/SpinalHDL/Semantic/when_switch.rst
+++ b/source/SpinalHDL/Semantic/when_switch.rst
@@ -39,6 +39,61 @@ As in VHDL and Verilog, signals can be conditionally assigned when a specified c
                 // Execute when (not cond1) and (not cond2)
             }
 
+
+WhenBuilder
+------
+
+Sometimes we need to generate some parameters for the when condition, 
+and the original structure of when else is not very suitable. 
+Therefore, we provide a 'whenBuilder' method to achieve this goal
+
+.. code-block:: scala
+
+    import spinal.lib._
+
+    val conds = Bits(8 bits)
+    val result = UInt(8 bits)
+
+    val ctx = WhenBuilder()
+    ctx.when(conds(0)) {
+      result := 0
+    }
+    ctx.when(conds(1)) {
+      result := 1
+    }
+    if(true){
+      ctx.when(conds(2)) {
+        result := 2
+      }
+    }
+    ctx.when(conds(3)) {
+      result := 3
+    }
+
+Compared to the when/elsewhen/otherwise approach, it might be more convenient for parameterization. 
+we can also use like this
+
+.. code-block:: scala
+
+    for(i <- 5 to 7) ctx.when(conds(i)) {
+      result := i
+    }
+
+    ctx.otherwise{
+      result := 255
+    }
+
+    switch(addr) {
+      for (i <- addressElements ) {
+        is(i) {
+          rdata :=  buffer(i)
+        }
+      }
+    }
+
+This way, we can parameterize priority circuits similar to how we use 'foreach' inside 'switch()', and generate code in a more intuitive if-else format.
+
+
 Switch
 ------