=================== Xv6 =================== -------- Overview -------- Xv6 is an instructional OS consisting of a stripped down version of unix. To get ready to work within xv6, please start reading the `xv6 book `__ as well as the other xv6 resources listed below. --------- Resources --------- - `xv6 book `__ - `xv6 indexed/cross referenced code `__ (all 9099 lines of it :-) - `Official website `__ --------------------- Getting Started (SSH) --------------------- Since the lab sessions will be online, you will need an SSH client to connect to sledge or a VM. If you are using Linux or macOS, you should already have a ssh client installed by default. If you are Windows 10, the best option would be the Windows Subsystem for Linux (WSL). You can follow the `installation guide `__ and the `tutorial `__. I would also recommend the `Windows Terminal `__. If you are using an earlier version of Windows, you can use `PuTTY `__. ------------------------ Getting Started (sledge) ------------------------ In sledge, most software is pre-installed, so you only need to download xv6. .. code-block:: bash [sledge] $ cd ~ [sledge] $ git clone https://github.com/mit-pdos/xv6-public.git xv6 ... [sledge] $ cd xv6 [sledge] $ make [sledge] $ echo "add-auto-load-safe-path $HOME/xv6/.gdbinit" > ~/.gdbinit -------------------- Getting Started (VM) -------------------- If you are using macOS, an earlier version of Windows, or your Linux distribution has trouble compiling xv6, you can use a Linux virtual machine (VM). To save the time of installing Linux in the VM, you can use Vagrant. 1) Download and install Virtualbox/Vagrant/SSH client - Download and install the latest version of virtualbox at https://www.virtualbox.org/wiki/Downloads - Download and install the latest version of vagrant at http://www.vagrantup.com/downloads.html - Windows: SSH client WSL (see above) or `PuTTY `__. Note: Ubuntu users may want to use the following commands to install Virtualbox and Vagrant .. code-block:: bash [host] $ sudo apt-get install virtualbox [host] $ sudo apt-get install vagrant 2) Add guest OS and run the VM .. code-block:: bash # download a 64-bit VM [host] $ vagrant box add ubuntu/xenial64 ==> box: Loading metadata for box 'ubuntu/xenial64' box: URL: https://atlas.hashicorp.com/ubuntu/xenial64 ==> box: Adding box 'ubuntu/xenial64' (v20170331.0.0) for provider: virtualbox box: Downloading: https://atlas.hashicorp.com/ubuntu/boxes/xenial64/versions/20170331.0.0/providers/virtualbox.box ==> box: Successfully added box 'ubuntu/xenial64' (v20170331.0.0) for 'virtualbox'! # move to your working directory [host] $ mkdir cs153 [host] $ cd cs153 # initialize the VM [host] $ vagrant init ubuntu/xenial64 A `Vagrantfile` has been placed in this directory. You are now ready to `vagrant up` your first virtual environment! Please read the comments in the Vagrantfile as well as documentation on `vagrantup.com` for more information on using Vagrant. # launch! [host] $ vagrant up Bringing machine 'default' up with 'virtualbox' provider... ==> default: Importing base box 'ubuntu/xenial64'... ... [host] $ vagrant ssh Welcome to Ubuntu 16.04.2 LTS (GNU/Linux 4.4.0-71-generic x86_64) ... ubuntu@ubuntu-xenial:~$ 3) Once you have the VM up and running, let's initialize your VM for this course, following the same steps as in WSL section. --------------------- Getting Started (WSL) --------------------- If you are using WSL or Linux (VM), install a customized QEMU (for better debugging support) and xv6. .. code-block:: bash # in the VM, install toolchain [wsl|vm] $ sudo apt-get update [wsl|vm] $ sudo apt-get install -y build-essential gdb git gcc-multilib # install the patched QEMU # [wsl|vm] $ cd ~ [wsl|vm] $ git clone https://github.com/mit-pdos/6.828-qemu.git qemu [wsl|vm] $ sudo apt-get install -y libsdl1.2-dev libtool-bin libglib2.0-dev libz-dev libpixman-1-dev [wsl|vm] $ cd qemu [wsl|vm] $ ./configure --disable-kvm --disable-werror --target-list="i386-softmmu x86_64-softmmu" [wsl|vm] $ make [wsl|vm] $ sudo make install # finally it's time for setting up xv6 # [wsl|vm] $ cd ~ [wsl|vm] $ git clone https://github.com/mit-pdos/xv6-public.git xv6 ... [wsl|vm] $ cd xv6 [wsl|vm] $ make # NOTE: allow local gdbinit to be loaded (only done once) # [wsl|vm] $ echo "add-auto-load-safe-path $HOME/xv6/.gdbinit" > ~/.gdbinit --------- Debugging --------- Get familiar with `development environment `__. Open two terminal windows (and enter the VM if not on sledge). Alternatively, you can also try `screen `__ (`shortcut `__) or `byobu `__ (not on sledge). .. code-block:: bash # in window one [wsl|vm|sledge] $ cd ~/xv6 [wsl|vm|sledge] $ make qemu-nox-gdb # this starts up QEMU, but QEMU stops just before the processor # executes the first instruction and waits for a debugging # connection from GDB. # in window two # # NOTE: -q removes the annoying init message # [wsl|vm|sledge] $ cd xv6 [wsl|vm|sledge] $ gdb -q + target remote localhost:26000 warning: A handler for the OS ABI "GNU/Linux" is not built into this configuration of GDB. Attempting to continue with the default i8086 settings. The target architecture is assumed to be i8086 [f000:fff0] 0xffff0: ljmp $0xf000,$0xe05b 0x0000fff0 in ?? () + symbol-file kernel # to terminate, for now, in window 2 [wsl|vm] $ killall qemu-system-i386 # for sledge [sledge] kill $(pgrep qemu) Read more on `how to use gdb with QEMU/JOS `__. Tips: - You can use `cprintf()` to print debugging information to the console. For example, you can check whether values of certain variables match your expectations. - When error happens, xv6 will output error messages like follows: :: lapicid: 0: panic: trap 80483231 80d48a34 80033423 0 0 0 0 0 0 0 in this message: - ``0`` is the number of the CPU that was running when the panic occurred. - ``trap`` is the message that was passed to the panic function. Usually, the xv6 code is written so that there is only one call to ``panic`` with a particular message, so this will precisely identify where the panic occurred. - ``8048323``, ``80d48a34``, etc. are the hexadecimal addresses of the code that was running when the ``panic()`` was called. You can look up these addresses in ``kernel.asm``, which contains the full assembly of the xv6 kernel, interleaved with its machine code, the addresses of each instruction, and the corresponding C code.