src/add/stageapi.py

   1 """ Stage API
   2
   3     Associated development bugs:
   4     * http://bugs.libre-riscv.org/show_bug.cgi?id=64
   5     * http://bugs.libre-riscv.org/show_bug.cgi?id=57
   6
   7     Stage API:
   8     ---------
   9
  10     stage requires compliance with a strict API that may be
  11     implemented in several means, including as a static class.
  12
  13     Stages do not HOLD data, and they definitely do not contain
  14     signalling (ready/valid).  They do however specify the FORMAT
  15     of the incoming and outgoing data, and they provide a means to
  16     PROCESS that data (from incoming format to outgoing format).
  17
  18     Stage Blocks really must be combinatorial blocks.  It would be ok
  19     to have input come in from sync'd sources (clock-driven) however by
  20     doing so they would no longer be deterministic, and chaining such
  21     blocks with such side-effects together could result in unexpected,
  22     unpredictable, unreproduceable behaviour.
  23     So generally to be avoided, then unless you know what you are doing.
  24
  25     the methods of a stage instance must be as follows:
  26
  27     * ispec() - Input data format specification.  Takes a bit of explaining.
  28                 The requirements are: something that eventually derives from
  29                 nmigen Value must be returned *OR* an iterator or iterable
  30                 or sequence (list, tuple etc.) or generator must *yield*
  31                 thing(s) that (eventually) derive from the nmigen Value class.
  32
  33                 Complex to state, very simple in practice:
  34                 see test_buf_pipe.py for over 25 worked examples.
  35
  36     * ospec() - Output data format specification.
  37                 format requirements identical to ispec.
  38
  39     * process(m, i) - Optional function for processing ispec-formatted data.
  40                 returns a combinatorial block of a result that
  41                 may be assigned to the output, by way of the "nmoperator.eq"
  42                 function.  Note that what is returned here can be
  43                 extremely flexible.  Even a dictionary can be returned
  44                 as long as it has fields that match precisely with the
  45                 Record into which its values is intended to be assigned.
  46                 Again: see example unit tests for details.
  47
  48     * setup(m, i) - Optional function for setting up submodules.
  49                 may be used for more complex stages, to link
  50                 the input (i) to submodules.  must take responsibility
  51                 for adding those submodules to the module (m).
  52                 the submodules must be combinatorial blocks and
  53                 must have their inputs and output linked combinatorially.
  54
  55     Both StageCls (for use with non-static classes) and Stage (for use
  56     by static classes) are abstract classes from which, for convenience
  57     and as a courtesy to other developers, anything conforming to the
  58     Stage API may *choose* to derive.  See Liskov Substitution Principle:
  59     https://en.wikipedia.org/wiki/Liskov_substitution_principle
  60
  61     StageChain:
  62     ----------
  63
  64     A useful combinatorial wrapper around stages that chains them together
  65     and then presents a Stage-API-conformant interface.  By presenting
  66     the same API as the stages it wraps, it can clearly be used recursively.
  67
  68     StageHelper:
  69     ----------
  70
  71     A convenience wrapper around a Stage-API-compliant "thing" which
  72     complies with the Stage API and provides mandatory versions of
  73     all the optional bits.
  74 """
  75
  76 from abc import ABCMeta, abstractmethod
  77 import inspect
  78
  79 import nmoperator
  80
  81
  82 def _spec(fn, name=None):
  83     if name is None:
  84         return fn()
  85     varnames = dict(inspect.getmembers(fn.__code__))['co_varnames']
  86     if 'name' in varnames:
  87         return fn(name=name)
  88     return fn()
  89
  90
  91 class StageCls(metaclass=ABCMeta):
  92     """ Class-based "Stage" API.  requires instantiation (after derivation)
  93
  94         see "Stage API" above..  Note: python does *not* require derivation
  95         from this class.  All that is required is that the pipelines *have*
  96         the functions listed in this class.  Derivation from this class
  97         is therefore merely a "courtesy" to maintainers.
  98     """
  99     @abstractmethod
 100     def ispec(self): pass       # REQUIRED
 101     @abstractmethod
 102     def ospec(self): pass       # REQUIRED
 103     #@abstractmethod
 104     #def setup(self, m, i): pass # OPTIONAL
 105     #@abstractmethod
 106     #def process(self, i): pass  # OPTIONAL
 107
 108
 109 class Stage(metaclass=ABCMeta):
 110     """ Static "Stage" API.  does not require instantiation (after derivation)
 111
 112         see "Stage API" above.  Note: python does *not* require derivation
 113         from this class.  All that is required is that the pipelines *have*
 114         the functions listed in this class.  Derivation from this class
 115         is therefore merely a "courtesy" to maintainers.
 116     """
 117     @staticmethod
 118     @abstractmethod
 119     def ispec(): pass
 120
 121     @staticmethod
 122     @abstractmethod
 123     def ospec(): pass
 124
 125     #@staticmethod
 126     #@abstractmethod
 127     #def setup(m, i): pass
 128
 129     #@staticmethod
 130     #@abstractmethod
 131     #def process(i): pass
 132
 133
 134 class StageHelper(Stage):
 135     """ a convenience wrapper around something that is Stage-API-compliant.
 136         (that "something" may be a static class, for example).
 137
 138         StageHelper happens to also be compliant with the Stage API,
 139         it differs from the stage that it wraps in that all the "optional"
 140         functions are provided (hence the designation "convenience wrapper")
 141     """
 142     def __init__(self, stage):
 143         self.stage = stage
 144         self._ispecfn = None
 145         self._ospecfn = None
 146         if stage is not None:
 147             self.set_specs(self, self)
 148
 149     def ospec(self, name):
 150         assert self._ospecfn is not None
 151         return _spec(self._ospecfn, name)
 152
 153     def ispec(self, name):
 154         assert self._ispecfn is not None
 155         return _spec(self._ispecfn, name)
 156
 157     def set_specs(self, p, n):
 158         """ sets up the ispecfn and ospecfn for getting input and output data
 159         """
 160         if hasattr(p, "stage"):
 161             p = p.stage
 162         if hasattr(n, "stage"):
 163             n = n.stage
 164         self._ispecfn = p.ispec
 165         self._ospecfn = n.ospec
 166
 167     def new_specs(self, name):
 168         """ allocates new ispec and ospec pair
 169         """
 170         return self.ispec("%s_i" % name), self.ospec("%s_o" % name)
 171
 172     def process(self, i):
 173         if self.stage and hasattr(self.stage, "process"):
 174             return self.stage.process(i)
 175         return i
 176
 177     def setup(self, m, i):
 178         if self.stage is not None and hasattr(self.stage, "setup"):
 179             self.stage.setup(m, i)
 180
 181     def _postprocess(self, i): # XXX DISABLED
 182         return i # RETURNS INPUT
 183         if hasattr(self.stage, "postprocess"):
 184             return self.stage.postprocess(i)
 185         return i
 186
 187
 188 class StageChain(StageHelper):
 189     """ pass in a list of stages, and they will automatically be
 190         chained together via their input and output specs into a
 191         combinatorial chain, to create one giant combinatorial block.
 192
 193         the end result basically conforms to the exact same Stage API.
 194
 195         * input to this class will be the input of the first stage
 196         * output of first stage goes into input of second
 197         * output of second goes into input into third
 198         * ... (etc. etc.)
 199         * the output of this class will be the output of the last stage
 200
 201         NOTE: whilst this is very similar to ControlBase.connect(), it is
 202         *really* important to appreciate that StageChain is pure
 203         combinatorial and bypasses (does not involve, at all, ready/valid
 204         signalling of any kind).
 205
 206         ControlBase.connect on the other hand respects, connects, and uses
 207         ready/valid signalling.
 208
 209         Arguments:
 210
 211         * :chain: a chain of combinatorial blocks conforming to the Stage API
 212                   NOTE: StageChain.ispec and ospect have to have something
 213                   to return (beginning and end specs of the chain),
 214                   therefore the chain argument must be non-zero length
 215
 216         * :specallocate: if set, new input and output data will be allocated
 217                          and connected (eq'd) to each chained Stage.
 218                          in some cases if this is not done, the nmigen warning
 219                          "driving from two sources, module is being flattened"
 220                          will be issued.
 221
 222         NOTE: do NOT use StageChain with combinatorial blocks that have
 223         side-effects (state-based / clock-based input) or conditional
 224         (inter-chain) dependencies, unless you really know what you are doing.
 225     """
 226     def __init__(self, chain, specallocate=False):
 227         assert len(chain) > 0, "stage chain must be non-zero length"
 228         self.chain = chain
 229         StageHelper.__init__(self, None)
 230         self.setup = self._sa_setup if specallocate else self._na_setup
 231         self.set_specs(self.chain[0], self.chain[-1])
 232
 233     def _sa_setup(self, m, i):
 234         for (idx, c) in enumerate(self.chain):
 235             if hasattr(c, "setup"):
 236                 c.setup(m, i)               # stage may have some module stuff
 237             ofn = self.chain[idx].ospec     # last assignment survives
 238             o = _spec(ofn, 'chainin%d' % idx)
 239             m.d.comb += nmoperator.eq(o, c.process(i)) # process input into "o"
 240             if idx == len(self.chain)-1:
 241                 break
 242             ifn = self.chain[idx+1].ispec   # new input on next loop
 243             i = _spec(ifn, 'chainin%d' % (idx+1))
 244             m.d.comb += nmoperator.eq(i, o) # assign to next input
 245         self.o = o
 246         return self.o                       # last loop is the output
 247
 248     def _na_setup(self, m, i):
 249         for (idx, c) in enumerate(self.chain):
 250             if hasattr(c, "setup"):
 251                 c.setup(m, i)               # stage may have some module stuff
 252             i = o = c.process(i)            # store input into "o"
 253         self.o = o
 254         return self.o                       # last loop is the output
 255
 256     def process(self, i):
 257         return self.o # conform to Stage API: return last-loop output
 258
 259