Creating an Application Patch

Introduction

This topic describes the procedure for developing a patch. For the patch overview and what can be performed with a patch, see "Wii U Overview: Patch".

The figure below covers everything from submitting the initial version of a title, the submission of a title that will be sold as both a disc and a downloadable application until the submission of the second patch.

Figure 1: Patch Build Sequence

Patch Development

Editing the File Tree

When you create the modified application, first edit the existing file tree, and test it on the PC in the emulation environment. You do not need to distinguish whether the files have actually changed.

When debugging in an environment closer to the production environment, create a test ROM for this purpose.

Creating the Patch

After you have finished with your modifications, create and debug the actual patch. Use the -p option with makecfmaster.exe to create the patch.

For information on makecfmaster, see Mastering Overview. This tool creates the patch from the following information.

makecfmaster automatically finds the updated files and creates the patch.

WARNING:
A patch must be created from the last released ROM or patch. If not, you will not be able to establish appropriate data differences.

To test, see Debug the Patch.

Patch Versioning

For Wii U versioning, every time a title is released with a patch to the market, the remaster version should be incremented. The remaster version of the initial disc is 0; the first patch submission should be 1. From thereafter, increment the version to 2, 3, and so forth. In case of resubmission, because the remaster version of a patch has not been released to the market, it is not necessary to increment the version.

Separate from this version value, you may create an application-specific version to display to users. In this case, the version number may be different from the remaster version of a patch.

Versioning described so far and how it appears to users are organized in the table below:

Submission Remaster Version Version Display Example Remarks
(Initial Disc Submission) 0 1.0
First Patch Submission 1 1.1
First Patch Resubmission 1 1.1 If the first submission is NG, the remaster version will not change.
Second Patch Submission 2 1.1.1 Depending on the modifications, it is acceptable to add a micro version to display.
Third Patch Submission 3 2.0

File System Performance during Patching

An application patch does not contain all data for the application; only updated files and directories should be included as entities. For this reason, when accessing data of a patched application, the file system first checks if a file/directory you wish to access is included in the patch. If not, it will try to access the source ROM data.

Due to this design, when an application patch is applied, the time it takes to open a file/directory may be slowed down by the time it takes to verify whether an entity exists in the patch. For your information, application patch performance measurements taken by Nintendo are shown below.

Summary of Measurement Method

The time it took to open/close an application file for testing was measured. First, measurement was taken before applying a patch; then, another measurement was taken after applying a patch. The file/directory to open after patching had no entity in the patch; the time shown here was how long it took to access the source ROM data.

Experiment Parameters

Used SDK Cafe SDK 2.08.02
Media with a Patch System NAND Memory
Media with Source ROM Data Optical Disc, System NAND Memory, PC
Measurement Object File and Directory with no Entity in the Patch
Comparison Object Same File and Directory before Applying a Patch
What is Measured Total time it takes to open and close a file and directory respectively
Directory Structure1
  • When multiple files/directories are present in 1 directory (Expected Value)
  • When 1 file/directory is present in 1 directory (Worst Value)

1 Because the data directory structure influences the average time it takes to open, measurements were taken by using a directory structure that would decrease performance as well as general directory structure.

The time it takes to open a file/directory when its entity is present in the patch is not measured; however, if the patch is located in the system NAND, the value should be the same as pre-patching when the application is located in the system NAND.

Measurement Results

File Open/Close

Original Application Media Expected Value [usec] Worst Value [usec]
Before Applying a Patch After Applying a Patch Before Applying a Patch After Applying a Patch
Optical Disc (ATFS) 633.19 1608.03 661.524410.24
System NAND (WFS)1124.03 1741.95 2481.55 4756.57
PC (PCFS)7184.91 7923.157152.15 9470.35

Directory Open/Close

Original Application Media Expected Value [usec] Worst Value [usec]
Before Applying a Patch After Applying a Patch Before Applying a Patch After Applying a Patch
Optical Disc (ATFS) 592.26 1366.15 626.37 1375.85
System NAND (WFS) 955.441390.34 2252.663084.59
PC (PCFS)7181.29 7997.737176.66 7939.67

Limitations and Cautions

This section describes precautions and restrictions associated with patch development. Also, see "Wii U Overview: Patch" as it contains information on other areas that require attention during patch planning and/or reviewing.

What Can be Patched

Wii U patches cannot be used to modify only part of a file. When modifying an extremely large file, include the entire file in your patch.

TitleID

Set the same TitleID which is displayed by the Application Config Tool as the initial version. In particular, do not change the Unique ID, Variation, and Category from the initial version.

When creating the patch, makecfmaster automatically changes the Title ID for patch. So be careful that the Title ID which is displayed on the System Config Tool is different with the initial Title ID. For example, when the initial Title ID is 0005000011000000, the patch's Title ID is set 0005000e11000000.

Debug the Patch

This section describes how to debug a patch.

Debug Environment/Settings

Use the same environment and settings as when the application was debugged to debug the patch. A patch should be installed from System Config Tool. The system guarantees downloading from the server, so it is not necessary to debug that area. The same goes for the version list.

Testing with a patch should be performed against the following combinations:

In terms of the system, the patch will never be applied to combinations other than the above.

How to Install a Patch

The WUMAD of a patch can be installed in the same way as that of a regular application from the System Config Tool.
However, when installing a patch from the System Config Tool via PCFS on the CAT-DEV to NAND or USB storage, restart the CAT-DEV once after installation completes.
Without restarting the CAT-DEV, the patch will not become effective.

Behavior Changes Caused by Patching

With and without patching, the following behavioral differences may be observed:

Data Compatibility Check

When creating a patch, the backward compatibility of various data (save data, data received via SpotPass, and add-on content) must be verified. While no patch (or an old patch) is applied, create such data; install the new patch on System Config Tool; then, verify if you can access various data.

After a patch is installed, you cannot boot in an unpatched state. To boot in an unpatched state, you must delete boot control data (Title Version Table) within the system. To delete the data, do the following:

  1. Run System Config Tool.
  2. Select "Other Setting" → "Initialize Title Version Table"

* You may also do it with a USB keyboard to enter and run the delete_ver_list command. In doing so, you should be able to boot in an unpatched state.

When executing delete_ver_list, unless relevant data is deleted at the same time, forward compatibility issues may occur. If there is no particular reason, it is recommended to delete various data at the same time.

Testing when the Account Server Provides Version Control

This section describes how to test when the account server provides version control. You only need to check whether rejection occurs during server token acquisition if the status is old and whether a service token can be obtained properly when a patch is applied.

Enabling version control by the account server, verify whether rejection occurs when you boot while no or an old patch is applied. Then, importing a new patch from System Config Tool, verify whether a service token can be obtained properly when you boot.

If it fails to obtain a service token, developers will not have to check version list synchronization themselves. The system takes care of this area along with patch downloading.

NOTE:
For information about version control by the account server, see "Wii U Network Error Simulation Manual".

See Also

Application Mastering Overview

Revision History

2014/07/08 Replaced makecfmaster.sh with makecfmaster.exe.
2013/05/08 Automated cleanup pass.
2013/01/23 Updates for System Config Tool
2012/11/28 Added how to install a patch.
2012/10/25 Added FS performance during Patching.
2012/10/09 Initial version.


CONFIDENTIAL