fpga: expand and reword things

1 files changed, 75 insertions, 7 deletions

diff --git a/fpga-hacking.rst b/fpga-hacking.rst
index edebb30..177b004 100644
--- a/fpga-hacking.rst
+++ b/fpga-hacking.rst
@@ -1,26 +1,91 @@
 FPGA Hacking
 ===================
 
-- HDL template
-- pointers to toolchain setup and FPGA learning resources
-- kernel and userland details
-- performance and "numbers" table
-- expansion header pinouts
+.. TODO::
+    - HDL template
+    - kernel and userland details
+    - performance and "numbers" table
+    - expansion header pinouts
+
+The general purpose FPGA on the Novena mainboard is a Xilinx Spartan6 XC6SLX45
+device in the CSG324 BGA package with a ``-3`` speedgrade. It is connected to
+the ARM CPU via SPI for bitstream configuration, via i2c for low-speed
+communications, and via a 16-bit memory interface ("EIM") for faster
+communications. The FPGA also has it's own DRAM chip and an expansion header to
+which extra hardware can be attached.
+
+.. list-table:: Novena FPGA Specifications (from Xilinx)
+    :stub-columns: 1
+
+    * - Part Number
+      - Xilinx Spartan6 XC6SLX45
+    * - Slices
+      - 6822
+    * - Logic Cells
+      - 43661
+    * - CLB Flip-Flops
+      - 54576
+    * - Max Distributed RAM
+      - 50 KB (401 Kb)
+    * - Block RAM
+      - 261 KB (116x 18 Kb blocks)
+    * - Clock Management Tiles (CMT)
+      - 4
+    * - DSP48A Slices
+      - 58
+    * - PCIe Hard Blocks
+      - None
+    * - Memory Controller Blocks
+      - 2
+    * - Gigabit Transcievers (GTP)
+      - None
+    * - Bitfile Size
+      - 1.49 MB (11.9 Mb)
+    * - US Market Price
+      - $53 (@100, December 2014)
+
+For those just getting started with FPGA development, two sources of free/libre
+learning resources are the `free range factory
+<http://www.freerangefactory.org/site/index.php>`_ website (including the libre
+"Free Range VHDL" book, and a mirror of opencores.org), and Xess Corp's free
+"FPGAs? Now What?!" `book (pdf) <http://www.xess.com/static/media/appnotes/FpgasNowWhatBook.pdf>`_. These guides cover a lot of context about getting
+vendor software installed, HDL languages, FPGA hardware resources, timing and
+constraint specification, the compilation and synthesis process, and the
+various toolchain workflows; this content won't be repeated here.
 
 GPBB FPGA Communications Quickstart
 -------------------------------------
 
-Run these commands from a Novena with the GPBB attached::
+The General Purpose Breakout Board (GPBB) comes installed on the expansion
+port header of all Novenas. It's got some LEDs and analog I/O (see `the wiki
+<http://kosagi.com/w/index.php?title=GPBB_User_Guide>`_ for details), which
+make it great for simple FPGA experimentation and blinky light displays.
+
+Before we can control the GPBB from linux, we need to load a bitfile to the
+FPGA (which controls the expansion header) and install some userland software
+to talk to the FPGA over the EIM interface.
+
+Run these commands from a Novena with the GPBB attached to compile the userland
+programs::
 
     sudo apt-get install i2c-tools libi2c-dev
     cd      # sic.
     git clone https://github.com/bunnie/novena-gpbb-example
     cd novena-gpbb-example
     make -j4
+
+Then use the helper script and bitfile included in the ``novena-gpbb-example``
+repo to configure the FPGA (this would need to be done after every power cycle
+of the board)::
+
     sudo ./configure.sh novena_fpga.bit
+
+And check if we can read metadata from the hardware::
+
     sudo ./novena-gpbb -v
 
-Simple test --- toggle four on-board LEDs, connected to I/O port B, pins 0--3::
+Finally, make with the blinkenlights_ and toggle the four LEDs on the GPBB,
+connected to I/O port B, pins 0 to 3::
 
     sudo ./novena-gpbb -oeb 1 # set port B to drive
     for BIT in 0 1 2 3; do
@@ -30,3 +95,6 @@ Simple test --- toggle four on-board LEDs, connected to I/O port B, pins 0--3::
     sudo ./novena-gpbb -p b 00 # Write 0x00, i.e. reset all pins
     sudo ./novena-gpbb -oeb 0 # return port B to tristate mode
 
+Joy!
+
+.. _blinkenlights: https://en.wikipedia.org/wiki/Blinkenlights