SRAM Load / Save Control Functions


Functions
void	ham_ResetRAM ()
	Reset / Clear the Save RAM.
u32	ham_InitRAM (u32 ram_type)
	Initialize the HAMlib Save RAM Load/Save system.
void	ham_SaveIntToRAM (char *ident_string, int the_number)
	Save an integer value into SRAM.
u32	ham_LoadIntFromRAM (char ident_string, int target_int)
	Load an integer value from SRAM.
void	ham_SaveRawToRAM (char ident_string, void data, u32 length_in_bytes)
	Save a raw block of data into SRAM.
u32	ham_LoadRawFromRAM (char ident_string, void target_data)
	Load any raw data previously stored from SRAM.

Detailed Description

This group of functions provides access to Saving data and reloading it later from a GBA cartridges internal SRAM, if present. Note that these functions will not work in MULTIBOOT mode, as there is no cartridge in this case.

HAM SaveRAM control is very easy. Every entity of information you want to save is identified via a so-called Identity String. This, user defined string is passed to the loading and saving functions and identifies the slot that is loaded and saved from/to. HAM stores these strings alongside the data in SaveRAM. This means, after initialization, you can use something like:

ham_SaveIntToRAM("My Highscore",my_highscore);

to store the integer value contained in my_highscore in SRAM, identified by the Identity string "My Highscore".

To later retrieve this data, use:

ham_LoadIntFromRAM("My Highscore",&my_highscore);

If you want to store other data in SaveRAM, you can use the RAW saving functions of HAMlib to store and Reload data:

ham_SaveRawToRAM("My Leveldata",&data_start,size_in_bytes); ham_LoadRawFromRAM("My Leveldata",&target_adress);

For more information, see the documentation of the individual functions.

To stabilize the SRAM loading and saving, critical functions will be copied into WRAM by the time of starting ham_InitSaveRAM(), and the Interrupt INT_TYPE_CART will be occupied by the HAMlib Save RAM system. Do not attempt to reset this interrupt by yourself before calling ham_DeInitSaveRAM() again. It will have no impact on your game code anyway. The only time this interrupt is called happens when a cartridge is removed. In this case, HAMlib will halt the program until the cartridge is inserted again and fully available.

Function Documentation

u32 ham_InitRAM ( u32 ram_type )

Initialize the HAMlib Save RAM Load/Save system.

Parameters:

ram_type In order to use the HAMlib Load and save support, you must call this function first. You will also need to specify one of three so-called RAM types, to let HAMlib know which kind of storage facility is desired:

RAM_TYPE_SRAM_256K Will provide 32 kBytes (256 kBit) of SRAM data storage if available in the ROM
RAM_TYPE_EEPROM_4K (support not yet available in HAMlib) Will provide 0.5 kBytes (4 kBit) of EEPROM data storage if available in the ROM
RAM_TYPE_EEPROM_64K (support not yet available in HAMlib) Will provide 8 kBytes (64 kBit) of EEPROM data storage if available in the ROM

As of HAM 2.7 , only SRAM is supported! Choosing EEPROM types will result in malfunction.
In SRAM mode, HAM will block the first 576 bytes for memory management purposes. the remaining 32192 bytes are free for use by your game. Every allocation will consume 64 byte for management overhead, so choose wisely what to store.
This function will return

1 if the RAM was loaded correctly, and HAM detected a correct HAM data block
0 if the RAM was left in a previously undefined state. HAM created a new data block and deleted all previous allocation assignments
Do NOT use the HAM Save RAM functions prior to calling this function, as it may result in data loss.
See also: ham_DeInitRAM() ham_ResetRAM() ham_LoadIntFromRAM() ham_SaveIntToRAM()

u32 ham_LoadIntFromRAM ( char * ident_string,

int * target_int

)

Load an integer value from SRAM.

Parameters:

ident_string Specify an identifier string for the integer to be retrieved. Maximum length should be 45 characters.

target_int A pointer to the integer you want to load the retrieved value into.

This function will load an integer previously stored with ham_SaveIntToRAM() from SRAM and store it's value in the integer pointer given in parameter \i target_int . In addition, this function returns the following values to indicate the loading status:

if the ident_string was found in SRAM, and the loading was fine, it will return the SRAM block number where the string is found (the block number corresponds to memory adress MEM_SRAM + 64*block_number ). This value is usually 0..511
if the ident_string was not found (SRAM corrupt or never saved before), the function will return 0xffffffff
Example: ham_LoadIntFromRAM("my highscore 1",&my_int);
See also: ham_InitRAM() ham_SaveIntToRAM()

u32 ham_LoadRawFromRAM ( char * ident_string,

void * target_data

)

Load any raw data previously stored from SRAM.

Parameters:

ident_string Specify an identifier string by which the data block was identified when saving.

target_data A pointer to the memory where the data is to be loaded into from SRAM.

This function will load raw data previously stored with ham_SaveRawToRAM() from SRAM and store it in the pointer location given in parameter \i target_data . In addition, this function returns the following values to indicate the loading status:

if the ident_string was found in SRAM, and the loading was fine, it will return the SRAM block number where the string was found (the block number corresponds to memory adress MEM_SRAM + 64*block_number ). This value is usually 0..511
if the ident_string was not found (SRAM corrupt or never saved before), the function will return 0xffffffff
See also: ham_InitRAM() ham_SaveRawToRAM()

void ham_ResetRAM ( )

Reset / Clear the Save RAM.

This function will clear all existing data entries in the HAM SaveRAM system. You can store new values right after calling this function. Make sure that you initialized the SaveRAM using ham_InitRAM() before calling this function.
See also: ham_LoadIntFromRAM() ham_SaveIntToRAM() ham_InitRAM()

void ham_SaveIntToRAM ( char * ident_string,

int the_number

)

Save an integer value into SRAM.

Parameters:

ident_string Specify an identifier string for the integer to be saved. Maximum length should be 45 characters.

the_number The number you want to save to SRAM

This function will store the number given in parameter \i the_number in the cartridges SRAM. It will be stored alongside with the identifier string, so you can then later query for this value by using ham_LoadIntFromRAM() .
Note that if the ident_string already exists, the current value for this ident_string will be overwritten with the new value passed.
Example: ham_SaveIntToRAM("my highscore 1",100400);
See also: ham_InitRAM() ham_LoadIntFromRAM()

void ham_SaveRawToRAM ( char * ident_string,

void * data,

u32 length_in_bytes

)

Save a raw block of data into SRAM.

Parameters:

ident_string Specify an identifier string by which the data block will be identified. Maximum length should be 45 characters.

data the pointer to the data you want to store

length_in_bytes the number of bytes you want to save beginning from \idata

This function will store the data at pointer location \i data in the cartridges SRAM. It will be stored alongside with the identifier string, so you can then later query for this data to retrieve it back by using ham_LoadRawFromRAM() .
Note that if the ident_string already exists, the current data for this ident_string will be overwritten with the new data passed. HAMlib will only create a new set of data if the ident_string differs.
See also: ham_InitRAM() ham_LoadRawFromRAM()

Documentation Homepage | HAMLib reference | Back to HAM Homepage

documentation created with Doxygen