X-Git-Url: https://git.libre-soc.org/?a=blobdiff_plain;f=src%2Fadd%2Fexample_buf_pipe.py;h=8b9c74f78f8abc4ef1be278e374eb6e024cfa55f;hb=25357c032b55274ce620a331ecc1dc0874f5fdac;hp=337ce50e9c39921421d625fee9f2361c1b2fae85;hpb=14559d0d0edaee06af261a04ed0a33a5bd1e0479;p=ieee754fpu.git diff --git a/src/add/example_buf_pipe.py b/src/add/example_buf_pipe.py index 337ce50e..8b9c74f7 100644 --- a/src/add/example_buf_pipe.py +++ b/src/add/example_buf_pipe.py @@ -12,12 +12,12 @@ where data will flow on *every* clock when the conditions are right. input acceptance conditions are when: - * incoming previous-stage strobe (i_p_stb) is HIGH - * outgoing previous-stage busy (o_p_busy) is LOW + * incoming previous-stage strobe (p.i_valid) is HIGH + * outgoing previous-stage ready (p.o_ready) is LOW output transmission conditions are when: - * outgoing next-stage strobe (o_n_stb) is HIGH - * outgoing next-stage busy (i_n_busy) is LOW + * outgoing next-stage strobe (n.o_valid) is HIGH + * outgoing next-stage ready (n.i_ready) is LOW the tricky bit is when the input has valid data and the output is not ready to accept it. if it wasn't for the clock synchronisation, it @@ -25,124 +25,370 @@ not ready". unfortunately, it's not possible to "change the past": the previous stage *has no choice* but to pass on its data. - therefore, the incoming data *must* be accepted - and stored. + therefore, the incoming data *must* be accepted - and stored: that + is the responsibility / contract that this stage *must* accept. on the same clock, it's possible to tell the input that it must not send any more data. this is the "stall" condition. we now effectively have *two* possible pieces of data to "choose" from: the buffered data, and the incoming data. the decision as to which to process and output is based on whether we are in "stall" or not. - i.e. when the next stage is no longer busy, the output comes from + i.e. when the next stage is no longer ready, the output comes from the buffer if a stall had previously occurred, otherwise it comes direct from processing the input. + this allows us to respect a synchronous "travelling STB" with what + dan calls a "buffered handshake". + it's quite a complex state machine! """ from nmigen import Signal, Cat, Const, Mux, Module -from nmigen.compat.sim import run_simulation from nmigen.cli import verilog, rtlil +from collections.abc import Sequence + + +class PrevControl: + """ contains signals that come *from* the previous stage (both in and out) + * i_valid: input from previous stage indicating incoming data is valid + * o_ready: output to next stage indicating readiness to accept data + * i_data : an input - added by the user of this class + """ + + def __init__(self): + self.i_valid = Signal(name="p_i_valid") # >>in + self.o_ready = Signal(name="p_o_ready") # <> + self.i_ready = Signal(name="n_i_ready") # <>in stage o_n_stb out>> stage+1 - stage-1 o_p_busy <>in stage o_data out>> stage+1 +class BufferedPipeline: + """ buffered pipeline stage. data and strobe signals travel in sync. + if ever the input is ready and the output is not, processed data + is stored in a temporary register. + + stage-1 p.i_valid >>in stage n.o_valid out>> stage+1 + stage-1 p.o_ready <>in stage n.o_data out>> stage+1 | | - +-------> process + process --->----^ | | - +-- r_data ---+ + +-- r_data ->-+ + + input data p.i_data is read (only), is processed and goes into an + intermediate result store [process()]. this is updated combinatorially. + + in a non-stall condition, the intermediate result will go into the + output (update_output). however if ever there is a stall, it goes + into r_data instead [update_buffer()]. + + when the non-stall condition is released, r_data is the first + to be transferred to the output [flush_buffer()], and the stall + condition cleared. + + on the next cycle (as long as stall is not raised again) the + input may begin to be processed and transferred directly to output. """ - def __init__(self): - # input - #self.i_p_rst = Signal() # >>in - comes in from PREVIOUS stage - self.i_p_stb = Signal() # >>in - comes in from PREVIOUS stage - self.i_n_busy = Signal() # in<< - comes in from the NEXT stage - self.i_data = Signal(32) # >>in - comes in from the PREVIOUS stage - #self.i_rst = Signal() + def __init__(self, stage): + """ pass in a "stage" which may be either a static class or a class + instance, which has three functions: + * ispec: returns input signals according to the input specification + * ispec: returns output signals to the output specification + * process: takes an input instance and returns processed data + + p.i_data -> process() -> result --> n.o_data + | ^ + | | + +-> r_data -+ + """ + self.stage = stage + + # set up input and output IO ACK (prev/next ready/valid) + self.p = PrevControl() + self.n = NextControl() + + # set up the input and output data + self.p.i_data = stage.ispec() # input type + self.r_data = stage.ospec() # all these are output type + self.result = stage.ospec() + self.n.o_data = stage.ospec() + + def connect_to_next(self, nxt): + """ helper function to connect to the next stage data/valid/ready. + """ + return self.n.connect_to_next(nxt.p) + + def connect_in(self, prev): + """ helper function to connect stage to an input source. do not + use to connect stage-to-stage! + """ + return self.p.connect_in(prev.p) + + def connect_out(self, nxt): + """ helper function to connect stage to an output source. do not + use to connect stage-to-stage! + """ + return self.n.connect_out(nxt.n) - # buffered - self.r_data = Signal(32) + def set_input(self, i): + """ helper function to set the input data + """ + return eq(self.p.i_data, i) - # output - self.o_n_stb = Signal() # out>> - goes out to the NEXT stage - self.o_p_busy = Signal() # <> - goes out to the NEXT stage + def update_buffer(self): + """ copies the result into the intermediate register r_data, + which will need to be outputted on a subsequent cycle + prior to allowing "normal" operation. + """ + return eq(self.r_data, self.result) - def pre_process(self, d_in): - return d_in | 0xf0000 + def update_output(self): + """ copies the (combinatorial) result into the output + """ + return eq(self.n.o_data, self.result) - def process(self, d_in): - return d_in + 1 + def flush_buffer(self): + """ copies the *intermediate* register r_data into the output + """ + return eq(self.n.o_data, self.r_data) + + def ports(self): + return [self.p.i_data, self.n.o_data] def elaborate(self, platform): m = Module() + if hasattr(self.stage, "setup"): + self.stage.setup(m, self.p.i_data) # establish some combinatorial temporaries - o_p_busyn = Signal(reset_less=True) - o_n_stbn = Signal(reset_less=True) - i_n_busyn = Signal(reset_less=True) - i_p_stb_o_p_busyn = Signal(reset_less=True) - m.d.comb += [i_n_busyn.eq(~self.i_n_busy), - o_n_stbn.eq(~self.o_n_stb), - o_p_busyn.eq(~self.o_p_busy), - i_p_stb_o_p_busyn.eq(self.i_p_stb & o_p_busyn), + o_n_validn = Signal(reset_less=True) + i_p_valid_o_p_ready = Signal(reset_less=True) + m.d.comb += [o_n_validn.eq(~self.n.o_valid), + i_p_valid_o_p_ready.eq(self.p.i_valid & self.p.o_ready), ] # store result of processing in combinatorial temporary - result = Signal(32) - m.d.comb += result.eq(self.process(self.i_data)) - with m.If(o_p_busyn): # not stalled - m.d.sync += self.r_data.eq(result) - - #with m.If(self.i_p_rst): # reset - # m.d.sync += self.o_n_stb.eq(0) - # m.d.sync += self.o_p_busy.eq(0) - with m.If(i_n_busyn): # next stage is not busy - with m.If(o_p_busyn): # not stalled - # nothing in buffer: send input direct to output - m.d.sync += [self.o_n_stb.eq(self.i_p_stb), - self.o_data.eq(result), + with m.If(self.p.i_valid): # input is valid: process it + m.d.comb += eq(self.result, self.stage.process(self.p.i_data)) + # if not in stall condition, update the temporary register + with m.If(self.p.o_ready): # not stalled + m.d.sync += self.update_buffer() + + #with m.If(self.p.i_rst): # reset + # m.d.sync += self.n.o_valid.eq(0) + # m.d.sync += self.p.o_ready.eq(0) + with m.If(self.n.i_ready): # next stage is ready + with m.If(self.p.o_ready): # not stalled + # nothing in buffer: send (processed) input direct to output + m.d.sync += [self.n.o_valid.eq(self.p.i_valid), + self.update_output(), ] - with m.Else(): # o_p_busy is true, and something is in our buffer. + with m.Else(): # p.o_ready is false, and something is in buffer. # Flush the [already processed] buffer to the output port. - m.d.sync += [self.o_n_stb.eq(1), - self.o_data.eq(self.r_data), + m.d.sync += [self.n.o_valid.eq(1), + self.flush_buffer(), # clear stall condition, declare register empty. - self.o_p_busy.eq(0), + self.p.o_ready.eq(1), ] - # ignore input, since o_p_busy is also true. + # ignore input, since p.o_ready is also false. - # (i_n_busy) is true here: next stage is busy - with m.Elif(o_n_stbn): # next stage being told "not busy" - m.d.sync += [self.o_n_stb.eq(self.i_p_stb), - self.o_p_busy.eq(0), # Keep the buffer empty + # (n.i_ready) is false here: next stage is ready + with m.Elif(o_n_validn): # next stage being told "ready" + m.d.sync += [self.n.o_valid.eq(self.p.i_valid), + self.p.o_ready.eq(1), # Keep the buffer empty # set the output data (from comb result) - self.o_data.eq(result), + self.update_output(), ] - # (i_n_busy) and (o_n_stb) both true: - with m.Elif(i_p_stb_o_p_busyn): - # If next stage *is* busy, and not stalled yet, accept input - m.d.sync += self.o_p_busy.eq(self.i_p_stb & self.o_n_stb) - - with m.If(o_p_busyn): # not stalled - # turns out that from all of the above conditions, just - # always put result into buffer if not busy - m.d.sync += self.r_data.eq(result) + # (n.i_ready) false and (n.o_valid) true: + with m.Elif(i_p_valid_o_p_ready): + # If next stage *is* ready, and not stalled yet, accept input + m.d.sync += self.p.o_ready.eq(~(self.p.i_valid & self.n.o_valid)) return m def ports(self): - return [self.i_p_stb, self.i_n_busy, self.i_data, - self.r_data, - self.o_n_stb, self.o_p_busy, self.o_data + return [self.p.i_valid, self.n.i_ready, + self.n.o_valid, self.p.o_ready, ] +class ExampleAddStage: + """ an example of how to use the buffered pipeline, as a class instance + """ + + def ispec(self): + """ returns a tuple of input signals which will be the incoming data + """ + return (Signal(16), Signal(16)) + + def ospec(self): + """ returns an output signal which will happen to contain the sum + of the two inputs + """ + return Signal(16) + + def process(self, i): + """ process the input data (sums the values in the tuple) and returns it + """ + return i[0] + i[1] + + +class ExampleBufPipeAdd(BufferedPipeline): + """ an example of how to use the buffered pipeline, using a class instance + """ + + def __init__(self): + addstage = ExampleAddStage() + BufferedPipeline.__init__(self, addstage) + + +class ExampleStage: + """ an example of how to use the buffered pipeline, in a static class + fashion + """ + + def ispec(): + return Signal(16) + + def ospec(): + return Signal(16) + + def process(i): + """ process the input data and returns it (adds 1) + """ + return i + 1 + + +class ExampleBufPipe(BufferedPipeline): + """ an example of how to use the buffered pipeline. + """ + + def __init__(self): + BufferedPipeline.__init__(self, ExampleStage) + + +class CombPipe: + """A simple pipeline stage containing combinational logic that can execute + completely in one clock cycle. + + Parameters: + ----------- + input_shape : int or tuple or None + the shape of ``input.data`` and ``comb_input`` + output_shape : int or tuple or None + the shape of ``output.data`` and ``comb_output`` + name : str + the name + + Attributes: + ----------- + input : StageInput + The pipeline input + output : StageOutput + The pipeline output + comb_input : Signal, input_shape + The input to the combinatorial logic + comb_output: Signal, output_shape + The output of the combinatorial logic + """ + + def __init__(self, stage): + self.stage = stage + self._data_valid = Signal() + # set up input and output IO ACK (prev/next ready/valid) + self.p = PrevControl() + self.n = NextControl() + + # set up the input and output data + self.p.i_data = stage.ispec() # input type + self.r_data = stage.ispec() # input type + self.result = stage.ospec() # output data + self.n.o_data = stage.ospec() # output type + self.n.o_data.name = "outdata" + + def set_input(self, i): + """ helper function to set the input data + """ + return eq(self.p.i_data, i) + + def elaborate(self, platform): + m = Module() + if hasattr(self.stage, "setup"): + self.stage.setup(m, self.r_data) + m.d.comb += eq(self.result, self.stage.process(self.r_data)) + m.d.comb += self.n.o_valid.eq(self._data_valid) + m.d.comb += self.p.o_ready.eq(~self._data_valid | self.n.i_ready) + m.d.sync += self._data_valid.eq(self.p.i_valid | \ + (~self.n.i_ready & self._data_valid)) + with m.If(self.p.i_valid & self.p.o_ready): + m.d.sync += eq(self.r_data, self.p.i_data) + m.d.comb += eq(self.n.o_data, self.result) + return m + + def ports(self): + return [self.p.i_data, self.n.o_data] + + +class ExampleCombPipe(CombPipe): + """ an example of how to use the combinatorial pipeline. + """ + + def __init__(self): + CombPipe.__init__(self, ExampleStage) + + if __name__ == '__main__': - dut = BufPipe() + dut = ExampleBufPipe() vl = rtlil.convert(dut, ports=dut.ports()) with open("test_bufpipe.il", "w") as f: f.write(vl) + dut = ExampleCombPipe() + vl = rtlil.convert(dut, ports=dut.ports()) + with open("test_combpipe.il", "w") as f: + f.write(vl)