Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

doc/dataflow: update to new API

  • Loading branch information...
commit 3a3bc2e8765bb6aeb78cf5537ae9b5479d534f0f 1 parent cf22aae
Sébastien Bourdeauducq authored

Showing 1 changed file with 12 additions and 19 deletions. Show diff stats Hide diff stats

  1. 31  doc/dataflow.rst
31  doc/dataflow.rst
Source Rendered
@@ -41,13 +41,9 @@ The flow of tokens is controlled using two handshake signals (strobe and acknowl
41 41
 
42 42
 It is permitted to generate an ``ack`` signal combinatorially from one or several ``stb`` signals. However, there should not be any combinatorial path from an ``ack`` to a ``stb`` signal.
43 43
 
44  
-Actors are derived from the the ``migen.flow.actor.Actor`` base class. The constructor of this base class takes a variable number of parameters, each describing one endpoint of the actor.
  44
+Actors are FHDL modules that have one or several endpoint attributes of the ``migen.flow.actor.Sink`` or ``migen.flow.actor.Source`` type, and a ``busy`` signal.
45 45
 
46  
-An endpoint description is a triple consisting of:
47  
-
48  
-* The endpoint's name.
49  
-* A reference to the ``migen.flow.actor.Sink`` or the ``migen.flow.actor.Source`` class, defining the token direction of the endpoint.
50  
-* The layout of the data record that the endpoint is dealing with.
  46
+Endpoint constructors take as parameter the layout of the data record that the endpoint is dealing with.
51 47
 
52 48
 Record layouts are a list of fields. Each field is described by a pair consisting of:
53 49
 
@@ -56,25 +52,22 @@ Record layouts are a list of fields. Each field is described by a pair consistin
56 52
 
57 53
 For example, this code: ::
58 54
 
59  
-  Actor(
60  
-    ("operands", Sink, [("a", 16), ("b", 16)]),
61  
-    ("result", Source, [("r", 17)]))
  55
+  class MyActor(Module):
  56
+    def __init__(self):
  57
+      self.busy = Signal()
  58
+      self.operands = Sink([("a", 16), ("b", 16)])
  59
+      self.result = Source([("r", 17)])
62 60
 
63 61
 creates an actor with:
64 62
 
65 63
 * One sink named ``operands`` accepting data structured as a 16-bit field ``a`` and a 16-bit field ``b``. Note that this is functionally different from having two endpoints ``a`` and ``b``, each accepting a single 16-bit field. With a single endpoint, the data is strobed when *both* ``a`` and ``b`` are valid, and ``a`` and ``b`` are *both* acknowledged *atomically*. With two endpoints, the actor has to deal with accepting ``a`` and ``b`` independently. Plumbing actors (see :ref:`plumbing`) and abstract networks (see :ref:`actornetworks`) provide a systematic way of converting between these two behaviours, so user actors should implement the behaviour that results in the simplest or highest performance design.
66 64
 * One source named ``result`` transmitting a single 17-bit field named ``r``.
67 65
 
68  
-Implementing the functionality of the actor can be done in two ways:
69  
-
70  
-* Overloading the ``get_fragment`` method.
71  
-* Overloading both the ``get_control_fragment`` and ``get_process_fragment`` methods. The ``get_control_fragment`` method should return a fragment that manipulates the control signals (strobes, acknowledgements and the actor's busy signal) while ``get_process_fragment`` should return a fragment that manipulates the token payload. Overloading ``get_control_fragment`` alone allows you to define abstract actor classes implementing a given scheduling model. Migen comes with a library of such abstract classes for the most common schedules (see :ref:`schedmod`).
72  
-
73  
-Accessing the endpoints is done via the ``endpoints`` dictionary, which is keyed by endpoint names and contains instances of the ``migen.flow.actor.Endpoint`` class. The latter holds:
  66
+Accessing the endpoints is done by manipulating the signals inside the ``Source`` and ``Sink`` objects. They hold:
74 67
 
75 68
 * A signal object ``stb``.
76 69
 * A signal object ``ack``.
77  
-* The data payload ``token``. The individual fields are the items (in the Python sense) of this object.
  70
+* The data payload ``payload``, which is a record with the layout given to the endpoint constructor.
78 71
 
79 72
 Busy signal
80 73
 ===========
@@ -92,7 +85,7 @@ This signal represents whether the actor's state holds information that will cau
92 85
 Common scheduling models
93 86
 ========================
94 87
 
95  
-For the simplest and most common scheduling cases, Migen provides logic to generate the handshake signals and the busy signal. This is done through abstract actor classes that overload ``get_control_fragment`` only, and the user should overload ``get_process_fragment`` to implement the actor's payload.
  88
+For the simplest and most common scheduling cases, Migen provides logic to generate the handshake signals and the busy signal. This is done through abstract actor classes that examine the endpoints defined by the user and add logic to drive their control signals (i.e. everything except the payload). The ``__init__`` method of the abstract scheduling class must be called after the user has created the endpoints. The ``busy`` signal is created by the abstract scheduling class.
96 89
 
97 90
 These classes are usable only when the actor has exactly one sink and one source (but those endpoints can contain an arbitrary data structure), and in the cases listed below.
98 91
 
@@ -174,7 +167,7 @@ Simulation actors
174 167
 
175 168
 When hardware implementation is not desired, Migen lets you program actor behaviour in "regular" Python.
176 169
 
177  
-For this purpose, it provides a ``migen.actorlib.sim.SimActor`` class. The constructor takes a generator as parameter, and a list of endpoints (similarly to the base ``migen.flow.actor.Actor`` class). The generator implements the actor's behaviour.
  170
+For this purpose, it provides a ``migen.actorlib.sim.SimActor`` class. The constructor takes a generator as parameter, which implements the actor's behaviour. The user must derive the ``SimActor`` class and add endpoint attributes. The ``busy`` signal is provided by the ``SimActor`` class.
178 171
 
179 172
 Generators can yield ``None`` (in which case, the actor does no transfer for one cycle) or one or a tuple of instances of the ``Token`` class. Tokens for sink endpoints are pulled and the "value" field filled in. Tokens for source endpoints are pushed according to their "value" field. The generator is run again after all transactions are completed.
180 173
 
@@ -216,7 +209,7 @@ The ``migen.actorlib.dma_lasmi.Reader`` requires a LASMI master port at instanti
216 209
 Input tokens contain the raw LASMI address, and output tokens are wide LASMI data words.
217 210
 
218 211
 LASMI writer
219  
------------
  212
+------------
220 213
 
221 214
 Similarly, Migen provides a LASMI writer actor that accepts tokens containing an address and write data (in the same format as a LASMI word).
222 215
 

0 notes on commit 3a3bc2e

Please sign in to comment.
Something went wrong with that request. Please try again.