.TH rsp2elf 1P local "Silicon Graphics, Inc."
.SH NAME
rsp2elf \- Convert RSP microcode to ELF format for linking with
applications and debugging.
.SH SYNOPSIS
\f3rsp2elf\f1 [-c] [-p] [-r] [-s] file
.SH DESCRIPTION
The
.I rsp2elf
program converts the output files produced by
.I rspasm
into a form that can be consumed by 
.I makerom
and the
.I gvd
debugger. It synthesizes an ELF format file from the various assembler
output files. These files are assumed to have names that are derivatives
of the
.B file
name specified on the command line. Similarly, the name of the output file will
be a derivative of
.B file.
The debugger can read this ELF file and extract information
about symbols, microcode procedures, etc.
.PP
The debugger expects a conventional program structure, a convention that
microcode does not normally follow. For example, the debug information
(mdebug) section expects that a program consists of files, procs (e.g., C
functions), blocks, lines, and symbols. Files contain procs, procs
contain blocks, symbols, and lines. There is no way to express information
about a source line or address
without referring to its enclosing proc. Similarly, a proc 
must belong to an enclosing file.
.PP
The
.I rsp2elf
program analyzes the microcode from various 
.I rspasm
output files and creates a
synthetic structure from this information. For example, if the microcode
contains a number of lines of code that are associated with a file but
no proc has been specified by the writer, then a synthetic proc based on the
name of the file will be created. The user will probably never reference the
name of this proc (since it is not necessarily obvious), but the hierarchy
of file\-proc\-line is maintained. Similarly, symbols encountered in the file
will be assigned to the synthetic proc name, and addresses that correspond to
code in this file will be considered part of the synthetic proc.
.PP
If the user does provide proc information within a source file using the
.I .entry
and
.I .end
directives, then this user structure will be preserved. Since
.I rsp2elf
does not produce any synthetic proc information if user procs are present,
it may be the case that some symbols or lines of code will not be
assigned to procs. These symbols may be referenced by the debugger, but
the debugger will not be able to map from a current program counter value
to the name of a proc, since these are "orphan addresses" and "orphan symbols."
The debugger will indicate that the code is stripped whenever the program 
counter points to such an address. Single stepping or running to a breakpoint
in the debugger will restore symbolic debug capability as soon as the PC
points to an address that is part of a proc - i.e., that is not an orphan.
.SS Options
.TP
.B \-c
specifies that constants are to be included in the ELF file. If not specified,
information about constants will be discarded.
.TP
.B \-p
causes all output sections to be padded so the following section starts
on an address that is a multiple of 16 bytes.
.TP
.B \-r
produces a relocatable ELF output instead of an absolute ELF output.
The relocatable file may be linked with other modules to form a load module.
It does not contain debug information, but does provide global symbols that
may be referenced by the rest of the game application. For a file named
.B gspFast3D.dram,
the symbols produced will be 
.B gspFast3D_dramTextStart, gspFast3D_dramTextEnd, gspFast3D_dramDataStart,
and
.B gspFast3D_dramDataEnd.
.TP
.B \-s
produces a greatly simplified ELF absolute file. The simple ELF file contains
only a single PROC record for the entire program, rather than one proc per
file. Use of this option is not recommended, since it greatly reduces debug
capability.
.SH FILES
.nf
file		The IMEM contents
file.dat	The DMEM contents
file.sym	The file contining line and proc information
file.dbg	The symbol table file
file.o	The relocatable output file
file.tvd	The absolute output file
.fi
.SH BUGS
The simplified format has not been tested thoroughly in the latest version.