makerom (tool command)

Creates a ROM Game Pak image and associated ELF object files

Syntax

makerom [-D name[=def]] [-I dir] [-U name] [-d] [-m] [-o]
        [-b bootstrap filename] [-h header filename]
        [-s romsize] [-f filldata]
        [-p pif2 bootstrap filename] [-r romfile] specfile

Description

makerom creates a ROM image suitable for downloading into the Game Pak ROM by the gload tool. makerom takes as input the specification file (specfile) that describes the organization of object and raw data files into segments. Then makerom invokes a link editor to resolve all undefined references, perform relocations, and create ELF object files for the Nintendo 64 debugger, gvd.

The makerom tool forcefully loads the first 8K bytes with the default bootstrap, pif bootstrap, and header files, unless you override these built-in defaults with command line options.

Command line options recognized by makerom are the following.

-D name[=def]
Is passed to cpp for use during its invocation.

-I directory
Is passed to cpp for use during its invocation.

-U name
Is passed to cpp for use during its invocation.

-d
Gives a verbose account of all the actions that makerom takes, leaving temporary files created that are normally deleted.

-m
Prints a link editor map to standard output for diagnostic purposes.

-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.

-b <bootstrap filename>
Overrides the default filename "/usr/lib/PR/Boot". This file must be in COFF format, and is loaded as 1K bytes into the ramrom memory.

-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.

-s <romsize (Mbits)>
Creates a ROM image with the specified size. This option is required for making the real Game Pak.

-f <filldata (0x0 - 0xff)>
Sets the fill pattern for "holes" within a ROM image. The argument filldata is a one-byte hexadecimal constant. Use this option when you create a ROM image using the -s option.

-p <pif bootstrap file>
Overrides the pif bootstrap filename "/usr/lib/PR/pif2Boot". This file must be in COFF format. It is loaded as 4K bytes into the ramrom memory.

-r
Provides an alternate ROM image file; the default is 'rom'.

-B 0
An option that concerns only games supported by 64DD. Using this option creates a startup game. For information on startup games, please see Section 15.1, "Restarting," in the N64 Disk Drive Programming Manual.

The makerom tool searches in three places for the bootstrap, pif bootstrap, and ROM header files in this order: First, $(ROOT)/<filename>, next $(WORKAREA)/<filename>, and last /<filename>. The ROOT and WORKAREA shell environment variables are used internally by SGI machine. The makerom tool's use 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 to overwrite the existing default structure in makerom.

The spec file is preprocessed with the C language preprocessor (cpp) so that header files may be used for consistency with source and #defines may be used for clarity. Following describes the syntax of the specification file.

<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>

The "name" statement when used in the segment definition provides makerom with a string that it associates with the segment. It uses this for two reasons: to associate the segment with "waves" described below and to create some predefined symbols that may be referenced by code segments. These symbols should be declared as an "extern" to avoid their interpretation as gp-relative data. The symbols, and their meaning are as follow.

_`name'SegmentStart
is the beginning virtual or segment address of the segment

_`name'SegmentEnd
is the ending virtual or segment address of the segment plus one

_`name'SegmentTextStart
if any program text (instructions) are present, this is the starting address of the text

_`name'SegmentTextEnd
if any program text (instructions) are present, this is the ending address of the text plus one

_`name'SegmentDataStart
if any initialized program data is present, this is the starting address of this section

_`name'SegmentDataEnd
if any initialized program data is present, this is the ending address of this section plus one

_`name'SegmentBssStart
if any uninitialized program data is present, this is the starting address of this section

_`name'SegmentBssEnd
if any uninitialized program data is present, this is the ending address of this section plus one

_`name'SegmentRomStart
is the beginning ROM address of the segment

_`name'SegmentRomEnd
is the ending ROM address of the segment plus one

The "flags" statement provides some specific information about the segment. Segments flagged as "object" are composed of nonshared ELF relocatables. The type "raw" consists of uninterpreted data. The segment flagged as the "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 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.

The "address", "number", and "after" statements are ways of indicating the beginning virtual address of an 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 fragments in the address space while easily accommodating changes in segment sizes.

Each of one or more "include" statements of a segment definition specifies files that comprise the segment. If the segment has been flagged with "object", the specified file should be a nonshared ELF relocatable. Any types of files can be specified for "raw".

The "maxsize" statement can be used to specify the maximum size of a segment in bytes.

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 bits) boundaries.

It is necessary to define multiple "waves" statements for specification files. Each wave definition results in a different ELF object file being created. Multiple waves may be used as desired to controll totally different scenes or perhaps appropriate when different address spaces are necessary due to the memory layouts.

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 defined segment specified by "include"' statement in the wave definition is included in the wave. The inclusion of the a segment into a wave makes its symbols available to all other segments of the wave.

Example

The following spec file describes an application with two segments: a boot program segment and a static data segment. A single ELF object file named "rotate" is created.

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

See Also

gload, gvd

Revision History

1999/01/21 Removed -C option, and added -B 0 option
1999/04/30 Changed Format