CS110/CS110P Lab 12

Computer Architecture I@ShanghaiTech

IMPORTANT: Read the FAQ from @103 before posting on Piazza!

Tasks of This Lab

Refer to the table to lookup your tasks for Longan Nano part of CS110/CS110P.

Background and Motivation

The background and motivation of Lab 11, Lab 12, and Project 4:

Project 4 is planned to be a comprehensive test on most of your knowledge learnt from CS110. It basically includes writing RISCV and C code in real hardware (Longan Nano) instead of emulator. In order to complete this task, one will need two techniques:

1. Compile the source code into an executable for Longan Nano (Lab 12)
2. Download (write) the compiled executable into Longan Nano (Lab 11)

In Lab 12, you will learn to compile the source code we provided into an executable for Longan Nano. The tasks for Lab 12 is listed as follows.

1. Get familiar with PlatformIO, so you get the compile environment.
2. Learn to modify the code for Longan Nano.

Task 1: Get familiar with PlatformIO

Overview

The objective of this task is to set up your compile environment for Longan Nano. You can then compile the code template of this lab into .bin file like the sample firmware we provided on Lab 10. In order to complete this task, you will need to:

• Install PlatformIO
• Hack PlatformIO so that you have a compiler capable of generating RISCV code.
• Download the code template of this lab
• Compile the code template of this lab

Install PlatformIO

Follow the instruction on PlatformIO Website to install PlatformIO.

IMPORTANT: By default, the built-in Python or Python installed via APT on Ubuntu 22.04 and 24.04 comes without python3-venv, which makes PlatformIO plugin always complains about invalid Python installation. For Ubuntu 22.04 and 24.04 users, we suggest that you run sudo apt install python3-venv before installing PlatformIO.

IMPORTANT: By default, the Python interpreter on Windows 10 and Windows 11 will be hooked by Microsoft Store to an invalid executable. It should have no impact on the PlatformIO installation given that you are not using command line to interact with PlatformIO, because it comes with an embedded Python interpreter. But if it does, follow the steps to solve this issue.

1. Remove all python-related path from all your PATH environment variable. Both user and system PATH should be cleaned.
2. Add path to your Python Interpreter into your PATH environment variable.
3. Close your VSCode and other IDE.
4. Open Powershell.
5. Run command taskkill /im explorer.exe /f in Powershell.
6. Run command explorer in Powershell.
7. Close all Powershell and cmd windows.
8. Re-open Powershell. Run command Get-Command python to verify if your shell now finds Python interpreter correctly.

Note: The typical installation for PlatformIO is to use the VSCode extension, not pip.

Note: It is still recommended to install PlatformIO through VSCode extension regardless of whether or not you are using CLion, because this is the official way installing PlatformIO.

Note: If you have Python environment, but PlatformIO plugin complains about invalid Python installation, make sure your Python interpreter supports the venv feature. See GitHub Issue for more detail.

Note: For ARM users, we are currently working to assign a server for you, on which you can deploy the compile environment. Stay tuned!

Hack PlatformIO

Background and Motivation

In order to compile the code template of this lab into a .bin file, you need a working compiler.

Unluckily, Sipeed, the manufacturer for Longan Nano, removed the whole SDK repository containing the compiler for Longan Nano in 2024. Therefore, it is no longer possible to let PlatformIO automatically install the compiler.

Fortunately, despite all the difficulties, we managed to compose a working environment for Longan Nano based on PlatformIO. It is tested on both Windows and Ubuntu LTS versions (20.04, 22.04, and 24.04).

Hack Guide

Download the Longan development kit for CA1 from here (longan-dev-kit-ca1-linux.tar.xz / longan-dev-kit-ca1-windows.7z).

Inflate the compressed archive, follow the instruction (readme.md/pdf), and you should be able to proceed. If you encounter any unexpected trouble, search on the Internet. If the problem persists, post on Piazza.

The reason why this chaos converges is beyond the scope of this lab. You may find your own answer, but ignoring the underlying magic suffices for this lab and Project 4. (Tip: If you are really curious about the magic, please read the source code of PlatformIO)

Download the Code Template

Download the code template(lab12-longan-nano-starter.tar.gz) for this lab from here.

IMPORTANT: DO NOT OPEN CODE TEMPLATE UNTIL YOU HACKED PLATFORMIO!

If you opened the code template before hacking PlatformIO, there is a (great) chance that you fail to compile the code template even if you hacked PlatformIO. To solve this issue, follow the steps below.

• Let <home> be your home directory. On Windows, it should look like C:\Users\<Your User Name>
• Remove PlatformIO plugin from VSCode.
• Close VSCode.
• Rename <home>/.platformio folder to another name.
• Restart this lab from the beginning.

Compile the Code Template

PlatformIO Basics

PlatformIO is a tool capable of:

1. Managing software development kits and toolchains for different boards,
2. Managing packages (works like apt) for embedded software development,
3. Performing static code analysis and cooperate with SCons to generate compiler commands so that the code can be automatically compiled.

Note: For introduction and detailed documentation to PlatformIO and SCons, please refer to their website. We only address issues that are vital to this lab and Project 4 here. If you have no further plans about embedded software development, and aim at merely completing this lab and Project 4, the following basics would be decent.

Compilation Guide

PlatformIO has only one configuration file in this lab and Project 4: platformio.ini. From now, we use <lab root> to represent the folder that contains platformio.ini.

In Project 4 and this lab, you only need 1 direct interaction with PlatformIO, which is the compilation of the code template. Use your IDE to compile the source code into .bin firmware.

The result should be <lab root>/.pio/build/sipeed-longan-nano/firmware.bin.

Note: You do not need knowledge for the compilation details to complete this lab and Project 4. However, if you ARE interested in, here are the clues so that you can search on the Internet.

• The ISA for your PC and the embedded device might be different, and the operation system will be different. Therefore, that the compiled executable cannot run natively on your host PC is a common phenomena. Generally, we call this (compiled executable cannot run natively on compiling host) cross compile.
• Generally speaking, the compiler during cross compile is different from the default compiler. Therefore, the Longan development kit for CA1 includes a working compiler toolchain, which explains why the size of the Longan development kit for CA1 after de-compression is so large.
• You may notice that PlatformIO does not generate CMakeLists.txt or Makefile. In fact, PlatformIO performs static code analysis and cooperates with SCons to generate compiler commands.

Check Procedure

(1 Point) Compile the source code and show TA the compiler log.

Task 2: Modify the C Code

Modify C code so that the text Test on the screen appears red when the joystick is pushed up.

Check Procedure

(1 Point) The text Test on the screen appears red when the joystick is pushed up. We encourage you to combine task 2 and 3 into one firmware.bin and show to TA only once.

Task 3: Modify the RISCV Code

Modify the RISCV code so that you can see a rectangular on screen. The position and size of rectangular does not matter.

RISCV code are in <lab root>/assembly.

Check Procedure

(1 Point) TAs can see a rectangular on screen. Show TAs your RISCV code so that TAs can make sure you are not using C to implement this task.