Difference between revisions of "Makerom"

From 3dbrew
Jump to navigation Jump to search
m (fix sample rsf link)
 
(12 intermediate revisions by 10 users not shown)
Line 3: Line 3:
 
| type        = pc utility
 
| type        = pc utility
 
| author      = [[User:3dsguy|3dsguy]]
 
| author      = [[User:3dsguy|3dsguy]]
−
| download = https://dl.dropboxusercontent.com/u/60710927/CTR/makerom/makerom.zip
+
| download = https://github.com/profi200/Project_CTR/releases
−
| source = https://github.com/3DSGuy/Project_CTR/tree/master/makerom
+
| source = https://github.com/profi200/Project_CTR/tree/master/makerom
−
| version    = 0.8
+
| version    = 0.15
 
}}
 
}}
  
−
makerom is a tool which can be used to created [[NCCH]] and [[NCSD|CCI]] and [[CIA]] files.
+
makerom is a tool which can be used to create [[NCCH]], [[NCSD|CCI]], and [[CIA]] files.
 +
 
 +
== Format Overviews ==
 +
=== NCCH ===
 +
The native format storing code binaries and data archives for the 3DS is [[NCCH]]. [[NCCH]] files are comprised of:
 +
* code/exheader/plainregion (used for code execution) (plainregion just lists included SDK library add-ons)
 +
* icon (app title text, icon, homemenu settings, see [[SMDH|here]]
 +
* banner (cbmd + cwav, i.e. the upper screen banner/sound shown on the homemenu)
 +
* logo (the splash screen displayed after an application is launched from the homemenu)
 +
* romfs (read-only filesystem used to store resources)
 +
 
 +
Typical uses for NCCH files include:
 +
* Executable image (code+exheader+icon+banner+logo+romfs)
 +
* e-Manual archive (accessed from homemenu) (romfs)
 +
* [[Download Play|DLP]] child CIA archive (accessed from application) (romfs)
 +
* Update Data archive (romfs)
 +
* Standalone data archive (romfs)
 +
* DLC index archive (icon+romfs)
 +
* DLC archive (romfs)
 +
 
 +
=== CCI ===
 +
The native format for gamecard images is [[NCSD|CCI]] and is a NCCH container format. CCI files are limited to containing 8 NCCH files, and can contain NCCH files for applications titles only.
 +
==== NCCH configuration for CCI ====
 +
{| class="wikitable"
 +
|-
 +
! NCCH
 +
! Required
 +
! Index
 +
|-
 +
| Executable image
 +
| YES
 +
| 0
 +
|-
 +
| e-Manual archive
 +
| NO
 +
| 1
 +
|-
 +
| DLP child CIA archive
 +
| NO
 +
| 2
 +
|-
 +
| Update Data archive
 +
| NO
 +
| 7
 +
|}
 +
 
 +
=== CIA ===
 +
The native format for packaging NCCH files for install is [[CIA]], which is also a NCCH container format. CIA files are limited to containing 65535 NCCH files and can be used to contain NCCH files for any title type. CIA files also contain '''signed''' data used by the 3DS for general title management and DRM. Installing custom CIA files on a 3DS which also uses eShop/SysUpdates is unwise as conflicts will likely occur.
 +
 
 +
==== NCCH configurations for CIA ====
 +
Applications (Application/DlpChild/Demo/Patch/SystemApplication):
 +
{| class="wikitable"
 +
|-
 +
! NCCH
 +
! Required
 +
! Index
 +
|-
 +
| Executable image
 +
| YES
 +
| 0
 +
|-
 +
| e-Manual archive
 +
| NO
 +
| 1
 +
|-
 +
| DLP child CIA archive
 +
| NO
 +
| 2
 +
|}
 +
 
 +
System Applet/Module:
 +
{| class="wikitable"
 +
|-
 +
! NCCH
 +
! Required
 +
! Index
 +
|-
 +
| Executable image
 +
| YES
 +
| 0
 +
|}
 +
 
 +
System Data Archives:
 +
{| class="wikitable"
 +
|-
 +
! NCCH
 +
! Required
 +
! Index
 +
|-
 +
| Data archive
 +
| YES
 +
| 0
 +
|}
 +
 
 +
DLC:
 +
 
 +
The number of DLC data archives in DLC varies for each DLC.
 +
{| class="wikitable"
 +
|-
 +
! NCCH
 +
! Required
 +
! Index
 +
|-
 +
| DLC index archive
 +
| YES
 +
| 0
 +
|-
 +
| DLC data archive
 +
| YES
 +
| Varies
 +
|}
  
 
== Using Makerom ==
 
== Using Makerom ==
  
 
=== Command line ===
 
=== Command line ===
−
Since CCI and CIA are NCCH containers, makerom was built so CXIs could be built stand alone, or straight into a container format. It is also possible rebuild CXIs as easily building a CXI from an elf. As a result the are many combinations which can be used, and for simplicity specific functions will be explained by breaking them up into argument groups:
 
  
−
'''Creating CXIs from scratch:'''
+
makerom [general args] [rsf args] [crypto args] [ncch 0 build args] [cci args] [cia args]
−
-elf <elf path> -rsf <rsf path> [-icon <[[SMDH|icon]] path> -banner <banner path>]
+
 
 +
'''General Arguments'''
 +
{| class="wikitable"
 +
|-
 +
! Argument
 +
! Acceptable values
 +
! Notes
 +
|-
 +
| -f <format>
 +
| 'ncch'/'cxi'/'cfa'/'cci'/'cia'
 +
| Specify the output file format. 'ncch'/'cxi'/'cfa' has no affect, probably parsed without error for legacy support.
 +
|-
 +
| -o <path>
 +
| Valid file path.
 +
| Specify name/path for output file. Makerom will decided a name if this is not specified.
 +
|-
 +
| -v
 +
| not required
 +
| Enables verbose output.
 +
|}
 +
 
 +
'''RSF Arguments'''
 +
{| class="wikitable"
 +
|-
 +
! Argument
 +
! Acceptable values
 +
! Notes
 +
|-
 +
| -rsf <path>
 +
| Valid file path
 +
| Specify the path to Rom Specification File(RSF). See below for creating RSF.
 +
|-
 +
| -D<NAME>=<VALUE>
 +
|
 +
| This is used to substitute where "$(<NAME>)" exists in the RSF files with "<VALUE>". (Uppercase isn't a requirement)
 +
|}
 +
 
 +
'''Crypto Arguments'''
 +
{| class="wikitable"
 +
|-
 +
! Argument
 +
! Acceptable values
 +
! Notes
 +
|-
 +
| -target <target>
 +
| 't'/'d'/'p'
 +
| Specify key-chain. This affects encryption, signing and '-desc' template availability. t=test, suitable for homebrew. d=devkit(incomplete), suitable for devkits. p=retail(unusable), suitable for signing retail software?
 +
|-
 +
| -ckeyid <index>
 +
| Any value between 0-255 (inclusive).
 +
| Overrides the default common key used to encrypt CIA title keys.
 +
|-
 +
| -showkeys
 +
| none
 +
| Dumps loaded key-chain to stdout.
 +
|}
 +
 
 +
'''NCCH Build Arguments'''
 +
{| class="wikitable"
 +
|-
 +
! Argument
 +
! Acceptable values
 +
! Notes
 +
|-
 +
| -elf <file>
 +
| Valid file path
 +
| Specify ELF. See below for creating ELF.
 +
|-
 +
| -icon <file>
 +
| Valid file path
 +
| Specify [[SMDH|icon]].
 +
|-
 +
| -banner <file>
 +
| Valid file path
 +
| Specify banner.
 +
|-
 +
| -desc <apptype>:<fw>
 +
| <apptype>='app'/'ecapp'/'demo'/'dlpchild'. <fw>='kernel version minor'.
 +
| Use a template for [[Exheader|exheader/accessdesc]]. These are hard-coded, so not all firmwares have a template. A value from 1-7 can be used in place of 'kernel version minor'. A template shouldn't be used if the title needs "special" permissions, the RSF must be configured fully.
 +
|-
 +
| -exefslogo
 +
| none
 +
| Include logo in ExeFS. Required for usage on <5.0 systems.
 +
|}
 +
 
 +
Arguments useful for rebuilding a NCCH file:
 +
{| class="wikitable"
 +
|-
 +
! Argument
 +
! Acceptable values
 +
! Notes
 +
|-
 +
| -code <file>
 +
| Valid file path
 +
| Specify decompressed/plaintext exefs code binary.
 +
|-
 +
| -exheader <file>
 +
| Valid file path
 +
| Specify plaintext exheader binary.
 +
|-
 +
| -logo <file>
 +
| Valid file path
 +
| Specify logo.
 +
|-
 +
| -plainrgn <file>
 +
| Valid file path
 +
| Specify NCCH plain-region.
 +
|-
 +
| -romfs <file>
 +
| Valid file path
 +
| Specify an unencrypted RomFS binary.
 +
|}
 +
 
 +
'''CCI Arguments'''
 +
{| class="wikitable"
 +
|-
 +
! Argument
 +
! Acceptable values
 +
! Notes
 +
|-
 +
| -content <path>:<index>
 +
| <path>=Valid file path. <index>=Any value between 0-7 (inclusive)
 +
| Include a built NCCH file in the CCI container. "-i" can be used instead of "-content".
 +
|-
 +
| -devcci
 +
| none
 +
| Build a debug CCI?
 +
|-
 +
| -nomodtid
 +
| none
 +
| Don't modify the TitleIds of NCCH files included to match NCCH0
 +
|-
 +
| -alignwr
 +
| none
 +
| Align the offset for the Card2 writable region to the end of the last NCCH in the CCI.
 +
|}
 +
 
 +
'''CIA Arguments'''
 +
{| class="wikitable"
 +
|-
 +
! Argument
 +
! Acceptable values
 +
! Notes
 +
|-
 +
| -content <path>:<index>:<id>
 +
| <path>=Valid file path. <index>=Any value between 0x0-0xFFFF (inclusive). <id>=Any value between 0x0-0xFFFFFFFF (inclusive)
 +
| Include a built NCCH file in the CIA container. If <id> isn't specified, it will be generated randomly. "-i" can be used instead of "-content".
 +
|-
 +
| -major <version>
 +
| Any value between 0-63 (inclusive)
 +
| Specify the version major for the title. This cannot be used with "-dver".
 +
|-
 +
| -minor <version>
 +
| Any value between 0-63 (inclusive)
 +
| Specify the version minor for the title. This cannot be used with "-dver".
 +
|-
 +
| -micro <version>
 +
| Any value between 0-15 (inclusive)
 +
| Specify the version micro for the title.
 +
|-
 +
| -dver <version>
 +
| Any value between 0-4095 (inclusive)
 +
| Specify the data-title version for the title. This cannot be used with "-major" or "-minor".
 +
|-
 +
| -dlc
 +
| none
 +
| Specify this flag when building a DLC CIA.
 +
|-
 +
| -rand
 +
| none
 +
| Use a random title key to encrypt CIA content.
 +
|}
  
−
'''Rebuilding CXIs:'''
+
==== Examples ====
−
-code <decompressed exefs .code> -exheader <exheader from original CXI> -rsf <rsf path> [-icon <[[SMDH|icon]] path> -banner <banner path> -romfs <cleartext romfs binary>]
 
  
−
'''Creating CFAs:'''
+
General examples:
−
-f cfa -rsf <rsf path> [-icon <[[SMDH|icon]] path> -romfs <romfs binary>]
 
  
−
'''Creating CCIs:'''
+
'''Create CXI'''
−
  -f cci [-content <path>:<index> ...]
+
  makerom -o sample.cxi -rsf sample.rsf -target t -elf sample.elf -icon sample.icn -banner sample.bnr -desc app:4
  
−
'''Creating CCIs:'''
+
'''Create CFA'''
−
  -f cia [-content <path>:<index>:<id> ...]
+
  makerom -o sample.cfa -rsf sample.rsf -target t
  
−
'''Using Desc presets:'''
+
'''Create CCI'''
−
  -desc <app type>:<firm version>
+
  makerom -f cci -o sample.cci -target t -i sample.cxi:0 -i sample.cfa:1
  
−
* 'app type' can be SDApp / ECApp / Demo / DlpChild
+
'''Create CIA'''
−
* 'firm version' is the target kernel version minor for the intended 3DS system.
+
makerom -f cia -o sample.cia -target t -i sample.cxi:0:0 -i sample.cfa:1:1
  
−
'''Examples:'''
 
−
Create a CCI, using a manual CFA, and a desc preset:
 
−
makerom -f cci -elf homebrew.elf -rsf app.rsf -desc sdapp:33 -icon homebrew.icn -banner homebrew.bnr -content manual.cfa:1 -o homebrew.cci
 
  
−
Create a CIA using an already built application CXI and manual CFA:
+
Makerom supports building a NCCH file and including it automatically (as index 0) into a NCCH container:
−
makerom -f cia -content homebrew.cxi:0:0 -content manual.cfa:1:1 -o homebrew.cia
 
  
−
Rebuild a CXI:
+
'''Create CCI and CXI at the same time and include a CFA'''
−
  makerom -code code.bin -exheader exheader.bin -icon icon.bin -banner banner.bin -romfs romfs.bin -rsf app.rsf -desc sdapp:33 -o rebuild.cxi
+
  makerom -f cci -o sample.cci -rsf sample.rsf -target t -elf sample.elf -icon sample.icn -banner sample.bnr -desc app:4 -i sample.cfa:1
  
 +
'''Create CIA and CXI at the same time and include a CFA'''
 +
makerom -f cia -o sample.cia -rsf sample.rsf -target t -elf sample.elf -icon sample.icn -banner sample.bnr -desc app:4 -i sample.cfa:1:1
 +
 +
Rebuilding CXI:
 +
makerom -o rebuild.cxi -rsf rebuild.rsf -target t -code rebuild/code.bin -exheader rebuild/exheader.bin -icon rebuild/icon.bin -banner rebuild/banner.bin -romfs rebuild/romfs.bin
  
 
=== Creating RSF files ===
 
=== Creating RSF files ===
−
Inspired by Nintendo's format for their makerom, is a yaml configuration file, required for creating NCCH files. CIA/CCI can be created without using a RSF file, but default settings will be used.
+
Inspired by Nintendo's format for their makerom, a yaml configuration file is required for creating NCCH files. CIA/CCI can be created without using a RSF file, but default settings will be used.
  
−
For CXI, RSF files can be used to specify permissions, and access control settings. However makerom can use default settings by use of the "-desc" option, which removes the requirement for specifing them in the RSF file.
+
For CXI, RSF files can be used to specify permissions, and access control settings. Makerom can use default settings by use of the "-desc" option, which removes the requirement for specifying them in the RSF file.
  
−
Sample RSF to be used with "-desc": [https://dl.dropboxusercontent.com/u/60710927/CTR/makerom/sample0.rsf download]
+
Sample RSF to be used with "-desc": [https://gist.githubusercontent.com/3DSGuy/83e12e0ae3dcccb9827f/raw/sample0.rsf download] (link broken)
  
−
Sample RSF to be used without "-desc": [https://dl.dropboxusercontent.com/u/60710927/CTR/makerom/sample1.rsf download]
+
Sample RSF to be used without "-desc": [https://gist.github.com/jakcron/9f9f02ffd94d98a72632 download]
  
 
=== Creating ELF files ===
 
=== Creating ELF files ===
−
ELF files created using the official SDK can be used with makerom. But ELF files created using smea's WIP ctrulib, can be used, provided they are linked with this linker script: [https://dl.dropboxusercontent.com/u/60710927/CTR/makerom/ctr_homebrew.ld download]
+
The latest devkitARM used in conjunction with [https://github.com/smealum/ctrulib ctrulib] can create ELF files compatible with makerom.
 +
 
 +
ELF files that are created using the official SDK are also supported by makerom.
  
 
== Compiling Source ==
 
== Compiling Source ==
−
For Windows use MinGW, 64bit versions of MinGW are supported also.
+
For Windows a MinGW-W64/MSYS build setup is required.  
  
 
For Linux, gcc/g++/make must be installed.
 
For Linux, gcc/g++/make must be installed.
  
−
All additional libraries used by makerom, are included in the source, and are linked statically.
+
All additional libraries used by makerom (polarssl/libyaml) are included in the source, and are linked statically.
−
 
 
−
== Issues ==
 
−
 
 
−
* Proper ticket index generation isn't complete (CIA tickets are valid for only one content)
 
−
* RomFs hasn't been completely implemented (But valid pre-built romfs can be used as substitute)
 

Latest revision as of 04:19, 6 June 2016

makerom
General
Author(s)3dsguy
TypePC utility
Version0.15
Links
Download
Source


makerom is a tool which can be used to create NCCH, CCI, and CIA files.

Format Overviews[edit]

NCCH[edit]

The native format storing code binaries and data archives for the 3DS is NCCH. NCCH files are comprised of:

  • code/exheader/plainregion (used for code execution) (plainregion just lists included SDK library add-ons)
  • icon (app title text, icon, homemenu settings, see here
  • banner (cbmd + cwav, i.e. the upper screen banner/sound shown on the homemenu)
  • logo (the splash screen displayed after an application is launched from the homemenu)
  • romfs (read-only filesystem used to store resources)

Typical uses for NCCH files include:

  • Executable image (code+exheader+icon+banner+logo+romfs)
  • e-Manual archive (accessed from homemenu) (romfs)
  • DLP child CIA archive (accessed from application) (romfs)
  • Update Data archive (romfs)
  • Standalone data archive (romfs)
  • DLC index archive (icon+romfs)
  • DLC archive (romfs)

CCI[edit]

The native format for gamecard images is CCI and is a NCCH container format. CCI files are limited to containing 8 NCCH files, and can contain NCCH files for applications titles only.

NCCH configuration for CCI[edit]

NCCH Required Index
Executable image YES 0
e-Manual archive NO 1
DLP child CIA archive NO 2
Update Data archive NO 7

CIA[edit]

The native format for packaging NCCH files for install is CIA, which is also a NCCH container format. CIA files are limited to containing 65535 NCCH files and can be used to contain NCCH files for any title type. CIA files also contain signed data used by the 3DS for general title management and DRM. Installing custom CIA files on a 3DS which also uses eShop/SysUpdates is unwise as conflicts will likely occur.

NCCH configurations for CIA[edit]

Applications (Application/DlpChild/Demo/Patch/SystemApplication):

NCCH Required Index
Executable image YES 0
e-Manual archive NO 1
DLP child CIA archive NO 2

System Applet/Module:

NCCH Required Index
Executable image YES 0

System Data Archives:

NCCH Required Index
Data archive YES 0

DLC:

The number of DLC data archives in DLC varies for each DLC.

NCCH Required Index
DLC index archive YES 0
DLC data archive YES Varies

Using Makerom[edit]

Command line[edit]

makerom [general args] [rsf args] [crypto args] [ncch 0 build args] [cci args] [cia args]

General Arguments

Argument Acceptable values Notes
-f <format> 'ncch'/'cxi'/'cfa'/'cci'/'cia' Specify the output file format. 'ncch'/'cxi'/'cfa' has no affect, probably parsed without error for legacy support.
-o <path> Valid file path. Specify name/path for output file. Makerom will decided a name if this is not specified.
-v not required Enables verbose output.

RSF Arguments

Argument Acceptable values Notes
-rsf <path> Valid file path Specify the path to Rom Specification File(RSF). See below for creating RSF.
-D<NAME>=<VALUE> This is used to substitute where "$(<NAME>)" exists in the RSF files with "<VALUE>". (Uppercase isn't a requirement)

Crypto Arguments

Argument Acceptable values Notes
-target <target> 't'/'d'/'p' Specify key-chain. This affects encryption, signing and '-desc' template availability. t=test, suitable for homebrew. d=devkit(incomplete), suitable for devkits. p=retail(unusable), suitable for signing retail software?
-ckeyid <index> Any value between 0-255 (inclusive). Overrides the default common key used to encrypt CIA title keys.
-showkeys none Dumps loaded key-chain to stdout.

NCCH Build Arguments

Argument Acceptable values Notes
-elf <file> Valid file path Specify ELF. See below for creating ELF.
-icon <file> Valid file path Specify icon.
-banner <file> Valid file path Specify banner.
-desc <apptype>:<fw> <apptype>='app'/'ecapp'/'demo'/'dlpchild'. <fw>='kernel version minor'. Use a template for exheader/accessdesc. These are hard-coded, so not all firmwares have a template. A value from 1-7 can be used in place of 'kernel version minor'. A template shouldn't be used if the title needs "special" permissions, the RSF must be configured fully.
-exefslogo none Include logo in ExeFS. Required for usage on <5.0 systems.

Arguments useful for rebuilding a NCCH file:

Argument Acceptable values Notes
-code <file> Valid file path Specify decompressed/plaintext exefs code binary.
-exheader <file> Valid file path Specify plaintext exheader binary.
-logo <file> Valid file path Specify logo.
-plainrgn <file> Valid file path Specify NCCH plain-region.
-romfs <file> Valid file path Specify an unencrypted RomFS binary.

CCI Arguments

Argument Acceptable values Notes
-content <path>:<index> <path>=Valid file path. <index>=Any value between 0-7 (inclusive) Include a built NCCH file in the CCI container. "-i" can be used instead of "-content".
-devcci none Build a debug CCI?
-nomodtid none Don't modify the TitleIds of NCCH files included to match NCCH0
-alignwr none Align the offset for the Card2 writable region to the end of the last NCCH in the CCI.

CIA Arguments

Argument Acceptable values Notes
-content <path>:<index>:<id> <path>=Valid file path. <index>=Any value between 0x0-0xFFFF (inclusive). <id>=Any value between 0x0-0xFFFFFFFF (inclusive) Include a built NCCH file in the CIA container. If <id> isn't specified, it will be generated randomly. "-i" can be used instead of "-content".
-major <version> Any value between 0-63 (inclusive) Specify the version major for the title. This cannot be used with "-dver".
-minor <version> Any value between 0-63 (inclusive) Specify the version minor for the title. This cannot be used with "-dver".
-micro <version> Any value between 0-15 (inclusive) Specify the version micro for the title.
-dver <version> Any value between 0-4095 (inclusive) Specify the data-title version for the title. This cannot be used with "-major" or "-minor".
-dlc none Specify this flag when building a DLC CIA.
-rand none Use a random title key to encrypt CIA content.

Examples[edit]

General examples:

Create CXI 

makerom -o sample.cxi -rsf sample.rsf -target t -elf sample.elf -icon sample.icn -banner sample.bnr -desc app:4

Create CFA 

makerom -o sample.cfa -rsf sample.rsf -target t

Create CCI 

makerom -f cci -o sample.cci -target t -i sample.cxi:0 -i sample.cfa:1

Create CIA 

makerom -f cia -o sample.cia -target t -i sample.cxi:0:0 -i sample.cfa:1:1


Makerom supports building a NCCH file and including it automatically (as index 0) into a NCCH container:

Create CCI and CXI at the same time and include a CFA 

makerom -f cci -o sample.cci -rsf sample.rsf -target t -elf sample.elf -icon sample.icn -banner sample.bnr -desc app:4 -i sample.cfa:1

Create CIA and CXI at the same time and include a CFA 

makerom -f cia -o sample.cia -rsf sample.rsf -target t -elf sample.elf -icon sample.icn -banner sample.bnr -desc app:4 -i sample.cfa:1:1

Rebuilding CXI: 

makerom -o rebuild.cxi -rsf rebuild.rsf -target t -code rebuild/code.bin -exheader rebuild/exheader.bin -icon rebuild/icon.bin -banner rebuild/banner.bin -romfs rebuild/romfs.bin

Creating RSF files[edit]

Inspired by Nintendo's format for their makerom, a yaml configuration file is required for creating NCCH files. CIA/CCI can be created without using a RSF file, but default settings will be used.

For CXI, RSF files can be used to specify permissions, and access control settings. Makerom can use default settings by use of the "-desc" option, which removes the requirement for specifying them in the RSF file.

Sample RSF to be used with "-desc": download (link broken)

Sample RSF to be used without "-desc": download

Creating ELF files[edit]

The latest devkitARM used in conjunction with ctrulib can create ELF files compatible with makerom.

ELF files that are created using the official SDK are also supported by makerom.

Compiling Source[edit]

For Windows a MinGW-W64/MSYS build setup is required.

For Linux, gcc/g++/make must be installed.

All additional libraries used by makerom (polarssl/libyaml) are included in the source, and are linked statically.

Retrieved from "https://www.3dbrew.org/w/index.php?title=Makerom&oldid=17471"