From: Luke Kenneth Casson Leighton Date: Tue, 19 Nov 2019 15:44:17 +0000 (+0000) Subject: clarify StageChain X-Git-Tag: ls180-24jan2020~357 X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=f8aef3cb7e99a6ca9a17016c25946a4cb2b092aa;p=ieee754fpu.git clarify StageChain --- diff --git a/src/nmutil/stageapi.py b/src/nmutil/stageapi.py index 5c0308e2..57eb1e07 100644 --- a/src/nmutil/stageapi.py +++ b/src/nmutil/stageapi.py @@ -199,11 +199,12 @@ class StageHelper(Stage): class StageChain(StageHelper): - """ pass in a list of stages, and they will automatically be - chained together via their input and output specs into a - combinatorial chain, to create one giant combinatorial block. + """ pass in a list of stages (combinatorial blocks), and they will + automatically be chained together via their input and output specs + into a combinatorial chain, to create one giant combinatorial + block. - the end result basically conforms to the exact same Stage API. + the end result conforms to the exact same Stage API. * input to this class will be the input of the first stage * output of first stage goes into input of second @@ -214,7 +215,7 @@ class StageChain(StageHelper): NOTE: whilst this is very similar to ControlBase.connect(), it is *really* important to appreciate that StageChain is pure combinatorial and bypasses (does not involve, at all, ready/valid - signalling of any kind). + signalling OF ANY KIND). ControlBase.connect on the other hand respects, connects, and uses ready/valid signalling. @@ -232,7 +233,7 @@ class StageChain(StageHelper): "driving from two sources, module is being flattened" will be issued. - NOTE: do NOT use StageChain with combinatorial blocks that have + NOTE: DO NOT use StageChain with combinatorial blocks that have side-effects (state-based / clock-based input) or conditional (inter-chain) dependencies, unless you really know what you are doing. """