Tools

Setting up the environment

Before starting to this series of lab assignments, please make sure that you have followed the environment setup described below.

Our labs are designed based on Ubuntu 20.04 LTS. This is done using docker so that everyone has similar setups.
We recommend you to stick to this ubuntu version unless you might face some configuration issues.
You will also be using use QEMU, an x86 emulator for easier executing and debugging process instead of using real raspberry pi board.

This section has the information you’ll need to setup the environment.

Docker

You first need to install docker for your OS:

• Windows
• Mac
• Linux

Spin up Container

Go to your working directory where you’ll be working inside and run:

docker run -it --name os_labs -v $(pwd):/root/workdir:Z ubuntu:20.04

Now you’ll be inside the container, where you’ll see a prompt like this:

root@e8f10931f506:/#

Your working directory will now be available in /root/workdir/.

For resuming the container after you’ve exited:

docker start -i os_labs

Getting Repository and Installing Dependencies

# Download the repository
git clone https://github.com/pratyush3757/cs330_os.git --origin skeleton rustos
cd rustos/
git switch lab3

# Install dependencies
./bin/setup.sh
# Update environment
source ~/.bashrc

You’re all set to go back to the lab document if the setup.sh runs correctly and says [!] Setup complete.
Contact a TA if it throws an error.

Reference

This section has the information for the various tools you’ll be using during the labs.

Makefile

Our Makefile includes a number of targets to test and run our OS in various ways.

make

• Build kernel in release mode. The result executable and binary will be located under build/ subdirectory.

make debug

• Build Rust libraries or kernel in debug mode.

make check

• Check a local package and all of its dependencies for errors.

make qemu

• Start QEMU with the executable file under build/ subdirectory generated by make command. QEMU will generate a detailed log of assembly code of the guest. To exit QEMU, press Ctrl-a x.

make objdump

• Disassemble the executable file generated by make.

make nm

• List all symbols in the executable file generated by make.

make clean

• Clean the directory.

make install

• Install compiled kernel image to SD card. (Not needed until we have physical RPi devices)

make test

• Execute all unit and integration tests and build examples of a local package.

QEMU Emulator

QEMU (manual ) is a modern and fast PC emulator. We are providing a pre-built QEMU binary to emulate raspberry pi 3+ board as /bin/qemu-system-aarch64.

QEMU includes a built-in monitor that can inspect and modify the machine state in useful ways. To enter the monitor, press Ctrl-a c in the terminal running QEMU. Press Ctrl-a c again to switch back to the serial console.

For a complete reference to the monitor commands, see the QEMU manual . Here are some particularly useful commands:

xp/Nx paddr

• Display a hex dump of N words starting at physical address paddr. If N is omitted, it defaults to 1. This is the physical memory analogue of GDB’s x command.

info registers

• Display a full dump of the machine’s internal register state. In particular, this includes the machine’s hidden segment state for the segment selectors and the local, global, and interrupt descriptor tables, plus the task register. This hidden state is the information the virtual CPU read from the GDT/LDT when the segment selector was loaded.

info mem

• Display mapped virtual memory and permissions. For example,

  ef7c0000-ef800000 00040000 urw
  efbf8000-efc00000 00008000 -rw
  

  tells us that the 0x00040000 bytes of memory from 0xef7c0000 to 0xef800000 are mapped read/write and user-accessible, while the memory from 0xefbf8000 to 0xefc00000 is mapped read/write, but only kernel-accessible.