01fc568b0146d2502321441619a667438d1aaa7a
1 # SPDX-License-Identifier: LGPL-3-or-later
4 This work is funded through NLnet under Grant 2019-02-012
9 Associated development bugs:
10 * http://bugs.libre-riscv.org/show_bug.cgi?id=148
11 * http://bugs.libre-riscv.org/show_bug.cgi?id=64
12 * http://bugs.libre-riscv.org/show_bug.cgi?id=57
17 stage requires compliance with a strict API that may be
18 implemented in several means, including as a static class.
20 Stages do not HOLD data, and they definitely do not contain
21 signalling (ready/valid). They do however specify the FORMAT
22 of the incoming and outgoing data, and they provide a means to
23 PROCESS that data (from incoming format to outgoing format).
25 Stage Blocks really should be combinatorial blocks (Moore FSMs).
26 It would be ok to have input come in from sync'd sources
27 (clock-driven, Mealy FSMs) however by doing so they would no longer
28 be deterministic, and chaining such blocks with such side-effects
29 together could result in unexpected, unpredictable, unreproduceable
32 So generally to be avoided, then unless you know what you are doing.
33 https://en.wikipedia.org/wiki/Moore_machine
34 https://en.wikipedia.org/wiki/Mealy_machine
36 the methods of a stage instance must be as follows:
38 * ispec() - Input data format specification. Takes a bit of explaining.
39 The requirements are: something that eventually derives from
40 nmigen Value must be returned *OR* an iterator or iterable
41 or sequence (list, tuple etc.) or generator must *yield*
42 thing(s) that (eventually) derive from the nmigen Value class.
44 Complex to state, very simple in practice:
45 see test_buf_pipe.py for over 25 worked examples.
47 * ospec() - Output data format specification.
48 format requirements identical to ispec.
50 * process(m, i) - Optional function for processing ispec-formatted data.
51 returns a combinatorial block of a result that
52 may be assigned to the output, by way of the "nmoperator.eq"
53 function. Note that what is returned here can be
54 extremely flexible. Even a dictionary can be returned
55 as long as it has fields that match precisely with the
56 Record into which its values is intended to be assigned.
57 Again: see example unit tests for details.
59 * setup(m, i) - Optional function for setting up submodules.
60 may be used for more complex stages, to link
61 the input (i) to submodules. must take responsibility
62 for adding those submodules to the module (m).
63 the submodules must be combinatorial blocks and
64 must have their inputs and output linked combinatorially.
66 Both StageCls (for use with non-static classes) and Stage (for use
67 by static classes) are abstract classes from which, for convenience
68 and as a courtesy to other developers, anything conforming to the
69 Stage API may *choose* to derive. See Liskov Substitution Principle:
70 https://en.wikipedia.org/wiki/Liskov_substitution_principle
75 A useful combinatorial wrapper around stages that chains them together
76 and then presents a Stage-API-conformant interface. By presenting
77 the same API as the stages it wraps, it can clearly be used recursively.
82 A convenience wrapper around a Stage-API-compliant "thing" which
83 complies with the Stage API and provides mandatory versions of
84 all the optional bits.
87 from nmigen
import Elaboratable
88 from abc
import ABCMeta
, abstractmethod
91 from nmutil
import nmoperator
94 def _spec(fn
, name
=None):
95 """ useful function that determines if "fn" has an argument "name".
96 if so, fn(name) is called otherwise fn() is called.
98 means that ispec and ospec can be declared with *or without*
99 a name argument. normally it would be necessary to have
100 "ispec(name=None)" to achieve the same effect.
104 varnames
= dict(inspect
.getmembers(fn
.__code
__))['co_varnames']
105 if 'name' in varnames
:
110 class StageCls(metaclass
=ABCMeta
):
111 """ Class-based "Stage" API. requires instantiation (after derivation)
113 see "Stage API" above.. Note: python does *not* require derivation
114 from this class. All that is required is that the pipelines *have*
115 the functions listed in this class. Derivation from this class
116 is therefore merely a "courtesy" to maintainers.
119 def ispec(self
): pass # REQUIRED
121 def ospec(self
): pass # REQUIRED
123 # def setup(self, m, i): pass # OPTIONAL
125 # def process(self, i): pass # OPTIONAL
128 class Stage(metaclass
=ABCMeta
):
129 """ Static "Stage" API. does not require instantiation (after derivation)
131 see "Stage API" above. Note: python does *not* require derivation
132 from this class. All that is required is that the pipelines *have*
133 the functions listed in this class. Derivation from this class
134 is therefore merely a "courtesy" to maintainers.
146 #def setup(m, i): pass
150 #def process(i): pass
153 class StageHelper(Stage
):
154 """ a convenience wrapper around something that is Stage-API-compliant.
155 (that "something" may be a static class, for example).
157 StageHelper happens to also be compliant with the Stage API,
158 it differs from the stage that it wraps in that all the "optional"
159 functions are provided (hence the designation "convenience wrapper")
162 def __init__(self
, stage
):
166 if stage
is not None:
167 self
.set_specs(self
, self
)
169 def ospec(self
, name
=None):
170 assert self
._ospecfn
is not None
171 return _spec(self
._ospecfn
, name
)
173 def ispec(self
, name
=None):
174 assert self
._ispecfn
is not None
175 return _spec(self
._ispecfn
, name
)
177 def set_specs(self
, p
, n
):
178 """ sets up the ispecfn and ospecfn for getting input and output data
180 if hasattr(p
, "stage"):
182 if hasattr(n
, "stage"):
184 self
._ispecfn
= p
.ispec
185 self
._ospecfn
= n
.ospec
187 def new_specs(self
, name
):
188 """ allocates new ispec and ospec pair
190 return (_spec(self
.ispec
, "%s_i" % name
),
191 _spec(self
.ospec
, "%s_o" % name
))
193 def process(self
, i
):
194 if self
.stage
and hasattr(self
.stage
, "process"):
195 return self
.stage
.process(i
)
198 def setup(self
, m
, i
):
199 if self
.stage
is not None and hasattr(self
.stage
, "setup"):
200 self
.stage
.setup(m
, i
)
202 def _postprocess(self
, i
): # XXX DISABLED
203 return i
# RETURNS INPUT
204 if hasattr(self
.stage
, "postprocess"):
205 return self
.stage
.postprocess(i
)
209 class StageChain(StageHelper
):
210 """ pass in a list of stages (combinatorial blocks), and they will
211 automatically be chained together via their input and output specs
212 into a combinatorial chain, to create one giant combinatorial
215 the end result conforms to the exact same Stage API.
217 * input to this class will be the input of the first stage
218 * output of first stage goes into input of second
219 * output of second goes into input into third
221 * the output of this class will be the output of the last stage
223 NOTE: whilst this is very similar to ControlBase.connect(), it is
224 *really* important to appreciate that StageChain is pure
225 combinatorial and bypasses (does not involve, at all, ready/valid
226 signalling OF ANY KIND).
228 ControlBase.connect on the other hand respects, connects, and uses
229 ready/valid signalling.
233 * :chain: a chain of combinatorial blocks conforming to the Stage API
234 NOTE: StageChain.ispec and ospect have to have something
235 to return (beginning and end specs of the chain),
236 therefore the chain argument must be non-zero length
238 * :specallocate: if set, new input and output data will be allocated
239 and connected (eq'd) to each chained Stage.
240 in some cases if this is not done, the nmigen warning
241 "driving from two sources, module is being flattened"
244 NOTE: DO NOT use StageChain with combinatorial blocks that have
245 side-effects (state-based / clock-based input) or conditional
246 (inter-chain) dependencies, unless you really know what you are doing.
249 def __init__(self
, chain
, specallocate
=False):
250 assert len(chain
) > 0, "stage chain must be non-zero length"
252 StageHelper
.__init
__(self
, None)
254 self
.setup
= self
._sa
_setup
256 self
.setup
= self
._na
_setup
257 self
.set_specs(self
.chain
[0], self
.chain
[-1])
259 def _sa_setup(self
, m
, i
):
260 for (idx
, c
) in enumerate(self
.chain
):
261 if hasattr(c
, "setup"):
262 c
.setup(m
, i
) # stage may have some module stuff
263 ofn
= self
.chain
[idx
].ospec
# last assignment survives
264 cname
= 'chainin%d' % idx
265 o
= _spec(ofn
, cname
)
266 if isinstance(o
, Elaboratable
):
267 setattr(m
.submodules
, cname
, o
)
268 # process input into "o"
269 m
.d
.comb
+= nmoperator
.eq(o
, c
.process(i
))
270 if idx
== len(self
.chain
)-1:
272 ifn
= self
.chain
[idx
+1].ispec
# new input on next loop
273 i
= _spec(ifn
, 'chainin%d' % (idx
+1))
274 m
.d
.comb
+= nmoperator
.eq(i
, o
) # assign to next input
276 return self
.o
# last loop is the output
278 def _na_setup(self
, m
, i
):
279 for (idx
, c
) in enumerate(self
.chain
):
280 if hasattr(c
, "setup"):
281 c
.setup(m
, i
) # stage may have some module stuff
282 i
= o
= c
.process(i
) # store input into "o"
284 return self
.o
# last loop is the output
286 def process(self
, i
):
287 return self
.o
# conform to Stage API: return last-loop output