CPSC 405 Tools

Sample RISV-V, Establish Linux, Establish Xv6, Test Xv6

In CPSC 405, we develop software using the C programming language. Our software is either (1) Xv6Linux/Unix utility or system programs (like cat and ls) or (2) operating system code that is part of Xv6. To develop our programs, you must have a Linux/Unix operating system, two C compiler toolchains, the Gnu Debugger (gdb), make, and other standard Linux utilities. A C compiler toolchain includes programs such as a C preprocessor, C compiler, assembler, linker, and C object dump. Most of our programs are developed for the Xv6 operating system. Xv6 is a special environment that includes the source code for simple Unix/Linux like OS and its utility programs (i.e., ls, cat, grep, etc.). Xv6 runs on a RISC-V architecture, which for our class is in the qemu emulator, which runs on a Linux computer. To summarize, you need

The simplest way to establish your programming environments is to use our CPSC server. It is a Linux computer that has all of the tools required for out class. You do not have to do anything to install Linux, QEMU, and the RISC-V compiler toolchain. All you have to do is login, perform git clones, design, edit, build, and test your programs.

For those more adventuresome, you can establish the programming environments on your personal computers. The instructions on this webpage describe how to establish the programming environments on your personal computers. You must perform two main steps.

  1. Establish Linux on your personal computer.
  2. Establish the Xv6 Programming Environment on your personal computer running under the Linux established in Step 1. The Xv6 programming environment includes QEMU, the RISC-V compiler toolchain, and make.

To reiterate, it is easiest to use the CPSC Linux Server - it has everything needed for our class.

If you are having trouble getting things set up, please come by to office hours, or post questions to Discord. We (me and students in our class) are happy to help!

Sample RISC-V Cross Compiler Commands

The following shows running the RISC-V gcc cross compiler. 
$ riscv64-linux-gnu-gcc test.c
test.c:1:27: error: conflicting types for 'argv'; have 'char **'
    1 | int main(int argv, char **argv) {
      |                    ~~~~~~~^~~~
test.c:1:14: note: previous definition of 'argv' with type 'int'
    1 | int main(int argv, char **argv) {
      |          ~~~~^~~~
$ vim test.c  <-- edit to fix duplicate argv
$ riscv64-linux-gnu-gcc test.c
$ ls
a.out  test.c

The following shows running the RISC-V gcc cross compiler to generate assembly code. 

$ riscv64-linux-gnu-gcc -S test.c
$ ls
test.c  test.s
$ cat test.c
int main(int argc, char **argv) {
   int i = 0, j = 0;
   while (i < 10)
      j++;
   return 0;
}
$ cat test.s
	.file	"test.c"
	.option pic
	.text
	.align	1
	.globl	main
	.type	main, @function
main:
	addi	sp,sp,-48
	sd	s0,40(sp)
	addi	s0,sp,48
	mv	a5,a0
	sd	a1,-48(s0)
	sw	a5,-36(s0)
	sw	zero,-20(s0)
	sw	zero,-24(s0)
	j	.L2
.L3:
	lw	a5,-24(s0)
	addiw	a5,a5,1
	sw	a5,-24(s0)
.L2:
	lw	a5,-20(s0)
	sext.w	a4,a5
	li	a5,9
	ble	a4,a5,.L3
	li	a5,0
	mv	a0,a5
	ld	s0,40(sp)
	addi	sp,sp,48
	jr	ra
	.size	main, .-main
	.ident	"GCC: (Ubuntu 11.4.0-1ubuntu1~22.04) 11.4.0"
	.section	.note.GNU-stack,"",@progbits

The following shows running the RISC-V object dump program. 

$ riscv64-linux-gnu-objdump -S wc.o

wc.o:     file format elf64-littleriscv


Disassembly of section .text:

0000000000000000 :

char buf[512];

void
wc(int fd, char *name)
{
   0:	7119                	addi	sp,sp,-128
0000000000000002 <.LCFI0>:
   2:	fc86                	sd	ra,120(sp)
   4:	f8a2                	sd	s0,112(sp)
   6:	f4a6                	sd	s1,104(sp)
   8:	f0ca                	sd	s2,96(sp)
   a:	ecce                	sd	s3,88(sp)
   c:	e8d2                	sd	s4,80(sp)
   e:	e4d6                	sd	s5,72(sp)
  10:	e0da                	sd	s6,64(sp)
  12:	fc5e                	sd	s7,56(sp)
  14:	f862                	sd	s8,48(sp)
  16:	f466                	sd	s9,40(sp)
  18:	f06a                	sd	s10,32(sp)
  1a:	ec6e                	sd	s11,24(sp)
  1c:	0100                	addi	s0,sp,128

000000000000001e <.LCFI1>:
  1e:	f8a43423          	sd	a0,-120(s0)
  22:	f8b43023          	sd	a1,-128(s0)

0000000000000026 <.LVL1>:
  int i, n;
  int l, w, c, inword;

  l = w = c = 0;
  inword = 0;
  26:	4981                	li	s3,0
  l = w = c = 0;
  28:	4c81                	li	s9,0
  2a:	4c01                	li	s8,0
  2c:	4b81                	li	s7,0
  2e:	00000d97          	auipc	s11,0x0
  32:	000d8d93          	mv	s11,s11
  while((n = read(fd, buf, sizeof(buf))) > 0){
    for(i=0; i 0){
  42:	a805                	j	72 <.L2>

... There is more output for this command ...

Establish Linux on CPSC Server and Personal Computers

The following sections describe how to establish Linux and C for CPSC Server, Linux, MacOS, and Windows.

UMW CPSC Linux Server

We have a Linux cloud server at cpsc.umw.edu, on which everyone should have an account. If you do not have an account, you can request one. Our CPSC Linux server is ready to use for Linux programming. 

% ssh username@cpsc.umw.edu
username@cpsc.umw.edu's password:

*************************************************************
* Welcome to                                                *
*                    ___  _ __   ___   ___                  *
*                   / __|| '_ \ / __| / __|                 *
*                  | (__ | |_) |\__ \| (__                  *
*                   \___|| .__/ |___/ \___|                 *
*                        |_|                                *
*                                                           *
* For use by UMW faculty and staff for academic use only.   *
* Please be respectful of others.  Questions and issues can *
* be directed to ifinlay@umw.edu                            *
*************************************************************

Last login: Wed Jul  6 17:37:17 2022 from 24.245.105.21
Hello
username@cpsc:~$ ls
dir1  dir2  dir3

Linux on Linux

For those of you using Linux, you are ready. Linux is Linux and has the C compiler tools suite.

Linux on MacOS

The MacOS terminal windows provide a Linux-like environment. MacOS is not based on the Linux source code, but it is based on Unix. You will need the MacOS Xcode command line developer tools, which contains git, the C compiler toolchain, and other items. You have three choices to install the MacOS Xcode Command Line Tools.

Linux on Windows

Windows supports Windows Subsystem for Linux (WSL). The entire WSL documentation is at Windows Subsystem for Linux (WSL)

There are two versions - WSL2 and WSL1. WSL2 is newer, preferred, and is the default installation, but either works for our purposes. I have installed and used both WSL1 and WSL2. I installed WSL 1 on an older computer that does not have a version of Windows required for WSL2. Second, on my newer Windows, I installed WSL2. If your computer supports WSL2, you should install it. For installation of WSL1/2 see WSL Installation

The installation includes an Ubuntu distribution, which is fine for us.

You run Ubuntu from the Windows home button. The first time you run Ubuntu, you must create a username and password.

You want to easily share files between Windows on Ubuntu. You can find several ways to do this on the Internet. One way is to enter the following command in your Ubuntu 

$ explorer.exe .

You get an Explorer window that is viewing your Linux files. Drag the box showing the Linux path to the Quick Access in the Explorer window. You can drag files from Windows to this Quick Access point. When I viewed the files from Linux, they were owned by root. You can do the following to change the file owner. The gusty:gusty is your username. 

$ sudo su
# chown gusty:gusty *

You must install the host versions of gcc and make on your Linux. To establish the C compiler, issue the following commands. 

$ sudo apt update
$ sudo apt install build essential
$ sudo apt-get install manpages-dev
$ gcc --version
When you enter $ make, make provides the commands to install make.

You can also install Windows Terminal from the Microsoft Store. The terminal has tabs, so you can run ubuntu via the > ubuntu command.

Establish the Xv6 Programming Environment

For the Xv6 programming environment you need the RISC-V versions of a several tools: QEMU 5.1+, GDB 8.3+, GCC, and Binutils.

The simplest way to access the Xv6 programming environment is to use the UMW CPSC server.

Using Xv6 on the UMW CPSC Server - No Installation Required

The Tools have been installed on the UMW CPSC Server. You can login, clone the git repo, and begin to work.

$ ssh username@cpsc.umw.edu
username@cpsc.umw.edu's password: 

username@cpsc:~$ git clone https://github.com/gustycooper/xv6-labs.git
username@cpsc:~$ cd xv6-labs/
username@cpsc:~/xv6-labs$

Installing Xv6 on Debian or Ubuntu

sudo apt-get install git build-essential gdb-multiarch qemu-system-misc gcc-riscv64-linux-gnu binutils-riscv64-linux-gnu

Installing Xv6 Arch Linux

sudo pacman -S riscv64-linux-gnu-binutils riscv64-linux-gnu-gcc riscv64-linux-gnu-gdb qemu-emulators-full

Installing Xv6 on Windows

Students running Windows are encouraged to either install Linux on their local machine or use WSL 2 (Windows Subsystem for Linux 2).

We also encourage students to install the Windows Terminal tool in lieu of using Powershell/Command Prompt.

To use WSL 2, first make sure you have the Windows Subsystem for Linux installed. Then add Ubuntu 20.04 from the Microsoft Store. Afterwards you should be able to launch Ubuntu and interact with the machine.

IMPORTANT: Make sure that you are running version 2 of WSL. WSL 1 is implemented with a different architecture than WSL 2, which may cause future problems with the labs. To sanity check, run wsl -l -v in a Windows terminal to confirm that WSL 2 and the correct Ubuntu version are installed.

To install all the software you need for this class, run:

$ sudo apt-get update && sudo apt-get upgrade
$ sudo apt-get install git build-essential gdb-multiarch qemu-system-misc gcc-riscv64-linux-gnu binutils-riscv64-linux-gnu

From Windows, you can access all of your WSL files under the "\\wsl$\" directory. For instance, the home directory for an Ubuntu 20.04 installation should be at "\\wsl$\Ubuntu-20.04\home\<username>\".

Installing Xv6 on macOS

First, install developer tools. You probably did this as you established you Linux environment. 

$ xcode-select --install

Next, install Homebrew, a package manager for macOS: 

$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Next, install the RISC-V compiler toolchain: 

$ brew tap riscv/riscv
$ brew install riscv-tools

The brew formula may not link into /usr/local. You will need to update your shell's rc file (e.g. ~/.bashrc) to add the appropriate directory to $PATH. 

PATH=$PATH:/usr/local/opt/riscv-gnu-toolchain/bin

Finally, install QEMU: 

brew install qemu

Running a Linux VM

If you're running an operating system on which it's not convenient to install the RISC-V tools, you may find it useful to run a Linux virtual machine (VM) and install the tools in the VM. Installing a Linux virtual machine is a two step process. First, you download the virtualization platform.

VirtualBox is a little slower and less flexible, but free!

Once the virtualization platform is installed, download a boot disk image for the Linux distribution of your choice.

This will download a file named something like ubuntu-20.04.3-desktop-amd64.iso. Start up your virtualization platform and create a new (64-bit) virtual machine. Use the downloaded Ubuntu image as a boot disk; the procedure differs among VMs but shouldn't be too difficult.

Testing your Xv6 Installation

To test your Xv6 installation, you should be able to compile and run xv6. You can try this by following the instructions in the first lab.

You can also double check your installation is correct by running the following:

$ qemu-system-riscv64 --version
QEMU emulator version 5.1.0

And at least one RISC-V version of GCC:

$ riscv64-linux-gnu-gcc --version
riscv64-linux-gnu-gcc (Debian 10.3.0-8) 10.3.0
...

$ riscv64-unknown-elf-gcc --version
riscv64-unknown-elf-gcc (GCC) 10.1.0
...

$ riscv64-unknown-linux-gnu-gcc --version
riscv64-unknown-linux-gnu-gcc (GCC) 10.1.0
...

Questions or comments regarding CPSC 405? Send e-mail to Gusty at ecooper@umw.edu.

Creative Commons License Top // CPSC 405 home // Last updated 8-Aug-2024 13:30 EST