sgdk
sys.h File Reference

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

Go to the source code of this file.

Defines

#define PROCESS_PALETTE_FADING   (1 << 0)
#define PROCESS_BITMAP_TASK   (1 << 1)
#define PROCESS_TILECACHE_TASK   (1 << 2)
#define PROCESS_DMA_TASK   (1 << 3)
#define PROCESS_XGM_TASK   (1 << 4)

Functions

void SYS_assertReset ()
 Assert reset.
void SYS_reset ()
 Soft reset.
void SYS_hardReset ()
 Hard reset.
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 ()
 Reenable interrupts (Vertical, Horizontal and External).
void SYS_setVIntPreCallback (VoidCallback *CB)
 Set start of 'Vertical interrupt' 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 ()
 Return != 0 if we are in the V-Int callback method.
u16 SYS_isInHIntCallback ()
 Return != 0 if we are in the H-Int callback method.
u16 SYS_isInExtIntCallback ()
 Return != 0 if we are in the Ext-Int callback method.
u16 SYS_isInInterrupt ()
 Return != 0 if we are in an interrupt callback method (Vertical, Horizontal or External)
void SYS_setVIntAligned (bool value)
 Set V-Interrupt VBlank alignment state (default state is TRUE).
u16 SYS_isVIntAligned ()
 Return != 0 if V-Interrupt are forced to be aligned on VBlank.
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 load (in %)
void SYS_showFrameLoad ()
 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.
u32 SYS_getMissedFrames ()
 Return the number of missed frames (a missed frame mean that a VInt was missed)
void SYS_resetMissedFrames ()
 Reset the number of missed frames.
void SYS_die (char *err)
 Die with the specified error message.
Program execution is interrupted.

Variables

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.
VoidCallback * internalVIntCB
 Internal Vertical interrupt callback.
VoidCallback * internalHIntCB
 Internal Horizontal interrupt callback.
VoidCallback * internalExtIntCB
 Internal External 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.


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 interrupt (to protect some VDP accesses for instance) and should always be followed by SYS_enableInts().
Be careful, this method can't be used if you are currently processing an interrupt !

See also:
SYS_enableInts()
void SYS_enableInts ( )

Reenable interrupts (Vertical, Horizontal and External).

This method is used to reenable interrupt after a call to SYS_disableInts().
Has no effect if called without a prior SYS_disableInts() call.

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 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.
This method don't return accurate result when you have missed frames (V-Int missed).

See also:
SYS_getMissedFrames()
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.

u32 SYS_getMissedFrames ( )

Return the number of missed frames (a missed frame mean that a VInt was missed)

See also:
SYS_setVIntAligned(bool)
SYS_isVIntAligned()
SYS_resetMissedFrames()
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 ( )

Return != 0 if we are in the Ext-Int callback method.

This method tests if we are currently processing an External interrupt.

u16 SYS_isInHIntCallback ( )

Return != 0 if we are in the H-Int callback method.

This method tests if we are currently processing a Horizontal retrace interrupt.

u16 SYS_isInInterrupt ( )

Return != 0 if we are in an interrupt callback method (Vertical, Horizontal or External)

This method tests if we are currently processing an interrupt.

u16 SYS_isInVIntCallback ( )

Return != 0 if we are in the V-Int callback method.

This method tests if we are currently processing a Vertical retrace interrupt.

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

u16 SYS_isVIntAligned ( )

Return != 0 if V-Interrupt are forced to be aligned on VBlank.

See also:
SYS_setVIntAligned(bool)
void SYS_reset ( )

Soft reset.

Software reset

void SYS_resetMissedFrames ( )

Reset the number of missed frames.

See also:
SYS_getMissedFrames()
void SYS_setExtIntCallback ( VoidCallback *  CB)

Set External interrupt callback method.

Parameters:
CBPointer 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:
CBPointer 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)

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_setVIntAligned ( bool  value)

Set V-Interrupt VBlank alignment state (default state is TRUE).

This method allows to force the V-Interrupt to be aligned on VBlank period.
It means that if the V-Int happen too late (after start of VBlank) then we force a passive wait for the next VBlank so we can align start of V-Int processing with beggining of VBlank period (to ensure fast DMA transfert and avoid possible graphical glitches due to VRAM update during active display).
When a V-Int is delayed to next VBlank then we increase the number of missed frames.

See also:
SYS_getMissedFrames()
void SYS_setVIntCallback ( VoidCallback *  CB)

Set 'Vertical Interrupt' callback method.

Parameters:
CBPointer 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 right before vertical blank.
This period is usually used to prepare next frame data (refresh sprites, scrolling ...).
Note that the callback will be called after some internal SGDK V-Int processes and so probably not right at the start of the V-Blank area.
For that you can use the SYS_setPreVIntCallback(..) method instead.

See also:
SYS_setHIntCallback(VoidCallback *CB);
SYS_setVIntPreCallback(VoidCallback *CB);
void SYS_setVIntPreCallback ( VoidCallback *  CB)

Set start of 'Vertical interrupt' callback method.

Parameters:
CBPointer to the method to call when the Vertical Interrupt just started.
You can remove current callback by passing a null pointer here.

Vertical interrupt happen at the end of display period right before vertical blank.
This period is usually used to prepare next frame data (refresh sprites, scrolling ...).
The difference with the SYS_setVIntCallback(..) method is this one is called right after the Vertical Interrupt happened and before any internals SGDK V-Int processes.
This is useful when you really need to do something right at the beginning of the V-Blank area.

See also:
SYS_setVIntCallback(VoidCallback *CB);
SYS_setHIntCallback(VoidCallback *CB);
void SYS_showFrameLoad ( )

Show a cursor indicating current frame load level in scanline (top = 0% load, bottom = 100% 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()

Variable Documentation

VoidCallback* addressErrorCB

Address error interrupt callback.

You can modify it to use your own callback (for debug purpose).

VoidCallback* busErrorCB

Bus error interrupt callback.

You can modify it to use your own callback (for debug purpose).

VoidCallback* chkInstCB

CHK instruction interrupt callback.

You can modify it to use your own callback (for debug purpose).

VoidCallback* errorExceptionCB

Error exception callback.

You can modify it to use your own callback (for debug purpose).

VoidCallback* illegalInstCB

Illegal instruction exception callback.

You can modify it to use your own callback (for debug purpose).

VoidCallback* intCB

Level interrupt callback.

You can modify it to use your own callback.

VoidCallback* internalExtIntCB

Internal External interrupt callback.

You can modify it to use your own callback.
Be careful: by doing that you disable SGDK default Ext-Int code and related features !
You should use it only for very low level process and if you don't care about SGDK facilities.
In all others cases you would use the SYS_setExtIntCallback() method.

VoidCallback* internalHIntCB

Internal Horizontal interrupt callback.

You can modify it to use your own callback.
Be careful: by doing that you disable SGDK default H-Int code and related features !
You should use it only for very low level process and if you don't care about SGDK facilities.
In all others cases you would use the SYS_setHIntCallback() method.

VoidCallback* internalVIntCB

Internal Vertical interrupt callback.

You can modify it to use your own callback.
Be careful: by doing that you disable SGDK default V-Int code and related features !
You should use it only for very low level process and if you don't care about SGDK facilities.
In all others cases you would use the SYS_setVIntCallback() method.

VoidCallback* line1x1xCB

Line 1x1x exception callback.

You can modify it to use your own callback (for debug purpose).

VoidCallback* privilegeViolationCB

Privilege violation exception callback.

You can modify it to use your own callback (for debug purpose).

VoidCallback* traceCB

Trace interrupt callback.

You can modify it to use your own callback (for debug purpose).

VoidCallback* trapvInstCB

TRAPV instruction interrupt callback.

You can modify it to use your own callback (for debug purpose).

VoidCallback* zeroDivideCB

Division by zero exception callback.

You can modify it to use your own callback (for debug purpose).

 All Classes Files Functions Variables Typedefs Enumerations Enumerator Defines