# Dynamic Partitioned Slice (`SimdSlice`)

In order to match the semantics of nmigen's `Slice` class, `SimdSlice` has to have each element of the result have
exactly the same `Shape` as the result of slicing the input `SimdSignal`'s corresponding element.

## Example code:

```python
a_s = SimdSignal(...)
a = a_s.sig # shorthand to make table smaller
b_s = a_s[3:6]
b = b_s.sig # shorthand to make table smaller
```

## `a`'s Elements:

(TODO 1: shrink to only 4 partitions.  TODO 2: convert to markdown)

<table>
    <tr class="text-right">
        <th scope="row" class="text-left">Bit #</th>
        <td>63&#8288;&hellip;&#8288;56</td>
        <td>55&#8288;&hellip;&#8288;48</td>
        <td>47&#8288;&hellip;&#8288;40</td>
        <td>39&#8288;&hellip;&#8288;32</td>
        <td>31&#8288;&hellip;&#8288;24</td>
        <td>23&#8288;&hellip;&#8288;16</td>
        <td>15&#8288;&hellip;&#8288;8</td>
        <td>7&#8288;&hellip;&#8288;0</td>
    </tr>
    <tr class="text-right">
        <th scope="row" class="text-left">ElWid: 8-bit</th>
        <td><code>a[56:64]</code></td>
        <td><code>a[48:56]</code></td>
        <td><code>a[40:48]</code></td>
        <td><code>a[32:40]</code></td>
        <td><code>a[24:32]</code></td>
        <td><code>a[16:24]</code></td>
        <td><code>a[8:16]</code></td>
        <td><code>a[0:8]</code></td>
    </tr>
    <tr class="text-right">
        <th scope="row" class="text-left">ElWid: 16-bit</th>
        <td colspan="2"><code>a[48:64]</code></td>
        <td colspan="2"><code>a[32:48]</code></td>
        <td colspan="2"><code>a[16:32]</code></td>
        <td colspan="2"><code>a[0:16]</code></td>
    </tr>
    <tr class="text-right">
        <th scope="row" class="text-left">ElWid: 32-bit</th>
        <td colspan="4"><code>a[32:64]</code></td>
        <td colspan="4"><code>a[0:32]</code></td>
    </tr>
    <tr class="text-right">
        <th scope="row" class="text-left">ElWid: 64-bit</th>
        <td colspan="8"><code>a[0:64]</code></td>
    </tr>
</table>

So, slicing bits `3:6` of a 32-bit element of `a` must, because we have to match nmigen, produce a 3-bit element, which might seem like no problem, however, slicing bits `3:6` of a 16-bit element of a 64-bit `SimdSignal` must *also* produce a 3-bit element, so, in order to get a `SimdSignal` where *all* elements are 3-bit elements, as required by `SimdSlice`'s output, we have to introduce padding:

## `b`'s Elements:

(TODO 1: shrink to only 4 partitions.  TODO 2: convert to markdown)

<table>
    <tr class="text-right">
        <th scope="row" class="text-left">Bit #</th>
        <td>23&#8288;&hellip;&#8288;21</td>
        <td>20&#8288;&hellip;&#8288;18</td>
        <td>17&#8288;&hellip;&#8288;15</td>
        <td>14&#8288;&hellip;&#8288;12</td>
        <td>11&#8288;&hellip;&#8288;9</td>
        <td>8&#8288;&hellip;&#8288;6</td>
        <td>5&#8288;&hellip;&#8288;3</td>
        <td>2&#8288;&hellip;&#8288;0</td>
    </tr>
    <tr class="text-right">
        <th scope="row" class="text-left">ElWid: 8-bit</th>
        <td><code>b[21:24]</code></td>
        <td><code>b[18:21]</code></td>
        <td><code>b[15:18]</code></td>
        <td><code>b[12:15]</code></td>
        <td><code>b[9:12]</code></td>
        <td><code>b[6:9]</code></td>
        <td><code>b[3:6]</code></td>
        <td><code>b[0:3]</code></td>
    </tr>
    <tr class="text-right">
        <th scope="row" class="text-left">ElWid: 16-bit</th>
        <td class="text-center"><i>Padding</i></td>
        <td><code>b[18:21]</code></td>
        <td class="text-center"><i>Padding</i></td>
        <td><code>b[12:15]</code></td>
        <td class="text-center"><i>Padding</i></td>
        <td><code>b[6:9]</code></td>
        <td class="text-center"><i>Padding</i></td>
        <td><code>b[0:3]</code></td>
    </tr>
    <tr class="text-right">
        <th scope="row" class="text-left">ElWid: 32-bit</th>
        <td colspan="3" class="text-center"><i>Padding</i></td>
        <td><code>b[12:15]</code></td>
        <td colspan="3" class="text-center"><i>Padding</i></td>
        <td><code>b[0:3]</code></td>
    </tr>
    <tr class="text-right">
        <th scope="row" class="text-left">ElWid: 64-bit</th>
        <td colspan="7" class="text-center"><i>Padding</i></td>
        <td><code>b[0:3]</code></td>
    </tr>
</table>

<style>
    /* duplicated from bootstrap so text editors can see it
        -- ignored by ikiwiki */
    .text-left {
        text-align: left !important
    }

    .text-right {
        text-align: right !important
    }

    .text-center {
        text-align: center !important
    }
</style>

# Partitioned SIMD Design implications

Slice is the very first of the entire suite of sub-modules of Partitioned
SimdSignal that requires (and propagates) fixed element widths.  All other
sub-modules have up until this point been a fixed *overall* width where the
element widths adapt to completely fill the entire underlying Signal.

(**This includes for [[dynamic_simd/eq]] and other comparators and the
[[dynamic_simd/logicops]] which very deliberately propagate the LSB boolean
value in each partition throughout the entire partition on a per-element
basis in order to make Mux and Switch function correctly**)

Given that this new width context is then passed through to other SimdSignals,
the entire SimdSignal suite has to adapt to this change in requirements.
It is however not as big an adaptation as it first seems, because ultimately
SimdSignals use PartitionPoints (and a PartType) to decide what to do.
Illustrating that SimdSignal uses PartitionPoints to make its decisions
at the low level, an add example using `b` and a new SimdSignal `c` of
an overall 8-bit width (with fixed element widths of size 2):

(TODO: add an example of how this would then do e.g. an add (to another
SimdSignal of only 8 bits in length or so - all element widths being
2 in all partitions, but having the exact same PartitionPoints)

Questions raised by the add example:

* after performing a Slice, which creates an entirely new
  (padded) set of PartitionPoints, where does c's PartitionPoints
  come from?
* how should a SimdSignal that does not contain the same
  padding be add()ed to a Slice()d SimdSignal that does *not*
  contain padding, having a completely different set of PartitionPoints?
* what happens when a fixed element width Slice()d source `b` is
  add()ed to a fixed *overall* width SimdSignal of width 8 that
  permits variable-length (max available space) elements?

Illustrating the case of adding a SimdSignal with padding to one that
does not:

(TODO: add a second example of how this would then do e.g. an add (to another
SimdSignal of only 8 bits in length or so, but having a **different**
style of PartitionPoints, with no padding this time)

take signal a, of 16 bits, each bit being numbered in hexadecimal:

            |        |        |
    AfAeAdAc AbAaA9A8 A7A6A5A4 A3A2A1A0

and take a slice a[0:1] to create 3-bit values, where padding is
specified by "x", at each elwid:

    elwid        |        |        |
    0b00 x x x x  x x x x  x x x x  x A2A1A0
    0b01 x x x x  x AaA9A8 x x x x  x A2A1A0
    0b10 x AeAdAc x AaA9A8 x A6A5A4 x A2A1A0

Illustrating the case where a Sliced (fixed element width) SimdSignal
is added to one which has variable-length elements that take up the
entirety of the partition (overall fixed width):

(TODO: third example)