Document & reproduce getting repl loop working

[mithro]

@shenki has had the repl loop working in QEmu.
@mithro has had the repl loop working on Opsis hardware.
@Kathatosada got repl loop working on the MimasV2 at Linux.conf.au

[ewenmcneill]

Documentation would definitely help :-)

I feel like I've got fairly close working with Ubuntu 16.04 LTS and trying to target a Mimas v2: built gateware from https://github.com/upy-fpga/upy-fpga-litex-gateware; built modern lm32 cross tools from https://github.com/shenki/lm32-build-scripts; built MicroPython from https://github.com/upy-fpga/micropython lm32-mimasv2 branch.

But there seems to be a "magic happens here" step that I'm missing which puts the gateware and MicroPython onto the Mimas v2, and then makes the REPL available. If I do "make image-flash-mimasv2" then I seem to be able to get a non-Python REPL (which looks a bit like the Optis one), so I think that part works. But I've had no luck with "make firmware-load-mimasv2" (just seems to hang at "Starting...", nor with trying to combine the gateware for the CPU with the bits built in the MicroPython build and flashing those. The "lm32/Makefile" implies that "deploy" is "to do later" without any hints on what one is supposed to do.

For reference my fairly detailed notes (to be turned into a blog post sometime) of my steps so far follow.

---

MicroPython on Numato Mimas V2 FPGA

Prerequisites

• Ubuntu 16.04 LTS x86_64 system

• Numato Mimas V2 Spartan6 FPGA board, with MimasV2Config.py set up to be able to upload "gateware" to the FPGA board (there is also a copy of MimasV2Config.py installed as part of this envvironment setup below which is used for flashing the MicroPython FPGA gateware).

• USB A to USB Mini B cable, to connect Numato Mimas V2 to laptop

• Xilinx ISE WebPACK installed, reachable from /opt/Xilinx (or optionally installed within the Xilinx directory inside your build directory).

Before you begin it would be a very good idea to check that the Numato Mimas v2 sample.bin
code will run on your Mimas v2, and that you can successful replace it with a program of your own (eg, the Numato tutorial synthesis example.

Gateware

Setup

Clone repository, which originated with HDMI2USB (hence the dependencies listed):

git clone https://github.com/upy-fpga/upy-fpga-litex-gateware

Install the relevant bits of the environment in two parts, firstly as root:

cd upy-fpga-litex-gateware
sudo bash -x scripts/download-env-root.sh

which will install dozens of packages as direct or indirect dependencies, including some from Tim's Ubuntu PPA.

And then as a non-root user (eg, your own user) for the remaining parts:

cd upy-fpga-litex-gateware
bash -x scripts/download-env.sh

which will download a bunch more packages, and execute/install them. Among other things it installs lm32 cross build tools (binutils, gcc, etc), as pre-built binary tools. The install process is managed with [conda](https://conda.io/docs/intro.html), a Python environment management tool. (It currently actually installs a Python 3.6 environment, and then downgrades it to Python 3.5.1 for compatability, as well as a lot of other old tools.)

It also automatically git clones the relevant Enjoy Digital litex git modules, as listed in the README.

The environment install process will take several minutes, mostly depending on the download speed.

Build

From a terminal which has not entered the Xilinx ISE WebPack environment, set the desired PLATFORM and TARGET to select what will be built, then enter the upy-fpga environment:

cd upy-fpga-litex-gateware
PLATFORM=mimasv2
TARGET=base
export PLATFORM TARGET
source scripts/enter-env.sh

All going well, it should do some checking, report the directories being used, and then change the prompt to include the PLATFORM and TARGET values. Eg,

(H2U P=mimasv2 T=base R=nextgen)

make help will show you the valid PLATFORM and TARGET values, but cannot be run until after
scripts/enter-env.sh has been done; to change platforms or targets it would be best to start with a fresh terminal. (README.targets has some information on the possible TARGET values.)

From there, you can build the "gateware" for your selected PLATFORM/TARGET combination with:

make gateware

which will result in a lot of output, most of it from the Xilinx ISE WebPACK tools. This step will also take a few minutes, and will keep your CPU pretty busy. All going well you should end up
with a build/mimasv2_base_lm32/gateware/top.bin file which can be loaded onto the Mimas V2.

Next you can build the "firmware" to run on the softcore CPU to provide MicroPython on the FPGA. You can build this for your selected PLATFORM/TARGET combination with:

make firmware

This step appears to use a pre-compiled firmware file, and builds quite quickly. It should result in a
build/mimasv2_base_lm32//software/firmware/firmware.bin file.

Install

Ensure that the Numato Mimas v2 "operation mode" switch (SW7) is set to program mode -- the side nearest the USB connector is program mode (see the Numato Mimas V2
documentation).

Install the gateware with:

make gateware-flash-mimasv2

Because the upload happens at 19200 bps, this will take a couple of minutes to complete -- it does an erase cycle, a write cycle, and a read-back verification cycle.

The process looks something like:

(H2U P=mimasv2 T=base R=nextgen) ewen@parthenon:~/work/naos/src/upy-fpga/upy-fpga-litex-gateware$ make gateware-flash-mimasv2
python $(which MimasV2Config.py) /dev/ttyACM0 build/mimasv2_base_lm32//gateware/top.bin
****************************************
* Numato Lab Mimas V2 Configuration Tool *
****************************************
Micron M25P16 SPI Flash detected
Loading file build/mimasv2_base_lm32//gateware/top.bin...
Erasing flash sectors...
Writing to flash 100% complete...
Verifying flash contents...
Flash verification successful...
Booting FPGA...
Done.
(H2U P=mimasv2 T=base R=nextgen) ewen@parthenon:~/work/naos/src/upy-fpga/upy-fpga-litex-gateware$ 

Modern build environment

Building MicroPython needs a fairly recent crosscompiler build environment, newer than the one used by the MicroPython gateware.

This step is best done in a terminal which does not have the gateware configuration (above) in it, so start a fresh terminal.

To build this newer crosscompiler environment clone the lm32-build-scripts repository:

git clone https://github.com/shenki/lm32-build-scripts.git

Then build the cross compilers on your system with:

cd lm32-build-scripts
./build-lm32-toolchain.sh

It will download several key Linux build tools (gcc, gmp, mpfr, mpc, binutils, gdb, etc), and then use them to build a crosscompiler for lm32, designed to be installed in /opt/lm32.

This step will take several minutes, particularly to download the required source to build. Expect your CPU to be very busy for a while as it does a make -j32 when building everything; this also makes the console output fairly tricky to follow, and it fairly difficult to tell how far through the build process it has reached. (Currently there does not seem to be any check that the downloads are complete, or as intended -- nor any stop and continue steps in the build process -- so it is a bit "hope this works". There is partial support for building a Docker environment with the cross-compilers, but it appears to do a one-shot build and then remove them; presumably it is there only for testing the build scripts work.)

Assuming that it finishes without obvious error, and the return code is 0:

echo $?

then we can assume that it worked. The build directory should include a lot of built code (approximately 2GB).

The built code can then be installed somewhere central with:

sudo mkdir /opt/lm32
sudo chown $USER:$USER /opt/lm32
(cd build && make install)

which will also generate a lot of output, but run much quicker.

After this /opt/lm32/bin should contain a bunch of useful cross-compile tools, eg:

ewen@parthenon:/opt/lm32/bin$ ls
lm32-elf-addr2line  lm32-elf-gcc-6.2.0   lm32-elf-gprof    lm32-elf-readelf
lm32-elf-ar         lm32-elf-gcc-ar      lm32-elf-ld       lm32-elf-run
lm32-elf-as         lm32-elf-gcc-nm      lm32-elf-ld.bfd   lm32-elf-size
lm32-elf-c++filt    lm32-elf-gcc-ranlib  lm32-elf-nm       lm32-elf-strings
lm32-elf-cpp        lm32-elf-gcov        lm32-elf-objcopy  lm32-elf-strip
lm32-elf-elfedit    lm32-elf-gcov-tool   lm32-elf-objdump
lm32-elf-gcc        lm32-elf-gdb         lm32-elf-ranlib
ewen@parthenon:/opt/lm32/bin$ 

MicroPython

MicroPython is best built in a new terminal, without the gateware environment variables. It needs to be built from an in-development repository with changes for MicroPython on FPGA and the Mimas v2.

In a fresh terminal, clone the forked MicroPython repository, with Mimas V2 support in it:

git clone https://github.com/upy-fpga/micropython.git

Enter the repository, and checkout the lm32-mimas2 branch:

cd micropython
git checkout lm32-mimas2

Change into the lm32 directory, and build with a cross compiler:

cd lm32
PATH="${PATH}:/opt/lm32/bin" make CROSS=1

That should build fairly quickly, and result in a build/firmware.elf file. Convert that into a firmware.bin file with:

PATH="${PATH}:/opt/lm32/bin" make build/firmware.bin CROSS=1

Installing MicroPython on the Numato Mimas v2

NOTE: this does not appear to actually work :-(

To actually install MicroPython, it appears that we have to build a complete flash image, by hand, containing the base processor gateware, the BIOS, and the MicroPython image. (There is a flterm upload tool, but I was unable to make this work.)

Return to the gateware build top directory, with the environment set up, ie as before (possibly you still have a suitable terminal open):

cd upy-fpga-litex-gateware
PLATFORM=mimasv2
TARGET=base
export PLATFORM TARGET
source scripts/enter-env.sh

Make a directory to build up the MicroPython flash image:

mkdir micropython
cd micropython

And then copy over the MicroPython firmware.elf and firmware.bin file:

cp -p .../micropython/lm32/build/firmware.elf .
cp -p .../micropython/lm32/build/firmware.bin .

Run:

python -m litex.soc.tools.mkmscimg firmware.elf
python -m litex.soc.tools.mkmscimg -f firmware.bin -o firmware.fbi

to build a firmware.fbi file.

Change back up to the top directory, and then use mkimage to build a complete flash image:

cd ..
rm build/mimasv2_base_lm32/flash.bin
./mkimage.py --override-bios none --override-firmware micropython/firmware.fbi

This should build a new flash image in build/mimasv2_base_lm32/flash.bin.

Then this custom flash image can be loaded onto the Numato Mimas v2, by ensuring that the "operation mode" switch (SW7) is in "program mode" (nearest to the USB connector), and then unplugging and plugging in the Numato Mimas v2 to reset it.

Once /dev/ttyACM0 appears on the system again, run:

MimasV2Config.py /dev/ttyACM0 build/mimasv2_base_lm32/flash.bin

to program MicroPython onto the Mimas v2. This will take a few minutes to write, as it is uploading at 19200 bps.

The result should look something like:

(H2U P=mimasv2 T=base R=nextgen) ewen@parthenon:~/work/naos/src/upy-fpga/upy-fpga-litex-gateware$ MimasV2Config.py /dev/ttyACM0 build/mimasv2_base_lm32/flash.bin
****************************************
* Numato Lab Mimas V2 Configuration Tool *
****************************************
Micron M25P16 SPI Flash detected
Loading file build/mimasv2_base_lm32/flash.bin...
Erasing flash sectors...
Writing to flash 100% complete...
Verifying flash contents...
Flash verification successful...
Booting FPGA...
Done.
(H2U P=mimasv2 T=base R=nextgen) ewen@parthenon:~/work/naos/src/upy-fpga/upy-fpg

a-litex-gateware$

Unfortunately this does not result in a working system :-( See comments at top

[mithro]

@ewen-naos-nz Hi! You should join us on #upy-fpga on Freenode. We have actually been hacking on stuff related to the MimasV2 yesterday and today!

[mithro]

So there are a couple of options to get micropython onto the MimasV2 instead of the H2U firmware.

(1) Load via serial

Use
flterm --port=$(PORT) --kernel=micropython.bin --speed=19200 and then type reboot at the H2U> prompt.

This will load micropython via the serial terminal.

(2) Actually flash micropython

Create a micropython.fbi using python -m litex.soc.tools.mkmscimg -f micropython.bin -o micropython.fbi and then use mkimage.py with --override-firmware=micropython.fbi and then flash the resulting image file.

(3) Flash without firmware and then load via serial

Use mkimage.py with --override-firmware=none and then flash the firmware. It will boot into the bios and complain about not being able to find the firmware. You can then follow the steps in (1).

---

BTW flterm doesn't like micropython for some reason (line endings I think?). So you'll have to disconnect from the serial port and use something like screen or minicom

[ewenmcneill]

After some assistance from @mithro on #upy-fpga on FreeNode, plus a couple of patches he added, I've been able to get to the REPL on the Numato Mimas v2.

Blog post with my notes on how I did it (an expanded version of the text above):

http://ewen.mcneill.gen.nz/blog/entry/2017-03-12-micropython-on-numato-mimas-v2/

Ewen