whitequark · Feb 5, 2019
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1 @@
+_build/
diff --git a/docs/Makefile b/docs/Makefile
@@ -0,0 +1,13 @@
+SPHINXOPTS  =
+SPHINXBUILD = sphinx-build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help . _build $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ . _build $(SPHINXOPTS) $(O)
diff --git a/docs/conf.py b/docs/conf.py
@@ -0,0 +1,19 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+import sys, os
+import sphinx_rtd_theme
+
+# Configure our load path
+sys.path.insert(0, os.path.abspath('../software'))
+
+# Configure Sphinx
+extensions = ['sphinx.ext.viewcode', 'sphinx.ext.autodoc', 'sphinxarg.ext']
+autodoc_member_order = 'bysource'
+source_suffix = '.rst'
+master_doc = 'index'
+project = 'Glasgow Reference'
+author = 'whitequark'
+copyright = '2018-2019, whitequark'
+pygments_style = 'sphinx'
+html_theme = 'sphinx_rtd_theme'
diff --git a/docs/index.rst b/docs/index.rst
@@ -0,0 +1,10 @@
+Glasgow Reference
+=================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   introduction
+   internals
diff --git a/docs/internals.rst b/docs/internals.rst
@@ -0,0 +1,11 @@
+Internals
+=========
+
+This section documents the parts of the Glasgow hardware and software stack that is not user-exposed. It is not required for using Glasgow applets, but can be helpful for working on the Glasgow system itself.
+
+Contents:
+
+.. toctree::
+   :maxdepth: 1
+
+   internals_startup
diff --git a/docs/internals_startup.rst b/docs/internals_startup.rst
@@ -0,0 +1,73 @@
+Provisioning and startup
+========================
+
+Overview
+--------
+
+The Glasgow device contains two non-volatile memories, `ICE_MEM` and `FX2_MEM`, implemented as I²C EEPROMs. The `ICE_MEM` memory contains critical device configuration, and must be factory-programmed in a revision-specific way for the device to be usable. The `FX2_MEM` memory optionally contains FPGA bitstream and is not accessed at all during operation other than when explicitly requested.
+
+The `ICE_MEM` memory is logically divided into three parts:
+
+  1. FX2 boot configuration (8 bytes);
+  2. Glasgow configuration (currently 4 + 64 bytes);
+  3. Firmware (rest of the flash).
+
+The FX2 boot configuration can specify one of the two boot modes: the `ID-only mode` and the `firmware mode`. The ID-only mode is indicated by the initial byte ``C0`` and the firmware mode is indicated by the initial byte ``C2``. In the firmware mode, immediately after the boot configuration, the memory contains a set of (length, address, data) firmware chunks, which are loaded into on-chip RAM after FX2 reset is deasserted.
+
+.. note::
+
+   The paragraph above is a simplified high-level explanation of the FX2 boot process. For exhaustive documentation, refer to the `EZ-USB Technical Reference Manual <http://www.cypress.com/file/126446>`_ section 3.4.
+
+The Glasgow configuration is structured as a firmware chunk that is loaded to the very end of on-chip RAM; this is done so that it can be located at a predetermined position in the non-volatile memory without placing a limit on firmware size. It is currently 64 bytes long; if this space is ever exhausted, an additional configuration block may be added using the same basic structure.
+
+The Glasgow configuration contains, most importantly, the revision (as an ASCII letter, ``A``-``Z``) and serial number (16 ASCII letters, time in ISO 8601 format); these are written during factory configuration and must be preserved at all times, because the revision determines routing for certain signals on the board. The rest of configuration is described :ref:`below <py-GlasgowConfig>`.
+
+Factory programming
+-------------------
+
+With an empty EEPROM, the FX2 chip enumerates with Cypress VID and PID. The ``glasgow factory`` command looks for a device with this VID and PID, initializes the FX2 boot block to ID-only mode with Glasgow VID and PID, and writes initial Glasgow configuration block with the provided revision and autogenerated serial number.
+
+In ID-only mode, the FX2 chip enumerates on its own with the provided USB VID and PID, and ignores the rest of EEPROM.
+
+Mode identification
+-------------------
+
+The Device ID field is used to provide the mode and device revision to the host regardless of whether the device contains firmware. The high byte of DID is ``00`` in a device without loaded FX2 firmware, and ``01`` in a device with loaded FX2 firmware. The low byte of DID is the board revision, encoded as ``A`` → ``01``, ``B`` → ``02``, etc.
+
+Boot process
+------------
+
+There are two FX2 boot flows.
+
+When in firmware boot mode, after reset, the firmware and the configuration block are automatically loaded by FX2 silicon into on-chip RAM. After that, the device enumerates with DID ``01xx``.
+
+When in ID-only boot mode, after reset, the device enumerates with DID ``00xx``. Any CLI operation involving the device detects this condition and automatically loads the firmware using FX2 silicon features. The firmware explicitly loads the configuration block from the EEPROM and enumerates with DID ``01xx``.
+
+Firmware programming
+--------------------
+
+The ``glasgow flash`` command, without arguments or with ``--firmware`` argument, writes the default or the provided firmware to `FX2_MEM` and switches the device to firmware mode. The same command with ``--remove-firmware`` argument switches the device to ID-only mode.
+
+Bitstream operations
+--------------------
+
+The ``glasgow run <applet>`` command loads a bitstream into SRAM and changes bitstream-related fields in the configuration block in RAM.
+
+The ``glasgow flash <applet>`` command writes the bitstream into `ICE_MEM` and changes bitstream-related fields in the configuration block in `FX2_MEM`. It does not change the FPGA bitstream or configuration in SRAM. The bitstream is loaded on the next reset.
+
+Hot reload
+----------
+
+Hot reload (loading the firmware using ``make -C firmware load``) only results in a proper reset when FX2 is configured in ID-only mode, i.e. it is necessary to run ``glasgow flash --no-firmware`` before using a device for developing firmware.
+
+Python API
+----------
+
+.. _py-GlasgowConfig:
+
+.. automodule:: glasgow.device.config
+
+   .. autoclass:: GlasgowConfig
+
+      .. automethod:: encode
+      .. automethod:: decode
diff --git a/docs/introduction.rst b/docs/introduction.rst
@@ -0,0 +1,4 @@
+Introduction
+============
+
+To be written.
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1 @@
+sphinx-argparse
diff --git a/software/glasgow/device/config.py b/software/glasgow/device/config.py
@@ -8,30 +8,24 @@ class GlasgowConfig:
     """
     Glasgow EEPROM configuration data.
 
-    :type size: int
-    :attr size:
+    :ivar int size:
         Total size of configuration block (currently 64).
 
-    :type revision: str[1]
-    :attr revision:
+    :ivar str[1] revision:
         Revision letter, ``A``-``Z``.
 
-    :type serial: str[16]
-    :attr serial:
+    :ivar str[16] serial:
         Serial number, in ISO 8601 format.
 
-    :type bitstream_size: int
-    :attr bitstream_size:
+    :ivar int bitstream_size:
         Size of bitstream flashed to ICE_MEM, or 0 if there isn't one.
 
-    :type bitstream_id: bytes[16]
-    :attr bitstream_id:
+    :ivar bytes[16] bitstream_id:
         Opaque string that uniquely identifies bitstream functionality,
         but not necessarily any particular routing and placement.
         Only meaningful if ``bitstream_size`` is set.
 
-    :type voltage_limit: int[2]
-    :attr voltage_limit:
+    :ivar int[2] voltage_limit:
         Maximum allowed I/O port voltage, in millivolts.
     """
     size = 64