SuperFX (GSU) coprocessor library — registers, config, and API. More...

#include <snes/types.h>

Macros
#define	CLSR_10MHZ 0x00

#define	CLSR_21MHZ 0x01

#define	GSU_SRAM_BASE 0x700000

#define	REG_BRAMR ((volatile u8)0x3033)

#define	REG_CBR ((volatile u16)0x303E)

#define	REG_CLSR ((volatile u8)0x3039)

#define	REG_GSU_R0 ((volatile u16)0x3000)

#define	REG_GSU_R1 ((volatile u16)0x3002)

#define	REG_GSU_R10 ((volatile u16)0x3014)

#define	REG_GSU_R11 ((volatile u16)0x3016)

#define	REG_GSU_R12 ((volatile u16)0x3018)

#define	REG_GSU_R13 ((volatile u16)0x301A)

#define	REG_GSU_R14 ((volatile u16)0x301C)

#define	REG_GSU_R15 ((volatile u16)0x301E)

#define	REG_GSU_R2 ((volatile u16)0x3004)

#define	REG_GSU_R3 ((volatile u16)0x3006)

#define	REG_GSU_R4 ((volatile u16)0x3008)

#define	REG_GSU_R5 ((volatile u16)0x300A)

#define	REG_GSU_R6 ((volatile u16)0x300C)

#define	REG_GSU_R7 ((volatile u16)0x300E)

#define	REG_GSU_R8 ((volatile u16)0x3010)

#define	REG_GSU_R9 ((volatile u16)0x3012)

#define	REG_PBR ((volatile u8)0x3034)

#define	REG_RAMBR ((volatile u8)0x303C)

#define	REG_ROMBR ((volatile u8)0x3036)

#define	REG_SCBR ((volatile u8)0x3038)

#define	REG_SCMR ((volatile u8)0x303A)

#define	REG_SFR ((volatile u16)0x3030)

#define	REG_SFR_L ((volatile u8)0x3030)

#define	REG_VCR ((volatile u8)0x303B)

#define	SCMR_2BPP 0x00

#define	SCMR_4BPP 0x01

#define	SCMR_8BPP 0x03

#define	SCMR_H128 0x00

#define	SCMR_H160 0x04

#define	SCMR_H192 0x20

#define	SCMR_RAN 0x08

#define	SCMR_RON 0x10

#define	SFR_GO 0x20

Functions
void	gsuDmaFullFrame (void)
	Scanline-polled 16KB DMA from SRAM to VRAM (60 FPS)

u8	gsuInit (void)
	Initialize SuperFX — detect hardware, set default config.

void	gsuLaunch (void)
	Launch GSU program and wait for completion (WRAM-safe)

void	gsuSetupBitmapTilemap (u16 vramAddr)
	Setup column-major tilemap for SuperFX PLOT framebuffer.

void	gsuSetupHdmaBlanking (u16 topBlank, u16 bottomBlank)
	Setup HDMA screen blanking for DMA bandwidth.

Variables
u8	gsu_cfgr
	CFGR register value ($80=IRQ mask, $A0=IRQ mask + fast multiply)

u8	gsu_dma_src_hi
	DMA source high byte ($00=buffer A at $70:0000, $40=buffer B at $70:4000)

u16	gsu_prog_addr
	GSU program 16-bit address (set by gsuSetProgram)

u8	gsu_prog_bank
	GSU program bank byte (set by gsuSetProgram)

u8	gsu_scbr
	SCBR screen base ($00=buffer A, $10=buffer B)

u8	gsu_scmr
	SCMR register value ($18=RAN+RON, $19=4bpp+RAN+RON)

u8	superfx_status
	SuperFX status from crt0 init (VCR chip version, 0=not detected)

Detailed Description

SuperFX (GSU) coprocessor library — registers, config, and API.

Provides a complete C API for SuperFX cartridges:

GSU detection and configuration
WRAM-safe GSU launch (mandatory — CPU can't read ROM during GSU execution)
DMA helpers for SRAM-to-VRAM framebuffer transfer
HDMA screen blanking for 60 FPS DMA bandwidth
Column-major tilemap setup for PLOT rendering

The GSU code itself is written in SuperFX assembly (.sfx files). The C API handles all SNES-side boilerplate.

See also: docs/tutorials/superfx.md

Macro Definition Documentation

◆ CLSR_10MHZ

#define CLSR_10MHZ 0x00

◆ CLSR_21MHZ

#define CLSR_21MHZ 0x01

◆ GSU_SRAM_BASE

#define GSU_SRAM_BASE 0x700000

◆ REG_BRAMR

#define REG_BRAMR (*(volatile u8*)0x3033)

◆ REG_CBR

#define REG_CBR (*(volatile u16*)0x303E)

◆ REG_CLSR

#define REG_CLSR (*(volatile u8*)0x3039)

◆ REG_GSU_R0

#define REG_GSU_R0 (*(volatile u16*)0x3000)

◆ REG_GSU_R1

#define REG_GSU_R1 (*(volatile u16*)0x3002)

◆ REG_GSU_R10

#define REG_GSU_R10 (*(volatile u16*)0x3014)

◆ REG_GSU_R11

#define REG_GSU_R11 (*(volatile u16*)0x3016)

◆ REG_GSU_R12

#define REG_GSU_R12 (*(volatile u16*)0x3018)

◆ REG_GSU_R13

#define REG_GSU_R13 (*(volatile u16*)0x301A)

◆ REG_GSU_R14

#define REG_GSU_R14 (*(volatile u16*)0x301C)

◆ REG_GSU_R15

#define REG_GSU_R15 (*(volatile u16*)0x301E)

◆ REG_GSU_R2

#define REG_GSU_R2 (*(volatile u16*)0x3004)

◆ REG_GSU_R3

#define REG_GSU_R3 (*(volatile u16*)0x3006)

◆ REG_GSU_R4

#define REG_GSU_R4 (*(volatile u16*)0x3008)

◆ REG_GSU_R5

#define REG_GSU_R5 (*(volatile u16*)0x300A)

◆ REG_GSU_R6

#define REG_GSU_R6 (*(volatile u16*)0x300C)

◆ REG_GSU_R7

#define REG_GSU_R7 (*(volatile u16*)0x300E)

◆ REG_GSU_R8

#define REG_GSU_R8 (*(volatile u16*)0x3010)

◆ REG_GSU_R9

#define REG_GSU_R9 (*(volatile u16*)0x3012)

◆ REG_PBR

#define REG_PBR (*(volatile u8*)0x3034)

◆ REG_RAMBR

#define REG_RAMBR (*(volatile u8*)0x303C)

◆ REG_ROMBR

#define REG_ROMBR (*(volatile u8*)0x3036)

◆ REG_SCBR

#define REG_SCBR (*(volatile u8*)0x3038)

◆ REG_SCMR

#define REG_SCMR (*(volatile u8*)0x303A)

◆ REG_SFR

#define REG_SFR (*(volatile u16*)0x3030)

◆ REG_SFR_L

#define REG_SFR_L (*(volatile u8*)0x3030)

◆ REG_VCR

#define REG_VCR (*(volatile u8*)0x303B)

◆ SCMR_2BPP

#define SCMR_2BPP 0x00

◆ SCMR_4BPP

#define SCMR_4BPP 0x01

◆ SCMR_8BPP

#define SCMR_8BPP 0x03

◆ SCMR_H128

#define SCMR_H128 0x00

◆ SCMR_H160

#define SCMR_H160 0x04

◆ SCMR_H192

#define SCMR_H192 0x20

◆ SCMR_RAN

#define SCMR_RAN 0x08

◆ SCMR_RON

#define SCMR_RON 0x10

◆ SFR_GO

#define SFR_GO 0x20

Function Documentation

◆ gsuDmaFullFrame()

void gsuDmaFullFrame ( void )

extern

Scanline-polled 16KB DMA from SRAM to VRAM (60 FPS)

Polls V-counter until scanline 184, then DMAs full framebuffer. Requires gsuSetupHdmaBlanking() for sufficient DMA bandwidth.

◆ gsuInit()

u8 gsuInit ( void )

Initialize SuperFX — detect hardware, set default config.

Returns: 1 if GSU detected, 0 if not

Sets defaults: gsu_cfgr=$80, gsu_scmr=$19, gsu_scbr=$00, gsu_dma_src_hi=$00

◆ gsuLaunch()

void gsuLaunch ( void )

extern

Launch GSU program and wait for completion (WRAM-safe)

Call gsuSetProgram() first to set the GSU binary address. Reads gsu_cfgr, gsu_scmr, gsu_scbr for configuration. Disables NMI during execution (ROM inaccessible).

◆ gsuSetupBitmapTilemap()

void gsuSetupBitmapTilemap ( u16 vramAddr )

extern

Setup column-major tilemap for SuperFX PLOT framebuffer.

Parameters

vramAddr VRAM word address for tilemap (typically 0x4000)

◆ gsuSetupHdmaBlanking()

void gsuSetupHdmaBlanking	(	u16	topBlank,
		u16	bottomBlank
	)

extern

Setup HDMA screen blanking for DMA bandwidth.

Parameters

topBlank	Scanlines of forced blank at top (e.g., 40)
bottomBlank	Scanlines of forced blank at bottom (e.g., 40)

Creates black bars like Star Fox. Total blank + VBlank must provide enough bandwidth for the 16KB framebuffer DMA (~6.2ms needed).

Variable Documentation

◆ gsu_cfgr

u8 gsu_cfgr

extern

CFGR register value ($80=IRQ mask, $A0=IRQ mask + fast multiply)

◆ gsu_dma_src_hi

u8 gsu_dma_src_hi

extern

DMA source high byte ($00=buffer A at $70:0000, $40=buffer B at $70:4000)

◆ gsu_prog_addr

u16 gsu_prog_addr

extern

GSU program 16-bit address (set by gsuSetProgram)

◆ gsu_prog_bank

u8 gsu_prog_bank

extern

GSU program bank byte (set by gsuSetProgram)

◆ gsu_scbr

u8 gsu_scbr

extern

SCBR screen base ($00=buffer A, $10=buffer B)

◆ gsu_scmr

u8 gsu_scmr

extern

SCMR register value ($18=RAN+RON, $19=4bpp+RAN+RON)

◆ superfx_status

u8 superfx_status

extern

SuperFX status from crt0 init (VCR chip version, 0=not detected)

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ CLSR_10MHZ

◆ CLSR_21MHZ

◆ GSU_SRAM_BASE

◆ REG_BRAMR

◆ REG_CBR

◆ REG_CLSR

◆ REG_GSU_R0

◆ REG_GSU_R1

◆ REG_GSU_R10

◆ REG_GSU_R11

◆ REG_GSU_R12

◆ REG_GSU_R13

◆ REG_GSU_R14

◆ REG_GSU_R15

◆ REG_GSU_R2

◆ REG_GSU_R3

◆ REG_GSU_R4

◆ REG_GSU_R5

◆ REG_GSU_R6

◆ REG_GSU_R7

◆ REG_GSU_R8

◆ REG_GSU_R9

◆ REG_PBR

◆ REG_RAMBR

◆ REG_ROMBR

◆ REG_SCBR

◆ REG_SCMR

◆ REG_SFR

◆ REG_SFR_L

◆ REG_VCR

◆ SCMR_2BPP

◆ SCMR_4BPP

◆ SCMR_8BPP

◆ SCMR_H128

◆ SCMR_H160

◆ SCMR_H192

◆ SCMR_RAN

◆ SCMR_RON

◆ SFR_GO

Function Documentation

◆ gsuDmaFullFrame()

◆ gsuInit()

◆ gsuLaunch()

◆ gsuSetupBitmapTilemap()

◆ gsuSetupHdmaBlanking()

Variable Documentation

◆ gsu_cfgr

◆ gsu_dma_src_hi

◆ gsu_prog_addr

◆ gsu_prog_bank

◆ gsu_scbr

◆ gsu_scmr

◆ superfx_status