# makerom

## Location

`$NitroSDK/tools/bin/makerom.exe`
`$NitroSDK/tools/bin/rom_header.template.sbin`

## Description

`makerom` is a tool for creating NITRO application ROM images. It creates the ROM image in accordance with the description in a file called the ROM Spec file.

## Usage

### Run Command

#### (1) Normal start

`% makerom [-d] [-DNAME=VALUE...] [-MDEFINES_FILE] [-F] SPECFILE [ROMFILE] [LISTFILE]`

This links files and creates a ROM image file named `ROMFILE` in accordance with the description in the ROM Spec file specified by `SPECFILE`. The ROM structure information is output to the file specified by `LISTFILE`.

`ROMFILE` and `LISTFILE` can be omitted, in which case the two files use the same name as that specified by `SPECFILE`, but with the extension changed to `.rom` and `.nlf`, respectively. Also, the `-D` option can be used to define a variable and its values. The value of this variable can be referenced at the time of the ROM Spec file description.

The `-M` option lets you define a variable and its value, just like the `-D` option. The text file that consists of the `[NAME=VALUE]` line is received as an argument. By using this option, the variables and their values that exceed the command line length restriction can be described in the definition.

When the `-F` option is specified, a ROM image file will be created even if the ROM file exceeds the size limitation value (refer to `RomSize` in the Property section).

The `-d` option is for outputting messages when debugging `makerom`. It is normally not necessary.

#### (2) The `-l` option

`% makerom [-d] [-DNAME=VALUE...] [-MDEFINES_FILE]-l SPECFILE [LISTFILE]`

This operates the same as the Normal Start method (1), except when a ROM image is not output. The file specified by `SPECFILE` is read, and the ROM structure information is output to the file named `LISTFILE`.

`LISTFILE` can be omitted, in which case the filename takes the same name as that specified by `SPECFILE`, but with the extension `.nlf`. The `-D` option can be used to define a variable and its values. The value of this variable can be referenced at the time of the ROM Spec file description.

#### 3) The `-r` option

`% makerom [-d] [-F] -r LISTFILE [ROMFILE]`

A ROM image is constructed from the ROM structure information specified by `LISTFILE` and output as a file with the name specified by `ROMFILE`.

`ROMFILE` can be omitted, in which case the filename takes the same name as that specified by `LISTFILE`, but with the extension `.rom`.

When the `-F` option is specified, a ROM image file will be created even if the ROM file exceeds the size limitation value (refer to `RomSize` in the Property section).

### ROM Spec File Format

The contents of the NITRO ROM image can be managed using a simple file system. The ROM Spec file is a text file that describes the structure of this file system. ARM9, ARM7 and incidental information sections should be described before the ROM image section. The structure is divided into four sections. The section definitions all follow this format: there is a declaration of the start of the section definition, followed by section-related parameters enclosed in curly brackets.

Subject of section definition | Format for section definition | Example definition
--- | --- | ---

ARM9
Executable binary

    Arm9
    {
      [ARM9 parameter description part]
      ....
    }

    Arm9
    {
      Static        main.sbin
      OverlayDefs   main_defs.sbin
      OverlayTable  main_table.sbin
      Nef           main.nef
    }

ARM7
Executable binary

    Arm7
    {
      [ARM7 parameter description part]
      ....
    }

    Arm7
    {
      Static        sub.sbin
      OverlayDefs   sub_defs.sbin
      OverlayTable  sub_table.sbin
      Nef           sub.nef
    }

Incidental Information
(Property)

    Property
    {
      [incidental information parameter description part]
      ....
    }

    Property
    {
      RomHeader
      rom_header.sbin
    }

ROM Image

    RomSpec
    {
      [ROM image parameter description part]
      ....
    }

    RomSpec
    {
      Offset   0x00000000
      Segment  All
      File     data.bin
    }

### Section Parameters

#### Arm9 section (ARM9 execution file definitions section)

This is for settings related to the execution file on the ARM9 side.

> `Static [ARM9's Resident Module filename]`
>   Specifies the filename of the Resident Module of the ARM9's execution file.

> `OverlayDefs [Name of the ARM9's Overlay Name file]`
>   Specifies the ARM9's OverlayDefs filename.

> `OverlayTable [ARM9's OverlayTable filename]`
>   Specifies the ARM9's OverlayTable filename. This file is not needed if overlays are not being used. If this is the case, the `OverlayTable` definition can be omitted.

> `Nef [Name of the ARM9's nef file (debug information file)]`
>   Specifies the `nef` file where ARM9 debug information will be stored.
>   If debugging is not run, this `Nef` definition is not needed, and the description can be omitted. Instead of `"Nef"`, you can use the alternative keyword `"Elf"`.

#### Arm7 section (ARM7 execution file definitions section)

This is for settings related to the execution file on the ARM7 side.

> `Static [ARM7's Resident Module filename]`
> `OverlayDefs[Name of the ARM7's Overlay Name file]`
> `OverlayTable [ARM7's OverlayTable filename]`
> `Nef [Name of the ARM7's nef file (debug information file)]`
>   Same as the ARM9's parameters.

#### Property section (incidental information definition section)

> `RomHeaderTemplate [Template file name of ROM header]`
>   Specifies the template file in the header section of the Rom image. When this not specified, "rom_header.template.sbin" that is in the same directory as makerom.exe is used as the default.

> `TitleName [Title name]`
>   Specifies the title name. Up to 12 characters of ASCII code. When it is shorter than 12 characters, 0 will be stored in the unused area. When this is not specified, the value that is embedded in RomHeaderTemplate is used.

> `MakerCode [manufacturer code]`
>   Specifies a manufacturer code that was determined when signing licensing agreement with our company. Two ASCII characters can be used. When this is not specified, the value that is embedded in RomHeaderTemplate is used.

> `RomVersion [ROM version]`
>   Specifies the ROM version of the retail product. Hexadecimal notation, decimal notation, and octal notation can be used. When this is not specified, the value that is embedded in RomHeaderTemplate is used.

> `RomSize [ 64M | 128M | 256M | 512M | 1G | 2G ]`
>   Specifies the ROM size in bits. Under the current circumstances, select from 64M/128M/256M/512M/1G/2G text strings. When the ROM image exceeds the specified value, an error or a warning (when the -F option is specified) is output. When this is not specified, the value that is embedded in RomHeaderTemplate (current one is "2G") is used.

> `RomFootPadding [TRUE|FALSE]`
>   Specify TRUE if you want the unused region above the program storage area in ROM to be filled with data, and create the binary that matches the ROM size specified by RomSize. The data stored in unused region is the value that is specified with the Padding parameter in the RomSpec section. To enable this feature, it is necessary to specify RomSize. When this is not specified, it becomes FALSE.

> `RomHeader [file name of ROM header]`
>   Name of the image file in the header section of the ROM image. This file is generated by embedding the information from ROM spec files to the copy of the template that is explained in the above item.

>   Normally it is not necessary to specify the name. When it is not specified, the file name is made by taking out the file extension from the file name of ARM9 resident module and then adding header.sbin.

> `FileName [FileNameTable file name]`
>   Name of the image file in the file name table section of the ROM file system. This file is generated from the RomSpec item in the ROM spec file. Normally it is not necessary to specify the name. When it is not specified, the file name is made by taking out the file extension from the file name of ARM9 resident module and then adding files.sbin.

> `BannerFile [banner file name]`
>   Specifies the banner file, that consists of the application identification image information that is displayed at the startup of NITRO.

#### RomSpec section (ROM image definitions section)

This section needs to be described after other sections.

> `Offset [offset value]`
>   Specifies the offset value for the location of the ROM image file (or data). To prevent the overlap of ROM image regions, the offset value that can be set must be larger than the final position where all files (or data) are set at that time. If it is not, then an error will occur.

> `OffsetMin [offset value]`
>   The same as `Offset`, except that an error will not occur even if the offset value is not larger than the final position where files are set. (Instead, the setting will be ignored.)

> `Segment All`
>   Sets all data for file system management. This management data precedes other files and must be placed at the start of ROM.

> `Padding [Character codes 0 - 255]`
>   Specifies the value to assign for padding when aligning ROM images. Specify a value between 0 and 255. The initial value is 0.

> `Align [alignment value]`
>   Matches the ROM image starting position of the next file or data-set to store to the specified memory boundary. Empty space is filled using the value specified by `Padding`. The alignment value must be an exponent of 2. `Align` is used to temporarily operate the memory boundary of the file, and it affects the file placed immediately after this one in the description. To specify the permanent memory boundary, use `AlignAll`.

> `AlignAll [alignment value]`
>   Matches the ROM image starting position of all subsequent files and data-sets being stored to the specified memory boundary. Empty space is filled using the value specified by `Padding`.

If `Align` and `AlignAll` are both defined, the alignment value used is the larger value. The initial value of `AlignAll` is 512.

Note: Access to the NITRO Software NITRO CARD is limited to the units of 512-byte blocks when the boundary for the file allocation is set to less than 512.

`Segment RomHeader`
`Segment Static Arm9`
`Segment OverlayTable Arm9`
`Segment Overlays Arm9`
`Segment Static Arm7`
`Segment OverlayTable Arm7`
`Segment Overlays Arm7`
`Segment FileName`
`Align 512`
`Segment FileAlloc`
`Segment Banner`

Sets the data used for file system management.
In order from the top, these correspond to:

- ROM header
- ARM9 Resident Module
- ARM9 Overlay Table
- ARM9 Overlay Module
- ARM7 Resident Module
- ARM7 Overlay Table
- ARM7 Overlay Module
- Filename Table
- File Allocation Table
- Banner File

This is used only when you want total control over the position of each set of data. The ROM header precedes the other data and must be located at the start of the ROM image. Normally, the use of `Segment All` is sufficient and there is no need to use these definitions to individually specify the locations of the file system management data.

`Segment All` has the following definitions and equivalencies:

    Segment   RomHeader

    Align 512
    Segment   Static       Arm9
    OffsetMin 0x8000
    Segment   OverlayTable Arm9
    Segment   Overlays     Arm9

    Align 512
    Segment   Static       Arm7
    Segment   OverlayTable Arm7
    Segment   Overlays     Arm7
    Segment   FileName
    Segment   FileAlloc
    Segment   Banner

> `HostRoot [Root directory name of PC]`
>   This is the standard directory on the PC for the files stored in the ROM image. `HostRoot` can be omitted, in which case the current directory (`.`) is used as the default value.

> `Root [Root directory name of NITRO]`
>   This is the standard directory on NITRO for the files stored in the ROM image. The directory indicated by `HostRoot` on the PC gets mapped to the NITRO directory indicated by `Root`. `Root` can be omitted, in which case the root directory (`/`) is used as the default value.

> `File [filename ...]`
>   Specifies files to store in the ROM image. If the specified filename is a directory, all files in all sub-directories get stored in the ROM image. However, any files or subdirectories that match the pattern specified by `Reject` will be excluded. You can use the symbols "`*`" and "`?`" as wildcards when specifying files. The symbol "`*`" represents any number of characters, while "`?`" represents any 1-byte character.

> `Reject [filename pattern ...]`
>   This is the name of files not to store in the ROM image. `makerom` internally requests a list of the files to expand and store in ROM. This list is built from the description of directories and files in `File`. Using the `Reject` definition you can specify certain files that you do not want placed on that list.
>   By using blank spaces between names, you can specify more than one filename pattern in `Reject`, and you can also employ the `*` and `?` wildcards. The specifications made in `Reject` remain effective until the next `Reject` description. The initial values set as the `Reject` filename pattern are `CVS` or `vssver.scc`.

> `Fixed [Default | True | False]`
>   This is for fixing nlf file parameters; it controls the flag that determines whether subsequently-placed data can be moved. There is normally no need for this. The initial value is: `Default` (auto-configuration according to type of data installed)

> `TagType [Default | Name | Id | None ]`
>   This is for fixing nlf file parameters; it specifies how to access subsequently-placed data (auto-configuration / filename/ file ID / no access method). Usually, there is no need to set this. The initial value is: `Default` (auto-configuration according to type of data installed)

### Variable References and Modifier Options

You can reference the value of a variable that is defined outside of the ROM Spec file by describing the variable in the format: `$([variable name])`. The variable's value can be set with the command line option like this: `-D`[variable name]=[value]. Alternately, you can set the value using an environment variable. If the same variable is defined with both the `-D` option and an environment variable, the `-D` option value takes priority. Following is an example of a description for a variable reference:

>     RomSpec
>     {
>         Offset     0x00000000
>         Segment    All
>         File       $(FILENAME)
>     }

If the variable value takes the form of a file path, you can reference the value by attaching a modifier option immediately after the variable name. The following values can be referenced with the modifier options `:h,``:t,``:r` and `:e`

> `For $(FILE)=C:/home/Nitro/readme.txt`:

> `:h` | The portion of the path before the final path delimiter | `$(FILE:h)=C:/home/Nitro/`
> `:t` | The portion of the path after the final path delimiter | `$(FILE:t)=readme.txt`
> `:r` | The portion of the path excluding the file extension | `$(FILE:r)=C:/home/Nitro/readme`
> `:e` | The path file-extension portion | `$(FILE:e)=txt`

### Other formats

Keywords like `"RomSpec"` used in section definitions can be written either in uppercase like `"ROMSPEC"`, or in lowercase like `"romspec"`. Anything than follows the pound sign (`#`) is treated as a comment.

To specify multiple items in `File` and `Reject`, separate them with blank spaces. Use double quotes (`" "`) to specify filenames that include blank spaces.

>     #
>     # Lines that begin with '#'are comments

>     #
>     Arm9
>     {
>     Static      "c:/Program Files/myApps/lib/main.sbin"
>        OverlayDefs "c:/Program Files/myApps/lib/overlaydefs.sbin"
>     }

>     Property
>     {
>        BannerFile  "./etc/default.bnr"
>     }

>     ROMSPEC  # Uppercase is also OK
>     {
>        Segment  ALL
>        File     boo.dat foo.dat woo.dat
>     }

## See Also

`makelcf`, `makebanner`

## Revision History

09/22/2004 Added description regarding the order of the section
07/23/2004 Added description regarding `Align` and `Align All`
06/08/2004 Initial version