src/ieee754/part/partsig.py

   1 # SPDX-License-Identifier: LGPL-2.1-or-later
   2 # See Notices.txt for copyright information
   3
   4 """
   5 Copyright (C) 2020 Luke Kenneth Casson Leighton <lkcl@lkcl.net>
   6
   7 dynamic-partitionable class similar to Signal, which, when the partition
   8 is fully open will be identical to Signal.  when partitions are closed,
   9 the class turns into a SIMD variant of Signal.  *this is dynamic*.
  10
  11 the basic fundamental idea is: write code once, and if you want a SIMD
  12 version of it, use SimdSignal in place of Signal.  job done.
  13 this however requires the code to *not* be designed to use nmigen.If,
  14 nmigen.Case, or other constructs: only Mux and other logic.
  15
  16 * http://bugs.libre-riscv.org/show_bug.cgi?id=132
  17 """
  18
  19 from ieee754.part_mul_add.adder import PartitionedAdder
  20 from ieee754.part_cmp.eq_gt_ge import PartitionedEqGtGe
  21 from ieee754.part_bits.xor import PartitionedXOR
  22 from ieee754.part_bits.bool import PartitionedBool
  23 from ieee754.part_bits.all import PartitionedAll
  24 from ieee754.part_shift.part_shift_dynamic import PartitionedDynamicShift
  25 from ieee754.part_shift.part_shift_scalar import PartitionedScalarShift
  26 from ieee754.part_mul_add.partpoints import make_partition2, PartitionPoints
  27 from ieee754.part_mux.part_mux import PMux
  28 from ieee754.part_ass.passign import PAssign
  29 from ieee754.part_cat.pcat import PCat
  30 from ieee754.part_repl.prepl import PRepl
  31 from ieee754.part.simd_scope import SimdScope
  32 from ieee754.part.layout_experiment import layout
  33 from operator import or_, xor, and_, not_
  34
  35 from nmigen import (Signal, Const, Cat)
  36 from nmigen.hdl.ast import UserValue, Shape
  37
  38
  39 def getsig(op1):
  40     if isinstance(op1, SimdSignal):
  41         op1 = op1.sig
  42     return op1
  43
  44
  45 def applyop(op1, op2, op):
  46     if isinstance(op1, SimdSignal):
  47         result = SimdSignal.like(op1)
  48     else:
  49         result = SimdSignal.like(op2)
  50     result.m.d.comb += result.sig.eq(op(getsig(op1), getsig(op2)))
  51     return result
  52
  53
  54 global modnames
  55 modnames = {}
  56 # for sub-modules to be created on-demand. Mux is done slightly
  57 # differently (has its own global)
  58 for name in ['add', 'eq', 'gt', 'ge', 'ls', 'xor', 'bool', 'all']:
  59     modnames[name] = 0
  60
  61
  62 # Prototype https://bugs.libre-soc.org/show_bug.cgi?id=713#c53
  63 # this provides a "compatibility" layer with existing SimdSignal
  64 # behaviour.  the idea is that this interface defines which "combinations"
  65 # of partition selections are relevant, and as an added bonus it says
  66 # which partition lanes are completely irrelevant (padding, blank).
  67 class PartType:  # TODO decide name
  68     def __init__(self, psig):
  69         self.psig = psig
  70
  71     def get_mask(self):
  72         return list(self.psig.partpoints.values())
  73
  74     def get_switch(self):
  75         return Cat(self.get_mask())
  76
  77     def get_cases(self):
  78         return range(1 << len(self.get_mask()))
  79
  80     @property
  81     def blanklanes(self):
  82         return 0
  83
  84
  85 # this one would be an elwidth version
  86 # see https://bugs.libre-soc.org/show_bug.cgi?id=713#c34
  87 # it requires an "adapter" which is the layout() function
  88 # where the PartitionPoints was *created* by the layout()
  89 # function and this class then "understands" the relationship
  90 # between elwidth and the PartitionPoints that were created
  91 # by layout()
  92 class ElwidPartType:  # TODO decide name
  93     def __init__(self, psig):
  94         self.psig = psig
  95
  96     def get_mask(self):
  97         return list(self.psig._shape.partpoints.values())  # i think
  98
  99     def get_switch(self):
 100         return self.psig.scope.elwid       # switch on elwid: match get_cases()
 101
 102     def get_cases(self):
 103         return self.psig._shape.bitp.keys() # all possible values of elwid
 104
 105     @property
 106     def blanklanes(self):
 107         return self.psig.shape.blankmask
 108
 109
 110 class SimdShape(Shape):
 111     """a SIMD variant of Shape. supports:
 112     * fixed overall width with variable (maxed-out) element lengths
 113     * fixed element widths with overall size auto-determined
 114     * both fixed overall width and fixed element widths
 115
 116     naming is preserved to be compatible with Shape().
 117     """
 118     def __init__(self, scope, width=None, # this is actually widths_at_elwid
 119                               signed=False,
 120                               fixed_width=None): # fixed overall width
 121         widths_at_elwid = width
 122         print ("SimdShape width", width, "fixed_width", fixed_width)
 123         # this check is done inside layout but do it again here anyway
 124         assert fixed_width != None or widths_at_elwid != None, \
 125             "both width (widths_at_elwid) and fixed_width cannot be None"
 126         (pp, bitp, lpoints, bmask, fixed_width, lane_shapes, part_wid) = \
 127             layout(scope.elwid,
 128                    scope.vec_el_counts,
 129                    widths_at_elwid,
 130                    fixed_width)
 131         self.partpoints = pp
 132         self.bitp = bitp        # binary values for partpoints at each elwidth
 133         self.lpoints = lpoints  # layout ranges
 134         self.blankmask = bmask  # blanking mask (partitions always padding)
 135         self.partwid = part_wid # smallest alignment start point for elements
 136
 137         # pass through the calculated width to Shape() so that when/if
 138         # objects using this Shape are downcast, they know exactly how to
 139         # get *all* bits and need know absolutely nothing about SIMD at all
 140         Shape.__init__(self, fixed_width, signed)
 141
 142
 143 class SimdSignal(UserValue):
 144     # XXX ################################################### XXX
 145     # XXX Keep these functions in the same order as ast.Value XXX
 146     # XXX ################################################### XXX
 147     def __init__(self, mask, shape=None, *args,
 148                        src_loc_at=0, fixed_width=None, **kwargs):
 149         super().__init__(src_loc_at=src_loc_at)
 150         print ("SimdSignal shape", shape)
 151         # create partition points
 152         if isinstance(mask, SimdScope): # mask parameter is a SimdScope
 153             self.scope = mask
 154             self.ptype = ElwidPartType(self)
 155             # adapt shape to a SimdShape
 156             if not isinstance(shape, SimdShape):
 157                 shape = SimdShape(self.scope, shape, fixed_width=fixed_width)
 158             self._shape = shape
 159             self.sig = Signal(shape, *args, **kwargs)
 160             # get partpoints from SimdShape
 161             self.partpoints = shape.partpoints
 162         else:
 163             self.sig = Signal(shape, *args, **kwargs)
 164             width = len(self.sig)  # get signal width
 165             if isinstance(mask, PartitionPoints):
 166                 self.partpoints = mask
 167             else:
 168                 self.partpoints = make_partition2(mask, width)
 169             self.ptype = PartType(self)
 170
 171     def set_module(self, m):
 172         self.m = m
 173
 174     def get_modname(self, category):
 175         modnames[category] += 1
 176         return "%s_%d" % (category, modnames[category])
 177
 178     @staticmethod
 179     def like(other, *args, **kwargs):
 180         """Builds a new SimdSignal with the same PartitionPoints and
 181         Signal properties as the other"""
 182         result = SimdSignal(PartitionPoints(other.partpoints))
 183         result.sig = Signal.like(other.sig, *args, **kwargs)
 184         result.m = other.m
 185         return result
 186
 187     def lower(self):
 188         return self.sig
 189
 190     # nmigen-redirected constructs (Mux, Cat, Switch, Assign)
 191
 192     # TODO, http://bugs.libre-riscv.org/show_bug.cgi?id=716
 193     #def __Part__(self, offset, width, stride=1, *, src_loc_at=0):
 194         raise NotImplementedError("TODO: implement as "
 195                         "(self>>(offset*stride)[:width]")
 196     # TODO, http://bugs.libre-riscv.org/show_bug.cgi?id=716
 197     def __Slice__(self, start, stop, *, src_loc_at=0):
 198         # NO.  Swizzled shall NOT be deployed, it violates
 199         # Project Development Practices
 200         raise NotImplementedError("TODO: need PartitionedSlice")
 201
 202     def __Repl__(self, count, *, src_loc_at=0):
 203         return PRepl(self.m, self, count, self.ptype)
 204
 205     def __Cat__(self, *args, src_loc_at=0):
 206         print ("partsig cat", self, args)
 207         # TODO: need SwizzledSimdValue-aware Cat
 208         args = [self] + list(args)
 209         for sig in args:
 210             assert isinstance(sig, SimdSignal), \
 211                 "All SimdSignal.__Cat__ arguments must be " \
 212                 "a SimdSignal. %s is not." % repr(sig)
 213         return PCat(self.m, args, self.ptype)
 214
 215     def __Mux__(self, val1, val2):
 216         # print ("partsig mux", self, val1, val2)
 217         assert len(val1) == len(val2), \
 218             "SimdSignal width sources must be the same " \
 219             "val1 == %d, val2 == %d" % (len(val1), len(val2))
 220         return PMux(self.m, self.partpoints, self, val1, val2, self.ptype)
 221
 222     def __Assign__(self, val, *, src_loc_at=0):
 223         print ("partsig assign", self, val)
 224         # this is a truly awful hack, outlined here:
 225         # https://bugs.libre-soc.org/show_bug.cgi?id=731#c13
 226         # during the period between constructing Simd-aware sub-modules
 227         # and the elaborate() being called on them there is a window of
 228         # opportunity to indicate which of those submodules is LHS and
 229         # which is RHS. manic laughter is permitted.  *gibber*.
 230         if hasattr(self, "_hack_submodule"):
 231             self._hack_submodule.set_lhs_mode(True)
 232         if hasattr(val, "_hack_submodule"):
 233             val._hack_submodule.set_lhs_mode(False)
 234         return PAssign(self.m, self, val, self.ptype)
 235
 236     # TODO, http://bugs.libre-riscv.org/show_bug.cgi?id=458
 237     # def __Switch__(self, cases, *, src_loc=None, src_loc_at=0,
 238     #                               case_src_locs={}):
 239
 240     # no override needed, Value.__bool__ sufficient
 241     # def __bool__(self):
 242
 243     # unary ops that do not require partitioning
 244
 245     def __invert__(self):
 246         result = SimdSignal.like(self)
 247         self.m.d.comb += result.sig.eq(~self.sig)
 248         return result
 249
 250     # unary ops that require partitioning
 251
 252     def __neg__(self):
 253         z = Const(0, len(self.sig))
 254         result, _ = self.sub_op(z, self)
 255         return result
 256
 257     # binary ops that need partitioning
 258
 259     def add_op(self, op1, op2, carry):
 260         op1 = getsig(op1)
 261         op2 = getsig(op2)
 262         pa = PartitionedAdder(len(op1), self.partpoints)
 263         setattr(self.m.submodules, self.get_modname('add'), pa)
 264         comb = self.m.d.comb
 265         comb += pa.a.eq(op1)
 266         comb += pa.b.eq(op2)
 267         comb += pa.carry_in.eq(carry)
 268         result = SimdSignal.like(self)
 269         comb += result.sig.eq(pa.output)
 270         return result, pa.carry_out
 271
 272     def sub_op(self, op1, op2, carry=~0):
 273         op1 = getsig(op1)
 274         op2 = getsig(op2)
 275         pa = PartitionedAdder(len(op1), self.partpoints)
 276         setattr(self.m.submodules, self.get_modname('add'), pa)
 277         comb = self.m.d.comb
 278         comb += pa.a.eq(op1)
 279         comb += pa.b.eq(~op2)
 280         comb += pa.carry_in.eq(carry)
 281         result = SimdSignal.like(self)
 282         comb += result.sig.eq(pa.output)
 283         return result, pa.carry_out
 284
 285     def __add__(self, other):
 286         result, _ = self.add_op(self, other, carry=0)
 287         return result
 288
 289     def __radd__(self, other):
 290         #   https://bugs.libre-soc.org/show_bug.cgi?id=718
 291         result, _ = self.add_op(other, self)
 292         return result
 293
 294     def __sub__(self, other):
 295         result, _ = self.sub_op(self, other)
 296         return result
 297
 298     def __rsub__(self, other):
 299         #   https://bugs.libre-soc.org/show_bug.cgi?id=718
 300         result, _ = self.sub_op(other, self)
 301         return result
 302
 303     def __mul__(self, other):
 304         raise NotImplementedError  # too complicated at the moment
 305         return Operator("*", [self, other])
 306
 307     def __rmul__(self, other):
 308         raise NotImplementedError  # too complicated at the moment
 309         return Operator("*", [other, self])
 310
 311     # not needed: same as Value.__check_divisor
 312     # def __check_divisor(self):
 313
 314     def __mod__(self, other):
 315         raise NotImplementedError
 316         other = Value.cast(other)
 317         other.__check_divisor()
 318         return Operator("%", [self, other])
 319
 320     def __rmod__(self, other):
 321         raise NotImplementedError
 322         self.__check_divisor()
 323         return Operator("%", [other, self])
 324
 325     def __floordiv__(self, other):
 326         raise NotImplementedError
 327         other = Value.cast(other)
 328         other.__check_divisor()
 329         return Operator("//", [self, other])
 330
 331     def __rfloordiv__(self, other):
 332         raise NotImplementedError
 333         self.__check_divisor()
 334         return Operator("//", [other, self])
 335
 336     # not needed: same as Value.__check_shamt
 337     # def __check_shamt(self):
 338
 339     # TODO: detect if the 2nd operand is a Const, a Signal or a
 340     # SimdSignal.  if it's a Const or a Signal, a global shift
 341     # can occur.  if it's a SimdSignal, that's much more interesting.
 342     def ls_op(self, op1, op2, carry, shr_flag=0):
 343         op1 = getsig(op1)
 344         if isinstance(op2, Const) or isinstance(op2, Signal):
 345             scalar = True
 346             pa = PartitionedScalarShift(len(op1), self.partpoints)
 347         else:
 348             scalar = False
 349             op2 = getsig(op2)
 350             pa = PartitionedDynamicShift(len(op1), self.partpoints)
 351         # else:
 352         #   TODO: case where the *shifter* is a SimdSignal but
 353         #   the thing *being* Shifted is a scalar (Signal, expression)
 354         #   https://bugs.libre-soc.org/show_bug.cgi?id=718
 355         setattr(self.m.submodules, self.get_modname('ls'), pa)
 356         comb = self.m.d.comb
 357         if scalar:
 358             comb += pa.data.eq(op1)
 359             comb += pa.shifter.eq(op2)
 360             comb += pa.shift_right.eq(shr_flag)
 361         else:
 362             comb += pa.a.eq(op1)
 363             comb += pa.b.eq(op2)
 364             comb += pa.shift_right.eq(shr_flag)
 365         # XXX TODO: carry-in, carry-out (for arithmetic shift)
 366         #comb += pa.carry_in.eq(carry)
 367         return (pa.output, 0)
 368
 369     def __lshift__(self, other):
 370         z = Const(0, len(self.partpoints)+1)
 371         result, _ = self.ls_op(self, other, carry=z)  # TODO, carry
 372         return result
 373
 374     def __rlshift__(self, other):
 375         #   https://bugs.libre-soc.org/show_bug.cgi?id=718
 376         raise NotImplementedError
 377         return Operator("<<", [other, self])
 378
 379     def __rshift__(self, other):
 380         z = Const(0, len(self.partpoints)+1)
 381         result, _ = self.ls_op(self, other, carry=z, shr_flag=1)  # TODO, carry
 382         return result
 383
 384     def __rrshift__(self, other):
 385         #   https://bugs.libre-soc.org/show_bug.cgi?id=718
 386         raise NotImplementedError
 387         return Operator(">>", [other, self])
 388
 389     # binary ops that don't require partitioning
 390
 391     def __and__(self, other):
 392         return applyop(self, other, and_)
 393
 394     def __rand__(self, other):
 395         return applyop(other, self, and_)
 396
 397     def __or__(self, other):
 398         return applyop(self, other, or_)
 399
 400     def __ror__(self, other):
 401         return applyop(other, self, or_)
 402
 403     def __xor__(self, other):
 404         return applyop(self, other, xor)
 405
 406     def __rxor__(self, other):
 407         return applyop(other, self, xor)
 408
 409     # binary comparison ops that need partitioning
 410
 411     def _compare(self, width, op1, op2, opname, optype):
 412         # print (opname, op1, op2)
 413         pa = PartitionedEqGtGe(width, self.partpoints)
 414         setattr(self.m.submodules, self.get_modname(opname), pa)
 415         comb = self.m.d.comb
 416         comb += pa.opcode.eq(optype)  # set opcode
 417         if isinstance(op1, SimdSignal):
 418             comb += pa.a.eq(op1.sig)
 419         else:
 420             comb += pa.a.eq(op1)
 421         if isinstance(op2, SimdSignal):
 422             comb += pa.b.eq(op2.sig)
 423         else:
 424             comb += pa.b.eq(op2)
 425         return pa.output
 426
 427     def __eq__(self, other):
 428         width = len(self.sig)
 429         return self._compare(width, self, other, "eq", PartitionedEqGtGe.EQ)
 430
 431     def __ne__(self, other):
 432         width = len(self.sig)
 433         eq = self._compare(width, self, other, "eq", PartitionedEqGtGe.EQ)
 434         ne = Signal(eq.width)
 435         self.m.d.comb += ne.eq(~eq)
 436         return ne
 437
 438     def __lt__(self, other):
 439         width = len(self.sig)
 440         # swap operands, use gt to do lt
 441         return self._compare(width, other, self, "gt", PartitionedEqGtGe.GT)
 442
 443     def __le__(self, other):
 444         width = len(self.sig)
 445         # swap operands, use ge to do le
 446         return self._compare(width, other, self, "ge", PartitionedEqGtGe.GE)
 447
 448     def __gt__(self, other):
 449         width = len(self.sig)
 450         return self._compare(width, self, other, "gt", PartitionedEqGtGe.GT)
 451
 452     def __ge__(self, other):
 453         width = len(self.sig)
 454         return self._compare(width, self, other, "ge", PartitionedEqGtGe.GE)
 455
 456     # no override needed: Value.__abs__ is general enough it does the job
 457     # def __abs__(self):
 458
 459     def __len__(self):
 460         return len(self.sig)
 461
 462     # TODO, http://bugs.libre-riscv.org/show_bug.cgi?id=716
 463     # def __getitem__(self, key):
 464
 465     def __new_sign(self, signed):
 466         # XXX NO - SimdShape not Shape
 467         print ("XXX requires SimdShape not Shape")
 468         shape = Shape(len(self), signed=signed)
 469         result = SimdSignal.like(self, shape=shape)
 470         self.m.d.comb += result.sig.eq(self.sig)
 471         return result
 472
 473     # http://bugs.libre-riscv.org/show_bug.cgi?id=719
 474     def as_unsigned(self):
 475         return self.__new_sign(False)
 476
 477     def as_signed(self):
 478         return self.__new_sign(True)
 479
 480     # useful operators
 481
 482     def bool(self):
 483         """Conversion to boolean.
 484
 485         Returns
 486         -------
 487         Value, out
 488             ``1`` if any bits are set, ``0`` otherwise.
 489         """
 490         width = len(self.sig)
 491         pa = PartitionedBool(width, self.partpoints)
 492         setattr(self.m.submodules, self.get_modname("bool"), pa)
 493         self.m.d.comb += pa.a.eq(self.sig)
 494         return pa.output
 495
 496     def any(self):
 497         """Check if any bits are ``1``.
 498
 499         Returns
 500         -------
 501         Value, out
 502             ``1`` if any bits are set, ``0`` otherwise.
 503         """
 504         return self != Const(0)  # leverage the __ne__ operator here
 505         return Operator("r|", [self])
 506
 507     def all(self):
 508         """Check if all bits are ``1``.
 509
 510         Returns
 511         -------
 512         Value, out
 513             ``1`` if all bits are set, ``0`` otherwise.
 514         """
 515         # something wrong with PartitionedAll, but self == Const(-1)"
 516         # XXX https://bugs.libre-soc.org/show_bug.cgi?id=176#c17
 517         #width = len(self.sig)
 518         #pa = PartitionedAll(width, self.partpoints)
 519         #setattr(self.m.submodules, self.get_modname("all"), pa)
 520         #self.m.d.comb += pa.a.eq(self.sig)
 521         # return pa.output
 522         return self == Const(-1)  # leverage the __eq__ operator here
 523
 524     def xor(self):
 525         """Compute pairwise exclusive-or of every bit.
 526
 527         Returns
 528         -------
 529         Value, out
 530             ``1`` if an odd number of bits are set, ``0`` if an
 531                   even number of bits are set.
 532         """
 533         width = len(self.sig)
 534         pa = PartitionedXOR(width, self.partpoints)
 535         setattr(self.m.submodules, self.get_modname("xor"), pa)
 536         self.m.d.comb += pa.a.eq(self.sig)
 537         return pa.output
 538
 539     # not needed: Value.implies does the job
 540     # def implies(premise, conclusion):
 541
 542     # TODO. contains a Value.cast which means an override is needed (on both)
 543     # def bit_select(self, offset, width):
 544     # def word_select(self, offset, width):
 545
 546     # not needed: Value.matches, amazingly, should do the job
 547     # def matches(self, *patterns):
 548
 549     # TODO, http://bugs.libre-riscv.org/show_bug.cgi?id=713
 550     def shape(self):
 551         return self.sig.shape()