update README for pipe_data.py

diff --git a/src/soc/fu/README.md b/src/soc/fu/README.md
index 83198f167bd9bf7ddba7d5cef5f25450ecb1367d..e66899060bf0991d60b8c45f98f1bb938c9f9290 100644 (file)
--- a/src/soc/fu/README.md
+++ b/src/soc/fu/README.md
@@ -26,3 +26,61 @@ receive data to and from the required Register Files.
 * pipe_data.py: base class for pipeline pipe_data.py data structures
 * common_input_stage.py: functionality common to input stages (RA, RB)
 * common_output_stage.py: functionality common to output stages (SO, CA/32 etc.)
+
+## `pipe_data.py`
+
+### `CommonPipeSpec`
+
+`CommonPipeSpec` creates a specification object that allows convenient
+plugging in to the Pipeline API.  In the parallel version this will
+involve mix-in using the ReservationStation class.  Construction of
+an actual pipeline specification is done, e.g. in `soc.spr.pipe_data`:
+
+    class SPRPipeSpec(CommonPipeSpec):
+        regspec = (SPRInputData.regspec, SPROutputData.regspec)
+        opsubsetkls = CompSPROpSubset
+
+* **pipekls** defines what type of pipeline base class (dynamic mixin)
+is to be used for *ALL* pipelines.  replace with `MaskCancellableRedir`
+when the Dependency Matrices are added: mask and stop signals will
+then "magically" appear right the way through every single pipeline
+(no further effort or coding required as far as the pipelines are concerned).
+
+* **id_wid** is for the `ReservationStation` muxid width.  the muxid
+  itself keeps track of which `ReservationStation` the partial results
+  are associated with, so that when finally produced the result can be
+  put back into the correctly-numbered Reservation Station "bucket".
+
+* **opkls** is the "operation context" which is passed through all pipeline
+  stages.  it is a PowerDecoder2 subset (actually Decode2ToOperand)
+
+### `IntegerData`
+
+`IntegerData` is the base class for all pipeline data structures,
+providing the "convenience" of auto-construction of members
+according to "regspec" definitions. This is conceptually similar to
+nmigen Record (Layout, actually) except that Layout does not contain
+the right type of information for connecting up to Register Files.
+
+By having a base class that handles creation of pipeline input/output
+in a structured fashion, CompUnits may conform to that same structured
+API, and when it comes to actually connecting up to regfiles, the same
+holds true.  The alternative is mountains of explicit code (which quickly
+becomes unmaintainable).
+
+Note the mode parameter - output.  output pipeline data structures need to
+have an "ok" flag added (using the Data Record), which is used by the
+CompUnit and by the Register File to determine if the output shall in fact be
+written to the register file or not.
+
+Input data has *already* been determined to have had to have been read,
+this by PowerDecoder2, so does not need any such flag, and consequently
+can be a plain "Signal".
+
+Therefore it is critical to note that there has to be properly coordinated
+collaboration between `PowerDecoder2` and each pipeline, to ensure that the
+inputs set up by `PowerDecoder2` are used *by* the pipeline (on a per
+operation basis) *and* that likewise when the pipeline sets up its
+outputs, `PowerDecoder2` is aware precisely and exactly where that data
+is to be written.  See `DecodeOut`, `OP_RFID` case statement for example.
+

diff --git a/src/soc/fu/pipe_data.py b/src/soc/fu/pipe_data.py
index 9bfb81aff5b32e5d0570e8d0975f1ec78f7b6f22..bdd2201971e260eef2eac4e056a58edec1b08824 100644 (file)
--- a/src/soc/fu/pipe_data.py
+++ b/src/soc/fu/pipe_data.py
@@ -8,26 +8,12 @@ from soc.fu.regspec import get_regspec_bitwidth
 class IntegerData:
     """IntegerData: base class for all pipeline data structures
 
-    this class auto-constructs parameters (placing them in self.data)
-    based on "regspecs".  this is conceptually similar to nmigen Record
-    (Layout, actually) except that Layout does not contain the right type
-    of information for connecting up to Register Files.
+    see README.md for explanation of parameters and purpose.
 
-    by having a base class that handles creation of pipeline input/output
-    in a structured fashion, CompUnits may conform to that same structured
-    API, and when it comes to actually connecting up to regfiles, the same
-    holds true.
-
-    the alternative is mountains of explicit code (which quickly becomes
-    unmaintainable).
-
-    note the mode parameter - output.  output pipeline data structures
-    need to have an "ok" flag added, which is used by the CompUnit and
-    by the Register File to determine if the output shall in fact be
-    written to the register file or not.
-
-    input data has *already* been determined to have had to have been read,
-    this by PowerDecoder2.
+    note the mode parameter - output.  XXXInputData specs must
+    have this set to "False", and XXXOutputData specs (and anything
+    that creates intermediary outputs which propagate through a
+    pipeline *to* output) must have it set to "True".
     """
 
     def __init__(self, pspec, output):
@@ -75,20 +61,12 @@ def get_rec_width(rec):
 
 
 class CommonPipeSpec:
+    """CommonPipeSpec: base class for all pipeline specifications
+    see README.md for explanation of members.
+    """
     def __init__(self, id_wid):
-        # this defines what type of pipeline base class (dynamic mixin)
-        # is to be used for *ALL* pipelines.  replace with MaskCancellableRedir
-        # when the Dependency Matrices are added: mask and stop signals will
-        # then "magically" appear right the way through every single pipeline
         self.pipekls = SimpleHandshakeRedir
-
-        # this is for the ReservationStation muxid width
         self.id_wid = id_wid
-
-        # this is the "operation context" which is passed through all pipeline
-        # stages.  it is a PowerDecoder2 subset (actually Decode2ToOperand)
         self.opkls = lambda _: self.opsubsetkls(name="op")
         self.op_wid = get_rec_width(self.opkls(None)) # hmm..
-
-        # gets set up by Pipeline API.
         self.stage = None