Module save 

Module for reading and writing to save media.

Save media types

There are, broadly speaking, three different kinds of save media that can be found in official Game Carts:

• Battery-Backed SRAM: The simplest kind of save media, which can be accessed like normal memory. You can have SRAM up to 32KiB, and while there exist a few variants this does not matter much for a game developer.
• EEPROM: A kind of save media based on very cheap chips and slow chips. These are accessed using a serial interface based on reading/writing bit streams into IO registers. This memory comes in 8KiB and 512 byte versions, which unfortunately cannot be distinguished at runtime.
• Flash: A kind of save media based on flash memory. Flash memory can be read like ordinary memory, but writing requires sending commands using multiple IO register spread across the address space. This memory comes in 64KiB and 128KiB variants, which can thankfully be distinguished using a chip ID.

As these various types of save media cannot be easily distinguished at runtime, the kind of media in use should be set manually.

Setting save media type

To use save media in your game, you must set which type to use. This is done by calling one of the following functions at startup:

• For 32 KiB battery-backed SRAM, call init_sram.
• For 64 KiB flash memory, call init_flash_64k.
• For 128 KiB flash memory, call init_flash_128k.
• For 512 byte EEPROM, call init_eeprom_512b.
• For 8 KiB EEPROM, call init_eeprom_8k.

Using save media

Each init_* method returns a SaveSlotManager which provides a high-level interface for managing multiple save slots with corruption detection and recovery.

Performance and Other Details

The performance characteristics of the media types are as follows:

• SRAM is simply a form of battery backed memory, and has no particular performance characteristics. Reads and writes at any alignment are efficient. Furthermore, no timer is needed for accesses to this type of media.
• Non-Atmel flash chips have a sector size of 4096 bytes. Reads and writes to any alignment are efficient, however, writes will erase all data in an entire sector before writing.
• Atmel flash chips have a sector size of 128 bytes. Reads to any alignment are efficient, however, unaligned writes are extremely slow.
• EEPROM has a sector size of 8 bytes. Unaligned reads and writes are slower than aligned writes, however, this is easily mitigated by the small sector size.

Structs

MediaInfo

Information about the save media used.

SaveManager

Allows access to the cartridge’s save data.

SaveSlotManager

Manages multiple save slots with corruption detection and recovery.

SerializationError

Further details about the serialization error.

Enums

MediaType

A list of save media types.

Slot

A save slot with its current state.

StorageError

The type used for errors encountered while reading or writing save media.

Type Aliases

SaveError

An error that can happen while saving or loading.