[Mesa-dev] [PATCH 2/5] gallium: document breakc and switch/case/default/endswitch

[sroland at vmware.com]

From: Roland Scheidegger <sroland at vmware.com>

docs were missing, especially the opcode-from-hell switch however is anything
but obvious.
---
 src/gallium/docs/source/tgsi.rst |   57 ++++++++++++++++++++++++++++++++++----
 1 file changed, 51 insertions(+), 6 deletions(-)

diff --git a/src/gallium/docs/source/tgsi.rst b/src/gallium/docs/source/tgsi.rst
index b7180f8..b46347e 100644
--- a/src/gallium/docs/source/tgsi.rst
+++ b/src/gallium/docs/source/tgsi.rst
@@ -861,7 +861,18 @@ This instruction replicates its result.
 
 .. opcode:: BRK - Break
 
-  TBD
+  Unconditionally moves the point of execution to the instruction after the
+  next endloop or endswitch. The instruction must appear within a loop/endloop
+  or switch/endswitch.
+
+
+.. opcode:: BREAKC - Break Conditional
+
+  Conditionally moves the point of execution to the instruction after the
+  next endloop or endswitch. The instruction must appear within a loop/endloop
+  or switch/endswitch.
+  Condition evaluates to true if src0.x != 0 where src0.x is interpreted
+  as an integer register.
 
 
 .. opcode:: IF - Float If
@@ -892,6 +903,45 @@ This instruction replicates its result.
   Ends an IF or UIF block.
 
 
+.. opcode:: SWITCH - Switch
+
+   Starts a c-style switch expression. The switch consists of one or multiple
+   CASE statements, and at most one DEFAULT statement. Execution of a statement
+   ends when a BRK is hit, but just like in C falling through to other cases
+   without a break is allowed. Similarly, DEFAULT label is allowed anywhere not
+   just as last statement, and fallthrough is allowed into/from it.
+   CASE src arguments are evaulated at bit level against the SWITCH src argument.
+
+   Example:
+   SWITCH src[0].x
+   CASE src[0].x
+   (some instructions here)
+   (optional BRK here)
+   DEFAULT
+   (some instructions here)
+   (optional BRK here)
+   CASE src[0].x
+   (some instructions here)
+   (optional BRK here)
+   ENDSWITCH
+
+
+.. opcode:: CASE - Switch case
+
+   This represents a switch case label. The src arg must be an integer immediate.
+
+
+.. opcode:: DEFAULT - Switch default
+
+   This represents the default case in the switch, which is taken if no other
+   case matches.
+
+
+.. opcode:: ENDSWITCH - End of switch
+
+   Ends a switch expression.
+
+
 .. opcode:: PUSHA - Push Address Register On Stack
 
   push(src.x)
@@ -1210,11 +1260,6 @@ XXX wait what
 
   TBD
 
-
-.. opcode:: BREAKC - Break Conditional
-
-  TBD
-
 .. _doubleopcodes:
 
 Double ISA
-- 
1.7.9.5