+ 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, 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
+
+ i_data -> process() -> result --> o.data
+ | ^
+ | |
+ +-> r_data -+
+ """
+ self.stage = stage
+
+ # set up input and output IO ACK (prev/next ready/valid)
+ self.i = IOAckIn()
+ self.o = IOAckOut()
+
+ # set up the input and output data
+ self.i.data = stage.ispec() # input type
+ self.r_data = stage.ospec() # all these are output type
+ self.result = stage.ospec()
+ self.o.data = stage.ospec()
+
+ def connect_next(self, nxt):
+ """ helper function to connect to the next stage data/valid/ready.
+ data/valid is passed *TO* nxt, and ready comes *IN* from nxt.
+ """
+ return [nxt.i.p_valid.eq(self.o.n_valid),
+ self.i.n_ready.eq(nxt.o.p_ready),
+ eq(nxt.i.data, self.o.data),
+ ]
+
+ def connect_in(self, prev):
+ """ helper function to connect stage to an input source. do not
+ use to connect stage-to-stage!
+ """
+ return [self.i.p_valid.eq(prev.i.p_valid),
+ prev.o.p_ready.eq(self.o.p_ready),
+ eq(self.i.data, prev.i.data),
+ ]
+
+ def connect_out(self, nxt):
+ """ helper function to connect stage to an output source. do not
+ use to connect stage-to-stage!
+ """
+ return [nxt.o.n_valid.eq(self.o.n_valid),
+ self.i.n_ready.eq(nxt.i.n_ready),
+ eq(nxt.o.data, self.o.data),
+ ]
+
+ def set_input(self, i):
+ """ helper function to set the input data
+ """
+ return eq(self.i.data, i)
+
+ 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 update_output(self):
+ """ copies the (combinatorial) result into the output
+ """
+ return eq(self.o.data, self.result)
+
+ def flush_buffer(self):
+ """ copies the *intermediate* register r_data into the output
+ """
+ return eq(self.o.data, self.r_data)
+
+ def ports(self):
+ return [self.i.data, self.o.data]