move pc_i and svstate_i inside if self.run_hdl
[soc.git] / 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