a4450c80e7af3ad2855fa21ad413a6f358df65f0
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 Stage Blocks really must be combinatorial blocks. It would be ok
14 to have input come in from sync'd sources (clock-driven) however by
15 doing so they would no longer be deterministic, and chaining such
16 blocks with such side-effects together could result in unexpected,
17 unpredictable, unreproduceable behaviour.
18 So generally to be avoided, then unless you know what you are doing.
20 the methods of a stage instance must be as follows:
22 * ispec() - Input data format specification
23 returns an object or a list or tuple of objects, or
24 a Record, each object having an "eq" function which
25 takes responsibility for copying by assignment all
27 * ospec() - Output data format specification
28 requirements as for ospec
29 * process(m, i) - Processes an ispec-formatted object
30 returns a combinatorial block of a result that
31 may be assigned to the output, by way of the "eq"
33 * setup(m, i) - Optional function for setting up submodules
34 may be used for more complex stages, to link
35 the input (i) to submodules. must take responsibility
36 for adding those submodules to the module (m).
37 the submodules must be combinatorial blocks and
38 must have their inputs and output linked combinatorially.
40 Both StageCls (for use with non-static classes) and Stage (for use
41 by static classes) are abstract classes from which, for convenience
42 and as a courtesy to other developers, anything conforming to the
43 Stage API may *choose* to derive.
48 A useful combinatorial wrapper around stages that chains them together
49 and then presents a Stage-API-conformant interface. By presenting
50 the same API as the stages it wraps, it can clearly be used recursively.
55 The base class for pipelines. Contains previous and next ready/valid/data.
56 Also has an extremely useful "connect" function that can be used to
57 connect a chain of pipelines and present the exact same prev/next
61 from nmigen
import Signal
, Cat
, Const
, Mux
, Module
, Value
, Elaboratable
62 from nmigen
.cli
import verilog
, rtlil
63 from nmigen
.hdl
.rec
import Record
65 from abc
import ABCMeta
, abstractmethod
66 from collections
.abc
import Sequence
, Iterable
67 from collections
import OrderedDict
75 self
.fields
= OrderedDict()
77 def __setattr__(self
, k
, v
):
79 if (k
.startswith('_') or k
in ["fields", "name", "src_loc"] or
80 k
in dir(Object
) or "fields" not in self
.__dict
__):
81 return object.__setattr
__(self
, k
, v
)
84 def __getattr__(self
, k
):
85 if k
in self
.__dict
__:
86 return object.__getattr
__(self
, k
)
90 raise AttributeError(e
)
93 for x
in self
.fields
.values():
94 if isinstance(x
, Iterable
):
101 for (k
, o
) in self
.fields
.items():
105 if isinstance(rres
, Sequence
):
116 class RecordObject(Record
):
117 def __init__(self
, layout
=None, name
=None):
118 Record
.__init
__(self
, layout
=layout
or [], name
=None)
120 def __setattr__(self
, k
, v
):
122 if (k
.startswith('_') or k
in ["fields", "name", "src_loc"] or
123 k
in dir(Record
) or "fields" not in self
.__dict
__):
124 return object.__setattr
__(self
, k
, v
)
126 #print ("RecordObject setattr", k, v)
127 if isinstance(v
, Record
):
128 newlayout
= {k
: (k
, v
.layout
)}
129 elif isinstance(v
, Value
):
130 newlayout
= {k
: (k
, v
.shape())}
132 newlayout
= {k
: (k
, nmoperator
.shape(v
))}
133 self
.layout
.fields
.update(newlayout
)
136 for x
in self
.fields
.values():
137 if isinstance(x
, Iterable
):
146 def _spec(fn
, name
=None):
149 varnames
= dict(inspect
.getmembers(fn
.__code
__))['co_varnames']
150 if 'name' in varnames
:
155 class PrevControl(Elaboratable
):
156 """ contains signals that come *from* the previous stage (both in and out)
157 * valid_i: previous stage indicating all incoming data is valid.
158 may be a multi-bit signal, where all bits are required
159 to be asserted to indicate "valid".
160 * ready_o: output to next stage indicating readiness to accept data
161 * data_i : an input - added by the user of this class
164 def __init__(self
, i_width
=1, stage_ctl
=False):
165 self
.stage_ctl
= stage_ctl
166 self
.valid_i
= Signal(i_width
, name
="p_valid_i") # prev >>in self
167 self
._ready
_o
= Signal(name
="p_ready_o") # prev <<out self
168 self
.data_i
= None # XXX MUST BE ADDED BY USER
170 self
.s_ready_o
= Signal(name
="p_s_o_rdy") # prev <<out self
171 self
.trigger
= Signal(reset_less
=True)
175 """ public-facing API: indicates (externally) that stage is ready
178 return self
.s_ready_o
# set dynamically by stage
179 return self
._ready
_o
# return this when not under dynamic control
181 def _connect_in(self
, prev
, direct
=False, fn
=None):
182 """ internal helper function to connect stage to an input source.
183 do not use to connect stage-to-stage!
185 valid_i
= prev
.valid_i
if direct
else prev
.valid_i_test
186 data_i
= fn(prev
.data_i
) if fn
is not None else prev
.data_i
187 return [self
.valid_i
.eq(valid_i
),
188 prev
.ready_o
.eq(self
.ready_o
),
189 nmoperator
.eq(self
.data_i
, data_i
),
193 def valid_i_test(self
):
194 vlen
= len(self
.valid_i
)
196 # multi-bit case: valid only when valid_i is all 1s
197 all1s
= Const(-1, (len(self
.valid_i
), False))
198 valid_i
= (self
.valid_i
== all1s
)
200 # single-bit valid_i case
201 valid_i
= self
.valid_i
203 # when stage indicates not ready, incoming data
204 # must "appear" to be not ready too
206 valid_i
= valid_i
& self
.s_ready_o
210 def elaborate(self
, platform
):
212 m
.d
.comb
+= self
.trigger
.eq(self
.valid_i_test
& self
.ready_o
)
216 return [self
.data_i
.eq(i
.data_i
),
217 self
.ready_o
.eq(i
.ready_o
),
218 self
.valid_i
.eq(i
.valid_i
)]
223 if hasattr(self
.data_i
, "ports"):
224 yield from self
.data_i
.ports()
225 elif isinstance(self
.data_i
, Sequence
):
226 yield from self
.data_i
234 class NextControl(Elaboratable
):
235 """ contains the signals that go *to* the next stage (both in and out)
236 * valid_o: output indicating to next stage that data is valid
237 * ready_i: input from next stage indicating that it can accept data
238 * data_o : an output - added by the user of this class
240 def __init__(self
, stage_ctl
=False):
241 self
.stage_ctl
= stage_ctl
242 self
.valid_o
= Signal(name
="n_valid_o") # self out>> next
243 self
.ready_i
= Signal(name
="n_ready_i") # self <<in next
244 self
.data_o
= None # XXX MUST BE ADDED BY USER
246 self
.d_valid
= Signal(reset
=1) # INTERNAL (data valid)
247 self
.trigger
= Signal(reset_less
=True)
250 def ready_i_test(self
):
252 return self
.ready_i
& self
.d_valid
255 def connect_to_next(self
, nxt
):
256 """ helper function to connect to the next stage data/valid/ready.
257 data/valid is passed *TO* nxt, and ready comes *IN* from nxt.
258 use this when connecting stage-to-stage
260 return [nxt
.valid_i
.eq(self
.valid_o
),
261 self
.ready_i
.eq(nxt
.ready_o
),
262 nmoperator
.eq(nxt
.data_i
, self
.data_o
),
265 def _connect_out(self
, nxt
, direct
=False, fn
=None):
266 """ internal helper function to connect stage to an output source.
267 do not use to connect stage-to-stage!
269 ready_i
= nxt
.ready_i
if direct
else nxt
.ready_i_test
270 data_o
= fn(nxt
.data_o
) if fn
is not None else nxt
.data_o
271 return [nxt
.valid_o
.eq(self
.valid_o
),
272 self
.ready_i
.eq(ready_i
),
273 nmoperator
.eq(data_o
, self
.data_o
),
276 def elaborate(self
, platform
):
278 m
.d
.comb
+= self
.trigger
.eq(self
.ready_i_test
& self
.valid_o
)
284 if hasattr(self
.data_o
, "ports"):
285 yield from self
.data_o
.ports()
286 elif isinstance(self
.data_o
, Sequence
):
287 yield from self
.data_o
295 class StageCls(metaclass
=ABCMeta
):
296 """ Class-based "Stage" API. requires instantiation (after derivation)
298 see "Stage API" above.. Note: python does *not* require derivation
299 from this class. All that is required is that the pipelines *have*
300 the functions listed in this class. Derivation from this class
301 is therefore merely a "courtesy" to maintainers.
304 def ispec(self
): pass # REQUIRED
306 def ospec(self
): pass # REQUIRED
308 #def setup(self, m, i): pass # OPTIONAL
310 def process(self
, i
): pass # REQUIRED
313 class Stage(metaclass
=ABCMeta
):
314 """ Static "Stage" API. does not require instantiation (after derivation)
316 see "Stage API" above. Note: python does *not* require derivation
317 from this class. All that is required is that the pipelines *have*
318 the functions listed in this class. Derivation from this class
319 is therefore merely a "courtesy" to maintainers.
331 #def setup(m, i): pass
338 class StageChain(StageCls
):
339 """ pass in a list of stages, and they will automatically be
340 chained together via their input and output specs into a
343 the end result basically conforms to the exact same Stage API.
345 * input to this class will be the input of the first stage
346 * output of first stage goes into input of second
347 * output of second goes into input into third (etc. etc.)
348 * the output of this class will be the output of the last stage
350 NOTE: whilst this is very similar to ControlBase.connect(), it is
351 *really* important to appreciate that StageChain is pure
352 combinatorial and bypasses (does not involve, at all, ready/valid
353 signalling of any kind).
355 ControlBase.connect on the other hand respects, connects, and uses
356 ready/valid signalling.
360 * :chain: a chain of combinatorial blocks conforming to the Stage API
361 NOTE: StageChain.ispec and ospect have to have something
362 to return (beginning and end specs of the chain),
363 therefore the chain argument must be non-zero length
365 * :specallocate: if set, new input and output data will be allocated
366 and connected (eq'd) to each chained Stage.
367 in some cases if this is not done, the nmigen warning
368 "driving from two sources, module is being flattened"
371 NOTE: do NOT use StageChain with combinatorial blocks that have
372 side-effects (state-based / clock-based input) or conditional
373 (inter-chain) dependencies, unless you really know what you are doing.
375 def __init__(self
, chain
, specallocate
=False):
376 assert len(chain
) > 0, "stage chain must be non-zero length"
378 self
.specallocate
= specallocate
381 """ returns the ispec of the first of the chain
383 return _spec(self
.chain
[0].ispec
, "chainin")
386 """ returns the ospec of the last of the chain
388 return _spec(self
.chain
[-1].ospec
, "chainout")
390 def _specallocate_setup(self
, m
, i
):
391 o
= i
# in case chain is empty
392 for (idx
, c
) in enumerate(self
.chain
):
393 if hasattr(c
, "setup"):
394 c
.setup(m
, i
) # stage may have some module stuff
395 ofn
= self
.chain
[idx
].ospec
# last assignment survives
396 o
= _spec(ofn
, 'chainin%d' % idx
)
397 m
.d
.comb
+= nmoperator
.eq(o
, c
.process(i
)) # process input into "o"
398 if idx
== len(self
.chain
)-1:
400 ifn
= self
.chain
[idx
+1].ispec
# new input on next loop
401 i
= _spec(ifn
, 'chainin%d' % (idx
+1))
402 m
.d
.comb
+= nmoperator
.eq(i
, o
) # assign to next input
403 return o
# last loop is the output
405 def _noallocate_setup(self
, m
, i
):
406 o
= i
# in case chain is empty
407 for (idx
, c
) in enumerate(self
.chain
):
408 if hasattr(c
, "setup"):
409 c
.setup(m
, i
) # stage may have some module stuff
410 i
= o
= c
.process(i
) # store input into "o"
411 return o
# last loop is the output
413 def setup(self
, m
, i
):
414 if self
.specallocate
:
415 self
.o
= self
._specallocate
_setup
(m
, i
)
417 self
.o
= self
._noallocate
_setup
(m
, i
)
419 def process(self
, i
):
420 return self
.o
# conform to Stage API: return last-loop output
423 class ControlBase(Elaboratable
):
424 """ Common functions for Pipeline API. Note: a "pipeline stage" only
425 exists (conceptually) when a ControlBase derivative is handed
426 a Stage (combinatorial block)
428 def __init__(self
, stage
=None, in_multi
=None, stage_ctl
=False):
429 """ Base class containing ready/valid/data to previous and next stages
431 * p: contains ready/valid to the previous stage
432 * n: contains ready/valid to the next stage
434 Except when calling Controlbase.connect(), user must also:
435 * add data_i member to PrevControl (p) and
436 * add data_o member to NextControl (n)
440 # set up input and output IO ACK (prev/next ready/valid)
441 self
.p
= PrevControl(in_multi
, stage_ctl
)
442 self
.n
= NextControl(stage_ctl
)
444 # set up the input and output data
445 if stage
is not None:
446 self
.p
.data_i
= _spec(stage
.ispec
, "data_i") # input type
447 self
.n
.data_o
= _spec(stage
.ospec
, "data_o") # output type
449 def connect_to_next(self
, nxt
):
450 """ helper function to connect to the next stage data/valid/ready.
452 return self
.n
.connect_to_next(nxt
.p
)
454 def _connect_in(self
, prev
):
455 """ internal helper function to connect stage to an input source.
456 do not use to connect stage-to-stage!
458 return self
.p
._connect
_in
(prev
.p
)
460 def _connect_out(self
, nxt
):
461 """ internal helper function to connect stage to an output source.
462 do not use to connect stage-to-stage!
464 return self
.n
._connect
_out
(nxt
.n
)
466 def connect(self
, pipechain
):
467 """ connects a chain (list) of Pipeline instances together and
468 links them to this ControlBase instance:
470 in <----> self <---> out
473 [pipe1, pipe2, pipe3, pipe4]
476 out---in out--in out---in
478 Also takes care of allocating data_i/data_o, by looking up
479 the data spec for each end of the pipechain. i.e It is NOT
480 necessary to allocate self.p.data_i or self.n.data_o manually:
481 this is handled AUTOMATICALLY, here.
483 Basically this function is the direct equivalent of StageChain,
484 except that unlike StageChain, the Pipeline logic is followed.
486 Just as StageChain presents an object that conforms to the
487 Stage API from a list of objects that also conform to the
488 Stage API, an object that calls this Pipeline connect function
489 has the exact same pipeline API as the list of pipline objects
492 Thus it becomes possible to build up larger chains recursively.
493 More complex chains (multi-input, multi-output) will have to be
498 * :pipechain: - a sequence of ControlBase-derived classes
499 (must be one or more in length)
503 * a list of eq assignments that will need to be added in
504 an elaborate() to m.d.comb
506 assert len(pipechain
) > 0, "pipechain must be non-zero length"
507 eqs
= [] # collated list of assignment statements
509 # connect inter-chain
510 for i
in range(len(pipechain
)-1):
512 pipe2
= pipechain
[i
+1]
513 eqs
+= pipe1
.connect_to_next(pipe2
)
515 # connect front of chain to ourselves
517 self
.p
.data_i
= _spec(front
.stage
.ispec
, "chainin")
518 eqs
+= front
._connect
_in
(self
)
520 # connect end of chain to ourselves
522 self
.n
.data_o
= _spec(end
.stage
.ospec
, "chainout")
523 eqs
+= end
._connect
_out
(self
)
527 def _postprocess(self
, i
): # XXX DISABLED
528 return i
# RETURNS INPUT
529 if hasattr(self
.stage
, "postprocess"):
530 return self
.stage
.postprocess(i
)
533 def set_input(self
, i
):
534 """ helper function to set the input data
536 return nmoperator
.eq(self
.p
.data_i
, i
)
545 def elaborate(self
, platform
):
546 """ handles case where stage has dynamic ready/valid functions
549 m
.submodules
.p
= self
.p
550 m
.submodules
.n
= self
.n
552 if self
.stage
is not None and hasattr(self
.stage
, "setup"):
553 self
.stage
.setup(m
, self
.p
.data_i
)
555 if not self
.p
.stage_ctl
:
558 # intercept the previous (outgoing) "ready", combine with stage ready
559 m
.d
.comb
+= self
.p
.s_ready_o
.eq(self
.p
._ready
_o
& self
.stage
.d_ready
)
561 # intercept the next (incoming) "ready" and combine it with data valid
562 sdv
= self
.stage
.d_valid(self
.n
.ready_i
)
563 m
.d
.comb
+= self
.n
.d_valid
.eq(self
.n
.ready_i
& sdv
)