Author: Songhui Cao <caosh2022>

Verified By: Luojia Hu <hulj>

CS110@ShanghaiTech 2024 Spring Lab12

Download Lab 12 Starter from here.

To those Windows lovers: we CS110 TAs have noticed your determination on using Windows for CA1.

Lab 12 and Project 3 will have official Windows/x86-64 Linux/MAC support. See Piazza post @281 for MAC support.

Read Piazza post @270 before asking any question!

Read Piazza post @270 before asking any question!

Read Piazza post @270 before asking any question!

Step 0: Identify Objectives for Lab 12

1. Hack platformio so that you have a stable developing environment for Lab 12 and Project 3. (Step 1)
2. Understand how to program C and RISC-V code for Longan Nano. (Steps 2-4)

Step 1: Hack platformio

Troubleshooting

I know that most of you do not have the patience reading through all material, so troubleshooting will be delivered here.

• I cannot install PlatformIO.

  • Use VSCode plugin to install PlatformIO. DO NOT USE pip!

    • If you were using pip to install PlatformIO, try uninstall the pip version and switch to VSCode plugin. The pip version of PlatformIO may not cooperate well with VSCode, but it works as a command line tool anyway.

  • (For x86-64 Linux user) See installation guide from post @281. The troubleshooting section here is especially useful.

  • Search on the Internet. If the Internet does not provide practical solutions, post on Piazza.

• When I try to hack PlatformIO, some files do not exist, while others do. Why does this happen? What should I do?

  • Why does this happen? Because you have not opened PlatformIO Home. Some files first appear after you have opened and see PlatformIO Home. Merely seeing “Loading…” does not indicate that you have opened PlatformIO Home.
  • What should I do? If you can see some of these files, ignore this issue and go ahead as if all files exist. Otherwise re-install platformio.

Why Hacking platformio

Until March 2024, the SDK for Longan Nano on platformio is maintained by Sipeed, the manufacturer for Longan Nano. Unluckily, Sipeed removed the whole repository for Longan Nano recently, perhaps because they are intentionally causing trouble to Longan Nano to promote Lichee series, the predecessor of Longan. Therefore, the legacy instructions for setting up developing environment descended from 2020 no longer works. Fortunately, despite all the difficulties, Songhui Cao managed to compose a working environment for Longan Nano based on platformio. It is tested on both Windows and Ubuntu LTS versions (20.04 and 22.04).

Install platformio

The typical installation for platformio is to use the VSCode extension, not pip. Install the platformio extension on VSCode, wait until the platformio home appears, then the platformio installation is complete.

Hack platformio

Download the Longan development kit for CA1 from here: https://epan.shanghaitech.edu.cn/l/KFjNMO (Link valid until June 30, 2024)

Inflate the compressed archive, follow the instruction (readme.md/pdf) herein, 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 Lab 12 and Project 3. (Tip: If you are really curious about the magic, please read the source code of platformio)

platformio Basics

For introduction and detailed documentation to platformio and scons, please refer to their website. We only address issues that are vital to Lab 12 and Project 3 here. If you have no further plans about embedded software development, and aim at merely completing Lab 12 and Project 3, the following basics would be decent.

platformio is capable of:

1. Managing software development kits and toolchains for different boards.
2. Managing packages (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.

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

In Project 3 and Lab 12, you do not need direct command line interaction with PlatformIO.

Step 2: Compile the Source Code

From now, we use <lab root> to represent the folder that contains platformio.ini.

From now, we use <lab root> to represent the folder that contains platformio.ini.

From now, we use <lab root> to represent the folder that contains platformio.ini.

Troubleshooting

• I am installing PlatformIO with pip. What should I do?

  • If you do not want the PlatformIO integration with VSCode, use the following command to compile the source code. The result should be <lab root>/.pio/build/sipeed-longan-nano/firmware.bin.

  • cd <lab root>
    python3 -m platformio run
    

  • Otherwise uninstall the pip version and use VSCode plugin to install PlatformIO.

• Command cd <lab root> fails. It appears that the working directory is not what I desire.

  • The most common reason is that your path to platformio.ini has whitespace inside. Solution: change the path so that there is no whitespace, or use "" to quote the path, or insert \ before a whitespace.

Workflow and Explanation

Compile Lab 12 source code (on PC):

If you are installing platformio with VSCode, then you do not need to directly interact with platformio. Use VSCode to open the folder <lab root>, in platformio panel, issue the build command to compile the source code. The result should be <lab root>/.pio/build/sipeed-longan-nano/firmware.bin.

• Explanation:

  • You do not need knowledge for the compilation details to complete Lab 12 and Project 3. 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.

Enter DFU mode (on Longan Nano):

Same as Lab 11 (Longan Nano Part).

Download (write) to device (on PC):

Same as Lab 11 (Longan Nano Part). Remember to replace the .bin file path to <lab root>/.pio/build/sipeed-longan-nano/firmware.bin.

Leave DFU mode (Windows version: on PC/Longan Nano; Linux version: on Longan Nano)

Same as Lab 11 (Longan Nano Part).

Workflow Completion Self-Check

Same as Lab 11 (Longan Nano Part). The released source code is the source code for Lab 11 (Longan Nano Part), so the behavior should be exactly the same.

Step 3: Modify C Code

Modify C code so that the text TEST on the screen appears red instead of green when the joystick is pushed down. Also, fix the correspondence between SW1, SW2, and their text on screen.

You can only add/delete/modify files in directory <lab root>. We do not enforce any other restriction on what you modify for this step.

The reference implementation modifies less than 10 lines of C code.

Step 4: Modify RISCV Code

Modify the RISCV code so that you can see a rectangular on screen.

Sample RISCV code are in <lab root>/assembly. Use this to your advantage.

You can only modify RISCV code in <lab root>. We do not enforce any other restriction on what you modify for this step.

The reference implementation modifies/adds less than 10 lines of RISCV code.

Hint on Debugging

Longan Nano does not support GDB, so you will need to display debugging message on something. In consideration that the peripheral board may interfere with Hardware Serial, the suggested way is to display the debugging message on the screen.

Grading Rubrics

Steps 0, 1, and 2 counts as no score. There is 2 point for step 3, and 1 points for step 4.

1 point: The correspondence between SW1, SW2, and their text on screen is fixed.

1 point: The text TEST on the screen appears red when the joystick is pushed down.

1 point: TA can see a rectangular on screen. And by reading your code, TAs are convinced that you use RISCV, instead of C or C keyword asm, to implement step 4.

Students are encouraged to merge steps 3 and 4 into one firmware.bin and show to TA only once. However, this counts as no score. Students may show TA step 3, then download firmware again, and show step 4.

Students are also encouraged to download the firmware into device before check.