Application Concepts

Introduction

Cafe Core OS (COS) applications are obliged to handle several system events:

This topic describes the high-level concepts associated with these events. For more information on the Application Lifecycle, see Application Lifecycle. In particular, refer to the Application Process State Diagram.

Game as Process

Your game runs as a process under Cafe OS.

A process has a dedicated address space and memory. Your game process is isolated from other non-game processes, for security and robustness.

Concurrency

After being launched, your game's process resides in memory along with several system processes. However, only one application process exists in memory at any given time.


Figure 1: Concurrency

While running, your application has exclusive control of the CPU and other IO resources, such as graphics and audio. No other processes share these resources with your application.

This state is known as the foreground.

Cooperative Foreground & Background Switching

The Cafe Operating System provides three cores for your game to run on: Core 0, Core 1, and Core 2. The use of those cores depends on whether an application is running in the foreground or the background.

Foreground Operation

An application running in the foreground has access to all three cores as shown in Figure 2.

If your application is requested to leave the foreground, it must explicitly relinquish control of the CPU and other foreground IO resources, and signal its readiness to recede into the background. Conversely, when returning to the foreground, your application must reacquire the resources and handle the transition appropriately.

This explicit, cooperative model improves determinism and simplifies the overall system. See Application Lifecycle for more information.

Background Operation

After your application has responded to a request to leave the foreground by relinquishing its foreground resources and signalling appropriately, your application is in the state known as the background. Your application can still run while in the background, though it no longer has access to any of the foreground resources.

Core 2 is reserved for application threads when in the background. System processes are guaranteed to use only Cores 0 and 1 when in control of the foreground. This means that your application can, for example, maintain a server connection even while the user invokes the HOME Menu and launches the Browser overlay app.

Your application leaves the background when it receives a message that it has reacquired the foreground.


Figure 2: Core Availability

Note that the file system and network stack are the only I/O devices available to the application when running in the background. All other I/O devices have been relinquished to the foreground process.

Foreground & Background Resources

Foreground Resources

The following resources are exclusive to the foreground application. This means that only the foreground application can use these resources. When transitioning to the background, the application must yield these resources so that the new foreground application can use them.

Resource Remarks
Processor The foreground application has full access to all three cores.
Graphics The user interface "focus" follows the foreground application. This means only the foreground application can render graphics to the TV and Wii U GamePad.
Audio The user interface "focus" follows the foreground application. Therefore, only the foreground application can render audio to the TV, Wii U GamePad, and Wii remotes.
Controllers The user interface "focus" follows the foreground application. Therefore, only the foreground application can use the controller devices.
Accessories The user interface "focus" follows the foreground application. Therefore, only the foreground application can use secondary controllers such as cameras and microphones.
MEM1 MEM1 is 32 MB of fast memory that is reserved for graphics rendering. Since its use is tied to graphics, it is exclusive to the foreground process.
Foreground Bucket The foreground bucket is an extra 40 MB area in the foreground area of MEM2, above and beyond the 1 GB that is reserved for the main application, that is available when application is running in the foreground.
Locked Cache
  • All Cores
Each Core can have a section of locked cache that can be used to improve performance. The foreground application has access to each Core's locked cache.

The following resources do not automatically handle foreground switches:

Resource Remarks
DMAE The DMAE driver does not automatically handle a foreground switch. It must be stopped and restarted manually when releasing and acquiring the foreground, respectively.
H.264 Decoder / MPEG-4 Demulitplexer The H.264 decoder and MPEG-4 demultiplexer libraries do not automatically handle a foreground switch. Applications need to ensure that functions from these libraries never get called from the background. If the application is exiting either from foreground or background, it is not necessary to call H264DECEnd / MP4DMXEnd or H264DECClose / MP4DMXClose APIs.

Background Resources

The following resources are safe for an application to use when in background. Note that background application threads are restricted to Core 2.

Resource Remarks
Processor A background application only has access to Core 2.
Network Networking is the most common background activity; for example, games may need to maintain a server connection even when in the background.
File System File I/O is also allowed during background; however, developers are strongly encouraged to minimize file activity.
Application Arena The application's entire code and data memory are accessible during background operation.
Locked Cache
  • Core 2
Each Core can have a section of locked cache that can be used to improve performance. The background application has access only to Core 2's locked cache. The locked caches of Cores 0 and 1 are unavailable in the background.

Note that background resources are shared with the foreground process. It is strongly recommended that background network and file I/O activities are minimized to prevent contention with the foreground application. If you have a thread with Core 0 or Core 1 affinity, and your application is transitioning to the background, you should block those threads and pick them up again when you get to the foreground.

Resource Division

When the user presses the HOME Button and selects a system application, the Cafe operating system must divide its resources between the system applications and the game.

Some games require reasonably high processing resources in the background. For example, a network game that assigns a single Cafe system within a networked group of Cafe systems to serve routing and simulation functions. When the user presses the HOME Button to activate the HOME Menu (HBM), the game continues to require processing resources in background mode along with network and file system access.

For more information about the HOME Menu, see Switching to the HOME Menu.

Your application may have an e-manual that uses the e-manual viewer. This viewer is managed by the system and can be started by the user from the HOME Menu. For more information about the e-manual, see Switching to the e-manual

Process Switching Events

In general, the following user-triggered events prompt a process switch:

Event Description
HOME Menu The user has pressed the HOME Button on the Wii U GamePad or Wii remote. Your application must release the foreground and allow the HOME Menu process to run.
Exit Game Request The user wants to exit the game and return to Cafe Menu. This option is provided in the HOME Menu. Your application must handle the exit while running in the background.
Power Off Request The user wants to shut down the system. This option is provided in the HOME Menu; therefore, your application must handle the exit and shutdown event while running in the background.
Direct Overlay App Request Applications can directly invoke certain overlay applications, such as the e-manual reader.
Catastrophic System Error Fatal events invoke the Error process; this is a non-recoverable transition and does not need handling by your application; the process switch is a one-way trip for which the user's only recourse is to power-cycle the system.

These high-level events present themselves as a sequence of one or more system messages, described in the next section.

System Message Queue

Every process has a system message queue; your application is required to poll the queue regularly and handle the events accordingly.

In general, your application must handle the following basic system messages:

Message Remarks
RELEASE_FOREGROUND The application must release the foreground so that another process may acquire the user's attention.
ACQUIRED_FOREGROUND Informs the application that all foreground resources are ready to use.
EXIT The application must prepare to exit for a shutdown or return-to-menu event.
NETIO_CHANGE This is a hint that informs the game - while in background - that the foreground process may use the network stack heavily.
HOMEBUTTON_DENIED The user has pressed the HOME Button while access to the HOME Menu is disabled.
RELEASE_FOREGROUND_SHUTDOWN_FLAG Warns the application that a process switch is being performed to shutdown the system or exit the application.

For explicit details on the handling of these system messages and events, see Application Lifecycle.

See Also

Preparing Your Application
Application Lifecycle
Multicore Processing
System Messages

Revision History

2014/04/11 Added link to 'overlay apps'.
2014/01/21 Terminology change to HOME Menu.
2013/05/08 Automated cleanup pass.
2011/02/21 Initial version.


CONFIDENTIAL