src/add/test_buf_pipe.py

   1 """ Unit tests for Buffered and Unbuffered pipelines
   2
   3     contains useful worked examples of how to use the Pipeline API,
   4     including:
   5
   6     * Combinatorial Stage "Chaining"
   7     * class-based data stages
   8     * nmigen module-based data stages
   9     * special nmigen module-based data stage, where the stage *is* the module
  10     * Record-based data stages
  11     * static-class data stages
  12     * multi-stage pipelines (and how to connect them)
  13     * how to *use* the pipelines (see Test5) - how to get data in and out
  14
  15 """
  16
  17 from nmigen import Module, Signal, Mux
  18 from nmigen.hdl.rec import Record
  19 from nmigen.compat.sim import run_simulation
  20 from nmigen.cli import verilog, rtlil
  21
  22 from example_buf_pipe import ExampleBufPipe, ExampleBufPipeAdd
  23 from example_buf_pipe import ExamplePipeline, UnbufferedPipeline
  24 from example_buf_pipe import ExampleStageCls
  25 from example_buf_pipe import PrevControl, NextControl, BufferedPipeline
  26 from example_buf_pipe import StageChain, ControlBase, StageCls
  27
  28 from random import randint
  29
  30
  31 def check_o_n_valid(dut, val):
  32     o_n_valid = yield dut.n.o_valid
  33     assert o_n_valid == val
  34
  35 def check_o_n_valid2(dut, val):
  36     o_n_valid = yield dut.n.o_valid
  37     assert o_n_valid == val
  38
  39
  40 def testbench(dut):
  41     #yield dut.i_p_rst.eq(1)
  42     yield dut.n.i_ready.eq(0)
  43     yield dut.p.o_ready.eq(0)
  44     yield
  45     yield
  46     #yield dut.i_p_rst.eq(0)
  47     yield dut.n.i_ready.eq(1)
  48     yield dut.p.i_data.eq(5)
  49     yield dut.p.i_valid.eq(1)
  50     yield
  51
  52     yield dut.p.i_data.eq(7)
  53     yield from check_o_n_valid(dut, 0) # effects of i_p_valid delayed
  54     yield
  55     yield from check_o_n_valid(dut, 1) # ok *now* i_p_valid effect is felt
  56
  57     yield dut.p.i_data.eq(2)
  58     yield
  59     yield dut.n.i_ready.eq(0) # begin going into "stall" (next stage says ready)
  60     yield dut.p.i_data.eq(9)
  61     yield
  62     yield dut.p.i_valid.eq(0)
  63     yield dut.p.i_data.eq(12)
  64     yield
  65     yield dut.p.i_data.eq(32)
  66     yield dut.n.i_ready.eq(1)
  67     yield
  68     yield from check_o_n_valid(dut, 1) # buffer still needs to output
  69     yield
  70     yield from check_o_n_valid(dut, 1) # buffer still needs to output
  71     yield
  72     yield from check_o_n_valid(dut, 0) # buffer outputted, *now* we're done.
  73     yield
  74
  75
  76 def testbench2(dut):
  77     #yield dut.p.i_rst.eq(1)
  78     yield dut.n.i_ready.eq(0)
  79     #yield dut.p.o_ready.eq(0)
  80     yield
  81     yield
  82     #yield dut.p.i_rst.eq(0)
  83     yield dut.n.i_ready.eq(1)
  84     yield dut.p.i_data.eq(5)
  85     yield dut.p.i_valid.eq(1)
  86     yield
  87
  88     yield dut.p.i_data.eq(7)
  89     yield from check_o_n_valid2(dut, 0) # effects of i_p_valid delayed 2 clocks
  90     yield
  91     yield from check_o_n_valid2(dut, 0) # effects of i_p_valid delayed 2 clocks
  92
  93     yield dut.p.i_data.eq(2)
  94     yield
  95     yield from check_o_n_valid2(dut, 1) # ok *now* i_p_valid effect is felt
  96     yield dut.n.i_ready.eq(0) # begin going into "stall" (next stage says ready)
  97     yield dut.p.i_data.eq(9)
  98     yield
  99     yield dut.p.i_valid.eq(0)
 100     yield dut.p.i_data.eq(12)
 101     yield
 102     yield dut.p.i_data.eq(32)
 103     yield dut.n.i_ready.eq(1)
 104     yield
 105     yield from check_o_n_valid2(dut, 1) # buffer still needs to output
 106     yield
 107     yield from check_o_n_valid2(dut, 1) # buffer still needs to output
 108     yield
 109     yield from check_o_n_valid2(dut, 1) # buffer still needs to output
 110     yield
 111     yield from check_o_n_valid2(dut, 0) # buffer outputted, *now* we're done.
 112     yield
 113     yield
 114     yield
 115
 116
 117 class Test3:
 118     def __init__(self, dut, resultfn):
 119         self.dut = dut
 120         self.resultfn = resultfn
 121         self.data = []
 122         for i in range(num_tests):
 123             #data.append(randint(0, 1<<16-1))
 124             self.data.append(i+1)
 125         self.i = 0
 126         self.o = 0
 127
 128     def send(self):
 129         while self.o != len(self.data):
 130             send_range = randint(0, 3)
 131             for j in range(randint(1,10)):
 132                 if send_range == 0:
 133                     send = True
 134                 else:
 135                     send = randint(0, send_range) != 0
 136                 o_p_ready = yield self.dut.p.o_ready
 137                 if not o_p_ready:
 138                     yield
 139                     continue
 140                 if send and self.i != len(self.data):
 141                     yield self.dut.p.i_valid.eq(1)
 142                     yield self.dut.p.i_data.eq(self.data[self.i])
 143                     self.i += 1
 144                 else:
 145                     yield self.dut.p.i_valid.eq(0)
 146                 yield
 147
 148     def rcv(self):
 149         while self.o != len(self.data):
 150             stall_range = randint(0, 3)
 151             for j in range(randint(1,10)):
 152                 stall = randint(0, stall_range) != 0
 153                 yield self.dut.n.i_ready.eq(stall)
 154                 yield
 155                 o_n_valid = yield self.dut.n.o_valid
 156                 i_n_ready = yield self.dut.n.i_ready
 157                 if not o_n_valid or not i_n_ready:
 158                     continue
 159                 o_data = yield self.dut.n.o_data
 160                 self.resultfn(o_data, self.data[self.o], self.i, self.o)
 161                 self.o += 1
 162                 if self.o == len(self.data):
 163                     break
 164
 165 def test3_resultfn(o_data, expected, i, o):
 166     assert o_data == expected + 1, \
 167                 "%d-%d data %x not match %x\n" \
 168                 % (i, o, o_data, expected)
 169
 170 def data_placeholder():
 171         data = []
 172         for i in range(num_tests):
 173             d = PlaceHolder()
 174             d.src1 = randint(0, 1<<16-1)
 175             d.src2 = randint(0, 1<<16-1)
 176             data.append(d)
 177         return data
 178
 179 def data_dict():
 180         data = []
 181         for i in range(num_tests):
 182             data.append({'src1': randint(0, 1<<16-1),
 183                          'src2': randint(0, 1<<16-1)})
 184         return data
 185
 186
 187 class Test5:
 188     def __init__(self, dut, resultfn, data=None):
 189         self.dut = dut
 190         self.resultfn = resultfn
 191         if data:
 192             self.data = data
 193         else:
 194             self.data = []
 195             for i in range(num_tests):
 196                 self.data.append((randint(0, 1<<16-1), randint(0, 1<<16-1)))
 197         self.i = 0
 198         self.o = 0
 199
 200     def send(self):
 201         while self.o != len(self.data):
 202             send_range = randint(0, 3)
 203             for j in range(randint(1,10)):
 204                 if send_range == 0:
 205                     send = True
 206                 else:
 207                     send = randint(0, send_range) != 0
 208                 o_p_ready = yield self.dut.p.o_ready
 209                 if not o_p_ready:
 210                     yield
 211                     continue
 212                 if send and self.i != len(self.data):
 213                     yield self.dut.p.i_valid.eq(1)
 214                     for v in self.dut.set_input(self.data[self.i]):
 215                         yield v
 216                     self.i += 1
 217                 else:
 218                     yield self.dut.p.i_valid.eq(0)
 219                 yield
 220
 221     def rcv(self):
 222         while self.o != len(self.data):
 223             stall_range = randint(0, 3)
 224             for j in range(randint(1,10)):
 225                 stall = randint(0, stall_range) != 0
 226                 yield self.dut.n.i_ready.eq(stall)
 227                 yield
 228                 o_n_valid = yield self.dut.n.o_valid
 229                 i_n_ready = yield self.dut.n.i_ready
 230                 if not o_n_valid or not i_n_ready:
 231                     continue
 232                 if isinstance(self.dut.n.o_data, Record):
 233                     o_data = {}
 234                     dod = self.dut.n.o_data
 235                     for k, v in dod.fields.items():
 236                         o_data[k] = yield v
 237                 else:
 238                     o_data = yield self.dut.n.o_data
 239                 self.resultfn(o_data, self.data[self.o], self.i, self.o)
 240                 self.o += 1
 241                 if self.o == len(self.data):
 242                     break
 243
 244 def test5_resultfn(o_data, expected, i, o):
 245     res = expected[0] + expected[1]
 246     assert o_data == res, \
 247                 "%d-%d data %x not match %s\n" \
 248                 % (i, o, o_data, repr(expected))
 249
 250 def testbench4(dut):
 251     data = []
 252     for i in range(num_tests):
 253         #data.append(randint(0, 1<<16-1))
 254         data.append(i+1)
 255     i = 0
 256     o = 0
 257     while True:
 258         stall = randint(0, 3) != 0
 259         send = randint(0, 5) != 0
 260         yield dut.n.i_ready.eq(stall)
 261         o_p_ready = yield dut.p.o_ready
 262         if o_p_ready:
 263             if send and i != len(data):
 264                 yield dut.p.i_valid.eq(1)
 265                 yield dut.p.i_data.eq(data[i])
 266                 i += 1
 267             else:
 268                 yield dut.p.i_valid.eq(0)
 269         yield
 270         o_n_valid = yield dut.n.o_valid
 271         i_n_ready = yield dut.n.i_ready
 272         if o_n_valid and i_n_ready:
 273             o_data = yield dut.n.o_data
 274             assert o_data == data[o] + 2, "%d-%d data %x not match %x\n" \
 275                                         % (i, o, o_data, data[o])
 276             o += 1
 277             if o == len(data):
 278                 break
 279
 280 ######################################################################
 281 # Test 2 and 4
 282 ######################################################################
 283
 284 class ExampleBufPipe2(ControlBase):
 285     """
 286         connect these:    ------|---------------|
 287                                 v               v
 288         i_p_valid >>in  pipe1 o_n_valid out>> i_p_valid >>in  pipe2
 289         o_p_ready <<out pipe1 i_n_ready <<in  o_p_ready <<out pipe2
 290         p_i_data  >>in  pipe1 p_i_data  out>> n_o_data  >>in  pipe2
 291     """
 292     def __init__(self):
 293         ControlBase.__init__(self)
 294
 295         # input / output
 296         self.p.i_data = Signal(32) # >>in - comes in from the PREVIOUS stage
 297         self.n.o_data = Signal(32) # out>> - goes out to the NEXT stage
 298
 299         self.pipe1 = ExampleBufPipe()
 300         self.pipe2 = ExampleBufPipe()
 301
 302     def elaborate(self, platform):
 303         m = Module()
 304         m.submodules.pipe1 = self.pipe1
 305         m.submodules.pipe2 = self.pipe2
 306
 307         # connect inter-pipe input/output valid/ready/data
 308         m.d.comb += self.pipe1.connect_to_next(self.pipe2)
 309
 310         # inputs/outputs to the module: pipe1 connections here (LHS)
 311         m.d.comb += self.pipe1.connect_in(self)
 312
 313         # now pipe2 connections (RHS)
 314         m.d.comb += self.pipe2.connect_out(self)
 315
 316         return m
 317
 318
 319 class ExampleBufPipeChain2(BufferedPipeline):
 320     """ connects two stages together as a *single* combinatorial stage.
 321     """
 322     def __init__(self):
 323         stage1 = ExampleStageCls()
 324         stage2 = ExampleStageCls()
 325         combined = StageChain([stage1, stage2])
 326         BufferedPipeline.__init__(self, combined)
 327
 328
 329 def data_chain2():
 330         data = []
 331         for i in range(num_tests):
 332             data.append(randint(0, 1<<16-2))
 333         return data
 334
 335
 336 def test9_resultfn(o_data, expected, i, o):
 337     res = expected + 2
 338     assert o_data == res, \
 339                 "%d-%d data %x not match %s\n" \
 340                 % (i, o, o_data, repr(expected))
 341
 342
 343 ######################################################################
 344 # Test 6 and 10
 345 ######################################################################
 346
 347 class SetLessThan:
 348     def __init__(self, width, signed):
 349         self.src1 = Signal((width, signed))
 350         self.src2 = Signal((width, signed))
 351         self.output = Signal(width)
 352
 353     def elaborate(self, platform):
 354         m = Module()
 355         m.d.comb += self.output.eq(Mux(self.src1 < self.src2, 1, 0))
 356         return m
 357
 358
 359 class LTStage(StageCls):
 360     """ module-based stage example
 361     """
 362     def __init__(self):
 363         self.slt = SetLessThan(16, True)
 364
 365     def ispec(self):
 366         return (Signal(16), Signal(16))
 367
 368     def ospec(self):
 369         return Signal(16)
 370
 371     def setup(self, m, i):
 372         self.o = Signal(16)
 373         m.submodules.slt = self.slt
 374         m.d.comb += self.slt.src1.eq(i[0])
 375         m.d.comb += self.slt.src2.eq(i[1])
 376         m.d.comb += self.o.eq(self.slt.output)
 377
 378     def process(self, i):
 379         return self.o
 380
 381
 382 class LTStageDerived(SetLessThan, StageCls):
 383     """ special version of a nmigen module where the module is also a stage
 384
 385         shows that you don't actually need to combinatorially connect
 386         to the outputs, or add the module as a submodule: just return
 387         the module output parameter(s) from the Stage.process() function
 388     """
 389
 390     def __init__(self):
 391         SetLessThan.__init__(self, 16, True)
 392
 393     def ispec(self):
 394         return (Signal(16), Signal(16))
 395
 396     def ospec(self):
 397         return Signal(16)
 398
 399     def setup(self, m, i):
 400         m.submodules.slt = self
 401         m.d.comb += self.src1.eq(i[0])
 402         m.d.comb += self.src2.eq(i[1])
 403
 404     def process(self, i):
 405         return self.output
 406
 407
 408 class ExampleLTPipeline(UnbufferedPipeline):
 409     """ an example of how to use the unbuffered pipeline.
 410     """
 411
 412     def __init__(self):
 413         stage = LTStage()
 414         UnbufferedPipeline.__init__(self, stage)
 415
 416
 417 class ExampleLTBufferedPipeDerived(BufferedPipeline):
 418     """ an example of how to use the buffered pipeline.
 419     """
 420
 421     def __init__(self):
 422         stage = LTStageDerived()
 423         BufferedPipeline.__init__(self, stage)
 424
 425
 426 def test6_resultfn(o_data, expected, i, o):
 427     res = 1 if expected[0] < expected[1] else 0
 428     assert o_data == res, \
 429                 "%d-%d data %x not match %s\n" \
 430                 % (i, o, o_data, repr(expected))
 431
 432
 433 ######################################################################
 434 # Test 7
 435 ######################################################################
 436
 437 class ExampleAddRecordStage(StageCls):
 438     """ example use of a Record
 439     """
 440
 441     record_spec = [('src1', 16), ('src2', 16)]
 442     def ispec(self):
 443         """ returns a Record using the specification
 444         """
 445         return Record(self.record_spec)
 446
 447     def ospec(self):
 448         return Record(self.record_spec)
 449
 450     def process(self, i):
 451         """ process the input data, returning a dictionary with key names
 452             that exactly match the Record's attributes.
 453         """
 454         return {'src1': i.src1 + 1,
 455                 'src2': i.src2 + 1}
 456
 457 ######################################################################
 458 # Test 11
 459 ######################################################################
 460
 461 class ExampleAddRecordPlaceHolderStage(StageCls):
 462     """ example use of a Record, with a placeholder as the processing result
 463     """
 464
 465     record_spec = [('src1', 16), ('src2', 16)]
 466     def ispec(self):
 467         """ returns a Record using the specification
 468         """
 469         return Record(self.record_spec)
 470
 471     def ospec(self):
 472         return Record(self.record_spec)
 473
 474     def process(self, i):
 475         """ process the input data, returning a PlaceHolder class instance
 476             with attributes that exactly match those of the Record.
 477         """
 478         o = PlaceHolder()
 479         o.src1 = i.src1 + 1
 480         o.src2 = i.src2 + 1
 481         return o
 482
 483
 484 class PlaceHolder: pass
 485
 486
 487 class ExampleAddRecordPipe(UnbufferedPipeline):
 488     """ an example of how to use the combinatorial pipeline.
 489     """
 490
 491     def __init__(self):
 492         stage = ExampleAddRecordStage()
 493         UnbufferedPipeline.__init__(self, stage)
 494
 495
 496 def test7_resultfn(o_data, expected, i, o):
 497     res = (expected['src1'] + 1, expected['src2'] + 1)
 498     assert o_data['src1'] == res[0] and o_data['src2'] == res[1], \
 499                 "%d-%d data %s not match %s\n" \
 500                 % (i, o, repr(o_data), repr(expected))
 501
 502
 503 class ExampleAddRecordPlaceHolderPipe(UnbufferedPipeline):
 504     """ an example of how to use the combinatorial pipeline.
 505     """
 506
 507     def __init__(self):
 508         stage = ExampleAddRecordPlaceHolderStage()
 509         UnbufferedPipeline.__init__(self, stage)
 510
 511
 512 def test11_resultfn(o_data, expected, i, o):
 513     res1 = expected.src1 + 1
 514     res2 = expected.src2 + 1
 515     assert o_data['src1'] == res1 and o_data['src2'] == res2, \
 516                 "%d-%d data %s not match %s\n" \
 517                 % (i, o, repr(o_data), repr(expected))
 518
 519
 520 ######################################################################
 521 # Test 8
 522 ######################################################################
 523
 524
 525 class Example2OpClass:
 526     """ an example of a class used to store 2 operands.
 527         requires an eq function, to conform with the pipeline stage API
 528     """
 529
 530     def __init__(self):
 531         self.op1 = Signal(16)
 532         self.op2 = Signal(16)
 533
 534     def eq(self, i):
 535         return [self.op1.eq(i.op1), self.op2.eq(i.op2)]
 536
 537
 538 class ExampleAddClassStage(StageCls):
 539     """ an example of how to use the buffered pipeline, as a class instance
 540     """
 541
 542     def ispec(self):
 543         """ returns an instance of an Example2OpClass.
 544         """
 545         return Example2OpClass()
 546
 547     def ospec(self):
 548         """ returns an output signal which will happen to contain the sum
 549             of the two inputs
 550         """
 551         return Signal(16)
 552
 553     def process(self, i):
 554         """ process the input data (sums the values in the tuple) and returns it
 555         """
 556         return i.op1 + i.op2
 557
 558
 559 class ExampleBufPipeAddClass(BufferedPipeline):
 560     """ an example of how to use the buffered pipeline, using a class instance
 561     """
 562
 563     def __init__(self):
 564         addstage = ExampleAddClassStage()
 565         BufferedPipeline.__init__(self, addstage)
 566
 567
 568 class TestInputAdd:
 569     """ the eq function, called by set_input, needs an incoming object
 570         that conforms to the Example2OpClass.eq function requirements
 571         easiest way to do that is to create a class that has the exact
 572         same member layout (self.op1, self.op2) as Example2OpClass
 573     """
 574     def __init__(self, op1, op2):
 575         self.op1 = op1
 576         self.op2 = op2
 577
 578
 579 def test8_resultfn(o_data, expected, i, o):
 580     res = expected.op1 + expected.op2 # these are a TestInputAdd instance
 581     assert o_data == res, \
 582                 "%d-%d data %x not match %s\n" \
 583                 % (i, o, o_data, repr(expected))
 584
 585 def data_2op():
 586         data = []
 587         for i in range(num_tests):
 588             data.append(TestInputAdd(randint(0, 1<<16-1), randint(0, 1<<16-1)))
 589         return data
 590
 591
 592 num_tests = 100
 593
 594 if __name__ == '__main__':
 595     print ("test 1")
 596     dut = ExampleBufPipe()
 597     run_simulation(dut, testbench(dut), vcd_name="test_bufpipe.vcd")
 598
 599     print ("test 2")
 600     dut = ExampleBufPipe2()
 601     run_simulation(dut, testbench2(dut), vcd_name="test_bufpipe2.vcd")
 602
 603     print ("test 3")
 604     dut = ExampleBufPipe()
 605     test = Test3(dut, test3_resultfn)
 606     run_simulation(dut, [test.send, test.rcv], vcd_name="test_bufpipe3.vcd")
 607
 608     print ("test 3.5")
 609     dut = ExamplePipeline()
 610     test = Test3(dut, test3_resultfn)
 611     run_simulation(dut, [test.send, test.rcv], vcd_name="test_combpipe3.vcd")
 612
 613     print ("test 4")
 614     dut = ExampleBufPipe2()
 615     run_simulation(dut, testbench4(dut), vcd_name="test_bufpipe4.vcd")
 616
 617     print ("test 5")
 618     dut = ExampleBufPipeAdd()
 619     test = Test5(dut, test5_resultfn)
 620     run_simulation(dut, [test.send, test.rcv], vcd_name="test_bufpipe5.vcd")
 621
 622     print ("test 6")
 623     dut = ExampleLTPipeline()
 624     test = Test5(dut, test6_resultfn)
 625     run_simulation(dut, [test.send, test.rcv], vcd_name="test_ltcomb6.vcd")
 626
 627     ports = [dut.p.i_valid, dut.n.i_ready,
 628              dut.n.o_valid, dut.p.o_ready] + \
 629              list(dut.p.i_data) + [dut.n.o_data]
 630     vl = rtlil.convert(dut, ports=ports)
 631     with open("test_ltcomb_pipe.il", "w") as f:
 632         f.write(vl)
 633
 634     print ("test 7")
 635     dut = ExampleAddRecordPipe()
 636     data=data_dict()
 637     test = Test5(dut, test7_resultfn, data=data)
 638     run_simulation(dut, [test.send, test.rcv], vcd_name="test_addrecord.vcd")
 639
 640     ports = [dut.p.i_valid, dut.n.i_ready,
 641              dut.n.o_valid, dut.p.o_ready,
 642              dut.p.i_data.src1, dut.p.i_data.src2,
 643              dut.n.o_data.src1, dut.n.o_data.src2]
 644     vl = rtlil.convert(dut, ports=ports)
 645     with open("test_recordcomb_pipe.il", "w") as f:
 646         f.write(vl)
 647
 648     print ("test 8")
 649     dut = ExampleBufPipeAddClass()
 650     data=data_2op()
 651     test = Test5(dut, test8_resultfn, data=data)
 652     run_simulation(dut, [test.send, test.rcv], vcd_name="test_bufpipe8.vcd")
 653
 654     print ("test 9")
 655     dut = ExampleBufPipeChain2()
 656     ports = [dut.p.i_valid, dut.n.i_ready,
 657              dut.n.o_valid, dut.p.o_ready] + \
 658              [dut.p.i_data] + [dut.n.o_data]
 659     vl = rtlil.convert(dut, ports=ports)
 660     with open("test_bufpipechain2.il", "w") as f:
 661         f.write(vl)
 662
 663     data = data_chain2()
 664     test = Test5(dut, test9_resultfn, data=data)
 665     run_simulation(dut, [test.send, test.rcv],
 666                         vcd_name="test_bufpipechain2.vcd")
 667
 668     print ("test 10")
 669     dut = ExampleLTBufferedPipeDerived()
 670     test = Test5(dut, test6_resultfn)
 671     run_simulation(dut, [test.send, test.rcv], vcd_name="test_ltbufpipe10.vcd")
 672     vl = rtlil.convert(dut, ports=ports)
 673     with open("test_ltbufpipe10.il", "w") as f:
 674         f.write(vl)
 675
 676     print ("test 11")
 677     dut = ExampleAddRecordPlaceHolderPipe()
 678     data=data_placeholder()
 679     test = Test5(dut, test11_resultfn, data=data)
 680     run_simulation(dut, [test.send, test.rcv], vcd_name="test_addrecord.vcd")
 681
 682