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

[Jose Fonseca]

----- Original Message -----
> 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.

This is fine. But I do wonder if hardware can really benefit from "UIF foo; BREAK; ENDIF" vs "BREAKC foo", or if this is just syntactic sugar that merely burdens developers. 


BTW, svga translates BREAKC, though I think it doesn't follow anywhere near these semantics, so that translation should be removed from the driver:
$ git grep BREAKC
[...]
src/gallium/drivers/svga/svga_tgsi_insn.c:   case TGSI_OPCODE_BREAKC:     return SVGA3DOP_BREAKC;
[...]

>  
>  .. 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

C-style

> 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

evaluated

> 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
> 


Reviewed-by: Jose Fonseca <jfonseca at vmware.com>