Merge pull request #33 from greatscottgadgets/documentation

docs: Cynthion documentation branch

cynthion/python/examples/facedancer-rubber-ducky.py

@@ -0,0 +1,15 @@
+import asyncio
+
+from facedancer                   import main
+from facedancer.devices.keyboard  import USBKeyboardDevice
+
+device = USBKeyboardDevice()
+
+async def type_letters():
+    # Wait for device to connect
+    await asyncio.sleep(2)
+
+    # Type a string with the device
+    await device.type_string("echo hello, facedancer\n")
+
+main(device, type_letters())

cynthion/python/examples/facedancer-usbproxy.py

@@ -0,0 +1,28 @@
+#!/usr/bin/env python3
+#
+# This file is part of Facedancer.
+#
+""" USB Proxy example; forwards all USB transactions and logs them to the console. """
+
+from facedancer          import main
+
+from facedancer.proxy    import USBProxyDevice
+from facedancer.filters  import USBProxySetupFilters, USBProxyPrettyPrintFilter
+
+# replace with the proxied device's information
+ID_VENDOR  = 0x1050
+ID_PRODUCT = 0x0407
+
+
+if __name__ == "__main__":
+    # create a USB Proxy Device
+    proxy = USBProxyDevice(idVendor=ID_VENDOR, idProduct=ID_PRODUCT)
+
+    # add a filter to forward control transfers between the target host and
+    # proxied device
+    proxy.add_filter(USBProxySetupFilters(proxy, verbose=0))
+
+    # add a filter to log USB transactions to the console
+    proxy.add_filter(USBProxyPrettyPrintFilter(verbose=5))
+
+    main(proxy)

docs/requirements.txt

@@ -1,4 +1,4 @@
 sphinx==7.2.6
-sphinx_rtd_theme==1.3.0
+sphinx_rtd_theme==2.0.0
 readthedocs-sphinx-search==0.3.2
 jinja2==3.1.4

docs/source/conf.py

@@ -17,14 +17,16 @@
 # -- General configuration ---------------------------------------------------
 
 extensions = [
-  'sphinx.ext.autodoc'
+    'sphinx.ext.autosectionlabel',
+    'sphinx.ext.autodoc',
 ]
+autosectionlabel_prefix_document = True
 
 templates_path = ['_templates']
 exclude_patterns = ['_build']
 source_suffix = '.rst'
 master_doc = 'index'
-language = None
+language = "en"
 exclude_patterns = []
 pygments_style = None
 

docs/source/developer/bitstream_generation.rst

@@ -0,0 +1,70 @@
+====================
+Bitstream Generation
+====================
+
+Before proceeding, please ensure you have followed the prerequisites in the :doc:`Setting up a Development Environment <introduction>` section.
+
+
+Cynthion Gateware
+-----------------
+
+The Cynthion repository contains gateware for two designs:
+
+- ``analyzer`` -- USB analyzer for using Cynthion with Packetry.
+- ``soc``      -- System-on-Chip for using Cynthion with Facedancer.
+
+Bitstreams can be generated from the ``cynthion`` Python package sub-directory as follows:
+
+Analyzer Gateware
+^^^^^^^^^^^^^^^^^
+
+.. code-block:: sh
+
+    # change to the 'cynthion' Python package directory
+    cd cynthion/python/
+
+    # generate bitstream
+    python3 -m cynthion.gateware.analyzer.top
+
+SoC Gateware
+^^^^^^^^^^^^
+
+.. code-block:: sh
+
+    # change to the 'cynthion' Python package directory
+    cd cynthion/python/
+
+    # generate bitstream
+    python3 -m cynthion.gateware.soc.top
+
+Additional Options
+^^^^^^^^^^^^^^^^^^
+
+Additional options for bitstream generation can be listed by appending ``--help`` to the command:
+
+.. code-block:: text
+
+    $ python3 -m cynthion.gateware.analyzer.top --help
+
+    usage: top.py [-h] [--output filename] [--erase] [--upload] [--flash]
+                  [--dry-run] [--keep-files] [--fpga part_number] [--console port]
+
+    Gateware generation/upload script for 'USBAnalyzerApplet' gateware.
+
+    optional arguments:
+      -h, --help            show this help message and exit
+      --output filename, -o filename
+                            Build and output a bitstream to the given file.
+      --erase, -E           Clears the relevant FPGA's flash before performing
+                            other options.
+      --upload, -U          Uploads the relevant design to the target hardware.
+                            Default if no options are provided.
+      --flash, -F           Flashes the relevant design to the target hardware's
+                            configuration flash.
+      --dry-run, -D         When provided as the only option; builds the relevant
+                            bitstream without uploading or flashing it.
+      --keep-files          Keeps the local files in the default `build` folder.
+      --fpga part_number    Overrides build configuration to build for a given
+                            FPGA. Useful if no FPGA is connected during build.
+      --console port        Attempts to open a convenience 115200 8N1 UART console
+                            on the specified port immediately after uploading.

docs/source/developer/cli.rst

@@ -0,0 +1,40 @@
+========================
+The ``cynthion`` Utility
+========================
+
+The ``cynthion`` distribution provides the ``cynthion`` command-line utility,
+that can be used to perform various simple functions useful in development;
+including simple JTAG operations, SVF playback, manipulating the board’s flash,
+and debug communications.
+
+.. code:: text
+
+    $ cynthion
+    usage: cynthion [-h] command ...
+
+    Cynthion FPGA Configuration / Debug tool
+
+    positional arguments:
+      command
+        info                Print device info.
+        jtag-scan           Prints information about devices on the onboard JTAG chain.
+        flash-info          Prints information about the FPGA's attached configuration flash.
+        flash-erase         Erases the contents of the FPGA's flash memory.
+        flash-program       Programs the target bitstream onto the FPGA's configuration flash.
+        flash-fast          Programs a bitstream onto the FPGA's configuration flash using a SPI bridge.
+        flash-read          Reads the contents of the attached FPGA's configuration flash.
+        svf                 Plays a given SVF file over JTAG.
+        configure           Uploads a bitstream to the device's FPGA over JTAG.
+        reconfigure         Requests the attached ECP5 reconfigure itself from its SPI flash.
+        force-offline       Forces the board's FPGA offline.
+        spi                 Sends the given list of bytes over debug-SPI, and returns the response.
+        spi-inv             Sends the given list of bytes over SPI with inverted CS.
+        spi-reg             Reads or writes to a provided register over the debug-SPI.
+        jtag-spi            Sends the given list of bytes over SPI-over-JTAG, and returns the response.
+        jtag-reg            Reads or writes to a provided register of JTAG-tunneled debug SPI.
+        leds                Sets the specified pattern for the Debug LEDs.
+        selftest            Run a hardware self-test on a connected Cynthion.
+        mcu-firmware        Update Apollo firmware version.
+
+    optional arguments:
+      -h, --help            show this help message and exit

docs/source/developer/introduction.rst

@@ -0,0 +1,44 @@
+============
+Introduction
+============
+
+
+Setting up a Development Environment
+------------------------------------
+
+This guide highlights the installation and setup process for setting up a local copy of the Cynthion source code for development.
+
+
+Prerequisites
+-------------
+
+- `Python <https://wiki.python.org/moin/BeginnersGuide/Download>`__ v3.8, or later.
+- A working FPGA toolchain. We only officially support a toolchain
+  composed of the `Project Trellis <https://github.com/YosysHQ/prjtrellis>`__
+  ECP5 tools, the `yosys <https://github.com/YosysHQ/yosys>`__
+  synthesis suite, and the `NextPNR <https://github.com/YosysHQ/nextpnr>`__
+  place-and-route tool. You can obtain the latest binary distribution of this
+  software from the `oss-cad-suite-build <https://github.com/YosysHQ/oss-cad-suite-build>`__
+  project.
+- A working `Rust development environment <https://www.rust-lang.org/learn/get-started>`__ if you want to develop firmware for Cynthion's SoC bitstream.
+- A `RISC-V GNU Compiler Toolchain <https://github.com/riscv-collab/riscv-gnu-toolchain>`__ if you want to use ``gdb`` for SoC firmware debugging over JTAG.
+
+
+Installation
+------------
+
+For development you'll need a local copy of the Cynthion repository:
+
+.. code-block:: sh
+
+    git clone https://github.com/greatscottgadgets/cynthion.git
+
+To install the ``cynthion`` Python package to allow for in-place editing of the sources you can use the ``pip --editable`` command:
+
+.. code-block:: sh
+
+    # change to the 'cynthion' Python package directory
+    cd cynthion/python/
+
+    # install the 'cynthion' Python package, including dependencies required for gateware development
+    pip install --editable ".[gateware]"

docs/source/developer/soc_firmware_compilation.rst

@@ -0,0 +1,80 @@
+========================
+SoC Firmware Compilation
+========================
+
+Before proceeding, please ensure you have followed the prerequisites in the :doc:`Setting up a Development Environment <introduction>` section.
+
+Building and Running
+--------------------
+
+Firmware for the Cynthion SoC can be found in the ``firmware/moondancer/`` sub-directory.
+
+You can rebuild the firmware using ``cargo`` as follows:
+
+.. code-block:: text
+
+    # change to the Cynthion firmware directory
+    cd firmware/moondancer/
+
+    # rebuild the firmware
+    cargo build --release
+
+To upload the firmware binary to Cynthion and flash the SoC bitstream you can run:
+
+.. code-block:: text
+
+    # change to the Cynthion firmware directory
+    cd firmware/moondancer/
+
+    # upload firmware and run it
+    cargo run --release
+
+.. note::
+
+    By default the firmware's flash script will look for the SoC UART
+    on ``/dev/ttyACM0``, if this is not the case on your machine you
+    will need to specify the correct path using the ``UART`` environment
+    variable, for example:
+
+    .. code-block:: sh
+
+        UART=/dev/cu.usbmodem22401 cargo run --release
+
+    By default the SoC bitstream is obtained from the latest build in
+    ``cynthion/python/build/top.bit`` but you can override
+    it with:
+
+    .. code-block:: sh
+
+        BITSTREAM=path/to/bitstream.bit cargo run --release
+
+
+Running Firmware Unit Tests
+---------------------------
+
+Once the firmware is running on the SoC you can execute some unit tests to exercise the firmware.
+
+In order to do this you will need to connect both the **CONTROL** and
+**AUX** ports of the Cynthion to the host and then run:
+
+.. code-block:: sh
+
+    # change to the Cynthion firmware directory
+    cd firmware/moondancer/
+
+    # run firmware unit tests
+    python -m unittest
+
+
+Firmware Examples
+-----------------
+
+There are a number of firmware examples in the ``firmware/moondancer/examples/`` sub-directory.
+
+.. code-block:: sh
+
+    # change to the Cynthion firmware directory
+    cd firmware/moondancer/
+
+    # run example
+    cargo run --release --example <example name>