You are on page 1of 22

Quickstart Guide for the Revolution

Development Environment
(for Revolution SDK)
Version 3.1

The content of this document is highly confidential


and should be handled accordingly.

© 2006-2008 Nintendo RVL-06-0045-001-G


CONFIDENTIAL Released: May 1, 2008
Quickstart Guide Revolution SDK

Confidential
These 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 Nintendo


Released: May 1, 2008 CONFIDENTIAL
Revolution SDK Quickstart Guide

Contents
1 Overview.............................................................................................................................................. 6
2 System Requirements ......................................................................................................................... 7
3 Hardware .............................................................................................................................................8
3.1 System Firmware....................................................................................................................... 8
4 Preparing Software ............................................................................................................................. 9
4.1 Obtaining Cygwin....................................................................................................................... 9
5 Connecting Hardware........................................................................................................................10
6 Installing Software .............................................................................................................................14
6.1 Cygwin .....................................................................................................................................14
6.2 NDEV Software........................................................................................................................14
6.3 CodeWarrior ............................................................................................................................14
6.4 Revolution SDK .......................................................................................................................15
6.5 Configuration of Environment Variables ..................................................................................15
6.6 Invoking Revolution Shell ........................................................................................................16
7 Running a Demo................................................................................................................................17
8 Building Code ....................................................................................................................................19
9 Troubleshooting.................................................................................................................................20

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

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

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

© 2006-2008 Nintendo 3 RVL-06-0045-001-G


CONFIDENTIAL Released: May 1, 2008
Quickstart Guide Revolution SDK

Revision History

Date Items
Revision No. Description
Revised (Chapter)

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 a


reference layout.

6.1 Changed the make version from 3.80 to 3.80.1.

6.2 Changed section headings. Revised content to match the latest


NDEV software.

6.4 Added a note.

7 Added a description to a note, concerning the display


configuration 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." Updated


contents.

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 the


Revolution 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 from


WarioWorld.

6.3 Revised documents to be referenced to indicate appropriate


documents as regards the method of using separate IDE
settings.

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.

RVL-06-0045-001-G 4 © 2006-2008 Nintendo


Released: May 1, 2008 CONFIDENTIAL
Revolution SDK Quickstart Guide

Date Items
Revision No. Description
Revised (Chapter)

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 corresponding


changes 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 the
different 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 Bluetooth
module.
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.

© 2006-2008 Nintendo 5 RVL-06-0045-001-G


CONFIDENTIAL Released: May 1, 2008
Quickstart Guide Revolution SDK

1 Overview
This document describes how to connect NDEV, install drivers and the Revolution SDK, update system
firmware, and build and run code.
No installer is provided with the Revolution SDK. Instead, developers copy the relevant directories to their
own 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 a
minimum of intrusive system settings. The Revolution SDK is designed to co-exist with other Nintendo
development 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 is
the case, you must install the appropriate firmware version on the Wii development hardware
before running applications.

RVL-06-0045-001-G 6 © 2006-2008 Nintendo


Released: May 1, 2008 CONFIDENTIAL
Revolution SDK Quickstart Guide

2 System Requirements
The Nintendo Revolution Development Environment runs on x86-compatible computers with Microsoft
Windows 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

Communications Three USB 2.0 ports (managed by the host controller)


Support
One RS-232 communications port

© 2006-2008 Nintendo 7 RVL-06-0045-001-G


CONFIDENTIAL Released: May 1, 2008
Quickstart Guide Revolution SDK

3 Hardware
The 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 Revolution
applications.
Note: For maximum performance, we strongly recommend that you plug the USB interfaces directly into
the 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 system
memory 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, we
refer to the leftmost number (X) as the major version and to the other numbers (Y and Z) as the minor
version. It is possible to install multiple firmware versions on a single Wii console if their major versions are
different. For example, both 9.2.4 and 17.2.0 can be installed. When installing firmware with a higher minor
version that has the same major version, the previous firmware will be overwritten. It is not possible to
install 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 will
be used.
Note: From Revolution SDK 3.1 on, it is possible to store the firmware used by the application on the
disc and to automatically upgrade the version upon startup. For more information, refer to the
Revolution Mastering Tools makemaster package.

RVL-06-0045-001-G 8 © 2006-2008 Nintendo


Released: May 1, 2008 CONFIDENTIAL
Revolution SDK Quickstart Guide

4 Preparing Software
The Revolution Development Environment requires several software components. Download the software
in Table 4-1 from www.warioworld.com.

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

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 obtaining
the setup program (a file named setup.exe). Within the program, you will be presented with a choice of
packages 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.81
available from the Cygwin site does not support DOS-style path expressions, it cannot be used for builds in
the Revolution development environment. Instead, use GNU make 3.80.1, which runs under the latest
Cygwin 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.

© 2006-2008 Nintendo 9 RVL-06-0045-001-G


CONFIDENTIAL Released: May 1, 2008
Quickstart Guide Revolution SDK

5 Connecting Hardware
Figure 5-1 shows the rear panel of the NDEV system.
Figure 5-1 NDEV System: Rear

SENSOR BAR
LABEL
S/N

AV MULTI OUT

USB3 (DI)

USB2 (COM)
SERIAL
USB1 (DEBUG)

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 serial
port on the rear of the NDEV system. You can monitor debug output on this port using a terminal
program on the PC such as TeraTerm (not included). Default settings for this communications channel
are 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 the
toolbar's settings. When Terminal is selected, the last item listed above can be changed. Settings for
both sending and receiving Japanese characters should be SJIS. This can be changed when Terminal
is 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. Connect
this 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 Bluetooth
module (set to wireless when shipped). As shown in the following figures, set the switch to the right
when using the wired module, and to the left when using the wireless module. Be sure to toggle
switches only while NDEV power is Off.
A serial number label is attached on the back, in the upper left corner.

RVL-06-0045-001-G 10 © 2006-2008 Nintendo


Released: May 1, 2008 CONFIDENTIAL
Revolution SDK Quickstart Guide

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)

© 2006-2008 Nintendo 11 RVL-06-0045-001-G


CONFIDENTIAL Released: May 1, 2008
Quickstart Guide Revolution SDK

Figure 5-4 NDEV Front Panel

Note: The controller ports on the front of the NDEV are ordered from right to left. Leave the DIP
switches 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 being
connected to. (This is set during registration.) Note that the wired Wii Remote and wired controller hub
should be connected after turning NDEV power Off.

RVL-06-0045-001-G 12 © 2006-2008 Nintendo


Released: May 1, 2008 CONFIDENTIAL
Revolution SDK Quickstart Guide

Figure 5-6 Right Panel of NDEV

© 2006-2008 Nintendo 13 RVL-06-0045-001-G


CONFIDENTIAL Released: May 1, 2008
Quickstart Guide Revolution SDK

6 Installing Software
6.1 Cygwin
The Revolution SDK build system requires the Cygwin bash shell and developer tools. Ensure that you
have 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 information
later.
Ensure that you have installed version 3.80.1 of make. Open a shell and type the following command.

% make --version
GNU Make 3.80
Copyright (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 Software


1. 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, Connecting
Hardware.
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 the
driver the second and third time. Navigate to the same directory, ND-Drivers-XXXXXX/, in each case
and select the given driver.
Note: The NDEV development environment is only officially supported on Windows XP SP2.

6.3 CodeWarrior
1. 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 of
your CodeWarrior installation. This batch file will register the COM components of the Codewarrior
IDE.
If CodeWarrior for Nintendo DS, or for some other platform, is already installed, its IDE configuration may
be in use. If you want separate IDE configurations for each installation, refer to the section “Using Separate
IDE Configurations” in Developer_Notes - Revolution_Tools.txt, which is included with
CodeWarrior.

RVL-06-0045-001-G 14 © 2006-2008 Nintendo


Released: May 1, 2008 CONFIDENTIAL
Revolution SDK Quickstart Guide

6.4 Revolution SDK


1. 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 variables
later.
In addition, you must install the appropriate firmware version before running programs. The appropriate
console firmware version is given in the Readme files of the Revolution SDK and the patches that are
used. Do not refer to the Revolution SDK’s Readme file when you install a patch; refer to that patch’s
Readme file instead and install firmware as necessary.
Note: When SDK patches are released, install the patch before using the SDK. Bug fixes and other
issues 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 a
text editor and find the section marked “Please specify your installation paths here:”.
Code 6-1 RVL NDEV.bat
@echo off

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

SET REVOLUTION_SDK_ROOT=C:\RVL_SDK
SET CWFOLDER_RVL=C:\CW_RVL
SET CYGWIN_PATH=C:\cygwin

You must change the items in red to match installation directories for each component.
Table 6-1 Configuring Installation Paths
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.

Note: All paths must be in MS-DOS format.


The ndrun command may fail to execute when a double quotation mark (") is included in the
PATH environment variable. In this case, the double quotation mark must be deleted from the
PATH environment variable.

© 2006-2008 Nintendo 15 RVL-06-0045-001-G


CONFIDENTIAL Released: May 1, 2008
Quickstart Guide Revolution SDK

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 not
permanent, and they will not affect the rest of your system. Thus, you can support multiple platforms (such
as 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.

RVL-06-0045-001-G 16 © 2006-2008 Nintendo


Released: May 1, 2008 CONFIDENTIAL
Revolution SDK Quickstart Guide

7 Running a Demo
1. 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 communication
channel 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 is
installed. If you have installed your SDK elsewhere, modify the example accordingly. Note that the
emulation 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 issuing
the 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 of
DvdRoot.

Note also that the disc emulator requires MS-DOS style paths. When invoking this command, you may
need 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 dialog
box will appear the first time you open a single elf file. This is to be expected. When opening a
single elf file for the first time, the CodeWarrior IDE turns off file caching and pre-build options in
the IDE settings.

© 2006-2008 Nintendo 17 RVL-06-0045-001-G


CONFIDENTIAL Released: May 1, 2008
Quickstart Guide Revolution SDK

In addition, clear the Run with CWComUtil option. CWComUtil does not offer complete support
for 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. By
default, CWComUtil is called first when running programs or debugging. However, its use is not
necessary, 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, select
Environment Settings, then Debugger, and then GCN Debugger Global Settings. In the dialog
box, clear the Minimize script window check box. When the ndrun_prechecker check called
by ndrun results in a “WARNING,” it will wait for key input; this will not be shown unless the script
window is configured to be displayed.

RVL-06-0045-001-G 18 © 2006-2008 Nintendo


Released: May 1, 2008 CONFIDENTIAL
Revolution SDK Quickstart Guide

8 Building Code
To 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 the
Programmer’s Guide.

© 2006-2008 Nintendo 19 RVL-06-0045-001-G


CONFIDENTIAL Released: May 1, 2008
Quickstart Guide Revolution SDK

9 Troubleshooting
Use the following steps to perform a check if the NDEV is used to start an application, but the TV screen is
blank.
Figure 9-1 Process to Check an Application when It Has Started but the TV Screen Is Blank

The application has started


but nothing is shown on
the TV screen.

The NDEV will not operate if it is not


Is the NDEV connected to N
connected to a PC. Connect the NDEV to
the PC?
the PC.
Y

Is there an NNGC USB


The PC does not recognize the NDEV.
Device item in the
Check whether the USB cable is properly
Windows Device Manager, N
connected.
with three devices under it
If there is nothing wrong with the
(see the image on the
connection, try installing an updated
right)?
version of the NDEV software.
Y

Does the NDEV software N


Install the latest NDEV software.
include the latest version?

N Can the DEVKIT System N N Something in the NDEV is


Does debugging output
Is the Wii Menu installed? Menu be displayed when broken. It must be sent in for
stop at “Last shutdown …”
the NDEV is turned on? repairs.

Y Y Y

Uninstall the Wii Menu. Power-cycling the NDEV or


running ndstop may fix this.

Does the smp-onetri.elf It is unlikely that the application is at fault, but to be safe,
Are operations normal with N Y
demo program, included check its implementation. If the cause of the bug is still
the Wii Menu uninstalled?
with the SDK, run? unknown, send the NDEV in for repairs.

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

Is “Apploader ……”
This condition occurs when an application goes beyond
displayed to the screen at Y
the 9MB Apploader restriction. You must fix your
startup while the Wii Menu
implementation to follow the restriction.
is not installed?

There may be a problem with


the NDEV, so you should send
it in for repairs.

RVL-06-0045-001-G 20 © 2006-2008 Nintendo


Released: May 1, 2008 CONFIDENTIAL
Revolution SDK Quickstart Guide

Use the following steps to perform a check when NDEV is used to start an application and debugging
information is not shown.
Figure 9-2 Process to Check an Application when It Sstarts but Debugging Information Is
Not Shown

Are the NDEV and PC N Connect the NDEV and PC with a


connected by a serial
serial cable.
cable?
Y

Have you configured the N Refer to Chapter 5 Connecting


terminal that will display Hardware and configure the terminal
serial output? software.
Y

Y Debugging information will not be output


Is the Wii Menu installed?
when the Wii Menu is installed.

Is the DEVKIT menu’s boot Y Change this to DEVELOPMENT;


mode set to debugging information will not be
“PRODUCTION”? output for PRODUCTION.
N

The NDEV may be damaged.


Send it in for repairs.

© 2006-2008 Nintendo 21 RVL-06-0045-001-G


CONFIDENTIAL Released: May 1, 2008
Quickstart Guide Revolution SDK

© 2006-2008 Nintendo
The contents of this document cannot be
duplicated, copied, reprinted, transferred,
distributed or loaned in whole or in part
without the prior approval of Nintendo.

RVL-06-0045-001-G 22 © 2006-2008 Nintendo


Released: May 1, 2008 CONFIDENTIAL