Backup RAM Functions

Backup RAM Functions

bm_check

char bm_check(void); [ 1.5+ ]
Return whether the backup ram is available. 0 = false 1 = true

bm_free

int bm_free(void); [ 1.5+ ]
Return the number of free bytes available for user data. The amount required for the data header and the necessary 2-byte termination are alreadt deducted from this amount. The value returned is the number of bytes free for user data. Extended Documentation

bm_size

int bm_size(void); [ 3.03+ ]
Return the total number of bytes in backup memory. This should be 2KB on actual systems, but backup memory will work with a value as large as 8KB, in case some strange hardware exists out there.

bm_rawread

char bm_rawread(int ptr); [ 3.03+ ]
Similar to peek(), but handles accesses to BRAM. Automatically handles mapping of memory and addresing range (ie. address doesn't need to be in the range $8000-$A000)

bm_rawwrite

void bm_rawwrite(int offset, char val); [ 3.03+ ]
Similar to poke(), but handles accesses to BRAM. Automatically handles mapping of memory and addresing range (ie. address doesn't need to be in the range $8000-$A000)

bm_format

char bm_format(void); [ 1.5+ ]
Format the whole backup ram. Does not format if data is already formatted. Actually, data aren't erased but header data reports so. You should be able to find old data in the bram using raw reads in the backup ram bank but not through the usual HuC functions. Return backup ram status as defined in the huc.h file.

bm_exist

char bm_exist(char* name); [ 1.5+ / 3.03+ ]

Check whether a backup ram file exists. Note: The return value changed in version 3.03 . Before 3.03, it would return the bm_error code ( 0 is OK, != 0 is bad ), but this did not match the sense of the function name. From 3.03 forward, it returns TRUE (!= 0) if good; FALSE (0) if bad. The error type can be retrieved from bm_errno(). Note2: The name structure is not just an ASCII name; it begins with a 2-byte "uniqueness ID" which is almost always 00 00, followed by 10 bytes of ASCII name - which should be padded with trailing spaces.

bm_sizeof

int bm_sizeof(char* name); [ 3.03+ ]
Return size of user data for a BRAM file with a given name Extended Documentation

bm_getptr

int bm_getptr(int ptr, char* name); [ 3.03+ ]

Useful for browsing through the list of files in BRAM. Use 'BRAM_STARTPTR' for the first iteration, and it will return the name of this entry, and the next pointer in the list (to use for next iteration). When the return value is 0, there is no entry at the current location (ie. don't expect a name to be returned), and no subsequent entry. This one is easier to use than it sounds, so here's some sample code: char namebuf[13]; int nextptr; int line_cnt; namebuf[12] = 0; nextptr = BRAM_STARTPTR; line_cnt = 5; while (nextptr = bm_getptr(nextptr, namebuf) { put_string(&namebuf[2], 2, line_cnt); put_number(bm_sizeof(namebuf), 4, 15, line_cnt); line_cnt++; } Extended Documentation

bm_delete

void bm_delete(char* name); [ 3.03+ ]
Delete BRAM entry with a given name.

bm_write

char bm_write(char *buf, char *name, int offset, int nb); [ 1.5+ ]
Write into the file named 'name'. Data to write are in the buffer 'buf' and 'nb' bytes are written from offset 'offset' in the buffer. Return backup ram status as defined in the huc.h file.

bm_read

char bm_read(char *buf, char *name, int offset, int nb); [ 1.5+ ]
Read 'nb' bytes from file named 'name' and put them into 'buf'. I'm not sure whether the 'offset' is relative to the buffer or the file ... Return backup ram status as defined in the huc.h file.

bm_create

char bm_create(char *name, int size); [ 1.5+ ]
Create a new file names 'name' with a size of 'size' bytes. Return backup ram status as defined in the huc.h file.

bm_errno

char bm_errno(void); [ 1.5+ ]
Return backup ram status as defined in the huc.h file. The error (or success) is relative to the last backup ram operation.

Internal Backup RAM Functions

bm_open

void bm_open(char *name); [ 1.5+ ]
Obtain access to a named file.

bm_enable

void bm_enable(void); [ 1.5+ ]
Enable the BRAM area and do a quick check.

bm_disable

void bm_disable(void); [ 1.5+ ]
Handles the fixup of BRAM segment/locking.

bm_unlock

void bm_unlock(void); [ 1.5+ ]
Handles only the map/unlock of the BRAM area.

bm_checksum

void bm_checksum(char *fcb); [ 1.5+ ]
internal function, not for direct use.

bm_setup_ptr

void bm_setup_ptr(char *fcb, char *buf, int offset, int nb); [ 1.5+ ]
internal function, not for direct use.