RVL Quick Start Guide 3 1 Us

The content of this document is highly confidential

and should be handled accordingly.

Quickstart Guide for the RevolutionDevelopment Environment

(for Revolution SDK)

Version 3.1

© 2006-2008 Nintendo RVL-06-0045-001-GCONFIDENTIAL Released: May 1, 2008

Quickstart Guide Revolution SDK

ConfidentialThese coded instructions, statements, and computer programs contain proprietary information of Nintendo

of America Inc. and/or Nintendo Company Ltd. and are protected by Federal copyright law. They may not be

disclosed to third parties or copied or duplicated in any form, in whole or in part, without the prior written

consent of Nintendo.

RVL-06-0045-001-G 2 © 2006-2008 NintendoReleased: May 1, 2008 CONFIDENTIAL

Revolution SDK Quickstart Guide

© 2006-2008 Nintendo 3 RVL-06-0045-001-GCONFIDENTIAL Released: May 1, 2008

Contents1 Overview..............................................................................................................................................62 System Requirements .........................................................................................................................73 Hardware .............................................................................................................................................8

3.1 System Firmware.......................................................................................................................84 Preparing Software .............................................................................................................................9

4.1 Obtaining Cygwin.......................................................................................................................95 Connecting Hardware........................................................................................................................106 Installing Software .............................................................................................................................14

6.1 Cygwin .....................................................................................................................................146.2 NDEV Software........................................................................................................................146.3 CodeWarrior ............................................................................................................................146.4 Revolution SDK .......................................................................................................................156.5 Configuration of Environment Variables ..................................................................................156.6 Invoking Revolution Shell ........................................................................................................16

7 Running a Demo................................................................................................................................178 Building Code ....................................................................................................................................199 Troubleshooting.................................................................................................................................20

Code ExamplesCode 6-1 RVL NDEV.bat .........................................................................................................................15

TablesTable 2-1 Operating Environment.............................................................................................................7Table 4-1 Components of Revolution Development Environment .............................................................9Table 6-1 Configuring Installation Paths ..................................................................................................15

FiguresFigure 5-1 NDEV System: Rear...............................................................................................................10Figure 5-2 BT MODE Setting for the Wired Module (Enlarged View of NDEV Rear Panel) ..................11Figure 5-3 BT MODE Setting for the Wireless Module (Enlarged View of NDEV Rear Panel)..............11Figure 5-4 NDEV Front Panel ..................................................................................................................12Figure 5-5 Left Panel of NDEV ................................................................................................................12Figure 5-6 Right Panel of NDEV ..............................................................................................................13Figure 9-1 Process to Check an Application when It Has Started but the TV Screen Is Blank ...............20Figure 9-2 Process to Check an Application when It Sstarts but Debugging Information Is Not Shown .21


Revision History

Revision No.Date

RevisedItems

(Chapter)Description

3.1.0 2008/04/02 All Updated document format.

1 Revised the explanation in a note.

3.1 Added a note.

4.1 Changed the make version from 3.80 to 3.80.1. Added areference layout.

6.1 Changed the make version from 3.80 to 3.80.1.

6.2 Changed section headings. Revised content to match the latestNDEV software.

6.4 Added a note.

7 Added a description to a note, concerning the displayconfiguration of the script window.

9 Added this chapter.

All Corrected notation and other issues.

2.2.2 2006/11/14 All Deleted NDEV version.

3 Updated terminology. Deleted the item "NDEV version."

3.1 Changed heading to "NDEV Points of Difference." Updatedcontents.

4.1 Added description of openssl as reference information.

5 Updated the diagram of NDEV. Updated contents.

2.2.1 2006/10/23 1 Changed written description to refer to Readme from theRevolution SDK and its patch for the NDEV firmware version.

3.2 Same as above.

6.4 Same as above.

3.1 Added 2.2 to supported Revolution SDKs.

4.1 Changed description so that GNU make 3.80 is obtained fromWarioWorld.

6.3 Revised documents to be referenced to indicate appropriatedocuments as regards the method of using separate IDEsettings.

2.2.0 2006/09/28 6.5 Added note about double quotation marks (").

2.2.0 2006/09/19 4.1 Noted that Cygwin version 3.81-1 cannot be used.



2.1.0 2006/08/22 1, 3.2 Added an update to the NDEV firmware.

3.1 Added information on NDEV version 2.1. Made correspondingchanges in table.

Added note regarding Sensor Bar and NDEV combinations.

4.1 Added the names of the files downloaded for setup.

Added a red oval around the button to cycle display of thedifferent views.

Added a description of how to change the make version.

5 Added a description of how to configure for TeraTerm.

Added NDEV 2.1 information on switching the Bluetoothmodule.

Added the USB Controller content when the power is turned on.

6.4 Added notes specific to Revolution SDK 2.1.

1.3.0 2006/06/19 3.1 Added the section "NDEV Version."

5 Updated information for NDEV version 2.x.

7 Updated the name of the directory used.

1.20 2006/04/07 5 Revised the notes about the dip switches.

1.10 2006/03/28 3 Revised some of the hardware description.

5 Indicated the need to use a cross serial cable.

6.6 Added a description of RVL_NDEV.bat.

Indicated that only the bash shell is supported.

7 Changed the demo so that its output is displayed on the screen.

Added notes specific to the CodeWarrior IDE.

1.00 2006/03/14 - First release by Nintendo of America Inc.

Revision No.Date

RevisedItems

(Chapter)Description



1 OverviewThis document describes how to connect NDEV, install drivers and the Revolution SDK, update systemfirmware, and build and run code.

No installer is provided with the Revolution SDK. Instead, developers copy the relevant directories to theirown PC and configure a few environment variables. Device drivers require separate installation.

The goal is to allow the developers to customize the configuration to their own environment, with aminimum of intrusive system settings. The Revolution SDK is designed to co-exist with other Nintendodevelopment platforms, such as that for the Nintendo DSTM system.

Note: By default, Wii development hardware may not have the most recent firmware installed. If this isthe case, you must install the appropriate firmware version on the Wii development hardwarebefore running applications.



2 System RequirementsThe Nintendo Revolution Development Environment runs on x86-compatible computers with MicrosoftWindows XP SP2. The required system specifications are as follows.

Table 2-1 Operating Environment

OS Microsoft Windows XP SP2

CPU Pentium III 1.0 GHz or better

OR an Athlon with equivalent or better performance

Main Memory 512 MB or more

Hard Drive At least 10 GB of free space

CommunicationsSupport

Three USB 2.0 ports (managed by the host controller)

One RS-232 communications port



3 HardwareThe NDEV hardware for the Revolution Development Environment has the following interfaces.

• A USB-based Disc Interface. This enables disc emulation on the developer’s PC.

• A USB-based Debugger Interface. This channel provides debugger control.

• A USB-based Firmware Interface. This channel updates the firmware on the NDEV interface hardware.

• An RS-232 serial-based Terminal Interface. This channel provides terminal output from Revolutionapplications.

Note: For maximum performance, we strongly recommend that you plug the USB interfaces directly intothe host controller of your PC rather than a hub.

3.1 System Firmware

Firmware is built into the Wii console (including development units). This firmware is written to Wii systemmemory and can be upgraded to newer versions.

The firmware version number has the X.Y.Z format, with two periods as delimiters. In this document, werefer to the leftmost number (X) as the major version and to the other numbers (Y and Z) as the minorversion. It is possible to install multiple firmware versions on a single Wii console if their major versions aredifferent. For example, both 9.2.4 and 17.2.0 can be installed. When installing firmware with a higher minorversion that has the same major version, the previous firmware will be overwritten. It is not possible toinstall firmware with a lower minor version that has the same major version.

When running applications, the firmware whose major version was specified at application build time willbe used.

Note: From Revolution SDK 3.1 on, it is possible to store the firmware used by the application on thedisc and to automatically upgrade the version upon startup. For more information, refer to theRevolution Mastering Tools makemaster package.



4 Preparing SoftwareThe Revolution Development Environment requires several software components. Download the softwarein Table 4-1 from www.warioworld.com.

4.1 Obtaining Cygwin

The SDK build system requires GNU Cygnus Tools for Windows (Cygwin).

To obtain Cygwin, go to:http://cygwin.com

Download the latest setup program from one of the listed mirror sites. Note that you will only be obtainingthe setup program (a file named setup.exe). Within the program, you will be presented with a choice ofpackages to install.

The packages provided may vary between sites.

The make utility is required by the SDK build system. Because the latest version of GNU make 3.81available from the Cygwin site does not support DOS-style path expressions, it cannot be used for builds inthe Revolution development environment. Instead, use GNU make 3.80.1, which runs under the latestCygwin environment and is currently distributed on Nintendo’s support site.

Note: When installing the Cygwin package, we recommend that you install it along with the openssl utility(version 0.9.8b-1). The openssl utility is used by the mastering tools and other utilities. For details,see the Revolution Mastering Tools Quickstart Guide.

Table 4-1 Components of Revolution Development Environment

File Description

RVL_SDK-XXXX.zip Revolution SDK package

NDEV-XXXXXX.zip NDEV Software

CW_GCN-3_0_XXXXXX.zip CodeWarrior


http://www.warioworld.com


5 Connecting HardwareFigure 5-1 shows the rear panel of the NDEV system.

Figure 5-1 NDEV System: Rear

1. Ensure that the power is Off.

2. Connect USB cables from your PC to the ports marked USB3 (DI), USB2 (COM), and USB1 (DEBUG)(the three USB terminals circled in red in Figure 5-1).

3. Connect a serial crossover cable (straight through cables cannot be used) from your PC to the serialport on the rear of the NDEV system. You can monitor debug output on this port using a terminalprogram on the PC such as TeraTerm (not included). Default settings for this communications channelare as follows.

115,200 baud.8-bit data.No Parity.One stop bit.Receive/Transmit CR+LF

With TeraTerm, the first four of the above settings can be changed when Serial Port is selected in thetoolbar's settings. When Terminal is selected, the last item listed above can be changed. Settings forboth sending and receiving Japanese characters should be SJIS. This can be changed when Terminalis selected in TeraTerm's toolbar settings.

When turned on, the Device Manager's USB Controller displays one "DI to USB" and two "EXI to USB"strings.

4. Connect the Sensor Bar to the port marked “SENSOR BAR.”

5. The port marked “AV MULTI OUT” provides audio and video output to your television monitor. Connectthis using a cable according to its intended use and the environment in which it will be used.

6. The switch marked "BT MODE" switches between wired and wireless versions of the Bluetoothmodule (set to wireless when shipped). As shown in the following figures, set the switch to the rightwhen using the wired module, and to the left when using the wireless module. Be sure to toggleswitches only while NDEV power is Off.

A serial number label is attached on the back, in the upper left corner.

LABEL

S/N

USB3 (DI)

AV MULTI OUT

SENSOR BAR

USB1 (DEBUG)

USB2 (COM)

SERIAL



Figure 5-2 BT MODE Setting for the Wired Module (Enlarged View of NDEV Rear Panel)

Figure 5-3 BT MODE Setting for the Wireless Module (Enlarged View of NDEV Rear Panel)



Figure 5-4 NDEV Front Panel

Note: The controller ports on the front of the NDEV are ordered from right to left. Leave the DIPswitches on the front panel in the On position.

The NDEV includes an SMA connector for the wired Bluetooth module on the left panel.

Figure 5-5 Left Panel of NDEV

Up to four wired Wii Remotes can be connected by connecting a wired controller hub to the SMA con-nectors marked "BT WIRED." Note that the player number does not depend on the connector beingconnected to. (This is set during registration.) Note that the wired Wii Remote and wired controller hubshould be connected after turning NDEV power Off.



Figure 5-6 Right Panel of NDEV



6 Installing Software

6.1 Cygwin

The Revolution SDK build system requires the Cygwin bash shell and developer tools. Ensure that youhave retrieved the appropriate installation package as discussed in Chapter 4, Preparing Software.

Install the Cygwin package. Make a note of where you installed Cygwin, as you’ll need this informationlater.

Ensure that you have installed version 3.80.1 of make. Open a shell and type the following command.

% make --versionGNU Make 3.80Copyright (C) 2002 Free Software Foundation, Inc.This is free software; see the source for copying conditions.There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

6.2 NDEV Software1. Unzip the contents of NDEV-XXXXXX.zip into a directory of your choice.

2. Ensure that the hardware is connected, but turned Off, as specified in Chapter 5, ConnectingHardware.

3. Go to the ND-Installer-XXXXXX/ directory and run the installation program. Follow the prompts.

4. Turn the system power On.

Windows will recognize the presence of a new device and request a driver.

5. Navigate to ND-Drivers-XXXXXX/ and select a given driver.

Note that there are three USB interfaces between the PC and NDEV system. Windows will request thedriver the second and third time. Navigate to the same directory, ND-Drivers-XXXXXX/, in each caseand select the given driver.

Note: The NDEV development environment is only officially supported on Windows XP SP2.

6.3 CodeWarrior1. Unzip the contents of the CW_GCN_3_0_XXXXXX.zip archive into a directory of your choice. For exam-

ple, C:\CW_RVL.

Make a note of the destination directory. You will need it to configure environment variables later.

2. After the CodeWarrior installer has finished, execute regservers.bat, found in the bin/ directory ofyour CodeWarrior installation. This batch file will register the COM components of the CodewarriorIDE.

If CodeWarrior for Nintendo DS, or for some other platform, is already installed, its IDE configuration maybe in use. If you want separate IDE configurations for each installation, refer to the section “Using SeparateIDE Configurations” in Developer_Notes - Revolution_Tools.txt, which is included withCodeWarrior.



6.4 Revolution SDK1. Unzip the contents of the RVL_SDK-XXXX.zip archive into a directory of your choice.

2. Move the RVL_SDK/ directory to a location that is convenient to navigate from a shell. For example,C:\RVL_SDK.

Again, make a note of the destination directory. You will need it to configure environment variableslater.

In addition, you must install the appropriate firmware version before running programs. The appropriateconsole firmware version is given in the Readme files of the Revolution SDK and the patches that areused. Do not refer to the Revolution SDK’s Readme file when you install a patch; refer to that patch’sReadme file instead and install firmware as necessary.

Note: When SDK patches are released, install the patch before using the SDK. Bug fixes and otherissues are fixed by the patches, so their use is strongly recommended.

6.5 Configuration of Environment Variables

You must now initialize environment variables for the Revolution Development Environment.

Find the file RVL_NDEV.bat, which you extracted from the RVL_SDK-XXXX.zip archive. Open the file in atext editor and find the section marked “Please specify your installation paths here:”.

Code 6-1 RVL NDEV.bat

@echo off

REM ************************************************************REM * Revolution SDK - EnvironmentREM ************************************************************REM *REM * Please specify your installation paths here:REM *REM ************************************************************

SET REVOLUTION_SDK_ROOT=C:\RVL_SDKSET CWFOLDER_RVL=C:\CW_RVLSET CYGWIN_PATH=C:\cygwin

You must change the items in red to match installation directories for each component.

Table 6-1 Configuring Installation Paths

Note: All paths must be in MS-DOS format.The ndrun command may fail to execute when a double quotation mark (") is included in thePATH environment variable. In this case, the double quotation mark must be deleted from thePATH environment variable.

Environment Variable Name Description

REVOLUTION_SDK_ROOT Specify the directory where the SDK is installed.

CWFOLDER_RVL Specify the directory where Codewarrior is installed.

CYGWIN_PATH Specify the directory where Cygwin is installed.



6.6 Invoking Revolution Shell

The batch file RVL_NDEV.bat will initialize these environment variables and invoke a Cygwin bash shell.Run this batch file when building or debugging your work.

Note that the environment settings are local to this shell session (and its children). These settings are notpermanent, and they will not affect the rest of your system. Thus, you can support multiple platforms (suchas Nitro or Nintendo GameCube) on the same PC.

However, there are a few caveats.

• You must invoke only the RVL SDK build system from within this shell. Build systems for other plat-forms are not guaranteed to work.

• The CW IDE/Debugger is Wii-specific and must be invoked from the command line of this shell ses-sion. Type the following to invoke the IDE/Debugger.

% rvl_ide.sh

You may then drag and drop Revolution projects or ELF files into the debugger.

• Only the bash shell is supported.



7 Running a Demo1. Ensure that all USB cables are connected and that the NDEV is powered on.

2. Open a terminal program and confirm that the COM port is properly configured (for communicationchannel settings see Chapter 5, Connecting Hardware).

3. Open a bash shell by double-clicking RVL_NDEV.bat.

4. Next, specify a directory for disc emulation. At the prompt, enter the following.

% setndenv DvdRoot “C:\RVL_SDK\dvddata”

In this example, we are pointing the disc emulator at the dvddata/ directory where Revolution SDK isinstalled. If you have installed your SDK elsewhere, modify the example accordingly. Note that theemulation system is case-sensitive, so ensure that you specify DvdRoot and not dvdroot.

Note that if you inadvertently specify dvdroot instead of DvdRoot, unset the variable first by issuingthe following command without a value.

% setndenv dvdroot

Then re-specify with the desired name, as follows.

% setndenv DvdRoot “C:\RVL_SDK\dvddata”

Note that these NDEV settings will persist across sessions, until you decide to change the location ofDvdRoot.

Note also that the disc emulator requires MS-DOS style paths. When invoking this command, you mayneed to enclose the path in quotes.

You can retrieve the current settings by issuing the following.

% getndenv“DvdRoot” “C:\RVL_SDK\dvddata”

5. Go to:

% cd /cygdrive/c/RVL_SDK/RVL/bin/demos/gxdemo

6. Execute the sample demo program.

% ndrun smp-onetri.elf

The sample demo should then appear on your screen.

Note: When launching a demo in the CodeWarrior IDE, the Preference Modification Warning dialogbox will appear the first time you open a single elf file. This is to be expected. When opening asingle elf file for the first time, the CodeWarrior IDE turns off file caching and pre-build options inthe IDE settings.



In addition, clear the Run with CWComUtil option. CWComUtil does not offer complete supportfor Wii. To clear the option, from the Edit menu, click Environment Settings, then Debugger,then GCN Remote Connection, then Run Settings, and then select Run with CWComUtil. Bydefault, CWComUtil is called first when running programs or debugging. However, its use is notnecessary, as programs can still be run and debugged occur without it.

Configure the script window so that it is displayed. To configure, from the Edit menu, selectEnvironment Settings, then Debugger, and then GCN Debugger Global Settings. In the dialogbox, clear the Minimize script window check box. When the ndrun_prechecker check calledby ndrun results in a “WARNING,” it will wait for key input; this will not be shown unless the scriptwindow is configured to be displayed.



8 Building CodeTo build a single demo, type the following.

% cd /cygdrive/c/RVL_SDK/build/demos/<demo_name>% make

To build a release (non-debug) version, use the following.

% make NDEBUG=TRUE

Build the entire SDK as follows.

% cd /cygdrive/c/RVL_SDK/build% make all

Remove all executable files and binary files, as follows.

% cd /cygdrive/c/RVL_SDK/build% make clobber

For more details on the Revolution SDK, please refer to the Build System document under theProgrammer’s Guide.



9 TroubleshootingUse the following steps to perform a check if the NDEV is used to start an application, but the TV screen isblank.

Figure 9-1 Process to Check an Application when It Has Started but the TV Screen Is Blank

Is the NDEV connected tothe PC?

Y

Is there an NNGC USBDevice item in the

Windows Device Manager,with three devices under it

(see the image on theright)?

N

N

The NDEV will not operate if it is notconnected to a PC. Connect the NDEV tothe PC.

The PC does not recognize the NDEV.Check whether the USB cable is properlyconnected.If there is nothing wrong with theconnection, try installing an updatedversion of the NDEV software.

Y

Does the NDEV softwareinclude the latest version?

N

Y

Is the Wii Menu installed?

Y

N Can the DEVKIT SystemMenu be displayed whenthe NDEV is turned on?

N Does debugging outputstop at “Last shutdown …”

N Something in the NDEV isbroken. It must be sent in forrepairs.

Power-cycling the NDEV orrunning ndstop may fix this.

Y

It is unlikely that the application is at fault, but to be safe,check its implementation. If the cause of the bug is stillunknown, send the NDEV in for repairs.

The application has startedbut nothing is shown on

the TV screen.

Are operations normal withthe Wii Menu uninstalled?

N

Is “Apploader ……”displayed to the screen atstartup while the Wii Menu

is not installed?

Y

Y This condition occurs when an application goes beyondthe 9MB Apploader restriction. You must fix yourimplementation to follow the restriction.

N

There may be a problem withthe NDEV, so you should sendit in for repairs.

Install the latest NDEV software.

Does the smp-onetri.elfdemo program, included

with the SDK, run?

Y

Uninstall the Wii Menu.

Ensure that there were no problems installing the SDKand NDEV software. If there are no problems withthese, there may be an issue with the NDEV hardware,so you should send it in for repairs.

Y

N



Use the following steps to perform a check when NDEV is used to start an application and debugginginformation is not shown.

Figure 9-2 Process to Check an Application when It Sstarts but Debugging Information IsNot Shown

N

N

Y

Y

N

N

Y

Y

Debugging information will not be outputwhen the Wii Menu is installed.

Change this to DEVELOPMENT;debugging information will not beoutput for PRODUCTION.

Connect the NDEV and PC with aserial cable.

Refer to Chapter 5 ConnectingHardware and configure the terminalsoftware.

The NDEV may be damaged.Send it in for repairs.

Are the NDEV and PCconnected by a serial

cable?

Have you configured theterminal that will display

serial output?

Is the Wii Menu installed?

Is the DEVKIT menu’s bootmode set to

“PRODUCTION”?




© 2006-2008 Nintendo

The contents of this document cannot beduplicated, copied, reprinted, transferred,distributed or loaned in whole or in partwithout the prior approval of Nintendo.

Documents

RVL Quick Start Guide 3 1 Us