Project 0

Due: Tuesday, September 9, 2014, 23:59


The goal of this project is to become familiar with assembly language programming. This project will use 32-bit x86 assembly. Other projects will involve some subset of ARM, Thumb, and x86-64. Fortunately, once you become familiar with one assembly language, others are not too difficult.


You may work on this project in collaboration with a single partner as described on the main page.

You must not discuss the project with anyone other than your partner and course staff. You may use online resources for general reference, but not to search for solutions to specific questions posed in this project.

The Environment

You (and we, for grading) will run your programs in a VirtualBox virtual machine. To use this VM on your personal computer (Windows, Mac OS X, and Linux are supported), you will need to download the virtual machine image provided on the course website (see Setting up the Environment below) as well as VirtualBox from the VirtualBox website.

The VM has Ubuntu installed as well as a number of useful utilities such as vim, ssh, and wget.

The Assignment

You are going to implement functions that operate on unsigned big nums. You have to implement the five functions described in bn.h in 32-bit x86 assembly in the file bn.s.

Some stubs have been provided so that the initial code will compile but will not run correctly.


You will use Blackboard to turn in a single file bn.s containing all of your code and writeup. In particular, this means that you cannot modify any of the other files since we will be using our own version to test your code.

You may wish to add additional tests in main.c to check that your code works properly. We will test using a more extensive test suite.

At the top of bn.s add a comment with the names of everyone in your group. Additionally, for each function that you write (including any helpers you produce), add a comment describing what the function does, what its parameters are, and (briefly) how it works. This is required. Failure to do so will result in lost points.


  1. gcc -m32 -S is your friend! If you run that on a C file, it will produce assembly.

  2. You should look at how gcc emits code for function calls and make sure you follow suit. See Wikipedia for details on stack alignment and the x86 cdecl calling convention used by Linux.

  3. You can get gcc to use Intel syntax (instead of AT&T) for x86 with gcc -S -masm=intel.

  4. For bn_hex2bn, a helper function that converts a single hex digit to an int can be very useful.

  5. The standard library function isxdigit() can be helpful as well.

  6. Several functions require ensuring that the bn has enough limbs. This can also be factored out into a helper function.

  7. When adding numbers, you'll want to use the adc instruction in a loop. The clc instruction can be used to clear the carry flag and the loop instruction can be used to decrement ecx and branch if nonzero without changing flags. Helpfully, inc and dec do not affect the carry flag.

  8. You're likely going to want to have a copy of the Intel manuals for reference. (See Resources on the main course webpage.)

Setting up the Environment

On your own machine, you will need to install VirtualBox. Follow the instructions on the VirtualBox webpage. If you have trouble, read the documentation.

  1. Download the VM sandbox-1.1.ova (1.1 GB).

  2. From the File menu, choose the Import Applianceā€¦ menu option.

  3. Open sandbox-1.1.ova and follow the steps to import.

  4. In the main window, select the sandbox-1.1 VM and start it by clicking on the Start button.

  5. Log in to the VM. There is one account user with the password user. The user account can use the sudo command to run commands as root (or sudo -s to get a root shell) but that should not be needed for this project.

  6. Download the project 0 tarball in the virtual machine.

  7. Unpack project0.tar.gz and use the Makefile to build the code.

  8. It is very useful to be able to ssh into the VM. You can forward a TCP port from your host machine to the VM using VirtualBox. Select the sandbox virtual machine and goto Settings > Network > Port Forwarding. The VM may already be configured to forward a port. The setting I use has protocol TCP, host port 2222, and guest port 22. On my host machine, I have the following lines in my $HOME/.ssh/config file so that I can ssh to the VM by running ssh sandbox:

Host = sandbox
HostName = localhost
Port = 2222
User = user