Programming Assignment Zero: PA0

Due Wednesday night, April 8 @ 11:59pm)

The purpose of this assignment is to introduce you to SPARC assembly language instructions and the sytnax used in assembly files, to help you use make and a Makefile to compile your C and assembly language source files, to introduce you to the GNU debugger gdb, lint (static C source code checker), and the turnin facility to turn in your programs. This assignment is not worth very much of your grade so make all the mistakes now :-). The C and assembly language source files and a Makefile will be provided. Please DO NOT CHANGE the Makefile rules unless instructed to do so.

Procedure:
1. Log in using your class account and make a directory called pa0.
(Do the following at the prompt)

2. Type mkdir pa0 <press enter>

3. Type ls <press enter> to list out the files and directories in the current working directory.

Here is the actual output :

ieng9.ucsd.edu% mkdir pa0

ieng9.ucsd.edu% ls
pa0

ieng9.ucsd.edu%

At this point, you are encouraged to check out the Subversion Notes page to set up a Subversion repository for pa0 or CVS Notes page to set up a CVS repository and module for pa0.

4. cd to directory pa0 (cd pa0).

5. Type the C and assembly source files provided in class into the files pa0.h, main.c, printHello.s, printBirthDateInfo.c, and sum3.s, respectively. You can use your favorite editor (vi/vim, emacs, pico, etc. -- we highly discourage using TextEditor) to type the files and save them in the pa0 directory. Use your real cs30x login, name, etc. in place of the dummy student info.

6. There is a Makefile template for PA0 in the public directory (~/../public). Copy the PA0 Makefile into your pa0 directory. To accomplish this do the following at the command prompt, pressing Enter after each line. :

ieng9.ucsd.edu% cd ~/pa0
(Just to make sure you are in the pa0 directory.)

ieng9.ucsd.edu% cp ~/../public/Makefile-PA0 Makefile
(Note you are naming the copy in your pa0 directory Makefile without the -PA0 suffix.)

ieng9.ucsd.edu%

6. Now you have the source files (which you created) and the Makefile in your pa0 directory. You need to run "make" to compile these files. Simply type make at the prompt. This will create the executable necessary to run the program -- by default, the target executable will be named a.out. Make will abort if any warnings are found by lint or if any errors are found in the program code by the compiler, assembler, or linker.

7. After compiling using make just type a.out at the prompt to execute your code. You should see

Hello, my name is: Joe Jane Student

My birth date is: December 17, 1978

The sum of 1, 2, and 3 = 6

printed out on your screen (it should have your own personal info).

8. Once you have checked, compiled, executed your code, and finished your README file (see below), and you are ready to turn it in, you should do make clean in order to remove all the object files, lint files, core dumps, and executables.

9. See a TA/Tutor on duty to get checked off for completing a simple debugging exercise.
This is important and part of this assignment.

README

Along with your source code, you will be turning in a README (use all caps) file with every assignment. For this assignment the README file should contain your name and cs30x login userid and answers to the debugger questions.
Follow the instructions below and answer the questions in your README file

At any time while you are in gdb, you can use the "help" command to get more info on a particular command. For example, help next or just h next as a shortcut. For a more complete information on gdb, see the on-line gdb manual.


To start the gnu debugger, at the prompt type : 
        gdb <executable-name>

In our case it will be 
        gdb a.out

Once the debugger is loaded, type the following:  
	break main
	run
	display/i $pc

1) What line do you see printed to the screen

2) What happens if you type step at this point? Why?

(you will need to type run again to be able to do the following)

Type list. This should show you about 10 lines from your main program.
(you can type list at any point during the debugging process
and it will show you the "C" code that is around the line you are executing)

do stepi until you see the following line : 
	<printHello+4>:    sethi  %hi(0x20400), %o0

3) Type x/s $i0. What do you see printed to the screen?

4) Do nexti until you see the following line : 
   	<printHello+24>:   ret

   Print out the value of %o0. It should contain the return value from 
   the printf function (printf returns the number of characters it printed out)
   To view this value you will have to use print command.
   Type p/d $o0. What value do you see?

Type disassemble. This should show you about 10 lines from your printHello.s file.
(you can type disassemble at any point during the debugging process and it will show you 
the "assembly" code that is around the line you are executing)

5) What is a breakpoint? How do you set one?

6) What function are you debugging if gdb displays:
   <foobar+32>:    sethi %hi(0x20400), %o6

7) What is the difference between step and next?
   What is the difference between step/next and stepi/nexti?

8) What are $o0, $i0, etc, refering to?

9) What is the difference between the x and p commands?
   - Which should you use to look at the contents of a register?
   - Which should you use to look at something in memory?
   - What do x/s and p/d mean (what do the /s and /d specify)?


To finish running the executable, type next until the program exits
Type q to quit the debugger and return to the shell prompt.

If you need to debug a program after getting a core dump, start gdb as

	gdb <executable_name> core

Turn in

Note: The turnin facility will be used for all your future programming assignments too. So get familiar with it now.

HOW TO TURN IN AN ASSIGNMENT:

  - First, you need to have all the relevant files
    in a sub-directory of your home directory.
    The sub-directory should be named:  pa#,
    where # is the number of the homework
    assignment.  

  Besides your source/header files, you may also have one 
  or more of the following files.   Note the capitalization
  and case of each letter of each file.

    Makefile:  
      To compile your program with make -- usually provided
      or you will be instructed to modify an existing Makefile.

    README:
      Information regarding your program.
      (This file will be graded, so make sure you turn it in.
      Specifications for README for pa0 are provided above) 

Again, we emphasize the importance of using the
above names *exactly* otherwise our Makefiles won't
find your files.

When you are ready to submit your pa0, type

	cd
	turnin pa0

to submit your files.  Additionally, you can type

	verify pa0

to verify that everything was submitted properly.

Failure to follow the procedures outlined here will result
in your assignment not being collected properly and will
result in a loss of points.  Late assignments WILL NOT 
be accepted.  Therefore, you MUST follow the instructions correctly.

If, at a later point (but before the respective deadlines)
you wish to make another submittal, simply type 

	cd
	turnin pa0

(or whatever the current pa# is) again and the new archive will
replace the old one.  The files aren't actually collected until
after the deadline, so the turnin command merely "packages" the files
for turnin.  To verify the time on your submission file,
simply type  verify pa0  and it will show you the
time and date of your most recent submission.  The governing
time will be the one which appears on that file, (the system
time).  The system time may be obtained by typing "date".

Your files must be located in a subdirectory of your home
directory which is named paX (where X is the assignment
number).  If the files aren't located there, they cannot 
be properly collected.  Remember to cd to your home directory
first before running turnin.

If there is anything in these procedures which needs
clarifying, please feel free to ask any tutor, the instructor, or
post on the Discussion Board.

Make

Make is a UNIX tool used to compile a group of source files in a particular way based on compilation rules written down in a file named Makefile. Using make makes it much easier to compile large projects. We can look at the sample Makefile provided as part of programming assignment zero to review the techniques of writing a Makefile. The Makefile can be found in the directory "~/../public/" from your class accounts.

The "#" symbol is used for commenting. The Makefile starts by defining some global environment variables to denote the C and assembly source files. These are referred to in the template as C_SRCS, and ASM_SRCS respectively. The object files (.o files) produced by compiling the sources are referred to by the environment variable OBJS. The files defining these variables will change from one assignment to another and it is your responsibility to change it accordingly. This is followed by a set of rules to compile the sources and the target executable file. These rules are standard and need not be modified for the rest of your assignments. If there are any changes we will modify the template and notify you, so you can copy that into your directories.

The rules specify paths for the various compilation tools. Using variables like CC, GCC, ASM, LINT, etc. to define these simplifies the task of writing the rules. Anytime the paths change, we just need to change it at one place. Following this, we have variables to define the various compilation flags. These flags each have a purpose as given below:

-c: This tells the compiler to stop the compilation once the .o files are generated and not go to the linking stage. This is needed because linking cannot be done without having all the .o files first. Most programs are written as multiple source files which are dependent on one another. The -c flag compiles each of them separately into object files.

-g: this option is used to generate debugging information which can be later used by the debugger (gdb).

-err=warn: This tells lint (see below) to consider warnings as errors and exit. As draconian as it may seem this is very useful in writing clean, compliant code.

The standard rules are defined to compile the .c and .s files into object files. You can now see the usefulness of using environment variables. Lastly, we define the target executable, which can be obtained by using the linker to link all the object files. The default name for the target executable is a.out. Note that the -c flag is not used for linking (the LD_FLAGS just define -g). Another target called "clean" is used to clean the directory of all garbage which are not needed for turning in (object files, executables, core files, etc.). You MUST do a make clean before turning in your code. Again, please do not edit the Makefiles rules unless instructed to do so.

Lint

Lint is a static source code checker for C programs. It is advisable to use lint even before using gcc to compile your code. Lint is designed to check C code and does not work on assembly. Lint checks for blatant syntax errors and other errors due to implicit declarations, undeclared headers, and incompatible types.

Example:

int
main( void ) {
   printf("HelloWorld!\n");
}

This will cause a warning if you use Lint. Why? Because the function printf() has not been declared. OK. You fix it by including the Standard C Header file specified in the man page for printf() which contains the function prototype for printf() as follows:

#include <stdio.h>

int
main( void ) {
   printf("HelloWorld!\n");
}

Lint will still give you a warning. This is because the function prototype in stdio.h defines printf() to return an int. So you have to say:

#include <stdio.h>

int
main( void ) {
   (void) printf("HelloWorld!\n");
}

if you want to ignore the return value.

Subversion

You are highly encouraged to use Subversion with all your programming assignments. See the Subversion Notes for this class.

A Subversion module setup script is available at

~/../public/cse30_svnrepo.sh