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