src/add/nmigen_add_experiment.py

   1 # IEEE Floating Point Adder (Single Precision)
   2 # Copyright (C) Jonathan P Dawson 2013
   3 # 2013-12-12
   4
   5 from nmigen import Module, Signal, Cat, Const
   6 from nmigen.cli import main, verilog
   7
   8
   9 class FPNum:
  10     """ Floating-point Number Class, variable-width TODO (currently 32-bit)
  11
  12         Contains signals for an incoming copy of the value, decoded into
  13         sign / exponent / mantissa.
  14         Also contains encoding functions, creation and recognition of
  15         zero, NaN and inf (all signed)
  16
  17         Four extra bits are included in the mantissa: the top bit
  18         (m[-1]) is effectively a carry-overflow.  The other three are
  19         guard (m[2]), round (m[1]), and sticky (m[0])
  20     """
  21     def __init__(self, width, m_width=None):
  22         self.width = width
  23         if m_width is None:
  24             m_width = width - 5 # mantissa extra bits (top,guard,round)
  25         self.v = Signal(width)      # Latched copy of value
  26         self.m = Signal(m_width)    # Mantissa
  27         self.e = Signal((10, True)) # Exponent: 10 bits, signed
  28         self.s = Signal()           # Sign bit
  29
  30         self.mzero = Const(0, (m_width, False))
  31         self.P127 = Const(127, (10, True))
  32         self.N127 = Const(-127, (10, True))
  33         self.N126 = Const(-126, (10, True))
  34
  35     def decode(self):
  36         """ decodes a latched value into sign / exponent / mantissa
  37
  38             bias is subtracted here, from the exponent.  exponent
  39             is extended to 10 bits so that subtract 127 is done on
  40             a 10-bit number
  41         """
  42         v = self.v
  43         return [self.m.eq(Cat(0, 0, 0, v[0:23])), # mantissa
  44                 self.e.eq(v[23:31] - self.P127), # exp (minus bias)
  45                 self.s.eq(v[31]),                 # sign
  46                 ]
  47
  48     def create(self, s, e, m):
  49         """ creates a value from sign / exponent / mantissa
  50
  51             bias is added here, to the exponent
  52         """
  53         return [
  54           self.v[31].eq(s),          # sign
  55           self.v[23:31].eq(e + self.P127), # exp (add on bias)
  56           self.v[0:23].eq(m)         # mantissa
  57         ]
  58
  59     def shift_down(self):
  60         """ shifts a mantissa down by one. exponent is increased to compensate
  61
  62             accuracy is lost as a result in the mantissa however there are 3
  63             guard bits (the latter of which is the "sticky" bit)
  64         """
  65         return [self.e.eq(self.e + 1),
  66                 self.m.eq(Cat(self.m[0] | self.m[1], self.m[1:-5], 0))
  67                ]
  68
  69     def nan(self, s):
  70         return self.create(s, 0x80, 1<<22)
  71
  72     def inf(self, s):
  73         return self.create(s, 0x80, 0)
  74
  75     def zero(self, s):
  76         return self.create(s, -127, 0)
  77
  78     def is_nan(self):
  79         return (self.e == 128) & (self.m != 0)
  80
  81     def is_inf(self):
  82         return (self.e == 128) & (self.m == 0)
  83
  84     def is_zero(self):
  85         return (self.e == self.N127) & (self.m == self.mzero)
  86
  87     def is_overflowed(self):
  88         return (self.e < 127)
  89
  90     def is_denormalised(self):
  91         return (self.e == self.N126) & (self.m[23] == 0)
  92
  93
  94 class FPADD:
  95     def __init__(self, width):
  96         self.width = width
  97
  98         self.in_a     = Signal(width)
  99         self.in_a_stb = Signal()
 100         self.in_a_ack = Signal()
 101
 102         self.in_b     = Signal(width)
 103         self.in_b_stb = Signal()
 104         self.in_b_ack = Signal()
 105
 106         self.out_z     = Signal(width)
 107         self.out_z_stb = Signal()
 108         self.out_z_ack = Signal()
 109
 110     def get_fragment(self, platform=None):
 111         m = Module()
 112
 113         # Latches
 114         a = FPNum(self.width)
 115         b = FPNum(self.width)
 116         z = FPNum(self.width, 24)
 117
 118         tot = Signal(28)     # sticky/round/guard bits, 23 result, 1 overflow
 119
 120         guard = Signal()     # tot[2]
 121         round_bit = Signal() # tot[1]
 122         sticky = Signal()    # tot[0]
 123
 124         with m.FSM() as fsm:
 125
 126             # ******
 127             # gets operand a
 128
 129             with m.State("get_a"):
 130                 with m.If((self.in_a_ack) & (self.in_a_stb)):
 131                     m.next = "get_b"
 132                     m.d.sync += [
 133                         a.v.eq(self.in_a),
 134                         self.in_a_ack.eq(0)
 135                     ]
 136                 with m.Else():
 137                     m.d.sync += self.in_a_ack.eq(1)
 138
 139             # ******
 140             # gets operand b
 141
 142             with m.State("get_b"):
 143                 with m.If((self.in_b_ack) & (self.in_b_stb)):
 144                     m.next = "unpack"
 145                     m.d.sync += [
 146                         b.v.eq(self.in_b),
 147                         self.in_b_ack.eq(0)
 148                     ]
 149                 with m.Else():
 150                     m.d.sync += self.in_b_ack.eq(1)
 151
 152             # ******
 153             # unpacks operands into sign, mantissa and exponent
 154
 155             with m.State("unpack"):
 156                 m.next = "special_cases"
 157                 m.d.sync += a.decode()
 158                 m.d.sync += b.decode()
 159
 160             # ******
 161             # special cases: NaNs, infs, zeros, denormalised
 162
 163             with m.State("special_cases"):
 164
 165                 # if a is NaN or b is NaN return NaN
 166                 with m.If(a.is_nan() | b.is_nan()):
 167                     m.next = "put_z"
 168                     m.d.sync += z.nan(1)
 169
 170                 # if a is inf return inf (or NaN)
 171                 with m.Elif(a.is_inf()):
 172                     m.next = "put_z"
 173                     m.d.sync += z.inf(a.s)
 174                     # if a is inf and signs don't match return NaN
 175                     with m.If((b.e == 128) & (a.s != b.s)):
 176                         m.d.sync += z.nan(b.s)
 177
 178                 # if b is inf return inf
 179                 with m.Elif(b.is_inf()):
 180                     m.next = "put_z"
 181                     m.d.sync += z.inf(b.s)
 182
 183                 # if a is zero and b zero return signed-a/b
 184                 with m.Elif(a.is_zero() & b.is_zero()):
 185                     m.next = "put_z"
 186                     m.d.sync += z.create(a.s & b.s, b.e[0:8], b.m[3:26])
 187
 188                 # if a is zero return b
 189                 with m.Elif(a.is_zero()):
 190                     m.next = "put_z"
 191                     m.d.sync += z.create(b.s, b.e[0:8], b.m[3:26])
 192
 193                 # if b is zero return a
 194                 with m.Elif(b.is_zero()):
 195                     m.next = "put_z"
 196                     m.d.sync += z.create(a.s, a.e[0:8], a.m[3:26])
 197
 198                 # Denormalised Number checks
 199                 with m.Else():
 200                     m.next = "align"
 201                     # denormalise a check
 202                     with m.If(a.e == a.N127):
 203                         m.d.sync += a.e.eq(-126) # limit a exponent
 204                     with m.Else():
 205                         m.d.sync += a.m[26].eq(1) # set top mantissa bit
 206                     # denormalise b check
 207                     with m.If(b.e == a.N127):
 208                         m.d.sync += b.e.eq(-126) # limit b exponent
 209                     with m.Else():
 210                         m.d.sync += b.m[26].eq(1) # set top mantissa bit
 211
 212             # ******
 213             # align.  NOTE: this does *not* do single-cycle multi-shifting,
 214             #         it *STAYS* in the align state until the exponents match
 215
 216             with m.State("align"):
 217                 # exponent of a greater than b: increment b exp, shift b mant
 218                 with m.If(a.e > b.e):
 219                     m.d.sync += b.shift_down()
 220                 # exponent of b greater than a: increment a exp, shift a mant
 221                 with m.Elif(a.e < b.e):
 222                     m.d.sync += a.shift_down()
 223                 # exponents equal: move to next stage.
 224                 with m.Else():
 225                     m.next = "add_0"
 226
 227             # ******
 228             # First stage of add.  covers same-sign (add) and subtract
 229             # special-casing when mantissas are greater or equal, to
 230             # give greatest accuracy.
 231
 232             with m.State("add_0"):
 233                 m.next = "add_1"
 234                 m.d.sync += z.e.eq(a.e)
 235                 # same-sign (both negative or both positive) add mantissas
 236                 with m.If(a.s == b.s):
 237                     m.d.sync += [
 238                         tot.eq(a.m + b.m),
 239                         z.s.eq(a.s)
 240                     ]
 241                 # a mantissa greater than b, use a
 242                 with m.Elif(a.m >= b.m):
 243                     m.d.sync += [
 244                         tot.eq(a.m - b.m),
 245                         z.s.eq(a.s)
 246                     ]
 247                 # b mantissa greater than a, use b
 248                 with m.Else():
 249                     m.d.sync += [
 250                         tot.eq(b.m - a.m),
 251                         z.s.eq(b.s)
 252                 ]
 253
 254             # ******
 255             # Second stage of add: preparation for normalisation.
 256             # detects when tot sum is too big (tot[27] is kinda a carry bit)
 257
 258             with m.State("add_1"):
 259                 m.next = "normalise_1"
 260                 # tot[27] gets set when the sum overflows. shift result down
 261                 with m.If(tot[27]):
 262                     m.d.sync += [
 263                         z.m.eq(tot[4:28]),
 264                         guard.eq(tot[3]),
 265                         round_bit.eq(tot[2]),
 266                         sticky.eq(tot[1] | tot[0]),
 267                         z.e.eq(z.e + 1)
 268                 ]
 269                 # tot[27] zero case
 270                 with m.Else():
 271                     m.d.sync += [
 272                         z.m.eq(tot[3:27]),
 273                         guard.eq(tot[2]),
 274                         round_bit.eq(tot[1]),
 275                         sticky.eq(tot[0])
 276                 ]
 277
 278             # ******
 279             # First stage of normalisation.
 280             # NOTE: just like "align", this one keeps going round every clock
 281             #       until the result's exponent is within acceptable "range"
 282             # NOTE: the weirdness of reassigning guard and round is due to
 283             #       the extra mantissa bits coming from tot[0..2]
 284
 285             with m.State("normalise_1"):
 286                 with m.If((z.m[23] == 0) & (z.e > z.N126)):
 287                     m.d.sync +=[
 288                         z.e.eq(z.e - 1),  # DECREASE exponent
 289                         z.m.eq(z.m << 1), # shift mantissa UP
 290                         z.m[0].eq(guard), # steal guard bit (was tot[2])
 291                         guard.eq(round_bit), # steal round_bit (was tot[1])
 292                     ]
 293                 with m.Else():
 294                     m.next = "normalise_2"
 295
 296             # ******
 297             # Second stage of normalisation.
 298             # NOTE: just like "align", this one keeps going round every clock
 299             #       until the result's exponent is within acceptable "range"
 300             # NOTE: the weirdness of reassigning guard and round is due to
 301             #       the extra mantissa bits coming from tot[0..2]
 302
 303             with m.State("normalise_2"):
 304                 with m.If(z.e < z.N126):
 305                     m.d.sync +=[
 306                         z.e.eq(z.e + 1),  # INCREASE exponent
 307                         z.m.eq(z.m >> 1), # shift mantissa DOWN
 308                         guard.eq(z.m[0]),
 309                         round_bit.eq(guard),
 310                         sticky.eq(sticky | round_bit)
 311                     ]
 312                 with m.Else():
 313                     m.next = "round"
 314
 315             # ******
 316             # rounding stage
 317
 318             with m.State("round"):
 319                 m.next = "corrections"
 320                 with m.If(guard & (round_bit | sticky | z.m[0])):
 321                     m.d.sync += z.m.eq(z.m + 1) # mantissa rounds up
 322                     with m.If(z.m == 0xffffff): # all 1s
 323                         m.d.sync += z.e.eq(z.e + 1) # exponent rounds up
 324
 325             # ******
 326             # correction stage
 327
 328             with m.State("corrections"):
 329                 m.next = "pack"
 330                 # denormalised, correct exponent to zero
 331                 with m.If(z.is_denormalised()):
 332                     m.d.sync += z.m.eq(-127)
 333                 # FIX SIGN BUG: -a + a = +0.
 334                 with m.If((z.e == -126) & (z.m[0:23] == 0)):
 335                     m.d.sync += z.s.eq(0)
 336
 337             # ******
 338             # pack stage
 339
 340             with m.State("pack"):
 341                 m.next = "put_z"
 342                 # if overflow occurs, return inf
 343                 with m.If(z.is_overflowed()):
 344                     m.d.sync += z.inf(0)
 345                 with m.Else():
 346                     m.d.sync += z.create(z.s, z.e, z.m)
 347
 348             # ******
 349             # put_z stage
 350
 351             with m.State("put_z"):
 352               m.d.sync += [
 353                   self.out_z_stb.eq(1),
 354                   self.out_z.eq(z.v)
 355               ]
 356               with m.If(self.out_z_stb & self.out_z_ack):
 357                   m.d.sync += self.out_z_stb.eq(0)
 358                   m.next = "get_a"
 359
 360         return m
 361
 362
 363 if __name__ == "__main__":
 364     alu = FPADD(width=32)
 365     main(alu, ports=[
 366                     alu.in_a, alu.in_a_stb, alu.in_a_ack,
 367                     alu.in_b, alu.in_b_stb, alu.in_b_ack,
 368                     alu.out_z, alu.out_z_stb, alu.out_z_ack,
 369         ])
 370
 371
 372     # works... but don't use, just do "python fname.py convert -t v"
 373     #print (verilog.convert(alu, ports=[
 374     #                alu.in_a, alu.in_a_stb, alu.in_a_ack,
 375     #                alu.in_b, alu.in_b_stb, alu.in_b_ack,
 376     #                alu.out_z, alu.out_z_stb, alu.out_z_ack,
 377     #    ]))