Introduction

Last year (2017) I bought a Numato Mimas v2 with the intention of running MicroPython on it. After a bit of guess work and some assistance on IRC, I managed to get MicroPython running on Mimas V2 (Spartan-6) FPGA.

A lot has changed in the 9 months since that original blog post, including:

So it seemed worth summarising the current build process for both FPGA MicroPython (FμPy) on the Numato Mimas v2 and also the Digilent Arty A7 in one place.

The process below has been tested on an Ubuntu 16.04 LTS x86_64 system, as with the previous build process last year.

USB Mode Switch udev rules

The Digilent Arty A7 benefits from the timvideos USB Mode Switch udev rules. So it is useful to install these before starting if you will be targetting the Arty A7:

git clone https://github.com/timvideos/HDMI2USB-mode-switch.git
cd HDMI2USB-mode-switch/udev
make install
sudo udevadm control --reload-rules

And also to ensure that your user has permission to access the relevant device files:

sudo adduser $USER video
sudo adduser $USER dialout
sudo reboot

(it may be sufficient to log out/log in again to pick up the relevant additional group permissions, but rebooting will ensure udev, etc, also have the updated configuration files active).

(The Numato Mimas v2 has a physical switch to move instead of relying on USB mode switching, so the above udev rules should not be needed if you are only working with a Numato Mimas v2.)

Downloading the build environment repository

To get the top level repository used for building, run, eg:

cd /src
git clone https://github.com/timvideos/litex-buildenv.git

(If you check it out in a different directory use that directory instead of cd /src/litex-buildenv below.)

This repository is common to both the Numato Mimas v2 (Spartan-6) and the Digilent Arty A7 (Artix-7), but contains both several git submodules referencing other git repositories (some slightly different between the two platforms) as well as a lot of conda install instructions to install relevant tools (again some slightly different between the two platforms).

Numato Mimas v2

The Numato Mimas v2 is a based around a Xilinx Spartan-6 FPGA, which uses the Xilinx ISE WebPACK proprietary FPGA synthesis software. The zero-cost "ISE WebPACK" license is sufficient for this process.

These instructions Assam you have:

Preparation

To get started building FPGA MicroPython for the Numato Mimas v2, start in the timvideos/litex-buildenv cloned above:

cd /src/litex-buildenv

and then configure the build targets:

CPU=lm32
PLATFORM=mimasv2
TARGET=base
FIRMWARE=micropython

export CPU PLATFORM TARGET FIRMWARE

Once this is done, download the other bits of the build environments required for the Numato Mimas v2:

scripts/download-env.sh

And then when that finishes, enter the build environment ready to build gateware and firmware for the Numato Mimas v2:

source scripts/enter-env.sh

All going well you should now have a prompt which begins with "(LX P=mimasv2 F=micropython)" (since the lm32 CPU is the default, as is the base TARGET). If anything is reported missing you may need to run scripts/download-env.sh again, or ensure that you have the Xilinx ISE WebPACK installed and reachable from /opt/Xilinx.

Once you have completed scripts/download-env.sh one time, you can then skip that step in later sessions, just doing:

cd /src/litex-buildenv
CPU=lm32
PLATFORM=mimasv2
TARGET=base
FIRMWARE=micropython
export CPU PLATFORM TARGET FIRMWARE
source scripts/enter-env.sh

to get started in a new terminal session.

Building the gateware and micropython for the Numato Mimas v2

To build the required gateware (FPGA configuration, including a lm32 soft CPU) and micropython run:

make gateware
scripts/build-micropython.sh

and after several minutes (depending on the speed of your build machine; the ISE WebPACK synthesis is very CPU intensive) you should have both a gateware/top.bin file, and also a software/micropython/firmware.bin file, inside build/mimasv2_base_lm32:

(LX P=mimasv2 F=micropython) ewen@parthenon:/src/litex-buildenv$ ls -l build/mimasv2_base_lm32/gateware/top.bin
-rw-rw-r-- 1 ewen ewen 340884 Jan 17 12:32 build/mimasv2_base_lm32/gateware/top.bin
(LX P=mimasv2 F=micropython) ewen@parthenon:/src/litex-buildenv$
(LX P=mimasv2 F=micropython) ewen@parthenon:/src/litex-buildenv$ ls -l build/mimasv2_base_lm32/software/micropython/firmware.bin
-rwxrwxr-x 1 ewen ewen 167960 Jan 17 12:32 build/mimasv2_base_lm32/software/micropython/firmware.bin
(LX P=mimasv2 F=micropython) ewen@parthenon:/src/litex-buildenv$

Loading the gateware and micropython onto the Numato Mimas v2

On the Numato Mimas v2, the gateware (hardware configuration, including the lm32 soft CPU), BIOS (boot loader, etc), and an application ("firmware", eg micropython) all need to be loaded together in one large combined image file.

This combined image file is loaded in the programming mode of the Mimas v2, which is controlled by the slide switch SW7 near the power and USB connectors.

To load the combined gateware/BIOS/firmware (application) image:

  • Slide the Mimas v2 SW7 switch to "programming" mode (switch in position closest to the USB connector), and connect the USB cable between the Mimas v2 and the build machine if it is not already connected

  • Run:

    make image-flash

    to load the combined image file. This loads over a 19200 bps serial link, so it takes many seconds to load.

You should see something like:

(LX P=mimasv2 F=micropython) ewen@parthenon:/src/litex-buildenv$ make image-flash
[...]
python $(which MimasV2Config.py) /dev/ttyACM0 build/mimasv2_base_lm32//image-gateware+bios+micropython.bin
****************************************
* Numato Lab Mimas V2 Configuration Tool *
****************************************
Micron M25P16 SPI Flash detected
Loading file build/mimasv2_base_lm32//image-gateware+bios+micropython.bin...
Erasing flash sectors...
Writing to flash 100% complete...
Verifying flash contents...
Flash verification successful...
Booting FPGA...
Done.
(LX P=mimasv2 F=micropython) ewen@parthenon:/src/litex-buildenv$

Then when it is installed, to reach the micropython REPL:

  • Slide the Mimas v2 SW7 switch to "operation" mode (switch in position furthest from the USB connector)

  • Run:

    make firmware-connect

    and press enter a few times to get the MicroPython REPL prompt (or press the SW6 lm32 CPU reset on the Mimas v2 to see the boot prompts).

This looks something like:

(LX P=mimasv2 F=micropython) ewen@parthenon:/src/litex-buildenv$ make firmware-connect
flterm --port=/dev/ttyACM0 --speed=19200
[FLTERM] Starting...

>>>
>>>
>>>
>>>
LiteX SoC BIOS (lm32)
(c) Copyright 2012-2018 Enjoy-Digital
(c) Copyright 2007-2018 M-Labs Limited
Built Jan 17 2018 12:29:35

BIOS CRC passed (5338fc86)
Initializing SDRAM...
Memtest OK
Booting from serial...
Press Q or ESC to abort boot completely.
sL5DdSMmkekro
Timeout
Booting from flash...
Loading 167960 bytes from flash...
Executing booted program at 0x40000000
MicroPython v1.8.7-465-g7a4245d on 2018-01-17; litex with lm32
>>>

when the SW6 button was pressed after hitting enter a few times.

The advantage of this approach is that both the lm32 soft CPU gateware and micropython are stored in the SPI flash on the Numato Mimas v2, and thus will start automatically when power is applied to the Numato Mimas v2, so the only steps to start interacting with the micropython REPL is

cd /src/litex-buildenv
CPU=lm32
PLATFORM=mimasv2
TARGET=base
FIRMWARE=micropython
export CPU PLATFORM TARGET FIRMWARE
source scripts/enter-env.sh
make firmware-connect

and then hitting enter a few times to bring up the micropython REPL prompt.

The disadvantage is that the "make image-flash" step can take a very long time to upload the combined image.

Testing micropython updates with serialboot:

Because "make image-flash" takes such a long time, you may prefer to test interactive changes to the micropython application by loading them via serial boot, as then only the micropython application needs to be transferred with each change. To do this:

  • Slide the Mimas v2 SW7 switch to "operation" mode (switch in position furthest from the USB connector)

  • Run:

    make firmware-load

    to prepare to serialboot the lm32 software CPU into micropython.

  • Press the Mimas v2 lm32 "reset" switch, which is SW6 (near the SD card connector) to reset the software CPU and kick off a serialboot.

You should see something like:

(LX P=mimasv2 F=micropython) ewen@parthenon:/src/litex-buildenv$ make firmware-load
flterm --port=/dev/ttyACM0 --kernel=build/mimasv2_base_lm32//software/micropython/firmware.bin --speed=19200
[...]
[FLTERM] Starting...

LiteX SoC BIOS (lm32)
(c) Copyright 2012-2018 Enjoy-Digital
(c) Copyright 2007-2018 M-Labs Limited
Built Jan 17 2018 12:29:35

BIOS CRC passed (5338fc86)
Initializing SDRAM...
Memtest OK
Booting from serial...
Press Q or ESC to abort boot completely.
sL5DdSMmkekro
[FLTERM] Received firmware download request from the device.
[FLTERM] Uploading kernel (167960 bytes)...
[FLTERM] Upload complete (1.6KB/s).
[FLTERM] Booting the device.
[FLTERM] Done.
Executing booted program at 0x40000000
MicroPython v1.8.7-465-g7a4245d on 2018-01-17; litex with lm32
>>> print("Hello World!")
Hello World!
>>>
(LX P=mimasv2 F=micropython) ewen@parthenon:/src/litex-buildenv$

The serialboot of micropython will still take many seconds, as loading about 170KB at 19.2kbps is relatively slow! But at least you do not also need to load the gateware/firmware too.

ETA, 2018-02-10: An earlier version of this blog post suggested using "make gateware-flash" and then "make firmware-load" as a quicker method; unfortunately (a) "make gateware-flash" does not include the BIOS or firmware (application), and (b) make firmware-load relies on the BIOS to work, so that combination only works if the Mimas v2 board in question happens to have been previously programmed with "make image-flash", so the BIOS is already on the board. (In which case "make gateware-flash" is redundant unless the hardware definition has changed, and still fits in the gap left for it in the flash.)

Digilent Arty A7

The Digilent Arty A7 is a based around a Xilinx Artix-7 FPGA, which uses the Xilinx Vivado HL WebPACK proprietary FPGA synthesis software. The zero-cost "Vivado HL WebPACK" license is sufficient for this process.

These instructions assume you have:

  • a Digilent Arty A7 Artix-7 based FPGA board

  • an USB A to USB Micro cable, to connect Digilent Arty A7 to the Ubuntu 16.04 LTS build system

  • the Xilinx Vivado HL WebPACK synthesis tool installed, reachable from /opt/Xilinx (eg, via a symlink) with at least:

    • Design Tools / Vivado Design Suite / Vivado

    • Devices / Production Devices / 7 Series / Artix-7

    features installed; the other features are not needed and do not need to be installed.

Preparation

To get started building FPGA MicroPython for the Digilent Arty A7, start in the timvideos/litex-buildenv cloned above:

cd /src/litex-buildenv

and then configure the build targets:

CPU=lm32
PLATFORM=arty
TARGET=base
FIRMWARE=micropython

export CPU PLATFORM TARGET FIRMWARE

Once this is done, download the other bits of the build environment required for the Digilent Arty A7:

scripts/download-env.sh

(If you have already done this for the Numato Mimas v2 above, then most of the extras required will be already installed, but there are a few board-specific items, so be sure to run scripts/download-env.sh again to be sure.)

When that finishes, enter the build environment ready to build gateware and firmware for the Numato Mimas v2:

source scripts/enter-env.sh

All going well you should now have a prompt which begins with "(LX P=arty T=base)" (since the lm32 CPU is the default CPU). If anything is reported missing you may need to run scripts/download-env.sh again, or ensure that you have the Xilinx Vivado HL WebPACK installed and reachable from /opt/Xilinx.

Once you have completed scripts/download-env.sh one time, you can then skip that step in later sessions, just doing:

cd /src/litex-buildenv
CPU=lm32
PLATFORM=arty
TARGET=base
FIRMWARE=micropython
export CPU PLATFORM TARGET FIRMWARE
source scripts/enter-env.sh

to get started in a new terminal session.

Building the gateware and micropython for the Digilent Arty A7

To build the required gateware (FPGA configuration, including a lm32 soft CPU) and micropython run:

make gateware
scripts/build-micropython.sh

and after several minutes (depending on the speed of your build machine; the Vivado HL WebPACK synthesis is very CPU intensive) you should have both a gateware/top.bin file, and also a software/micropython/firmware.bin file, inside build/arty_base_lm32:

(LX P=arty T=base F=micropython) ewen@parthenon:/src/litex-buildenv$ ls -l build/arty_base_lm32/gateware/top.bin
-rw-rw-r-- 1 ewen ewen 2192012 Jan 17 16:06 build/arty_base_lm32/gateware/top.bin
(LX P=arty T=base F=micropython) ewen@parthenon:/src/litex-buildenv$ ls -l build/arty_base_lm32/software/micropython/firmware.bin
-rwxrwxr-x 1 ewen ewen 167816 Jan 17 16:07 build/arty_base_lm32/software/micropython/firmware.bin
(LX P=arty T=base F=micropython) ewen@parthenon:/src/litex-buildenv$

Loading the gateware and micropython onto the Digilent Arty A7

There are two stages to getting micropython running on the Digilent Arty A7: loading the gateware (hardware configuration, including the lm32 soft CPU), and loading the micropython firmware.

On the Digilent Arty A7 these two steps can be done one after another, thanks to the USB mode switching:

To load the gateware:

  • Run:

    make gateware-load

    to load the hardware configuration. This loads over the JTAG path to the Digilent Arty A7, so loads in a few seconds (much faster than the equivalent step with the Numato Mimas v2).

You should see something like:

(LX P=arty T=base F=micropython) ewen@parthenon:/src/litex-buildenv$ make gateware-load
openocd -f board/digilent_arty.cfg -c "init; pld load 0 build/arty_base_lm32//gateware/top.bit; exit"
Open On-Chip Debugger 0.10.0+dev-00267-gf7836bbc7-dirty (2018-01-15-07:40)
Licensed under GNU GPL v2
For bug reports, read
        http://openocd.org/doc/doxygen/bugs.html
none separate
adapter speed: 10000 kHz
Info : auto-selecting first available session transport "jtag". To override use 'transport select <transport>'.
jtagspi_program
Info : ftdi: if you experience problems at higher adapter clocks, try the command "ftdi_tdo_sample_edge falling"
Info : clock speed 10000 kHz
Info : JTAG tap: xc7.tap tap/device found: 0x0362d093 (mfg: 0x049 (Xilinx), part: 0x362d, ver: 0x0)
Info : Listening on port 3333 for gdb connections
loaded file build/arty_base_lm32//gateware/top.bit to pld device 0 in 1s 833353us
(LX P=arty T=base F=micropython) ewen@parthenon:/src/litex-buildenv$

To load micropython via serialboot:

  • Run:

    make firmware-load

    to prepare to serialboot the lm32 software CPU into micropython.

  • You may (or may not) then need to press the red "reset" button on the Digilent Arty A7 board (in the corner diagonally opposite the power connector) to get it to start serial booting (or if you have just powered the board on and loaded the gateware, it might be sitting waiting to serial boot).

You should see something like:

(LX P=arty T=base F=micropython) ewen@parthenon:/src/litex-buildenv$ make firmware-load
[...]
flterm --port=/dev/ttyUSB1 --kernel=build/arty_base_lm32//software/micropython/firmware.bin --speed=115200
[FLTERM] Starting...

LiteX SoC BIOS (lm32)
(c) Copyright 2012-2018 Enjoy-Digital
(c) Copyright 2007-2018 M-Labs Limited
Built Jan 17 2018 16:03:05

BIOS CRC passed (df2e52a7)
Initializing SDRAM...
Memtest OK
Booting from serial...
Press Q or ESC to abort boot completely.
sL5DdSMmkekro
[FLTERM] Received firmware download request from the device.
[FLTERM] Uploading kernel (167816 bytes)...
[FLTERM] Upload complete (7.7KB/s).
[FLTERM] Booting the device.
[FLTERM] Done.
Executing booted program at 0x40000000
MicroPython v1.8.7-465-g7a4245d on 2018-01-17; litex with lm32
>>> print("Hello World!")
Hello World!
>>>
(LX P=arty T=base F=micropython) ewen@parthenon:/src/litex-buildenv$

The serialboot of micropython will take several seconds, as loading about 170KB even at 115.2kbps is slow (but a lot faster than loading at 19.2kbps on the Mimas v2!).

Avoiding serialbooting

Unlike the Numato Mimas v2 there does not appear to be an easy way to avoid the serialboot process of micropython; but fortunately the Arty A7 serialboot (at 115.2kbps) is much faster than the Mimas v2 serialboot (at 19.2kbps).

However if the Arty A7 is already powered on with the gateware and micropython loaded, you can reconnect to the micropython REPL by running:

cd /src/litex-buildenv
CPU=lm32
PLATFORM=arty
TARGET=base
FIRMWARE=micropython
export CPU PLATFORM TARGET FIRMWARE
source scripts/enter-env.sh
make firmware-connect

and then hitting enter a few times to bring up the micropython REPL prompt.

Not that the Digilent Arty A7 does not store the gateware configuration in a SPI flash (unlike the Numato Mimas v2) so if the Arty A7 is power cycled you will need to go through the:

cd /src/litex-buildenv
CPU=lm32
PLATFORM=arty
TARGET=base
FIRMWARE=micropython
export CPU PLATFORM TARGET FIRMWARE
source scripts/enter-env.sh
make gateware-load
make firmware-load

cycle from the beginning, most likely including hitting the Arty A7 reset button to initiate serial booting. Fortunately this only takes a few tens of seconds to do.

ETA, 2018-01-19: Swapped instructions to using make firmware-load, now that it supports alternate firmware on Mimas v2 and Arty A7, as it is much easier to type :-)