3d_gpu/architecture/dynamic_simd/simdscope.mdwn

   1 # SimdScope
   2
   3 Links:
   4
   5 * <https://bugs.libre-soc.org/show_bug.cgi?id=734>
   6
   7 TODO
   8
   9 SimdScope is the user-facing "front" behind which SimdSignal
  10 is entirely and transparently hidden.  Aside from using it,
  11 the goal and its purpose is that
  12 developers should under no circumstances have to know
  13 that their HDL, which was initially written as scalar
  14 nmigen HDL, is behaving entirely transparently as full
  15 SIMD capable HDL.  There are a few caveats to that: some
  16 capabilities such as LHS assignment to an ast.Part are so
  17 complex in a SIMD context that SimdSignal in its first
  18 version does not implement it.  Array is out at the moment
  19 as well.  Over time this may change.
  20
  21 SimdScope is used as follows:
  22
  23     m = Module()
  24     elwid = Signal(2)
  25     vec_el_counts = { 0b00: 1, 0b01: 2, 0b10: 4, 0b11: 8}
  26     with SimdScope(m, elwid, vec_el_counts, scalar=pspec.scalar) as s:
  27         a = s.Signal(64)
  28         b = s.Signal(32)
  29
  30     with m.If(a > 2):
  31         m.d.comb += b.eq(a[:32])
  32
  33 Note that the scalar parameter is selected from a runtime/compiletime
  34 configuration parameter which can alter the context between scalar and
  35 SIMD.
  36
  37 When set to scalar, SimdScope.Signal simply re-routes directly
  38 to nmigen.ast.Signal and in this way sets the mandatory expectation
  39 that **under no circumstances** shall SimdScope or SimdSignal alter
  40 the fundamental language behavioural characteristics of Type 1 (AST)
  41 or Type 2 (dsl.Module)
  42
  43 Note that under some circumstances, particularly temporary intermediate
  44 results, it may be necessary to introduce explicit SimdShape instances
  45 containing elwid-specific element widths.  Relevant examples here include
  46 exponent and mantissa for IEEE754FP
  47
  48     m = Module()
  49     elwid = Signal(2)
  50     vec_el_counts = { 0b00: 1, 0b01: 2, 0b10: 4, 0b11: 4}
  51     with SimdScope(m, elwid, vec_el_counts, scalar=pspec.scalar) as s:
  52         expshape = SimdShape(part_shape={0b00: 11, # FP64
  53                                          0b01: 8,  # FP32
  54                                          0b10: 5,  # FP16
  55                                          0b01: 8}  # BF16
  56         exp = s.Signal(expshape)
  57
  58 Here, because SimdShape derives from Shape, things still work
  59 because SimdShape works out that its maximum scalar size is
  60 11, and sets Shape.width to 11 when SimdScope is set in
  61 scalar mode.  When scalar=False, full SIMD is activated and
  62 the resultant HDL combines vec_el_counts with expshape as part
  63 of an ALU with inputs that can be
  64 1xFP64, 2xFP32, 4xFP16, 4xBF16, where the exponents are 1x11, 2x8, 4x5, 4x8
  65 respectively.
  66
  67 Behind the scenes, when calling SimdShape.Signal in SIMD mode,
  68 the elwid and vec_el_counts parameters from the context are combined
  69 with the SimdShape passed in to SimdScope.Signsl,
  70 as inputs to create a layout() that is "Element-width
  71 aware" (ElwidPartType).  With the full information being passed in to
  72 SimdSignals, the actual use of the SimdSignals need not be inside
  73 the Context Manager.