OS/161 on WSL

Learning Outcome

Set up and run OS161 for all COMP3231 assignments on a computer running Windows Subsystem for Linux.

Introduction

In this module, there are several steps marked with do once per… - these indicate if you need to repeat those steps if you have already done them. Just follow the steps in order (from the valid once per… label), replacing <n> with the assignment number and <20t1> with the trimester number.

Applicable subjects

COMP3231

Setting up your folders

Do once per computer

Place your assignment files somewhere on the Windows section of your computer. This allows you to use the windows GUI to open them and edit them in a graphical text editor. The OS/161 code base is quite large so you will want to be using a text editor with search/ view folder functionality (such as VSCode). This tutorial will assume that you have placed your code within your Documents folder, but you can place them wherever you like (just don’t forget to change the file path in this module appropriately).

Create a folder called cs3231 within your documents folder using WSL:

$ cd /mnt/c/Users/<YourUserName>/Documents
$ mkdir cs3231

You can now find your files via File Explorer in the following folder:

C:\Users\<YourUserName>\Documents\cs3231

GDB User Initialization File

Do once per computer

The user initialization file contains commands that are executed upon the startup of GDB. It is located in your home folder under the path:

~/.gdbinit

Create/ edit this file and add the following line to this file:

set auto-load safe-path /

This allows our programs to use the current drectory initialization file (see the next section).

Install the conf file

Do once per computer

Install the sys161-asst0.conf file in the ~/cs3231/root directory by running:

$ mkdir ~/cs3231/root
$ cd ~/cs3231/root
$ wget http://cgi.cse.unsw.edu.au/~cs3231/19T1/assignments/asst1/sys161.conf -O sys161.conf

Clone your repository

Do once per assignment

Git is not only helpful for retreiving the files, but also for transferring files to and from CSE, backups, and collaborating with your partner. Clone the git repo using the command below:

$ cd ~/cs3231
$ git clone gitlab@gitlab.cse.unsw.EDU.AU:<z5555555>/<20t1>-comp3231-asst<n>.git asst<n>-src

Don’t forget to substitute in your zID, session number and the assignment number (removing the angle brackets).

GDB Current Directory Initialization File

Do once per assignment

The current directory initialization file contains commands to be executed upon the startup of GDB within the current folder. Since we will be running GDB within the root folder of cs3231, the path is:

~/cs3231/root/.gdbinit

Create/ edit this file and add the following line to this file (replacing <n> with the appropriate assignment number):

set can-use-hw-watchpoints 0

define connect
    dir ~/cs3231/asst<n>-src/kern/compile/ASST<n>
    target remote localhost:16161
    b panic
end

Make your Assignment the First Time

Do once per assignment

For each assignment, run the following commands to set up the files. You only need to run these commands once (for the current assignment). Make sure you replace <n> with the current assignment number.:

$ cd ~/cs3231/asst<n>-src
$ ./configure
$ bmake
$ bmake install
$ cd ~/cs3231/asst<n>-src/kern/conf
$ ./config ASST<n>
$ cd ../compile/ASST<n>
$ bmake depend
$ bmake
$ bmake install

Make Your Assignments Additional Times

Do before you run your assignment if you have changed code

Each time you make changes to your code and want to run your code, run the following commands:

$ cd ~/cs3231/asst<n>-src/kern/compile/ASST<n>
$ bmake && bmake install

Note: If you have added more files or changed #includes, then you should use bmake depend as well. Remember to replace <n> with the appropriate assignment number.

Running OS/161 (with or without GDB)

Do each time you want to run/ debug your code

terminal 1

terminal 2

Run OS/161 without GDB
$ cd ~/cs3231/root

$ sys161 kernel



Debug from the beginning
$ cd ~/cs3231/root

$ sys161 -w -p 16161 kernel

sys161: Waiting for debugger connection..


sys161: New debugger connection
$ cd ~/cs3231/root


$ os161-gdb kernel


(gdb) connect

Debug already running instance
$ cd ~/cs3231/root

$ sys161 -p 16161 kernel

OS/161 kernel [? for menu]:

<Execute various commands in OS/161>

ctrl+G

sys161: Waiting for debugger connection..



sys161: New debugger connection
$ cd ~/cs3231/root










$ os161-gdb kernel

(gdb) connect

Using GBD

Do when gdb is attached to an instance of OS/161 (i.e. after option 2 and 3 of the previous step)

The OS/161 instance is currently stopped at a breakpoint and is awaiting instructions from the debugger. Most commonly we want to set breakpoints, then continue through our program.

See All GDB Content for more information.

Module author: Liz Willer <e.willer@unsw.edu.au>

Date

2020-01-29