SDK Release Notes us

December 19, 2001

CONFIDENTIAL

NINTENDO GAMECUBE Release Notes

SDK Version 1.0 (Install Image 12-Dec-2001)

OTE

: Due to frequent changes in the development of the NINTENDO GAMECUBE prototype hardware, many versions

of the hardware exist concurrently. Scheduling considerations require that we cut new SDK releases on a daily basis. In
order to keep track of release notes under such circumstances, we’ve dated the release notes to track them by the relevant
SDK installation image. A release note issue affects all SDK installation images cut on and after the date of the note.

Contents

NINTENDO GAMECUBE Release Notes

December 19, 2001

CONFIDENTIAL

December 19, 2001

NINTENDO GAMECUBE Release Notes

CONFIDENTIAL

NINTENDO GAMECUBE Release Notes

December 19, 2001

CONFIDENTIAL

Note 234: Fixed OS ROM font functions

(12-Dec-2001)

Previously,

OSGetFontTexel()

and other OS font functions would sometimes return random character widths if the

specified character string included invalid codes. This bug has been fixed. The OS font functions now evaluate invalid
character codes as a ‘wide space’ character.

Note that the NINTENDO GAMECUBE ROM font includes only JIS Level-1 Kanji.

Note 233: GCN SDK date stamp

(12-Dec-2001)

A macro constant has been added to the

dolphin.h

header file:

#define __SDKVER__ “<DayMonthYear>”

The string

__SDKVER__

will contain the date of the SDK build. For example: “

12Dec2001

”.

This facilitates identification of the SDK used in a particular build of an application.

Note 232: MAKEBANNER2.EXE for European IPL

(12-Dec-2001)

The European IPL accepts two types of ‘

opening.bnr

’ file formats:

BNR1

and

BNR2

The

BNR1

format is used in the US/JPN IPL. The

BNR2

format is new and contains text for six different languages

(English, German, French, Spanish, Italian, and Dutch).

The

BNR2

file format is defined as the

DVDBanner2

structure in the following header file:

<dolphin>/include/dolphin/dvd/dvdbanner.h

A new command-line tool (

makebanner2.exe

) has been added for creating ‘opening.bnr’ files of type

BNR2

Note 231: WARNING: Sample rate of DVD audio streams

(12-Dec-2001)

Please note that hardware audio streams from the optical disc are actually played at a sample rate of 48,043 samples per
second, rather than 48KHz. While this difference is practically inaudible, it may cause problems if you attempt to
synchronize the streamed audio with a very long movie or cut-scene.

Note 230: Batch-file versions of SDK tools

(12-Dec-2001)

The following batch files have been added to support those who do not wish to use the Cygwin bash shell:

•

setcountrycode.bat

•

setdollimit.bat

•

setpadspec.bat

•

setsmemsize.bat

•

showsettings.bat

•

supportlongfilename.bat

December 19, 2001

NINTENDO GAMECUBE Release Notes

CONFIDENTIAL

Note 229: SI and EXI libraries added

(12-Dec-2001)

To facilitate support of future serial (SI) and expansion interface (EXI) peripherals, the SI and EXI functions have been
separated into discrete libraries. Note that these functions were previously integrated within the OS library.

Please ensure that your application links the new SI and EXI libraries (

si[D].a

and

exi[D].a

Furthermore, please note that a new function,

SISetSampleRate()

, obsoletes the

PADSetSamplingRate()

function. Please see the corresponding MAN pages for details.

Note 228: Corrections to CARD MAN pages

(12-Dec-2001)

The CARD library MAN pages have been corrected with respect to the

CARD_RESULT_IOERROR

return code. In general,

CARD_RESULT_IOERROR

can be returned by any CARD function that modifies memory card sectors. The only exception

is for

CARDMount[Async]()

, which can also return

CARD_RESULT_IOERROR

for broken memory cards.

Note that CARD functions which only read sectors will never return this error code.

The following is a list of revised MAN page entries:

•

CARDCheck[Ex][Async]

// can return IOERROR

•

CARD[Fast]Delete[Async]

// can return IOERROR

•

CARDRename[Async]

// can return IOERROR

•

CARDSetAttributes[Async]

// can return IOERROR

•

CARDSetStatus[Async]

// can return IOERROR

•

CARDRead[Async]

// never return IOERROR

Note 227: Modified card.h

(12-Dec-2001)

The following macro constants have been added to

#define CARD_XFER_SETATTRIBUTES

(1 * 8 * 1024) // CARDSetAttributes[Async]

#define CARD_XFER_WRITE

(1 * 8 * 1024) // CARDWrite[Async]

The

CARDWrite[Async]()

function writes an extra

CARD_XFER_WRITE

bytes to the memory card in addition to the

user-specified length of data when updating the time field of the memory card directory entry.

The

CARDSetAttributes[Async]()

also writes

CARD_XFER_SETATTRIBUTES

bytes to the memory card in

order to update the directory entry of the specified file.

Note that the

CARDGetXferredBytes()

MAN page has been updated to reflect these changes.

Note 226: Using C++ global constructors in relocatable modules

(12-Dec-2001)

The introductory MAN page of the relocatable module system has been updated to describe how to invoke global C++
constructors and destructors from each relocatable module through the use of module prolog and epilog functions.

Note that the makefile for

reldemo

has also been updated to directly link “

global_destructor_chain.c

” from

the Metrowerks Standlard Library (MSL) source tree. This ensures that the _epilog function calls every global destructor of
the module.

NINTENDO GAMECUBE Release Notes

December 19, 2001

CONFIDENTIAL

Note 225: GX_NO_LEGACY_HW1 compile flag used in GXEnum.h

(12-Dec-2001)

A check for the non-existence of this flag was added around obsolete HW1-related enumerations (used in

GXTevColorArg

and

GXTevAlphaArg

). Thus, if you define

GX_NO_LEGACY_HW1

, the obsolete enumerations will

no longer be defined. In the default SDK build environment, this flag is not defined (and thus the obsolete enumerations are
stil present).

Note 224: Added new versions of bootmode.elf and videomode.elf

(12-Dec-2001)

New versions of

bootmode.elf

and

videomode.elf

allow you to interactively set the boot mode and video mode,

respectively, on-screen.

The executable

videomode.elf

also detects the console IPL version and does not switch to PAL mode automatically if

the IPL version is “DEVKIT BOOTROM v0.93a” or earlier, or if the IPL is for the NPDP reader.

Note 223: VI library bug fix

(12-Dec-2001)

We have fixed a bug that only occurs in MPAL versions of games. Since the bug only occurred in MPAL, there is no need
to revise a Japanese build of your game; however, US versions should use the latest version of VI so that they can support
both NTSC and MPAL properly.

Note 222: Modified Gekko BAT register configuration

(12-Dec-2001)

Previously, the Gekko

DBAT0

and

IBAT0

registers were used to establish the cached main memory region starting from

0x80000000

. The

DBAT0

and

IBAT0

lengths were configured to 256MB to support both 24MB and 48MB boards.

However, this configuration allowed Gekko to perform out-of-order load operations and instruction prefetches beyond the
24MB/48MB main memory spaces, which led to unwanted memory protection errors. The operating system has been
modified to configure

BAT

registers to cover only the 24MB or 48MB main memory space (as determined by the

setsmemsize

command setting) using

DBAT0

IBAT0

DBAT2

and

IBAT2

Note that

DBAT1

is used for non-cached main memory region, and

DBAT3

is used for the locked cache.

Due to this modification, memory protection errors are most likely to be raised from Flipper units like

DSP

etc. unless you manually set protection regions via

OSProtectRange()

The

apploader[D].img

files have been updated to reflect this fix.

Note 221: OS error handler mechanism revised

(12-Dec-2001)

Previously, the operating system assumed that the application would shut down the game immediately after calling the user
specified error handler set by

OSSetErrorHandler()

. This specification has been changed: Now by simply returning

from the error handler, the operating system tries to continue the program execution. In addition, the thread scheduler is
disabled while the error handler is running. Threads will be rescheduled after the error handler completes its function.

Note 220: Record of last interrupt

(12-Dec-2001)

To facilitate debugging, the OS has been modified to record information about the last interrupt handled by Gekko. Three
user-accessible global variables have been added to the operating system:

•

__OSLastInterrupt

December 19, 2001

NINTENDO GAMECUBE Release Notes

CONFIDENTIAL

•

__OSLastInterruptTime

•

__OSLastInterruptSrr0

These variables record the type of interrupt, the tick value, and the

SRR0

interrupt was taken.

Note 219: New memory card utilities: rformat.elf and corrupt.elf

(12-Dec-2001)

The executable

rformat.elf

will format the memory card to a different region without rebooting the dev-kit. The

executable

corrupt.elf

will apply various types of corruption to memory cards.

These utilities facilitate debugging and testing of game applications with respect to card management.

Please see the corresponding MAN page entries for more details.

Note 218: NR disc verification tool

(12-Dec-2001)

The NR disc verification tool (“NR disc checker”) has been integrated into the apploader. Please refer to the “NR disc
verification tool” section under the “Tools” MAN pages for more details.

Note that in order to use the NR disc verification tool you will need a special controller which is distributed by Nintendo
separately.

Note 217: New OS functions: OSGetLanguage() and OSSetLanguage()

(12-Dec-2001)

European Gamecubes reserve a single byte for the default language setting in NVRAM. The new OS functions

OSGetLanguage()

and

OSSetLanguage()

provide access to this configuration byte. Please see the corresponding

MAN page entries for more details.

Note 216: OS semaphore functions added

(12-Dec-2001)

We’ve added semaphore functions to the OS library. Please refer to the semaphore section under ‘Thread Synchronization’
in the OS MAN pages for details. Note that for mutual exclusion, a mutex is better than a semaphore since a mutex can
perform the priority inheritance protocol for superior real-time response.

Note 215: Added MAN pages for HIOExit() and MCCExit()

(12-Dec-2001)

MAN pages have been added for

HIOExit()

and

MCCExit()

Note 214: OSResetSystem() has been modified

(12-Dec-2001)

OSResetSystem() has been modified to make it not perform compiler recalibration in case OS_RESET_SHUTDOWN is
specified. In any other cases, OSResetSystem() performs controller recalibration by default.

NINTENDO GAMECUBE Release Notes

December 19, 2001

CONFIDENTIAL

Note 213: EURGB60 mode is now supported

(12-Dec-2001)

A new video mode called EURGB60 is now supported. For more information about this mode, see the document
“vi.us.pdf”. Note that this change has introduced new

GXRenderModeObj

entities such as

GXEurgb60Hz480Int

and

GXEurgb60Hz480IntDf

. Please see the

VIConfigure()

MAN page for more details.

Note 212: GXSetDispCopyYScale bug fixed, added new functions

(12-Dec-2001)

We have fixed a bug in

GXSetDispCopyYScale()

which sometimes caused the function to return an incorrect value

for the number of lines actually copied to the external frame buffer (XFB).

There was also a small problem with an input argument that roughly calculated float value causing calculation errors. To
solve this, we’ve added a new convenience function called

GXGetYScaleFactor()

which computes an accurate Y-

scale factor. We also added the function

GXGetNumXfbLines()

which calculates the number of XFB lines without

sending any commands into the graphics processor.

Note 211: Better quality for PAL non-interlaced display

(12-Dec-2001)

The PAL non-interlaced mode register setting has been changed slightly so that the image quality is better.

Note 210: GX texture-coordinate scaling issue fixed

(12-Dec-2001)

Previously, if a TEV stage used a non-null texture map but a null texture coordinate (because the texture coordinate was
coming from an indirect texture stage), inappropriate texture coordinate scaling could take place. This issue has been fixed.

Note 209: DEMOStats operation fixed

(12-Dec-2001)

Previously,

DEMOStats

would not necessarily show the right results, depending upon the sequence of the performance

counters requested. This has been fixed.

Note 208: GX TRIANGLE performance counters fixed

(12-Dec-2001)

The

TRIANGLE

performance counters in GX should now return the correct results. Previously, they were counting

multiple command words per triangle.

Note 207: Graphics Display List library (GD) added

(12-Dec-2001)

We've added the GD library, a toolkit for creating and modifying display lists containing graphics state commands, to the
NINTENDO GAMECUBE SDK. The library can be compiled and run on both the NINTENDO GAMECUBE as well as
the host PC, allowing display lists to be easily constructed in the tool chain and loaded from a file for use during runtime.
GD is considered an advanced API; you should be thoroughly familiar with GX before proceeding to GD. Please refer to
“Graphics Display List Library (GD)” in the NINTENDO GAMECUBE Graphics Programmer’s Guide for more
information.

Note 206: New OS library functions

(12-Dec-2001)

The following functions have been added to the OS library.

December 19, 2001

NINTENDO GAMECUBE Release Notes

CONFIDENTIAL

•

EXIProbe()

•

EXIProbeEx()

•

EXIGetType()

•

EXIGetTypeString()

Please refer to the corresponding pages in the Dolphin Reference Manual (HTML) for details.

Note 205: New CARD library functions

(12-Dec-2001)

The following new functions have been added to the CARD library:

•

CARDGetAttributes()

•

CARDGetSerialNo()

•

CARDSetAttributes()

•

CARDSetAttributesAsync()

Please refer to the corresponding pages in the Dolphin Reference Manual (HTML) for details.

Note 204: CARD callback functions can now access FPU registers

(12-Dec-2001)

Previously, CARD callback functions were not allowed to touch FPU registers. We have changed this specification so that
now you can touch FPU registers inside CARD callback functions. However, developers should still be careful not to
process time-consuming tasks (like other callbacks) in the handlers.

Note 203: HIO callback functions can now access FPU registers

(12-Dec-2001)

Previously, HIO callback functions were not allowed to touch FPU registers. We have changed this specification so that
now you can touch FPU registers inside HIO callback functions. However, developers should still be careful not to process
time-consuming tasks (like other callbacks) in the handlers.

Note 202: Support for Cygwin b20, Cygwin 1.3.2, GNUPro

(12-Dec-2001)

We have revised the make system to support Cygwin b20, GNUPro for GBA, and Cygwin 1.3.2 natively.

To use the make system properly, add

c:\cygwin\bin

(assuming you've installed Cygwin on your C drive) to the

Windows

PATH

environment variable. For example, edit

cygwin.bat

to insert a line such as:

SET PATH=c:\cygwin\bin;%PATH%

Note that the Cygwin installer does not set the

PATH

automatically.

Note that the SDK does indeed support the use of Cygwin 1.3.3 and later. However, you must revise the

DOLPHIN_ROOT

environment variable to use a standard MS-DOS path. So if you are using Cygwin 1.3.3 or later, please change the
environment variable from:

DOLPHIN_ROOT=//c/DolphinSDK1.0

NINTENDO GAMECUBE Release Notes

December 19, 2001

CONFIDENTIAL

To:

DOLPHIN_ROOT=C:\DolphinSDK1.0

Note 201: Fixed SI[PAD]SetSamplingRate() in progressive video mode

(12-Dec-2001)

In the previous release, the controller sampling rate was not set correctly in progressive video mode (i.e., when the Graphics
Processor does not perform controller sampling in the second half of every video frame). The OS, SI, PAD, and VI libraries
have been revised to fix this bug. Note that you do not have to specify the sampling rate again when changing the current
video mode.

Note 200: PADSetSamplingCallback() CPU delay eliminated

(12-Dec-2001)

Previously, if standard and WaveBird controllers were used together with

PADSetSamplingCallback()

, under

interrupts disabled there would be a delay in CPU cycles of about 30 microseconds before the user-specified callback
function was called. This delay in CPU cycles has been eliminated.

Note 199: Bug fixed in modulerules

(12-Dec-2001)

In the previous release, executing “

make clobber

” for certain libraries accidentally clobbered other libraries. The

clobber rule has been fixed.

Note 198: Fixed CARD listdemo

(12-Dec-2001)

Previously,

listdemo

would not show the same icon animation pattern as the IPL if the memory card file contained

CARD_STAT_ICON_NONE

in the middle of the animation sequence. This bug in

$DOLPHIN_ROOT/build/demos/carddemo/src/cardutil.c

has been fixed. By using

CARD_STAT_ICON_NONE

in the middle of the animation sequence, you can create a slow animation pattern such as the

one in “Luigi’s Mansion.”

Note 197: Added OS_RESET_SHUTDOWN for OSResetSystem()

(12-Dec-2001)

OSResetSystem()

now has a third mode which only shuts down all devices/threads/etc., except for the thread running,

and then returns. Because of this change, we’ve changed the type of the first argument from

BOOL

int

. This shouldn't

affect anything because

BOOL

is a

typedef

int

. Please refer to the

OSResetSystem()

page in the Dolphin

Reference Manual for more details.

Note 196: Fixes and modifications to audio system

(12-Dec-2001)

The following bugs have been fixed in the audio libraries:

•

Previously, the

sndconv.exe

tool would sometimes calculate end addresses for sound effects incorrectly, resulting

in intermittent pops and clicks for “one-shot” sound effects. This has been fixed.

•

A spurious static definition in the ar.h header file caused an error with the SN Systems ProDG compiler suite. This has
been fixed.

December 19, 2001

NINTENDO GAMECUBE Release Notes

CONFIDENTIAL

•

Previously, the definition of the field “

sound

” in “

SPSoundTable

” was an incomplete C-type definition. The GNU

C compiler, being quite strict, would generate an “

incomplete type

” error. The

sp.h

header file has been

changed to correct this problem.

•

We’ve corrected some definitions in

axfx.h

related to the maximum and minimum values for effect parameters.

•

Type definitions for the

AXART

library have also been corrected for ProDG users.

•

Previously, the

DSPTOOL

dynamic-link library would fail to free allocated memory, causing a ‘heap-creep’ problem.

This has been fixed.

•

The

DLS1WT

converter tool has been modified to properly parse output from Microsoft Direct Music Producer 2.5.1.

•

The

soundfile

dynamic-link library has been revised to properly parse AIFF fields as PASCAL strings instead of C

strings. Previously, the library would assume that strings were NULL-terminated, which is not necessarily the case for
AIFF chunks. This problem most frequently manifested itself as incorrect loop markers.

•

Previously, the

DSPADPCM

tool would parse backslashes in the command line as option switches. This has been

corrected.

The following enhancements have been made to the audio libraries:

•

A new function,

void ARClear(u32 flag)

, has been added to the AR library. This function will clear the region

of ARAM as specified by

flag

. Note that this function uses the low-level AR DMA functions; the user is therefore

responsible for ensuring that no other AR or ARQ traffic is pending. This function is intended only for debugging.
Please see the AR MAN pages for more details.

Note 195: Dolby and Roland license information

(12-Dec-2001)

Licensing information for use of Dolby Prologic audio encoding and/or the Roland general MIDI instrument set was
inadvertently excluded from previous SDKs. These can now be found on the distribution CD under:

Docs\License\

Note 194: Bug fixed in makerel.exe

(12-Dec-2001)

In the 8-Sept-2001 SDK release,

makerel.exe

would generate

.plf

files whose alignment constraints were set to 0

rather than 1 if the specified

.plf

files did not contain

.bss

sections, etc. The

OSLink()

function fails if alignment

constraints are set to 0; therefore,

makerel.exe

has been fixed to set the alignment constraints for

.plf

files to at least

Note 193: MTX library revision

(12-Dec-2001)

We found a function-definition bug in the new MTX44 extension portion of the MTX library. There were also some
incorrect argument type declarations. These bugs were fixed.

Furthermore, we have fixed a minor problem in which some paired-single calculations in the MTX library could
inadvertently cause divide-by-zero exceptions.

Note 192: Fixed Gekko performance monitor bit define names

(12-Dec-2001)

Certain performance monitor bit define names are now undefined in

because they are

not valid on the Gekko CPU (they are only valid on PowerPC 750). These performance monitor bit define names are:

•

MMCR0_PMC1_IC_FETCH_MISS

•

MMCR0_PMC2_PR_SWITCH

•

MMCR0_PMC3_PM_SWITCH

•

MMCR1_PMC4_DC_MISS

NINTENDO GAMECUBE Release Notes

December 19, 2001

CONFIDENTIAL

Note 191: BUG: OS default OS_ERROR_PROTECTION error handler

(12-Dec-2001)

In the current debug version of the OS library, once an

OS_ERROR_PROTECTION

error is incurred and no user error

handler has been specified by

OSSetErrorHandler()

, the OS default memory protection error handler causes another

DSI or other exception.

Note 190: Directory-independent samplebuild makefile

(8-Sept-2001)

The

/dolphin/build/samplebuild/sample/makefile

has been modified to be directory-independent. The

clobber rule in the moderules file was slightly modified to avoid clobbering demos in the

/dolphin/HW2/bin/demos

directory.

Note 189: Caution: PADSetSamplingCallback()

(8-Sept-2001)

Currently, if standard controllers and WaveBird controllers are used together with

PADSetSamplingCallback()

there is a 30 microsecond CPU delay before the user specified callback function is called. This will be rectified in a future
patch or release.

Note 188: CARD man pages

(8-Sept-2001)

Man pages for some of the CARD utility macros have been added. Please see the Dolphin Reference Manual for details.

Note 187: More CARD demos

(8-Sept-2001)

Three CARD demos have been added to demonstrate how to create icon, banner, and comment information. See

create-

1icon

create-8icon

, and

create-bnr-4icon

. Please see the Dolphin Reference Manual for details.

Note 186: DVD errors & warnings

(8-Sept-2001)

This release contains various bug fixes for error handling on the part of the DVD library. In addition, it includes a demo
and documentation for error handling. Please use these to make proper error handlers for final games.

Note 185: Fixed .rel file

(8-Sept-2001)

There was a problem where a

.rel

file output by the

makerel

tool would contain garbage data the size of the

.bss

section. Because of this bug,

makerel

would halt some

.plf

files with an irrelevant error message (such as “

Write:

ins. disk space

” when there was in fact enough room on the disk). This problem has been fixed.

Note 184: Improved CARD API response time

(8-Sept-2001)

In previous releases,

CARDWrite[Async]

could take at most about 130 seconds for each 8KB block until the function

returned

CARD_RESULT_IOERROR

CARD_RESULT_READY

for a worn-out memory card. The other functions that

modify memory card blocks (including

CARDCreate[Async]

CARD[Fast]Delete[Async]

CARDMount[Async]

CARDFormat[Async]

CARDSetStatus[Async]

CARDRename[Async]

, and

December 19, 2001

NINTENDO GAMECUBE Release Notes

CONFIDENTIAL

CARDCheck[Async]

) could also take a few minutes until they completed their operations. The CARD library has been

improved to return

CARD_RESULT_IOERROR

CARD_RESULT_READY

within about 8.4 seconds for each 8KB block.

Note 183: OS functions added

(8-Sept-2001)

We’ve added

OSResetSystem()

and

OSGetResetCode()

to the OS library. Please see the Dolphin Reference

Manual for details.

Note 182: DVD function added

(8-Sept-2001)

We’ve added

DVDCheckDisk()

to the DVD library. Please see the Dolphin Reference Manual for details.

Note 181: VI function added

(8-Sept-2001)

We’ve added

VIGetDTVStatus()

to the VI library. Please see the Dolphin Reference Manual for details.

Note 180: Auto mode problem in progressive mode fixed

(8-Sept-2001)

Previously, there was a problem in progressive mode where the aspect ratio changed from time to time if the TV was set to
“auto mode.” This bug has been fixed.

OTE

: Because of this fix, the image is shown in progressive mode two lines lower than before. This should correct a

previous situation where the top two lines shown in interlace mode did not appear in progressive mode.

Note 179: Bug in DVDCancel* fixed

(8-Sept-2001)

We found a bug in

DVDCancel*

that generates a fatal error if it’s issued at a certain time. When this problem occurs, the

DVD library stops responding for 10 seconds, then generates the fatal error. Although we think this bug occurs only rarely,
we wanted to eliminate the possibility and so have modified the DVD library accordingly.

With this change, read speed is impacted when audio streaming is played and/or the read size is longer than 512KB. There
is no effect on read speed otherwise.

Note 178: Debugger stepping problem and the DTK library

(8-Sept-2001)

Previously, using the DTK library while stepping through code could cause the application to crash. This is because some
subsystems of the audio streaming hardware will continue to run even after a breakpoint, resulting in timing problems.
DTK has been modified to accommodate this.

Note 177: Apploader revision

(8-Sept-2001)

It was possible that the apploader could cause some problems during the boot process if the size of the FST exceeded
128KB. This problem has been fixed.

You can check the FST size by simply checking the arenaHi address, which is passed to the serial output at the beginning
of the game. You will see two “

Arena : 0xXXXXXXXX – 0xYYYYYYYY

” messages for each run of the game; the

second one shows the arena for the game. If the address on the right is higher than 0x817e0000 (or 0x82fe0000 on a 48MB

NINTENDO GAMECUBE Release Notes

December 19, 2001

CONFIDENTIAL

system), the FST size is smaller than 128KB. If the FST for the game is smaller than 128KB, you don’t need this new
apploader.

Note 176: Matrix-Vector library updates

(8-Sept-2001)

We have added more paired-single versions of existing functions, as well as some new quaternion operation functions. In
addition, we have added some 4x4 matrix operation functions as extensions for special-purpose usage. You can access them
by including an extra header file. For details, please refer to the relevant pages in Dolphin Reference Manual.

In addition, some matrix functions have been changed to macros that switch between C and paired-single code, depending
on the

DEBUG

settings. You may need to recompile code that depends on the previous Matrix-Vector libraries.

Note 175: OSInit now clears entire arena

(8-Sept-2001)

OSInit()

, which is called in

__start

, now zeroes out the entire arena after powering on the console. Due to this

change,

OSInit()

also clears the entire arena by default after restarting, and as a result, doesn't preserve the area

[0x8070_0000, 0x8120_0000)

anymore. If you call

OSSetSaveRegion()

before

OSResetSystem()

, you

can change this behavior, as noted in Note 179.

Note 174: New USB man pages

(8-Sept-2001)

The Dolphin Reference Manual now contains function descriptions for the HIO, FIO, MCC, and TTY API. Additional
information on the USB adapter libraries may be found in SDK documentation under

//…/PDF/SDK1.0/USB adapter/USB_Comm_Lib.us.pdf

Note 173: New GCN binary tool: videomode.elf

(8-Sept-2001)

The

videomode.elf

tool has been merged into the SDK under

$DOLPHIN_ROOT/HW2/bin/tools

. Currently,

videomode.elf

switches the DEVKIT video mode between NTSC and MPAL; PAL is not yet supported. Please refer

to the relevant page in the Dolphin Reference Manual for details.

Note 172: OSAlarm handler can now access FPU registers

(8-Sept-2001)

Previously,

OSAlarm

handlers have not been allowed to touch FPU registers, but this specification has been changed. Now

you can touch FPU registers in

OSAlarm

handlers just like in other device callbacks. However, developers should still be

careful not to process time-consuming tasks (like other callbacks) in the handlers.

Note 171: OSResetSystem() (restart) no longer saves memory by default (8-Sept-2001)

When using OSResetSystem() to restart, please note that this function no longer saves the memory content

[0x8070_0000, 0x8120_0000)

by default. We have added two new APIs,

OSSetSaveRegion()

and

OSGetSaveRegion()

, to change this default behavior. Please refer to the relevant pages in the Dolphin Reference

Manual for details.

Using

OSSetSaveRegion()

, you can specify where in the area

[0x8070_0000, 0x8120_0000)

you want to

save. We have fixed a bug in the previous version of

OSResetSystem()

that would overwrite

[0x8100_0000,

0x8120_0000)

. Although this area gets cleared due to the default behavior change of

OSResetSystem()

, if you

want you can specify, for example, the entire

[0x8070_0000, 0x8120_0000)

by using

OSSetSaveRegion()

December 19, 2001

NINTENDO GAMECUBE Release Notes

CONFIDENTIAL

Note 170: VI color alternating bug fixed

(8-Sept-2001)

In the previous release, there is a bug in which calling

VIConfigure()

to change the VI mode after

VIFlush()

can

cause a “VI color alternating” problem (as reported in the newsgroup). This bug has been fixed.

Note 169: Relocatable module file version 2

(8-Sept-2001)

The version number of the relocatable module file has been extended to 2. Now the

OSModuleHeader

structure contains

align

and

bssAlign

members. These indicate memory alignment constraints for the relocatable module and the

bss

section, respectively.

OSLink()

now checks the alignment constraints at runtime. You can also inspect the relocatable

module file header on your PC by using the new

reldump.exe

command line tool (provided under

/X86/bin

A new page called “Alignment Requirements for Relocatable Modules” has been added to the Dolphin Reference Manual.

Note the new OS library is backward-compatible. You can use the previous

makerel.exe

command line tool, if

necessary, to generate version 1 relocatable module files.

Note 168: Memory protection function has been added

(8-Sept-2001)

We have added a new OS function,

OSProtectRange()

. Function details are available in the Dolphin Reference

Manual.

OSProtectRange()

raises a new OS error,

OS_ERROR_PROTECTION

, that can be captured by the handler

installed by

OSSetErrorHandler()

. In addition, main memory access from the end of the main memory address

(24MB or 48MB as set by the

setsmemsize

command) to 64MB will also raise an

OS_ERROR_PROTECTION

error.

Note 167: PADSetSamplingCallback() function has been added

(8-Sept-2001)

A new PAD library function,

PADSetSamplingCallback()

, is available. You can set a callback function to be called

every time the Graphics Processor completes controller data sampling at the rate specified by

PADSetSamplingRate()

. The use of

PADSetSamplingCallback()

is illustrated in the following new demo

program:

/dolphin/build/demos/paddemo/src/sampling.c

Note 166: SIProbe() function has been added

(8-Sept-2001)

A new OS library function,

SIProbe()

, is now available. You can inspect what type of controller is currently attached to

the specified controller port. Details are available in the Dolphin Reference Manual (HTML).

Note 165: Two OSResetSystem bugs fixed

(8-Sept-2001)

Two OSResetSystem bugs have been fixed.

•

In the first bug, two system static variables named "Header" and "Prepared" were declared globally by mistake.

•

The second bug involved the possibility of restart not working properly when the invalidation mode was “manual” (see

DVDSetAutoInvalidation()

for more details about the invalidation mode).

NINTENDO GAMECUBE Release Notes

December 19, 2001

CONFIDENTIAL

Note 164: GP hang diagnosis added to DEMO library

(8-Sept-2001)

We’ve added new functionality to the DEMO library to enable it to detect and attempt to determine the cause of GP hangs.
To enable this feature, simply call the function

DEMOEnableGPHangWorkaround()

. This function used to be called

DEMOEnableBypassWorkaround()

; we’ve changed its name to more accurately reflect its purpose. With the

workaround enabled,

DEMODoneRender()

will detect GP hangs and then call another function to determine the cause.

Note that GP hang diagnosis requires the use of the GP hardware performance counters; thus you cannot use the
performance counters to count other metrics while hang diagnosis is enabled. We’ve provided source code for the setup
and diagnosis routines, so you may incorporate this functionality into your own code without having to use the DEMO
library framework.

Note 163: CARD library fixes

(8-Sept-2001)

In previous releases, this library could leave a corrupted file on the memory card if the card was removed from the console
while game data was being saved to it. The corrupted file would be inaccessible from the IPL menu. This bug has been
fixed.

In addition, we recommend removing any previously-created memory card files that do not have icons from the IPL
memory card screen.

Note 162: Bug fix for makerel.exe

(8-Sept-2001)

In the previous release, if the

.rel

file specified in the command line argument did not require any relocation information

to be generated (i.e., it did not refer to any external symbol, etc.), then

makerelD.exe

(debug version) could be aborted

by an assertion failure like “

Assertion failed: sizeof(OSImportInfo) * ImpCurrent <= ImpSize

”.

Likewise, the non-debug version of

makerel.exe

could generate a broken

.rel

file in the same case. This bug has

been fixed.

Note 161: New AX Sound Pipeline tools and libraries

(8-Sept-2001)

We've created a new set of libraries and tools to illustrate how to import and manage sound effects using AX. Please refer
to SoundPipeline.us.pdf for more information. Note that many of the AX demo programs have been revised to use this
pipeline. Full source code has been provided for the Sound Pipeline tools and libraries for your amusement.

Note 160: SEQ and SYN libraries

(8-Sept-2001)

We’ve revised the

SEQAddSequence()

and

SYNInitSynth()

APIs by adding the zeropBuffer parameter to pass the

start offset of the “zero buffer” in ARAM to SYN.

Note 159: Modified CARDProbeEx()

(8-Sept-2001)

In previous releases,

CARDProbeEx()

would return

CARD_RESULT_NOCARD

if no memory card was attached, or if the

operating system was still probing the specified slot. We’ve now modified

CARDProbeEx()

to return

CARD_RESULT_BUSY

while the operating system is probing the memory card slot. This state will change to the

appropriate slot state in a few hundred milliseconds. (Note that

CARDProbe()

returns

FALSE

if no memory card is

attached, or if the OS is still probing the specified slot.)

December 19, 2001

NINTENDO GAMECUBE Release Notes

CONFIDENTIAL

Note 158: PAD library fixed

(8-Sept-2001)

Previously, the PAD library would—on rare occasions—fail to calibrate the X-axis of the Control Stick (i.e., the left-hand
joystick) correctly. Specifically, the control stick would considerably drift from its origin to the left. This problem has been
fixed.

Note 157: Added function DVDFastOpenDir

(8-Sept-2001)

We’ve added a new DVD function called

DVDFastOpenDir()

. This is the fast version of

DVDOpenDir()

, in the same

way that

DVDFastOpen()

is for

DVDOpen()

. (In fact,

DVDOpenDir()

has been modified a bit to behave in a similar

fashion to

DVDOpen()

. When the specified directory cannot be found,

DVDOpenDir()

now prints out a warning and

returns

FALSE

in both the debug and release versions of the library.)

Please refer to the Dolphin Reference Manual for more details.

Note 156: Fixed bug in makerel.exe

(8-Sept-2001)

In previous releases,

makerel.exe

might resolve external symbols to the wrong places under certain situations (e.g., if

multiple relocatable modules called each others’ functions). This bug has been fixed.

Note 155: Man pages for BI2 scripts

(8-Sept-2001)

We’ve added manual pages for the so-called BI2 scripts (

setcountrycode

setpadspec

, etc.). You can find them in

the “Tools” section of the Dolphin Reference Manual (HTML).

Note 154: Fixed bug in OSResetSystem()

(8-Sept-2001)

OSResetSystem()

has a bug where the function would not disable the locked cache inside. If an application called

OSResetSystem()

with

/reset/ == OS_RESET_RESTART

while the locked cache was enabled, the game would

start with the locked cache enabled, which is not the same as cold-booting the game. To work around this problem,
applications had to call

LCDisable()

before calling

OSResetSystem()

This bug is now fixed and it is no longer necessary to call

LCDisable()

before calling

OSResetSystem()

Note 153: Modified PADRead() return value

(8-Sept-2001)

PADRead()

has been modified to return an OR-ed bit mask (

PAD_CHANn_BIT

) of the controllers that support rumble

motors.

Note 152: CARDStat.commentAddr restriction

(8-Sept-2001)

To correctly show the 64-byte comment block on the GAMECUBE IPL memory card screen, the comment block, specified
by

stat->commentAddr

CARDSetStatus[Async]

, must not cross any 8KB file boundaries (i.e., the comment

block must fit into one of the 8KB blocks in the file.

NINTENDO GAMECUBE Release Notes

December 19, 2001

CONFIDENTIAL

Note 151: Fixed GX wide point/clipping problem

(8-Sept-2001)

Drawing a wide point or line (width > 240) at the left edge of the guardband would previously wrap across the screen. This
has been fixed. Note that you may still encounter the problem if you shift your viewport off the screen (xOrig < 0 or yOrig
< 0). You can avoid doing this by using

GXSetScissorBoxOffset()

instead.

Note 150: Modified CARDSetStatus[Async]

(8-Sept-2001)

CARDSetStatus()

and

CARDSetStatusAsync()

will not accept a value for iconAddr (in the

CARDStat

structure)

that is greater than or equal to

CARD_READ_SIZE

. The value of iconAddr must be set to 0xffffffff (i.e., no icon) in any

case where it would otherwise be greater than or equal to

CARD_READ_SIZE

. This is necessary so that the game banner

and icons may be displayed on the production IPL memory screen.

Note 149: Fixed CARDRead[Async]

(8-Sept-2001)

In previous releases, there was a bug where the

CARDRead()

and

CARDReadAsync()

functions might complete their

operation before reading all of the specified length of data from the file, if the specified file offset was not aligned with the
memory card sector size boundary. This problem has been fixed.

Note 148: Fixed CARDCheckAsync() semantics

(8-Sept-2001)

In previous releases, if the memory card file system did not have any consistency problems,

CARDCheckAsync()

would

immediately return

CARD_RESULT_READY

and the specified callback function would not be called.

We have fixed

CARDCheckAsync()

to always call the specified callback function if the return value of

CARDCheckAsync()

CARD_RESULT_READY

. Note that all the CARD asynchronous functions now invoke user-

specified callbacks if the function’s return value is

CARD_RESULT_READY

Note 147: GCN binary tools

(8-Sept-2001)

The following three binary tools have been merged into the SDK under

$DOLPHIN_ROOT/HW2/bin/tools

•

bootmode.elf

switches DEVKIT boot mode (production or development).

•

erase.elf

erases the specified memory card sector.

•

zero.elf

zero-clears all memory card sectors.

Please refer to the relevant pages in the Dolphin Reference Manual for details.

Note 146: GX verification system improved

(8-Sept-2001)

The GX verification system, which is activated by the

GXSetVerifyLevel()

, is now more accurate. Warning messages

are stated more clearly than in previous releases. Also, a list of all the possible warning messages has been added to

GXSetVerifyLevel()

in the Dolphin Reference Manual.

Note 145: GXInitTexObjCI bug fixed

(8-Sept-2001)

A bug in

GXInitTexObjCI()

set the wrong filter mode by default if mipmapping was on. This might have caused

broken textures when using mipmapped CI textures. The bug has been fixed.

December 19, 2001

NINTENDO GAMECUBE Release Notes

CONFIDENTIAL

Note 144: VI library fixed

(8-Sept-2001)

The following changes have been made to the VI library:

•

Fixed the internal register settings for the progressive mode.

•

Fixed a bug in VISetBlack() in progressive mode.

•

Modified library so that applications need no longer call __VIInit.

Please delete

__VIInit()

from now on.

VIConfigure()

can properly set progressive mode.

Note 143: Fixed OSGetResetSwitchState()

(8-Sept-2001)

In the production console, electrical noises in the controller port lines can generate a false reset button input to the graphics
chip.

OSGetResetSwitchState()

has been fixed to reject such false reset button inputs. Note that this means you

should not use

OSSetResetCallback()

to detect a console reset button push in a game program.

Note 142: OSGetProgressiveMode() and OSSetProgressiveMode()

(8-Sept-2001)

The NINTENDO GAMECUBE console reserves one bit in its NVRAM for the default video mode configuration
(interlace/progressive).

OSGetProgressiveMode()

and

OSSetProgressiveMode()

provide the access to this

configuration bit. Please refer to “Video Guidelines” and the Dolphin Reference Manual (HTML) for more details.

Note 141: GXReadBoundingBox and GXPoke commands altered

(8-Sept-2001)

GXReadBoundingBox()

and the various

GXPoke

commands can now be called at any point in time. Previously, the

library prevented you from calling these between

GXBegin()

and

GXEnd()

, but that also prevented you from calling

these functions during interrupts.

Note 140: XF Stall Bug work-around altered

(8-Sept-2001)

We’ve slightly altered the workaround for the XF Stall Bug. The previous version was inserting dummy vertices more
often than necessary. This has been fixed.

Note 139: Directory access APIs added for USB2EXI adapter libraries

(8-Sept-2001)

The following APIs have been added for the USB2EXI adapter libraries:

•

FIOOpenDir()

•

FIOCloseDir()

•

FIOReadDir()

•

FIOGetDirSize()

Note 138: MCCStreamRead/Write enhancement

(8-Sept-2001)

In the previous release, there was a restriction that

MCCStreamRead/Write

could only be called once between

MCCStreamOpen()

and

MCCStreamClose()

. This restriction no longer exists, and applications can call multiples of

MCCStreamRead/Write

between

MCCStreamOpen()

and

MCCStreamClose()

NINTENDO GAMECUBE Release Notes

December 19, 2001

CONFIDENTIAL

Note 137: Various bug fixes on USB2EXI adapter libraries

(8-Sept-2001)

We have fixed various bugs in the USB2EXI adapter libraries, including:

•

Initialization would fail when

HIOInit()

was called after

HIOExit()

had been called on host side.

•

Target side

FIOFprintf()

would print one character more than intended, adding a “

” at the end.

•

In certain cases, initialization of the host side MCC/FIO APIs would fail.

•

In certain cases, the host side

MCCClose()

would fail.

Note 136: makerel.exe generates full pathnames in .str file

(8-Sept-2001)

For better debugger support, the

makerel.exe

tool now generates the full pathnames of the relocatable modules to the

module string table file.

Note 135: PAD library fixed

(8-Sept-2001)

In the previous release of the PAD library, other serial port devices (such as Game Boy Advance) could interfere with the
controller hot-plug operation (via

PADReset()

, etc.). This bug was hard to notice if only standard controllers were in

use. This bug has been fixed.

Note 134: CARD library fixed

(8-Sept-2001)

The previous release of the CARD library could hang if the memory card was removed from the slot while the mount
operation was in progress. This bug has been fixed.

In the previous release of the CARD library,

CARDMount()

and

CARDGetResultCode()

, running after

CARDMountAsync()

, may return

CARD_RESULT_NOCARD

inappropriately. This bug has been fixed.

Note 133: Setting disc country code

(8-Sept-2001)

We have added a new script called

setcountrycode

to allow you to set the country code for the optical disc.

Depending on which country (Japan or US) the game is for, run

setcountrycode [jp | us]

to set the proper country code for the disc.

Note 132: New function in MIX library

(8-Sept-2001)

We have added

MIXSetSoundMode()

so that an application can mix sounds in MONO or STEREO. In MONO mode,

the pan attenuation is ignored, and signals are distributed equally to left and right.

Note 131: DSPADPCM and DSPTOOL fixes

(8-Sept-2001)

We've made the following fixes since the 22 May 2001 release of the SDK:

•

The

End

address for single-shot sounds was not computed correctly. This has been fixed.

•

WAV files with copyright information in the header sometimes caused DSPADPCM to hang. This has been fixed.

•

Sometimes, the loop-end address of an ADPCM-encoded sample would be calculated incorrectly. This problem would
manifest itself as noise or unexpected loop behavior during playback. This has been fixed.

December 19, 2001

NINTENDO GAMECUBE Release Notes

CONFIDENTIAL

•

DSPADPCM would report two extra nibbles when the number of samples was a multiple of 14. This has been fixed.

•

We've added a new function to the DSPTOOL.DLL:

getNibblesForNSamples()

. This function returns the

number of nibbles for ADPCM-encoded samples (including ADPCM headers)

•

Sometimes, DSPADPCM would cause a GPF when attempting to read AIFF sound files. This bug has been fixed.

Note 130: PAD clamp zones finalized

(8-Sept-2001)

Pad clamp zones have been finalized for the final production controller. The final pad clamp zones are:

FINAL

Before

PADClamp()

After

PADClamp()

Control Stick

(15, 87) - (55, 55) - (87, 15)

(0, 72) - (40, 40) - (72, 0)

C-Stick

(15, 74) - (46, 46) - (74, 15)

(0, 59) - (31, 31) - (59, 0)

Trigger

30 – 180

0 - 150 (max)

5/22 SDK

Before

PADClamp()

After

PADClamp()

Control Stick

(15, 89) - (67, 67) - (87, 15)

(0, 74) - (52, 52) - (74, 0)

C-Stick

(15, 89) - (67, 67) - (87, 15)

(0, 74) - (52, 52) - (74, 0)

Trigger

16 - 156

0 - 140 (max)

The

PADClamp()

function has also been updated.

Note 129: Fixed PADRead()

(8-Sept-2001)

In the 22-May-2001 release of the SDK,

PADRead()

may repeatedly return a

PAD_ERR_TRANSFER

error if the

PADStatus

array was not statically allocated. This bug has been fixed.

Note 128: AX library changes

(8-Sept-2001)

We've made the following changes to AX since the 22 May 2001 release of the SDK:

•

Previously,

AXSetVoiceMix()

failed to update the mixing parameters correctly. This has been fixed.

•

The mode

AX_MODE_STEREO_HRTF

has been removed for the time being.

•

We've added an

ASSERTMSG

for the case is which

AXSetVoicePriority()

called with a priority of 0. Priority 0

voices belong to the free stack. You must use

AXFreeVoice()

to send voices to this stack in order to ensure that the

voice's parameters are reset correctly.

•

In previous releases, there was a race condition in which AX and the DSP could become unsynchronized. This problem
would manifest itself under extreme (and hopefully unrealistic) conditions, such as when the AX user callback takes a
very long time to complete (on the order of milliseconds). AX would continue to run, but the DSP would stop
generating audio. This bug has been fixed.

•

In addition, AX has been revised so that all user callbacks are invoked with interrupts disabled. Interrupts were
previously enabled during user callbacks, which is a violation of the DolphinOS callback handling policy. The AXFX
effects library and AXDEMO programs have been revised to reflect this. The MIX, SEQ, and SYN libraries are
unaffected.

NINTENDO GAMECUBE Release Notes

December 19, 2001

CONFIDENTIAL

Note 127: Stricter checks of loading address in apploader

(8-Sept-2001)

The new version of apploader now checks the loading address more strictly. On the production system (including the
production mode of devkit bootrom 0.93A or later), no section (including BSS and SBSS) can be placed at a higher address
than

0x8070_0000

. In development mode of devkit bootrom 0.93A or later, no section (including BSS and SBSS) can

be placed at a higher address than

0x8120_0000

. As in previous versions, the apploader checks the 4MB total size

restriction if

setdollimit

is enabled.

Note 126: No support for non-8KB sector memory cards

(8-Sept-2001)

Currently, there is no way for game developers to test their programs with non-8KB sector memory cards. Although
Nintendo may provide large-capacity, non-8KB sector memory cards in future, we cannot support such cards now.
Therefore, Nintendo officially does not recommend that game programs currently under development support non-8KB
sector memory cards.

Game programs should call

CARDProbeEx()

CARDGetSectorSize()

to verify whether the memory card is an

8KB sector card before moving on to further steps. Any game program must support 4-to-128 Mbit memory cards (with
8KB sector size).

**Previous release notes have been incorporated into the relevant NINTENDO GAMECUBE documentation.**