Running MicroPython on LiteX

Building MicroPython

LiteX Build Environment comes with a helper script that configures the environment and automatically clones and builds MicroPython.

Download and Configure the Build Environment

First, clone the LiteX Build Environment repository and set it up:

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

# configure target
export CPU=vexriscv
export PLATFORM=arty
export FIRMWARE=micropython

./scripts/download-env.sh

Enter the Build Environment and build MicroPython

Follow the instructions in this section to setup udev rules needed to enable access to the USB device.

Once udev rules are set up and the environment is configured, enter it and build the firmware:

source scripts/enter-env.sh
SKIP_IMAGE=1 ./scripts/build-micropython.sh

MicroPython sources, available for further modification, will be cloned to third_party/micropython.

The script will then build the MicroPython binary.

Setting SKIP_IMAGE to 1 informs the script not to generate the flash image after building the MicroPython binary. Since the flash image contains all necesasary binaries and a gateware, generating it requires to synthetize the project first (which is time consuming and requires the Vivado software). This is not needed, though, when running the simulation in Renode. The gateware can be generated later (if needed) as described in the following section.

As a result you will find firmware.bin in the build/arty_base_vexriscv/software/micropython directory.

Building the bitstream and flashing the FPGA

Note: Steps in this section can be skipped if you are only interested in simulation in Renode.

In order to build the gateware for an Arty board, you will need to have the Xilinx Vivado toolchain installed in your system.

Follow the instructions on the LiteX BuildEnv Wiki to download, install and get a license for Vivado.

Building the gateware

Execute the following command to build the gateware:

make gateware

Note that the above operation might take a while.

Loading the gateware onto the FPGA

Once you have a synthesized gateware, load it onto the FPGA with:

make gateware-load

As a result your FPGA will contain the LiteX+VexRiscv platform preloaded with the LiteX BIOS bootloader.

Running MicroPython

Simulation in Renode

Execute the following command to start the simulation in Renode:

./scripts/build-renode.sh

This will generate startup scripts for Renode based on your current LiteX configuration and start the simulation. As a result two windows will be opened.

The monitor, used to control the simulation:

And a UART analyzer displaying messages printed by the software and allowing to interact with the MicroPython shell:

For more information on simulating LiteX in Renode (including advanced usage) see the Renode page on the LiteX BuildEnv wiki.

Running on Arty Board

Execute the following command:

make firmware-load

This will start an flterm tool that connects to the board using /dev/ttyUSB and uploads the binary via the serialboot option in LiteX BIOS.

Now, press red reset button on the board to reset the CPU, reboot LiteX BIOS and start the process of uploading the MicroPython image.

Finally, you should see the prompt of MicroPython shell:

flterm --port=/dev/ttyUSB1 --kernel=build/arty_base_vexriscv.full//software/micropython/firmware.bin --speed=115200
[FLTERM] v2.4-29-g47d3b15 Starting...

        __   _ __      _  __
       / /  (_) /____ | |/_/
      / /__/ / __/ -_)>  <
     /____/_/\__/\__/_/|_|

 (c) Copyright 2012-2019 Enjoy-Digital
 (c) Copyright 2007-2015 M-Labs Ltd

 BIOS built on Oct 23 2019 13:50:35
 BIOS CRC passed (23d0a341)

--============ SoC info ================--
CPU:       VexRiscv @ 100MHz
ROM:       32KB
SRAM:      32KB
L2:        8KB
MAIN-RAM:  262144KB

--========= Peripherals init ===========--
Initializing SDRAM...
SDRAM now under software control
Read leveling:
m0, b0: |11111111110000000000000000000000| delays: 05+-05
m0, b1: |00000000000000111111111111000000| delays: 20+-06
m0, b2: |00000000000000000000000000000001| delays: 31+-00
m0, b3: |00000000000000000000000000000000| delays: -
m0, b4: |00000000000000000000000000000000| delays: -
m0, b5: |00000000000000000000000000000000| delays: -
m0, b6: |00000000000000000000000000000000| delays: -
m0, b7: |00000000000000000000000000000000| delays: -
best: m0, b1 delays: 20+-06
m1, b0: |11111111110000000000000000000000| delays: 05+-05
m1, b1: |00000000000000111111111111000000| delays: 20+-06
m1, b2: |00000000000000000000000000000001| delays: 31+-00
m1, b3: |00000000000000000000000000000000| delays: -
m1, b4: |00000000000000000000000000000000| delays: -
m1, b5: |00000000000000000000000000000000| delays: -
m1, b6: |00000000000000000000000000000000| delays: -
m1, b7: |00000000000000000000000000000000| delays: -
best: m1, b1 delays: 20+-06
SDRAM now under hardware control
Memtest OK

--========== Boot sequence =============--
Booting from serial...
Press Q or ESC to abort boot completely.
sL5DdSMmkekro
[FLTERM] Received firmware download request from the device.
[FLTERM] Uploading kernel (218608 bytes)...
[FLTERM] Upload complete (7.7KB/s).
[FLTERM] Booting the device.
[FLTERM] Done.
Executing booted program at 0x40000000
--============= Liftoff! ===============--
MicroPython v1.9.4-1429-gb856c7a5d on 2019-10-23; litex with riscv32
>>>