ctr_makerom

Table of 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's Required

You will 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, -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, -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 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 is a file that contains the settings for the CCI file.

Format

The RSF file format is shown below.

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:          # Root path of the ROM file system
  Reject:            # File and directory names to exclude from the ROM file system
  Include:           # File names that should be included in the ROM file system
  SaveDataSize:      # Size of the save data

CardInfo:
  CardDevice:        # Set to NorFlash or None
  MediaType:         # Set to Card1 or Card2

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

Setting descriptions for each of these items are provided below.

BasicInfo

Item Description Comments
Title The title of the application. Specifies the application title in eight or fewer ASCII characters.
ProductCode Specifies the product code, or the add-on content code. If this is a product code, specify the product code issued by Nintendo.
MediaSize Specifies the media size. Specify a value of 125 MB, 256 MB, 512 MB, 1 GB, 2 GB, or 4GB.
Logo Specifies 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 Specifies the application type.
Application Specify this when building a typical application.
DlpChild Specify this when building a Download Play child.
This must be specified along with ChildIndex (described later).
Demo Specify this when you create a demo as a downloadable application.
AddOnContents Specify this when you create add-on content.
When omitted, the tool automatically chooses a value based on the DESC file contents.
UniqueId The application's unique ID. Specifies the ID issued by Nintendo.
Specifies 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 Specifies the Download Play child index. You can specify values from 0 through 255.
DemoIndex Specifies the index for downloadable application demos.
For details, 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 will be stored in the ROM file system. However, any files or directories that start with a period (".") will not be stored in the ROM file system, nor will any files or directories specified under the Reject item.		 Although setting this parameter has the same effect as setting ROMFS_ROOT in the OMake file (except for the one point below), if both are set then 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 will not be performed even if the files under the ROM file system are updated.
When you would like 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. See Build Rules (ctr_makerom) for details.
Reject Specify the names of files and directories to exclude from the ROM file system.
Any files or directories that match the names specified will not be 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 Specifies the names of files and directories that should be included 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 Specifies the size of the save data. Specify values in the format nKB, nMB, or nGB. If the media is Card1, downloadable applications can be specified only in sizes of 0 KB, 128 KB, and 512 KB.
If the media is Card2, you can specify values only in increments of 1 MB, and only up to half of the value specified for BasicInfo / BackupMemoryType.
Note: In either case, the actual size that is used is smaller than the size specified here.
To read details about usable sizes, see the Save Data File System Capacity Calculation Sheet page in the Function Reference. 		If the value specified here differs from the size of the backup memory that is actually used, then the backup memory size takes precedence.
For details, see the page on the nn::fs::FormatSaveData function in the Function Reference.


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 Specifies the game card type. 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 Specifies the remaster version. When omitted, the tool uses the default value of 0.

AccessControlInfo

Item Description Comments
Priority Specifies the priority of the main thread. You can specify values between 0 and 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 ID(s) for the title(s) with the save data you want to access. Up to three 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 own unique ID can be used.
When true is specified, access is allowed. When false is specified, access is not allowed. 		The default value is false.
FileSystemAccess Specifies the file system access permission attributes.
Specify from the following values:
  • DirectSdmc: Allows direct access to the SD Card. Specify this 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 will be 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 details, see the Build Rules.

Game Software Prototype Code

The following code has been assigned for software testing and prototyping purposes. Use this 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 ～ 0xFF3FF

 * ... A-Z, 0-9

Note: In CTR-SDK 0.14.1 and prior versions, ProductCode used the format below, 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

Refer to Build Rules (ctr_makerom) for more information about variables defined in OMakefile.

Revision History

2012/06/29
Deleted the description for the Company Code.
2012/02/16
Added a means of specifying access to the save data of another program.
Added a precaution 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 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 note that a warning is generated when code for prototyping is used.
Added note that Master Editor treats the code for prototyping as an error.
2011/04/25
Added 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 specifying CardDevice.
2011/01/26
Updated for compliance 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 description of when no logo is specified.
2010/11/18
Added description of DESC file types.
Added description of the change in logo specification.
Added description of the -icon option.
2010/11/11
Added description of file system access permission attributes.
2010/11/10
Added description of product code format change.
2010/10/29
Added description of expanded save data and backup memory specifications.
2010/10/26
Added description of logo data.
Changed 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 the -info option, CompanyCode, ProductCode, and UniqueId.
2010/07/14
Added a description of CXI files.
2009/12/22
Initial version.

CONFIDENTIAL