System Messages

Introduction

Each process needs to periodically check for messages from the "System Message Queue" to respond to system level events. A handle to this OSMessageQueue can be retrieved by calling OSGetSystemMessageQueue.

Handling OS_SYSTEM_MESSAGE_DATA0_RELEASE_FOREGROUND

This message is received only when a process needs to release the foreground and let another process interact with the user.

If using the DEMOGfx or DEMODRC APIs there is a function to call per API to properly release all foreground-only resources called DEMOGfxReleaseForeground and DEMODRCReleaseForeground.

The GX2 subsystem requires the most work on a foreground switch as it is the primary user of both MEM1 and the Foreground Bucket. All resources allocated from MEM1 and the Foreground Bucket must be freed on a foreground release. If the process needs to preserve data from either of these regions it must do so manually. The Cafe operating system will not automatically save and restore these regions; instead they are cleared on each foreground switch.

NOTE:
It is necessary to call OSReleaseForeground from all three cores to complete a foreground release.
NOTE:
When in the background, a game can only expect to receive CPU time on Core 2. Any task that should run in the background should be scheduled on Core 2.
if (msg.data0 == OS_SYSTEM_MESSAGE_DATA0_RELEASE_FOREGROUND)
{
    DEMODRCReleaseForeground(); // Free all DEMODRC MEM1 and Foreground Bucket resources.

    DEMOGfxReleaseForeground(); // Free all DEMOGfx MEM1 and Foreground Bucket resources.
				// Calls GX2DrawDone.

    // Signal other threads creating GX2 display lists to call
    // GX2EndDisplayList and block while in the background

    // Call GX2SetTVEnable(TRUE) if rendering was done to TV
    // Call GX2SetDRCEnable(TRUE) if rendering was done to DRC

    // Signal To Other Cores that the Foreground needs to be released.

    // Block other threads that do not need to operate in the background.

    OSReleaseForeground();
}
if (in the background)
{
    // If this thread was scheduled to run in the background, yield to other threads and processes.
    OSYieldThread();
}

Handling OS_SYSTEM_MESSAGE_DATA1_RELEASE_FOREGROUND_SHUTDOWN_FLAG

A special case of the OS_SYSTEM_MESSAGE_DATA0_RELEASE_FOREGROUND message is when the OSMessage data1 field is set to OS_SYSTEM_MESSAGE_DATA1_RELEASE_FOREGROUND_SHUTDOWN_FLAG. This indicates that the process is being shutdown and the next message that will be received is an OS_SYSTEM_MESSAGE_DATA0_EXIT message.

NOTE:
Even if the HOME Menu is disabled, this message may be received from the system.

Handling OS_SYSTEM_MESSAGE_DATA0_ACQUIRED_FOREGROUND

By the time a process receives the "acquired foreground" message from the System Message Queue, all drivers that handle a foreground switch will be ready to use.

NOTE:
If you are using the DRC Camera or DRC Microphone, it must to call the Init and Open APIs again to resume using these devices.
if (msg.data0 == OS_SYSTEM_MESSAGE_DATA0_RELEASE_FOREGROUND)
{
    DEMOGfxAcquiredForeground(); // Re-allocate all DEMOGfx MEM1 and Foreground Bucket resources.
				 // Calls GX2SetContextState

    DEMODRCAcquiredForeground(); // Re-allocate all DEMODRC MEM1 and Foreground Bucket resources.

    // Un-block other threads that do not need to operate in the background.
}

Handling OS_SYSTEM_MESSAGE_DATA0_EXIT

This message is received via the system message queue when a process has been instructed to exit.

NOTE:
A process will only exit from the background.

Handling OS_SYSTEM_MESSAGE_DATA0_NETIO_CHANGE

This message is received via the system message queue when the game is in the background. It notifies the game that network I/O is starting or stopping in the foreground process (a system application). A game can use this information to throttle its own network I/O or make changes to its behavior due to the different in network bandwidth.

The data1 member of the MESSAGE structure will be nonzero if network I/O is starting, and zero if it has ended.

Handling OS_SYSTEM_MESSAGE_DATA0_HOMEBUTTON_DENIED

This message is sent if the HOME Menu is disabled when the user presses the HOME Button on any controller.

Demos for Process Switching

See Also

OSGetSystemMessageQueue
OSReleaseForeground
OSEnableHomeButtonMenu

Revision History

2014/01/21 Terminology change to HOME Menu.
2013/05/08 Automated cleanup pass.
2012/08/20 Updated messages.
2012/07/27 Cleanup Pass
2012/04/17 Initial version.


CONFIDENTIAL