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.
12 the methods of a stage instance must be as follows:
14 * ispec() - Input data format specification
15 returns an object or a list or tuple of objects, or
16 a Record, each object having an "eq" function which
17 takes responsibility for copying by assignment all
19 * ospec() - Output data format specification
20 requirements as for ospec
21 * process(m, i) - Processes an ispec-formatted object
22 returns a combinatorial block of a result that
23 may be assigned to the output, by way of the "eq"
25 * setup(m, i) - Optional function for setting up submodules
26 may be used for more complex stages, to link
27 the input (i) to submodules. must take responsibility
28 for adding those submodules to the module (m).
29 the submodules must be combinatorial blocks and
30 must have their inputs and output linked combinatorially.
32 Both StageCls (for use with non-static classes) and Stage (for use
33 by static classes) are abstract classes from which, for convenience
34 and as a courtesy to other developers, anything conforming to the
35 Stage API may *choose* to derive.
40 A useful combinatorial wrapper around stages that chains them together
41 and then presents a Stage-API-conformant interface. By presenting
42 the same API as the stages it wraps, it can clearly be used recursively.
47 The base class for pipelines. Contains previous and next ready/valid/data.
48 Also has an extremely useful "connect" function that can be used to
49 connect a chain of pipelines and present the exact same prev/next
53 from nmigen
import Signal
, Cat
, Const
, Mux
, Module
, Value
, Elaboratable
54 from nmigen
.cli
import verilog
, rtlil
55 from nmigen
.hdl
.rec
import Record
57 from abc
import ABCMeta
, abstractmethod
58 from collections
.abc
import Sequence
, Iterable
59 from collections
import OrderedDict
62 from nmoperator
import eq
, cat
, shape
67 self
.fields
= OrderedDict()
69 def __setattr__(self
, k
, v
):
71 if (k
.startswith('_') or k
in ["fields", "name", "src_loc"] or
72 k
in dir(Object
) or "fields" not in self
.__dict
__):
73 return object.__setattr
__(self
, k
, v
)
76 def __getattr__(self
, k
):
77 if k
in self
.__dict
__:
78 return object.__getattr
__(self
, k
)
82 raise AttributeError(e
)
85 for x
in self
.fields
.values():
86 if isinstance(x
, Iterable
):
93 for (k
, o
) in self
.fields
.items():
97 if isinstance(rres
, Sequence
):
108 class RecordObject(Record
):
109 def __init__(self
, layout
=None, name
=None):
110 Record
.__init
__(self
, layout
=layout
or [], name
=None)
112 def __setattr__(self
, k
, v
):
114 if (k
.startswith('_') or k
in ["fields", "name", "src_loc"] or
115 k
in dir(Record
) or "fields" not in self
.__dict
__):
116 return object.__setattr
__(self
, k
, v
)
118 #print ("RecordObject setattr", k, v)
119 if isinstance(v
, Record
):
120 newlayout
= {k
: (k
, v
.layout
)}
121 elif isinstance(v
, Value
):
122 newlayout
= {k
: (k
, v
.shape())}
124 newlayout
= {k
: (k
, shape(v
))}
125 self
.layout
.fields
.update(newlayout
)
128 for x
in self
.fields
.values():
129 if isinstance(x
, Iterable
):
138 def _spec(fn
, name
=None):
141 varnames
= dict(inspect
.getmembers(fn
.__code
__))['co_varnames']
142 if 'name' in varnames
:
147 class PrevControl(Elaboratable
):
148 """ contains signals that come *from* the previous stage (both in and out)
149 * valid_i: previous stage indicating all incoming data is valid.
150 may be a multi-bit signal, where all bits are required
151 to be asserted to indicate "valid".
152 * ready_o: output to next stage indicating readiness to accept data
153 * data_i : an input - added by the user of this class
156 def __init__(self
, i_width
=1, stage_ctl
=False):
157 self
.stage_ctl
= stage_ctl
158 self
.valid_i
= Signal(i_width
, name
="p_valid_i") # prev >>in self
159 self
._ready
_o
= Signal(name
="p_ready_o") # prev <<out self
160 self
.data_i
= None # XXX MUST BE ADDED BY USER
162 self
.s_ready_o
= Signal(name
="p_s_o_rdy") # prev <<out self
163 self
.trigger
= Signal(reset_less
=True)
167 """ public-facing API: indicates (externally) that stage is ready
170 return self
.s_ready_o
# set dynamically by stage
171 return self
._ready
_o
# return this when not under dynamic control
173 def _connect_in(self
, prev
, direct
=False, fn
=None):
174 """ internal helper function to connect stage to an input source.
175 do not use to connect stage-to-stage!
177 valid_i
= prev
.valid_i
if direct
else prev
.valid_i_test
178 data_i
= fn(prev
.data_i
) if fn
is not None else prev
.data_i
179 return [self
.valid_i
.eq(valid_i
),
180 prev
.ready_o
.eq(self
.ready_o
),
181 eq(self
.data_i
, data_i
),
185 def valid_i_test(self
):
186 vlen
= len(self
.valid_i
)
188 # multi-bit case: valid only when valid_i is all 1s
189 all1s
= Const(-1, (len(self
.valid_i
), False))
190 valid_i
= (self
.valid_i
== all1s
)
192 # single-bit valid_i case
193 valid_i
= self
.valid_i
195 # when stage indicates not ready, incoming data
196 # must "appear" to be not ready too
198 valid_i
= valid_i
& self
.s_ready_o
202 def elaborate(self
, platform
):
204 m
.d
.comb
+= self
.trigger
.eq(self
.valid_i_test
& self
.ready_o
)
208 return [self
.data_i
.eq(i
.data_i
),
209 self
.ready_o
.eq(i
.ready_o
),
210 self
.valid_i
.eq(i
.valid_i
)]
215 if hasattr(self
.data_i
, "ports"):
216 yield from self
.data_i
.ports()
217 elif isinstance(self
.data_i
, Sequence
):
218 yield from self
.data_i
226 class NextControl(Elaboratable
):
227 """ contains the signals that go *to* the next stage (both in and out)
228 * valid_o: output indicating to next stage that data is valid
229 * ready_i: input from next stage indicating that it can accept data
230 * data_o : an output - added by the user of this class
232 def __init__(self
, stage_ctl
=False):
233 self
.stage_ctl
= stage_ctl
234 self
.valid_o
= Signal(name
="n_valid_o") # self out>> next
235 self
.ready_i
= Signal(name
="n_ready_i") # self <<in next
236 self
.data_o
= None # XXX MUST BE ADDED BY USER
238 self
.d_valid
= Signal(reset
=1) # INTERNAL (data valid)
239 self
.trigger
= Signal(reset_less
=True)
242 def ready_i_test(self
):
244 return self
.ready_i
& self
.d_valid
247 def connect_to_next(self
, nxt
):
248 """ helper function to connect to the next stage data/valid/ready.
249 data/valid is passed *TO* nxt, and ready comes *IN* from nxt.
250 use this when connecting stage-to-stage
252 return [nxt
.valid_i
.eq(self
.valid_o
),
253 self
.ready_i
.eq(nxt
.ready_o
),
254 eq(nxt
.data_i
, self
.data_o
),
257 def _connect_out(self
, nxt
, direct
=False, fn
=None):
258 """ internal helper function to connect stage to an output source.
259 do not use to connect stage-to-stage!
261 ready_i
= nxt
.ready_i
if direct
else nxt
.ready_i_test
262 data_o
= fn(nxt
.data_o
) if fn
is not None else nxt
.data_o
263 return [nxt
.valid_o
.eq(self
.valid_o
),
264 self
.ready_i
.eq(ready_i
),
265 eq(data_o
, self
.data_o
),
268 def elaborate(self
, platform
):
270 m
.d
.comb
+= self
.trigger
.eq(self
.ready_i_test
& self
.valid_o
)
276 if hasattr(self
.data_o
, "ports"):
277 yield from self
.data_o
.ports()
278 elif isinstance(self
.data_o
, Sequence
):
279 yield from self
.data_o
287 class StageCls(metaclass
=ABCMeta
):
288 """ Class-based "Stage" API. requires instantiation (after derivation)
290 see "Stage API" above.. Note: python does *not* require derivation
291 from this class. All that is required is that the pipelines *have*
292 the functions listed in this class. Derivation from this class
293 is therefore merely a "courtesy" to maintainers.
296 def ispec(self
): pass # REQUIRED
298 def ospec(self
): pass # REQUIRED
300 #def setup(self, m, i): pass # OPTIONAL
302 def process(self
, i
): pass # REQUIRED
305 class Stage(metaclass
=ABCMeta
):
306 """ Static "Stage" API. does not require instantiation (after derivation)
308 see "Stage API" above. Note: python does *not* require derivation
309 from this class. All that is required is that the pipelines *have*
310 the functions listed in this class. Derivation from this class
311 is therefore merely a "courtesy" to maintainers.
323 #def setup(m, i): pass
330 class StageChain(StageCls
):
331 """ pass in a list of stages, and they will automatically be
332 chained together via their input and output specs into a
335 the end result basically conforms to the exact same Stage API.
337 * input to this class will be the input of the first stage
338 * output of first stage goes into input of second
339 * output of second goes into input into third (etc. etc.)
340 * the output of this class will be the output of the last stage
342 NOTE: whilst this is very similar to ControlBase.connect(), it is
343 *really* important to appreciate that StageChain is pure
344 combinatorial and bypasses (does not involve, at all, ready/valid
345 signalling of any kind).
347 ControlBase.connect on the other hand respects, connects, and uses
348 ready/valid signalling.
352 * :chain: a chain of combinatorial blocks conforming to the Stage API
353 NOTE: StageChain.ispec and ospect have to have something
354 to return (beginning and end specs of the chain),
355 therefore the chain argument must be non-zero length
357 * :specallocate: if set, new input and output data will be allocated
358 and connected (eq'd) to each chained Stage.
359 in some cases if this is not done, the nmigen warning
360 "driving from two sources, module is being flattened"
363 NOTE: do NOT use StageChain with combinatorial blocks that have
364 side-effects (state-based / clock-based input) or conditional
365 (inter-chain) dependencies, unless you really know what you are doing.
367 def __init__(self
, chain
, specallocate
=False):
368 assert len(chain
> 0), "stage chain must be non-zero length"
370 self
.specallocate
= specallocate
373 """ returns the ispec of the first of the chain
375 return _spec(self
.chain
[0].ispec
, "chainin")
378 """ returns the ospec of the last of the chain
380 return _spec(self
.chain
[-1].ospec
, "chainout")
382 def _specallocate_setup(self
, m
, i
):
383 o
= i
# in case chain is empty
384 for (idx
, c
) in enumerate(self
.chain
):
385 if hasattr(c
, "setup"):
386 c
.setup(m
, i
) # stage may have some module stuff
387 ofn
= self
.chain
[idx
].ospec
# last assignment survives
388 o
= _spec(ofn
, 'chainin%d' % idx
)
389 m
.d
.comb
+= eq(o
, c
.process(i
)) # process input into "o"
390 if idx
== len(self
.chain
)-1:
392 ifn
= self
.chain
[idx
+1].ispec
# new input on next loop
393 i
= _spec(ifn
, 'chainin%d' % (idx
+1))
394 m
.d
.comb
+= eq(i
, o
) # assign to next input
395 return o
# last loop is the output
397 def _noallocate_setup(self
, m
, i
):
398 o
= i
# in case chain is empty
399 for (idx
, c
) in enumerate(self
.chain
):
400 if hasattr(c
, "setup"):
401 c
.setup(m
, i
) # stage may have some module stuff
402 i
= o
= c
.process(i
) # store input into "o"
403 return o
# last loop is the output
405 def setup(self
, m
, i
):
406 if self
.specallocate
:
407 self
.o
= self
._specallocate
_setup
(m
, i
)
409 self
.o
= self
._noallocate
_setup
(m
, i
)
411 def process(self
, i
):
412 return self
.o
# conform to Stage API: return last-loop output
415 class ControlBase(Elaboratable
):
416 """ Common functions for Pipeline API. Note: a "pipeline stage" only
417 exists (conceptually) when a ControlBase derivative is handed
418 a Stage (combinatorial block)
420 def __init__(self
, stage
=None, in_multi
=None, stage_ctl
=False):
421 """ Base class containing ready/valid/data to previous and next stages
423 * p: contains ready/valid to the previous stage
424 * n: contains ready/valid to the next stage
426 Except when calling Controlbase.connect(), user must also:
427 * add data_i member to PrevControl (p) and
428 * add data_o member to NextControl (n)
432 # set up input and output IO ACK (prev/next ready/valid)
433 self
.p
= PrevControl(in_multi
, stage_ctl
)
434 self
.n
= NextControl(stage_ctl
)
436 # set up the input and output data
437 if stage
is not None:
438 self
.p
.data_i
= _spec(stage
.ispec
, "data_i") # input type
439 self
.n
.data_o
= _spec(stage
.ospec
, "data_o") # output type
441 def connect_to_next(self
, nxt
):
442 """ helper function to connect to the next stage data/valid/ready.
444 return self
.n
.connect_to_next(nxt
.p
)
446 def _connect_in(self
, prev
):
447 """ internal helper function to connect stage to an input source.
448 do not use to connect stage-to-stage!
450 return self
.p
._connect
_in
(prev
.p
)
452 def _connect_out(self
, nxt
):
453 """ internal helper function to connect stage to an output source.
454 do not use to connect stage-to-stage!
456 return self
.n
._connect
_out
(nxt
.n
)
458 def connect(self
, pipechain
):
459 """ connects a chain (list) of Pipeline instances together and
460 links them to this ControlBase instance:
462 in <----> self <---> out
465 [pipe1, pipe2, pipe3, pipe4]
468 out---in out--in out---in
470 Also takes care of allocating data_i/data_o, by looking up
471 the data spec for each end of the pipechain. i.e It is NOT
472 necessary to allocate self.p.data_i or self.n.data_o manually:
473 this is handled AUTOMATICALLY, here.
475 Basically this function is the direct equivalent of StageChain,
476 except that unlike StageChain, the Pipeline logic is followed.
478 Just as StageChain presents an object that conforms to the
479 Stage API from a list of objects that also conform to the
480 Stage API, an object that calls this Pipeline connect function
481 has the exact same pipeline API as the list of pipline objects
484 Thus it becomes possible to build up larger chains recursively.
485 More complex chains (multi-input, multi-output) will have to be
490 * :pipechain: - a sequence of ControlBase-derived classes
491 (must be one or more in length)
495 * a list of eq assignments that will need to be added in
496 an elaborate() to m.d.comb
498 assert len(pipechain
> 0), "pipechain must be non-zero length"
499 eqs
= [] # collated list of assignment statements
501 # connect inter-chain
502 for i
in range(len(pipechain
)-1):
504 pipe2
= pipechain
[i
+1]
505 eqs
+= pipe1
.connect_to_next(pipe2
)
507 # connect front of chain to ourselves
509 self
.p
.data_i
= _spec(front
.stage
.ispec
, "chainin")
510 eqs
+= front
._connect
_in
(self
)
512 # connect end of chain to ourselves
514 self
.n
.data_o
= _spec(end
.stage
.ospec
, "chainout")
515 eqs
+= end
._connect
_out
(self
)
519 def _postprocess(self
, i
): # XXX DISABLED
520 return i
# RETURNS INPUT
521 if hasattr(self
.stage
, "postprocess"):
522 return self
.stage
.postprocess(i
)
525 def set_input(self
, i
):
526 """ helper function to set the input data
528 return eq(self
.p
.data_i
, i
)
537 def elaborate(self
, platform
):
538 """ handles case where stage has dynamic ready/valid functions
541 m
.submodules
.p
= self
.p
542 m
.submodules
.n
= self
.n
544 if self
.stage
is not None and hasattr(self
.stage
, "setup"):
545 self
.stage
.setup(m
, self
.p
.data_i
)
547 if not self
.p
.stage_ctl
:
550 # intercept the previous (outgoing) "ready", combine with stage ready
551 m
.d
.comb
+= self
.p
.s_ready_o
.eq(self
.p
._ready
_o
& self
.stage
.d_ready
)
553 # intercept the next (incoming) "ready" and combine it with data valid
554 sdv
= self
.stage
.d_valid(self
.n
.ready_i
)
555 m
.d
.comb
+= self
.n
.d_valid
.eq(self
.n
.ready_i
& sdv
)