whenBuilder document

source/SpinalHDL/Semantic/when_switch.rst

@@ -39,6 +39,61 @@
                 // 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
 ------