tpak.h File Reference

Transfer Pak interface. More...

Go to the source code of this file.

Data Structures
struct	old_gbc_title
	"Old" Game Boy Color cartridge ROM header title structure. More...
struct	new_gbc_title
	"New" Game Boy Color cartridge ROM header title structure. More...
struct	gameboy_cartridge_header
	Game Boy cartridge ROM header structure. More...
union	gameboy_cartridge_header.__unnamed44__
	Union of possible structures for the game title bytes. More...

Macros
Transfer Pak error values
#define	TPAK_ERROR_INVALID_ARGUMENT   -1
	Transfer Pak error: Invalid argument.
#define	TPAK_ERROR_NO_TPAK   -2
	Transfer Pak error: No Transfer Pak.
#define	TPAK_ERROR_NO_CONTROLLER   -3
	Transfer Pak error: No controller.
#define	TPAK_ERROR_UNKNOWN_BEHAVIOUR   -4
	Transfer Pak error: Unknown behavior.
#define	TPAK_ERROR_NO_CARTRIDGE   -5
	Transfer Pak error: No cartridge.
#define	TPAK_ERROR_ADDRESS_OVERFLOW   -6
	Transfer Pak error: Address overflow.
Transfer Pak status bits
#define	TPAK_STATUS_READY   0x01
	Transfer Pak status bit 0: Ready.
#define	TPAK_STATUS_WAS_RESET   0x04
	Transfer Pak status bit 2: Reset status.
#define	TPAK_STATUS_IS_RESETTING   0x08
	Transfer Pak status bit 3: Reset detected.
#define	TPAK_STATUS_REMOVED   0x40
	Transfer Pak status bit 6: Cartridge removed.
#define	TPAK_STATUS_POWERED   0x80
	Transfer Pak status bit 7: Power status.

Enumerations
enum	gb_cart_type_t {   GB_ROM_ONLY = 0x00 , GB_MBC1 = 0x01 , GB_MBC1_RAM = 0x02 , GB_MBC1_RAM_BATTERY = 0x03 ,   GB_MBC2 = 0x05 , GB_MBC2_BATTERY = 0x06 , GB_ROM_RAM = 0x08 , GB_ROM_RAM_BATTERY = 0x09 ,   GB_MMM01 = 0x0B , GB_MMM01_RAM = 0x0C , GB_MMM01_RAM_BATTERY = 0x0D , GB_MBC3 = 0x11 ,   GB_MBC3_RAM = 0x12 , GB_MBC3_RAM_BATTERY = 0x13 , GB_MBC3_TIMER_BATTERY = 0x0F , GB_MBC3_TIMER_RAM_BATTERY = 0x10 ,   GB_MBC5 = 0x19 , GB_MBC5_RAM = 0x1A , GB_MBC5_RAM_BATTERY = 0x1B , GB_MBC5_RUMBLE = 0x1C ,   GB_MBC5_RUMBLE_RAM = 0x1D , GB_MBC5_RUMBLE_RAM_BATTERY = 0x1E , GB_MBC6 = 0x20 , GB_MBC7_SENSOR_RUMBLE_RAM_BATTERY = 0x22 ,   GB_POCKET_CAMERA = 0xFC , GB_BANDAI_TAMA5 = 0xFD , GB_HUC3 = 0xFE , GB_HUC1_RAM_BATTERY = 0xFF }
	Game Boy cartridge types. More...
enum	gb_cart_rom_size_t {   GB_ROM_32KB = 0x00 , GB_ROM_64KB = 0x01 , GB_ROM_128KB = 0x02 , GB_ROM_256KB = 0x03 ,   GB_ROM_512KB = 0x04 , GB_ROM_1MB = 0x05 , GB_ROM_2MB = 0x06 , GB_ROM_4MB = 0x07 ,   GB_ROM_8MB = 0x08 , GB_ROM_1152KB = 0x52 , GB_ROM_1280KB = 0x53 , GB_ROM_1536KB = 0x54 }
	Game Boy cartridge ROM size types. More...
enum	gb_cart_ram_size_t {   GB_RAM_NONE = 0x00 , GB_RAM_2KB = 0x01 , GB_RAM_8KB = 0x02 , GB_RAM_32KB = 0x03 ,   GB_RAM_64KB = 0x05 , GB_RAM_128KB = 0x04 }
	Game Boy cartridge RAM size types. More...
enum	gbc_support_type { GBC_NOT_SUPPORTED = 0x00 , GBC_DMG_SUPPORTED = 0x80 , GBC_ONLY_SUPPORTED = 0xC0 }
	Game Boy Color cartridge compatibility values. More...
enum	sgb_support_type { SGB_NOT_ENHANCED = 0x00 , SGB_ENHANCED = 0x03 }
	Super Game Boy cartridge compatibility values. More...

Functions
int	tpak_init (int controller)
	Prepare a Transfer Pak for read/write commands.
int	tpak_set_value (int controller, uint16_t address, uint8_t value)
	Set Transfer Pak or Game Boy cartridge status/control value.
int	tpak_set_bank (int controller, int bank)
	Set the cartridge data address memory bank for a Transfer Pak.
int	tpak_set_power (int controller, bool power_state)
	Set the power enabled flag for a Transfer Pak.
int	tpak_set_access (int controller, bool access_state)
	Set the access mode flag for a Transfer Pak.
uint8_t	tpak_get_status (int controller)
	Get the status flags for a Transfer Pak.
int	tpak_get_cartridge_header (int controller, struct gameboy_cartridge_header *header)
	Read the Game Boy cartridge ROM header from a Transfer Pak.
bool	tpak_check_header (struct gameboy_cartridge_header *header)
	Verify a Game Boy cartridge ROM header checksum.
int	tpak_write (int controller, uint16_t address, uint8_t *data, uint16_t size)
	Write data from a buffer to a Game Boy cartridge via Transfer Pak.
int	tpak_read (int controller, uint16_t address, uint8_t *buffer, uint16_t size)
	Read data from a Game Boy cartridge to a buffer via Transfer Pak.

Detailed Description

Transfer Pak interface.

---

Data Structure Documentation

old_gbc_title

struct old_gbc_title

"Old" Game Boy Color cartridge ROM header title structure.

When the Game Boy Color was first introduced, games could use up to 15 characters for the title, and 1 byte to signal CGB compatibility.

Data Fields
uint8_t	title[15]	Game title in ASCII.
gbc_support_type	gbc_support	Game Boy Color support.

new_gbc_title

struct new_gbc_title

"New" Game Boy Color cartridge ROM header title structure.

Shortly after the Game Boy Color launched, games were limited to 11 characters for the title, 4 bytes for a manufacturer code, and 1 byte for CGB compatibility.

Data Fields
uint8_t	title[11]	Game title in ASCII.
uint8_t	manufacturer_code[4]	Manufacturer identifier.
gbc_support_type	gbc_support	Game Boy Color support.

gameboy_cartridge_header

struct gameboy_cartridge_header

Game Boy cartridge ROM header structure.

Data located at $0100-014F in each Game Boy cartridge ROM.

Data Fields
uint8_t	entry_point[4]	Z80 instructions to boot the main program.
uint8_t	logo[48]	Bitmap image data for the boot logo.
union gameboy_cartridge_header.__unnamed44__	__unnamed__	Union of possible structures for the game title bytes.
uint16_t	new_licensee_code	"New" publisher identifier.
sgb_support_type	is_sgb_supported	Super Game Boy support.
gb_cart_type_t	cartridge_type	Cartridge type.
gb_cart_rom_size_t	rom_size_code	ROM size identifier.
gb_cart_ram_size_t	ram_size_code	RAM size identifier.
uint8_t	destination_code	Japan-only identifier.
uint8_t	old_licensee_code	"Old" publisher identifier.
uint8_t	version_number	Version number of the game.
uint8_t	header_checksum	Checksum of cartridge ROM header.
uint16_t	global_checksum	Checksum of entire cartridge ROM.
uint8_t	overflow[16]	Padding.

gameboy_cartridge_header.__unnamed44__

union gameboy_cartridge_header.__unnamed44__

Union of possible structures for the game title bytes.

Data Fields
uint8_t	title[16]	Game title in ASCII.
struct old_gbc_title	old_title	"Old" Game Boy Color title structure.
struct new_gbc_title	new_title	"New" Game Boy Color title structure.

Macro Definition Documentation

TPAK_STATUS_READY

#define TPAK_STATUS_READY   0x01

Transfer Pak status bit 0: Ready.

Also referred to as the "Access Mode" flag. If not set, Transfer Pak cartridge reads/writes will fail.

TPAK_STATUS_WAS_RESET

#define TPAK_STATUS_WAS_RESET   0x04

Transfer Pak status bit 2: Reset status.

If set, the Game Boy cartridge is in the process of booting or resetting.

TPAK_STATUS_IS_RESETTING

#define TPAK_STATUS_IS_RESETTING   0x08

Transfer Pak status bit 3: Reset detected.

If set, the Game Boy cartridge has been reset since the last status read.

TPAK_STATUS_REMOVED

#define TPAK_STATUS_REMOVED   0x40

Transfer Pak status bit 6: Cartridge removed.

If set, there is no Game Boy cartridge in the Transfer Pak.

TPAK_STATUS_POWERED

#define TPAK_STATUS_POWERED   0x80

Transfer Pak status bit 7: Power status.

If set, the Transfer Pak has enabled power to the Game Boy cartridge.

Enumeration Type Documentation

gb_cart_type_t

enum gb_cart_type_t

Game Boy cartridge types.

Describes the Memory Bank Controller and other hardware on the cartridge.

Enumerator
GB_ROM_ONLY	ROM only (32 KiB ROM)
GB_MBC1	MBC1 (max 2 MiB ROM)
GB_MBC1_RAM	MBC1 (max 2 MiB ROM) + RAM (32 KiB)
GB_MBC1_RAM_BATTERY	MBC1 (max 2 MiB ROM) + RAM (32 KiB) + Battery.
GB_MBC2	MBC2 (max 256 KiB ROM; 512x4 bits RAM built-in)
GB_MBC2_BATTERY	MBC2 (max 256 KiB ROM; 512x4 bits RAM built-in) + Battery.
GB_ROM_RAM	ROM (32 KiB) + RAM (max 8 KiB)
GB_ROM_RAM_BATTERY	ROM (32 KiB) + RAM (max 8 KiB) + Battery.
GB_MMM01	MMM01 ("Meta-mapper")
GB_MMM01_RAM	MMM01 ("Meta-mapper") + RAM.
GB_MMM01_RAM_BATTERY	MMM01 ("Meta-mapper") + RAM + Battery.
GB_MBC3	MBC3 (max 2 MiB ROM)
GB_MBC3_RAM	MBC3 (max 2 MiB ROM) + RAM (64 KiB)
GB_MBC3_RAM_BATTERY	MBC3 (max 2 MiB ROM) + RAM (64 KiB) + Battery.
GB_MBC3_TIMER_BATTERY	MBC3 (max 2 MiB ROM) + Real-Time Clock + Battery.
GB_MBC3_TIMER_RAM_BATTERY	MBC3 (max 2 MiB ROM) + Real-Time Clock + RAM (64 KiB) + Battery.
GB_MBC5	MBC5 (max 8 MiB ROM)
GB_MBC5_RAM	MBC5 (max 8 MiB ROM) + RAM (128 KiB)
GB_MBC5_RAM_BATTERY	MBC5 (max 8 MiB ROM) + RAM (128 KiB) + Battery.
GB_MBC5_RUMBLE	MBC5 (max 8 MiB ROM) + Rumble.
GB_MBC5_RUMBLE_RAM	MBC5 (max 8 MiB ROM) + Rumble + RAM (128 KiB)
GB_MBC5_RUMBLE_RAM_BATTERY	MBC5 (max 8 MiB ROM) + Rumble + RAM (128 KiB) + Battery.
GB_MBC6	MBC6.
GB_MBC7_SENSOR_RUMBLE_RAM_BATTERY	MBC7 + Tilt Sensor + Rumble + RAM + Battery.
GB_POCKET_CAMERA	Game Boy Camera.
GB_BANDAI_TAMA5	Bandai TAMA5.
GB_HUC3	Hudson HuC3.
GB_HUC1_RAM_BATTERY	Hudson HuC1 + RAM + Battery.

gb_cart_rom_size_t

enum gb_cart_rom_size_t

Game Boy cartridge ROM size types.

Describes how many ROM banks are available on the cartridge.

Enumerator
GB_ROM_32KB	ROM size: 32 KiB (no banks)
GB_ROM_64KB	ROM size: 64 KiB (4 banks)
GB_ROM_128KB	ROM size: 128 KiB (8 banks)
GB_ROM_256KB	ROM size: 256 KiB (16 banks)
GB_ROM_512KB	ROM size: 512 KiB (32 banks)
GB_ROM_1MB	ROM size: 1 MiB (64 banks)
GB_ROM_2MB	ROM size: 2 MiB (128 banks)
GB_ROM_4MB	ROM size: 4 MiB (256 banks)
GB_ROM_8MB	ROM size: 8 MiB (512 banks)
GB_ROM_1152KB	ROM size: 1.125 MiB (72 banks)
GB_ROM_1280KB	ROM size: 1.25 MiB (80 banks)
GB_ROM_1536KB	ROM size: 1.5 MiB (96 banks)

gb_cart_ram_size_t

enum gb_cart_ram_size_t

Game Boy cartridge RAM size types.

Describes how much SRAM is available on the cartridge.

Enumerator
GB_RAM_NONE	RAM not available.
GB_RAM_2KB	RAM size: 2 KiB (no banks)
GB_RAM_8KB	RAM size: 8 KiB (no banks)
GB_RAM_32KB	RAM size: 32 KiB (4 banks)
GB_RAM_64KB	RAM size: 64 KiB (8 banks)
GB_RAM_128KB	RAM size: 128 KiB (16 banks)

gbc_support_type

enum gbc_support_type

Game Boy Color cartridge compatibility values.

Found in the cartridge ROM header; describes whether the game should boot into CGB mode or monochrome "Non CGB" compatibility mode.

Enumerator
GBC_NOT_SUPPORTED	Game Boy Color not supported. Cartridge has no special support for Game Boy Color and will run in original Game Boy mode. This is typically a grey Game Boy Game Pak with a notch in the corner.
GBC_DMG_SUPPORTED	Game Boy Color enhanced. Cartridge has special support for Game Boy Color, but still works on original Game Boy. This is typically a black Game Boy Game Pak with a notch in the corner.
GBC_ONLY_SUPPORTED	Game Boy Color required. Cartridge has special support for Game Boy Color and does not work on original Game Boy. This is typically a black Game Boy Game Pak that does not have a notch in the corner, which physically prevents it from being played on original Game Boy.

sgb_support_type

enum sgb_support_type

Super Game Boy cartridge compatibility values.

Found in the cartridge ROM header; describes whether the game has special enhancements for the Super Game Boy.

Enumerator
SGB_NOT_ENHANCED	Not enhanced for Super Game Boy.
SGB_ENHANCED	Enhanced for Super Game Boy.

Function Documentation

tpak_init()

int tpak_init

(

int

controller

)

Prepare a Transfer Pak for read/write commands.

Powers on the Transfer Pak and enables access to the Game Boy cartridge. Also performs status checks to confirm the Transfer Pak can be accessed reliably.

Parameters

[in]

controller

The controller (0-3) with Transfer Pak connected.

Returns

0 if successful or TPAK_ERROR otherwise.

tpak_set_value()

int tpak_set_value	(	int	controller,
		uint16_t	address,
		uint8_t	value
	)

Set Transfer Pak or Game Boy cartridge status/control value.

This is an internal helper to set a Transfer Pak status or control setting. This function is not suitable for setting individual bytes in Save RAM!

Parameters

[in]	controller	The controller (0-3) with Transfer Pak connected.
[in]	address	Address of the setting. Should be between 0x8000 and 0xBFE0
[in]	value	A byte of data to fill the write buffer with.

tpak_set_bank()

int tpak_set_bank	(	int	controller,
		int	bank
	)

Set the cartridge data address memory bank for a Transfer Pak.

Change the bank of address space that is available for tpak_read and tpak_write between Transfer Pak addresses 0xC000 and 0xFFFF.

Parameters

[in]	controller	The controller (0-3) with Transfer Pak connected.
[in]	bank	The bank (0-3) to switch to.

Returns

0 if successful or TPAK_ERROR otherwise.

tpak_set_power()

int tpak_set_power	(	int	controller,
		bool	power_state
	)

Set the power enabled flag for a Transfer Pak.

Parameters

[in]	controller	The controller (0-3) with Transfer Pak connected.
[in]	power_state	True to power the Transfer Pak and cartridge on, false to turn it off.

Returns

0 if successful or TPAK_ERROR otherwise.

tpak_set_access()

int tpak_set_access	(	int	controller,
		bool	access_state
	)

Set the access mode flag for a Transfer Pak.

Parameters

[in]	controller	The controller (0-3) with Transfer Pak connected.
[in]	access_state	Whether to allow access to the Game Boy cartridge.

Returns

0 if successful or TPAK_ERROR otherwise.

tpak_get_status()

uint8_t tpak_get_status

(

int

controller

)

Get the status flags for a Transfer Pak.

Parameters

[in]

controller

The controller (0-3) with Transfer Pak connected.

Returns

The status byte with TPAK_STATUS flags

tpak_get_cartridge_header()

int tpak_get_cartridge_header	(	int	controller,
		struct gameboy_cartridge_header *	header
	)

Read the Game Boy cartridge ROM header from a Transfer Pak.

Parameters

[in]	controller	The controller (0-3) with Transfer Pak connected.
[out]	header	Pointer to destination Game Boy cartridge ROM header data structure.

Returns

0 if successful or TPAK_ERROR otherwise.

tpak_check_header()

bool tpak_check_header

(

struct gameboy_cartridge_header *

header

)

Verify a Game Boy cartridge ROM header checksum.

Confirms that the Transfer Pak is connected and working properly.

Parameters

[in]

header

The Game Boy ROM header to check.

tpak_write()

int tpak_write	(	int	controller,
		uint16_t	address,
		uint8_t *	data,
		uint16_t	size
	)

Write data from a buffer to a Game Boy cartridge via Transfer Pak.

Save RAM is located between gameboy addresses 0xA000 and 0xBFFF, which is in the Transfer Pak's bank 2. This function does not account for cartridge bank switching, so to switch between MBC1 RAM banks, for example, you'll need to switch to Tpak bank 1, and write to address 0xE000, which translates to address 0x6000 on the gameboy.

Parameters

[in]	controller	The controller (0-3) with Transfer Pak connected.
[in]	address	address in Game Boy cartridge space to write to.
[in]	data	buffer containing the data to write.
[in]	size	length of the buffer.

Returns

0 if successful or TPAK_ERROR otherwise.

tpak_read()

int tpak_read	(	int	controller,
		uint16_t	address,
		uint8_t *	buffer,
		uint16_t	size
	)

Read data from a Game Boy cartridge to a buffer via Transfer Pak.

Parameters

[in]	controller	The controller (0-3) with Transfer Pak connected.
[in]	address	address in Game Boy cartridge space to read from.
[in]	buffer	buffer to copy cartridge data into.
[in]	size	length of the data to be read.

Returns

0 if successful or TPAK_ERROR otherwise.