CS611
Programming Assignment 5
Fall 2000

Implement a simple dynamic linker for the Alpha architecture.

You need to write a function called dynamicLinker with the following prototype:

void dynamicLinker(PLTentry* e);

The single parameter is a pointer to a Procedure Linkage Table (PLT) entry. A PLT entry has four fields:

• procedureName - string containing the name of the procedure described by the PLT entry.
• objectFileName - string containing the name of the object file that defines the procedure, if the procedure is not yet linked to the running program.
• procedureAddress - address of the procedure if it is already linked to the running program; otherwise it is the address of a "stub" function that will invoke the dynamic linker to bring the procedure into the program.
• status - status flag that indicates whether the procedure is currently linked to the running program or not. This field takes on two integer values, with these symbolic names: PLT_INSYMBOL (procedure is in the program) and PLT_OUTSYMBOL (procedure is not in the program).

The dynamic linker should take the PLT entry and use it to load the procedure it describes into the running program. This will involve reading the object file to access both symbol information and code. The symbol information is stored in a PLT in the object file. The code is a series of functions. Each function consists of encoded Alpha instructions, preceded by two quadwords, which will be described below.

The format of the object file is the following:

1. quadword containing the number of PLT entries that follow
2. the PLT entries
3. quadword containing the length in bytes of the code that follows
4. the code

A PLT entry is stored in the object file in the following manner:

• The two strings are stored in C format, i.e. null terminated. These strings should be fewer than 256 bytes in length (including the null).
• The address and status fields are stored as quadwords.

All multibyte quantities (actually there are only quadwords) stored in the object file are stored in Little Endian format.

Dynamic linking is made possible by user programs calling procedures via the PLT. The call is made using the address field of the procedure's PLT entry. If the procedure has already been loaded into the program, then its address will be in the PLT entry and the function will therefore be called. If the procedure has not already been loaded, then the address field will contain the address of a "stub" function, which determines which PLT entry is being accessed, then calls the dynamic linker passing a pointer to the PLT entry.

A dynamically linked procedure finds the PLT by accessing the two quadwords that immediately precede the procedure's code. The quadword immediately in front of the code contains a pointer that points to a pointer to the PLT. (Be careful! There is an extra level of indirection!) The second quadword, which is immediately in front of the first quadword, contains an offset into the PLT where this procedure's PLT entries are stored. It was the responsibility of the dynamic linker to properly set these two quadwords when the object file containing this procedure was loaded into memory.

When loading an object file, its PLT entries should be appended to the running program's current PLT. The current PLT is pointed to by the global variable PLT. The length of the current PLT is stored in the global variable PLTlength. To append the new PLT entries, you must allocate space to accomodate the new size of the table. Then copy the old entries to the new space, followed by the new entries read from the object file. You then can update the PLT and PLTlength globals. You should also free the memory of the old table, if the global variable PLTstatus is set to PLT_DYNAMIC_TABLE. And you should set PLTstatus to PLT_DYNAMIC_TABLE.

As you combine the two sets of PLT entries, you need to resolve the symbol information. There are two basic cases:

• A symbol defined in the object file may appear in the old table as an outsymbol. The old PLT entry should have its status changed to PLT_INSYMBOL and the correct procedure address should be stored in its address field. Note that there could be multiple old PLT entries for the symbol (because we append rather than merging PLT entries).
• A symbol that is an outsymbol in the object file may appear as an insymbol in the running program. The PLT entry loaded from the object file must have its status flipped to become PLT_INSYMBOL and its address field should be set from the old PLT entry for the symbol.

Each insymbol PLT entry in the object file should be used to set the two preceding quadwords for the corresponding function. The address field of an insymbol PLT entry in an object file expresses the address of the procedure/function as its byte offset from the beginning of the code section of the object file. Therefore the location of the function in memory can be determined from the base address of where the object code was loaded into memory. (You need to allocate space for this code.) This then allows you to find the two quadwords and appropriately set their values. You also need to change the PLT entry's address field to be the actual address of the function after it is loaded into memory.

As outsymbol entries are read from the object file and appended to the program's PLT, their address fields must be filled in with the address of the "stub" function, which is called DLstub.

After completing the linking process, the linker should re-call the procedure that caused the linker to be called.

When reading an object file you should validate its structure and contents. Here is a (possibly partial) list of the errors you might encounter:

• can't find object file
• unexpected EOF
• string too long
• null symbol name
• invalid symbol status

Errors might also occur during the linking process. Here is a (possibly partial) list of the errors you might encounter:

• duplicate insymbol
• faulting symbol still unresolved
• out of memory (malloc fails)

The directory ~cs611/public/prog5 contains a stub for the dynamic linker in dynamicLinker.c. You should closely examine the header file in this directory, DL.h, which contains definitions for the PLT, among other things. The directory also contains the source code for the DLstub function, a Makefile, and a test program that utilizes two object files. There is also a tool for generating object files. Look at the Makefile for information on how to construct both test programs and object files. Also look at the comments in the C source for the test programs (zero.c and one.c) for more information. Additional tests will distributed closer to the due date.

Successfully completing the dynamic linker for functions with no arguments will be worth 80% of the points for this assignment. Supporting functions with up to six arguments will be worth another 10%. And supporting functions with an arbitrary number of parameters is worth another 10%. In all cases you need to support function return values.

Your implementation should be performed using C. Put all your C code in the dynamicLinker.c file. To support arguments you may need to write some assembly code. If so, put your assembly code in the DLstub.s file.

Your program will be graded primarily by testing it for correct functionality. However, you may lose points if your program is not properly structured or adequately documented. Remember that with assembler code documentation is even more important than with C programs.

Your programs should be submitted for grading from a UNH CIS Alpha machine (e.g. alberti.unh.edu). Submit at most two files, dynamicLinker.c and possibly DLstub.s. To turn in this assignment, type either:
~cs611/bin/submit prog5 dynamicLinker.c
or:
~cs611/bin/submit prog5 dynamicLinker.c DLstub.s

Submissions can be checked by typing:
~cs611/bin/scheck prog5

To receive full credit for the assignment, you must turn in your files prior to 8am on Monday November 20. Late submissions will be accepted at the penalty of 5% per day up to one week late.

Remember: as always you are expected to do your own work on this assignment.

Comments and questions should be directed to pjh@cs.unh.edu