SAVE Programming Guide

This topic describes specifications and performance tips when using the SAVE library.

SAVE Library Initialization Timing

To start applications quickly, delay your call to SAVEInit as long as you can.

Initializing the SAVE library depends heavily on the file system. Calling SaveInit may decrease the speed of important read requests, or block other processes from executing until the necessary storage device is mounted and becomes available.

Nintendo recommends calling SAVEInit after the startup screen of the game application has been displayed for the user. The same is true for SAVEInitSaveDir.

Updating Save Data

When updating save data, you can generally achieve maximum performance by performing the following procedure.

  1. Update save data files and directories.
    • If updating all files:
      • First delete the files, and then recreate files that have the same names.
      • Recreating the files as new files helps avoid file fragmentation.
    • If updating only some files:
      • If the size of the update is small, you may expect good performance by overwriting the files.
      • It is recommended that you keep this practice to a minimum because frequent file updates can result in file fragmentation.
      • When using a USB hard disk drive, file fragmentation has a negative effect on file access.
  2. After all save data is completely updated, call SAVEFlushQuota just once.

User Buffer for Save Data Files

512-byte Alignment

Align the user buffer used to store data at 512-byte boundaries to allow save data to be read and written at high speed.
If the user buffer is not aligned at 512-byte boundaries, depending on hardware specifications, data may need to be realigned when copied to buffers inside the library. This realignment of data reduces access speed.

Allocate Storage Space Equal to the Maximum File Size Ahead of Time

If you allocate storage equal to the maximum file size ahead of time to create a file, appending files later is faster. If you do not allocate storage ahead of time, new storage is allocated each time you write new data to the file. This results in file fragmentation. If you already know the size of a file, you can avoid fragmentation by allocating a large amount of storage ahead of time.
To allocate storage ahead of time based on file size, use FSAppendFile.

Fragmentation may occur if you update a file by overwriting it instead of appending to it.

Archiving Multiple Small Files

To load files quickly, you can create one large file out of many small ones and load them all at the same time.
The transfer rate of a small file is slower than the transfer rate of a large file. Transferring each file separately takes more time. You can reduce this type of overhead by merging the small files into one large file in cases where you are going to simultaneously access many small files.

Flushing the Save Directory Quota

The Wii U file system, used to store save data, supports a journaling feature that enables data to be updated safely.

All update operations on save data, including deletions, accumulate as journaling information. Calling SAVEFlushQuota automatically flushes all updates accumulated up to that point, enabling that updated data. All save data accumulated for update is lost if a game application exits (including termination on an error) or if power goes off unexpectedly before calling the SAVEFlushQuota function. When this happens, data is automatically rolled back to its state the last time the SAVEFlushQuota function was called. The state of save data when a game application starts always matches its state the last time SAVEFlushQuota was called. A game application cannot be started in the middle of updating save data.

The time required for the SAVEFlushQuota function to execute depends on the number of updates that have accumulated. About one second of overhead is required even if there is no data to update. Keep the number of flush calls to a minimum to optimize the time needed to update save data. Nintendo recommends that you call this function only once after all updates are complete.

If you implement an automatic save-data save feature, leave a gap of at least one minute between calls to SAVEFlushQuota. Frequent calls to SAVEFlushQuota may shorten the lifetime of NAND hardware.

Determining Maximum Quota Size

You can access the save data of a game application by freely creating files and directories in the common save data directory or the save data directory for each account, as long as the data does not exceed the maximum quota size specified for each application.

To enable the journaling feature to make safe updates as described, deleted files and data in old files prior to update must all be maintained as a cache. This cache is maintained inside the save directory quota. This cache cannot be released until a game application calls SAVEFlushQuota. You can call SAVEFlushQuota to allocate empty storage space for journaling. Specify an amount of storage capable of storing all active save data and old data that may be cached as the maximum quota size for the save directory.

Because of these specifications, old data will continue to be saved in the cache upon each update if you repeatedly update the same file location without calling SAVEFlushQuota. To prevent the unnecessary consumption of save data storage, avoid operations that frequently update the same file location.

Game applications must set the maximum quota size based on the total size of all save data that may become active plus all old data that might need to be cached. This size can be difficult to determine during the development of a game. Use the following guidelines to determine the maximum quota size to use.

Save Metadata

Creation of the Save meta Directory and Save Data

The save meta directory is created whenever you create save data (that is, when you call SAVEInitSaveDir). When this function is called, metadata for the title is copied into the save meta directory with full awareness of any patches. Note that this directory is not created if the account_save_size, common_save_size, account_boss_size, and common_boss_size elements in meta.xml are all set to zero.

The following save metadata is placed in this save meta directory.

Save Metadata Updates

Save metadata is updated whenever a patch or remastered title is installed. Save metadata is updated according to the following rules by comparing the meta.xml file of the title with the meta.xml file saved in the save meta directory.

Retail products and development hardware use the following specifications based on these rules.

Retail Products

Before a new title is installed, the new meta.xml file is copied to the save meta directory. This avoids making unnecessary copies for retail products, because the contents of the meta.xml file for a title never differs between the same versions of a particular title. Even if an older and newer version of a title were installed side-by-side on the same console, the meta.xml file for the older title would never be used to overwrite the meta.xml file stored in the save meta directory.

Development Hardware

During development, you can apply partial changes in the meta.xml file of a title to the meta.xml file in the save meta directory by setting the title version in the title's meta.xml file greater than or equal to the title version in the saved meta.xml file. Note that if you roll back the version of a title, the content of the meta.xml file copied to the save meta directory is not rolled back. Be sure to delete the save directory when you roll back the version of a title. Also, if you make partial changes to the meta.xml file while the system is on, the previous meta.xml file occasionally remains cached, meaning that changes are not always correctly applied. If this happens, turn off the power to the development hardware, and then turn it back on.

Deleting Save Metadata

Save metadata is deleted whenever the save directory is deleted.

BOSS Storage

BOSS storage is created as part of your quota in the data area used for temporarily saving data to upload, saving management information using BOSS (SpotPass), and saving data downloaded by executing a task. Game applications can access this data using the BOSS API.

An application's BOSS storage region includes a common BOSS storage region and an individual BOSS storage region for each account. Although it is not possible to confirm this directly from the save data management screen, the common BOSS storage region is included in the common save data directory, and the individual BOSS storage region is included in the save data for each account. Consequently, the data in common BOSS storage is deleted if you delete the common save data, and similarly, the data in an account's BOSS storage is deleted if you delete the account's save data.

For more information, see the BOSS (SpotPass) Reference Manual.

Specifying the Quota Size of BOSS Storage

To specify the quota size of BOSS storage, use the Application Configuration Tool. Use the following general guidelines when deciding whether to use common BOSS storage or individual BOSS storage by account.

Use the Worksheet for Calculating BOSS Storage Size to calculate an appropriate maximum quota size for BOSS storage.

Notes About Using PCFS in Development

PCFS does not support journaling. You cannot use the automatic rollback feature mentioned previously when you emulate the save data feature on a PC.

You cannot implement restrictions on writing when using PCFS like you can with NAND. You can access locations other than the common save data directory and individual account save data directories. NAND treats such access as invalid and generates an error. Take care not to access areas that are not allowed.

Revision History

2013/05/08 Automated cleanup pass.
2013/03/06 Cleaned up content.
2012/05/07 Initial version.