OS_GetConsoleType

Syntax

#include <nitro/os.h>

u32 OS_GetConsoleType( void );

Arguments

None.

Return Values

A u32-type value that depends on the program's execution environment. Details are provided in Description.

Description

Returns a u32-type value that represents the program's execution environment.

This function is an effective way to automatically switch processes depending on the operating environment. It allows you to create a common program for multiple operating environments.

OS_GetConsoleType is a function for getting the operating environment, not a function for finding out the operating mode. Use the OS_IsRunOnTwl function to find out the operating mode. For example, games for NTR can be played on the NTR as well as the TWL. The program is running in NTR mode in either case, but the hardware it is running on is different (NTR or TWL).

·The OS_IsRunOnTwl function tells you whether the application is running in NTR mode or TWL mode. However, it will not tell you which hardware the application is running on.
With the OS_GetConsoleType function, you can find out whether the application is running on NTR or TWL. However, it will not tell you what the operating mode is.
(Note, however, that if the FINALROM build of a NITRO-only ROM is run on TWL, it returns a value indicating that the software is running on NTR.)

The first time it is called, the OS_GetConsoleType function will survey the devices, memory, and other information to determine its return value, but in subsequent calls, it will just return the same value it returned earlier. As a result, there is hardly any overhead in calling this function.

This function's return values are limited in the FINALROM libraries. When running these builds on something other than the production hardware (such as the debugger), values may be returned that represent environments other than the one being used.



Similar Functions

There is a similar function called OS_GetRunningConsoleType. This function is different in that it will survey the actual hardware and return the appropriate value, even for FINALROM builds.

For example, this difference can be seen by running a TWL FINALROM build on IS-TWL-DEBUGGER. The IS-TWL-DEBUGGER hardware has 32 MB of built-in memory, so the value returned by the OS_GetRunningConsoleType function and OS_CONSOLE_SIZE_MASK is OS_CONSOLE_SIZE_32MB, whereas the value returned by the OS_GetConsoleType function and OS_CONSOLE_SIZE_MASK is OS_CONSOLE_SIZE_16MB.

If either of these functions for getting the operating environment are being left in a FINALROM build, it would be safer to use the OS_GetConsoleType function instead of the OS_GetRunningConsoleType function. The reason is this: Thinking ahead to when this platform is a retail product, the final ROM should only be running on the production hardware, so we want to eliminate the chances of a value that should never occur in the retail product (such as "operating environment is the debugger") being returned. With that in mind, it would probably be best to limit your use of the OS_GetRunningConsoleType function to debugging purposes.



Values That Can Be Obtained

Operating environment:
The logical product (bitwise AND) of the return value and OS_CONSOLE_MASK will take the following values depending on the operating environment.
Value Operating Environment
OS_CONSOLE_TWL Running on an actual TWL console (*1)
OS_CONSOLE_NITRO Running on an actual NITRO system
OS_CONSOLE_TWLDEBUGGER Running on IS-TWL-DEBUGGER (*2)
OS_CONSOLE_ISDEBUGGER Running on IS-NITRO-DEBUGGER
OS_CONSOLE_ENSATA Running on Ensata NITRO Software Emulator
For *1, where the function has determined that the application is running on an actual TWL console, the values will be further broken down based on the logical product with OS_CONSOLE_TWLTYPE_MASK.
That said, you do not normally have to give consideration to OS_CONSOLE_TWLTYPE_DEV. There is no problem with assuming the environment to be an actual TWL console based solely on a return value of OS_CONSOLE_TWL.
Value TWL Hardware Types
OS_CONSOLE_TWLTYPE_RETAIL TWL retail hardware
OS_CONSOLE_TWLTYPE_DEV TWL hardware with a different security key, for development purposes

For *2, where the function has determined that the application is running on IS-TWL-DEBUGGER, the values will be further broken down based on the logical product with OS_CONSOLE_BOARD_MASK.
Value IS-TWL-DEBUGGER Types
OS_CONSOLE_BOARD_A9_A7 Debugger that supports both the ARM9 and ARM7, for component development
OS_CONSOLE_BOARD_A9 ARM9-only debugger, for application development

Devices for Loading Programs:

The logical product (bitwise AND) of the return value and OS_CONSOLE_DEV_MASK will take the following values depending on the device loading the program data.
Value Load Device
OS_CONSOLE_DEV_CARD Load from a Game Card device
OS_CONSOLE_DEV_CARTRIDGE Load from a Game Pak (*3)
OS_CONSOLE_DEV_NAND Load from NAND
OS_CONSOLE_DEV_SDCARD Load from an SD Card
OS_CONSOLE_DEV_MEMORY Load from memory
OS_CONSOLE_DEV_DOWNLOAD Load from a download

*3 The TWL console does not include a Game Pak slot, so this value cannot be obtained on the TWL platform.
Memory Size:

The logical product (bitwise AND) of the return value and OS_CONSOLE_SIZE_MASK will take the following values depending on the size of the implemented memory.
Value Main Memory Size
OS_CONSOLE_SIZE_4MB 4 MB
OS_CONSOLE_SIZE_8MB 8 MB
OS_CONSOLE_SIZE_16MB 16 MB
OS_CONSOLE_SIZE_32MB 32 MB

If a NITRO-only ROM is run on an actual TWL system, the memory size will be 4 MB, regardless of the build type.



Actual Values Due to the Environment or Build

The table below indicates the values that can be obtained with the OS_GetConsoleType and OS_GetRunningConsoleType functions. The logical sum (bitwise OR) of the items in the table is the value obtained. OS_CONSOLE_DEV_xxx will be the value of the device that actually loaded the ROM data.

For NITRO Mode
Operating Environment Build Value of the OS_GetConsoleType Function Value of the OS_GetRunningConsoleType Function Comments
Actual NTR console DEBUG
RELEASE
OS_CONSOLE_NITRO
OS_CONSOLE_DEV_xxx
OS_CONSOLE_SIZE_4MB
OS_CONSOLE_NITRO
OS_CONSOLE_DEV_xxx
OS_CONSOLE_SIZE_4MB
All 4 are
the same.
FINALROM OS_CONSOLE_NITRO
OS_CONSOLE_DEV_xxx
OS_CONSOLE_SIZE_4MB
OS_CONSOLE_NITRO
OS_CONSOLE_DEV_xxx
OS_CONSOLE_SIZE_4MB
Actual TWL unit DEBUG
RELEASE
OS_CONSOLE_TWL
OS_CONSOLE_TWLTYPE_RETAIL

OS_CONSOLE_DEV_xxx
OS_CONSOLE_SIZE_4MB
OS_CONSOLE_TWL
OS_CONSOLE_TWLTYPE_RETAIL

OS_CONSOLE_DEV_xxx
OS_CONSOLE_SIZE_4MB
The only difference is
the OS_GetConsoleType function
for FINALROM builds.
The amount of built-in memory will be
4 MB, regardless of the build.
FINALROM OS_CONSOLE_NITRO
OS_CONSOLE_DEV_xxx
OS_CONSOLE_SIZE_4MB
OS_CONSOLE_TWL
OS_CONSOLE_TWLTYPE_RETAIL

OS_CONSOLE_DEV_xxx
OS_CONSOLE_SIZE_4MB
IS-NITRO-DEBUGGER DEBUG
RELEASE
OS_CONSOLE_ISDEBUGGER
OS_CONSOLE_DEV_xxx
OS_CONSOLE_SIZE_8MB
OS_CONSOLE_ISDEBUGGER
OS_CONSOLE_DEV_xxx
OS_CONSOLE_SIZE_8MB
The only difference is
the OS_GetConsoleType function
for FINALROM builds.
FINALROM OS_CONSOLE_NITRO
OS_CONSOLE_DEV_xxx
OS_CONSOLE_SIZE_4MB
OS_CONSOLE_ISDEBUGGER
OS_CONSOLE_DEV_xxx
OS_CONSOLE_SIZE_8MB
ENSATA EMULATOR DEBUG
RELEASE
OS_CONSOLE_ISDEBUGGER
OS_CONSOLE_DEV_xxx
OS_CONSOLE_SIZE_8MB
OS_CONSOLE_ISDEBUGGER
OS_CONSOLE_DEV_xxx
OS_CONSOLE_SIZE_8MB
The only difference is
the OS_GetConsoleType function
for FINALROM builds.
FINALROM OS_CONSOLE_NITRO
OS_CONSOLE_DEV_xxx
OS_CONSOLE_SIZE_4MB
OS_CONSOLE_ISDEBUGGER
OS_CONSOLE_DEV_xxx
OS_CONSOLE_SIZE_8MB
IS-TWL-DEBUGGER
(For general-purpose development: ARM9)
DEBUG
RELEASE
OS_CONSOLE_TWLDEBUGGER
OS_CONSOLE_BOARD_A9

OS_CONSOLE_DEV_xxx
OS_CONSOLE_SIZE_32MB
OS_CONSOLE_TWLDEBUGGER
OS_CONSOLE_BOARD_A9

OS_CONSOLE_DEV_xxx
OS_CONSOLE_SIZE_32MB
The only difference is
the OS_GetConsoleType function
for FINALROM builds.
FINALROM OS_CONSOLE_NITRO
OS_CONSOLE_DEV_xxx
OS_CONSOLE_SIZE_4MB
OS_CONSOLE_TWLDEBUGGER
OS_CONSOLE_BOARD_A9

OS_CONSOLE_DEV_xxx
OS_CONSOLE_SIZE_32MB
IS-TWL-DEBUGGER
(For component development
ARM9 + ARM7)
DEBUG
RELEASE
OS_CONSOLE_TWLDEBUGGER
OS_CONSOLE_BOARD_A9_A7

OS_CONSOLE_DEV_xxx
OS_CONSOLE_SIZE_32MB
OS_CONSOLE_TWLDEBUGGER
OS_CONSOLE_BOARD_A9_A7

OS_CONSOLE_DEV_xxx
OS_CONSOLE_SIZE_32MB
The only difference is
the OS_GetConsoleType function
for FINALROM builds.
FINALROM OS_CONSOLE_NITRO
OS_CONSOLE_DEV_xxx
OS_CONSOLE_SIZE_4MB
OS_CONSOLE_TWLDEBUGGER
OS_CONSOLE_BOARD_A9_A7

OS_CONSOLE_DEV_xxx
OS_CONSOLE_SIZE_32MB
For TWL Mode
Operating Environment Build Value of the OS_GetConsoleType Function Value of the OS_GetRunningConsoleType Function Comments
Actual TWL unit DEBUG
RELEASE
OS_CONSOLE_TWL
OS_CONSOLE_TWLTYPE_RETAIL

OS_CONSOLE_DEV_xxx
OS_CONSOLE_SIZE_16MB
OS_CONSOLE_TWL
OS_CONSOLE_TWLTYPE_RETAIL

OS_CONSOLE_DEV_xxx
OS_CONSOLE_SIZE_16MB
All 4 are
the same.
FINALROM OS_CONSOLE_TWL
OS_CONSOLE_TWLTYPE_RETAIL

OS_CONSOLE_DEV_xxx
OS_CONSOLE_SIZE_16MB
OS_CONSOLE_TWL
OS_CONSOLE_TWLTYPE_RETAIL

OS_CONSOLE_DEV_xxx
OS_CONSOLE_SIZE_16MB
IS-TWL-DEBUGGER
(For general-purpose development: ARM9)
DEBUG
RELEASE
OS_CONSOLE_TWLDEBUGGER
OS_CONSOLE_BOARD_A9

OS_CONSOLE_DEV_xxx
OS_CONSOLE_SIZE_32MB
OS_CONSOLE_TWLDEBUGGER
OS_CONSOLE_BOARD_A9

OS_CONSOLE_DEV_xxx
OS_CONSOLE_SIZE_32MB
The only difference is
the OS_GetConsoleType function
for FINALROM builds.
FINALROM OS_CONSOLE_TWL
OS_CONSOLE_TWLTYPE_RETAIL

OS_CONSOLE_DEV_xxx
OS_CONSOLE_SIZE_16MB
OS_CONSOLE_TWLDEBUGGER
OS_CONSOLE_BOARD_A9

OS_CONSOLE_DEV_xxx
OS_CONSOLE_SIZE_32MB
IS-TWL-DEBUGGER
(For component development:
ARM9 + ARM7)
DEBUG
RELEASE
OS_CONSOLE_TWLDEBUGGER
OS_CONSOLE_BOARD_A9_A7

OS_CONSOLE_DEV_xxx
OS_CONSOLE_SIZE_32MB
OS_CONSOLE_TWLDEBUGGER
OS_CONSOLE_BOARD_A9_A7

OS_CONSOLE_DEV_xxx
OS_CONSOLE_SIZE_32MB
The only difference is
the OS_GetConsoleType function
for FINALROM builds.
FINALROM OS_CONSOLE_TWL
OS_CONSOLE_TWLTYPE_RETAIL

OS_CONSOLE_DEV_xxx
OS_CONSOLE_SIZE_16MB
OS_CONSOLE_TWLDEBUGGER
OS_CONSOLE_BOARD_A9_A7

OS_CONSOLE_DEV_xxx
OS_CONSOLE_SIZE_32MB




Identifying the Operating Environment in NITRO Mode

When run in NITRO mode, the OS_GetConsoleType function alone cannot determine whether the application is running on a NTR console or a TWL console. This is because not all developers creating NITRO-exclusive ROMs know about TWL. Because NITRO developers who do not know about TWL assume that their NITRO-exclusive ROMs will ultimately only be run on NTR consoles, it would be undesirable for the return value of the OS_GetConsoleType function to be set to a value that indicates their software is running on TWL.

However, there may be times when you absolutely need to distinguish the two. The OSi_IsNitroModeOnTwl function has been created to serve that purpose. If this function returns TRUE, it will indicate that a NITRO-mode ROM is running on TWL. The name of the TWL appears in this function, so it will be handled as a private (undisclosed) function, and an "i" was added to the function name (OSi_).

See Also

OS_IsRunOnDebugger
OS_IsRunOnEmulator
OS_GetRunningConsoleType

Revision History

2008/04/15 Divided the table according to mode.
2008/03/27 Added actual values based on the environment or build.
2007/11/16 Added descriptions.
2007/11/05 Migrated to the OS_GetRunningConsoleType function.


CONFIDENTIAL