im-tomu / fomu-workshop

Support files for participating in a 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, how to write software for Fomu and finally how to write hardware 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 workshop.fomu.im.

Repository Contents

• docs - The actual workshop directions and content.
• hdl
  • verilog - The files required for the Verilog on Fomu section of the workshop.
  • vhdl - The files required for the VHDL on Fomu section of the workshop.
  • mixed - The files required for the Mixed HDL on Fomu section of the workshop.
• icestudio - The files required for the Fomu on IceStudio Nightly section of the workshop.
• litex, migen - The files required for the Migen and LiteX section of the workshop.
• reference - Extra reference documentation such as schematics and part datasheets.
• riscv
  • riscv-blink - The files required for the Fomu as a CPU section of the workshop.
  • riscv-rust-blink - The files required for the Fomu as a CPU, Using Rust section of the workshop.

Development

For guidelines about how to develop the workshop or how to build the workshop locally, see DEVELOPMENT.

fomu-workshop's Issues

Risc-V communication with host

Is there any abstraction layer to make a serial communication between the fomu and the host pc? I have been taking a look at the implementation that is used at the micropython port, but it is a bit too low level.

Expand the SPI flash ID section

https://github.com/im-tomu/fomu-workshop/blob/master/Workshop.md#fomu-with-python

>>> spi = fomu.spi()
>>> hex(spi.id())
'0xc2152815'
>>> 

Info at;
https://github.com/im-tomu/fomu-flash/blob/c24ffda85ba5d2a11cee0358831930fbd16c94cc/spi.c#L560-L598

static void spi_decode_id(struct ff_spi *spi) {


	spi->id.manufacturer = "unknown";
	spi->id.model = "unknown";
	spi->id.capacity = "unknown";
	spi->id.bytes = -1; // unknown


	if (spi->id.manufacturer_id == 0xc2) {
		spi->id.manufacturer = "Macronix";
		if ((spi->id.memory_type == 0x28)
		 && (spi->id.memory_size == 0x15)) {
			spi->id.model = "MX25R1635F";
			spi->id.capacity = "16 Mbit";
			spi->id.bytes = 2 * 1024 * 1024;
		}
	}


	if (spi->id.manufacturer_id == 0xef) {
		spi->id.manufacturer = "Winbond";
		if ((spi->id.memory_type == 0x70)
		 && (spi->id.memory_size == 0x18)) {
			spi->id.model = "W25Q128JV";
			spi->id.capacity = "128 Mbit";
			spi->id.bytes = 16 * 1024 * 1024;
		}
	}


	if (spi->id.manufacturer_id == 0x1f) {
		spi->id.manufacturer = "Adesto";
		 if ((spi->id.memory_type == 0x86)
		  && (spi->id.memory_size == 0x01)) {
			spi->id.model = "AT25SF161";
			spi->id.capacity = "16 Mbit";
			spi->id.bytes = 1 * 1024 * 1024;
		}
	}


	return;
}

Add a "what Fomu do I have" section?

There are multiple Fomu devices. It would be good to have a section which lets you figure out which device you have.

where to get the missing /usr/share/icebox/ice40/chipdb-384.bin

Hi, i'm trying to package all the fomu deps for alpine linux, i managed to compile icestorm, yosys and nextpnr, to verify if everything is ok, i try to run the workshop like this, however when i run python3 workshop.py --board hacker i get this:

ERROR: Unable to read chipdb /usr/share/icebox/ice40/chipdb-384.bin
0 warnings, 1 error
Traceback (most recent call last):
  File "workshop.py", line 132, in <module>
    main()
  File "workshop.py", line 126, in main
    vns = builder.build()
  File "/home/s/tasks/fomu/fomu-workshop/litex/deps/litex/litex/soc/integration/builder.py", line 180, in build
    toolchain_path=toolchain_path, **kwargs)
  File "/home/s/tasks/fomu/fomu-workshop/litex/deps/litex/litex/soc/integration/soc_core.py", line 461, in build
    return self.platform.build(self, *args, **kwargs)
  File "/home/s/tasks/fomu/fomu-workshop/litex/deps/litex/litex/build/lattice/platform.py", line 29, in build
    return self.toolchain.build(self, *args, **kwargs)
  File "/home/s/tasks/fomu/fomu-workshop/litex/deps/litex/litex/build/lattice/icestorm.py", line 183, in build
    _run_script(script)
  File "/home/s/tasks/fomu/fomu-workshop/litex/deps/litex/litex/build/lattice/icestorm.py", line 64, in _run_script
    raise OSError("Subprocess failed")
OSError: Subprocess failed

i've been looking everywhere but could not find either a matching .bin file, nor a make rule that generates these .bin files. what am i missing?

Is it worth mentioning LUT / Distributed RAM?

The iCE40 doesn't have any, but most other FPGAs do.

Fix link to ICE40 LED docs

The page https://workshop.fomu.im/en/latest/python.html has a link at the bottom to https://workshop.fomu.im/en/latest/reference/FPGA-TN-1288-ICE40LEDDriverUsageGuide.pdf which is dead.

make error using Fomu Toolchain

Attempting to build either riscv-blink or riscv-usb-cdcacm using the Fomu Toolchain gives the following error:

riscv64-unknown-elf-gcc: error trying to exec ‘cc1’: execvp: No such file or directory

The toolchain bin directory is at the start of $PATH, so it is calling the correct binaries. This is using release v1.3 of said toolchain and is on macOS 10.14.6. Not been able to compare on other platforms yet.

Add a rust section to the CPU bit

Rust is cool. Rust on RISC-V is cool. Would be awesome to demonstrate it on Fomu!

dfu fails

dfu-util.exe -D micropython-fomu.dfu

fails at 36%
dfuerror status(8)

:(

Fix: evt and prod reference schematics should be valid PDF

It seems something went wrong with the update of the reference schematics on f5cc2b1. Namely:
https://github.com/im-tomu/fomu-workshop/blob/master/reference/schematic-evt.pdf and https://github.com/im-tomu/fomu-workshop/blob/master/reference/schematic-prod.pdf

The files actually contain an HTML error page "You can’t perform that action at this time." instead of PDF. e.g. https://raw.githubusercontent.com/im-tomu/fomu-workshop/f5cc2b1188ab0cf3a80cd949b6df26f0510bc6dd/reference/schematic-prod.pdf.

Sorry, I'm not yet confident enough to find the right sources to send a PR instead of an issue.

Link to fomu-toolchain fails

https://github.com/im-tomu/fomu-toolchain

In the required software section is broken.

https://github.com/im-tomu/fomu-workshop/blob/master/README.md#required-software

Explain a LUT is N inputs to 1 output

And the iCE40 uses 4-input LUTs

Add instructions on how to update to foboot 2.0.3

foboot 2 series is a major upgrade in the bootloader. The workshop should start by telling people to upgrade the bootloader.

Add picture of PVT hardware in case.

Fix the broken image in the "Require Hardware".

LLVM support

It looks like there's LLVM support for RISC-V, which should allow using clang, Rust, TinyGO.
Maybe someone played with LLVM already and can share experience / how to get started with this?
Thanks!

Add gitignore for people who have extracted toolchain in workshop directory

As reported by @tatzelbrumm

Future: Add section on writing your own PWM LED controller

The obvious first peripheral for someone on the Fomu to write is something which does hardware offload of the LED control and implements something like PWM exposed as CSRs.

Can get really complicated with non-linear ramps (breathe effects) etc.

Covering more topics

This is a very nice write-up, thanks! Great explanations, as well as a getting-started guide.
Considering the OSS/OSH aspect of this project, it would be also great to extend this (or possibly organize a separate one) with such ground-up topics:

• How to build the Lattice toolchain
• How to build/flash the bootloader
• How to get the softcore source and how to build it
• How to build micropython
• ...

P.S. It's a good idea to show how a simple modification/extension can be made in each of the components (like you did). I believe it's an important part for building a healthy developer community around Fomu.

wishbone-tool shows occasional BridgeError

In the litex/workshop.py and litex/workshop_rgb.py examples, I often have to retry reads and writes via the wishbone-tool to work around BridgeError(USBError(Pipe)). This is happening on box Linux and OSX for me.

Have others experienced similar reliability challanges?

$ dfu-util -D build/gateware/top.dfu 
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/

Match vendor ID from file: 5bf0
Match product ID from file: 1209
Opening DFU capable USB device...
ID 1209:5bf0
Run-time device DFU version 0101
Claiming USB DFU Interface...
Setting Alternate Setting #0 ...
Determining device status: state = dfuIDLE, status = 0
dfuIDLE, continuing
DFU mode device DFU version 0101
Device returned transfer size 1024
Copying data from PC to DFU device
Download	[=========================] 100%       104090 bytes
Download done.
state(7) = dfuMANIFEST, status(0) = No error condition is present
state(8) = dfuMANIFEST-WAIT-RESET, status(0) = No error condition is present
Done!

$ wishbone-tool 0x10000000
INFO [wishbone_tool::usb_bridge] opened USB device device 008 on bus 020
ERROR [wishbone_tool] server error: BridgeError(USBError(Pipe))
INFO [wishbone_tool::usb_bridge] waiting for target device
^C

$ wishbone-tool 0x10000000
INFO [wishbone_tool::usb_bridge] opened USB device device 008 on bus 020
Value at 10000000: 4019c91a

$ wishbone-tool 0x10000000 1
INFO [wishbone_tool::usb_bridge] opened USB device device 008 on bus 020
ERROR [wishbone_tool] server error: BridgeError(USBError(Pipe))
INFO [wishbone_tool::usb_bridge] waiting for target device
^C

$ wishbone-tool 0x10000000 1
INFO [wishbone_tool::usb_bridge] opened USB device device 008 on bus 020
ERROR [wishbone_tool] server error: BridgeError(USBError(Pipe))
INFO [wishbone_tool::usb_bridge] waiting for target device
^C

$ wishbone-tool 0x10000000 1
INFO [wishbone_tool::usb_bridge] opened USB device device 008 on bus 020
ERROR [wishbone_tool] server error: BridgeError(USBError(Pipe))
INFO [wishbone_tool::usb_bridge] waiting for target device
^C

$ wishbone-tool 0x10000000 1
INFO [wishbone_tool::usb_bridge] opened USB device device 008 on bus 020
ERROR [wishbone_tool] server error: BridgeError(USBError(Pipe))
INFO [wishbone_tool::usb_bridge] waiting for target device
^C

$ wishbone-tool 0x10000000 1
INFO [wishbone_tool::usb_bridge] opened USB device device 008 on bus 020

$ wishbone-tool 0x10000000 
INFO [wishbone_tool::usb_bridge] opened USB device device 008 on bus 020
ERROR [wishbone_tool] server error: BridgeError(USBError(Io))
INFO [wishbone_tool::usb_bridge] waiting for target device
^C

$ wishbone-tool 0x10000000 
INFO [wishbone_tool::usb_bridge] opened USB device device 008 on bus 020
Value at 10000000: 00000001

Block diagram has SPRAM mislabelled as PSRAM

This diagram: https://github.com/im-tomu/fomu-workshop/blob/master/img/fomu-block-diagram.png

It's SPRAM in the surrounding text but PSRAM in the ICE40 block on the diagram.

Add section on checking /dev/ttyACM permissions

Lots of people were getting stuck with not having permissions to access the /dev/ttyACM device due to not being in the dialout group.

Can't open serial port on Linux unless VID/PID are manually bound to serial driver

I couldn't get the provided MicroPython firmware to work at first. It seemed to flash fine, but afterwards no /dev/ttyACM* were created. I thought I didn't have the right USB serial driver before I realized the USB VID/PID pair for "Generic Fomu Micropython v1.10-298-g6f94468" just wasn't registered with any USB serial driver.

Once I figured that out, I manually added it to the generic (ftdi_sio appears to work too) USB serial driver:

# lsusb
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
---- 8< ----
Bus 001 Device 006: ID 1209:5bf0 Generic Fomu Micropython v1.10-298-g6f94468
# echo 1209 5bf0 > /sys/bus/usb-serial/drivers/generic/new_id

Once the driver picked it up (i.e. it was unplugged and plugged back in) it worked fine.

A hacker's solution would be to use a VID/PID the kernel already knows about (which obviously won't fly on a production release). A better solution would be to get 1209:5bf0 added to this list. However, other Fomu applications that use the default VID/PID and don't emulate a USB serial port might not appreciate this driver taking over by default.

P.S: I've only ever seen /dev/ttyACM* when a "real" hardware serial port is behind it; using the USB serial driver with Fomu on Linux results in a device file named /dev/ttyUSB*. If that's not just my weird system configuration the instructions should be changed to match.

Broken image at top of workshop.md

USB with bridge has weird output

Issues;

• Product: Fomu Bridg -- Missing e?
• can't set config #1, error -71?

[286448.555178] usb 1-2: USB disconnect, device number 8
[286448.902061] usb 1-2: new full-speed USB device number 9 using xhci_hcd
[286449.051394] usb 1-2: New USB device found, idVendor=1209, idProduct=5bf0, bcdDevice= 1.01
[286449.051397] usb 1-2: New USB device strings: Mfr=1, Product=2, SerialNumber=0
[286449.051399] usb 1-2: Product: Fomu Bridg
[286449.051401] usb 1-2: Manufacturer: Foos
[286449.051686] usb 1-2: can't set config #1, error -71

Future: Have section showing Renode emulation of Fomu platform.

@mgielda

Make the names in each row of the required software table links

Any way to auto-start?

Currently it requires running dfu-util -e to detach the DFU interface and start the previously loaded program.
It would be good to have a way of auto-starting the program, i.e. automatically detaching after 5 seconds, or maybe some other ways.

Add License

There is no license in the sources.

"wishbone-tool -s gdb" fails

Following the workshop I cannot get the gdb step working on my machine (Win10 laptop).
dfu-util with the (modified) blink C example works, but the wishbone-tools afterwards fails.

C:\fomu\fomu-workshop\riscv-blink>dfu-util -D riscv-blink.bin
dfu-util 0.9

Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
Copyright 2010-2019 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/

Invalid DFU suffix signature
A valid DFU suffix will be required in a future dfu-util release!!!
Opening DFU capable USB device...
ID 1209:5bf0
Run-time device DFU version 0101
Claiming USB DFU Interface...
Setting Alternate Setting #0 ...
Determining device status: state = dfuIDLE, status = 0
dfuIDLE, continuing
DFU mode device DFU version 0101
Device returned transfer size 1024
Copying data from PC to DFU device
Download        [=========================] 100%          832 bytes
Download done.
state(7) = dfuMANIFEST, status(0) = No error condition is present
state(8) = dfuMANIFEST-WAIT-RESET, status(0) = No error condition is present
Done!

C:\fomu\fomu-workshop\riscv-blink>wishbone-tool -s gdb
INFO [wishbone_tool::usb_bridge] opened USB device device 001 on bus 001
INFO [wishbone_tool::usb_bridge] waiting for target device
�[1;38;5;196mERROR�[0m [wishbone_tool] �[1;38;5;196mserver error: RiscvCpuError(BridgeError(USBError(NotFound)))�[0m

Add Required Hardware section

Make the minimal verilog actually minimal

Convert the file at https://github.com/im-tomu/fomu-workshop/blob/master/verilog-blink-minimal/blink.v to be more minimal.

• Remove the usage of the PLL, use a counter instead.
• Directly drive the pins rather than SB_RGBA_DRV

Would be nice to have the block diagram go with a photo

The photo of an actual Fomu can show the parts map to the block diagram. See https://opsis.hdmi2usb.tv/getting-started/overview.html

Future: Have an example of running Zephyr

Upstream Zephyr is getting good LiteX support, hence it would make a pretty good RTOS demo.

Add CircuitPython instructions

@xobs got Circuit Python working on the Fomu with tinyusb. We should add it to the workshop.

Micropython demo functionally unusable on Chrome OS via Crostini

Due to a (probable) bug in Chrome OS USB device handling, there is a crossvm state machine issue that prevents the fomu serial console from being usable after DFU flashing the micropython demo binary.

This issue is currently being tracked at https://bugs.chromium.org/p/chromium/issues/detail?id=996197

Explain where the generated Fomu files are and where they come from

"If we look at the generated Fomu header files, we can see many, many memory-mapped registers. For example, the major, minor, and revision numbers all have registers:"

This fragment refers to such files but they are never mentioned earlier. Minor thing, but worth fixing.

litex build usb does not emumerate

Using the fomu from camp
steps to reproduce:

cd litex
python3 workshop.py --lx-check-git --board hacker
dfu-util -D build/gateware/top.bin

dmesg output:
https://gist.github.com/yorickvP/c1500a88f424861d7a69a98177648b3c

Human readable Makefile versions

I'm not too familiar with make.
I want to read
fomu/verilog-blink/Makefile
to understand the Verilog-to-uploaded binary design flow.

However, the Makefile contains about 65 lines of variable substitutions, abstractions and generalizations.
I would appreciate a human readable Makefile with no variable substitutions whatsoever,
so that each line in the Makefile is self-contained, and I do not have to jump to 5 lines of previous definitions, abstractions, and generalizations.

Abstraction layers are evil.
They obfuscate more than they help.

verilog blink minimal make error

Below is an error I get when trying to make verilog blink minimal. Regular verilog blink does work however. What is a compiler directive and why is it missing?

Yosys c7f1368cd273f1d84507d29548f3420a08a82702 (Fomu build) (git sha1 ecdc4d8, gcc 7.4.0-1ubuntu1~18.04.1 -fPIC -Os)

-- Parsing blink.v' using frontend verilog' --

1. Executing Verilog-2005 frontend: blink.v
   Parsing Verilog input from blink.v' to AST representation. blink.v:119: ERROR: Unimplemented compiler directive or undefined macro BLUEPWM.
   Makefile:14: recipe for target 'blink.json' failed
   make: *** [blink.json] Error 1

Add some pictures of hardware

A picture is worth a thousand words :-)

Some nice pictures of the board. Maybe a gif of the blinking, etc would be nice.

Shell confusion with make on Windows

Cohabitation with cygwin caused make shell confusion. Workaround to make riscv-blink was to perform "make SHELL=cmd.exe"

Improve the GDB debugging session output

It would be good to improve the GDB debugging sessions in the workshop.

• It would be good to have a pygments Lexer for GDB
• Demonstrate connecting to Fomu.
• Demonstrate connecting to Renode.
• Demonstrate loading programs directly into memory.
• Demonstrate loading programs debug symbols.
• Demonstrate setting breakpoints and then resuming.
• Demonstrate single stepping.

Serial port doesn't appear on macOS 10.14.6

After successfully loading micropython-fomu.dfu onto Fomu (and once the LED starts pulsing red) it does not show up as a /dev/cu.* or /dev/tty.* device.

No additional serial drivers are installed. Reproduced on two devices - one connecting straight to a USB-A interface, the other to USB-C via an adapter.

Make Workshop.md the README.md file

This just tripped me up right then :-)

Add USB to the bridge diagram

Something like the following;

How to reset to RISCV state after verilog update without unplugging

If I want to jump back from the

Hardware Description Languages

section,

is there a way to get the FOMU back to the configuration needed for the

Python on FOMU

or

FOMU as a CPU

chapters without prying the FOMU out of the USB port or turning the host computer on and off?

Future: Have section on using Renode + USB bridge

Run the RISC-V on your computer and a peripheral on the Fomu connected over the wishbone USB bridge.

can I --download while something else is running?

https://workshop.fomu.im/#loading-binaries
shows

dfu-util -D file.dfu
...
To restart Fomu, unplug it and plug it back in. This will start the bootloader. To run the program on Fomu without needing to load it again, use the -e option:

is "restart Fomu" and "run the program on Fomu" the same thing?

The way I read that is: "unplug it and plug it back in" is the same as "use the -e option" but I am very not sure.

Convert the workshop to use Sphinx

Converting the workshop to sphinx will allow us to further improve the workshop and;

• Include wavedrom diagrams
• Include links to other sphinx repositories like lxsocdoc and similar
• Include and highlight specific lines of code
• Auto generate diagrams from Verilog
• etc....

Migen and LiteX workshop section doesn't remind the user to specify the board type

In the Migen and LiteX section, the user is instructed to run:

$ python3 workshop.py --board hacker

There should probably be a comment somewhere mentioning that 'hacker' needs to be replaced with a board-specific value.