doc: dataflow chapter structure

doc/index.rst

@@ -405,34 +405,75 @@ TODO: please document me!
 
 Dataflow synthesis
 ##################
-.. WARNING::
-   This is experimental and incomplete.
 
 Many hardware acceleration problems can be expressed in the dataflow paradigm, that is, using a directed graph representing the flow of data between actors.
 
-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. It is conceivable that a CAL [cal]_ to FHDL compiler be implemented at some point, to support higher level descriptions of some actors and reuse of third-party RVC-CAL applications. [orcc]_ [orcapps]_ [opendf]_
+Actors communicate by exchanging tokens, whose flow is controlled using handshake signals (strobe and acknowledgement).
 
-.. [cal] http://opendf.svn.sourceforge.net/viewvc/opendf/trunk/doc/GentleIntro/GentleIntro.pdf
-.. [orcc] http://orcc.sourceforge.net/
-.. [orcapps] http://orc-apps.sourceforge.net/
-.. [opendf] http://opendf.sourceforge.net/
+Actors
+******
+
+Overview
+========
+
+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. 
 
-Actors communicate by exchanging tokens, whose flow is typically controlled using handshake signals (strobe/ack).
+Common scheduling models
+========================
 
-Each actor has a "scheduling model". It can be:
+Combinatorial
+-------------
+The actor datapath is made entirely of combinatorial logic. The handshake signals pass through. A small integer adder would use this model.
 
-* N-sequential: the actor fires when tokens are available at all its inputs, and it produces one output token after N cycles. It cannot accept new input tokens until it has produced its output. A multicycle integer divider would use this model.
-* N-pipelined: similar to the sequential model, but the actor can always accept new input tokens. It produces an output token N cycles of latency after accepting input tokens. A pipelined multiplier would use this model.
-* Dynamic: the general case, when no simple hypothesis can be made on the token flow behaviour of the actor. An actor accessing system memory on a shared bus would use this model.
+N-sequential
+------------
+The actor consumes one token at its input, and it produces one output token after N cycles. It cannot accept new input tokens until it has produced its output. A multicycle integer divider would use this model.
+
+N-pipelined
+-----------
+This is similar to the sequential model, but the actor can always accept new input tokens. It produces an output token N cycles of latency after accepting an input token. A pipelined multiplier would use this model.
+
+The Migen actor library
+***********************
+
+Plumbing actors
+===============
+
+Structuring actors
+==================
+
+Simulation actors
+=================
+
+Arithmetic and logic actors
+===========================
 
-Migen Flow automatically generates handshake logic for the first two scheduling models. In the third case, the FHDL descriptions for the logic driving the handshake signals must be provided by the actor.
+Bus actors
+==========
 
-An actor can be a composition of other actors.
+Actor networks
+**************
 
-Actor graphs are managed using the NetworkX [networkx]_ library.
+Actor networks are managed using the NetworkX [networkx]_ library.
 
 .. [networkx] http://networkx.lanl.gov/
 
+Performance tools
+*****************
+
+
+High-level actor description
+****************************
+.. WARNING::
+   Not implemented yet, just an idea.
+
+It is conceivable that a CAL [cal]_ to FHDL compiler be implemented at some point, to support higher level descriptions of some actors and reuse of third-party RVC-CAL applications. [orcc]_ [orcapps]_ [opendf]_
+
+.. [cal] http://opendf.svn.sourceforge.net/viewvc/opendf/trunk/doc/GentleIntro/GentleIntro.pdf
+.. [orcc] http://orcc.sourceforge.net/
+.. [orcapps] http://orc-apps.sourceforge.net/
+.. [opendf] http://opendf.sourceforge.net/
+
 .. _simulating:
 
 Simulating a Migen design
@@ -599,3 +640,11 @@ Dataflow simulation actors
 ==========================
 .. include:: ../examples/sim/dataflow.py
    :code: python
+
+Case studies
+############
+
+A VGA framebuffer using dataflow
+********************************
+
+TODO