sgdk: sys.h File Reference

sgdk

- Main Page
- Related Pages
- Classes
- Files

- File List
- File Members

Classes | Defines | Enumerations | Functions | Variables
sys.h File Reference

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

Go to the source code of this file.

## 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()

## 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* 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