DMK Work - Procedures

Emacs is a text editor, sort of a word processor for programs. If Emacs recognizes the kind of thing you're editing (program, html, etc) it provides relevant commands. For example, if can help you indent code correctly, run a compiler, run a debugger, etc.

It would probably not be an exaggeration to say Emacs has myriad commands out of the box (with the standard distribution) and probably no single person knows them all. The key to being productive with Emacs is learning the commands you need without spending too much time learning commands that you don't.

When Emacs starts it reads an initialization file, .emacs, from the user's home directory. This file is used to turn on certain features, load optional packages, set preferred keybindings, etc.. A .emacs file is provided for those working with me.

Copy the file from /fac/drk/pub/work/.emacs on the ECE Sun systems to your home directory.
You may have to do this from sol. The file may be edited, it has comments explaining what it does.

Skills

Students are expected to have the following Emacs skills:

Be able to start Emacs and load a file into a buffer.
Be able to look something up using Emacs' info mode.
Understand Emacs shorthand for keys. (For example, M-x find-file RET, see the tutorial.).
Be able to load a file using Emacs' dired mode.
Be able to find text using occur and p-smart-grep (see below).
Be able to do all of the above without referring to documentation.

Using Emacs to Edit a File

Type emacs & or click the kitchen-sink icon. A window should pop up, the frame will be labeled Emacs.
Load a file by selecting "Open File..." from the Files menu. Enter a file name. Note that text appears in the bottom of the main window in an area called the minibuffer, not in a dialog box.
(Once loaded, the file name will appear in the mode line near the bottom of the window.)
Enter text in the buffer to try out the editor.
Select "Save Buffer" from the Files menu to save.
Select "Exit Emacs" from Files to exit.

Using Emacs to Edit C

Special features for editing C code. (Some work with other languages.)

Load a C file into a buffer. Enter C code (any C code). Code should be syntax highlighted, alerting you to some syntax errors and giving you something pretty to look at.
Pressing tab will automatically indent the line the cursor is over. This is useful for catching syntax errors and keeping the description properly indented.
If there is a makefile in the directory pressing F9 will build the program using the Makefile. A window will open showing the compiler output. Clicking on an error message with the center mouse button will move the cursor to the line with the error.

Running the Emacs Tutorial

(The tutorial is an introduction for first-time users.)

Start Emacs.
Select "Emacs Tutorial" from the "Help" menu. Do not attempt to learn everything the first day.
Note: The meta keys on the Sun keyboards are the ones with black diamonds to the left and right of the space bar.

Starting Info, Emacs' Help

(Info provides detailed documentation for Emacs and other programs.)

Start Emacs
Select "Browse Manuals" from "Help" menu.
Following instructions, select the Emacs manual.

Finding a Needle in a Haystack (grep, occur, hi-lock)

Students will have to work on large programs spanning many files. A very common frustration is not knowing what a function does or where it is used. The same holds for variables, structures, and other program elements. Several commands can be used to quickly find these, including occur, p-smart-grep, and hi-lock.

You are using Emacs to edit a C program and would like to see all places that variable "decode_pos" is used in that file:

Enter the command C-q m decode_pos RET.
A window should appear listing each line that decode_pos appears.
To jump to one of the listed lines click on it with the center mouse button or move the cursor over the line and press RET.
For more information see the documentation on occur by pressing F1 f occur RET.

You are using Emacs to edit a C program and would like to see all places that variable "decode_pos" is used in that file and similar files in the same directory:

Enter C-q C-g decode_pos RET.
A window should appear listing file names, line numbers, and lines containing decode_pos.
To jump to one of the listed lines click with the center mouse button or move the cursor over the line and press RET.
The command above is p-smart-grep, something included in the .emacs file you should have copied.

You are using Emacs to edit a C program and would like to see all places that variable "decode_pos" is used in that file highlighted, as though by a yellow highlighting marker.

Enter C-q h decode_pos RET.
All visible occurrences should look like this: decode_pos. For more information enter F1 f hi-lock-mode RET.

Learning the gdb Debugger

Background and Skills

A debugger is a program for finding bugs. Learning a few basic debugger commands might take about 20 minutes; this is too long for most people because (1) they will find the bug in five minutes and (2) that will be the last bug they encounter. If you are one of the rare exceptions, read on.

The procedures here are for running gdb, the GNU debugger, under Emacs. It is also possible, though less convenient, to run gdb from a command line.

To learn gdb follow the steps below.

Run the quick debug session (below).
Choose the tutorial (easier) or gdb documentation (more thorough) listed below.
Be able to access the tutorial or documentation in less than ten seconds when working on a program.
Learn how to set a breakpoint on a line of code within Emacs, print the value of a variable, and resume execution.
Learn how to print expressions (a+b-c) and how to specify whether to print it in decimal, hex, etc.
Learn how to set conditional breakpoints. (For example, break if i> 5.)
Be able to do all of the debugging steps listed above without referring to documentation.

GDB Documentation

GDB Documentation. Available through Emacs' info mode (in the ECE installation, anyway). It is also available on the Web.
GDB Tutorial. There are several on the Web, a tutorial attributed to Richard M. Stallman looks about right. It describes how to use gdb from the command line, which is very similar to using it under Emacs.
Emacs GUD (Grand Unified Debugger) Mode. See the Debuggers node in the Emacs info pages.

Quick Debug Session

Find or write a program that encounters a segmentation fault. In this example the program below, buggy.c, will be used. It should print out the command line arguments (starting with its name). For example if it is started using the command buggy first second it should print out:
```
Arg  0 = "buggy"
Arg  1 = "first"
Arg  2 = "second"
```
The program is:
```
#include <stdio.h>
int main(int argv, char **argc)
{
  int i;
  for(i=0; i<=argv; i++)
    printf("Arg %2d = \"%s\"\n",i,argc[i]);
  return 0;
}
```
Compile the program with the debug switch on (-g for gcc and Sun cc) and (optional) optimization off.
```
[drop] % gcc buggy.c -o buggy -g
```
The program can be debugged even if it was compiled with optimization on, but things will be confusing because the compiler will probably have rearranged or omitted code and the correct value of variables cannot always be printed. The program can also be debugged if it was compiled without the debug switch, but line number and other information will be missing, making it much harder to figure out what's going on.
Load buggy.c into an Emacs buffer: C-x C-f buggy.c RET

Start the debugger in Emacs: M-x gdb RET. In response to the prompt Run gdb (like this): gdb type buggy. A window should open with the following text (or something similar):

Current directory is /home/faculty/koppel/students/web/
GNU gdb 6.1
Copyright 2004 Free Software Foundation, Inc.
GDB is free software, covered by the GNU General Public License, and you are
welcome to change it and/or distribute copies of it under certain conditions.
Type "show copying" to see the conditions.
There is absolutely no warranty for GDB.  Type "show warranty" for details.
This GDB was configured as "sparc-sun-solaris2.8"...
(gdb)

Run the buggy program within the debugger by typing run. Output should be:
```
(gdb) run one two
Starting program: /home/faculty/koppel/students/web/buggy 
Arg  0 = "/home/faculty/koppel/students/web/buggy"
Arg  1 = "one"
Arg  2 = "two"

Program received signal SIGSEGV, Segmentation fault.
0xff2b3218 in strlen () from /usr/lib/libc.so.1
(gdb) 
```
The debugger output indicates that an instruction in the strlen function raised a segmentation fault. Program buggy.c did not itself call strlen, instead it called printf which in turn called strlen.
Find out who called strlen by issuing the command where
```
(gdb) where
#0  0xff2b3218 in strlen () from /usr/lib/libc.so.1
#1  0xff306520 in _doprnt () from /usr/lib/libc.so.1
#2  0xff30815c in printf () from /usr/lib/libc.so.1
#3  0x000106d8 in main (argv=1, argc=0xffbeecb4) at buggy.c:8
(gdb) 
```
Ahhh, our program called printf, which called _doprnt which called strlen. The where command prints a call stack (sometimes called a backtrace). Each level in the stack (there are four in the example) is called a frame. Frame zero is where the program was when it stopped and the highest numbered frame is where the program started.
Switch to frame 3 (the only one containing code from buggy) to see if anything “we” did caused the problem. Type frame 3. Emacs should open a second window (pane) with an arrow pointing to the line holding the printf function call. In addition, the gdb window should show:
```
(gdb) frame 3
#3  0x000106d8 in main (argv=1, argc=0xffbeecb4) at buggy.c:6
(gdb) 
```
Think: Hmmm, there can't be a bug in strlen because that's a widely used and very simple library function and so most problems would be discovered and fixed by now. The printf function is more complicated, maybe that had the bug. But I'm not doing something very fancy with it and printf is widely used so any bug with a simple format string would probably have been fixed by now too. Maybe it's something about the arguments that are being passed. The format string must be okay because it worked in the first iteration, so it's something about i or argc[i]. It's probably not i because printf should be able to print any integer. Okay, let's have a look at what i and argc[i] are.

Print the values of i, argc[i], and argc[2] using the print command as shown below:
```
(gdb) print i
$1 = 3
(gdb) print argc[i]
$2 = 0x0
(gdb) print argc[2]
$3 = 0xffbeee64 "two"
(gdb) 
```
Think some more: Okay, argc[2], the second program argument, looks okay but argc[3] is 0x0. Wait, there isn't a third program argument so that's why argc[3] is zero! Hmmm, printf expected argc[i] to be a pointer to (address of) a string but instead it's zero. Perhaps printf actually tried to copy memory at address zero and that's why there was a seg fault! Our test program is supposed to print out the command-line arguments and so it should stop at two and not three, that's the bug. To fix the program change the for line to:
```
  for(i=0; i<argv; i++)
```
Re-compile.
```
[drop] % gcc buggy.c -o buggy -g
```

And re-run.

(gdb) run one two
The program being debugged has been started already.
Start it from the beginning? (y or n) y
`/home/faculty/koppel/students/web/buggy' has changed; re-reading symbols.

Starting program: /home/faculty/koppel/students/web/buggy one two
Arg  0 = "/home/faculty/koppel/students/web/buggy"
Arg  1 = "one"
Arg  2 = "two"

Program exited normally.
(gdb)

Running PSE

Background

PSE is a program for graphically viewing the output of CPU simulators. For instructions on running PSE see EE 4720 Procedures page.

CVS

Background

CVS is a system used to manage the files that are part of a large computer program. For the moment it is being used in the ECE department to manage two projects, PSE and LSU RSIM.

Further information can be found at the cvs Web site.

Setup

The instructions below are for obtaining read and write access to the repository. This will only be granted to trusted people. (Currently the repository is only accessible locally, there is no network access.)

Ask David Koppelman to have your userid added to the cvsdmk group.
Set environment variable CVSROOT to /fac/drk/pub/cvsroot/.
Make sure that the system you use has /fac/drk/pub mounted. If not, ask Saied Andalib to mount it. (System sol has it mounted.)

Checking out a Project

Checking out a project makes a copy of it for you. If you plan to modify the project for your own use you would do this once. If you are fixing a bug or adding a feature you would check out a copy for each bug or feature you were working on. (That is, it's bad style to work on two different features at the same time in one working copy.)

Determine which module (project) you want to check out. Currently, LSU RSIM is module rsiml and PSE is module see.

Move to a directory in which you want the project to be placed and execute the checkout command:

[drop] % cd ~/myprojects/
/home/smith/myprojects
[drop] % cvs co see
cvs checkout: Updating see
U see/README
cvs checkout: Updating see/doc
...
U see/src/shade-spix/reguse.h
U see/src/shade-spix/reguse2.h
U see/src/shade-spix/spixtypes.h
[drop] %

A common problem is not having /fac/drk/pub mounted. Out main server, sol, usually has it mounted.

Updating a Project

Suppose a project is checked out, you make changes to your working copy and later others have checked in changes. Your working copy would be out of date. Updating is merging those changes into your working copy (while retaining your changes). Updating does not change the repository, just your working copy.

To update enter the command: cvs update.
Those with some common sense may fear that this command will eliminate some or all of their changes. If it does it's very rare.

CVS should print the status of every file it examines.
Edit each file for which CVS was not able to merge in changes. Those files will have both your changes and the other person's changes side by side. You need to combine those in an appropriate way.

Preparing Diffs

If you are making changes to be included in the repository those changes will have to be reviewed before being checked in. To do that prepare a diff file which contains differences between your working copy and the corresponding repository versions.

Change to the directory containing the modified working files (or a parent, if there are several directories with modified files).
Issue the command /fac/drk/pub/bin/makediffs
The command should create a file named with your userid and the date and time.
If you're feeling shy, inspect the file to see the changes that you've made.
Send the file to the person doing the review.

RSIM

Background

RSIM is a multiprocessor simulator written at Rice and extensively modified here at LSU.

Setup

Obtain a copy of the distribution through CVS (see instructions elsewhere on this page.) or by some other means.
The module name (for CVS) is rsiml.
Follow the instructions in the file README.lsu and examples/simple/README.txt.
These instruction explain how to run the simulator on a simple test program.

Using Shade (Fall 2003)

Background

Shade is a package for analyzing the dynamic instruction stream of SPARC (Sun) programs running on Solaris. Analysis can be simple, such as counting the number of load instructions executed, of moderate complexity, such as evaluating the prediction accuracy of a branch predictor, or complex, such as determining the performance of a particular pipelined implementation.

Shade comes with several analyzers, programs for analyzing instruction streams, and users can write their own. See the Shade User's Manual for documentation on analyzers that come with Shade.

For a typical homework assignment one will have to modify an existing analyzer, or perhaps write a new one. A set of files will be provided for each homework assignment, including analyzer source code and a makefile.

For instructions on running and writing analyzers see the Introduction to Shade.
For details see the Shade User's Manual.

Running Shade

Shade is run to analyze (perhaps simulate) a benchmark program. This step is performed after an analyzer has been compiled and suitable benchmarks chosen. The steps below are for the icount (instruction count) analyzer and the pwd program, both of which should be available if the class account was set up correctly.

Start a shell if none is already handy. In Emacs this can be done with the command M-x shell.
The advantage of using Emacs is the ease of scrolling back to look at lengthy output. It may also be easier to cut and paste portions of the output you want to save.

Run the analyzer and provide the name of the benchmark and any arguments to stdin. An easy way to do that is:

echo pwd | icount

Analyzer: icount
Version: Shade and Spixtools V5.33A, V9 SPARC Solaris
Uname: drop sun4u SunOS 5.8 Generic_108528-24
Start: Mon Nov 10 16:17:03 2003
Application: /bin/pwd
/home/faculty/koppel/teach/tca03/shade/hw3
Application Instructions: 557466
Stop: Mon Nov 10 16:17:04 2003
Instructions: 557466
Time: 0.060 usr  0.010 sys  0.140 real  49.978%
Speed: 7963.800 KIPS

The text "pwd" is read by the icount analyzer, which then runs it (the pwd program). Instead of using echo and a pipe, one could enter:

icount
pwd

Running the Instruction Tracing Utility

The instruction tracing utility is a shade analyzer that shows the instructions executed by, traces, a program. By default it shows the first ten instructions, but it can show any number. Each of the steps below shows a different way of using it, the first step describes the tracer's output.

Show the first ten instructions of a program named sum. But first, here is the output of sum:

sum

Hello.0.000000 
Sum in: 45  0.000000

Here is the traced output of sum. The output of sum comes first, followed by the trace output. (Other times the trace and the traced program output will be mixed.)

echo sum | rtrace

Hello.0.000000 
Sum in: 45  0.000000
_start+0  :
 Insn Num  Insn PC    Assembler                ! Register and Other Values
        1  0x00010078 or     %g0,0,%fp         ! 0x0,0,0x0
        2  0x0001007c lduw   [%sp+64],%l0      ! [0xffffcbc0+64],0x1
        3  0x00010080 add    %sp,68,%l1        ! 0xffffcbc0,68,0xffffcc04
        4  0x00010084 sub    %sp,32,%sp        ! 0xffffcbc0,32,0xffffcba0
        5  0x00010088 orcc   %g0,%g1,%g0       ! 0x0,0x0,0x0
        6  0x0001008c be     0x1009c (_start+9  )  ! 
        7  0x00010090 or     %g0,%g1,%o0       ! 0x0,0x0,0x0
_start+9  :
        8  0x0001009c sethi  %hi(0x32800),%o0  ! %hi(0x32800),0x32800
        9  0x000100a0 or     %o0,904,%o0       ! 0x32800,904,0x32b88
       10  0x000100a4 call   0x102e8 (atexit+0  )  !
Executed 3241 instructions.

The Insn Num is a numbering of dynamic instructions. The PC of each instruction is shown, line labels are shown (_start+0 and _start+9 above) at the target of taken control transfers, the amount of information depends on how the program being analyzed was built. Register values are shown as comments.

To trace 20 instructions starting at instruction number 1000:

echo sum | rtrace 1000 20

Hello.0.000000 
Sum in: 45  0.000000
_doprnt+1283  :
 Insn Num  Insn PC    Assembler                ! Register and Other Values
     1000  0x00011bb0 add    %i4,1,%i4         ! 0x0,1,0x1
     1001  0x00011bb4 add    %i3,1,%i3         ! 0xffffc370,1,0xffffc371
     1002  0x00011bb8 ba     0x11bcc (_doprnt+1290  )  ! 
     1003  0x00011bbc lduw   [%sp+152],%o1     ! [0xffffbd08+152],0x30
_doprnt+1290  :
     1004  0x00011bcc lduw   [%sp+92],%o0      ! [0xffffbd08+92],0xffffc592
     1005  0x00011bd0 stb    %o1,[%o0]         ! 0x30,[0xffffc592]
     1006  0x00011bd4 add    %o0,1,%o0         ! 0xffffc592,1,0xffffc593
     1007  0x00011bd8 lduw   [%sp+184],%g1     ! [0xffffbd08+184],0x5
     1008  0x00011bdc stw    %o0,[%sp+92]      ! 0xffffc593,[0xffffbd08+92]
     1009  0x00011be0 subcc  %g1,1,%o0         ! 0x5,1,0x4
     1010  0x00011be4 stw    %o0,[%sp+184]     ! 0x4,[0xffffbd08+184]
     1011  0x00011be8 bpos,a 0x11b80 (_doprnt+1271  )  ! 
     1012  0x00011bec lduw   [%fp-1228],%o0    ! [0xffffca40-1228],0x1
_doprnt+1271  :
     1013  0x00011b80 add    %o0,1,%o0         ! 0x1,1,0x2
     1014  0x00011b84 subcc  %o0,0,%g0         ! 0x2,0,0x0
     1015  0x00011b88 ble    0x11bc0 (_doprnt+1287  )  ! 
_doprnt+1274  :
     1016  0x00011b8c stw    %o0,[%fp-1228]    ! 0x2,[0xffffca40-1228]
     1017  0x00011b90 ldsb   [%i3],%o0         ! [0xffffc371],0x30
     1018  0x00011b94 subcc  %o0,0,%g0         ! 0x30,0,0x0
     1019  0x00011b98 be,a   0x11bc4 (_doprnt+1288  )  ! 
Executed 1019 instructions.

To execute the first 20 instructions of routine main:

echo sum | rtrace 20 main

Hello.0.000000 
Sum in: 45  0.000000
main+0  :
 Insn Num  Insn PC    Assembler                ! Register and Other Values
       94  0x0001020c save   %sp,-128,%sp      ! 0xffffcba0,-128,0xffffcb20
       95  0x00010210 stw    %i0,[%fp+68]      ! 0x1,[0xffffcba0+68]
       96  0x00010214 stw    %i1,[%fp+72]      ! 0xffffcc04,[0xffffcba0+72]
       97  0x00010218 stw    %g0,[%fp-24]      ! 0x0,[0xffffcba0-24]
       98  0x0001021c sethi  %hi(0x4ac00),%o1  ! %hi(0x4ac00),0x4ac00
       99  0x00010220 or     %o1,904,%o0       ! 0x4ac00,904,0x4af88
      100  0x00010224 sethi  %hi(0x2400),%o2   ! %hi(0x2400),0x2400
      101  0x00010228 or     %o2,784,%o1       ! 0x2400,784,0x2710
      102  0x0001022c stw    %o1,[%o0] (traceamt)  ! 0x2710,[0x4af88+0x0]
      103  0x00010230 stw    %g0,[%fp-20]      ! 0x0,[0xffffcba0-20]
      104  0x00010234 lduw   [%fp-20],%o0      ! [0xffffcba0-20],0x0
      105  0x00010238 subcc  %o0,9,%g0         ! 0x0,9,0x0
      106  0x0001023c ble    0x1024c (main+16  )  ! 
      107  0x00010240 nop                      ! 
main+16  :
      108  0x0001024c lduw   [%fp-24],%o0      ! [0xffffcba0-24],0x0
      109  0x00010250 lduw   [%fp-20],%o1      ! [0xffffcba0-20],0x0
main+18  :
      110  0x00010254 add    %o0,%o1,%o0       ! 0x0,0x0,0x0
      111  0x00010258 stw    %o0,[%fp-24]      ! 0x0,[0xffffcba0-24]
      112  0x0001025c lduw   [%fp-20],%o0      ! [0xffffcba0-20],0x0
      113  0x00010260 add    %o0,1,%o1         ! 0x0,1,0x1
Executed 3241 instructions.

To trace for five instructions whenever global variable traceamt in sum is assigned or referenced, with a limit of 20 instructions:

echo sum | rtrace traceamt 5 20

Hello.0.000000 
Sum in: 45  0.000000
main+8  :
 Insn Num  Insn PC    Assembler                ! Register and Other Values
      102  0x0001022c stw    %o1,[%o0] (traceamt)  ! 0x2710,[0x4af88+0x0]
      103  0x00010230 stw    %g0,[%fp-20]      ! 0x0,[0xffffcba0-20]
      104  0x00010234 lduw   [%fp-20],%o0      ! [0xffffcba0-20],0x0
      105  0x00010238 subcc  %o0,9,%g0         ! 0x0,9,0x0
      106  0x0001023c ble    0x1024c (main+16  )  ! 
main+27  :
      242  0x00010278 stw    %g0,[%o0] (traceamt)  ! 0x0,[0x4af88+0x0]
      243  0x0001027c ldf    [%fp+68], f2      ! [0xffffcba0+68],
      244  0x00010280 fitod   f2, f4           ! ,
      245  0x00010284 stdf    f4,[%fp-16]      ! ,[0xffffcba0-16]
      246  0x00010288 ldd    [%fp-16],%o2      ! [0xffffcba0-16],0x0
Executed 3241 instructions.

Compiling a Shade Analyzer

You've got to know if code ever uses subcc with a non-zero destination register. Or maybe you've figured out a solution to the homework assignment. Either way you need to write and run an analyzer, follow the steps below.

Write an analyzer program from scratch, including the makefile. Or, start with an existing analyzer (that might have been provided as part of the homework assignment), and edit it.

Build the analyzer by running the make file. On Emacs this can be done by pressing F9 while in a buffer visiting the analyzer source file, from the shell:

make

gcc -I/data4/koppel/shadekit/shade.v9.elf/src/include -I/data4/koppel/shadekit/shade.v9.elf/spixtools/src/include -g -c pred.c
gcc -dn -Wl,-M,/data4/koppel/shadekit/shade.v9.elf/lib/mapfile -o pred pred.o /data4/koppel/shadekit/shade.v9.elf/lib/libshade.a /data4/koppel/shadekit/shade.v9.elf/spixtools/lib/libspix.a

Your output may include error messages. If you build by pressing F9 then you can jump to an error by clicking the error message with the mouse button.

That's it. To run the analyzer follow the instructions for running Shade.

David M. Koppelman - koppel@ece.lsu.edu

Modified 15 Jun 2004 12:07 (1707 UTC)