ctr_makerom

Contents

  1. Introduction
  2. How to Use
  3. RSF File
  4. DESC File
  5. Game Software Prototype Code
  6. Variables Defined in OMakefile
  7. Revision History

Introduction

The ctr_makerom tool is for creating CCI (CTR Card Image) files.
CCI files are created based on the content in RSF files.

Use the -f option to generate a CXI (CTR eXecutable Image) file and a CFA (CTR File Archive) file.

How to Use

What Is Required

You need the following to create a CCI file:

RSF files contain the information required to create a CCI file. They must be created individually for each application. By default, the SDK build system uses $(CTRSDK_ROOT)/resources/specfiles/Application.rsf (the default RSF file).
Be sure to always use the DESC file included in the SDK.

Commands

Format 1

% ctr_makerom32 ELF_FILE -rsf RSF_FILE -desc DESC_FILE [-o OUTPUT_FILE] [-Dname=value...] [-f FORMAT] [-info INFO_FILE] [-banner BANNER_FILE] [-icon ICON_FILE] [-content CONTENTS_PATH:INDEX] [-j NUM]

Creates files in CXI, CFA, and CCI format. You must specify ELF_FILE, -rsf, and -desc.

Format 2

% ctr_makerom32 ELF_FILE -rsf RSF_FILE -desc DESC_FILE -f le -lr LR_FILE -m 0x01000000 -o OUTPUT_FILE [-Dname=value...] [-info INFO_FILE] [-banner BANNER_FILE] [-icon ICON_FILE] [-j NUM]

Creates files in LE format. You must specify ELF_FILE, -rsf, -desc, -f, -lr, -m, and -o.

Format 3

% ctr_makerom32 -rsf RSF_FILE -desc DESC_FILE -f lr -o OUTPUT_FILE [-Dname=value...] [-info INFO_FILE] [-j NUM]

Creates files in LR format. You must specify a value for -rsf, -desc, -f, and -o.

Format 4

% ctr_makerom32 -f list -le LE_FILE -lr LR_FILE -o OUTPUT_FILE

Creates files in CCL format. You must specify all options.

Options

Options Description
-rsf Specifies the RSF file.
-desc Specifies the DESC file.
-banner Specifies the banner file.
-icon Specifies the icon file.
Unless you specify an icon file with this option, you cannot get the EULA version from the application.
-content CONTENTS_PATH:INDEX Specifies content (CFA files) included in the CCI file.
Specify the content file path in CONTENTS_PATH.
INDEX specifies the index number that contains this content. There is a predetermined INDEX to specify for each type of content. Specify 1 for a CFA file storing an e-manual. Specify 2 for a CFA file storing a download-play child program. You must not specify any other values.
For more information, see the documentation for each type of content.
-o Specifies the output filename. If this option is omitted, the output is written to a file with a filename that consists of the input .axf filename with its extension replaced by .cci, .cxi, or .cfa. The extension is determined by the format specified in the -f option.
-Dname=value Specifies the variable name (name) and value (value) to reference in the RSF file. Locations where $(name) is written in the RSF file are replaced with the value command line argument and then evaluated.
-f FORMAT Specifies the format of the image to output. The following values can be specified for FORMAT.
card Outputs in .cci format. Specify this option when creating a standard card application.
exec Outputs in .cxi format. Specify this option when building an import application.
To create images that can be imported, you must input the generated CXI file to ctr_makecia and create a CIA file.
data Outputs in CFA format.
list Outputs in CCL format.
le Outputs in LE format used for CCL.
lr Outputs in LR format used for CCL.
If nothing is specified, it is assumed that exec is specified.
-info Specifies the output file to which to output information about the output image. When omitted, the file is saved with the .xml filename extension. This file contains information about the application title and ROMFS.
-j NUM Specifies the number of makerom parallel processes. However, only some processes can be performed in parallel.
When it is not specified, the CPU core count for the execution environment is acquired and used.
-le LE_FILE Specifies the file path for an LE-format file created in format 2.
-lr LR_FILE Specifies the file path for an LR-format file created in format 3.
-m 0x01000000 Required for format 2. Always specify 0x01000000.
-nowarn WARNING_NUMBER Suppresses warnings. Currently, you can only specify 0 for WARNING_NUMBER. When you specify a value of 0, you can suppress warnings for invalid combinations of CardDevice and BackupMemoryType.

RSF File

This file contains the settings for the CCI file.

Format

The RSF file format includes the following elements.

BasicInfo:
  Title:             # Application title.
  ProductCode:       # Product code.
  MediaSize:         # Media size.
  Logo:              # Logo data specification.
  BackupMemoryType:  # Backup memory type.

TitleInfo:
  Category:          # Title category.
  UniqueId:          # Unique ID for title code.
  ChildIndex:        # Download Play child index.
  DemoIndex:         # Downloadable application demos index.
  Variation:         # Add-on content index.

Rom:
  HostRoot:          # The root path of the ROM file system.
  Reject:            # Specifies files and directories to exclude from the ROM file system.
  Include:           # Specifies files that should be included in the ROM file system.
  SaveDataSize:      # Save data size.

CardInfo:
  CardDevice:        # Set to NorFlash or None.
  MediaType:         # Set to Card 1 or Card 2.

AccessControlInfo:
  Priority:          # Main thread priority.
  UseExtSaveData:    # Whether to use expanded save data.
  ExtSaveDataNumber: # Expanded save data number.
  FileSystemAccess:  # File system access permissions.

SystemControlInfo:
StackSize:   # Stack size of main thread.
  RemasterVersion:   # The remaster version.

Option:
  EnableCompress:  # Enables or disables compression of static memory.

Configure the values of the items under the seven main sections (BasicInfo, TitleInfo, Rom, AccessControlInfo, SystemControlInfo, and Option).
Set the values using the following format:

Specifying Single Values

Key Name: Value

Specifying Multiple Values

Key Name:
  - Value 1
  - Value 2
  ...

Notes

The following table describes the settings for each of these items.

BasicInfo

Item Description Comments
Title The title of the application. Specify the application title in eight or fewer ASCII characters.
ProductCode Specify the product code, or the add-on content code. If it is a product code, specify the product code issued by Nintendo.
MediaSize Specify the media size. Specify a value of 125 MB, 256 MB, 512 MB, 1 GB, 2 GB, or 4GB.
Logo Specify the logo data type. Specify Nintendo for Nintendo titles, Distributed for titles for which Nintendo purchased the publishing license from the software manufacturer or titles for which Nintendo acquired the publishing license from a publisher, and Licensed for all other titles. For Chinese region titles, specify iQue.
BackupMemoryType This parameter is not used at the present time. It will be deleted in the future. This parameter has been integrated into SaveDataSize.

TitleInfo

Item Description Comments
Category Specify the application type.
Application Specify this item when building a typical application.
DlpChild Specify this item when building a Download Play child.
It must be specified along with ChildIndex (described later).
Demo Specify this item when you create a demo as a downloadable application.
AddOnContents Specify this item when you create add-on content.
When omitted, the tool automatically chooses a value based on the DESC file contents.
UniqueId The unique ID of the application. Specify the ID issued by Nintendo.
Specify the same ID as the parent device for Download Play child devices.		 You can specify a value from 0x00300 through 0xf7fff. An error occurs if you do not specify a value. In the default RSF file, the end of the trial code is used as the UniqueId.
ChildIndex Specify the Download Play child index. You can specify values from 0 through 255.
DemoIndex Specify the index for downloadable application demos.
For more information, see CTR Demo Creation Procedures for Downloadable Demos.		 You can specify values from 1 through 255.
Variation This option specifies the index of add-on content. You can specify values from 0 through 255.

Rom

Item Description Comments
HostRoot The root path of the ROM file system.
Specify either an absolute path or a relative path from the directory that is the current directory when executing ctr_makerom. All files and directories under the directory specified here are stored in the ROM file system. However, any files or directories that start with a period ("."), or that are specified under the Reject item, are not stored in the ROM file system.		 Although setting this parameter has the same effect as setting ROMFS_ROOT in the OMake file (except for the following point), if both are set HostRoot has precedence.
  • When HostRoot is specified, the dependency relationships for the files and directories under the specified directory are not set, and a rebuild is not performed even if the files under the ROM file system are updated.
When you want to set the dependency relationships for files and directories under the directory specified with HostRoot, they must be set with the Omake file'sROMFS_DEPENDENCIES. For more information, see Build Rules (ctr_makerom).
Reject Specify the names of files and directories to exclude from the ROM file system.
Any files or directories that match the specified names are not stored in the ROM file system. You can set multiple values. Specifications can use the "*" and "?" wildcards ("*" matches 0 or more characters, and "?" matches a single character) or the .NET Framework regular expressions. When specifying paths, specify absolute paths from the root directory specified by HostRoot.
The only character that can be used as a path delimiter is the / character.

When specifying wildcards, denote paths that begin with '/'.

Example:
Reject:

  - "/abc*"          # Exclude files in HostRoot that start with "abc."
  - "/*def*"         # Exclude files that contain the string "def."


When specifying regular expressions, start the notation pattern with '>'.

Example:
Reject:

  - ">^/abc.*"          # Exclude files in HostRoot that start with "abc."
  - ">def.*"            # Exclude files that contain the string "def."
  - ">^/[^/]+/.*ghi.*"  # Exclude files two levels below the HostRoot directory that contain the string "ghi."



When the first character is other than '/' or '>', it is treated as a wildcard specification. Although operation specifications of this type were supported up to CTR-SDK 1.0, their use is not recommended.
For example, if the filename matches, it is excluded regardless of the directory it is in.

 Use the syntax described in the Specifying Multiple Values section.
Include Specify the names of files and directories to include in the ROM file system.
An error occurs if files and directories matching the specified names do not exist in the ROM file system.
You can set multiple values. The format for specifying values is the same as for Reject.
 Use the syntax described in the Specifying Multiple Values section.
SaveDataSize Specify the size of the save data. Specify values in the format nKB, nMB, or nGB. If Card1 is specified for CardInfo/MediaType, a value of 0 KB, 128 KB, or 512 KB can be specified.
If Card2 is specified for CardInfo/MediaType, any value can be specified in 1 MB units up to a maximum of half the value specified for BasicInfo/MediaSize.
Note: In either case, the actual size that is used is smaller than the size specified here.
For more information about the sizes that can be used, see the Save Data File System Capacity Calculation Sheet page in the Function Reference. 		If the specified value differs from the size of the backup memory actually being used, the backup memory size takes precedence. (However, if you specify nothing or a size of 0, CardInfo/MediaType is set to None by default, and you cannot use backup memory.)
For more information, see the function reference page for nn::fs::FormatSaveData.

If this value is not specified, it is treated as if a size of 0 has been specified.


The Card2 specifications are provisional, and may change moving forward.

CardInfo

Item Description Comments
CardDevice Specify NorFlash if MediaType is Card1 and SaveDataSize is larger than 0.
Otherwise, specify None.
This value can be omitted because if it is unspecified, the appropriate value is determined automatically.
MediaType Specify the type of game card according to the size of save data required. Specify either Card1 or Card2. When omitted, the tool uses the default value of Card1.

SystemControlInfo

Item Description Comments
StackSize Specify the stack size of the main thread (in bytes). Must be a multiple of 4096. (Default value: 256 KB)
RemasterVersion Specify the remaster version. When omitted, the tool uses the default value of 0.

AccessControlInfo

Item Description Comments
Priority Specify the priority of the main thread. You can specify values from 0 through 31 (inclusive).
UseExtSaveData Specify true when using expanded save data. The default value is false.
ExtSaveDataNumber Specify the expanded save data number using 20 bits. The default is the UniqueId.
OtherUserSaveDataId1
OtherUserSaveDataId2
OtherUserSaveDataId3		 Specify the unique IDs for the titles with the save data you want to access. Up to three IDs can be specified.
If the unique ID you want to specify is the same as the unique ID of the program that is made by this RSF file, you can just set true for UseOtherVariationSaveData and not bother setting anything for OtherUserSaveDataId.
UseOtherVariationSaveData Specify whether the save data of titles with the same unique ID as the local one can be accessed.
When true is specified, access is allowed. When false is specified, access is not allowed. 		The default value is false.
FileSystemAccess Specify the file system access permission attributes.
Specify from the following values:
  • DirectSdmc: Allows direct access to the SD Card. Specify this option when using the library to directly access the SD CARD.
  • DirectSdmcWrite: Enables direct access to the SD Card for writing only.
  • Debug: Enables debug features, such as direct access to SD Cards. This value cannot be specified for retail versions.
When Debug is specified, restrictions on access to the file system are eased in part. For this reason, actions that operate with Debug specified may not operate correctly when Debug is not specified. To confirm the operations of retail products, be sure to check them with Debug not specified. 		Use the syntax described in the Specifying Multiple Values section.

Option

Item Description Comments
EnableCompress Specify true to enable static memory compression or false to disable it. Memory is not compressed if doing so does not decrease the size. The compression rate is output to the file specified in the -info argument. If this argument is not specified, the default value of true is used.

Variables

Using the -Dname=value option allows you to pass variable names and their corresponding values to the ctr_makerom tool. The ctr_makerom tool replaces any occurrences of $(name) within the RSF file with the specified value, then evaluates the results. An example is shown below.

$ ctr_makerom32 test.axf -o test.cci -rsf test.rsf -DTITLE=Test -DROMFS_ROOT=files

--- test.rsf
BasicInfo:
  Title: $(TITLE)

Rom:
  HostRoot: "$(ROMFS_ROOT)"

--- Value at final evaluation.
BasicInfo:
  Title: Test

Rom:
  HostRoot: "files"

DESC File

DESC files are placed in the CTR_SDK/resources/specfiles folder. Use the appropriate DESC file depending on the type of application you are creating.

Application Type DESC File Comments
General applications Application.desc
Download Play child DlpChild.desc
Downloadable application demo DemoVersion.desc

Edits to the DESC file are prohibited. Editing this file may prevent your application from operating properly.

When you use the build system, the option -desc CTR_SDK/resources/specfiles/Application.desc is specified automatically when you run ctr_makerom.
You can also specify within the OMakefile what DESC file to use. For more information, see the Build Rules.

Game Software Prototype Code

The following code has been assigned for software testing and prototyping purposes.
Use it as an ID for internal testing. Be careful to avoid duplicate IDs within your company and development department.
Note that if you use this code for prototyping it will be handled as an error by Master Editor.

BasicInfo:
  ProductCode: "CTR-*-****"

TitleInfo:
  UniqueId   : 0xFF000 through 0xFF3FF

 * ... A-Z, 0-9

Note: In CTR-SDK 0.14.1 and prior versions, ProductCode used the following format, but this format is no longer usable in subsequent versions.
The value that is used in the 0.14.1 environment is the value with the "(###)" portion removed.

  ProductCode: "CTR-*-**** (###)"

Variables Defined in OMakefile

For more information about variables defined in OMakefile, see Build Rules (ctr_makerom).

Revision History

2012/06/29
Deleted the description of the Company Code.
2012/02/16
Added a means of specifying access to the save data of another program.
Added a caution about specifying AccessControlInfo/Debug.
2012/02/13
Added a description of Include.
2012/01/20
Noted that BackupMemoryType cannot be used anymore.
Noted that the specification has been changed for CardDevice.
2012/01/11
Added 4 GB to the media sizes.
2011/12/15
Added text about add-on content codes and add-on content indices.
Added a method for specifying logos for the Chinese region.
2011/12/07
Added a reference to Demo Creation Procedures for Downloadable Demos to the DemoIndex item of the TitleInfo section.
2011/09/29
Added information specific to DemoIndex and TitleInfo.
2011/09/05
Added text about CardDevice download applications.
2011/08/03
Added information on -nowarn.
2011/07/21
Added what to specify in Category and DESC for a downloadable application demo.
2011/05/24
Added information on what to specify in Category for add-on content.
2011/05/18
Deleted the note that a warning is generated when code for prototyping is used.
Added a note that Master Editor treats the code for prototyping as an error.
2011/04/25
Added an explanation relating to CCL builds.
Corrected misleading text.
2011/04/04
Added information about SaveDataSize.
2011/03/25
Added supplementary information about BackupMemoryType.
2011/03/23
Added information about -f exec.
Revised "NAND app" to "import application."
2011/02/17
Added information about specifications for CardDevice.
2011/01/26
Complied with the changes in specification methods for Reject.
2010/12/27
Added a method for specifying the remaster version.
2010/12/10
Added remarks about ChildIndex.
Added information about Download Play child devices to UniqueId.
2010/12/07
Added a description of when no logo is specified.
2010/11/18
Added a description of DESC file types.
Added a description of the change in logo specification.
Added a description of the -icon option.
2010/11/11
Added a description of the file system access permission attributes.
2010/11/10
Added a description of the change in the format of the product code.
2010/10/29
Added a description of expanded save data and backup memory specifications.
2010/10/26
Added a description of logo data.
Changed the specifiable range for UniqueId to 0x300.
2010/10/07
Added the -j option.
2010/09/24
Changed the -cxi option to -content and included a description.
Included a description of the -banner and -icon options.
Included a description of Category and ChildIndex specifications for TitleInfo and the logo specification for BasicInfo.
2010/08/17
Added the Game Software Prototype Code section.
2010/08/03
Added descriptions of the EnableCompress and MediaSize options.
Deleted the InitialCode option.
2010/07/19
Added a description of specifying the -info option, CompanyCode, ProductCode, and UniqueId.
2010/07/14
Added a description of CXI files.
2009/12/22
Initial version.

CONFIDENTIAL