system.h File Reference

NDS hardware definitions. More...

#include <stddef.h>
#include <nds/ndstypes.h>

Data Structures
struct	RTCtime
	Struct containing time and day of the real time clock. More...
struct	rtcTime
	Struct containing time of the real time clock. More...
struct	rtcTimeAndDate
	Struct containing time and day of the real time clock. More...
struct	sysVectors
	Structure of function pointers corresponding to ARM CPU interrupts. Each member contains an ARM instuction that will be executed when an exeption occurs. More...
struct	tPERSONAL_DATA
	User's DS settings. More...

Macros
#define	PersonalData   ((PERSONAL_DATA *)0x2FFFC80)
	Default location for the user's personal data (see PERSONAL_DATA).
#define	PM_LED_CONTROL_MASK   (3 << 4)
	PM control register bits - LED control.
#define	REG_DISPSTAT   (*(vu16*)0x04000004)
	LCD status register.
#define	REG_HALTCNT   (*(vu16*)0x04000300)
	Halt control register.
#define	REG_POWERCNT   *(vu16 *)0x4000304
	Power control register.
#define	REG_VCOUNT   (*(vu16*)0x4000006)
	Current display scanline.
#define	SCREEN_HEIGHT   192
	Screen height in pixels.
#define	SCREEN_WIDTH   256
	Screen width in pixels.

Typedefs
typedef struct tPERSONAL_DATA	PERSONAL_DATA
	User's DS settings.
typedef struct sysVectors	sysVectors_t
	Structure of function pointers corresponding to ARM CPU interrupts. Each member contains an ARM instuction that will be executed when an exeption occurs.

Enumerations
enum	ARM7_power {   POWER_SOUND = BIT(0) ,   PM_CONTROL_REG = 0 ,   PM_BATTERY_REG = 1 ,   PM_AMPLIFIER_REG = 2 ,   PM_READ_REGISTER = (1 << 7) ,   PM_AMP_OFFSET = 2 ,   PM_GAIN_OFFSET = 3 ,   PM_BACKLIGHT_LEVEL = 4 ,   PM_GAIN_20 = 0 ,   PM_GAIN_40 = 1 ,   PM_GAIN_80 = 2 ,   PM_GAIN_160 = 3 ,   PM_AMP_ON = 1 ,   PM_AMP_OFF = 0 }
	Power-controlled hardware devices accessable to the ARM7. More...
enum	BACKLIGHT_LEVELS {   BACKLIGHT_LOW ,   BACKLIGHT_MED ,   BACKLIGHT_HIGH ,   BACKLIGHT_MAX }
	Backlight level settings. More...
enum	DISP_BITS {   DISP_IN_VBLANK = BIT(0) ,   DISP_IN_HBLANK = BIT(1) ,   DISP_YTRIGGERED = BIT(2) ,   DISP_VBLANK_IRQ = BIT(3) ,   DISP_HBLANK_IRQ = BIT(4) ,   DISP_YTRIGGER_IRQ = BIT(5) }
	LCD Status register defines. More...
enum	PM_Bits {   PM_SOUND_AMP = BIT(0) ,   PM_SOUND_MUTE = BIT(1) ,   PM_BACKLIGHT_BOTTOM = BIT(2) ,   PM_BACKLIGHT_TOP = BIT(3) ,   PM_SYSTEM_PWR = BIT(6) ,   PM_ARM9_DIRECT = BIT(16) ,   POWER_LCD = PM_ARM9_DIRECT | BIT(0) ,   POWER_2D_A = PM_ARM9_DIRECT | BIT(1) ,   POWER_MATRIX = PM_ARM9_DIRECT | BIT(2) ,   POWER_3D_CORE = PM_ARM9_DIRECT | BIT(3) ,   POWER_2D_B = PM_ARM9_DIRECT | BIT(9) ,   POWER_SWAP_LCDS = PM_ARM9_DIRECT | BIT(15) ,   POWER_ALL_2D = PM_ARM9_DIRECT | POWER_LCD | POWER_2D_A | POWER_2D_B ,   POWER_ALL = PM_ARM9_DIRECT | POWER_ALL_2D | POWER_3D_CORE | POWER_MATRIX }
	Power Management control bits for powerOn() and powerOff(). More...

Functions
void	disableSleep (void)
	Disables sleep mode from ARM9.
void	enableSleep (void)
	Enables sleep mode from ARM9.
u32	getBatteryLevel (void)
	Gets the DS battery level.
u8 *	getHeapEnd (void)
	Returns current end of heap space.
u8 *	getHeapLimit (void)
	Returns current heap limit.
u8 *	getHeapStart (void)
	Returns current start of heap space.
void	installSystemFIFO (void)
	Install the system FIFO handlers.
static bool	isDSiMode (void)
	Checks whether the application is running in DSi mode.
static bool	isHwDebugger (void)
	Checks whether the application is running in a debugger or retail console.
static void	lcdMainOnBottom (void)
	Forces the main core to display on the bottom.
static void	lcdMainOnTop (void)
	Forces the main core to display on the top.
static void	lcdSwap (void)
	Switches the screens.
void	ledBlink (int bm)
	Set the LED blink mode.
void *	memCached (void *address)
	Returns a cached mirror of an address.
void *	memUncached (void *address)
	Returns an uncached mirror of an address.
void	peripheralSlot2DisableCache (void)
	Disable data cache for the DS slot-2 memory region. If write-back was enabled, additionally clear and flush the data cache.
void	peripheralSlot2EnableCache (bool write_back)
	Enable data cache for the DS slot-2 memory region.
void	powerOff (uint32_t bits)
	Turns off specified hardware.
void	powerOn (uint32_t bits)
	Turns on specified hardware.
void	readFirmware (u32 address, void *buffer, u32 length)
	Read bytes at a specified address from firmware flash.
static int	readPowerManagement (int reg)
	Read from a power management register.
bool	readUserSettings (void)
	Read user settings/personal data from firmware flash to a shared memory location.
bool	setCpuClock (bool speed)
	Sets the ARM9 clock speed, only possible in DSi mode.
void	setVectorBase (int base)
	Set the ARM9 interrupt vector base to one of two locations:
static void	SetYtrigger (int Yvalue)
	Sets the LCD refresh scanline Y trigger.
static void	systemShutDown (void)
	Powers down the DS.
void	systemSleep (void)
	Causes the NDS to go to sleep.
int	writeFirmware (u32 address, void *buffer, u32 length)
	Write bytes at a specified address to firmware flash.
int	writePowerManagement (int reg, int command)
	Write to a power management register.

Variables
sysVectors_t	SystemVectors
	Function pointers to user-provided interrupt handlers, used in the alternate interrupt vector mode in place of BIOS interrupt handlers.

Detailed Description

NDS hardware definitions.

These definitions are usually only touched during the initialization of the program.

Macro Definition Documentation

REG_HALTCNT

#define REG_HALTCNT   (*(vu16*)0x04000300)

Halt control register.

Writing 0x40 to REG_HALTCNT activates GBA mode. REG_HALTCNT can only be accessed via the BIOS.

REG_POWERCNT

#define REG_POWERCNT   *(vu16 *)0x4000304

Power control register.

This register controls what hardware should be turned ON or OFF.

Typedef Documentation

PERSONAL_DATA

typedef struct tPERSONAL_DATA PERSONAL_DATA

User's DS settings.

Defines the structure the DS firmware uses for transfer of the user's settings to the booted program.

Theme/Color values:

• 0 = Gray
• 1 = Brown
• 2 = Red
• 3 = Pink
• 4 = Orange
• 5 = Yellow
• 6 = Yellow/Green-ish
• 7 = Green
• 8 = Dark Green
• 9 = Green/Blue-ish
• 10 = Light Blue
• 11 = Blue
• 12 = Dark Blue
• 13 = Dark Purple
• 14 = Purple
• 15 = Purple/Red-ish

Language values:

• 0 = Japanese
• 1 = English
• 2 = French
• 3 = German
• 4 = Italian
• 5 = Spanish
• 6 = Chinese(?)
• 7 = Unknown/Reserved

sysVectors_t

typedef struct sysVectors sysVectors_t

Structure of function pointers corresponding to ARM CPU interrupts. Each member contains an ARM instuction that will be executed when an exeption occurs.

See GBATEK for more information on each interrupt.

See also

SystemVectors

Enumeration Type Documentation

ARM7_power

enum ARM7_power

Power-controlled hardware devices accessable to the ARM7.

Note

These should only be used when programming for the ARM7. Trying to boot up these hardware devices via the ARM9 would lead to unexpected results. ARM7 only.

Enumerator
POWER_SOUND	Controls the power for the sound controller.
PM_CONTROL_REG	Selects the PM control register.
PM_BATTERY_REG	Selects the PM battery register.
PM_AMPLIFIER_REG	Selects the PM amplifier register.
PM_READ_REGISTER	Selects the PM read register.
PM_AMP_OFFSET	Selects the PM amp register.
PM_GAIN_OFFSET	Selects the PM gain register.
PM_BACKLIGHT_LEVEL	Selects the DS Lite backlight register.
PM_GAIN_20	Sets the mic gain to 20db.
PM_GAIN_40	Sets the mic gain to 40db.
PM_GAIN_80	Sets the mic gain to 80db.
PM_GAIN_160	Sets the mic gain to 160db.
PM_AMP_ON	Turns the sound amp ON.
PM_AMP_OFF	Turns the sound amp OFF.

BACKLIGHT_LEVELS

enum BACKLIGHT_LEVELS

Backlight level settings.

Note

Only available on DS Lite.

Enumerator
BACKLIGHT_LOW	Low backlight setting.
BACKLIGHT_MED	Medium backlight setting.
BACKLIGHT_HIGH	High backlight setting.
BACKLIGHT_MAX	Max backlight setting.

DISP_BITS

enum DISP_BITS

LCD Status register defines.

Enumerator
DISP_IN_VBLANK	The display currently in a vertical blank.
DISP_IN_HBLANK	The display currently in a horizontal blank.
DISP_YTRIGGERED	Current scanline and DISP_Y match.
DISP_VBLANK_IRQ	Interrupt on vertical blank.
DISP_HBLANK_IRQ	Interrupt on horizontal blank.
DISP_YTRIGGER_IRQ	Interrupt when current scanline and DISP_Y match.

PM_Bits

enum PM_Bits

Power Management control bits for powerOn() and powerOff().

Enumerator
PM_SOUND_AMP	Power the sound hardware (needed for GBA mode too)
PM_SOUND_MUTE	Mute the main speakers, headphone output will still work.
PM_BACKLIGHT_BOTTOM	Enable the bottom backlight if set.
PM_BACKLIGHT_TOP	Enable the top backlight if set.
PM_SYSTEM_PWR	Turn the NDS power OFF if set.
PM_ARM9_DIRECT	Internal: Write to REG_POWERCNT directly instead of sending a FIFO message.
POWER_LCD	Controls the power for both LCD screens.
POWER_2D_A	Controls the power for the main 2D core.
POWER_MATRIX	Controls the power for the 3D matrix.
POWER_3D_CORE	Controls the power for the main 3D core.
POWER_2D_B	Controls the power for the sub 2D core.
POWER_SWAP_LCDS	Controls which screen should use the main core.
POWER_ALL_2D	Power 2D hardware.
POWER_ALL	Power everything.

Function Documentation

getBatteryLevel()

u32 getBatteryLevel

(

void

)

Gets the DS battery level.

This returns a value with two fields. Bits 0 to 3 are the battery level, and bit 7 is set to 1 if an external power source is connected to the DS.

On DSi the battery level is the one reported by the hardware. On DS, the battery level is only "high" or "low", and libnds returns 15 or 3 respectively as the equivalent DSi battery level.

Returns

Battery level and external power source status.

getHeapEnd()

u8 * getHeapEnd

(

void

)

Returns current end of heap space.

Returns

Returns a pointer to the end of the heap.

getHeapLimit()

u8 * getHeapLimit

(

void

)

Returns current heap limit.

Returns

Returns a pointer to the limit of the heap. It won't grow past this address.

getHeapStart()

u8 * getHeapStart

(

void

)

Returns current start of heap space.

Returns

Returns a pointer to the start of the heap.

installSystemFIFO()

void installSystemFIFO

(

void

)

Install the system FIFO handlers.

This handles power management, DSi SD card access, and firmware flash access.

isDSiMode()

static bool isDSiMode ( void  )

inlinestatic

Checks whether the application is running in DSi mode.

Returns

Returns true if the application is running in DSi mode.

isHwDebugger()

static bool isHwDebugger ( void  )

inlinestatic

Checks whether the application is running in a debugger or retail console.

It works on DS and DSi consoles.

Note

swiIsDebugger() only works with the cache disabled, this function doesn't have any restrictions.

Returns

Returns true if running on a debugger unit, false on retail units.

ledBlink()

void ledBlink

(

int

bm

)

Set the LED blink mode.

Parameters

bm	What to power on.

memCached()

void * memCached

(

void *

address

)

Returns a cached mirror of an address.

Parameters

address

An address.

Returns

A pointer to the cached mirror of that address.

memUncached()

void * memUncached

(

void *

address

)

Returns an uncached mirror of an address.

Parameters

address

An address.

Returns

A pointer to the uncached mirror of that address.

peripheralSlot2DisableCache()

void peripheralSlot2DisableCache

(

void

)

Disable data cache for the DS slot-2 memory region. If write-back was enabled, additionally clear and flush the data cache.

Note that flushing the data cache may still be required to remove stale "read" pages, such as if you write to external RAM uncached and then re-enable cache.

peripheralSlot2EnableCache()

void peripheralSlot2EnableCache

(

bool

write_back

)

Enable data cache for the DS slot-2 memory region.

Note that this is not safe to enable if you're using Slot-2 memory for purposes other than external RAM, such as rumble or other I/O.

Parameters

write_back

Set as write-back. This allows writes to skip the slow Slot-2 bus, at the expense of requiring a full memory flush when calling peripheralSlot2DisableCache().

powerOff()

static void powerOff ( uint32_t  bits )

inline

Turns off specified hardware.

It may be called from the ARM7 or ARM9 (ARM9 power bits will be ignored by the ARM7, ARM7 power bits will be passed to the ARM7 from the ARM9).

Parameters

bits	What to power OFF (PM_Bits).

powerOn()

static void powerOn ( uint32_t  bits )

inline

Turns on specified hardware.

It may be called from the ARM7 or ARM9 (ARM9 power bits will be ignored by the ARM7, ARM7 power bits will be passed to the ARM7 from the ARM9).

Parameters

bits	What to power ON (PM_Bits).

readFirmware()

void readFirmware	(	u32	address,
		void *	buffer,
		u32	length
	)

Read bytes at a specified address from firmware flash.

Parameters

address	Address in the firmware to read from.
buffer	Pointer to the buffer to use as destination.
length	Size of the buffer to read.

readPowerManagement()

static int readPowerManagement ( int  reg )

inlinestatic

Read from a power management register.

Parameters

reg	The register to read from.

Returns

The value read from the register.

readUserSettings()

bool readUserSettings

(

void

)

Read user settings/personal data from firmware flash to a shared memory location.

Returns

It returns true on success, false on error.

setCpuClock()

bool setCpuClock

(

bool

speed

)

Sets the ARM9 clock speed, only possible in DSi mode.

Parameters

speed

CPU speed (false = 67.03MHz, true = 134.06MHz)

Returns

The old CPU speed value

setVectorBase()

void setVectorBase

(

int

base

)

Set the ARM9 interrupt vector base to one of two locations:

• 0xFFFF0000 (default; controlled by the BIOS)
• 0x00000000 (alternate; configurable by the homebrew program, initialized by default with function pointers to BIOS handlers)

To initialize function pointers for the alternate vector base, set the relevant values in the SystemVectors structure before calling this function.

Note that it is recommended to call this function with interrupts disabled (REG_IME = 0).

Parameters

base	Vector base. Setting it to any non-zero value will use the default vector base (0xFFFF0000); setting it to zero will use the alternate vector base (0x00000000).

See also

SystemVectors

SetYtrigger()

static void SetYtrigger ( int  Yvalue )

inlinestatic

Sets the LCD refresh scanline Y trigger.

Parameters

Yvalue

The value for the Y trigger.

systemShutDown()

void systemShutDown ( void  )

inlinestatic

Powers down the DS.

This function shutds down the console.

systemSleep()

void systemSleep

(

void

)

Causes the NDS to go to sleep.

The NDS will be reawakened when the lid is opened.

Note

By default, this is automatically called when closing the lid.

writeFirmware()

int writeFirmware	(	u32	address,
		void *	buffer,
		u32	length
	)

Write bytes at a specified address to firmware flash.

Parameters

address	Address in the firmware to write to.
buffer	Pointer to the buffer to write.
length	Size of the buffer to write.

Returns

0 on success, else error.

writePowerManagement()

int writePowerManagement	(	int	reg,
		int	command
	)

Write to a power management register.

Parameters

reg	Register address.
command	Command to send to the register.

Returns

Value returned from the command/value exchange.

Variable Documentation

SystemVectors

sysVectors_t SystemVectors

extern

Function pointers to user-provided interrupt handlers, used in the alternate interrupt vector mode in place of BIOS interrupt handlers.

See also

setVectorBase