doc: detailed actor description

doc/casestudies.rst

@@ -1,7 +1,7 @@
 Case studies
 ############
 
-A VGA framebuffer using dataflow
-********************************
+A VGA framebuffer
+*****************
 
 TODO

doc/dataflow.rst

@@ -1,17 +1,80 @@
-Dataflow synthesis
-##################
+Dataflow
+########
 
 Many hardware acceleration problems can be expressed in the dataflow paradigm. It models a program as a directed graph of the data flowing between functions. The nodes of the graph are functional units called actors, and the edges represent the connections (transporting data) between them.
 
-Actors communicate by exchanging data units called tokens. A token contains arbitrary (user-defined) data, which is a record containing one or many fields, a field being a bit vector or another record. Token exchanges are atomic (i.e. all fields are transferred at once from the transmitting actor to the receiving actor). The flow of tokens is controlled using handshake signals (strobe and acknowledgement).
+Actors communicate by exchanging data units called tokens. A token contains arbitrary (user-defined) data, which is a record containing one or many fields, a field being a bit vector or another record. Token exchanges are atomic (i.e. all fields are transferred at once from the transmitting actor to the receiving actor).
 
 Actors
 ******
 
-Overview
-========
+Actors in Migen are implemented in FHDL. This low-level approach maximizes the practical flexibility: for example, an actor can manipulate the bus signals to implement a DMA master in order to read data from system memory.
 
-Actors in Migen are written directly in FHDL. This maximizes the flexibility: for example, an actor can implement a DMA master to read data from system memory. 
+Token exchange ports of actors are called endpoints. Endpoints are unidirectional and can be sources (which transmit tokens out of the actor) or sinks (which receive tokens into the actor).
+
+.. figure:: actors_endpoints.png
+   :scale: 50 %
+
+   Actors and endpoints.
+
+The flow of tokens is controlled using two handshake signals (strobe and acknowledgement) which are implemented by every endpoint. The strobe signal is driven by sources, and the acknowledgement signal by sinks.
+
+======= ======= ====================================================================================================
+``stb`` ``ack`` Situation
+======= ======= ====================================================================================================
+0       0       The source endpoint does not have data to send, and the sink endpoint is not ready to 
+                accept data.
+0       1       The sink endpoint is ready to accept data, but the source endpoint has currently no data
+                to send. The sink endpoint is not required to keep its ``ack`` signal asserted.
+1       0       The source endpoint is trying to send data to the sink endpoint, which is currently not
+                ready to accept it. The transaction is *stalled*. The source endpoint must keep ``stb``
+                asserted and continue to present valid data until the transaction is completed.
+1       1       The source endpoint is sending data to the sink endpoint which is ready to accept it. The
+                transaction is *completed*. The sink endpoint must register the incoming data, as the
+                source endpoint is not required to hold it valid at the next cycle.
+======= ======= ====================================================================================================
+
+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.
+
+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.
+
+An endpoint description is a triple consisting of:
+
+ * The endpoint's name.
+ * A reference to the ``migen.flow.actor.Sink`` or the ``migen.flow.actor.Source`` class, defining the token direction of the endpoint.
+ * The layout of the data record that the endpoint is dealing with.
+
+Record layouts are a list of fields. Each field is described by a pair consisting of:
+
+ * The field's name.
+ * Either a BV object (see :ref:`bv`) if the field is a bit vector, or another record layout if the field is a lower-level record.
+
+For example, this code: ::
+
+  Actor(
+    ("operands", Sink, [("a", BV(16)), ("b", BV(16))]),
+    ("result", Source, [("r", BV(17))]))
+
+creates an actor with:
+
+ * 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.
+ * One source named ``result`` transmitting a single 17-bit field named ``r``.
+
+Implementing the functionality of the actor can be done in two ways:
+
+ * Overloading the ``get_fragment`` method.
+ * 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`).
+
+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:
+
+ * A signal object ``stb``.
+ * A signal object ``ack``.
+ * The data payload ``token``. The individual fields are the items (in the Python sense) of this object.
+
+Busy signal
+===========
+
+.. _schedmod:
 
 Common scheduling models
 ========================
@@ -31,6 +94,8 @@ This is similar to the sequential model, but the actor can always accept new inp
 The Migen actor library
 ***********************
 
+.. _plumbing:
+
 Plumbing actors
 ===============
 
@@ -46,6 +111,8 @@ Arithmetic and logic actors
 Bus actors
 ==========
 
+.. _actornetworks:
+
 Actor networks
 **************
 
@@ -59,6 +126,7 @@ Performance tools
 
 High-level actor description
 ****************************
+
 .. WARNING::
    Not implemented yet, just an idea.
 

doc/fhdl.rst

@@ -13,6 +13,8 @@ FHDL is made of several elements, which are briefly explained below.
 Expressions
 ***********
 
+.. _bv:
+
 Bit vector (BV)
 ===============
 The bit vector (BV) object defines if a constant or signal is signed or unsigned, and how many bits it has. This is useful e.g. to: