From: Luke Kenneth Casson Leighton <lkcl@lkcl.net>
Date: Mon, 29 Apr 2019 02:52:26 +0000 (+0100)
Subject: update comments
X-Git-Tag: ls180-24jan2020~1137
X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=8d62e8206e286a18ec1677d403340bd0846d2341;p=ieee754fpu.git

update comments
---

diff --git a/src/add/iocontrol.py b/src/add/iocontrol.py
index b3cdb3a3..d68f6da7 100644
--- a/src/add/iocontrol.py
+++ b/src/add/iocontrol.py
@@ -477,6 +477,11 @@ class ControlBase(StageHelper, Elaboratable):
     """ Common functions for Pipeline API.  Note: a "pipeline stage" only
         exists (conceptually) when a ControlBase derivative is handed
         a Stage (combinatorial block)
+
+        NOTE: ControlBase derives from StageHelper, making it accidentally
+        compliant with the Stage API.  Using those functions directly
+        *BYPASSES* a ControlBase instance ready/valid signalling, which
+        clearly should not be done without a really, really good reason.
     """
     def __init__(self, stage=None, in_multi=None, stage_ctl=False):
         """ Base class containing ready/valid/data to previous and next stages
@@ -487,6 +492,7 @@ class ControlBase(StageHelper, Elaboratable):
             Except when calling Controlbase.connect(), user must also:
             * add data_i member to PrevControl (p) and
             * add data_o member to NextControl (n)
+            Calling ControlBase._new_data is a good way to do that.
         """
         StageHelper.__init__(self, stage)