src/freedreno/computerator/README.rst

   1 Overview
   2 ========
   3
   4 Computerator is a tool to launch compute shaders, written in assembly.
   5 The main purpose is to have an easy way to experiment with instructions
   6 without dealing with the entire compiler stack (which makes controlling
   7 the order of instructions, the registers chosen, etc, difficult).  The
   8 choice of compute shaders is simply because there is far less state
   9 setup required.
  10
  11 Headers
  12 -------
  13
  14 The shader assembly can be prefixed with headers to control state setup:
  15
  16 * ``@localsize X, Y, Z`` - configures local workgroup size
  17 * ``@buf SZ`` - configures an SSBO of the specified size (in dwords).
  18   The order of the ``@buf`` headers determines the index, ie the first
  19   ``@buf`` header is ``g[0]``, the second ``g[1]``, and so on
  20 * ``@const(cN.c)`` configures a const vec4 starting at specified
  21   const register, ie ``@const(c1.x) 1.0, 2.0, 3.0, 4.0`` will populate
  22   ``c1.xyzw`` with ``vec4(1.0, 2.0, 3.0, 4.0)``
  23 * ``@invocationid(rN.c)`` will populate a vec3 starting at the specified
  24   register with the local invocation-id
  25 * ``@wgid(rN.c)`` will populate a vec3 starting at the specified register
  26   with the workgroup-id (must be a high-reg, ie. ``r48.x`` and above)
  27 * ``@numwg(cN.c)`` will populate a vec3 starting at the specified const
  28   register
  29
  30 Example
  31 -------
  32
  33 ```
  34 @localsize 32, 1, 1
  35 @buf 32  ; g[0]
  36 @const(c0.x)  0.0, 0.0, 0.0, 0.0
  37 @const(c1.x)  1.0, 2.0, 3.0, 4.0
  38 @wgid(r48.x)        ; r48.xyz
  39 @invocationid(r0.x) ; r0.xyz
  40 @numwg(c2.x)        ; c2.xyz
  41 mov.u32u32 r0.y, r0.x
  42 (rpt5)nop
  43 stib.untyped.1d.u32.1 g[0] + r0.y, r0.x
  44 end
  45 nop
  46 ```
  47
  48 Usage
  49 -----
  50
  51 ```
  52 cat myshader.asm | ./computerator --disasm --groups=4,4,4
  53 ```
  54