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.
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.
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.
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.
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.
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.
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.
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.
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.
|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.|
||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:
|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
The following resources are safe for an application to use when in background. Note that background application threads are restricted to Core 2.
|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.|
||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.
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
In general, the following user-triggered events prompt a process switch:
|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.
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:
||The application must release the foreground so that another process may acquire the user's attention.|
||Informs the application that all foreground resources are ready to use.|
||The application must prepare to exit for a shutdown or return-to-menu event.|
||This is a hint that informs the game - while in background - that the foreground process may use the network stack heavily.|
||The user has pressed the HOME Button while access to the HOME Menu is disabled.|
||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.
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.