Description of Header Files (NITRO-SDK)


NITRO-SDK System Header

nitro.h This is the definitions file for the NITRO-SDK standard library.
nitro_win32.h This file contains the collection of definitions, such as the variable types unique to NITRO-SDK, that are needed when creating tools on a Windows PC.

These header files must be placed in an include statement in modules that use NITRO-SDK.

Module Initialization Function

nitro/sinit.h This enables use of the module initialization function NitroStaticInit.

This header file is for using the C language static initializer NitroStaticInit().

Place the header file in an include statement in the module that defines the body of NitroStaticInit(). The overlay module's static initializer is started when the overlay is linked. By using this mechanism you can prepare an entry for a pointer to a function so the corresponding function gets registered in NitroStaticInit() when the overlay module is linked.

Switching Between ARM & THUMB Instruction Sets

nitro/code32.h All subsequent code is output as ARM instructions (32-bit code).
nitro/code16.h All subsequent code is output as THUMB instructions (16-bit code).
nitro/codereset.h At compile time, all subsequent code is output as an instruction set, according to the specified options.

The ARM9 and ARM7 CPUs of the NINTENDO DS can use two kinds of instruction sets: ARM instructions and THUMB instructions. You can switch between these two instruction sets with some jump instructions. In C, switching with jump instructions is performed as function calls, so normally the instruction set is selected for each function.

Use code32.h and code16.h by combining with codereset.h. Enclose the function you want the instruction set to be fixed to the ARM with code32.h and codereset.h. Enclose the function you want to be fixed to the THUMB with code16.h and codereset.h. When you are using assembler code, always enclose the function with code32.h or code16.h depending on the instruction set.

#include <nitro/code32.h>     // This outputs the following arm_inst() using an ARM instruction set
int arm_inst(int n)
{
// 32-bit code area return n * n; }
#include <nitro/codereset.h> // The instruction set is restored (as per the compiler options)

Using TCM Memory (TCM section specification)

nitro/dtcm_begin.h
nitro/dtcm_end.h
The code in between is output to the .dtcm section. According to the SDK standard setting, the .dtcm section is placed in ARM9 DTCM (data-use TCM).
nitro/itcm_begin.h
nitro/itcm_end.h
The code in between is output to the .itcm section. According to the SDK standard setting, the .itcm section is placed in ARM9 ITCM (instruction-use TCM).

The NINTENDO DS ARM9 processor has a scratchpad region in CPU (a high-speed buffer region that is fixed in the memory map) called TCM. The region can be accessed as fast as cache in the CPU, so by making better use of this region you can limit the slow-down to processing speed that might otherwise occur due to a cache miss.

When defining the functions you want to place in the TCM region, enclose them with nitro/itcm_begin.h and nitro/itcm_end.h, as shown below. Function regions that are enclosed this way are transferred to the instruction TCM (ITCM) region at startup.

#include <nitro/itcm_begin.h>  //  Place the following tcm_inst() in ITCM
int tcm_inst(int n)
{
    // 32-bit code area
    return n * n;
}
#include <nitro/item_end.h>    // Return the placement destination to normal

When you want to place a data block in data TCM (DTCM) region, enclose it with nitro/dtcm_begin.h and nitro/dtcm_end.h, as shown below.

#include <nitro/dtcm_begin.h>  // Place the following tcm_data() in DTCM
u32  tcm_data[] =
{
    0, 1, 2, 3, 4, 5, 6, 7, 8, 9
}
#include <nitro/dtem_end.h>    // Returns to placement destination to normal

Specifying Special Sections

nitro/parent_begin.h
nitro/parent_end.h
The code in between gets output to the .parent section. This is used during a clone boot operation.
nitro/version_begin.h
nitro/version_end.h
The code in between gets output to the .version section. Do not use this section; it is reserved in the NITRO-SDK library.
nitro/wram_begin.h
nitro/wram_end.h
The code in between is output to the .wram section. This is enabled only in the ARM7.

There are also other special sections besides TCM sections.

The .parent section is essential for clone boot, which is one form of DS Download Play. For details, read the section about clone booting in the document that explains DS Download Play ($NitroSDK/docs/TechnicalNotes/AboutMultiBoot.pdf).

The .version section and the .wram section are used internally in the NITRO SDK implementation, so there is no need to be careful when using them.

NITRO-SDK Version Information

nitro/version.h This is the NITRO-SDK version information.

This defines the NITRO-SDK version information.