From: Luke Kenneth Casson Leighton Date: Wed, 22 Jul 2020 09:50:47 +0000 (+0100) Subject: update README for pipe_data.py X-Git-Tag: semi_working_ecp5~636 X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=593c41881b455aeeb19fe98071647d7b4ffca15c;p=soc.git update README for pipe_data.py --- diff --git a/src/soc/fu/README.md b/src/soc/fu/README.md index 83198f16..e6689906 100644 --- 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 9bfb81af..bdd22019 100644 --- 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