eb90315c7fcc70518839ed95403ad2a1831bec91
3 Associated development bugs:
4 * http://bugs.libre-riscv.org/show_bug.cgi?id=64
5 * http://bugs.libre-riscv.org/show_bug.cgi?id=57
10 stage requires compliance with a strict API that may be
11 implemented in several means, including as a static class.
13 Stages do not HOLD data, and they definitely do not contain
14 signalling (ready/valid). They do however specify the FORMAT
15 of the incoming and outgoing data, and they provide a means to
16 PROCESS that data (from incoming format to outgoing format).
18 Stage Blocks really must be combinatorial blocks. It would be ok
19 to have input come in from sync'd sources (clock-driven) however by
20 doing so they would no longer be deterministic, and chaining such
21 blocks with such side-effects together could result in unexpected,
22 unpredictable, unreproduceable behaviour.
23 So generally to be avoided, then unless you know what you are doing.
25 the methods of a stage instance must be as follows:
27 * ispec() - Input data format specification. Takes a bit of explaining.
28 The requirements are: something that eventually derives from
29 nmigen Value must be returned *OR* an iterator or iterable
30 or sequence (list, tuple etc.) or generator must *yield*
31 thing(s) that (eventually) derive from the nmigen Value class.
33 Complex to state, very simple in practice:
34 see test_buf_pipe.py for over 25 worked examples.
36 * ospec() - Output data format specification.
37 format requirements identical to ispec.
39 * process(m, i) - Optional function for processing ispec-formatted data.
40 returns a combinatorial block of a result that
41 may be assigned to the output, by way of the "nmoperator.eq"
42 function. Note that what is returned here can be
43 extremely flexible. Even a dictionary can be returned
44 as long as it has fields that match precisely with the
45 Record into which its values is intended to be assigned.
46 Again: see example unit tests for details.
48 * setup(m, i) - Optional function for setting up submodules.
49 may be used for more complex stages, to link
50 the input (i) to submodules. must take responsibility
51 for adding those submodules to the module (m).
52 the submodules must be combinatorial blocks and
53 must have their inputs and output linked combinatorially.
55 Both StageCls (for use with non-static classes) and Stage (for use
56 by static classes) are abstract classes from which, for convenience
57 and as a courtesy to other developers, anything conforming to the
58 Stage API may *choose* to derive. See Liskov Substitution Principle:
59 https://en.wikipedia.org/wiki/Liskov_substitution_principle
64 A useful combinatorial wrapper around stages that chains them together
65 and then presents a Stage-API-conformant interface. By presenting
66 the same API as the stages it wraps, it can clearly be used recursively.
71 A convenience wrapper around a Stage-API-compliant "thing" which
72 complies with the Stage API and provides mandatory versions of
73 all the optional bits.
76 from abc
import ABCMeta
, abstractmethod
82 def _spec(fn
, name
=None):
85 varnames
= dict(inspect
.getmembers(fn
.__code
__))['co_varnames']
86 if 'name' in varnames
:
91 class StageCls(metaclass
=ABCMeta
):
92 """ Class-based "Stage" API. requires instantiation (after derivation)
94 see "Stage API" above.. Note: python does *not* require derivation
95 from this class. All that is required is that the pipelines *have*
96 the functions listed in this class. Derivation from this class
97 is therefore merely a "courtesy" to maintainers.
100 def ispec(self
): pass # REQUIRED
102 def ospec(self
): pass # REQUIRED
104 #def setup(self, m, i): pass # OPTIONAL
106 #def process(self, i): pass # OPTIONAL
109 class Stage(metaclass
=ABCMeta
):
110 """ Static "Stage" API. does not require instantiation (after derivation)
112 see "Stage API" above. Note: python does *not* require derivation
113 from this class. All that is required is that the pipelines *have*
114 the functions listed in this class. Derivation from this class
115 is therefore merely a "courtesy" to maintainers.
127 #def setup(m, i): pass
131 #def process(i): pass
134 class StageHelper(Stage
):
135 """ a convenience wrapper around something that is Stage-API-compliant.
136 (that "something" may be a static class, for example).
138 StageHelper happens to also be compliant with the Stage API,
139 it differs from the stage that it wraps in that all the "optional"
140 functions are provided (hence the designation "convenience wrapper")
142 def __init__(self
, stage
):
146 if stage
is not None:
147 self
.set_specs(self
, self
)
149 def ospec(self
, name
):
150 assert self
._ospecfn
is not None
151 return _spec(self
._ospecfn
, name
)
153 def ispec(self
, name
):
154 assert self
._ispecfn
is not None
155 return _spec(self
._ispecfn
, name
)
157 def set_specs(self
, p
, n
):
158 """ sets up the ispecfn and ospecfn for getting input and output data
160 if hasattr(p
, "stage"):
162 if hasattr(n
, "stage"):
164 self
._ispecfn
= p
.ispec
165 self
._ospecfn
= n
.ospec
167 def new_specs(self
, name
):
168 """ allocates new ispec and ospec pair
170 return self
.ispec("%s_i" % name
), self
.ospec("%s_o" % name
)
172 def process(self
, i
):
173 if self
.stage
and hasattr(self
.stage
, "process"):
174 return self
.stage
.process(i
)
177 def setup(self
, m
, i
):
178 if self
.stage
is not None and hasattr(self
.stage
, "setup"):
179 self
.stage
.setup(m
, i
)
181 def _postprocess(self
, i
): # XXX DISABLED
182 return i
# RETURNS INPUT
183 if hasattr(self
.stage
, "postprocess"):
184 return self
.stage
.postprocess(i
)
188 class StageChain(StageHelper
):
189 """ pass in a list of stages, and they will automatically be
190 chained together via their input and output specs into a
191 combinatorial chain, to create one giant combinatorial block.
193 the end result basically conforms to the exact same Stage API.
195 * input to this class will be the input of the first stage
196 * output of first stage goes into input of second
197 * output of second goes into input into third
199 * the output of this class will be the output of the last stage
201 NOTE: whilst this is very similar to ControlBase.connect(), it is
202 *really* important to appreciate that StageChain is pure
203 combinatorial and bypasses (does not involve, at all, ready/valid
204 signalling of any kind).
206 ControlBase.connect on the other hand respects, connects, and uses
207 ready/valid signalling.
211 * :chain: a chain of combinatorial blocks conforming to the Stage API
212 NOTE: StageChain.ispec and ospect have to have something
213 to return (beginning and end specs of the chain),
214 therefore the chain argument must be non-zero length
216 * :specallocate: if set, new input and output data will be allocated
217 and connected (eq'd) to each chained Stage.
218 in some cases if this is not done, the nmigen warning
219 "driving from two sources, module is being flattened"
222 NOTE: do NOT use StageChain with combinatorial blocks that have
223 side-effects (state-based / clock-based input) or conditional
224 (inter-chain) dependencies, unless you really know what you are doing.
226 def __init__(self
, chain
, specallocate
=False):
227 assert len(chain
) > 0, "stage chain must be non-zero length"
229 StageHelper
.__init
__(self
, None)
230 self
.setup
= self
._sa
_setup
if specallocate
else self
._na
_setup
231 self
.set_specs(self
.chain
[0], self
.chain
[-1])
233 def _sa_setup(self
, m
, i
):
234 for (idx
, c
) in enumerate(self
.chain
):
235 if hasattr(c
, "setup"):
236 c
.setup(m
, i
) # stage may have some module stuff
237 ofn
= self
.chain
[idx
].ospec
# last assignment survives
238 o
= _spec(ofn
, 'chainin%d' % idx
)
239 m
.d
.comb
+= nmoperator
.eq(o
, c
.process(i
)) # process input into "o"
240 if idx
== len(self
.chain
)-1:
242 ifn
= self
.chain
[idx
+1].ispec
# new input on next loop
243 i
= _spec(ifn
, 'chainin%d' % (idx
+1))
244 m
.d
.comb
+= nmoperator
.eq(i
, o
) # assign to next input
246 return self
.o
# last loop is the output
248 def _na_setup(self
, m
, i
):
249 for (idx
, c
) in enumerate(self
.chain
):
250 if hasattr(c
, "setup"):
251 c
.setup(m
, i
) # stage may have some module stuff
252 i
= o
= c
.process(i
) # store input into "o"
254 return self
.o
# last loop is the output
256 def process(self
, i
):
257 return self
.o
# conform to Stage API: return last-loop output