src/soc/fu/README.md

   1 # Pipelines
   2
   3 In this directory are the pipelines.  The structure of each pipeline is
   4 as follows:
   5
   6 * pipe_data.py: contains pipeline input and output data structures
   7 * XXXX_stage.py: function-specific stages (connected up together by pipeline.py)
   8 * XXX_input_record.py: a PowerISA decoded instruction subset for this pipeline
   9 * pipeline.py: the actual pipeline chain, which brings all stages together
  10
  11 # Computation Units
  12
  13 A subdirectory named compunits contains the 6600 style "Comp Units".
  14 These are pipeline managers whose sole job is to monitor the operation
  15 in its entirety from start to finish, including receiving of all
  16 operands and the storage of all results. AT NO TIME does a Comp Unit
  17 "abandon" data to a pipeline.
  18
  19 Each pipeline is given a Comp Unit frontend.  The base class uses regspecs
  20 to construct the required latches in order to capture data pending send and
  21 receive data to and from the required Register Files.
  22
  23 # Common files
  24
  25 * regspec.py: the register specification API.  used by each pipe_data.py
  26 * pipe_data.py: base class for pipeline pipe_data.py data structures
  27 * common_input_stage.py: functionality common to input stages (RA, RB)
  28 * common_output_stage.py: functionality common to output stages (SO, CA/32 etc.)
  29
  30 ## `pipe_data.py`
  31
  32 ### `CommonPipeSpec`
  33
  34 `CommonPipeSpec` creates a specification object that allows convenient
  35 plugging in to the Pipeline API.  In the parallel version this will
  36 involve mix-in using the ReservationStation class.  Construction of
  37 an actual pipeline specification is done, e.g. in `soc.spr.pipe_data`:
  38
  39     class SPRPipeSpec(CommonPipeSpec):
  40         regspec = (SPRInputData.regspec, SPROutputData.regspec)
  41         opsubsetkls = CompSPROpSubset
  42
  43 * **pipekls** defines what type of pipeline base class (dynamic mixin)
  44 is to be used for *ALL* pipelines.  replace with `MaskCancellableRedir`
  45 when the Dependency Matrices are added: mask and stop signals will
  46 then "magically" appear right the way through every single pipeline
  47 (no further effort or coding required as far as the pipelines are concerned).
  48
  49 * **id_wid** is for the `ReservationStation` muxid width.  the muxid
  50   itself keeps track of which `ReservationStation` the partial results
  51   are associated with, so that when finally produced the result can be
  52   put back into the correctly-numbered Reservation Station "bucket".
  53
  54 * **opkls** is the "operation context" which is passed through all pipeline
  55   stages.  it is a PowerDecoder2 subset (actually Decode2ToOperand)
  56
  57 ### `IntegerData`
  58
  59 `IntegerData` is the base class for all pipeline data structures,
  60 providing the "convenience" of auto-construction of members
  61 according to "regspec" definitions. This is conceptually similar to
  62 nmigen Record (Layout, actually) except that Layout does not contain
  63 the right type of information for connecting up to Register Files.
  64
  65 By having a base class that handles creation of pipeline input/output
  66 in a structured fashion, CompUnits may conform to that same structured
  67 API, and when it comes to actually connecting up to regfiles, the same
  68 holds true.  The alternative is mountains of explicit code (which quickly
  69 becomes unmaintainable).
  70
  71 Note the mode parameter - output.  output pipeline data structures need to
  72 have an "ok" flag added (using the Data Record), which is used by the
  73 CompUnit and by the Register File to determine if the output shall in fact be
  74 written to the register file or not.
  75
  76 Input data has *already* been determined to have had to have been read,
  77 this by PowerDecoder2, so does not need any such flag, and consequently
  78 can be a plain "Signal".
  79
  80 Therefore it is critical to note that there has to be properly coordinated
  81 collaboration between `PowerDecoder2` and each pipeline, to ensure that the
  82 inputs set up by `PowerDecoder2` are used *by* the pipeline (on a per
  83 operation basis) *and* that likewise when the pipeline sets up its
  84 outputs, `PowerDecoder2` is aware precisely and exactly where that data
  85 is to be written.  See `DecodeOut`, `OP_RFID` case statement for example.
  86