.TH makerom 1P local "Silicon Graphics, Inc."
.SH NAME
makerom \- create a ROM cartridge image and associated ELF object files
.SH SYNOPSIS
\f3makerom\f1 [-D name[=def]] [-I dir] [-U name] [-d] [-m] [-o]
.br
[-b bootstrap filename] [-h header filename]
.br
[-s romsize] [-f filldata] [-C clockrate]
.br
[-p pif2 bootstrap filename] [-r romfile] specfile
.SH DESCRIPTION
The
.I makerom
program creates a rom image suitable for downloading into the cartridge rom by
.IR gload (1P).
It takes as input the specification file `specfile' which describes the
organization of object and raw data files into segments.
Then
.I makerom
invokes a link editor to resolve all undefined references,
perform relocations,
and creates ELF object files for the Ultra 64 debugger,
.IR gvd (1P).
.P
.I makerom
will intentionally load the 
first 8K bytes with the default bootstrap, pif bootstrap, and header files, 
unless you override these built-in defaults with command line options.  
.PP
The following command line flags are recognized by
.IR makerom :
.TP 15
.BI -D name[=def]
Passed to
.IR cpp (1)
for use during its invocation.
.TP
.BI -I directory
Passed to
.IR cpp (1)
for use during its invocation.
.TP
.BI U name
Passed to
.IR cpp (1)
for use during its invocation.
.TP
.B -d
Gives a verbose account of all the actions that
.I makerom
takes, leaving temporary files created that are ordinarily deleted.
.TP
.B -m
Prints a link editor map to standard output for diagnostic purposes.
.TP
.B -o
Disables checking of overlapping sections.
By default, 
segments with direct mapped CPU addresses are checked to ensure that
the underlying physical memory mappings do not conflict.
.TP
.B \-b <bootstrap filename>
Overrides the default filename "/usr/lib/PR/Boot".  This file must be in COFF
format, and is loaded 1K bytes into the ramrom memory.
.TP
.B \-h <header filename>
Overrides the default rom header filename "/usr/lib/PR/romheader".  This file
is in ascii format, and each character is converted to hex and loaded in 
sequence, starting at the beginning of ramrom memory.  Currently only 32 bytes
are used.
.TP
.B \-s <romsize (Mbits)>
Creates a rom image with specified size. This option is required for making
the real game cassette.
.TP
.B \-f <filldata (0x0 - 0xff)>
Set the fill pattern for "holes" within a rom image. The argument 
.I filldata
is an one byte hexadecimal constant.
This option is used when creating a rom image using 
.B -s 
option  and required for making the real game cassette.
.TP
.B \-C <clockrate>
Overwrite the default processor speed for older hardware. The default value for 
processor speed is 62.5 Mhz. If 
.I clockrate
is specified as zero, the processor speed will be set to 60.85  Mhz. Otherwise,
.I clockrate
will be used as processor speed.
.TP
.B \-p <pif bootstrap file>
Overrides the pif bootstrap filename "/usr/lib/PR/pif2Boot".  This file must be
in COFF format, and is loaded 4K bytes into the ramrom memory.
.TP
.B -r
Provides an alternate ROM image file; the default is `rom'.
.PP
.I makerom
will search in three places for the bootstrap, pif bootstrap, and rom
header files:
it first searches $(ROOT)/<filename>, then $(WORKAREA)/<filename>, and 
finally /<filename>.  The ROOT and WORKAREA shell environment variables are 
used internally at Silicon Graphics, and 
.I makerom's
usage of these variables allow our internal developers to use sw modules 
created within their personal development source directories, even if the same
modules are installed on the development system upon which they are running 
their new code.  If these variables are not set, you must supply the full 
pathname for these files, should you wish to override the defaults built into 
.I makerom.
.PP
.PP
The spec file is preprocessed with the C language preprocessor
.I "(cpp)"
so that header files may be used for consistency with source and
#defines may be used for clarity.
The grammar of the specification file is described below:
.nf
.ft 7
        <specFile>      :       <segmentList> <waveList>

        <segmentList>   :       <segment>
                        |       <segmentList> <segment>

        <segment>       :       beginseg <segStmtList> endseg

        <segStmtList>   :       <segStatement>
                        |       <segStmtList> <segStatement>

        <segStatement>  :       name <segmentName>
                        |       address <constant>
                        |       after <segmentName>
                        |       after max[<segmentName>,<segmentName>]
                        |       after min[<segmentName>,<segmentName>]
                        |       include <filename>
                        |       maxsize <constant>
                        |       align <constant>
                        |       flags <flagList>
                        |       number <constant>
                        |       entry <symbol>
                        |       stack <stackValue>

        <flagList>      :       <flag>
                        |       <flagList> <flag>

        <flag>          :       BOOT
                        |       OBJECT
                        |       RAW

        <stackValue>    :       <constant>
                        |       <symbol>
                        |       <symbol> + <constant>

        <waveList>      :       <wave>
                        |       <waveList> <wave>

        <wave>          :       beginwave <waveStmtList> endwave

        <waveStmtList>  :       <waveStatement>
                        |       <waveStmtList> <waveStatement>

        <waveStatement> :       name <waveName>
                        |       include <segmentName>
.fi
.ft 1
.PP
The `name' statement when used in the segment definition provides
.I makerom
with a string that it associates with the segment.
It uses for two purposes:
first, to associate the segment with "waves" described below;
and second,
to create some predefined symbols that may be referenced with by
code segments.  These symbols should be declared as an external array
avoid their interpretation as gp-relative data.  The symbols, and
their meaning are:
.TP 25
.B _`name'SegmentStart
beginning virtual or segment address of the segment
.TP
.B _`name'SegmentEnd
ending virtual or segment address of the segment plus one
.TP
.B _`name'SegmentTextStart
if any program text (instructions) are present, the starting address of the text
.TP
.B _`name'SegmentTextEnd
if any program text (instructions) are present, the ending address of the
text plus one
.TP
.B _`name'SegmentDataStart
if any program initialized data is present, the starting address of this
section
.TP
.B _`name'SegmentDataEnd
if any program initialized data is present, the ending address of this
section plus one
.TP
.B _`name'SegmentBssStart
if any program uninitialized data is present, the starting address of this
section
.TP
.B _`name'SegmentDataEnd
if any program uninitialized data is present, the ending address of this
section plus one
.TP
.B _`name'SegmentRomStart
beginning ROM address of the segment
.TP
.B _`name'SegmentRomEnd
ending ROM address of the segment plus one
.PP
The `flags' statement provides some specific information about the segment.
Segments flagged as
.I OBJECT
are composed of nonshared ELF relocatables;
otherwise,
they are of type
.I RAW
and consist of uninterpreted data.
The segment flagged as the
.I BOOT
segment is of special significance.
It must be the first segment in the specification file,
and it is linked at a fixed address.
The `entry' statement gives the symbol that will be jumped to immediately after
the rom image is loaded by
.IR gload .
The `stack' segment specifies the beginning stack address
of the boot code.
It may either be a constant virtual address,
or optionally, a program segment symbol name plus an offset.
The later form is often useful since stacks grow backwards (towards
smaller addresses) as procedures are invoked.
.PP
The `address', `number', and `after' statements are ways of indicating the
beginning virtual address of an
.I OBJECT
segment.
The
`address' statements are primarily intended for segments that will be
executed by the CPU,
whereas segments numbered by the `number' segment are primarily intended
to be accessed by the RSP.
The `after' keyword can place a segment directly after the address range
of another segment;
this can be useful for preventing holes in the address space while
easily accomodating changes in segment sizes.
.PP
Each of one or more `include' statements of a segment definition
specifies files that comprise the segment.
If the segment has been flagged with
.IR OBJECT ,
the specified file should be a nonshared ELF relocatable;
a
.I RAW
file can be of any type.
.PP
The `maxsize' statement can be used to enforce a size restriction (in bytes)
that the total segment size must not exceed.
.PP
The `align' statement can be used to align a segment to a given number
of bytes.
By default, segments are aligned to 16 byte (128 bit) boundaries.
.PP
After the segments have been defined,
a definition for one or more "waves" is expected.
Each wave definition results in a different ELF object file being created.
Multiple waves may be used as desired to keep distinct address spaces,
perhaps for dramatically different scenes and resulting memory layouts.
.PP
The `name' statement of a wave definition will be used as the file name
of the resulting ELF object file that corresponds to the wave.
The `include' statement of a wave definition specifies which of the
previously defined segments are to be included in a wave.
The inclusion of the a segment into a wave makes its symbols available
to all other segments of the wave.
.PP
.SH SEE ALSO
.IR gload (1P),
.IR gvd (1P)
.SH EXAMPLE
.PP
The following spec file describes an application with two segments:
a boot program segment and a static data segment.
A single ELF object file "rotate" will be created.
.KS

        beginseg
                name "program"
                flags BOOT OBJECT
                entry mainproc
                stack mainThreadStack + 0x1000
                include "rotate.o"
        endseg

        beginseg
                name "static"
                flags OBJECT
                number 1
                include "square.o"
        endseg

        beginwave
                name "rotate"
                include "program"
                include "static"
        endwave
.KP