rst

From Zero to Rust on RISC-V

Abstract

rusty at sftsrc.com

April 2018

This technical note describes steps for creating a new, Linux-based virtual machine suitable for developing and deploying Rust applications for the SiFive HiFive1 RISC-V development board.

These steps are not the only possible configuration and they assume only a small amount of previous Linux experience. Also, the state of change for Rust and RISC-V may require some amount of flexibility in adapting these instructions to the most recent source code (i.e., expect some deviation from precisely what’s prescribed here).

Kudos to dvc94ch for blazing the trail with Rust support for RISC-V–these instructions leverage his excellent work.

Step 0: Before Beginning

Make sure you have the following before you begin:

  1. A machine with at least 8GB of RAM and at least 80GB of free disk space. Less of either may still work, but might make for a Rust development environment with less than ideal performance.

  2. A recent copy of VirtualBox installed on your machine. An alternate VM hypervisor may also work just fine, although connecting from a VM guest to the HiFive1 board will likely be different than with VirtualBox.

  3. Download and install (if not already installed) the VirtualBox Extension Pack for VirtualBox. This provides virtual USB devices enabling connectivity between the VM guest and the HiFive1.

  4. Download the latest ISO of Ubuntu Desktop, LTS version. Other distributions will also work–these instructions are tested with Ubuntu 16.04.4 (Xenial Xerus).

Step 1: Create new VM and install Ubuntu

  1. In VirtualBox, create a new virtual machine. Choose the following configuration parameters:

    • Ubuntu (64-bit)
    • 4096 MB of RAM (more, if desired; less, if necessary)
    • Create a new virtual HD, fixed-size, 80.00 GB or more
    • 2 or more CPU cores allocated to VM (1 is okay, if necessary)
    • As much Video Memory as possible
    • Enable 3D Acceleration (if possible)
    • Mount the IDE controller to the downloaded Ubuntu ISO so the Ubuntu installer runs when the VM is booted
  2. Start the virtual machine and confirm the Ubuntu installer boots up.

  3. Select “Install Ubuntu” button to begin installation.

  4. Proceed through installation dialogs using defaults or personal preferences. There is nothing special required.

  5. When installation is complete, unmount the Ubunto ISO from the virtual machine.

  6. Boot the Ubuntu VM and log in.

  7. Install the VirtualBox Guest Additions (via the Devices | Insert Guest Additions CD image... menu option) and reboot the VM.

  8. Log in and open a terminal shell.

Step 2: Install needed development packages

Both the RISC-V tools and the Rust compiler require several development libraries, tools, and other packages to be installed.

Within a shell, execute the following:

$ sudo apt-get install git cmake curl ninja-build libssl-dev pkg-config shtool screen autoconf automake autotools-dev device-tree-compiler libmpc-dev libmpfr-dev libgmp-dev gawk build-essential bison flex texinfo gperf libtool patchutils bc zlib1g-dev libusb-1.0-0-dev expat doxygen libexpat1-dev python2.7-dev babeltrace libbabeltrace-dev libncurses5-dev

Step 3: Download and build RISC-V tools

  1. In a shell, navigate to your home directory into which you’ll place the RISC-V tools.

  2. Clone the RISC-V Tools source code:

     $ git clone --recursive https://github.com/riscv/riscv-tools.git
    
  3. Use a text editor to update your ~/.profile to export a RISCV environment variable and update your search path:

     export RISCV=~/riscv
     PATH=$PATH:$RISCV/bin
    
  4. Log out and log back in to pick up these new environment variables.

  5. Change to the riscv-tools subdirectory.

  6. Execute the following:

     $ ./build-rv32ima.sh
    

    Note: there are other build shell scripts in the riscv-tools directory, but by default they build 64-bit tool versions, and the HiFive1 is a 32-bit RISC-V computer.

  7. Look for any errors during the build process for the RISC-V tools. There likely will be some warnings. If errors occur, look at the RISC-V Tools install instructions here.

  8. Verify that core RISC-V tools are in place by running:

     $ riscv32-unknown-elf-gcc --version
     $ riscv32-unknown-elf-gdb --version
    

Step 4: Test RISC-V tools (optional)

  1. Create a hello, world C file named hello.c similar to the following:

     #include <stdio.h>
    
     void main() {
       printf("hello, world\n");
     }
    
  2. Compile hello.c into a RISC-V executable:

     $ riscv32-unknown-elf-gcc -o hello hello.c
    
  3. Run the RISC-V executable within the RISC-V tools Spike simulator and associated proxy kernel (pk):

     $ spike pk hello
    
  4. If all goes well, hello, world is emitted to the console.

Step 5: Download and build RISC-V version of Rust tools

  1. In a console, change back to home directory.
  2. Perform the following:

     $ git clone --recursive https://github.com/riscv-rust/rust
     $ cd rust
     $ ./x.py build
    

    Note: building Rust will take awhile (at least an hour, but probably less than two, unless your VM resources are constrained).

  3. Prepare for Rust install by changing permissions on the /opt directory. It’s not ideal to leave the permissions this way, so consider changing them back as appropriate after you’re finished:

     $ sudo chmod 777 /opt
    
  4. Modify ~/.profile to include a search PATH to /opt/rust/bin. Log out and log back in to pick up the changes.

  5. Execute the following in a shell:

     $ cd rust
     $ ./x.py install
    

    Note: this will take awhile as well, although not as long as building Rust. Look for the message Rust is ready to roll to know when you’re finished.

  6. Verify Rust is installed:

     $ rustc --version
    

Step 6: Connect to HiFive1 board

  1. Shut down the virtual machine.
  2. Connect the HiFive1 board to your computer via USB cable.
  3. On the Settings dialog for the virtual machine in VirtualBox, select the Ports icon, then select the USB tab.
  4. Enable USB Controller and select the USB 2.0 (EHCI) Controller.
  5. Add a new USB filter, choosing the FTDI Dual RS232-HS [0700] option from the context menu.
  6. Click OK, boot the virtual machine, and log in.
  7. Open a shell and execute:

     $ ls -al /dev/ttyUSB*
    
  8. You should a result for /dev/ttyUSB0 and /dev/ttyUSB1. USB1 is most likely the correct device for the HiFive1 board, although be prepared to try USB0 (or other USB* options).

  9. Add your username to the dialout group, otherwise you will always need to use sudo when connecting to the HiFive1 board:

     $ sudo adduser username dialout
    
  10. Create a config file named /etc/udev/rules.d/99-openocd.rules with the following contents:

    SUBSYSTEM=="usb", ATTR{idVendor}=="0403", ATTR{idProduct}=="6010", MODE="664", GROUP="plugdev"

    SUBSYSTEM=="tty", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6010", MODE="664", GROUP="plugdev"

  11. Reboot the VM and log back in so that your username will be allowed to connect without sudo.

  12. Test connectivity to the HiFive1 board:

    $ screen /dev/ttyUSB1 115200
    

    This connects to the HiFive1 board at 115,200 baud.

  13. Reboot the HiFive1 board using the red push button on the board. Observe whether or not console output is emitted to the screen.

  14. When ready, kill screen typing Ctrl+A, then k, and then confirming with y.

Step 7: Download and build sample RISC-V crates

  1. Change to home directory.
  2. Download bare metal sample Rust code for the HiFive1 board:

     $ git clone --recursive https://github.com/riscv-rust/riscv-crates
    
  3. Install xargo:

     $ cargo install xargo
    
  4. Modify .profile to include a PATH directory to ~/.cargo/bin as per the warning issued when installing xargo. Log out and log back in to pick up changes.

  5. Using a text editor, modify riscv-crates/env.sh:

    • Comment out the line adjusting the PATH (these are already handled by .profile changes above)
    • Change XARGO_RUST_SRC to ~/rust/src
    • Change LD_LIBRARY_PATH to $RISCV/lib
  6. Modify the Makefile to build one of the examples and prepare it for deployment to the HiFive1 board. Make the following changes:

    • Uncomment EXAMPLE := blinky_delay
    • Uncomment OPENOCD_CFG := hifive-openocd.cfg
  7. Build the blinky_delay example:

     $ cd riscv-crates
     $ source ./env.sh
     $ make clean
     $ make build
     $ make upload
    

    Note: you may need to run make upload more than once to cleanly get the Rust program uploaded to the HiFive1 board.

  8. If all goes well, your HiFive1 board should rotate between the display of its red, green, and blue LEDs. The source code for this sample program is found at riscv-crates/examples/blinky_delay.rs

Congratulations! You’re done.