From: Luke Kenneth Casson Leighton <lkcl@lkcl.net>
Date: Sat, 27 Apr 2019 18:59:33 +0000 (+0100)
Subject: update ControlBase docstrings, throw assert if pipechain is zero length
X-Git-Tag: ls180-24jan2020~1175
X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=5334a109f78855323db39c669e39981eb79ef355;p=ieee754fpu.git

update ControlBase docstrings, throw assert if pipechain is zero length
---

diff --git a/src/add/iocontrol.py b/src/add/iocontrol.py
index e0a6e0cb..66c67c94 100644
--- a/src/add/iocontrol.py
+++ b/src/add/iocontrol.py
@@ -397,7 +397,9 @@ class StageChain(StageCls):
 
 
 class ControlBase(Elaboratable):
-    """ Common functions for Pipeline API
+    """ Common functions for Pipeline API.  Note: a "pipeline stage" only
+        exists (conceptually) when a ControlBase derivative is handed
+        a Stage (combinatorial block)
     """
     def __init__(self, stage=None, in_multi=None, stage_ctl=False):
         """ Base class containing ready/valid/data to previous and next stages
@@ -466,7 +468,18 @@ class ControlBase(Elaboratable):
             Thus it becomes possible to build up larger chains recursively.
             More complex chains (multi-input, multi-output) will have to be
             done manually.
+
+            Argument:
+
+            * :pipechain: - a sequence of ControlBase-derived classes
+                            (must be one or more in length)
+
+            Returns:
+
+            * a list of eq assignments that will need to be added in
+              an elaborate() to m.d.comb
         """
+        assert len(pipechain > 0), "pipechain must be non-zero length"
         eqs = [] # collated list of assignment statements
 
         # connect inter-chain
@@ -527,4 +540,3 @@ class ControlBase(Elaboratable):
 
         return m
 
-