diff --git a/cynthion/python/examples/facedancer-rubber-ducky.py b/cynthion/python/examples/facedancer-rubber-ducky.py new file mode 100644 index 00000000..c29cc46c --- /dev/null +++ b/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()) diff --git a/cynthion/python/examples/facedancer-usbproxy.py b/cynthion/python/examples/facedancer-usbproxy.py new file mode 100755 index 00000000..007e72fb --- /dev/null +++ b/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) diff --git a/docs/images/cynthion-bottom.svg b/docs/images/cynthion-bottom.svg new file mode 100644 index 00000000..40f9e997 --- /dev/null +++ b/docs/images/cynthion-bottom.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/images/cynthion-connections-facedancer.svg b/docs/images/cynthion-connections-facedancer.svg new file mode 100644 index 00000000..ee024eb5 --- /dev/null +++ b/docs/images/cynthion-connections-facedancer.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/images/cynthion-connections-host.svg b/docs/images/cynthion-connections-host.svg new file mode 100644 index 00000000..0fc5338a --- /dev/null +++ b/docs/images/cynthion-connections-host.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/images/cynthion-connections-packetry.svg b/docs/images/cynthion-connections-packetry.svg new file mode 100644 index 00000000..a74c84a9 --- /dev/null +++ b/docs/images/cynthion-connections-packetry.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/images/cynthion-connections-usbproxy.svg b/docs/images/cynthion-connections-usbproxy.svg new file mode 100644 index 00000000..ddd673a8 --- /dev/null +++ b/docs/images/cynthion-connections-usbproxy.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/images/cynthion-front.svg b/docs/images/cynthion-front.svg new file mode 100644 index 00000000..61d02c86 --- /dev/null +++ b/docs/images/cynthion-front.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/images/cynthion-left.svg b/docs/images/cynthion-left.svg new file mode 100644 index 00000000..4e30d4cb --- /dev/null +++ b/docs/images/cynthion-left.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/images/cynthion-right.svg b/docs/images/cynthion-right.svg new file mode 100644 index 00000000..db3daf89 --- /dev/null +++ b/docs/images/cynthion-right.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/images/cynthion-top.svg b/docs/images/cynthion-top.svg new file mode 100644 index 00000000..0e467e65 --- /dev/null +++ b/docs/images/cynthion-top.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/images/cynthion.jpg b/docs/images/cynthion.jpg new file mode 100644 index 00000000..9296149b Binary files /dev/null and b/docs/images/cynthion.jpg differ diff --git a/docs/images/cynthion.png b/docs/images/cynthion.png deleted file mode 100644 index f87c289e..00000000 Binary files a/docs/images/cynthion.png and /dev/null differ diff --git a/docs/images/cynthion_hardware.jpg b/docs/images/cynthion_hardware.jpg new file mode 100644 index 00000000..482d0925 Binary files /dev/null and b/docs/images/cynthion_hardware.jpg differ diff --git a/docs/requirements.txt b/docs/requirements.txt index 508b33eb..1bd66f75 100644 --- a/docs/requirements.txt +++ b/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 diff --git a/docs/source/conf.py b/docs/source/conf.py index 31396dcc..e1fb52af 100644 --- a/docs/source/conf.py +++ b/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 diff --git a/docs/source/developer/bitstream_generation.rst b/docs/source/developer/bitstream_generation.rst new file mode 100644 index 00000000..fe6af632 --- /dev/null +++ b/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 ` 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. diff --git a/docs/source/developer/cli.rst b/docs/source/developer/cli.rst new file mode 100644 index 00000000..36953c42 --- /dev/null +++ b/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 diff --git a/docs/source/developer/introduction.rst b/docs/source/developer/introduction.rst new file mode 100644 index 00000000..f551bd2b --- /dev/null +++ b/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 `__ v3.8, or later. +- A working FPGA toolchain. We only officially support a toolchain + composed of the `Project Trellis `__ + ECP5 tools, the `yosys `__ + synthesis suite, and the `NextPNR `__ + place-and-route tool. You can obtain the latest binary distribution of this + software from the `oss-cad-suite-build `__ + project. +- A working `Rust development environment `__ if you want to develop firmware for Cynthion's SoC bitstream. +- A `RISC-V GNU Compiler 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]" diff --git a/docs/source/developer/soc_firmware_compilation.rst b/docs/source/developer/soc_firmware_compilation.rst new file mode 100644 index 00000000..7a28229a --- /dev/null +++ b/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 ` 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 diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst new file mode 100644 index 00000000..83c50e2c --- /dev/null +++ b/docs/source/getting_started.rst @@ -0,0 +1,104 @@ +================================================ +Getting Started with Cynthion +================================================ + + +Prerequisites +------------- + +To use Cynthion you will need to ensure the following software is installed: + + * `Python `__ v3.8, or later. + + +Cynthion Host Software Installation +----------------------------------- + +The Cynthion host software distribution can be obtained from the `Python Package Index (PyPI) `__ or :doc:`directly from source `. + +Using the `pip `__ tool you can install the Cynthion host software by running: + +.. code-block :: sh + + pip install cynthion + +.. note:: + + For more information on installing Python packages from PyPI please refer to the + `"Installing Packages" `__ + section of the Python Packaging User Guide. + + +Install udev Rules (Linux Only) +------------------------------- + +Configure your system to allow access to Cynthion for logged in users: + +.. code-block :: sh + + # download udev rules + curl -O https://raw.githubusercontent.com/greatscottgadgets/cynthion/main/util/54-cynthion.rules + + # install udev rules + sudo cp 54-cynthion.rules /etc/udev/rules.d + + # reload udev rules + sudo udevadm control --reload + + # apply udev rules to any devices that are already plugged in + sudo udevadm trigger + + +Test Installation +----------------- + +Connect Hardware +^^^^^^^^^^^^^^^^ + +.. image:: ../images/cynthion-connections-host.svg + :width: 800 + :alt: Connection diagram for testing Cynthion installation. + +- Connect the Host computer to the Cynthion **CONTROL** port. +- Check that the :ref:`LED A power-on indicator ` lights up. + + +Test Hardware Connectivity +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Open a terminal and confirm that everything is working by running: + +.. code-block :: sh + + cynthion info + +If everything is working you will see the following output: + +.. code-block :: text + + Detected a Cynthion device! + Hardware: Cynthion r1.4 + Serial number: xxxxxxxxxxxxxxxxxxxxxxxxxx + Firmware version: v1.0.4 + USB API version: 1.1 + Flash UID: xxxxxxxxxxxxxxxx + + +Upgrading Cynthion Host Software +-------------------------------- + +To upgrade the Cynthion host software to the latest version run: + +.. code-block :: sh + + pip install --upgrade cynthion + + +Upgrading Cynthion Device Firmware +---------------------------------- + +To upgrade the Cynthion device firmware to the latest version run: + +.. code-block :: sh + + cynthion mcu-firmware --autoflash diff --git a/docs/source/getting_started_facedancer.rst b/docs/source/getting_started_facedancer.rst new file mode 100644 index 00000000..07be0cee --- /dev/null +++ b/docs/source/getting_started_facedancer.rst @@ -0,0 +1,99 @@ +============================== +Using Cynthion with Facedancer +============================== + +Before proceeding, please ensure you have completed all steps in the :doc:`getting_started` section. + + +Install the Facedancer library +------------------------------ + +You can install the Facedancer library from the `Python Package Index (PyPI) `__, a `release archive `__ or directly from `source `__. + + +Install From PyPI +^^^^^^^^^^^^^^^^^ + +You can use the `pip `__ tool to install the Facedancer library from PyPI using the following command: + +.. code-block :: sh + + pip install facedancer + +For more information on installing Python packages from PyPI please refer to the `"Installing Packages" `__ section of the Python Packaging User Guide. + + +Install From Source +^^^^^^^^^^^^^^^^^^^ + +.. code-block :: sh + + git clone https://github.com/greatscottgadgets/facedancer.git + cd facedancer/ + +Once you have the source code downloaded you can install the Facedancer library with: + +.. code-block :: sh + + pip install . + + + +Load Facedancer Bitstream and Firmware +-------------------------------------- + +You can load the Facedancer Bitstream and Firmware by running: + +.. code-block :: sh + + `cynthion program TODO` + +To put Cynthion back into analyzer mode you can run: + +.. code-block :: sh + + `cynthion program TODO` + +You can verify that everything is working by running: + +.. code-block :: sh + + cynthion info + +You should see output like: + +.. code-block :: sh + + TODO cynthion info output when running as moondancer + + +Connect Hardware +---------------- + +.. image:: ../images/cynthion-connections-facedancer.svg + :width: 800 + :alt: Connection diagram for using Cynthion with Facedancer. + +Make sure that the target host is running a program that can receive keyboard input such as a terminal or text editor and that it has focus. + +Run a Facedancer example +------------------------ + +Create a new Python file called ``rubber-ducky.py`` with the following content: + +.. literalinclude:: ../../cynthion/python/examples/facedancer-rubber-ducky.py + :language: python + :linenos: + +Open a terminal and run: + +.. code-block :: sh + + python ./rubber-ducky.py + +If all goes well, you should see the string ``hello, facedancer`` typed into the target host. + +More Information +---------------- + +For further information, see the `Facedancer documentation `_. diff --git a/docs/source/getting_started_packetry.rst b/docs/source/getting_started_packetry.rst new file mode 100644 index 00000000..48519bec --- /dev/null +++ b/docs/source/getting_started_packetry.rst @@ -0,0 +1,19 @@ +============================ +Using Cynthion with Packetry +============================ + +Before proceeding, please ensure you have completed all steps in the :doc:`getting_started` section. + + +Load Analyzer Bitstream +----------------------- + +TODO + + +Connect Hardware +---------------- + +.. image:: ../images/cynthion-connections-packetry.svg + :width: 800 + :alt: Connection diagram for using Cynthion with Packetry. diff --git a/docs/source/getting_started_usbproxy.rst b/docs/source/getting_started_usbproxy.rst new file mode 100644 index 00000000..52bbdb96 --- /dev/null +++ b/docs/source/getting_started_usbproxy.rst @@ -0,0 +1,37 @@ +============================= +Using Cynthion with USB Proxy +============================= + +Before proceeding, please ensure you have completed all steps in the :doc:`getting_started` and :doc:`getting_started_facedancer` sections. + + +Connect Hardware +---------------- + +.. image:: ../images/cynthion-connections-usbproxy.svg + :width: 800 + :alt: Connection diagram for using Cynthion with Facedancer. + + + +Run a USB Proxy example +----------------------- + +Create a new Python file called ``usbproxy.py`` with the following content: + +.. literalinclude:: ../../cynthion/python/examples/facedancer-usbproxy.py + :language: python + :linenos: + +Open a terminal and run: + +.. code-block :: sh + + python ./usbproxy.py + +If all goes well you should see the output from device enumeration in your terminal and the proxied USB device should be detected by the target computer. + +More Information +---------------- + +For further information, see the `Facedancer USB Proxy documentation `_. diff --git a/docs/source/hardware/bringup_guide.rst b/docs/source/hardware/bringup_guide.rst new file mode 100644 index 00000000..910574b1 --- /dev/null +++ b/docs/source/hardware/bringup_guide.rst @@ -0,0 +1,274 @@ +========================== +Self-made Hardware Bringup +========================== + +This guide is intended to help you bring up a Cynthion board you’ve built +yourself. If you’ve received your board from Great Scott Gadgets, it +should already be set up, and you shouldn’t need to follow these steps. + +Prerequisites +------------- + +- A Cynthion board with a populated *Debug Controller* microprocessor. This + is the SAMD microcontroller located in the Debug section at the + bottom of the board. When powering the board, the test points should + have the marked voltages. The FPGA LEDs might be dimly lit. +- A programmer capable of uploading firmware via SWD. Examples include + the `Black Magic + Probe `__; the `Segger + J-Link `__, and + many `OpenOCD compatible + boards `__. +- A toolchain capable of building binaries for Cortex-M0 processors, + such as the `GNU Arm + Embedded `__ + toolchain. If you’re using Linux or macOS, you’ll likely want to + fetch this using a package manager; a suitable toolchain may be + called something like ``arm-none-eabi-gcc``. +- A DFU programming utility, such as + `dfu-util `__. + +Bring-up Process +---------------- + +The high-level process for bringing up your board is as follows: + +1. Compile and upload the + `Saturn-V `__ + bootloader, which allows Debug Controller to program itself. +2. Compile and upload the + `Apollo `__ Debug + Controller firmware, which allows FPGA configuration & flashing; + and provides debug interfaces for working with the FPGA. +3. Install the ``cynthion`` tools, and run through the self-test procedures + to validate that your board is working. + +Build/upload Saturn-V +--------------------- + +The “recovery mode (RVM)” bootloader for Cynthion boards is named +*Saturn-V*; as it’s the first stage in “getting to Cynthion”. The bootloader +is located in `in its own repository `__ + +You can clone the bootloader using ``git``: + +.. code:: sh + + $ git clone https://github.com/greatscottgadgets/saturn-v + + +Build the DFU bootloader by invoking ``make``. An example invocation +for modern Cynthion hardware might look like: + +.. code:: sh + + $ cd saturn-v + $ make + +If you're building a board that predates r0.3 hardware, you'll need to specify +the board you're building for: + + +.. code:: sh + + $ cd saturn-v + $ make BOARD=luna_d21 + + +The build should yield two useful build products: ``bootloader.elf`` and +``bootloader.bin``; your SWD programmer will likely consume one of these +two files. + +Next, connect your SWD programmer to the header labeled ``uC``, and +upload bootloader image. You can use both the ports labelled +``Sideband`` and ``Main Host`` to power the board in this process. +If you’re using the Black Magic Probe, this might look like: + +.. code:: sh + + $ arm-none-eabi-gdb -nx --batch \ + -ex 'target extended-remote /dev/ttyACM0' \ + -ex 'monitor swdp_scan' \ + -ex 'attach 1' \ + -ex 'load' \ + -ex 'kill' \ + bootloader.elf + +If you are using openocd, the process might look similar to the following +(add the configuration file for your SWD adapter: + +.. code:: sh + + $ openocd -f openocd/scripts/target/at91samdXX.cfg + Open On-Chip Debugger 0.11.0-rc2 + Licensed under GNU GPL v2 + Info : Listening on port 4444 for telnet connections + Info : clock speed 400 kHz + Info : SWD DPIDR 0x0bc11477 + Info : at91samd.cpu: hardware has 4 breakpoints, 2 watchpoints + Info : at91samd.cpu: external reset detected + +.. code:: sh + + $ nc localhost 4444 + Open On-Chip Debugger + > targets + TargetName Type Endian TapName State + -- ------------------ ---------- ------ ------------------ ------------ + 0* at91samd.cpu cortex_m little at91samd.cpu reset + + > at91samd chip-erase + chip erase started + + > program Luna/saturn-v/bootloader.bin verify reset + target halted due to debug-request, current mode: Thread + xPSR: 0xf1000000 pc: 0xfffffffe msp: 0xfffffffc + ** Programming Started ** + SAMD MCU: SAMD21G18A (256KB Flash, 32KB RAM) + ** Programming Finished ** + ** Verify Started ** + ** Verified OK ** + ** Resetting Target ** + +If your programmer works best with ``.bin`` files, be sure to upload the +``bootloader.bin`` to the start of flash (address ``0x00000000``). + +Once the bootloader is installed, you should see LED ``A`` blinking +rapidly. This is the indication that your board is in Recovery Mode +(RVM), and can be programmed via DFU. + +You can verify that the board is DFU-programmable by running +``dfu-util`` while connected to the USB port labelled ``Sideband``: + +.. code:: sh + + $ dfu-util --list + dfu-util 0.9 + + Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc. + Copyright 2010-2016 Tormod Volden and Stefan Schmidt + This program is Free Software and has ABSOLUTELY NO WARRANTY + Please report bugs to http://sourceforge.net/p/dfu-util/tickets/ + + Found DFU: [1d50:615c] ver=0000, devnum=22, cfg=1, intf=0, path="2-3.3.1.2", alt=1, name="SRAM" + Found DFU: [1d50:615c] ver=0000, devnum=22, cfg=1, intf=0, path="2-3.3.1.2", alt=0, name="Flash" + +If your device shows up as a Cynthion board, congratulations! You’re ready +to move on to the next step. + +Optional: Bootloader Locking +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Optionally, you can reversibly lock the bootloader region of the Debug +Controller, preventing you from accidentally overwriting the bootloader. +This is most useful for users developing code for the Debug Controller. + +If you choose to lock the bootloader, you should lock the first ``2KiB`` +of flash. Note that currently, the bootloader lock feature of *Black +Magic Probe* devices always locks ``8KiB`` of flash; and thus cannot be +used for Cynthion. + +Build/upload Apollo +------------------- + +The next bringup step is to upload the *Apollo* Debug Controller +firmware, which will provide an easy way to interface with the board’s +FPGA and any gateware running on it. The Apollo source is located +`in its own repository `__. + +You can clone the bootloader using `git`: + +.. code:: sh + + $ git clone --recurse-submodules https://github.com/greatscottgadgets/apollo + + + +You can build and run the firmware in one step by invoking +``make``. In order to ensure your firmware matches the hardware it’s +running on, you’ll need to provide board type and hardware revision +using the ``APOLLO_BOARD``, ``BOARD_REVISION_MAJOR`` and +``BOARD_REVISION_MINOR`` make variables. + +The board’s hardware revision is printed on its silkscreen in a +``r(MAJOR).(MINOR)`` format. Board ``r1.4`` would have a +``BOARD_REVISION_MAJOR=1`` and a ``BOARD_REVISION_MINOR=4``. If your +board’s revision ends in a ``+``, do not include it in the revision +number. + +An example invocation for a ``r1.4`` board might be: + +.. code:: sh + + $ make APOLLO_BOARD=cynthion BOARD_REVISION_MAJOR=1 BOARD_REVISION_MINOR=4 dfu + +Once programming is complete, LED's ``A``, ``B``, ``C``, ``D`` and ``E`` should all be on; +indicating that the Apollo firmware is idle. + +You can also upload a firmware binary using `dfu-util` with: + +.. code:: sh + + $ dfu-util -d 1d50:615c -D firmware.bin + + +Running Self-Tests +------------------ + +The final step of bringup is to validate the functionality of your +hardware. This is most easily accomplished by running Cynthion’s interactive +self-test applet. + +Before you can run the applet, you’ll need to have a working +``cynthion`` development environment. See +:doc:`../developer/introduction` to get your environment set up. + +Next, we can check to make sure your Cynthion board is recognized by the +Cynthion toolchain. Running the ``apollo info`` command will list any +detected devices: + +.. code:: sh + + $ apollo info + Detected a Cynthion device! + Hardware: Cynthion r1.4 + Serial number: + +Once you’ve validated connectivity, you’re ready to try running the +``cynthion selftest`` command. + +.. code:: sh + + $ cynthion selftest + + INFO | __init__ | Building and uploading gateware to attached Cynthion r1.4... + INFO | __init__ | Upload complete. + INFO | selftest | Connected to onboard debugger; hardware revision r1.4 (s/n: ). + INFO | selftest | Running tests... + + Automated tests: + Debug module: ✓ PASSED + AUX PHY: ✓ PASSED + HyperRAM: ✓ PASSED + CONTROL PHY: ✓ PASSED + TARGET PHY: ✓ PASSED + +Troubleshooting +--------------- + +**Issue: some of the build files weren't found;** ``make`` **produces a message like "** ``no rule to make target`` **".** + +Chances are, your clone of Apollo was pulled down without its +submodules. You can pull down the relevant submodules using ``git``: + +.. code:: sh + + $ git submodule update --init --recursive + +**Issue: the ``apollo info`` command doesn't see a connected board.** + +On Linux, this can be caused by a permissions issue. Check first for the +presence of your device using ``lsusb``; if you see a device with the +VID/PID ``1d50:615c``, your board is present – and you likely have a +permissions issue. You’ll likely need to install permission-granting +udev rules. diff --git a/docs/source/hardware/introduction.rst b/docs/source/hardware/introduction.rst new file mode 100644 index 00000000..c98cf032 --- /dev/null +++ b/docs/source/hardware/introduction.rst @@ -0,0 +1,10 @@ +============ +Introduction +============ + +.. image:: ../../images/cynthion_hardware.jpg + :alt: Cynthion PCB (Front) + + +Cynthion Hardware +------------------ diff --git a/docs/source/index.rst b/docs/source/index.rst index c27f16bc..54718fd3 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -2,9 +2,40 @@ Cynthion Documentation ====================== +.. image:: ../images/cynthion.jpg + :width: 400 + :alt: Cynthion + .. toctree:: :maxdepth: 2 :caption: User Documentation - getting_help - cynthion_project_mentions \ No newline at end of file + introduction + getting_started + getting_started_packetry + getting_started_facedancer + getting_started_usbproxy + +.. toctree:: + :maxdepth: 2 + :caption: Cynthion Hardware + + hardware/introduction + hardware/bringup_guide + +.. toctree:: + :maxdepth: 2 + :caption: Support + + support/getting_help + support/project_mentions + support/safety_information + +.. toctree:: + :maxdepth: 2 + :caption: Developer Documentation + + developer/introduction + developer/bitstream_generation + developer/soc_firmware_compilation + developer/cli diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst new file mode 100644 index 00000000..ee0cb6e1 --- /dev/null +++ b/docs/source/introduction.rst @@ -0,0 +1,90 @@ +============ +Introduction +============ + +What is Cynthion? +----------------- + +Cynthion is an all-in-one tool for building, testing, monitoring, and experimenting with USB devices. Built around a unique FPGA-based architecture, Cynthion’s digital hardware can be fully customized to suit the application at hand. As a result, it can act as a no-compromise High-Speed USB protocol analyzer, a USB-hacking multi-tool, or a USB development platform. + +Out-of-the-box, Cynthion acts as a USB protocol analyzer capable of capturing and analyzing traffic between a host and any Low-, Full-, or High-Speed ("USB 2.0") USB device. It works seamlessly with our `Packetry `__ open-source analysis software. + +Combined with our `LUNA `__ gateware and `Facedancer `__ libraries, Cynthion becomes a versatile USB-hacking and development tool. Facedancer makes it quick and easy to create or tamper with real USB devices—not just emulations—even if you don’t have experience with digital hardware design, HDL, or FPGA architecture! + + +Device Overview +--------------- + + +Top View +~~~~~~~~ + +.. image:: ../images/cynthion-top.svg + :width: 300 + :alt: Cynthion Top View + +- **A-E** - Five status LEDs managed by the debug microcontoller. + + - **A** - Power Indicator. + - **B** - FPGA is online. + - **C** - FPGA has requested control of the **CONTROL** port. + - **D** - FPGA has control of the **CONTROL** port. + - **E** - Reserved for future use. + +- **0-5** - Six user LEDs connected to the FPGA + + +Left View +~~~~~~~~~ + +.. image:: ../images/cynthion-left.svg + :width: 400 + :alt: Cynthion Left View + +- **PROGRAM** - Press this button to return control of the **CONTROL** port to the debug microcontroller and hold the FPGA in an unconfigured state. + + - *Recovery mode*: Press this button during power-on to invoke the `Saturn-V `__ bootloader on the **CONTROL** port. + +- **CONTROL** - Primary USB connector used by the host computer to control Cynthion. +- **USER** - A user-assignable button that can be used in your own designs. +- **AUX** - An auxiliary USB connection that can be used in your own designs. + + +Right View +~~~~~~~~~~ + +.. image:: ../images/cynthion-right.svg + :width: 400 + :alt: Cynthion Right View + +- **TARGET C** - USB Type-C connector for Packetry traffic capture and Facedancer device emulation. +- **TARGET A** - USB Type-A connector shared with the **TARGET C** connector. +- **RESET** - Press this button to reset Cynthion's debug microcontroller and reconfigure the FPGA from flash. + + +Front View +~~~~~~~~~~ + +.. image:: ../images/cynthion-front.svg + :width: 400 + :alt: Cynthion Front View + +- **A & B** - Two Digilent Pmod™ Compatible I/O connectors for a total of 16 high-speed FPGA user IOs. + + - **B** can also be configured to act as a serial port and JTAG connector for debugging SoC designs: + + - **1** - SERIAL RX + - **2** - SERIAL TX + - **7** - JTAG TMS + - **8** - JTAG TDI + - **9** - JTAG TDO + - **10** - JTAG TCK + + + +Bottom View +~~~~~~~~~~~ + +.. image:: ../images/cynthion-bottom.svg + :width: 300 + :alt: Cynthion Bottom View diff --git a/docs/source/getting_help.rst b/docs/source/support/getting_help.rst similarity index 100% rename from docs/source/getting_help.rst rename to docs/source/support/getting_help.rst diff --git a/docs/source/cynthion_project_mentions.rst b/docs/source/support/project_mentions.rst similarity index 100% rename from docs/source/cynthion_project_mentions.rst rename to docs/source/support/project_mentions.rst diff --git a/docs/source/support/safety_information.rst b/docs/source/support/safety_information.rst new file mode 100644 index 00000000..7376542d --- /dev/null +++ b/docs/source/support/safety_information.rst @@ -0,0 +1,45 @@ +================== +Safety Information +================== + +Warnings +-------- + +* This product shall only be connected to an external power supply + rated at 5 V DC. Any power supply used with this product shall + comply with relevant regulations and standards applicable in the + country of intended use. +* This product should be used in a shielded enclosure. Removing this + product from its enclosure or using this product without a shielded + enclosure may expose it to additional risks of damage. Extra care + should be taken to prevent damage from electrostatic discharge and + impact damage when this product is removed from its enclosure or + used without a shielded enclosure. +* This product should only be connected to another device that is + rated to be used at the power level this device is configured to + provide. Attaching this product to another device that is not rated + to be used at the power level that this device is configured to + provide may result in damage. + +Instructions For Safe Use +------------------------- + +* Do not expose this product to water or moisture. +* Do not expose this product to excessive heat while in use. +* Do not place undue stress on any connector port. +* Any equipment connected to Cynthion should comply with relevant + standards for the country of use and be marked accordingly to ensure + that safety and performance requirements are met. +* Do not allow equipment connected to Cynthion to make contact with + any internal component of Cynthion other than a connector. +* A pass-through power supply connected to Cynthion must supply at + least 5 V DC and no more than 20 V DC. The pass-through power supply + must be rated for the current drawn by the pass-through device + connected to Cynthion. +* A device connected to Cynthion must be rated for 5 V DC or the + pass-through power supply voltage and must draw no more than 3 A + current from the pass-through power supply or 500 mA current from + Cynthion’s power supply. +* Use USB cables of no more than 2 m length with Cynthion. +* Do not expose Pmod or mezzanine connectors to voltages greater than + 3.3 V.