e819fefca4167cccc7ce9dc5ba937b90e047331b
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 StageChain(StageCls
):
135 """ pass in a list of stages, and they will automatically be
136 chained together via their input and output specs into a
137 combinatorial chain, to create one giant combinatorial block.
139 the end result basically conforms to the exact same Stage API.
141 * input to this class will be the input of the first stage
142 * output of first stage goes into input of second
143 * output of second goes into input into third
145 * the output of this class will be the output of the last stage
147 NOTE: whilst this is very similar to ControlBase.connect(), it is
148 *really* important to appreciate that StageChain is pure
149 combinatorial and bypasses (does not involve, at all, ready/valid
150 signalling of any kind).
152 ControlBase.connect on the other hand respects, connects, and uses
153 ready/valid signalling.
157 * :chain: a chain of combinatorial blocks conforming to the Stage API
158 NOTE: StageChain.ispec and ospect have to have something
159 to return (beginning and end specs of the chain),
160 therefore the chain argument must be non-zero length
162 * :specallocate: if set, new input and output data will be allocated
163 and connected (eq'd) to each chained Stage.
164 in some cases if this is not done, the nmigen warning
165 "driving from two sources, module is being flattened"
168 NOTE: do NOT use StageChain with combinatorial blocks that have
169 side-effects (state-based / clock-based input) or conditional
170 (inter-chain) dependencies, unless you really know what you are doing.
172 def __init__(self
, chain
, specallocate
=False):
173 assert len(chain
) > 0, "stage chain must be non-zero length"
175 self
.setup
= self
._sa
_setup
if specallocate
else self
._na
_setup
178 """ returns the ispec of the first of the chain
180 return _spec(self
.chain
[0].ispec
, "chainin")
183 """ returns the ospec of the last of the chain
185 return _spec(self
.chain
[-1].ospec
, "chainout")
187 def _sa_setup(self
, m
, i
):
188 for (idx
, c
) in enumerate(self
.chain
):
189 if hasattr(c
, "setup"):
190 c
.setup(m
, i
) # stage may have some module stuff
191 ofn
= self
.chain
[idx
].ospec
# last assignment survives
192 o
= _spec(ofn
, 'chainin%d' % idx
)
193 m
.d
.comb
+= nmoperator
.eq(o
, c
.process(i
)) # process input into "o"
194 if idx
== len(self
.chain
)-1:
196 ifn
= self
.chain
[idx
+1].ispec
# new input on next loop
197 i
= _spec(ifn
, 'chainin%d' % (idx
+1))
198 m
.d
.comb
+= nmoperator
.eq(i
, o
) # assign to next input
200 return self
.o
# last loop is the output
202 def _na_setup(self
, m
, i
):
203 for (idx
, c
) in enumerate(self
.chain
):
204 if hasattr(c
, "setup"):
205 c
.setup(m
, i
) # stage may have some module stuff
206 i
= o
= c
.process(i
) # store input into "o"
208 return self
.o
# last loop is the output
210 def process(self
, i
):
211 return self
.o
# conform to Stage API: return last-loop output
214 class StageHelper(Stage
):
215 """ a convenience wrapper around something that is Stage-API-compliant.
216 (that "something" may be a static class, for example).
218 StageHelper happens to also be compliant with the Stage API,
219 it differs from the stage that it wraps in that all the "optional"
220 functions are provided (hence the designation "convenience wrapper")
222 def __init__(self
, stage
):
226 if stage
is not None:
227 self
.set_specs(self
, self
)
229 def ospec(self
, name
):
230 assert self
._ospecfn
is not None
231 return _spec(self
._ospecfn
, name
)
233 def ispec(self
, name
):
234 assert self
._ispecfn
is not None
235 return _spec(self
._ispecfn
, name
)
237 def set_specs(self
, p
, n
):
238 self
._ispecfn
= p
.stage
.ispec
239 self
._ospecfn
= n
.stage
.ospec
241 def new_specs(self
, name
):
242 """ allocates new ispec and ospec pair
244 return self
.ispec("%s_i" % name
), self
.ospec("%s_o" % name
)
246 def process(self
, i
):
247 if self
.stage
and hasattr(self
.stage
, "process"):
248 return self
.stage
.process(i
)
251 def setup(self
, m
, i
):
252 if self
.stage
is not None and hasattr(self
.stage
, "setup"):
253 self
.stage
.setup(m
, i
)
255 def _postprocess(self
, i
): # XXX DISABLED
256 return i
# RETURNS INPUT
257 if hasattr(self
.stage
, "postprocess"):
258 return self
.stage
.postprocess(i
)