Fomu Workshop

Hi, I'm Fomu! This workshop covers the basics of Fomu in a top-down approach. We'll start out by learning what Fomu is, how to load software into Fomu, and finally how to write software for Fomu.

FPGAs are complex, weird things, so we'll take a gentle approach and start out by treating it like a Python interpreter first, and gradually peel away layers until we're writing our own hardware registers. You can take a break at any time and explore! Stop when you feel the concepts are too unfamiliar, or plough on and dig deep into the world of hardware.

The contents of this workshop is published at https://workshop.fomu.im

Repository Contents

• docs - The actual workshop directions and content.
• litex - The files required for the Migen / LiteX section of the workshop.
• reference - Extra reference documentation such as schematics and part datasheets.
• riscv-blink - The files required for the Fomu as a RISC-V CPU section of the workshop.
• verilog - The files required for the Verilog on Fomu section of the workshop.

Developing the Workshop

The workshop is written in reStructuredText (rst) and generated using Sphinx.

It is hosted on Read The Docs and currently uses the Material Design style developed by Google through a slightly custom version of the sphinx_materialdesign_theme package.

It uses the sphinxcontrib-session extension to properly highlight the example sessions and to allow copying only the session lines.

Other sphinx extensions which are used include;

• sphinxcontrib-hdl-diagrams to generate nice diagrams from Verilog examples.
• sphinx-wavedrom to generate nice waveform diagrams. sphinxcontrib-wavedrom?
• symbolator to generate block level diagrams from Verilog examples.
• sphinx_tabs to support tabs for different Linux / Windows / Mac OS X instructions.

Useful Resources for writing docs

• Sphinx RestructuredText Primer
• ReStructuredText directives
• Material Design Icons

Building Workshop Locally

On Mac & Linux

$ cd docs

Download conda environment with Python utilities:

$ make env
rm -rf env
make _download/Miniconda3-latest-Linux-x86_64.sh
make[1]: Entering directory '~/fomu-workshop/docs'
mkdir env
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O _download/Miniconda3-latest-Linux-x86_64.sh
--2020-01-03 10:15:07--  https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
Resolving repo.anaconda.com (repo.anaconda.com)... 104.16.131.3, 104.16.130.3, 2606:4700::6810:8203, ...
Connecting to repo.anaconda.com (repo.anaconda.com)|104.16.131.3|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 71785000 (68M) [application/x-sh]
Saving to: ‘_download/Miniconda3-latest-Linux-x86_64.sh’

_download/Miniconda3-latest-Linux-x86_64.sh                100%[==================>]  68.46M  1.29MB/s    in 17s

2020-01-03 10:15:29 (3.98 MB/s) - ‘_download/Miniconda3-latest-Linux-x86_64.sh’ saved [71785000/71785000]

chmod a+x _download/Miniconda3-latest-Linux-x86_64.sh
make[1]: Leaving directory '~/fomu-workshop/docs'
_download/Miniconda3-latest-Linux-x86_64.sh -p ~/fomu-workshop/docs/env -b -f
PREFIX=~/fomu-workshop/docs/env
Unpacking payload ...
Collecting package metadata (current_repodata.json): done
Solving environment: done

## Package Plan ##

  environment location: ~/fomu-workshop/docs/env

  added / updated specs:
    - _libgcc_mutex==0.1=main
    - asn1crypto==1.2.0=py37_0
    - ca-certificates==2019.10.16=0

<snip>

tk-8.6.10            | 3.2 MB    | ########################### | 100%
_libgcc_mutex-0.1    | 2 KB      | ########################### | 100%
xorg-libsm-1.2.3     | 25 KB     | ########################### | 100%
requests-2.22.0      | 84 KB     | ########################### | 100%
harfbuzz-2.4.0       | 1.5 MB    | ########################### | 100%
conda-package-handli | 942 KB    | ########################### | 100%
Preparing transaction: done
Verifying transaction: done
Executing transaction: done

Install dependencies:

$ pip install -r requirements.txt

Build the html output:

$ make html
Running Sphinx v2.3.1
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 21 source files that are out of date
updating environment: [config changed ('version')] 15 added, 0 changed, 6 removed
reading sources... [100%] verilog
writing output... [100%] verilog
copying images... [100%] _static/wishbone-usb-debug-bridge.png
copying static files... ... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 15 warnings.

The HTML pages are in _build/html.
Copying tabs assets

Start your web browser:

$ xdg-open ./_build/html/index.html

On Windows

FIXME: @xobs to add instructions here.