Backup RAM.

Description

The Tennokoe 2, IFU-30 and DUO systems provided an extra 2KB of battery powered back up memory.

The backup ram (BRAM for short) “file system” is organized as follows :

BRAM Header (16 bytes)

00-03	Header tag (equals to “HUBM”)
04-05	Pointer to the first byte after BRAM.
06-07	Pointer to the next available BRAM slot (first unused byte).
08-0f	Reserved (set to 0).

BRAM Entry Header

00-01	Entry size. This size includes the $10 bytes of the entry header.
02-03	Checksum. The checksum is the sum of the entry bytes starting from byte #4 (i.e all bytes except the entry size and checksum). The value stored is the opposite of the computed checksum. This way the consistency check only consists in adding the ssum the stored checksum and the newly computed one. If this sum is 0, the entry is valid.
04-0f	Entry name.

BRAM Entry name

00-01	Unique ID.
02-0b	ASCII name (padded with spaces).

BRAM Entry Data

Miscenalleous data which size is given in the BRAM Entry Header.

BRAM Entry Trailer (2 bytes)

This 2 bytes are set to zeroes. They are not part of the BRAM “used area”. It is used as a linked list terminator.

For CD-ROM programs, the following BRAM routines are provided from the System Card:

bm_format
bm_free
bm_read
bm_write
bm_delete
bm_files

Summary

Backup RAM.	The Tennokoe 2, IFU-30 and DUO systems provided an extra 2KB of battery powered back up memory.
Functions
bm_bind	Unlock and map BRAM to mpr #4.
bm_unbind	Lock BRAM and restore mpr #4.
bm_test	Test if data can safely be written to BRAM.
bm_check_header	Checks if the BRAM header is valid.
bm_detect	Detect if a BRAM is present on the system.
bm_size	Get the storage capacity in bytes of the backup RAM.
bm_format	Initialize backup memory.
bm_free	Returns the number of free bytes.
bm_checksum	Compute checksum.
bm_open	Finds the BRAM entry whose name is given as argument.
bm_adjust_pointer
bm_read	Read entry data.
bm_write	Update entry data.
bm_delete	Delete the specified entry.
bm_files	Get file by index and store the information in a buffer.
bm_getptr.2	Given a pointer to the BRAM, obtain the name of the entry and the pointer to the next entry.
bm_create	Create a new entry at the end of current storage.
bm_exists	Check if there is an entry which name matches the one given as parameter.

Functions

bm_bind

Unlock and map BRAM to mpr #4.

Warning

This routine switches the CPU to slow mode.

bm_unbind

Lock BRAM and restore mpr #4.

Warning

This routines switches the CPU to fast mode.

bm_test

Test if data can safely be written to BRAM.

Warning

bm_bind must have been previously called.

Return

The carry flag is cleared if the backup RAM storage is valid.

bm_check_header

Checks if the BRAM header is valid.

Warning

bm_bind must have been previously called.

Return

The carry flag is cleared and A is set to 0 if the header is valid. Otherwise the carry flag is set and A is set to $ff.

bm_detect

Detect if a BRAM is present on the system.

Return

The carry flag is set if an error occured and the value of bm_error is set as follow: 0 - BRAM is present and fully formated. 1 - BRAM is present but not formatted. 2 - no BRAM was found.

bm_size

Get the storage capacity in bytes of the backup RAM. Standard value is 2KB, but it can go up to 8KB.

Return

_cx	BRAM total storage size (in bytes).
bm_error	Error code.

Error value

$00	Success.
$ff	BRAM not formatted.

bm_format

Initialize backup memory. Set header info and and limit of BRAM to the maximum amount of memory available on this hardware.

bm_free

Returns the number of free bytes.

Returns

carry flag	1 upon success or 0 if an error occured.
_cx	Number of free bytes.
bm_error	Error code.

Error Value

$00	Success.
$ff	Error.

bm_checksum

Compute checksum. The checksum is the sum of all entry bytes except the first 4 ones (file size and checksum).

Parameters

_si	BRAM file entry pointer.

Return

_dx

checksum

bm_open

Finds the BRAM entry whose name is given as argument.

Parameters

_bx	pointer to the BRAM entry name.

Return

carry flag	1 upon success or 0 if an error occured.
bm_error	Error code.
_si	Pointer to the beginning of the first matching BRAM entry.
_dx	Pointer to the next BRAM entry.
_cx	Entry size.

Error code values

$01	File not found
$03	Directory is corrupted.
$04	Empty file
$ff	BRAM is not formatted

bm_adjust_pointer

Parameters

_si	pointer to BRAM entry.
_bp	offset (in bytes) in BRAM entry data.
_ax	number of byte to read from BRAM.

Return

The carry flag is cleared is the BRAM pointer was succesfully adjusted to point to the requested BRAM entry data area. It is set if the requested size is zero or if the requested area to read is out the entry bounds.

<_ax, <_cx	adjusted size
<_dx	entry pointer

bm_read

Read entry data.

Parameters

_di	pointer to the output buffer.
_bx	pointer to the BRAM entry name.
_bp	offset (in bytes) in BRAM entry data.
_ax	number of bytes to read from BRAM.

Return

_ax	number of bytes to read from BRAM.
_dx	entry pointer
bm_error	Error code.

Error values

$02	invalid checksum.

bm_write

Update entry data.

Warning

The entry will not be resized if the offset and size exceed the current entry area.

Parameters

_di	pointer to the input buffer.
_bx	pointer to the BRAM entry name.
_bp	offset (in bytes) in BRAM entry data.
_ax	number of bytes to write BRAM.

Return

bm_error

Error code.

Error values

$01	File not found
$03	Directory is corrupted.
$04	Empty file
$ff	BRAM is not formatted

bm_delete

Delete the specified entry.

Parameters

_bx	pointer to the BRAM entry name.

bm_files

Get file by index and store the information in a buffer.

Entry format

00-01	User ID.
02-0f	Entry name.
10-11	Entry size.

Parameters

_bx	Address to the buffer where the entry informations will be stored.
_al	File index (starts at 1).

Return

_si	Entry address
bm_error	Error code.

Error values

$00	Success.
$01	Cannot find file.
$ff	BRAM is not formatted.

bm_getptr.2

Given a pointer to the BRAM, obtain the name of the entry and the pointer to the next entry.

Set _bp to bm_entry for the first entry.

Parameters

_bp	Address of the current entry.
A	MSB of the destination address for the entry name.
X	LSB of the destination address for the entry name.

Return

A	MSB of the next entry address.
X	LSB of the next entry address.
_cx	Entry size.
bm_error	Error code.
carry flag	Set if an error occured.

Error values

$00	Success.
$01	Cannot find file. _bp is past the last entry.
$ff	BRAM is not formatted.

bm_create

Create a new entry at the end of current storage.

Parameters

_bx	pointer to the entry name.
_ax	entry size.

Return

bm_error	Error code.
carry flag	Set if an error occured.

Error values

$00	Success.
$01	Cannot find file. _bp is past the last entry.
$05	Not enough space for entry.
$ff	BRAM is not formatted.

bm_exists

Check if there is an entry which name matches the one given as parameter.

Parameters

_bx	pointer to the entry name.

Return

X	1 if a matching entry exists, 0 otherwise.
carry flag	Cleared if a matching entry exists.
bm_error	Error code.

Error values

$00	Success.
$01	Cannot find file. _bp is past the last entry.
$ff	BRAM is not formatted.