Project 0: Fun with assembly

Due: Tuesday, September 6, 2016, 23:59

Goal

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.

Collaboration

You may work on this project in collaboration with a single partner.

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 code on an x86 Linux machine. You are free to write your code on your own personal machine or on a departmental machine (e.g., bertvm or ernievm).

If you don’t have an x86 Linux machine and you don’t want to use the departmental servers, one good choice is to install VirtualBox and run a Debian virtual machine. There are many guides describing the steps to do that on the Internet.

The Code

This semester, you are going to use GitHub to (1) download the starter code, (2) collaborate with your partner, and (3) submit your solutions.

To download the code repository, follow these steps.

1. Find a partner in the class.
2. If you do not already have one, create a free account on GitHub.
3. Click the link for Project 0 on BlackBoard. This will take you to GitHub Classroom (which may ask you to log into GitHub).
4. Once you’ve logged in, you will be asked to select a team or create a new one. Exactly one of you or your partner should create a team, the other should select the appropriate team. Important: Do not select the wrong team as you cannot change it later!
5. This should create a new repository filled with starter code, testing code, and a script, submit.sh, which you will use to submit your code.

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.

Deliverables

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.

All of your code and your comments should be in the single file bn.s. You may not modify any other file in the repository as those changes will not be used. In particular, you may not modify the Makefile or any of the tests.

To build your code, run make. To run the test suite, run make check.

Submitting

You may submit your code at any time and you may do so as many times as you wish. Note: If you submit after the deadline given above, you will be penalized according to the course policy, even if a previous submission prior to the deadline worked perfectly.

To submit, follow these simple steps.

1. Commit all of your code (which should just be bn.s).
2. [Optional] Push your code to GitHub. (You should be doing this throughout your development process anyway.)
3. Run ./submit.sh.

Once you submit, a new branch called submission will be created on your repository on GitHub. This will cause our test machine to download and test your code. Once it has finished testing the code, a comment will be left on your commit on GitHub. The submit.sh script will print out the URL where the comment will appear. (It may take a few minutes for the comment to appear, depending on the load of the machine.)

Hints

• gcc -m32 -S is your friend! If you run that on a C file, it will produce assembly.
• 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.
• You can get gcc to use Intel syntax (instead of AT\&T) for x86 with gcc -S -masm=intel.
• For bn_hex2bn, a helper function that converts a single hex digit to an int can be very useful.
• The standard library function isxdigit() can be helpful as well.
• Several functions require ensuring that the bn has enough limbs. This can also be factored out into a helper function.
• 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.
• You’re likely going to want to have a copy of the Intel manuals for reference. (See Resources on the main course webpage.)

SSH with VirtualBox

If you want to run a VirtualBox VM locally, you may want to set up ssh so that you can ssh into the VM rather than typing into the tiny console window.

You can forward a TCP port from your host machine to the VM using VirtualBox. Select the Debian virtual machine you have created and go to 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 debian (where user is the non-root user I created):

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