sys.h File Reference

Header file for system functions. More...

#include <kos.h>

Go to the source code of this file.

Data Structures
struct	_atexit_entry
struct	lldiv_t
struct	timed_event
Defines
#define	_LONGLONG_DEF
#define	EXTERN   extern
#define	sys_bcd2bin(BCD)   sys_bcd2bin_nibbles(BCD,2)
	Convert a BCD format BYTE (least significant 2 digits) to an integer value.
#define	_mmu_table_addr   0x01100000
	Value of r1 register at the begining of execution.
#define	_code_base_addr   0x01220000
#define	_ram_base_addr   0x01101000
#define	_ram_size   ((__mg->_mmu_table_entries-4)<<10)
#define	MEM_REGS   0x07000000
#define	SD_REGS   0x07e00000
#define	IO_REGS   0x07a00000
#define	LCD_REGS   0x07300000
#define	CLK_REGS   0x07200000
#define	RTC_REGS   0x07B00000
#define	TMR_REGS   0x07600000
#define	INT_REGS   0x07100000
#define	CLK_1MHZ   0x16000000
#define	CLK_6MHZ   0x11000000
#define	CLK_12MHZ   0x10000000
#define	CLK_48MHZ   0x78023
#define	CLK_75MHZ   0x43012
#define	CLK_120MHZ   0x5c080
#define	CLK_152MHZ   0x44011
#define	CLK_192MHZ   0x58011
#define	NUM_EVENTS   5
#define	tmr_ms2ticks(a)   tmr_addms((tmr_t)0,(a))
	Macro to convert milliseconds to ticks.
#define	tmr_us2ticks(a)   tmr_addus((tmr_t)0,(a))
	Macro to convert milliseconds to ticks.
#define	MODE_MONO   0
#define	MODE_4GRAY   1
#define	MODE_16GRAY   2
#define	__EX_CONT   1
	Options for throw_exception.
#define	__EX_EXIT   2
	Options for throw_exception.
#define	__EX_WARM   4
	Options for throw_exception.
#define	__EX_RESET   8
	Options for throw_exception.
Typedefs
typedef unsigned long long	ULONGLONG
typedef long long	LONGLONG
typedef void(*	__interrupt__ )(void)
	Type definition for interrupt handler functions.
typedef void(*	ATEXITFUNC )()
typedef struct _atexit_entry	ATEXIT_ENTRY
typedef int	HEVENT
	Handle to refer to a timed event.
typedef ULONGLONG	tmr_t
	Type to use with all timer routines: ticks and frequencies are 64-bit.
Functions
int	atexit (ATEXITFUNC f)
unsigned int	sys_bcd2bin_nibbles (unsigned int BCD, int nibbles)
	Convert the least significant n (=nibbles, max. 8) digits of a BCD formatted number to it's integer value.
lldiv_t	lldiv (LONGLONG, LONGLONG)
unsigned	divlu2 (unsigned num_h, unsigned num_l, unsigned den, unsigned *rem)
	Unsigned 64/32 bit division.
ULONGLONG	udiv64 (ULONGLONG nom, unsigned den, unsigned *rem)
	Unsigned 64/32 bit division with 64 bit quotient.
LONGLONG	sdiv64 (LONGLONG nom, int den, int *rem)
	Signed 64/32 bit division with 64 bit quotient.
void	cpu_intoff ()
void	cpu_inton ()
void	cpu_intsave (unsigned int *buffer)
	Save interrupt controller state to a buffer (11 words)
void	cpu_intrestore (unsigned int *buffer)
	Restore interrupt controller state from a buffer (11 words)
void	cpu_clksave (unsigned int *buf)
	Save CPU clock state to a buffer (8-words)
void	cpu_clkrestore (unsigned int *buf)
	Restore CPU clock from a buffer (8-words)
int	cpu_setspeed (int hz)
	Set CPU speed in Hz, change to closest supported speed and return new frequency.
int	cpu_getspeed ()
	Get CPU speed in Hz.
int	__cpu_setspeed (int PLLCON)
	Low-level cpu speed control.
int	__cpu_getFCLK ()
	Get CPU clock speed in Hz. Same as cpu_getspeed.
int	__cpu_getHCLK ()
	Get peripherals clock (HCLK) speed in Hz.
int	__cpu_getPCLK ()
	Get peripherals clock (PCLK) speed in Hz.
void	cpu_flush_cache (int *ptr, int size)
	Flush write-back caches on the specified block of memory.
void	tmr_save (unsigned int *tmrbuffer)
	Save all timers state to a buffer (13-word)
void	tmr_restore (unsigned int *tmrbuffer)
	Restore saved timers state from buffer.
void	tmr_setup ()
	Setup system timers and event scheduler - automatically called at startup.
tmr_t	tmr_getsysfreq ()
	Get the frequency of the system timer in ticks per second, normally 100 KHz or 125KHz.
tmr_t	tmr_ticks ()
	Get system timer count in ticks since program started.
void	tmr_delayms (int milliseconds)
	Do not return until the specified time has passed.
void	tmr_delayus (int microseconds)
	Do not return until the specified time has passed (in microseconds). Accuracy is +/- 10 microseconds.
int	tmr_ticks2ms (tmr_t before, tmr_t after)
	Calculate elapsed time in milliseconds between before and after (both given in ticks)
int	tmr_ticks2us (tmr_t before, tmr_t after)
	Calculate elapsed time in microseconds between before and after (both given in ticks)
tmr_t	tmr_addms (tmr_t time, int ms)
	Add/subtract an interval in milliseconds to the given time in ticks.
tmr_t	tmr_addus (tmr_t time, int us)
	Add/subtract an interval in microseconds to the given time in ticks.
void	tmr_waituntil (tmr_t time)
	Wait until the system timer reaches the given time in ticks.
HEVENT	tmr_eventcreate (__interrupt__ handler, unsigned int ms, BOOL autorepeat)
	Create a timed event. Create a new timed event, specifying a callback function that will be called after the given time has passed. The autorepeat feature allows the event to be automatically rescheduled for another interval of time. Autorepeated events need to be manually removed by tmr_eventkill. One-shot events will remove themselves after completion (no need to explicitly call tmr_eventkill).
void	tmr_eventkill (HEVENT event)
	Kill a timed event. Stops an autoreloading event.
int	sys_RTC_seconds ()
	Get date in seconds from RTC.
void	lcd_sync ()
	Wait for LCD synchro.
void	__lcd_fix ()
	Fix LCD clock rate at any CPU speed.
void	lcd_save (unsigned int *buffer)
	Save LCD controller state (buffer size must be 17 words min.)
void	lcd_restore (unsigned int *buffer)
	Restore LCD controller state from buffer (saved by lcd_save)
int	lcd_setmode (int mode, int *physicalbuffer)
int	lcd_getheight ()
void	lcd_off ()
	Turn screen off.
void	lcd_on ()
	Turn screen on.
void	lcd_setcontrast (int level)
	Set the contrast level.
EXTERN int	sys_map_v2p (unsigned int vaddr)
	Convert a virtual address to its physical bus address.
EXTERN int	sys_map_p2v (unsigned int paddr)
	Convert a physical bus address to its virtual address.
int	sys_mem_classify (int addr)
	Classify a memory address 0=System; 1=Port1; 2=Main.
void *	sys_phys_malloc (size_t)
EXTERN void	sys_playTone (unsigned int tone, unsigned int duration)
EXTERN void	sys_waitTicks (unsigned int time)
EXTERN void	setDisplayPlane (unsigned char *plane)
EXTERN void	sys_playTone2 (unsigned int time, unsigned int duration)
int	sys_isRTCTick ()
	Returns '1' if an RTC Interrupt Tick has occured since it was last called.
unsigned char	sys_setRTCTickPeriod (unsigned char n)
	Ajdusts the rate of the RTC Tick. Remember to restore the default when done!
void	sys_waitRTCTicks (int count)
	Waits for 'count' RTC Ticks to elapse.
int	sys_delta_seconds (int t_start, int t_end)
	Compute the time span (in seconds) between t_start and t_end. Account for possible wrap around at midnight.
void	sys_error (const char *msg, int code)
	Output msg to screen, set errno=code and exit if code < 0.
void *	sys_chkptr (void *p)
	Check pointer after malloc'ing and exit via sys_error() if NULL.
void	throw_exception (char *message, unsigned int options)
	Throw a user exception Cause a user exception to be thrown. It displays the requested message and offer the user several options to treat the exception.
void	throw_dbgexception (char *message, unsigned int options)
void	__irq_addhook (int service_number, __interrupt__ serv_routine)
	Install an IRQ handler Set a routine to service interrupt requests from a specific device. It does not change the state of the interrupt controller, so the user needs to manually unmask the interrupt and configure the rest of the hardware to generate the proper IRQ request.
void	__irq_releasehook (int service_number)
	Uninstall an IRQ handler Removes a service routine that handles interrupt requests from a specific device. It does not change the state of the interrupt controller, so the user needs to manually mask the interrupt and configure the rest of the hardware to stop generating IRQ requests. If an IRQ is generated after this routine is called, it will be serviced by a do-nothing routine.

---

Detailed Description

Header file for system functions.

Definition in file sys.h.

---

Define Documentation

#define __EX_CONT   1

Options for throw_exception.

Definition at line 463 of file sys.h.

#define __EX_EXIT   2

Options for throw_exception.

Definition at line 467 of file sys.h.

#define __EX_RESET   8

Options for throw_exception.

Definition at line 475 of file sys.h.

#define __EX_WARM   4

Options for throw_exception.

Definition at line 471 of file sys.h.

#define _code_base_addr   0x01220000

Definition at line 159 of file sys.h.

#define _LONGLONG_DEF

Definition at line 22 of file sys.h.

#define _mmu_table_addr   0x01100000

Value of r1 register at the begining of execution.

See post of Robert Hildinger: "The R1 register contains the base address for all the ARM globals, which can be used to access all of the Saturn registers. Altering this register will not affect the calling code. The LR register contains the return address to get back into Saturn emulation."

API INFORMATION
---------------

So far there is no real API information available, although experimentally I've been able to determine the following offsets from the global base register for accessing the emulated Saturn CPU registers:

Base (R1) offset Description
---------------------------------------

0x90C Saturn register A (low order 8 nibbles)
0x910 Saturn register A (high order 8 nibbles)
0x914 Saturn register B (low order 8 nibbles)
0x918 Saturn register B (high order 8 nibbles)
0x91C Saturn register C (low order 8 nibbles)
0x920 Saturn register C (high order 8 nibbles)
0x924 Saturn register D (low order 8 nibbles)
0x928 Saturn register D (high order 8 nibbles)

0x92C Saturn register R0 (low order 8 nibbles)
0x930 Saturn register R0 (high order 8 nibbles)
0x934 Saturn register R1 (low order 8 nibbles)
0x938 Saturn register R1 (high order 8 nibbles)
0x93C Saturn register R2 (low order 8 nibbles)
0x940 Saturn register R2 (high order 8 nibbles)
0x944 Saturn register R3 (low order 8 nibbles)
0x948 Saturn register R3 (high order 8 nibbles)
0x94C Saturn register R4 (low order 8 nibbles)
0x950 Saturn register R4 (high order 8 nibbles)

0x954 Saturn register d0
0x958 Saturn register d1
0x95C Saturn register P
0x968 Saturn register ST
0x96C Saturn register HST
0x970 Saturn CARRY flag
0x974 Saturn DECIMAL_MODE flag

Definition at line 158 of file sys.h.

#define _ram_base_addr   0x01101000

Definition at line 160 of file sys.h.

#define _ram_size   ((__mg->_mmu_table_entries-4)<<10)

Definition at line 161 of file sys.h.

#define CLK_120MHZ   0x5c080

Definition at line 181 of file sys.h.

#define CLK_12MHZ   0x10000000

Definition at line 178 of file sys.h.

#define CLK_152MHZ   0x44011

Definition at line 182 of file sys.h.

#define CLK_192MHZ   0x58011

Definition at line 183 of file sys.h.

#define CLK_1MHZ   0x16000000

Definition at line 176 of file sys.h.

#define CLK_48MHZ   0x78023

Definition at line 179 of file sys.h.

#define CLK_6MHZ   0x11000000

Definition at line 177 of file sys.h.

#define CLK_75MHZ   0x43012

Definition at line 180 of file sys.h.

#define CLK_REGS   0x07200000

Definition at line 169 of file sys.h.

#define EXTERN   extern

Definition at line 29 of file sys.h.

#define INT_REGS   0x07100000

Definition at line 172 of file sys.h.

#define IO_REGS   0x07a00000

Definition at line 167 of file sys.h.

#define LCD_REGS   0x07300000

Definition at line 168 of file sys.h.

#define MEM_REGS   0x07000000

Definition at line 165 of file sys.h.

#define MODE_16GRAY   2

Definition at line 356 of file sys.h.

#define MODE_4GRAY   1

Definition at line 355 of file sys.h.

#define MODE_MONO   0

Definition at line 354 of file sys.h.

#define NUM_EVENTS   5

Definition at line 225 of file sys.h.

#define RTC_REGS   0x07B00000

Definition at line 170 of file sys.h.

#define SD_REGS   0x07e00000

Definition at line 166 of file sys.h.

#define sys_bcd2bin

(

BCD

)

sys_bcd2bin_nibbles(BCD,2)

Convert a BCD format BYTE (least significant 2 digits) to an integer value.

Definition at line 60 of file sys.h.

#define tmr_ms2ticks

(

a

)

tmr_addms((tmr_t)0,(a))

Macro to convert milliseconds to ticks.

Definition at line 270 of file sys.h.

#define TMR_REGS   0x07600000

Definition at line 171 of file sys.h.

#define tmr_us2ticks

(

a

)

tmr_addus((tmr_t)0,(a))

Macro to convert milliseconds to ticks.

Definition at line 273 of file sys.h.

---

Typedef Documentation

typedef void(* __interrupt__)(void)

Type definition for interrupt handler functions.

Definition at line 39 of file sys.h.

typedef struct _atexit_entry ATEXIT_ENTRY

typedef void(* ATEXITFUNC)()

Definition at line 43 of file sys.h.

typedef int HEVENT

Handle to refer to a timed event.

Definition at line 236 of file sys.h.

typedef long long LONGLONG

Definition at line 21 of file sys.h.

typedef ULONGLONG tmr_t

Type to use with all timer routines: ticks and frequencies are 64-bit.

Definition at line 246 of file sys.h.

typedef unsigned long long ULONGLONG

Definition at line 20 of file sys.h.

---

Function Documentation

int __cpu_getFCLK

(

)

Get CPU clock speed in Hz. Same as cpu_getspeed.

int __cpu_getHCLK

(

)

Get peripherals clock (HCLK) speed in Hz.

int __cpu_getPCLK

(

)

Get peripherals clock (PCLK) speed in Hz.

int __cpu_setspeed

(

int

PLLCON

)

Low-level cpu speed control.

void __irq_addhook	(	int	service_number,
		__interrupt__	serv_routine
	)

Install an IRQ handler Set a routine to service interrupt requests from a specific device. It does not change the state of the interrupt controller, so the user needs to manually unmask the interrupt and configure the rest of the hardware to generate the proper IRQ request.

Parameters:

service_number	Identifies the device that is causing the interrupt. It's a number from 0 to 31 according to the list below (see Samsung S3C2410X manual).
serv_routine	Address of a service routine. The service routine has no special requirements, other than returning as fast as possible to allow other IRQ's to be processed.

Note:

The interrupt service number is as follows: = [31] = [30] = [29] = [28] = [27] = [26] = [25] = [24] Not used = [23] = [22] = [21] = [20] = [19] = [18] = [17] = [16] = [15]

• =[14] =[13] =[12] [Used for HPGCC3 sound routines, do not use] =[11] [Used for HPGCC3 timed events, do not use] =[10] [Used for HPGCC3 system timer, do not use] = [9] = [8] = [7] = [6] Not used = [5] [Used for HPGCC3 keyboard routines, do not use] = [4] [Used for HPGCC3 keyboard routines, do not use] = [3] = [2] = [1] = [0] [Used for HPGCC3 exception handler, do not use]

See also:

__irq_releasehook

void __irq_releasehook

(

int

service_number

)

Uninstall an IRQ handler Removes a service routine that handles interrupt requests from a specific device. It does not change the state of the interrupt controller, so the user needs to manually mask the interrupt and configure the rest of the hardware to stop generating IRQ requests. If an IRQ is generated after this routine is called, it will be serviced by a do-nothing routine.

Parameters:

service_number

Identifies the device that is causing the interrupt. It's a number from 0 to 31 according to the list below (see Samsung S3C2410X manual).

Note:

See __irq_addhook for a list of interrupt service numbers

See also:

__irq_addhook

void __lcd_fix

(

)

Fix LCD clock rate at any CPU speed.

int atexit

(

ATEXITFUNC

f

)

void cpu_clkrestore

(

unsigned int *

buf

)

Restore CPU clock from a buffer (8-words)

void cpu_clksave

(

unsigned int *

buf

)

Save CPU clock state to a buffer (8-words)

void cpu_flush_cache	(	int *	ptr,
		int	size
	)

Flush write-back caches on the specified block of memory.

int cpu_getspeed

(

)

Get CPU speed in Hz.

void cpu_intoff

(

)

void cpu_inton

(

)

void cpu_intrestore

(

unsigned int *

buffer

)

Restore interrupt controller state from a buffer (11 words)

void cpu_intsave

(

unsigned int *

buffer

)

Save interrupt controller state to a buffer (11 words)

int cpu_setspeed

(

int

hz

)

Set CPU speed in Hz, change to closest supported speed and return new frequency.

unsigned divlu2	(	unsigned	num_h,
		unsigned	num_l,
		unsigned	den,
		unsigned *	rem
	)

Unsigned 64/32 bit division.

int lcd_getheight

(

)

void lcd_off

(

)

Turn screen off.

void lcd_on

(

)

Turn screen on.

void lcd_restore

(

unsigned int *

buffer

)

Restore LCD controller state from buffer (saved by lcd_save)

void lcd_save

(

unsigned int *

buffer

)

Save LCD controller state (buffer size must be 17 words min.)

void lcd_setcontrast

(

int

level

)

Set the contrast level.

Parameters:

level

Number from 0 to 15, being 15=darkest, 0=lightest

int lcd_setmode	(	int	mode,
		int *	physicalbuffer
	)

void lcd_sync

(

)

Wait for LCD synchro.

lldiv_t lldiv	(	LONGLONG	,
		LONGLONG
	)

LONGLONG sdiv64	(	LONGLONG	nom,
		int	den,
		int *	rem
	)

Signed 64/32 bit division with 64 bit quotient.

EXTERN void setDisplayPlane

(

unsigned char *

plane

)

unsigned int sys_bcd2bin_nibbles	(	unsigned int	BCD,
		int	nibbles
	)

Convert the least significant n (=nibbles, max. 8) digits of a BCD formatted number to it's integer value.

void sys_chkptr

(

void *

p

)

Check pointer after malloc'ing and exit via sys_error() if NULL.

Parameters:

p	the pointer to be checked

int sys_delta_seconds	(	int	t_start,
		int	t_end
	)

Compute the time span (in seconds) between t_start and t_end. Account for possible wrap around at midnight.

Parameters:

t_start	Start time
t_end	End time

void sys_error	(	const char *	msg,
		int	code
	)

Output msg to screen, set errno=code and exit if code < 0.

Parameters:

msg	The message text or NULL for none
code	The error code, forwarded to exit()

int sys_isRTCTick

(

)

Returns '1' if an RTC Interrupt Tick has occured since it was last called.

EXTERN int sys_map_p2v

(

unsigned int

paddr

)

Convert a physical bus address to its virtual address.

EXTERN int sys_map_v2p

(

unsigned int

vaddr

)

Convert a virtual address to its physical bus address.

int sys_mem_classify

(

int

addr

)

Classify a memory address 0=System; 1=Port1; 2=Main.

void* sys_phys_malloc

(

size_t

)

EXTERN void sys_playTone	(	unsigned int	tone,
		unsigned int	duration
	)

EXTERN void sys_playTone2	(	unsigned int	time,
		unsigned int	duration
	)

int sys_RTC_seconds

(

)

Get date in seconds from RTC.

Returns:

The current time in seconds

The total number of seconds 3600*H+60*M+S.

unsigned char sys_setRTCTickPeriod

(

unsigned char

n

)

Ajdusts the rate of the RTC Tick. Remember to restore the default when done!

void sys_waitRTCTicks

(

int

count

)

Waits for 'count' RTC Ticks to elapse.

EXTERN void sys_waitTicks

(

unsigned int

time

)

void throw_dbgexception	(	char *	message,
		unsigned int	options
	)

void throw_exception	(	char *	message,
		unsigned int	options
	)

Throw a user exception Cause a user exception to be thrown. It displays the requested message and offer the user several options to treat the exception.

Parameters:

message

The string that will be displayed.

options

One or more of the following constants: __EX_CONT Display the "Continue" option, allowing the program to continue. __EX_EXIT Display the "Exit" option, which immediately exits the program. __EX_WARM Display the "Warmstart" option, which exits the program and causes a restart of the calculator, similar to On-C. __EX_RESET Display the "Reset" option, which exits the program and then reset the calculator in a way equivalent to a paperclip. It is similar to a Warmstart but also restarts all the ARM hardware.

Note:

If the options parameter is passed as 0, the calculator will display the exception message and show no options, staying in an infinite loop until the user resets the calc using a paperclip. Only use this option if it is not safe to attempt to exit the program.

Returns:

The function does not return a value, and it may not return at all depending on the user's choice to handle the exception. If the user chooses to exit, warmstart or reset the program will exit first as if the exit() function was called.

tmr_t tmr_addms	(	tmr_t	time,
		int	ms
	)

Add/subtract an interval in milliseconds to the given time in ticks.

tmr_t tmr_addus	(	tmr_t	time,
		int	us
	)

Add/subtract an interval in microseconds to the given time in ticks.

void tmr_delayms

(

int

milliseconds

)

Do not return until the specified time has passed.

void tmr_delayus

(

int

microseconds

)

Do not return until the specified time has passed (in microseconds). Accuracy is +/- 10 microseconds.

HEVENT tmr_eventcreate	(	__interrupt__	handler,
		unsigned int	ms,
		BOOL	autorepeat
	)

Create a timed event. Create a new timed event, specifying a callback function that will be called after the given time has passed. The autorepeat feature allows the event to be automatically rescheduled for another interval of time. Autorepeated events need to be manually removed by tmr_eventkill. One-shot events will remove themselves after completion (no need to explicitly call tmr_eventkill).

Parameters:

handler	The function that will be called back on every interval
ms	Time interval in milliseconds after which the handler will be called
autorepeat	If TRUE, the event will be repeated every 'ms' milliseconds, if FALSE the event will be executed only once after 'ms' milliseconds have passed since the event was created.

Returns:

An event handler, or -1 if there are no more handles available (see notes).

Note:

A maximum of NUM_EVENTS (typically 5) can be created simultaneously.

See also:

tmr_eventkill

void tmr_eventkill

(

HEVENT

event

)

Kill a timed event. Stops an autoreloading event.

Parameters:

event

The event handler obtained from tmr_eventcreate

See also:

tmr_eventcreate

tmr_t tmr_getsysfreq

(

)

Get the frequency of the system timer in ticks per second, normally 100 KHz or 125KHz.

void tmr_restore

(

unsigned int *

tmrbuffer

)

Restore saved timers state from buffer.

void tmr_save

(

unsigned int *

tmrbuffer

)

Save all timers state to a buffer (13-word)

void tmr_setup

(

)

Setup system timers and event scheduler - automatically called at startup.

tmr_t tmr_ticks

(

)

Get system timer count in ticks since program started.

int tmr_ticks2ms	(	tmr_t	before,
		tmr_t	after
	)

Calculate elapsed time in milliseconds between before and after (both given in ticks)

int tmr_ticks2us	(	tmr_t	before,
		tmr_t	after
	)

Calculate elapsed time in microseconds between before and after (both given in ticks)

void tmr_waituntil

(

tmr_t

time

)

Wait until the system timer reaches the given time in ticks.

ULONGLONG udiv64	(	ULONGLONG	nom,
		unsigned	den,
		unsigned *	rem
	)

Unsigned 64/32 bit division with 64 bit quotient.