RISC-V Analyzer for CMPUT 229

Last updated: March 7, 2025 9:00 PM

The CMPUT 229 team is super 🥳 excited to test a new tool to aid in your code development. This page introduces RISC-V Analyzer with installation and usage instructions.

RISC-V Analyzer (RVA) is a static analysis tool for linting RISC-V assembly code. RVA aims to detect violations of RISC-V register and procedure calling conventions and possible bugs. Some of these violations caught by RVA include:

invalid stack pointer manipulation,
caller-saved registers invalidly read after function calls,
overwriting callee-saved registers in functions, and
dead assignments.

Alpha software disclaimer

RVA is alpha software and you may encounter bugs. Please verify the output and take its output with caution. Do not assume RVA is always correct. If you encounter bugs, please report them.

Installation

RVA is a CLI (command-line) tool and must be interacted with through the terminal. There are multiple ways to install RVA. We recommend method 1.

Method 1: Lab machines (recommended)

(Linux) To install RVA, run the following commands.

# Step 0: ensure you are ssh'd into a lab machine

# Step 1: update .bashrc to include 
echo "source /cshome/cmput229/229-resources/env.sh" >> ~/.bashrc

# Step 2: source your .bashrc file or re-login to your shell
source ~/.bashrc

# Step 3: run rva
rva --version

More details: On the lab machines, the application is located publicly at the path /cshome/cmput229/229-resources/bin/rva. The above commands will source, or load, a custom file env.sh. This file contains instructions that updates your local $PATH variable, allowing you to run the command rva from your command line. As we update RVA, you will not need to run these instructions again. We will keep RVA updated for you.

Method 2: Personal machine (advanced)

(Linux, macOS) You can download and install the rva binary in any way you'd like. This is one such way to install RVA manually.

# Step 1: ensure the directory `~/.local/bin` exists
mkdir -p ~/.local/bin

# Step 2: add `~/.local/bin` to $PATH variable
echo "export PATH=\"\$PATH:$HOME/.local/bin\"" >> ~/.bashrc

# Step 3: source your .bashrc file or re-login to your shell
source ~/.bashrc

# Step 4: download the binary
curl "https://cmput229.github.io/229-RVA/RVA/$(uname)-$(uname -m)/latest/rva" -f -o ~/.local/bin/rva

# Step 5: update permissions
chmod +x ~/.local/bin/rva

# Step 5: run rva
rva --version

To update rva, you can run the following one-liner.

curl "https://cmput229.github.io/229-RVA/RVA/$(uname)-$(uname -m)/latest/rva" -f -o ~/.local/bin/rva && chmod +x ~/.local/bin/rva

Windows users

Windows is not officially supported at this time. If you use Windows, there are 2 main alternatives to use RVA.

Manual downloads

These links contain downloads to all versions of RVA. The top-most links will always be the latest versions.

Release date	Version
March 7, 2025	latest	Linux-x86_64	Linux-aarch64	Darwin-x86_64	Darwin-arm64
March 7, 2025	0.1.0-alpha.2	Linux-x86_64	Linux-aarch64	Darwin-x86_64	Darwin-arm64

Usage

To lint a file, run the following command.

rva lint <file-path>

To check the version installed, run the following command.

rva --version

For all available commands and other help, run the following command.

rva --help

Reporting issues

Reporting bugs and issues is the easiest way to contribute to open-source software! We encourage all students to report any issues or bugs they might encounter.

If you encounter a bug, please send an email to rmaghera@ualberta.ca with the subject beginning with RVA:. Don't be afraid to send as many emails as you need to! In your email, please include:

all your code files, including common.s,
the program output, screenshots are okay, and
a short description of what the issue or bug is

Do not publish your lab code on the GitHub issue page as it will be a violation of your code's copyright. Sending an email will not be a code violation.

How the analysis works

This section is a work-in-progress. This information is optional if you are curious about the inner workings of the analysis.

RVA uses data-flow analysis (more info: LLVM documentation) to gather information about code. In particular, RVA uses elements liveness analysis (more info: Wikipedia) and abstract interpretation (more info: Wikipedia) to determine where registers may be "live" or what the values inside registers and memory may be at any given point.

RVA uses the information from those analyses to write rules determining when calling conventions may be violated.

Example: register lifetimes and invalid read after function calls

Consider the following code segment.

# ----  LIVENESS:  t0   a0
li t0, 10          ##         # t0 <- 10
jal ra, foo        ##   ##    # call foo
add a0, t0, a0     ##   ##    # a0 <- t0 + a0

This code violates calling conventions. Since t0 is a caller-saved, or temporary, register, it is the responsibility of the caller, this code, to preserve the value in t0 if it is required. The function may use t0 and is not required to restore t0 to its original value. Thus, reading the value of t0 after the call is not valid.

After running liveness analysis, the lifetime of the register t0 begins on the first line of code, when its value is defined, and ends on the final line, when its value is last used. Since the register is live in and out of the jump-and-link instruction, the value defined on the first line will be the same value used after the function call.

With this knowledge, we can produce a warning based on this situation. Anywhere in the program, if a caller-saved register is live in and out of a function call instruction, that caller-saved register is read from after a function call.

More information

A basic demo can be found in the slides prepared by J. Nelson Amaral in CMPUT 229. If you have further questions or inquiries, you can message Rajan Maghera at hautsawce on the CMPUT 229 Discord or at rmaghera@ualberta.ca.