Entry point unit / Interrupt callback / System. More...

Classes
struct	ROMHeader
Defines
#define	PROCESS_PALETTE_FADING (1 << 0)
#define	PROCESS_BITMAP_TASK (1 << 1)
#define	PROCESS_DMA_TASK (1 << 2)
#define	PROCESS_XGM_TASK (1 << 3)
#define	PROCESS_VDP_SCROLL_TASK (1 << 4)
#define	ROM_ALIGN_BIT 17
#define	ROM_ALIGN (1 << ROM_ALIGN_BIT)
#define	ROM_ALIGN_MASK (ROM_ALIGN - 1)
#define	ROM_START 0
#define	ROM_END (((u32) &_stext) + ((u32) &_sdata))
#define	ROM_SIZE ((ROM_END + ROM_ALIGN_MASK) & (~ROM_ALIGN_MASK))
Enumerations
enum	VBlankProcessTime { IMMEDIATELY, ON_VBLANK, ON_VBLANK_START }
	Define at which period to do VBlank process (see SYS_doVBlankProcess() method) More...
Functions
void	SYS_assertReset ()
	Assert reset.
void	SYS_reset ()
	Soft reset.
void	SYS_hardReset ()
	Hard reset.
bool	SYS_doVBlankProcess ()
	Wait for start of VBlank and do all the VBlank processing (DMA transfers, XGM driver tempo, Joypad pooling..)
bool	SYS_doVBlankProcessEx (VBlankProcessTime processTime)
	Do all the VBlank processing (DMA transfers, XGM driver tempo, Joypad pooling..)
u16	SYS_getInterruptMaskLevel ()
	Return current interrupt mask level.
void	SYS_setInterruptMaskLevel (u16 value)
	Set interrupt mask level.
u16	SYS_getAndSetInterruptMaskLevel (u16 value)
	Set the interrupt mask level to given value and return previous level.
void	SYS_disableInts ()
	Disable interrupts (Vertical, Horizontal and External).
void	SYS_enableInts ()
	Re-enable interrupts (Vertical, Horizontal and External).
void	SYS_setVBlankCallback (VoidCallback *CB)
	Set user 'Vertical Blank' callback method.
void	SYS_setVIntCallback (VoidCallback *CB)
	Set 'Vertical Interrupt' callback method.
void	SYS_setHIntCallback (VoidCallback *CB)
	Set 'Horizontal Interrupt' callback method.
void	SYS_setExtIntCallback (VoidCallback *CB)
	Set External interrupt callback method.
u16	SYS_isInVIntCallback ()
u16	SYS_isInHIntCallback ()
u16	SYS_isInExtIntCallback ()
u16	SYS_isInInterrupt ()
bool	SYS_isInVInt ()
	Return TRUE if we are in the V-Interrupt process.
void	SYS_setVIntAligned (bool value)
bool	SYS_isVIntAligned ()
u16	SYS_isNTSC ()
	Return != 0 if we are on a NTSC system.
u16	SYS_isPAL ()
	Return != 0 if we are on a PAL system.
u32	SYS_getFPS ()
	Returns number of Frame Per Second.
fix32	SYS_getFPSAsFloat ()
	Returns number of Frame Per Second (fix32 form).
u16	SYS_getCPULoad ()
	Return an estimation of CPU frame load (in %)
void	SYS_showFrameLoad (bool mean)
	Show a cursor indicating current frame load level in scanline (top = 0% load, bottom = 100% load)
void	SYS_hideFrameLoad ()
	Hide the frame load cursor previously enabled using SYS_showFrameLoad() method.
u16	SYS_computeChecksum ()
	Computes full ROM checksum and return it. The checksum is a custom fast 32 bit checksum converted to 16 bit at end.
bool	SYS_isChecksumOk ()
	Returns TRUE if ROM checksum is ok (correspond to rom_head.checksum field)
void	SYS_die (char *err)
	Die with the specified error message. Program execution is interrupted.
Variables
const ROMHeader	rom_header
u32	_stext
u32	_sdata
VoidCallback *	busErrorCB
	Bus error interrupt callback.
VoidCallback *	addressErrorCB
	Address error interrupt callback.
VoidCallback *	illegalInstCB
	Illegal instruction exception callback.
VoidCallback *	zeroDivideCB
	Division by zero exception callback.
VoidCallback *	chkInstCB
	CHK instruction interrupt callback.
VoidCallback *	trapvInstCB
	TRAPV instruction interrupt callback.
VoidCallback *	privilegeViolationCB
	Privilege violation exception callback.
VoidCallback *	traceCB
	Trace interrupt callback.
VoidCallback *	line1x1xCB
	Line 1x1x exception callback.
VoidCallback *	errorExceptionCB
	Error exception callback.
VoidCallback *	intCB
	Level interrupt callback.

Detailed Description

Entry point unit / Interrupt callback / System.

Author:: Stephane Dallongeville

Date:: 08/2011

This unit contains SGDK initialization / reset methods, IRQ callbacks and others system stuff.

Enumeration Type Documentation

enum VBlankProcessTime

Define at which period to do VBlank process (see SYS_doVBlankProcess() method)

Enumerator:

ON_VBLANK	Start VBlank process immediately whatever we are in blanking period or not
ON_VBLANK_START	Start VBlank process on VBlank period, start immediatly in we are already in VBlank Start VBlank process on VBlank start period, means that we wait the next start of VBlank period if we missed it

Function Documentation

void SYS_assertReset ( )

Assert reset.

Assert reset pin on the 68000 CPU. This is needed to reset some attached hardware.

void SYS_die ( char * err )

Die with the specified error message.
Program execution is interrupted.

This actually display an error message and program ends execution.

void SYS_disableInts ( )

Disable interrupts (Vertical, Horizontal and External).

This method is used to temporary disable interrupts to protect some processes and should always be followed by SYS_enableInts().
You need to protect against interrupts any processes than can be perturbed / corrupted by the interrupt callback code (IO ports access in general but not only).
Now by default SGDK doesn't do anything armful in its interrupts handlers (except with the Bitmap engine) so it's not necessary to protect from interrupts by default but you may need it if your interrupts callback code does mess with VDP for instance.
Note that you can nest SYS_disableInts / SYS_enableInts() calls.

See also:: SYS_enableInts()

bool SYS_doVBlankProcess ( )

Wait for start of VBlank and do all the VBlank processing (DMA transfers, XGM driver tempo, Joypad pooling..)

Returns:: FALSE if process was canceled because the method was called from V-Int (vertical interrupt) callback in which case we exit the function as V-Int will be triggered immediately.

Do all the SGDK VBlank process.
Some specific processing should be done during the Vertical Blank period as the VDP is idle at this time. This is always where we should do all VDP data transfer (using the DMA preferably) but we can also do the processes which has to be done at a frame basis (joypad polling, sound driver sync/update..)
In the case of SGDK, calling this method will actually do the following tasks:

flush the DMA queue
process asynchronous palette fading operation
joypad polling

Note that VBlank process may be delayed to next VBlank if we missed the start of the VBlank period so that will cause a frame miss.

bool SYS_doVBlankProcessEx ( VBlankProcessTime processTime )

Do all the VBlank processing (DMA transfers, XGM driver tempo, Joypad pooling..)

Parameters:

processTime Define at which period we start VBlank process, accepted values are:
IMMEDIATELY Start VBlank process immediatly whatever we are in blanking period or not (*highly discouraged* unless you really know what you're doing !)
ON_VBLANK Start VBlank process on VBlank period, if we already are in VBlank period it starts immediately (discouraged as VBlank period may be shortened and all processes cannot be completed in time)
ON_VBLANK_START Start VBlank process on VBlank *start* period (recommanded as default value). That means that if SYS_doVBlankProcess() is called too late (after the start of VBlank) then we force a passive wait for the next start of VBlank so we can align the processing with the beggining of VBlank period to ensure fast DMA transfert and avoid possible graphical glitches due to VRAM update during active display.

Returns:: FALSE if process was canceled because we forced Start VBlank process (time = ON_VBLANK_START) and the method was called from V-Int (vertical interrupt) callback in which case we exit the function as V-Int will be triggered immediately.

Do all the SGDK VBlank process.
Some specific processing should be done during the Vertical Blank period as the VDP is idle at this time. This is always where we should do all VDP data transfer (using the DMA preferably) but we can also do the processes which has to be done at a frame basis (joypad polling, sound driver sync/update..)
In the case of SGDK, calling this method will actually do the following tasks:

flush the DMA queue
process asynchronous palette fading operation
joypad polling

Note that depending the used time parameter, VBlank process may be delayed to next VBlank so that will wause a frame miss.

void SYS_enableInts ( )

Re-enable interrupts (Vertical, Horizontal and External).

This method is used to reenable interrupts after a call to SYS_disableInts().
Note that you can nest SYS_disableInts / SYS_enableInts() calls.

See also:: SYS_disableInts()

u16 SYS_getAndSetInterruptMaskLevel ( u16 value )

Set the interrupt mask level to given value and return previous level.

You can disable interrupt depending their level.
Interrupt with level <= interrupt mask level are ignored.
We have 3 different interrupts:
Vertical interrupt (V-INT): level 6
Horizontal interrupt (H-INT): level 4
External interrupt (EX-INT): level 2
Vertical interrupt has the highest level (and so priority) where external interrupt has lowest one.
For instance to disable Vertical interrupt just use SYS_setInterruptMaskLevel(6).

See also:: SYS_getInterruptMaskLevel(); SYS_setInterruptMaskLevel(); SYS_setVIntCallback(); SYS_setHIntCallback()

u16 SYS_getCPULoad ( )

Return an estimation of CPU frame load (in %)

Return an estimation of CPU load (in %, mean value computed on 8 frames) based of idle time spent in VDP_waitVSync() / VDP_waitVInt() methods.
The method can return value above 100% you CPU load is higher than 1 frame.

See also:: VDP_waitVSync(); VDP_waitVInt()

u32 SYS_getFPS ( )

Returns number of Frame Per Second.

This function actually returns the number of time it was called in the last second.
i.e: for benchmarking you should call this method only once per frame update.

fix32 SYS_getFPSAsFloat ( )

Returns number of Frame Per Second (fix32 form).

This function actually returns the number of time it was called in the last second.
i.e: for benchmarking you should call this method only once per frame update.

u16 SYS_getInterruptMaskLevel ( )

Return current interrupt mask level.

See SYS_setInterruptMaskLevel() for more informations about interrupt mask level.

void SYS_hardReset ( )

Hard reset.

Reset with forced hardware init and memory clear / reset operation.

void SYS_hideFrameLoad ( )

Hide the frame load cursor previously enabled using SYS_showFrameLoad() method.

See also:: SYS_showFrameLoad()

u16 SYS_isInExtIntCallback ( )

Deprecated:: Always return 0 now, you need to use your own flag to detect if you are processing an External interrupt

u16 SYS_isInHIntCallback ( )

Deprecated:: Always return 0 now, you need to use your own flag to detect if you are processing a Horizontal interrupt

u16 SYS_isInInterrupt ( )

Deprecated:: Use SYS_isInVInt() instead, only vertical interrupt supported now

bool SYS_isInVInt ( )

Return TRUE if we are in the V-Interrupt process.

This method tests if we are currently processing a Vertical retrace interrupt (V-Int callback).

u16 SYS_isInVIntCallback ( )

Deprecated:: Use SYS_isInVInt() instead

u16 SYS_isNTSC ( )

Return != 0 if we are on a NTSC system.

Better to use the IS_PALSYSTEM

u16 SYS_isPAL ( )

Return != 0 if we are on a PAL system.

Better to use the IS_PALSYSTEM

bool SYS_isVIntAligned ( )

Deprecated:: Not anymore useful as SYS_doVBlankProcess() handle that directly now

void SYS_reset ( )

Soft reset.

Software reset

void SYS_setExtIntCallback ( VoidCallback * CB )

Set External interrupt callback method.

Parameters:

CB	Pointer to the method to call on External Interrupt. You can remove current callback by passing a null pointer here.

External interrupt happen on Light Gun trigger (HVCounter is locked).

void SYS_setHIntCallback ( VoidCallback * CB )

Set 'Horizontal Interrupt' callback method.

Parameters:

CB	Pointer to the method to call on Horizontal Interrupt. You can remove current callback by passing a null pointer here.

Horizontal interrupt happen at the end of scanline display period right before Horizontal blank.
This period is usually used to do mid frame changes (palette, scrolling or others raster effect).
When you do that, don't forget to protect your VDP access from your main loop using SYS_disableInts() / SYS_enableInts() otherwise you may corrupt your VDP writes.

void SYS_setInterruptMaskLevel ( u16 value )

Set interrupt mask level.

You can disable interrupt depending their level.
Interrupt with level <= interrupt mask level are ignored.
We have 3 different interrupts:
Vertical interrupt (V-INT): level 6
Horizontal interrupt (H-INT): level 4
External interrupt (EX-INT): level 2
Vertical interrupt has the highest level (and so priority) where external interrupt has lowest one.
For instance to disable Vertical interrupt just use SYS_setInterruptMaskLevel(6).

See also:: SYS_getInterruptMaskLevel(); SYS_getAndSetInterruptMaskLevel(); SYS_setVIntCallback(); SYS_setHIntCallback()

void SYS_setVBlankCallback ( VoidCallback * CB )

Set user 'Vertical Blank' callback method.

Parameters:

CB	Pointer to the method to call on Vertical Blank period. You can remove current callback by passing a NULL pointer here.

Vertical blank period starts right at the end of display period.
This period is usually used to prepare next frame data (refresh sprites, scrolling ...).
SGDK handle that in the SYS_doVBlankProcess() method and will call the user 'Vertical Blank' from this method after all major tasks.
It's recommended to use the 'Vertical Blank' callback instead of the 'VInt' callback if you need to do some VDP accesses.

See also:: SYS_setVIntCallback(VoidCallback *CB);

void SYS_setVIntAligned ( bool value )

Deprecated:: Not anymore useful as SYS_doVBlankProcess() handle that directly now

void SYS_setVIntCallback ( VoidCallback * CB )

Set 'Vertical Interrupt' callback method.

Parameters:

CB	Pointer to the method to call on Vertical Interrupt. You can remove current callback by passing a NULL pointer here.

Vertical interrupt happen at the end of display period at the start of the vertical blank period.
This period is usually used to prepare next frame data (refresh sprites, scrolling ...) though now SGDK handle most of these process using SYS_doVBlankProcess() so you can control it manually (do it from main loop or put it in Vint callback).
The only things that SGDK always handle from the vint callback is the XGM sound driver music tempo and Bitmap engine phase reset.
It's recommended to keep your code as fast as possible as it will eat precious VBlank time, nor you should touch the VDP from your Vint callback otherwise you will need to protect any VDP accesses from your main loop (which is painful), use the SYS_setVIntCallback(..) instead for that.

See also:: SYS_setVBlankCallback(VoidCallback *CB);; SYS_setHIntCallback(VoidCallback *CB);

void SYS_showFrameLoad ( bool mean )

Show a cursor indicating current frame load level in scanline (top = 0% load, bottom = 100% load)

Parameters:

mean	frame load level display is averaged on 8 frames (mean load)

Show current frame load using a cursor indicating the scanline reached when VDP_waitVSync() / VDP_waitVInt() method was called.
Note that internally sprite 0 is used to display to cursor (palette 0 and color 15) as it is not directly used by the Sprite Engine but if you're using the low level VDP sprite methods then you should know that sprite 0 will be used here.

See also:: SYS_hideFrameLoad()