CARD API Introduction

Introduction

The Revolution supports GameCube Memory Cards (4 Mb, 16 Mb, and 64 Mb). This API has nearly the same specifications as the CARD API for the GameCube.

The CARD API provides file level access to these Memory Cards. A 4-Mb Memory Card can have up to 59 files. Larger capacity Memory Cards can hold up to 127 files. The file size must be a multiple of the Memory Card sector size obtained with the CARDGetSectorSize function. The file size is fixed at the time the file is created and does not change.

With the Revolution, Memory Cards can be used for loading data--for example, handing over game software data used by past GameCubes. For this reason, be sure to only use read related APIs in applications. Although write related APIs are also prepared for debugging, they should not be used in an application. (Contact Nintendo if write processing is required in the application.)

Note: The APIs that you cannot use in applications are described in the API Reference Manual.

Note: Be sure to use the flash memory built into the system to save Revolution programs.

Initialization

The CARDInit function must be called only once before using any other CARD API functions.

Detecting Memory Cards

The CARDProbeEx function checks whether a memory card (of any type) is inserted in the specified Memory Card slot.

Note: After a card is detected in a Memory Card Slot, it is recommended that the program should wait for the player's input response before proceeding to the next process (e.g., the CARDMount function).

Mounting and Unmounting

Before a Memory Card is accessed, the card must be mounted using the CARDMount or CARDMountAsync function. As a best practice, if the game program does not use the Memory Card, it should be unmounted. This best practice is to ensure that the Memory Card is removed safely from the Memory Card slot. The CARDUnmount function unmounts the Memory Card.

Note: Memory Cards must be probed before mounting.

Verifying and Repairing Memory Cards

The CARD API is carefully designed to maintain the consistency of the file system during normal processing; However, the file system may remain inconsistent because of a power supply problem or under unusual circumstances (for example, when the Memory Card is removed from the slot intentionally).

CARDCheck or CARDCheckAsync checks the consistency of the file system and repairs it if possible. Although these functions are unable to repair all data damage, one of them must be called just after mounting a Memory Card (regardless of whether the return value of the mount operation returned CARD_RESULT_READY or CARD_RESULT_BROKEN). The game program can call other CARD functions after the CARDCheck function completes processing.

Note: The CARDCheck and CARDCheckAsync functions only checks the consistency of the file system. These function can't verify the contents of each user file in the file system. Each game program is responsible for verifying the contents of a file. For example, if a power failure occurred while saving game data to a file, the data would be lost, but the file system may remain consistent.

Note: After mounting a Memory Card, the CARDCheck[Async] function must be used for verification.

Format Processing

The CARDFormat or CARDFormatAsync function can format a Memory Card for access. If the Memory Card is not formatted or the system blocks of a Memory Card are broken, the CARDMount function will return CARD_RESULT_BROKEN (the same way other functions do). In these cases, be sure to display an error message on the screen.

Note:For programs that perform write processing, if CARD_RESULT_BROKEN has been returned, be sure to reformat after checking game players on the screen.

Note: Memory Cards must be mounted before they can be formatted.

Text Character Sets

Memory Cards use one of two text character set encoding standards that depend on the type of console used for formatting. Japanese version consoles format Memory Cards to use the Japanese Shift-JIS text character set. Other versions of the console format Memory Cards to use the ANSI 8-bit text character set. The CARDGetEncoding function returns the text character set of the current Memory Card.

Note:For programs that perform write processes, if the text character set of the Memory Card and the system do not match, the CARDMount and CARDMountAsync functions return CARD_RESULT_ENCODING. In these cases, after the player reconfirms on screen, the Memory Card should be reformatted.

Synchronous and Asynchronous Functions

Several CARD API functions provide both synchronous and asynchronous access to the Memory Card. Synchronous functions block the current thread until the process is completed and control is transfered to other executable threads. In contrast, asynchronous functions return immediately and call the specified callback when the process is completed. Asynchronous functions have the suffix Async (as shown in the table below).

Note: While accessing the Memory Card using the functions in the above table, specific errors that can occur related to missing data (for example, the Memory Card is removed from the system) must be displayed on screen until the function completes its task.

Note: A call to an asynchronous function returns CARD_RESULT_READY if the specified process has been initiated sucessfully. Otherwise, the function returns an error code and the specified callback function is not called.

Note: If there are no corresponding asynchronous functions, the API completes immediately after the call. (for example, CARDOpen, CARDClose, etc. functions).

Note: Unlike the Optical Disc (DVD) API, the CARD API can issue only one process at a time per Memory Card slot (for example, while the process of a synchronous/asynchronous function is in progress, a call to another CARD API function simply returns CARD_RESULT_BUSY). A game program should wait for the previous CARD function to complete processing before invoking the next one. The CARDProbeEx, CARDProbe, and CARDGetXferredBytes functions are exceptions and can be called while the current memory card process is in progress.

Polling Access

Instead of using a callback function with an asynchronous function, you can specify a NULL function as a callback and inspect the process completion by repeatedly calling CARDGetResultCode function. This function returns CARD_RESULT_BUSY until the process completes.

Even while a memory card read/write process is in progress, you can check the total number of read/write bytes by calling the CARDGetXferredBytes function. The CARDGetXferredBytes() function can be used to implement a progress bar, etc. to show on screen while data saves.

Memory Card Life Span

Each Memory Card has a life span like any type of flash memory device. If a CARD API function returns CARD_RESULT_IOERROR, the Memory Card may have reached the end of its life span. Alternatively, the Memory Card connector may be dirty. For this case, cleaning the connector may help.

Note: Once the CARD_RESULT_IOERROR error is returned, the current Memory Card must be unmounted. Do not retry the CARD function that returned the CARD_RESULT_IOERROR error. Otherwise, an unexpected error may occur. Because the CARD API returns the CARD_RESULT_IOERROR error after several internal retries, there is no doubt that the Memory Card that generated this error is defective.

Directory

The CARD API does not support hierarchical directories. Only 127 flat file entries are supported. Call the CARDGetStatus function to check each file entry by specifying the file entry number (from 0 to 126). Files can be opened/deleted by specifying either a file entry number or a file name. Functions that take a file entry number have the prefix CARDFast (for example, the CARDFastOpen and CARDFastDelete functions).

The CARDCreate and CARDCreateAsync functions create new files.

The CARDDelete, CARDDeleteAsync, CARDFastDelete, and CARDFastDeleteAsync functions delete files.

The CARDRename and CARDRenameAsync functions rename an existing file.

File Attributes

Each file can set the following file attributes.

By default, only the CARD_ATTR_PUBLIC bit is set to a Memory Card file created by the CARDCreate or CARDCreateAsync functions. The CARD_ATTR_PUBLIC must not be cleared by a game program.

A game program can set a CARD_ATTR_NO_COPY bit and/or CARD_ATTR_NO_MOVE bit if required.A game program must not modify any other bits.

CARD_ATTR_GLOBAL is set to a file created by a utility program (for example, network setup program) that all games share.

Note:CARD_ATTR_GLOBAL is a reserved bit: cardedit.elf will display error messages.

Note:Both gameName and company are zero in the file with the CARD_ATTR_GLOBAL bit enabled: cardedit.elf will not display game code (gameName) and company code (company) for the file.

The CARDGetAttributes function gets the file attributes.
The CARDSetAttributes and CARDSetAttributesAsync functions set file attributes.

Filename Space for Each Game

Each game has its own seperate filename space on a Memory Card. Each filename space is stored in the boot block of a Game Disc and separated by gameName and company. A game program can make a file name identical to files created by other games.

Note: A game program can't write or delete files that are not in its own filename space.

Read/Write

Before performing read/write processes, the file must be opened with the CARDOpen or CARDFastOpen function (the CARDCreate and CARDCreateAsync function open newly created file). The CARDOpen function can open only the current game files because of the filename space for each game. The CARDFastOpen function can also open other game files that have the CARD_ATTR_PUBLIC attribute.

Note: When using the CARDFastOpen function, the game program should check the gameName, company, and fileName members of the CARDStat structure using the CARDGetStatus.

The CARDRead and CARDReadAsync functions read data from the file. CARDWrite and CARDWriteAsync functions write data to the file. The read process to a file must be performed in multiples of CARD_READ_SIZE (512 bytes). The write process to a file must be performed in multiples of the card sector size that the CARDGetSectorSize function returns. The main memory data buffer to read/write data must be on a 32-byte boundary.

The current read/write process can be canceled using the CARDCancel function.

Files should be closed using the CARDClose function before unmounting the Memory Card.

Note: Memory Cards must be mounted before read/write to files.

Note: Memory Card files must be opened before read/write.

Memory Card 1019 Fast Mode

Memory Card 1019 meets the needs of games that must save a large volume of data. Using fast mode reduces the wait time during large file saves; Memory Card 1019 has fast mode which saves files much faster than Memory Card 59 and Memory Card 251.
For backward compatibility, because potential programming errors related to latent timing may surface, the high speed mode is disabled by default. To enable fast mode, call CARDSetFastMode(TRUE before mounting a Memory Card. Use the CARDGetFastMode function to retrive the current operation mode. To check the current mode of a Memory Card inserted in a Memory Card slot, call the CARDGetCurrentMode function.
Note that fast mode doesn't do anything for Memory Card 59 and Memory Card 251.

Error Code List

Appendix: Memory Card Size and Sector Size

Although the CARD API supports 4, 8, 16, 32, 64, and 128 Mb Memory Cards and 8, 16, 32, 64, 128, and 256 KB sector sizes, only Memory Cards with 8 KB sectors are sold. The Memory Card size and sector size can be checked at runtime by calling the CARDGetMemSize and CARDGetSectorSize functions, respectively. All game programs must support Memory Cards that have a sector size of 8 KB.

Note: Nintendo officially discourages the current development of game programs that support Memory Cards that are not 8 KB sector memory cards. A game program should call the CARDProbeEx or CARDGetSectorSize function to verify whether the Memory Card is an 8 KB sector Memory Card before proceeding. [as of 5/30/2001]

Appendix: Icons, Banners, and Comments

The Revolution system menu includes a Memory Card screen that displays memory card files. Please refer to the Icons and Banners page for more details about creating icons, banners, and comments.

Revision History

03/01/2006 Initial version.