Mapper / bank switch methods. More...

#include "config.h"
#include "types.h"

Defines
#define	MAPPER_BASE 0xA130F1
#define	BANK_SIZE 0x80000
#define	BANK_IN_MASK (BANK_SIZE - 1)
#define	BANK_OUT_MASK (0xFFFFFFFF ^ BANK_IN_MASK)
#define	FAR(data) data
	Give access to specified 'far' data through SEGA official bank switch mechanism if needed.
#define	FAR_SAFE(data, size) data
Functions
u16	SYS_getBank (u16 regionIndex)
	Returns the current bank of specified region index.
void	SYS_setBank (u16 regionIndex, u16 bankIndex)
	Set the current bank of specified region index.
void *	SYS_getFarData (void *data)
	Make the given binary data ressource accessible and return a pointer to it.
void *	SYS_getFarDataEx (void *data, bool high)
	Make the given binary data ressource accessible and return a pointer to it.
bool	SYS_isCrossingBank (void *data, u32 size)
	Returns TRUE if given binary data is crossing 2 512 KB banks.
void *	SYS_getFarDataSafe (void *data, u32 size)
	Make the given binary data ressource accessible and return a pointer to it (safe version with possible bank crossing)
void *	SYS_getFarDataSafeEx (void *data, u32 size, bool high)
	Make the given binary data ressource accessible and return a pointer to it (safe version with possible bank crossing)

Detailed Description

Mapper / bank switch methods.

Author:: Stephane Dallongeville

Date:: 01/2020

This unit provides tools to deal with ROM larger than 4MB.
It allows to do classic bank switching using the official SEGA mapper but also provide methods to get easy access to "far" data.
Note that you can use the ENABLE_BANK_SWITCH flag in config.h file to enable automatic bank switch on binary data access.

SEGA official mapper description (taken from Segaretro.org):
The bankswitching mechanism is very simple. It views the addressable 4 mega-bytes of ROM as 8 512KB regions.
The first area, 0x000000-0x07FFFF is fixed and cannot be remapped because that is where the vector table resides.
The banking registers on the cartridge work by allocating the 512KB chunk to a given part of the addressable 4MB ROM space.
Below are the registers and what range they correspond to. The value written to a register will cause the specified 512KB page to be mapped to that region.
A page is specified with 6 bits (bits 7 and 6 are always 0) thus allowing a possible 64 pages = 32 MB (SSFII only has 10, though.)

0xA130F3: 0x080000 - 0x0FFFFF
0xA130F5: 0x100000 - 0x17FFFF
0xA130F7: 0x180000 - 0x1FFFFF
0xA130F9: 0x200000 - 0x27FFFF
0xA130FB: 0x280000 - 0x2FFFFF
0xA130FD: 0x300000 - 0x37FFFF
0xA130FF: 0x380000 - 0x3FFFFF

The registers are accessed through byte writes.
Examples:
If 0x01 is written to register 0xA130FF, 0x080000-0x0FFFFF is visible at 0x380000-0x3FFFFF.
If 0x08 is written to register 0xA130F9, the first 512KB of the normally invisible upper 1MB of ROM is now visible at 0x200000-0x27FFFF.

The registers simply represent address ranges in the 4MB ROM area and you can page in data to these ranges by specifying the bank #

Define Documentation

#define FAR ( data ) data

Give access to specified 'far' data through SEGA official bank switch mechanism if needed.

See also:: ENABLE_BANK_SWITCH flag in config.h file; SYS_getFarData(..); SYS_getFarDataSafe(..)

Function Documentation

u16 SYS_getBank ( u16 regionIndex )

Returns the current bank of specified region index.

Parameters:

regionIndex the 512KB region index we want to get. Accepted values: 1-7 as region 0 (0x000000-0x07FFFF) is fixed.

Returns:: the effective 512KB data bank index mapped on this region (0 to 63)

void* SYS_getFarData ( void * data )

Make the given binary data ressource accessible and return a pointer to it.

Parameters:

data	data we want to access.

This method will use bank switching to make the specified data accessible and return a valid pointer to it.
WARNING: this method use the 0x00300000-0x003FFFFF range (2 regions) to make the requested data accessible using bank switching mechanism.
If data bank is already accessible it re-uses the region otherwise it will change bank of one of the region so be careful of that if you want to access data from different data bank at same time

See also:: SYS_getFarDataEx; SYS_getFarDataSafe

void* SYS_getFarDataEx	(	void *	data,
		bool	high
	)

Make the given binary data ressource accessible and return a pointer to it.

Parameters:

data	far data we want to access.
high	if set to TRUE then we use the high remappable bank for the FAR acces otherwise we use the low one

This method will use bank switching to make the specified data accessible and return a valid pointer to it.
It will use the 0x00300000-0x0037FFFF or 0x00380000-0x003FFFFF region depending the value of high parameter.

See also:: SYS_getFarData; SYS_getFarDataSafe

void* SYS_getFarDataSafe	(	void *	data,
		u32	size
	)

Make the given binary data ressource accessible and return a pointer to it (safe version with possible bank crossing)

Parameters:

data	far data we want to access.
size	size (in byte) of the far data block we want to access. Note that size should be > 0, if you don't the size then use SYS_getFarData(..) method instead.

This method will use bank switching to make the specified data accessible and return a valid pointer to it.
WARNING: this method use the 0x00300000-0x003FFFFF range (2 regions) to make the requested data accessible using bank switching mechanism.
If data bank is already accessible it re-uses the region otherwise it will change bank of one of the region so be careful of that if you want to access data from different data bank at same time :p
The method checks if the data is crossing banks in which case it will set the 2 switchable/remappable regions to make the data fully accessible.

See also:: SYS_getFarDataSafeEx; SYS_getFarData

void* SYS_getFarDataSafeEx	(	void *	data,
		u32	size,
		bool	high
	)

Make the given binary data ressource accessible and return a pointer to it (safe version with possible bank crossing)

Parameters:

data	address of far data we want to access.
size	size (in byte) of the far data block we want to access. Note that size should be > 0, if you don't the size then use SYS_getFarData(..) method instead.
high	if set to TRUE then we use the high remappable bank for the FAR acces otherwise we use the low one

This method will use bank switching to make the specified data accessible and return a valid pointer to it.
It will use the 0x00300000-0x0037FFFF or 0x00380000-0x003FFFFF region depending the value of high parameter.
The method checks if the data is crossing banks in which case it will set the 2 switchable/remappable regions to make the data fully accessible.

See also:: SYS_getFarDataSafe

bool SYS_isCrossingBank	(	void *	data,
		u32	size
	)

Returns TRUE if given binary data is crossing 2 512 KB banks.

Parameters:

data	far data pointer
size	size (in byte) of the far data block

This method return TRUE is the given binary data block is crossing 2 512 KB banks

See also:: SYS_getFarDataSafe

void SYS_setBank	(	u16	regionIndex,
		u16	bankIndex
	)

Set the current bank of specified region index.

Parameters:

regionIndex	the 512KB region index we want to set. Accepted values: 1-7 as region 0 (0x000000-0x07FFFF) is fixed.
bankIndex	the effective 512KB data bank index mapped on this region. Accepted values: 0-63

Defines

Functions

Detailed Description

Define Documentation

Function Documentation