Mastering Cafe Applications

IMPORTANT:
Since the SDK 2.11.07, you must use makecfmaster to create the final master image that you submit to Lotcheck. The makecfmaster tool was added to versions of the SDK starting from 2.11.x. This command-line tool was created to replace makecfmaster.sh and the mastering-related features in cafex. For more information, see the page on makecfmaster.

Introduction to Mastering

If you have built your application, and are ready to convert it to a format that can be submitted as a master ROM, first see Wii U Master ROM Creation And Submission Procedures.

Types of Master Image Files

There are two types of Master Image Files:

Since most tools such as HDD uploader or R-disc writer support master archive file for input, developers do not have to handle full-padded image file format.

Creating Master Archive Images

To master an application, open a Cafe Cygwin shell (cafe.bat) or a Windows Cafe environment (cafex_env.bat) and invoke the makecfmaster command:

makecfmaster archive -r <rpx file>.rpx [-o <output file name>] [-w <work directory>]
IMPORTANT:
Before you master an application, you must run the application on the CAT-DEV without the debugger. This helps avoid a scenario where an application cannot run successfully on the CAT-DEV because it is waiting for the debugger.

Where:

In the following example, the program testapp.rpx and its associated content files will be mastered into the file testmaster.wumad at the directory $OUT_PATH.

$ makecfmaster archive -r $APP_PATH/testapp.rpx -o $OUT_PATH/testmaster -w $WORK_DIR

The same example, but in a Windows environment:

makecfmaster archive -r %APP_PATH%\testapp.rpx -o %OUT_PATH%\testmaster -w %WORK_DIR%

Rating Images

NOTE:
The use of this feature is limited to particular titles. As for a general application, dummy images (not displayed to users) are automatically inserted when creating the wumad. Set up original rating images only when Nintendo instructs to do so.

As of SDK version 2.10.03, a service is available on the Wii U for automatically pushing applications to users who have opted in. (For more information about this service, see the Wii U Overview and other related documents.) For your application to support this service, you must include the rating images displayed to the user on initial boot in your WUMAD file. To include rating images in your WUMAD file, you must place the images in the $CAFE_META_DIR directory with the filenames specified in the following table, and run makecfmaster. Any rating images that are missing when makecfmaster is executed are created using copies of a dummy file. Dummy images are not displayed to the user. The size of the image must be 896 × 224 pixels (W×H).

Rating Agency (Language) Image Filename
CERO (Japanese) CERO_ja.jpg
CGSRR CGSRR_zh.jpg
COB COB_en.jpg
ESRB (English) ESRB_en.jpg
ESRB (French) ESRB_fr.jpg
GRB GRB_ko.jpg
OFLC OFLC_en.jpg
PEGI (English) PEGI_en.jpg
PEGI+BBFC PEGI_BBFC_en.jpg
PEGI_Portugal PEGI_Portugal_pt.jpg
PEGI (Italian) PEGI_it.jpg
PEGI (Dutch) PEGI_nl.jpg
PEGI (Spanish) PEGI_es.jpg
PEGI (German) PEGI_de.jpg
PEGI (French) PEGI_fr.jpg
PEGI (Portuguese) PEGI_pt.jpg
PEGI (Russian) PEGI_ru.jpg
USK USK_de.jpg

Notes

IMPORTANT:
The disc format changed as of SDK 2.10.03. For this reason, if you insert a disc mastered with version 2.10.03 of the SDK or later into a console with version 2.09 of the SDK or earlier, the console will fail to recognize the title on the disc. This is not a bug. The console will be able to recognize and run the title after a system update.

Creating Add-On Content Master Archive Images

To create an add-on content master archive image from content files, open a Cafe Cygwin shell (cafe.bat) or a Windows Cafe environment (cafex_env.bat) and invoke the makecfmaster aoc command:

$ makecfmaster aoc <aoc root directory> <aoc name>

Where:

In the following example, the content files under $AOC_ROOT/content/ and the associated files will be mastered into the file AocTest0001.wumad in the directory $AOC_ROOT/outdir.

$ makecfmaster aoc -a $AOC_ROOT AocTest0001

The same example, but in a Windows environment:

makecfmaster aoc %AOC_ROOT% AocTest0001

Notes

Creating Patch Master Archive Images

To create a patch master archive image from the past master archive image and the current source tree, open a Cafe Cygwin shell (cafe.bat) or a Windows Cafe environment (cafex_env.bat) and invoke the makecfmaster patch command:

makecfmaster patch -p <most recent master archive>.wumad -r <rpx file>.rpx [-o <output file name>] [-w <work directory>]

Where:

In the following example, the updated files of the program testapp.rpx will be extracted and be mastered into a new patch archive patch002_testapp.wumad.

$ makecfmaster patch -p patch001_testapp.wumad -r testapp.rpx -o patch002_testapp

Notes

IMPORTANT:
Confirm the created patch (WUMAD file) has continuity when submitting. The continuity of the patch may be checked from the Master Editor by selecting ToolVerify Continuity (P). For more information, see the Wii U Master Editor Manual.

Creating Master Images

To create a fully-padded master image file (.wum) from a master archive, open a Cafe Cygwin shell (cafe.bat) or a Windows Cafe environment (cafex_env.bat) and invoke the makecfmaster disc command:

makecfmaster disc -i <master archive file> [-o <output file name>] [-w <work directory>]

Where:

In the following example, the master archive testmaster.wumad is extracted to full padded master image file testimage.wum.

$ makecfmaster disc -i $MASTER_PATH/testmaster.wumad -o $OUT_PATH/testimage -w $WORK_DIR

The same example, but in a Windows environment:

makecfmaster disc -i %MASTER_PATH%\testmaster.wumad -o %OUT_PATH%\testimage -w %WORK_DIR%

Notes

IMPORTANT:
Developer does not need to create full padded file. The HDD uploader and the R-disc writer tool support direct input of Master archive file.

Testing Master Images

CAT-DEV Hard Disk Based Emulation

The master image can be written to and executed from the built-in hard drive of the CAT-DEV system. The hard drive emulates the Cafe optical drive, allowing the application (and Cafe firmware) to exercise production-target code paths with the benefit of debug logging via the host bridge.

For information regarding this test procedure, see the Hard Disk Based Emulation reference.

Host PC Hard Disk Based Emulation

The master image can be executed from the host PC hard drive without uploading it to the CAT-DEV's hard disk. This approach is similar to the CAT-DEV hard disk based emulation, as it allows the emulation of the Cafe optical drive with the debug logging via the host bridge. The added benefit is saving the upload time of a master image to the CAT-DEV's hard disk every time it is remastered.

For information regarding this test procedure, see the Hard Disk Based Emulation reference.

CAT-R Development System

Running from an actual optical disc is the most complete test of a (disc-based) application. A special development system - equipped with an optical drive - and a separate optical disc burner are available from Nintendo. Contact your local Nintendo developer support group for more information.

For information on burning and executing an optical disc application, see Running on CAT-R.

Submitting Master Images

See 'Wii U Master ROM Creation and Submission Procedures'.

About SDK Versions and Remastering

IMPORTANT:
When downloading an updated version of a title that was updated via a remaster, normally only the data that was updated in the remaster is downloaded to the user. However, when you take a title that was originally mastered using Cafe SDK 2.10.12 or earlier, and then remaster it using SDK 2.11.07 or later, unchanged data will be also be downloaded due to system specs.

When remastering applications that have previously been released, or when remastering AOC (data titles), we recommend following the below SDK version guidelines to prevent unchanged data from being downloaded.

SDK version used prior to remastering SDK version to use during remastering
Version earlier than Cafe SDK 2.08.112.08.11 ~ 2.10.12
Cafe SDK 2.08.11 ~ 2.10.12SDK version used in prior mastering ~ 2.10.12
Cafe SDK 2.11.07 or laterSDK version used in prior mastering or later version

NOTE:
The above conditions do not affect patches, which are different from remasters.

See Also

Running an Application on CAT-DEV
Running an Application in Disc Emulation Mode
Hard Disk Based Emulation
Running on CAT-R
System Devices and File Systems
Installing Applications
Application Patch Overview

Revision History

2015/05/14 Removed description of omitting -r option.
2015/03/19 Formatted as 'NOTE'.
2014/08/27 Added description about SDK Versions and Remastering.
2014/07/08 Replaced makecfmaster.sh and CafeX commands with makecfmaster.exe commands. makecfmaster.sh and CafeX's mastering-related features are no longer supported.
2014/05/26 Added information about patch continuity.
2014/02/25 Added description about makecfmaster.exe.
2014/02/19 Replace refs to cafe_env.bat.
2013/09/17 Added a description of automatic push delivery.
2013/06/11 Added equivalent CafeX commands
2013/05/08 Automated cleanup pass.
2013/01/23 Updates for System Config Tool
2012/12/21 Added description about using host PC hard disk based image emulation.
2012/10/10 Added reference to Installing Applications and Application Patch Overview.
2012/10/04 Added description about creating patch master archive images.
2012/09/11 Added description about creating add-on content master archive images.
2012/04/19 Now R-disc writer supports master archive file, so app does not need to handle full padded image basically.
2012/04/11 Moved information of disc size to System Devices and File Systems.
2012/03/26 Removed description about application-specific ddf file.
2012/02/29 Added description about full master image file (.wum) and master archive file (.wumad). HDD based emulation uses master archive file from now on.
2011/03/28 Initial version.


CONFIDENTIAL