You may have noticed that debuggers (e.g.,
gdb) do a
remarkably good job of understanding source-code-level information
entered from the keyboard.
Among other things, they know which declaration of a function,
variable, or type is live at each
point in a program. This is because the compiler (when invoked
with appropriate command-line switches) includes symbol table
information in its assembly language output.
In the current assignment you will leverage this information to
implement a web-based cross-reference tool.
Gcc is capable of producing symbol table information in a
formats. One of the most
comprehensive of these—and the one used by default on
Linux—is known as DWARF. It captures details
about variables, functions, typedefs, etc., including the locations in
the source code (file and the line number), at which they are
declared. To embed DWARF information in your object file, compile
gcc -g3 -o myprogram myfile1.c myfile2.c ...The
gccto include detailed debugging information, including macro definitions, in the symbol table.
After compilation, DWARF information can be extracted from an executable
or object file in any of several ways.
Arguably the easiest is to use the
dwarfdump tool, which
you can find in
~cs254/bin/ on the
Your task in this assignment is to write a scripting program—call
xref—that uses the
(also found in
construct a web page that contains
side-by-side assembly language and corresponding source
code for a given program. The assembly and source should be lined
up nicely on the page: the first instruction in
each contiguous block of instructions that come from the same line of
source should be horizontally aligned with a copy of that source
line. Source lines without corresponding assembly instructions
(e.g., comments and declarations) should be presented immediately above
the first occurrence of the following source line, or at the bottom of
the page if there are no more lines with corresponding assembly
code. In the rare case that a single assembly instruction is
generated for multiple lines of source, the instruction should line up
with the final source line.
Source for in-lined functions should be displayed in-line, even if it
comes from a different source file than do the surrounding lines.
Note that some source lines (e.g., loop headers) may
contribute to two or more non-contiguous blocks of instructions; in this
case, the source line may appear more than once on your web page. For
the sake of clarity, you should print the second and subsequent
occurrences in a “grayed-out” color.
Vertical white space should be inserted as needed to make
the alignment work out.
If the above instructions seem a little vague, that’s because they are. This assignment is underspecified. Part of your job is to exercise good judgment and to build a tool that does a reasonable job most of the time. It probably won’t be perfect.
Note that your task is in some sense “assembly centric”: you are to display assembly-language instructions, in address order, and show next to them the corresponding source. In many cases the instructions for a given function—or even an entire file of source code—will be contiguous, but this may not always be the case: compilers are free to reorder blocks of instructions—even to the point of interleaving code from different functions or files. I recommend you keep track of which files contain source that corresponds to some instruction(s) in the assembly code. Within each such file, you can then determine which lines correspond to some assembly. This in turn will allow you to identify the source lines that do not correspond to any assembly, and should therefore be output immediately before the first occurrence of the next line. For extra credit (see below) you are welcome to try formatting your output in a more “source-centric” way, but this is a significantly more difficult (and more poorly defined) undertaking.
In addition to displaying side-by-side assembly and source, you should
arrange for every fixed-address control transfer (branch or subroutine
call) in the assembly code to be rendered as an HTML link that will
scroll or jump the browser to the target of the branch. You can
ignore code that transfers indirectly to a location contained in a
register. You can also ignore transfers whose targets are
outside the code you are presenting (i.e., in a library package).
When viewing your web page, a user should be able to jump to the
destination of a subroutine call (or the continuation of a loop) by
clicking the link in the neighboring assembly code.
After following a link, one can return to the original
location by using the browser’s back button.
Be aware that C allows
static functions in different source
files to have the same name. Be sure you identify and
differentiate among these, so your links always go to the right
You may write your program in Perl, Python, Ruby, or (with
instructor’s permission) some other scripting language.
If you’re undecided, I recommend either Perl (because of its
ubiquity in systems administration) or Ruby (because of its elegant
merger of imperative and functional programming).
Python has the disadvantage of substantially less succinct notation for
pattern matching, which you’ll be doing a lot of in this
assignment. You will almost certainly want to work on the
csug machines: behavioral details of
objdump vary across versions and platforms, so you code
is unlikely to port easily from elsewhere.
xref program should be run in a directory containing
an executable program (built with
-g3) and a collection of
C source files from which the
program was built (all
.h files other
than standard library header files).
When invoked with the name of the executable (e.g.,
myprogram) as a command-line
objdump ‑d myprogramand examine the output to obtain the assembly language version of the program.
dwarfdump myprogramand examine the output to learn the names of the source files and the code ranges in the program corresponding to each line in those files.
HTML, with an extra file
index.htmlthat contains a link to the main HTML file(s), a location-specific link to the beginning of the code for
main, and information about when and where the
xreftool was run.
For a hint as to what your side-by-side code might look like, you can
objdump -Sd to see interleaved source and
assembly (this feature may be a little buggy; no guarantees).
You might also try the “
disassemble /m” command in
however, that you are required to build your pages without
using these extra mechanisms; instead, you have to glean
the correspondence from the
debug_line table in
If you have taken CSC 252, you may know that the correspondence between
source and assembly code is not always very intuitive, especially at
higher levels of optimization. You may want to start with
programs that have been compiled with
‑O0. We reserve the right to test
(and grade!) your code on arbitrary programs, however, including those
that have been compiled with
As in previous assignments, you may work alone or in teams of two.
If you choose to work in pairs, one possible division of labor is for one
partner to write the code that inspects the
and the other to use this information to create the HTML files.
If you do this, be very careful to agree on the information you need,
and read each other’s code to look for errors.
Be sure to follow all the rules on the Grading page. As with all assignments,
use the turn-in script:
~cs254/bin/TURN_IN. Put your write-up in a
README.pdf file in the directory in
which you run the script.
Be sure to include your name(s)—both of them, if you’re
working as a team.
Also be sure to describe any
features of your code that the TAs might not immediately notice.
To illustrate the functionality of your code, you may want to include
test data, contained in subdirectories.
DWARFcan be found in various places the web, notably
www.dwarfstd.org. There’s a pretty good tutorial introduction at this site. (The tutorial includes some history and some encoding information that you won’t actually need, but even those parts are interesting.) The official DWARF 4 Standard is also available, but it’s over 300 pages long, and almost certainly more than you need.
typedefnames, struct and union tags, structure and union field names, enum constants, labels, and/or macros.
Before the end of the day on Wednesday, October 25, each student should complete the T4 trivia assignment found on Blackboard.