Debug (Operating Environment): Overview

# Operating Environment: Overview

## Description

This section explains the API for getting the operating environment and the operating mode.

The TWL-SDK provides functions for getting the current run-time environment. For example, you can use these functions to make determinations if you want to vary the behavior of a NITRO/TWL hybrid ROM depending on which platform it is running on, or if you want to run different code when your application is run on the actual console as opposed to the debugger hardware.

The following functions belong to this category.

> - `OS_GetConsoleType`
> - `OS_GetRunningConsoleType`
> - `OS_IsRunOnEmulator`
> - `OS_IsRunOnDebugger`
> - `OS_IsRunOnTwl`

## Operating Environment and Operating Mode

This section explains the concepts of the operating environment and operating mode.

The operating environment comprises information about the hardware on which a given program is running and information about the hardware type, amount of built-in memory, and boot device. An example of this information would be that the application "was booted from the card bus of an IS-TWL-DEBUGGER that has 32 MB of built-in memory."

- The hardware type will be one of the following: TWL console, DS console, IS-TWL-DEBUGGER, IS-NITRO-DEBUGGER, or Ensata Emulator.
- The amount of built-in memory will be one of the following, depending on the environment: 4 MB, 8 MB, 16 MB, or 32 MB.
- The boot device will be one of the following: Game Card, Game Pak, NAND, SD Card, Memory, or Download.

The operating mode indicates whether a given program is running as a TWL application or as a NITRO application. Accordingly, there are only two operating modes: NITRO mode and TWL mode.

- NITRO-exclusive ROMs can run only in NITRO mode. Even when run on a TWL console unit, they will be running in NITRO mode.
- TWL-exclusive ROMs can run only in TWL mode.
- NITRO/TWL hybrid ROMs may run in NITRO mode at times and in TWL mode at other times.

## Functions to Get the Operating Environment

To determine the operating environment, use the `OS_GetConsoleType` or `OS_GetRunningConsoleType` functions.
The differences between these two functions are shown below.

- In FINALROM builds, the `OS_GetConsoleType` function returns a constant that indicates the fact that the application is a FINALROM build, regardless of which device it is running on.
- The `OS_GetRunningConsoleType` function returns the current operating environment, even for FINALROM builds.

In other words, these two functions differ only when the build type is FINALROM. They will return the same values when the build type is DEBUG or RELEASE.
See the `OS_GetConsoleType` function for details such as the values that can be obtained.

The `OS_IsRunOnDebugger` and `OS_IsRunOnEmulator` functions, which use the values of the `OS_GetConsoleType` function, are also available.

- Use the `OS_IsRunOnDebugger` function to find out whether the operating environment is a debugger.
- Use the `OS_IsRunOnEmulator` function to find out whether the operating environment is the Ensata emulator.

## Functions to Get the Operating Mode

To determine the operating mode, use the `OS_IsRunOnTwl` function. When this function returns `TRUE`, it indicates that the application is running in TWL mode. `FALSE` indicates the application is running in NITRO mode.

- With NITRO-exclusive ROMs, the `OS_IsRunOnTwl` function will return the constant `FALSE`.
- With TWL-exclusive ROMs, the `OS_IsRunOnTwl` function will return the constant `TRUE`.
- With NITRO/TWL hybrid ROMs, the `OS_IsRunOnTwl` function will use information such as the I/O registers to determine the operating mode. Consequently, it will return `TRUE` if it determines the application is in TWL mode, and `FALSE` otherwise.

## See Also

List of OS Functions (Operating Environment)

## Revision History

2008/04/15 Initial version.

CONFIDENTIAL