core.h File Reference

Jo Engine core function prototypes. More...

Go to the source code of this file.

Macros
#define	jo_core_error(...)
#define	JO_ENGINE_VERSION
	Jo Engine Version.
#define	jo_core_set_screens_order(screen1, args...)
	Set scroll screen order between them.

Typedefs
typedef void(*)	jo_event_callback(void)
	Function prototype for jo_core_add_callback().
typedef void(*)	jo_interrupt_handler(void)
	Function prototype for interrupt handlers (Internal usage).
typedef void(*)	jo_slave_callback(void)
	Function prototype for jo_core_exec_on_slave().
typedef void(*)	jo_slave_job_function(void *argument)
	Function of a job of the slave CPU (Internal usage).

Functions
void	__jo_core_error (char *message, const char *function)
void	__jo_core_errorf (const char *function, const char *format,...) __attribute__((cold
	The message formatted, then __jo_core_error() (Internal usage): one call at each of the hundreds of jo_core_error() (the formatting at each of them was about 4 KB of code), out of the hot code (cold).
void	jo_core_init (const jo_color back_color)
	Init the engine.
void	jo_core_run (void)
	Run the game.
int	jo_core_add_vblank_callback (const jo_event_callback callback)
	Add a callback during VBLANK interruption.
void	jo_core_remove_vblank_callback (const int vblank_event_id)
	Remove a callback during VBLANK interruption.
int	jo_core_add_callback (const jo_event_callback callback)
	Add a callback in the game loop on main CPU.
void	jo_core_remove_callback (const int event_id)
	Remove a callback in the game loop from on main CPU.
int	jo_core_add_slave_callback (const jo_event_callback callback)
	Add a callback in the game loop on slave CPU.
void	jo_core_remove_slave_callback (const int event_id)
	Remove a callback in the game loop from on slave CPU.
void	jo_core_set_restart_game_callback (const jo_event_callback callback)
	Add a callback when A+B+C+Start is pressed on the first control pad.
void	jo_goto_boot_menu (void)
	Return to the boot menu.
void	jo_core_exec_on_slave (jo_slave_callback callback)
	Execute a callback on the slave CPU.
void	jo_core_wait_for_slave (void)
	Wait until all the callbacks given to jo_core_exec_on_slave() are completed.
int	jo_core_slave_idle_time (void)
	Balance of the CPUs in the last frame (between the 2 last calls of jo_core_wait_for_slave()).
bool	__jo_core_is_slave_running (void)
	Check if the slave CPU started (Internal usage).
void	__jo_core_add_slave_job (const jo_slave_job_function function, void *argument)
	Add a job to the queue of the slave CPU (Internal usage).
static __jo_force_inline void	jo_core_disable_reset (void)
	Disable reset button.
static __jo_force_inline void	jo_core_enable_reset (void)
	Enable reset button.
void	jo_core_tv_off (void)
	Turn OFF scroll drawing processing in the monitor.
void	jo_core_tv_on (void)
	Turn ON scroll drawing processing in the monitor.
static __jo_force_inline int	jo_core_get_refresh_rate (void)
	Get the refresh rate of the console.
static __jo_force_inline void	jo_core_exit_to_multiplayer (void)
	Exit program and return to the Saturn multiplayer (CD player) screen.
static __jo_force_inline void	jo_core_restart_saturn (void)
	Restart the Saturn.
void	jo_core_suspend (void)
	Stop the execution until someone press Start.
static __jo_force_inline char *	jo_get_last_error (void)
	Get last error.
void	jo_dump_vdp1_registers (void)
	Dump VDP1 registers.
void	jo_dump_vdp2_registers (void)
	Dump VDP2 registers.
void	__jo_core_set_screens_order (jo_scroll_screen screen1,...)
	Screen order (Internal usage).
static __jo_force_inline unsigned int	jo_core_get_vblank_count (void)
	Get the number of VBLANK since startup (60 per second in NTSC, 50 in PAL).
void	__jo_core_synch (void)
	Wait for the end of the current frame (Internal usage).
void	__jo_core_set_interrupt_handler (const unsigned int vector, jo_interrupt_handler handler)
	Set an interrupt handler in the vector table (Internal usage).
void	__jo_core_enable_scu_interrupts (const unsigned int mask)
	Unmask SCU interrupts (Internal usage).
void	__jo_core_restore_scu_mask (void)
	Write the SCU interrupt mask again at the end of a SCU interrupt handler (Internal usage).
static __jo_force_inline unsigned int	__jo_core_get_sr (void)
	Get CPU status register (Internal usage).
static __jo_force_inline void	__jo_core_set_sr (const unsigned int sr)
	Set CPU status register (Internal usage).
static __jo_force_inline unsigned int	__jo_core_disable_interrupts (void)
	Mask all interrupts (Internal usage).
static __jo_force_inline void	__jo_core_restore_interrupts (const unsigned int sr)
	Restore interrupts masked by __jo_core_disable_interrupts() (Internal usage).

Variables
char	__jo_last_error [JO_PRINTF_BUF_SIZE]
	Error handling (Internal usage).
void	noinline
volatile unsigned int	__jo_core_vblank_count
	Number of VBLANK since startup (Internal usage).

Detailed Description

Jo Engine core function prototypes.

Author

Johannes Fetz

Bug

No known bugs.

Macro Definition Documentation

jo_core_error

#define jo_core_error

(

...

)

jo_core_set_screens_order

#define jo_core_set_screens_order	(		screen1,
			args... )

Set scroll screen order between them.

Parameters

screen1	First screen (high priority)
args	Other screens

Remarks

Default Jo Engine screen priority : NBG0 > SPR0 > SPR1 > RBG0 > NBG1 > NBG2 > NBG3

JO_ENGINE_VERSION

#define JO_ENGINE_VERSION

Jo Engine Version.

Typedef Documentation

jo_event_callback

typedef void(*) jo_event_callback(void)

Function prototype for jo_core_add_callback().

jo_interrupt_handler

typedef void(*) jo_interrupt_handler(void)

Function prototype for interrupt handlers (Internal usage).

jo_slave_callback

typedef void(*) jo_slave_callback(void)

Function prototype for jo_core_exec_on_slave().

jo_slave_job_function

typedef void(*) jo_slave_job_function(void *argument)

Function of a job of the slave CPU (Internal usage).

Function Documentation

__jo_core_add_slave_job()

void __jo_core_add_slave_job	(	const jo_slave_job_function	function,
		void *	argument )

Add a job to the queue of the slave CPU (Internal usage).

Parameters

function	Function executed by the slave CPU
argument	Argument of the function

Remarks

The jobs are executed in order. The master CPU waits only if the queue is full. If the slave CPU didn't start, the function is executed now by the master CPU

The slave CPU purges its cache before each job: the job reads the data written by the master CPU before this call

__jo_core_disable_interrupts()

__jo_force_inline unsigned int __jo_core_disable_interrupts ( void )

static

Mask all interrupts (Internal usage).

Returns

Previous status register for __jo_core_restore_interrupts()

__jo_core_enable_scu_interrupts()

void __jo_core_enable_scu_interrupts

(

const unsigned int

mask

)

Unmask SCU interrupts (Internal usage).

Parameters

mask	Interrupts (JO_SCU_INT_VBLANK_IN, etc)

__jo_core_error()

void __jo_core_error	(	char *	message,
		const char *	function )

__jo_core_errorf()

void __jo_core_errorf	(	const char *	function,
		const char *	format,
			... )

The message formatted, then __jo_core_error() (Internal usage): one call at each of the hundreds of jo_core_error() (the formatting at each of them was about 4 KB of code), out of the hot code (cold).

__jo_core_get_sr()

__jo_force_inline unsigned int __jo_core_get_sr ( void )

static

Get CPU status register (Internal usage).

Returns

Status register value

__jo_core_is_slave_running()

bool __jo_core_is_slave_running

(

void

)

Check if the slave CPU started (Internal usage).

Returns

false if the slave CPU didn't start (the jobs are executed by the master CPU)

__jo_core_restore_interrupts()

__jo_force_inline void __jo_core_restore_interrupts ( const unsigned int sr )

static

Restore interrupts masked by __jo_core_disable_interrupts() (Internal usage).

Parameters

sr	Value returned by __jo_core_disable_interrupts()

__jo_core_restore_scu_mask()

void __jo_core_restore_scu_mask

(

void

)

Write the SCU interrupt mask again at the end of a SCU interrupt handler (Internal usage).

Remarks

When the CPU takes a SCU interrupt, the SCU masks all its interrupts (JO_SCU_IMS = JO_SCU_INT_ALL): without this call, no other SCU interrupt happens (the BIOS handlers do the same)

__jo_core_set_interrupt_handler()

void __jo_core_set_interrupt_handler	(	const unsigned int	vector,
		jo_interrupt_handler	handler )

Set an interrupt handler in the vector table (Internal usage).

Parameters

vector	Interrupt vector number (JO_VECTOR_VBLANK_IN, etc)
handler	Function declared with attribute((interrupt_handler))

__jo_core_set_screens_order()

void __jo_core_set_screens_order	(	jo_scroll_screen	screen1,
			... )

Screen order (Internal usage).

Warning

Use jo_core_set_screens_order instead

__jo_core_set_sr()

__jo_force_inline void __jo_core_set_sr ( const unsigned int sr )

static

Set CPU status register (Internal usage).

Parameters

sr	Status register value (JO_SH2_SR_INTERRUPT_MASK bits: interrupt mask level)

__jo_core_synch()

void __jo_core_synch

(

void

)

Wait for the end of the current frame (Internal usage).

Remarks

Send the VDP1 commands and wait for JO_FRAMERATE VBLANK

jo_core_add_callback()

int jo_core_add_callback

(

const jo_event_callback

callback

)

Add a callback in the game loop on main CPU.

Parameters

callback

Function name with no parameters and no return value

Warning

Must be called before jo_core_run()

Returns

Event Id (usefull for jo_core_remove_callback())

jo_core_add_slave_callback()

int jo_core_add_slave_callback

(

const jo_event_callback

callback

)

Add a callback in the game loop on slave CPU.

Parameters

callback

Function name with no parameters and no return value

Warning

Must be called before jo_core_run()

Returns

Event Id (usefull for jo_core_remove_slave_callback())

jo_core_add_vblank_callback()

int jo_core_add_vblank_callback

(

const jo_event_callback

callback

)

Add a callback during VBLANK interruption.

Parameters

callback

Function name with no parameters and no return value

Returns

VBLANK Event Id (usefull for jo_core_remove_vblank_callback())

jo_core_disable_reset()

__jo_force_inline void jo_core_disable_reset ( void )

static

Disable reset button.

jo_core_enable_reset()

__jo_force_inline void jo_core_enable_reset ( void )

static

Enable reset button.

jo_core_exec_on_slave()

void jo_core_exec_on_slave

(

jo_slave_callback

callback

)

Execute a callback on the slave CPU.

Parameters

callback

Function name with no parameters and no return value

Remarks

The callback is added to the jobs of the slave CPU: the master CPU doesn't wait (unless 8 jobs are waiting). The slave CPU may first finish a job of the engine (the VDP1 commands of the previous frame are sorted and copied by the slave CPU, see JO_COMPILE_WITH_DUAL_CPU_SUPPORT)

If the slave CPU didn't start, the callback is executed on the master CPU

jo_core_exit_to_multiplayer()

__jo_force_inline void jo_core_exit_to_multiplayer ( void )

static

Exit program and return to the Saturn multiplayer (CD player) screen.

Warning

Works but I didn't found documentation about it

Todo

Investigate and give feedback to https://segaxtreme.net/threads/best-way-to-debug-saturn-bios.18644/

jo_core_get_refresh_rate()

__jo_force_inline int jo_core_get_refresh_rate ( void )

static

Get the refresh rate of the console.

Returns

50 for a PAL console, 60 for a NTSC console

Remarks

This is the number of VBLANK per second (see jo_core_add_vblank_callback())

jo_core_get_vblank_count()

__jo_force_inline unsigned int jo_core_get_vblank_count ( void )

static

Get the number of VBLANK since startup (60 per second in NTSC, 50 in PAL).

Returns

VBLANK count (it is incremented by the VBLANK interrupt)

Remarks

Measure the time of a frame or the frames per second without a timer

jo_core_init()

void jo_core_init

(

const jo_color

back_color

)

Init the engine.

Parameters

back_color

Default background color (colors.h)

Warning

Must be the first function called in jo_main()

jo_core_remove_callback()

void jo_core_remove_callback

(

const int

event_id

)

Remove a callback in the game loop from on main CPU.

Parameters

event_id

Value returned by jo_core_add_callback()

jo_core_remove_slave_callback()

void jo_core_remove_slave_callback

(

const int

event_id

)

Remove a callback in the game loop from on slave CPU.

Parameters

event_id

Value returned by jo_core_add_slave_callback()

jo_core_remove_vblank_callback()

void jo_core_remove_vblank_callback

(

const int

vblank_event_id

)

Remove a callback during VBLANK interruption.

Parameters

vblank_event_id

Value returned by jo_core_add_vblank_callback()

jo_core_restart_saturn()

__jo_force_inline void jo_core_restart_saturn ( void )

static

Restart the Saturn.

Warning

Doesn't work in Yabause

jo_core_run()

void jo_core_run

(

void

)

Run the game.

Warning

Must be the last function called in jo_main()

jo_core_set_restart_game_callback()

void jo_core_set_restart_game_callback

(

const jo_event_callback

callback

)

Add a callback when A+B+C+Start is pressed on the first control pad.

Parameters

callback

Function name with no parameters and no return value

jo_core_slave_idle_time()

int jo_core_slave_idle_time

(

void

)

Balance of the CPUs in the last frame (between the 2 last calls of jo_core_wait_for_slave()).

Returns

Microseconds the slave CPU spent waiting for a job (it can take more work), negative: microseconds the master CPU waited for the slave CPU in jo_core_wait_for_slave() (the slave CPU has too much work)

Remarks

To move the drawing of some objects from a CPU to the other: the frame takes the time of the slowest CPU

jo_core_suspend()

void jo_core_suspend

(

void

)

Stop the execution until someone press Start.

jo_core_tv_off()

void jo_core_tv_off

(

void

)

Turn OFF scroll drawing processing in the monitor.

jo_core_tv_on()

void jo_core_tv_on

(

void

)

Turn ON scroll drawing processing in the monitor.

jo_core_wait_for_slave()

void jo_core_wait_for_slave

(

void

)

Wait until all the callbacks given to jo_core_exec_on_slave() are completed.

Remarks

Then the master CPU can read the data written by the slave CPU (its cache is purged)

jo_dump_vdp1_registers()

void jo_dump_vdp1_registers

(

void

)

Dump VDP1 registers.

jo_dump_vdp2_registers()

void jo_dump_vdp2_registers

(

void

)

Dump VDP2 registers.

jo_get_last_error()

__jo_force_inline char * jo_get_last_error ( void )

static

Get last error.

Returns

Formated error

jo_goto_boot_menu()

void jo_goto_boot_menu

(

void

)

Return to the boot menu.

Variable Documentation

__jo_core_vblank_count

volatile unsigned int __jo_core_vblank_count

extern

Number of VBLANK since startup (Internal usage).

__jo_last_error

char __jo_last_error[JO_PRINTF_BUF_SIZE]

extern

Error handling (Internal usage).

Warning

MC Hammer: don't touch this

noinline

void noinline