• CSCI 350 Operating Systems Image
  • Intro
    • Supported Platforms
    • Recommended Editors
  • Quick Start
  • Getting Started
    • Set Up
    • Running
    • Working in the Environment
    • Exiting the Environment
    • Stopping
  • Demo
  • Container Helper
  • System Requirements
  • Troubleshooting
    • xv6 will not start shell, hangs at qemu command
    • make qemu fails
    • Makefile:104: recipe for target 'bootblock' failed
    • xv6 stuck on qemu-system-i386 Windows
      • Docker Desktop Setting Screenshots

This repo contains a simple dev environment to do operating system development (at least for xv6). After pulling the Docker image from Docker Hub, you should be able to use the run.sh or run.ps1 script to start, stop, and work in a virtualized environment all from your command line.

The interface is based off of Noah Kim's and my cs104/docker.

For more information, please see the wiki. For any bugs or problems, please create an issue or dm me on Discord.

This Docker image has been tested and verified to be functioning correctly on the following platforms:

• Catalina, Big Sur (Intel)
• Big Sur (Apple Silicon)
• Windows 10 (Docker with WSL2 backend)

• Visual Studio Code with the Remote Containers extension
• JetBrains CLion with the Makefile extension or CMake integration
• NeoVim with coc.nvim and extra patience

You can download the CLI utility to run this and other docker environments. Shameless plug, I wrote that CLI too. Benefits of installing this way is that you don't have to be in a specific directory to start the csci350 environment. Also, you won't have to clone this repo to get started.

See instructions here on the commands to run to install the CLI.

Once you have ch installed, run the command to create the csci350 environment. This will download the Docker image that will work for xv6 and set the required environment to run qemu, gdb, and even do remote debugging. Before you run the command, make sure you've provided the correct path with the --volume flag (see instructions in the README for details).

The instructions below will walk you through running the setup script and the run script you'll use to access the csci350 environment.

1. Install Docker desktop from the website

   • Windows Users Only: Docker provides better performance using WSL 2 than legacy Hyper-V. Set up WSL 2 using Microsoft's guide here. After you have WSL 2 running, refer to the screenshots at the end of this readme for settings you have to enable in Docker Desktop app.

2. Clone this repository.

3. Specify your desired mount location (i.e. your xv6 project folder)

Windows users only

Make sure you run this in an Admin PowerShell to let you run scripts:

# must execute this in admin powershell and select [A] to run scripts
Set-ExecutionPolicy RemoteSigned

1. Modify the work variable at the top of the run script in the project folder. For example:

   macOS/Linux:

   # in run.sh
   work=~/projects/cs350/xv6-public-master/

   Windows Powershell:

   # in run.ps1
   $work="C:\Users\Username\cs350\xv6-public-master"

   Windows Terminal using WSL2:

   work=/mnt/c/Users/Username/cs350/xv6-public-master

2. Run the run.sh/run.ps1 script. If this is your first time starting, this will pull the Docker image. This image will be cached until there's a new image available or you manually remove it.

   macOS/Linux/Windows Terminal (WSL2):

   ./run.sh start

   Windows Powershell:

   .\run.ps1 start

This script is only a wrapper for some simple Docker commands.

To start up a Linux shell inside the Docker image, you'll want to start a terminal session inside the Docker image:

macOS/Linux/Windows Terminal (WSL2):

./run.sh shell

Windows Powershell:

.\run.ps1 shell

To quit qemu and return to Linux shell:

ctrl + a
x

Don't hit all three keys at the same time. Do ctrl + a then x

After you're done working in the environment, you might want to shut down the image. Don't worry if you forget to do this, since Docker Desktop will automatically and safely stop running images when you shutdown your computer.

macOS/Linux/Windows Terminal (WSL2):

./run.sh stop

Windows Powershell:

.\run.ps1 stop

Here's what it looks like to interact with a setup environment:

If you don't want to navigate to your docker directory every time, you can check out Container Helper to start your docker shell anywhere.

Below are the system requirements for Docker Desktop:

Windows host:

• Windows 10 64-bit: (Build 15063 or later)
  • Pro, Enterprise, or Education: using Hyper-V and Containers Windows features
  • Any Windows 10 version: using WSL2 container backend (recommended)

If you are using Windows 10 Home, you can obtain a "free" license for Windows 10 Education here.

Mac host:

• Mac hardware must be a 2010 or newer model
• macOS must be version 10.13 or newer
• 4 GB RAM minimum

If you're having issues starting xv6, such as the system is hanging at qemu commands, try the following

1. Outside the Docker shell, pull updated repo directory from xv6-public: git clone git@github.com:mit-pdos/xv6-public.git
2. Ensure all .pl files are executable and re-build:

# run these commands in the docker shell
chmod +x *.pl
make clean
make qemu-nox

Since this Docker image does not run a virtual display or window server, you cannot run make qemu. Instead, use make qemu-nox. Adding an X server would have minimal benefit, since you can simply use your current terminal window to debug your xv6 programs.

Run these commands

make clean
chmod 755 *.pl cuth dot-bochsrc printpcs runoff runoff1 show1 spinp
make qemu-nox

If your shell is stuck at qemu-system-i386 -nographic -drive file=fs.img,index=1,media=disk,format=raw -drive file=xv6.img,index=0,media=disk,format=raw -smp 2 -m 512 after running make qemu-nox, it probably means you don't have WSL/WSL2 enabled properly.

You can check if you have WSL by checking here.

If you don't have WSL, you can follow the steps here.

Now that you have WSL and a linux distro installed, you can check if you have WSL2 enabled by runnning PowerShell in administration and run this command

wsl --list --verbose

You'll then see the name of your WSL, State, and Version (what you see may vary based on the distro you installed, this write up is using Ubuntu)

PS C:\WINDOWS\system32> wsl --list --verbose
  NAME                   STATE           VERSION
* Ubuntu                 Running         2
  docker-desktop         Running         2
  docker-desktop-data    Running         2

Here, you see a list of WSL running processes along with its state and WSL version.

If it shows 1 under version for any of the names, you can change it to 2 by entering this command in PowerShell in administration

wsl --set-version <process name> 2

You can change the default distro by running

wsl --setdefault <process name>

After it finishes changing, open your Docker Desktop and enable Use the WSL 2 based engine. Then navigate to Settings > Resources > WSL Integration, make sure you check Enable integration with my default WSL distro, and enable integrations with any of the additional distros you have. You'll have to restart your docker by doing this operation.