+""" Unit tests for Buffered and Unbuffered pipelines
+
+ contains useful worked examples of how to use the Pipeline API,
+ including:
+
+ * Combinatorial Stage "Chaining"
+ * class-based data stages
+ * nmigen module-based data stages
+ * special nmigen module-based data stage, where the stage *is* the module
+ * Record-based data stages
+ * static-class data stages
+ * multi-stage pipelines (and how to connect them)
+ * how to *use* the pipelines (see Test5) - how to get data in and out
+
+"""
+
from nmigen import Module, Signal, Mux
from nmigen.hdl.rec import Record
from nmigen.compat.sim import run_simulation
from nmigen.cli import verilog, rtlil
from example_buf_pipe import ExampleBufPipe, ExampleBufPipeAdd
-from example_buf_pipe import ExampleCombPipe, CombPipe, ExampleStageCls
+from example_buf_pipe import ExamplePipeline, UnbufferedPipeline
+from example_buf_pipe import ExampleStageCls
from example_buf_pipe import PrevControl, NextControl, BufferedPipeline
-from example_buf_pipe import StageChain
+from example_buf_pipe import StageChain, ControlBase, StageCls
from random import randint
o_n_valid = yield dut.n.o_valid
assert o_n_valid == val
+def check_o_n_valid2(dut, val):
+ o_n_valid = yield dut.n.o_valid
+ assert o_n_valid == val
+
def testbench(dut):
#yield dut.i_p_rst.eq(1)
yield
yield dut.p.i_data.eq(7)
- yield from check_o_n_valid(dut, 0) # effects of i_p_valid delayed 2 clocks
+ yield from check_o_n_valid2(dut, 0) # effects of i_p_valid delayed 2 clocks
yield
- yield from check_o_n_valid(dut, 0) # effects of i_p_valid delayed 2 clocks
+ yield from check_o_n_valid2(dut, 0) # effects of i_p_valid delayed 2 clocks
yield dut.p.i_data.eq(2)
yield
- yield from check_o_n_valid(dut, 1) # ok *now* i_p_valid effect is felt
+ yield from check_o_n_valid2(dut, 1) # ok *now* i_p_valid effect is felt
yield dut.n.i_ready.eq(0) # begin going into "stall" (next stage says ready)
yield dut.p.i_data.eq(9)
yield
yield dut.p.i_data.eq(32)
yield dut.n.i_ready.eq(1)
yield
- yield from check_o_n_valid(dut, 1) # buffer still needs to output
+ yield from check_o_n_valid2(dut, 1) # buffer still needs to output
yield
- yield from check_o_n_valid(dut, 1) # buffer still needs to output
+ yield from check_o_n_valid2(dut, 1) # buffer still needs to output
yield
- yield from check_o_n_valid(dut, 1) # buffer still needs to output
+ yield from check_o_n_valid2(dut, 1) # buffer still needs to output
yield
- yield from check_o_n_valid(dut, 0) # buffer outputted, *now* we're done.
+ yield from check_o_n_valid2(dut, 0) # buffer outputted, *now* we're done.
yield
yield
yield
"%d-%d data %x not match %x\n" \
% (i, o, o_data, expected)
+def data_placeholder():
+ data = []
+ for i in range(num_tests):
+ d = PlaceHolder()
+ d.src1 = randint(0, 1<<16-1)
+ d.src2 = randint(0, 1<<16-1)
+ data.append(d)
+ return data
+
def data_dict():
data = []
for i in range(num_tests):
if o == len(data):
break
+######################################################################
+# Test 2 and 4
+######################################################################
-class ExampleBufPipe2:
- """
- connect these: ------|---------------|
- v v
- i_p_valid >>in pipe1 o_n_valid out>> i_p_valid >>in pipe2
- o_p_ready <<out pipe1 i_n_ready <<in o_p_ready <<out pipe2
- p_i_data >>in pipe1 p_i_data out>> n_o_data >>in pipe2
+class ExampleBufPipe2(ControlBase):
+ """ Example of how to do chained pipeline stages.
"""
- def __init__(self):
- self.pipe1 = ExampleBufPipe()
- self.pipe2 = ExampleBufPipe()
-
- # input
- self.p = PrevControl()
- self.p.i_data = Signal(32) # >>in - comes in from the PREVIOUS stage
-
- # output
- self.n = NextControl()
- self.n.o_data = Signal(32) # out>> - goes out to the NEXT stage
def elaborate(self, platform):
m = Module()
- m.submodules.pipe1 = self.pipe1
- m.submodules.pipe2 = self.pipe2
- # connect inter-pipe input/output valid/ready/data
- m.d.comb += self.pipe1.connect_to_next(self.pipe2)
+ pipe1 = ExampleBufPipe()
+ pipe2 = ExampleBufPipe()
- # inputs/outputs to the module: pipe1 connections here (LHS)
- m.d.comb += self.pipe1.connect_in(self)
+ m.submodules.pipe1 = pipe1
+ m.submodules.pipe2 = pipe2
- # now pipe2 connections (RHS)
- m.d.comb += self.pipe2.connect_out(self)
+ m.d.comb += self.connect([pipe1, pipe2])
return m
+######################################################################
+# Test 9
+######################################################################
+
class ExampleBufPipeChain2(BufferedPipeline):
""" connects two stages together as a *single* combinatorial stage.
"""
% (i, o, o_data, repr(expected))
+######################################################################
+# Test 6 and 10
+######################################################################
+
class SetLessThan:
def __init__(self, width, signed):
self.src1 = Signal((width, signed))
return m
-class LTStage:
+class LTStage(StageCls):
+ """ module-based stage example
+ """
def __init__(self):
self.slt = SetLessThan(16, True)
return self.o
-class LTStageDerived(SetLessThan):
+class LTStageDerived(SetLessThan, StageCls):
+ """ special version of a nmigen module where the module is also a stage
+
+ shows that you don't actually need to combinatorially connect
+ to the outputs, or add the module as a submodule: just return
+ the module output parameter(s) from the Stage.process() function
+ """
def __init__(self):
SetLessThan.__init__(self, 16, True)
return Signal(16)
def setup(self, m, i):
- self.o = Signal(16)
m.submodules.slt = self
m.d.comb += self.src1.eq(i[0])
m.d.comb += self.src2.eq(i[1])
- m.d.comb += self.o.eq(self.output)
def process(self, i):
- return self.o
+ return self.output
-class ExampleLTCombPipe(CombPipe):
- """ an example of how to use the combinatorial pipeline.
+class ExampleLTPipeline(UnbufferedPipeline):
+ """ an example of how to use the unbuffered pipeline.
"""
def __init__(self):
stage = LTStage()
- CombPipe.__init__(self, stage)
+ UnbufferedPipeline.__init__(self, stage)
-class ExampleLTBufferedPipeDerived(CombPipe):
- """ an example of how to use the combinatorial pipeline.
+class ExampleLTBufferedPipeDerived(BufferedPipeline):
+ """ an example of how to use the buffered pipeline.
"""
def __init__(self):
stage = LTStageDerived()
- CombPipe.__init__(self, stage)
+ BufferedPipeline.__init__(self, stage)
def test6_resultfn(o_data, expected, i, o):
% (i, o, o_data, repr(expected))
-class ExampleAddRecordStage:
+######################################################################
+# Test 7
+######################################################################
+
+class ExampleAddRecordStage(StageCls):
""" example use of a Record
"""
record_spec = [('src1', 16), ('src2', 16)]
def ispec(self):
- """ returns a tuple of input signals which will be the incoming data
+ """ returns a Record using the specification
"""
return Record(self.record_spec)
return Record(self.record_spec)
def process(self, i):
- """ process the input data (sums the values in the tuple) and returns it
+ """ process the input data, returning a dictionary with key names
+ that exactly match the Record's attributes.
"""
return {'src1': i.src1 + 1,
'src2': i.src2 + 1}
+######################################################################
+# Test 11
+######################################################################
+
+class ExampleAddRecordPlaceHolderStage(StageCls):
+ """ example use of a Record, with a placeholder as the processing result
+ """
-class ExampleAddRecordPipe(CombPipe):
+ record_spec = [('src1', 16), ('src2', 16)]
+ def ispec(self):
+ """ returns a Record using the specification
+ """
+ return Record(self.record_spec)
+
+ def ospec(self):
+ return Record(self.record_spec)
+
+ def process(self, i):
+ """ process the input data, returning a PlaceHolder class instance
+ with attributes that exactly match those of the Record.
+ """
+ o = PlaceHolder()
+ o.src1 = i.src1 + 1
+ o.src2 = i.src2 + 1
+ return o
+
+
+class PlaceHolder: pass
+
+
+class ExampleAddRecordPipe(UnbufferedPipeline):
""" an example of how to use the combinatorial pipeline.
"""
def __init__(self):
stage = ExampleAddRecordStage()
- CombPipe.__init__(self, stage)
+ UnbufferedPipeline.__init__(self, stage)
def test7_resultfn(o_data, expected, i, o):
% (i, o, repr(o_data), repr(expected))
+class ExampleAddRecordPlaceHolderPipe(UnbufferedPipeline):
+ """ an example of how to use the combinatorial pipeline.
+ """
+
+ def __init__(self):
+ stage = ExampleAddRecordPlaceHolderStage()
+ UnbufferedPipeline.__init__(self, stage)
+
+
+def test11_resultfn(o_data, expected, i, o):
+ res1 = expected.src1 + 1
+ res2 = expected.src2 + 1
+ assert o_data['src1'] == res1 and o_data['src2'] == res2, \
+ "%d-%d data %s not match %s\n" \
+ % (i, o, repr(o_data), repr(expected))
+
+
+######################################################################
+# Test 8
+######################################################################
+
+
class Example2OpClass:
""" an example of a class used to store 2 operands.
requires an eq function, to conform with the pipeline stage API
return [self.op1.eq(i.op1), self.op2.eq(i.op2)]
-class ExampleAddClassStage:
+class ExampleAddClassStage(StageCls):
""" an example of how to use the buffered pipeline, as a class instance
"""
print ("test 2")
dut = ExampleBufPipe2()
run_simulation(dut, testbench2(dut), vcd_name="test_bufpipe2.vcd")
+ ports = [dut.p.i_valid, dut.n.i_ready,
+ dut.n.o_valid, dut.p.o_ready] + \
+ [dut.p.i_data] + [dut.n.o_data]
+ vl = rtlil.convert(dut, ports=ports)
+ with open("test_bufpipe2.il", "w") as f:
+ f.write(vl)
+
print ("test 3")
dut = ExampleBufPipe()
run_simulation(dut, [test.send, test.rcv], vcd_name="test_bufpipe3.vcd")
print ("test 3.5")
- dut = ExampleCombPipe()
+ dut = ExamplePipeline()
test = Test3(dut, test3_resultfn)
run_simulation(dut, [test.send, test.rcv], vcd_name="test_combpipe3.vcd")
run_simulation(dut, [test.send, test.rcv], vcd_name="test_bufpipe5.vcd")
print ("test 6")
- dut = ExampleLTCombPipe()
+ dut = ExampleLTPipeline()
test = Test5(dut, test6_resultfn)
run_simulation(dut, [test.send, test.rcv], vcd_name="test_ltcomb6.vcd")
with open("test_ltbufpipe10.il", "w") as f:
f.write(vl)
+ print ("test 11")
+ dut = ExampleAddRecordPlaceHolderPipe()
+ data=data_placeholder()
+ test = Test5(dut, test11_resultfn, data=data)
+ run_simulation(dut, [test.send, test.rcv], vcd_name="test_addrecord.vcd")
+
projects / ieee754fpu.git / blobdiff