Mini-lab setup guide

1. Use class machines at CIMS
2. Use class machines remotely
3. Set up home Linux machine for minilab: Install compilation tools
4. Set up home Linux machine for minilab: Install Bochs
5. Set up home Linux machine for minilab: play with the QEMU Emulator
6. Boot WeensyOS For Real

Use class machines at CIMS

The compilation tools and PC emulator Bochs are available in a shared directory. Include the shared directory to your PATH and MANPATH like this if you are using tcsh shell:

% setenv PATH /home/jinyang/minilabenv/bin:${PATH} 
% setenv MANPATH /home/jinyang/minilabenv/man:${MANPATH} 

If you are using the bash shell, type:

$ export PATH=/home/jinyang/minilabenv/bin:${PATH} 
$ export MANPATH=/home/jinyang/minilabenv/man:${MANPATH} 

Depending on which shell you are using, append the above two lines to your ~/.bashrc or ~/.tcsh file, so they are automatically executed by the shell every time you log in.

To find out which shell you are currently using, type echo $SHELL.

To check that your PATH and MANPATH are set up correctly, type echo $PATH and echo $MANPATH

Use class machines remotely

If you have a Linux machine at home, you can easily log into class machines by first logging into the access machine using ssh -X YOURUSERNAME@access.cims.nyu.edu and from there type ssh -X to log into any of the class machines. The "-X" option of the ssh command will make remote X windows show up on your home screen automatically. If you are doing remote login from the CIMS network, you can directly ssh into the class machines without going through access.cims.nyu.edu first.

If you have a Windows machine at home, the easiest way to work on minilabs from home is to use the Cygwin system to log in to the class Linux machines. Cygwin is quite popular, so it is unlikely that you will mess up your computer by installing it. But if you don't want to go through this procedure, you either have to install a Linux box at home or show up on campus to use the class machines.

Here's how to install Cygwin on your Windows machine and log in to class machines to do the minilabs.

1. Install Cygwin/X. Follow this procedure. Make sure you select the "xorg-x11-base" package and the "openssh" package. This sets up a Unix-like environment on your Windows machine, including an X server. X is the protocol used by the Solaris machines to display images, such as the Bochs window, on remote computers.
2. Start the Cygwin X server by running startxwin.bat. "Run /usr/X11R6/bin/startxwin.bat by double-clicking it in Windows Explorer." http://x.cygwin.com/docs/ug/using.html
3. Follow these instructions to log in to a class machine using ssh. You will do something like "ssh -Y -l yourusername classmachine.cs.nyu.edu" from the X terminal you started up on your machine.

Set up home Linux machine for minilab: Install compilation tools

If your machine has a standard Ubuntu installation of 7.10 or higher, its default compilation environment should just work fine (If you've not installed gcc yet, do apt-get install gcc-4.1 binutils)

If you don't have a standard Ubuntu installation, make sure your native gcc compiler is 3.0 or higher (type gcc --version). You should also check that your native GNU binutils build for i386 ELF target. To check, run objdump -i. If the second line is elf32-i386, you should be okay and try to compile the Minilab code.

If compilation fails using your native binutils and gcc, you have to configure and build them yourself. Follow the instructions below:

1. Download binutils-2.18.tar.bz2 and gcc-core-4.2.2.tar.bz2
2. Unpack these archives using "bzcat FILE | tar xf -".
3. Compile and install binutils using the following commands. (Supply your install directory prefix for PFX.)

   cd binutils-2.18
   ./configure --target=i386-jos-elf --prefix=PFX
   make
   make install
   cd ../gcc-4.2.2
   ./configure --target=i386-jos-elf --prefix=PFX --enable-languages=c --disable-libssp
   make
   make install

Set up home Linux machine for minilab: Install Bochs

If you are running a Debian-style Linux distribution (e.g. Ubuntu), simply type ``sudo apt-get install bochs'' The pre-built binary package of Bochs might not be compiled with the same options as we use for the class, but it probably be fine.

If you want to build Bochs from source, download Bochs 2.3.5 from the Bochs download page. Configure and install as follows:

gzcat bochs-2.3.5.tar.gz | tar xf -
cd bochs-2.3.5
./configure --enable-cpu-level=6 --enable-disasm \
    --enable-debugger --enable-x86-debugger \
    --enable-iodebug --enable-instrumentation \
    --enable-4meg-pages --enable-pae --enable-global-pages \
    --enable-all-optimizations --with-all-libs \
    --prefix=PFX
make
make install

You may also want to run ./configure --help and look at the available options.

./configure --with-carbon --without-wx \
    --enable-cpu-level=6 --enable-disasm \
    --enable-debugger --enable-x86-debugger \
    --enable-iodebug --enable-instrumentation \
    --enable-4meg-pages --enable-pae --enable-global-pages \
    --enable-all-optimizations \
    --prefix=PFX

Check out the online Bochs user manual if want to learn more about Bochs.

Set up home Linux machine for minilab: play with the QEMU Emulator

The QEMU Emulator is much, much faster than bochs, and has a slightly slicker GUI. The QEMU command line that most resembles our bochs setup is this:

qemu -hda imagefile -parallel stdio

The QEMU monitor, which is like the Bochs internal debugger, is accessible by pressing Ctrl-Alt-2 inside the QEMU window; return to normal display with Ctrl-Alt-1. QEMU tends to take control of your mouse given any opportunity. If you can't find a mouse pointer, check the QEMU title bar for text like "Press Ctrl-Alt to exit grab"; if it's there, press Ctrl-Alt to regain control.

Boot WeensyOS For Real

Here's how to alter your Linux machine's Grub bootloader configuration so you can boot WeensyOS for real!

1. Add the following lines to /etc/grub.conf:

   title WeensyOS
   	kernel /weensyos
   

2. Copy the file named obj/OSNAME-kern to /boot/weensyos. For example, in Lab 1, you would:

   # cp obj/mpos-kern /boot/weensyos
   

3. Reboot and select "WeensyOS" from the Grub boot menu!