doc: framebuffer example

diff --git a/doc/bus.rst b/doc/bus.rst
index ef3f2a31907ca4a06d8bc3ed89593f099c049cfc..1ecf3fd3d7d34af15c5cd97a8623f60b7be6000e 100644 (file)
--- a/doc/bus.rst
+++ b/doc/bus.rst
@@ -35,6 +35,8 @@ It is the successor of the CSR bus used in Milkymist SoC 1.x, with two modificat
 * Up to 32 slave devices (instead of 16)
 * Data words are 8 bits (instead of 32)
 
+.. _bank:
+
 Generating register banks
 =========================
 Migen Bank is a system comparable to wishbone-gen [wbgen]_, which automates the creation of configuration and status register banks and interrupt/event managers implemented in cores.

diff --git a/doc/casestudies.rst b/doc/casestudies.rst
index be962527be3509621eac51c127a058873f0d0b78..77e9827434a5f07a66fff1b76c9bf36ff59aa1c3 100644 (file)
--- a/doc/casestudies.rst
+++ b/doc/casestudies.rst
@@ -1,7 +1,60 @@
 Case studies
 ############
 
-A VGA framebuffer
-*****************
+A VGA framebuffer core
+**********************
 
-TODO
+Purpose
+=======
+
+The purpose of the VGA framebuffer core is to scan a buffer in system memory and generate an appropriately timed video signal in order to display the picture from said buffer on a regular VGA monitor.
+
+The core is meant to be integrated in a SoC and is controllable by a CPU which can set parameters such as the framebuffer address, video resolution and timing parameters.
+
+This case study highlights what tools Migen provides to design such a core.
+
+Architecture
+============
+
+The framebuffer core is designed using the Migen dataflow system (see :ref:`dataflow`). Its block diagram is given in the figure below:
+
+.. figure:: fbflow.png
+   :scale: 50 %
+
+   Data flow graph of the framebuffer core.
+
+Actors drawn with a blue background are designed specifically for the framebuffer cores, the others are generic actors from the Migen library. Migen also provides the interconnect logic between the actors.
+
+Frame initiator
+===============
+
+The frame initiator generates tokens that correspond each to one complete scan of the picture (active video, synchronization pulses, front and back porches). The token contains the address and the length of the framebuffer used for the active video region, and timing parameters to generate the synchronization and porches.
+
+Switching the framebuffer address (without tearing) is simply done by generating a token with the new address.  Tearing will not occur since the new token will accepted only after the one from the previous frame has been processed (i.e. all addresses within the previous frame have been generated).
+
+Video resolution can be changed in a similar way.
+
+To interface with the CPU, the frame initiator uses Migen to provide a CSR bank (see :ref:`bank`).
+
+Pixel fetcher
+=============
+
+The pixel fetcher is made up of the address generator, the ASMI reader and the unpacker.
+
+TODO: IntSequence doc
+
+The address generator is a simple counter that takes one token containing the pair ``(base, length)`` and generates ``length`` tokens containing ``base``, ..., ``base+length-1``.
+
+Those addresses are fed into the ASMI reader (see :ref:`busactors`) that fetches the corresponding locations from the system memory. The ASMI reader design supports an arbitrary number of outstanding requests (which is equal to the number of slots in its ASMI port), which enables it to sustain a high throughput in spite of memory latency. The ASMI reader also contains a reorder buffer and generates memory word tokens in the order of the supplied address tokens, even if the memory system completes the transactions in a different order (see see :ref:`asmi` for information about reordering). These features make it possible to utilize the available memory bandwidth to the full extent, and reduce the need for on-chip buffering.
+
+ASMI memory words are wide and contain several pixels. The unpacking actor (see :ref:`structuring`) takes a token containing a memory word and "chops" it into multiple tokens containing one pixel each.
+
+Video timing generator
+======================
+
+The video timing generator is the central piece of the framebuffer core. It takes one token containing the timing parameters of a frame, followed by as many tokens as there are pixels in the frame. It generates tokens containing the status of the horizontal/vertical synchronization signals and red/green/blue values. When the contents of those tokens are sent out at the pixel clock rate (and the red/green/blue value converted to analog), they form a valid video signal for one frame.
+
+DAC driver
+==========
+
+The DAC driver accepts and buffers the output tokens from the video timing generator, and sends their content to the DAC and video port at the pixel clock rate using an asynchronous FIFO.

diff --git a/doc/dataflow.rst b/doc/dataflow.rst
index cd15a55ef7188bde91404933d6cb504c5966c927..636ab54e945d45c99a6e2192b7122ea6d7dfbc5b 100644 (file)
--- a/doc/dataflow.rst
+++ b/doc/dataflow.rst
@@ -1,3 +1,5 @@
+.. _dataflow:
+
 Dataflow
 ########
 

diff --git a/doc/fbflow.dia b/doc/fbflow.dia
new file mode 100644 (file)
index 0000000..e62c98f
Binary files /dev/null and b/doc/fbflow.dia differ

diff --git a/doc/fbflow.png b/doc/fbflow.png
new file mode 100644 (file)
index 0000000..5066769
Binary files /dev/null and b/doc/fbflow.png differ