Install.txt
July 23, 1998


Table of Contents
-----------------

1. Hardware and Software Requirements
2. Katana System Components
3. Installing the Hardware and Drivers
4. Installing the Development Software
5. Flashing the Katana ROMS
6. Using the Codescape Debugger
7. Using GD-ROM Workshop
8. Compiling the Samples
9. Shinobi Initialization


Getting Started with Katana
---------------------------

This document contains material for programmers who are getting started
with the Katana development system.

To get set-up as quickly as possible, follow the procedures detailed in
each chapter, in order.  Start with "Installing the Hardware and
Software" and work through each section culminating in a brief walkthrough
of compiling, debugging, and executing sample code.


1. Hardware and Software Requirements
-------------------------------------

Programming environment:
   - IBM PC compatible running Windows 95, 98, or NT
   - P200 or greater
   - 32 MB of memory
   - 100 MB of free hard drive space
   - Adaptec 2940U PCI-to-Ultra SCSI card dedicated to Katana
   - A second VGA monitor and/or composite TV monitor
   - CD-ROM drive
   - Microsoft Visual C++ v.5.0 with Service Pack 3

Supported art packages:
   - SoftImage v.3.51 & 3.7 for SGI or Windows NT
   - Alias for SGI v.7.5
   - 3D Studio Max R2
   - Lightwave 3D

Note: Do not connect the Katana development system to a SCSI controller
serving other SCSI devices, such as the Windows boot drive.  During the
development process, the debug adapter may lock-up or crash contributing
to timing problems and possible data loss.


2. Katana System Components
---------------------------

You should have received the following components as part of the Katana
development system:

   - Set 4 development tower
   - 50-pin external SCSI cable
   - Katana/Maple controller box
   - Maple connector cable
   - Serial cable
   - Katana Software Development Kit CD-ROM, Release 4
   - Printed documentation for Shinobi, Kamui, and Hitachi dev. tools


3. Installing the Hardware and Drivers
--------------------------------------

Sega recommends Adaptec 2940U (PCI-to-Ultra SCSI) or
2940UW (PCI-to-Wide Ultra SCSI) controllers for use with the Katana
development system.  These controllers have been tested and verified with
both the Cross Products' Debug Adapter (DA) and GD-ROM Emulator (GD-M).

Note: When purchasing a 2940UW, make sure the package includes a 68-pin to
50-pin external adapter.

Although other PCI SCSI controllers may function with the Katana DA,
problems have been identified in the GD-ROM filesystem.  Known cards that
fail to operate properly include Diamond Fireport 20/40s and older
Adaptec ISA 1540/1542s.

The following procedure assumes the use of an Adaptec 2940U controller.

Before installing the Set 4 Katana development system, make sure your
computer has been properly shut-down and that the power cord has been
disconnected from the wall outlet.

1) Remove the outer case from the computer as described in the owner's
   manual.

2) Locate an open PCI slot and remove the protective plate covering the
   opening.  If installing a second SCSI controller, make a note of
   the card location dedicated to the Katana development system.
   (This card may need to be swapped later).

3) Install the SCSI controller according to the instructions provided
   by Adaptec.  Fasten the card in place.

4) Connect the Set 4 to the SCSI controller card using the 50-pin cable
   attached to the unit.

5) Connect the Maple controller box to the port on the back of the Set 4
   labeled "Cont. Box" using the Maple connector cable.  If a Saturn 3D
   analog "Nights" controller is available, insert this into Port A.

6) Connect a VGA monitor to the "VGA Out" port on the back of the Set 4.
   If a TV monitor is available, connect this to either the "Video Out" or
   "S-Video Out" ports.

7) Double-check that the red voltage switch near the Set 4's power cord
   matches your country's electrical rating.  Plug the unit into the
   wall outlet and set the power switch on the back of the case to 1 (on).
   Press the large power button on the front of the Set 4 to boot the
   Katana development system.
   
Note: The button labeled "Reset" has no effect.

8) Wait approximately 15 seconds while the Set 4 completes the power-on
   sequence.  When the hard drive finishes mounting, plug the PC's power
   cord back into the wall outlet and boot the system.

9) As the PC boots, watch the SCSI controller's status information and
   verify that the following devices mount:

   ID 3: CPL KATANA DA
   ID 4: CROSPROD GD-M

10) On some PC's with two SCSI controllers, the Windows boot drive may need
    to be located on the first controller.  If no boot device is found
    after the Katana development system mounts, shut down both computers,
    and swap the SCSI controller cards.  Repeat the installation procedure
    described above.

Note: Do not attempt to modify the default SCSI controller settings unless
absolutely necessary.

11) Windows will auto-recognize the Adaptec 2940U card and load the
    appropriate software.  Follow the instructions provided by Adaptec to
    install the latest "AHA-2940U/AHA-2940UW" SCSI controller drivers.

12) As the system boots, a message should appear stating that an "unknown
    device" has been found.  When the "Update Device Driver Wizard" opens,
    select "Next" to search for a device driver.

13) The hardware wizard should return with the message "Unable to locate a
    driver for this device".  At this point, select "Finish".
    No device driver is necessary for the Katana DA.

14) Once the O/S has finished loading, go to the Windows Control Panel
    and double-click the "System" icon.

15) Click on the "Device Manager" tab and select "View devices by
    connection".

16) Expand the "Plug and Play BIOS" category followed by the "PCI bus"
    device type to reveal the "Adaptec AHA-2940U/UHA-2940UW PCI SCSI
    Controller".

Note: If you installed a second 2940U controller, verify that only
two devices are present.  If a SCSI controller was swapped, multiple
'false' cards may be listed.  In this case, highlight all the
conflicting devices and select "Remove".  Repeat steps 11 through 16.

17) The "Adaptec AHA-2940U/UHA-2940UW PCI SCSI Controller" should show
    the "CPL KATANA DA" and "CROSPROD GD-M" units as mounted (see step 9).
    Select the "Close" button on the Device Manager control panel to
    return to the desktop.

18) The Set 4 system contains a 4 GB hard drive divided into two FAT-16
    formatted partitions (2 GB each).  If you open "My Computer", the
    Katana's internal hard drive partitions should show up as two
    "Removable Disk" drives.  You can read and write files on these drives
    just like any other removable media.

Note: A bug currently exists in Windows NT preventing the second partition
from being seen.

19) Before continuing with the installation procedure, verify that Windows
    is running the latest ASPI drivers from Adaptec.  Locate the following
    files in the Windows\System folder:

    C:\WINDOWS\SYSTEM\WINASPI.DLL
    C:\WINDOWS\SYSTEM\WNASPI32.DLL
    C:\WINDOWS\SYSTEM\APIENUM.VXD
    C:\WINDOWS\SYSTEM\IOSUBSYS\APIX.VXD

    Right click on each file and select "Properties".  Click the "Version"
    tab and verify that the "File version" number is 4.57 (1008).

    The most recent ASPI drivers are available on the Adaptec web site:
    http://www.adaptec.com/support/faqs/aspilayer.html
    Look for the file "Aspi32.exe".

Note: The default Windows 98 ASPI drivers do not work with the Katana
development system.  Install the Adaptec drivers to overcome this problem.

20) After the ASPI drivers have been verified, install the Katana
    development software, and continue the hardware setup by following
    the procedure labeled "Flashing the Katana ROMS".


4. Installing the Development Software
--------------------------------------

The Katana Software Development Kit (SDK) may be installed using the
standard "InstallShield" utility or by manually copying the contents of
the CD-ROM to a hard drive.  

Note: Before installing the Katana SDK, make sure Microsoft Developer
Studio (Visual C++) v.5.0 has already been installed and updated with
Service Pack 3.

To use the standard installer, simply open the "Katana SDK, Release 4"
CD-ROM and double-click the "Setup.exe" icon.  Follow the instructions
contained within the installation program.  Using this method, you may
select the entire SDK or "Custom Install" only a few basic components.
The full software release requires approximately 100 MB of drive space.

To un-install the SDK, open the Windows "Add/Remove Programs" Control
Panel, select "Katana Development Software", and click "Add/Remove".

Note: To avoid confusion, install the current Katana SDK in a different
location from the previous release.

If you want to install portions of the SDK manually, you may peruse the
CD-ROM using the Windows Explorer and copy only those files that you
require.  This method requires knowledge of the Katana folder hierarchy
and hand-editing of makefiles and path settings in order to compile the
sample programs.

To perform a full manual installation:

1) Copy the contents of the CD to the PC hard drive.
   Assuming CD-ROM drive is D: and the hard drive is C:, the MS-DOS
   command to perform the copy is:

   XCOPY D:\ C:\KATANA\*.* /S

2) Set the attributes of the copied files to writable, using the command:

   ATTRIB -R -A C:\KATANA\*.* /S

3) Edit "C:\KATANA\LIB\SETPATHS.BAT" to match your computer's setup.


5. Flashing the Katana ROMS
---------------------------

Whenever a new version of the Codescape debugger or GD-ROM Workshop is
released, the Flash ROM files on the Katana development system must be
updated.  Use the following procedure to re-flash these ROMs.

1) Open the "Info.txt" file located in the "Katana\Utl\Dev" folder and
   make a note of the current versions of DA Firmware and GD-M Firmware.

2) Run the DACheck utility located in "Katana\Utl\Dev\DACheck".

3) A "DACheck Warning" window should open, displaying the message that the
   Debug Adapter will be set to "CPU Mode" and all emulation halted on
   the target.  Select "OK" to continue.

4) Once DACheck finishes initialization, a split window will open
   displaying Debug Adapter operations on the left side and GD-ROM
   Emulation on the right.  Both sets of indicator lights should be yellow.
   If a communication error occurs at this point, the problem is most
   likely caused by old or incompatible ASPI drivers.  See Step 19 of
   "Installing the Hardware and Drivers" for more information.

5) Check the version number of the Debug Adapter and GD-M Firmware against
   the versions recorded in Step 1.  If the ROMs are up-to-date,
   re-flashing is unnecessary.

6) If the DA Firmware needs to be updated, click on the "Reflash DA"
   button in the lower left-hand corner of the window.  This will bring
   up a file requester searching for a ".fsh" file.

7) Select the "Genie.fsh" Flash ROM file located in the
   "Katana\Utl\Dev\Codescape" directory.  When DACheck asks if you wish
   to flash this file, select "OK".

8) The flashing process takes approximately 20 seconds to complete.  When
   finished, both the host PC and Katana development system need to be
   shutdown.  DACheck will ask you to select either "Continue" or "Exit
   DACheck".  If you plan on updating the GD-M Firmware, select "Continue"
   and proceed to the next step.  If you are finished updating ROMs, or if
   contact is lost with the Debug Adapter, quit DACheck and shutdown
   Windows at this time.

9) If the GD-M Firmware needs to be updated, click on the "Reflash GD-M"
   button in the lower middle-right portion of the window.  When prompted,
   choose the "Flash from file" option, to bring up a standard
   file requester window.

10) Select the "gmX_X_Xx.fsh" Flash ROM file (where X's are replaced by
    version numbers) located in the "Katana\Utl\Dev\GDWorkshop" folder.
    When DACheck asks if you wish to flash this file, select "OK".

11) After approximately 20 seconds, the ROM flashing procedure will finish.
    Select "Shutdown Windows" to allow the changes to take effect.

12) After Windows shuts down, turn off the Katana development system.
    Wait at least 10 seconds before restoring power to the unit.
    Seriously, this wait period is important!  Reboot the PC and verify
    that the DA and GD-M devices mount, as described in Step 9 of
    "Installing the Hardware and Drivers".

13) Once the Flash ROMs have been updated, launch the DACheck utility
    again.  Test the functionality of the development system by running
    the "Test DA" and "Test GD-M" simulations.  If each test passes, the
    appropriate indicator light on the sidebar will turn green.

14) Exit DACheck.  When prompted, make certain to set the Debug Adapter
    back to "CPU Mode".

Note: At any time, if a problem occurs or contact is lost with the Debug
Adapter, shutdown Windows and turn off the Katana development system.
For best results, wait at least 10 seconds before restarting the Set 4.


6. Using the Codescape Debugger
-------------------------------

Once the Katana development system has been completely installed and
updated with the latest firmware, you may begin compiling, debugging, and
executing code.  To download and run executables on the SH-4, you must use
Cross Products' Codescape debugger.

The quickest way to verify that the hardware is functioning properly is to
load and run one of the pre-compiled sample programs.  The following
procedure describes how to use the basic features of Codescape to execute
the "Teapot" sample.

1) Load "Codescape.exe" in the "Katana\Utl\Dev\Codescape" folder.  If
   Codescape brings up a dialog boxing prompting for a debug mode,
   select "CPU Mode".

Note: Always run Shinobi code in "CPU Mode".  The mode can be changed by
running the DACheck utility.

2) The first time Codescape is run, a warning message stating "Unable to
   restore toolbar state" is displayed.  Press "OK" to continue.

3) From the "File" menu, select "Load Program File".

4) Press the "Browse" button to bring up a standard file requester or type
   in the path to the "Teapot.elf" sample executable located in
   "Katana\Lib\Ninja\Samples\Teapot\Exe".

5) Leave the "Load Options" and "Reset Options" settings at default.
   Check the "Enable Run Options" box and select "Run to" "main".

6) Press "OK" to load "Teapot.elf".  At this point, make sure that a VGA
   monitor is plugged into the back of the Katana development system.

Note: Changing the video output to NTSC composite requires re-compiling the
"Teapot" sample.

7) From Codescape's "Window" menu, select "New Window" (Ctrl-N).  This will
   open a blank window with "No type".

8) From the "Region" menu, pull down "Type" and select "Source".  The
   window type can also be modified by clicking the desired toolbar icon.

9) "Teapot.elf" contains hardcoded paths to "C:\Katana\Lib\Ninja\Samples".
   If the Katana SDK has been installed in a different directory,
   Select "Edit Source Path" from Codescape's "Project" menu.  Press the
   "Browse" button to bring up a standard file requester or enter the
   path to the "Teapot" source folder.

Note: When the Program Counter (PC) is located in a section of code with
no source or debugging information, the following message is displayed in
the source window:  "**** No debug info. available for address <addr> ****"

10) The source window should now display the following from "NjLoop.c":

=> void main (void)    /* Arrow (=>) represents PC. */
   {
.     njUserInit();    /* Dot (.) indicates "no break point". */
      ...              /* F5 toggles break points. */
   }

11) From the "Debug" menu, pull down "Execution" and select "Run" (F9).
    A spinning teapot should be displayed on the VGA monitor.

12) To expedite the process of loading and running the "Teapot" sample,
    save the current session by selecting "Session Save" from the "File"
    menu.  This records directory paths, window states, break points, etc.

You may wish to continue testing the Set 4 unit by running additional
sample programs which exercise the Maple controller box and GD-ROM
filesystem.  Read through the following two sections for information on
how to do this.


7. Using GD-ROM Workshop
------------------------

The GD Workshop utility allows you to lay out and burn GD-ROM disks.  It
also controls the emulation of GD-ROM disks on the Katana development
system's hard drive.

The following procedure demonstrates how to set up the GD-M emulation
environment and execute a sample program which accesses the filesystem.

1) Load "GDWorkshop.exe" in the "Katana\Utl\Dev\GDWorkshop" folder.
   
2) The first time GD Workshop is run, a warning message is displayed
   stating "Workshop was unable to determine your emulation configuration;
   you will be taken to the configuration screen."  Press "OK" to continue.

Note: If this message does not appear, go to the "Configuration" menu and
select "Configure drive letters".

3) In the "Configure drive letters" window, the available SCSI controllers
   on the system should be listed with any attached devices that match
   the characteristics of the GD-M Emulator.  For example:

   Adapter #0
   +-- ID #4 CPL GD-M

4) Highlight the "CPL GD-M" device.  On the right side of the display is
   a pull-down menu containing drive letter assignments.  Select an
   appropriate drive name and click "Add".  Repeat this process for the
   second drive partition (if present).  When finished, the lower portion
   of the window labeled "Current drive selections" should list:

   E: 0,4 CPL GD-M  (assuming drive E: is the first available)
   F: 0,4 CPL GD-M

Note: Be careful not to select other removable drives, such as a "Zip"
drive, as a Katana emulation device.

5) When finished assigning drive letters, press "OK" to exit.  Re-launch
   the GD Workshop application to continue.

6) Once the main Workshop window opens, pull down the "Configuration"
   menu and select "Workshop".

7) In the "Workshop Settings" dialog box, make sure that the checkbox
   labeled "GD-ROM auto-build, add files to 2nd session" is checked.  You
   may also want to adjust the pull-down speed adjustment menu from
   "Real Katana Speed" to "No Speed Restrictions".  This will allow files
   to be loaded from the Set 4 filesystem at the full speed of the SCSI
   hard drive.  Press "OK" to return to the main window.

8) From the "File" menu, select "New" (Ctrl-N) and supply a name for the
   project.  For this example, use the title "Samples".  This will open
   a blank project window with a number of user-modifiable tab menus to
   the right.

9) Leave GD Workshop running in the background and use the Windows Explorer
   to locate the folder "Katana\Lib\Ninja\Samples\F40\GD_Root".  Open this
   directory and select all the files within.

10) Drag-and-drop the selected files onto the empty "Samples" project
    window within GD Workshop.  This action will launch a dialog box
    labeled "File Systems Configuration".  Select the "GD-ROM" option and
    press "OK".

11) GD Workshop displays a progress bar for each file as it is copied to
    the Katana development system.  When finished, a GD-ROM disk is 
    generated with the following data structure:

    GD-ROM
    +-- Session
        +-- ISO Level 2
            +-- 01 - Mode 1
            +-- 02 - CDDA
    +-- Session
        +-- ISO Level 2
            +-- 03 - Mode 1

    All data files are stored on Track 03 (03 - Mode 1).

Note: A bug currently exists in GD Workshop preventing the addition of
new files to a disk that has been auto-created using drag-and-drop.  To
work around this problem, close the project window.  When prompted to
"Save changes" select "Yes" and save the project to any location on the
hard drive.  Then re-load the same project by pulling down the "File"
menu and selecting "Samples.cpj"

12) To finish setting up the GD-ROM disk, some 'dummy' system files need
    to be added to the first two tracks (in Session 1).  Highlight Track 1
    (01 - Mode 1) and right-click the mouse to bring up an option menu.
    Choose "Insert" "File".

13) From the file requester, select "Test.dat" located in the
    "Katana\Utl\Dev\GDWorkshop" directory.

14) Repeat this process for Track 2 (02 - CDDA).  Insert the same
    "Test.dat" file.  The disk is now ready to emulate.

15) Near the bottom portion of the GD Workshop screen is a log window
    displaying the current version of the GD-M Firmware.  Above this are
    four toolbar icons for controlling the state of the emulator.  Make
    sure that the right-most icon labeled "Switch Emulator/GD-ROM" is set
    to "Emulator" (Switch is pointing up - away from the yellow disk).

16) The left-most icon represents the state of the virtual "Drive Door".
    When this is open, you can add and delete files in a GD-ROM project.
    When closed, the disk is in emulation mode.  Changes to the project
    do not take effect until the drawer is opened and closed again.  To
    begin emulating the "Samples" disk, click the "Drive Door" icon (F9).

17) Several messages are printed to the log window as the door closes
    indicating that the emulation is being prepared.  Once the filesystem
    has mounted, the text "Close Door" is displayed.  At this point,
    you may minimize the GD Workshop window.  Keep the application running
    in the background so that file access strings are displayed in the
    log window.

18) Launch the Codescape Debugger.  Follow the procedure detailed in the
    previous chapter for loading and running an executable file.  Load the
    "F40.elf" example located in "Katana\Lib\Ninja\Samples\F40\Exe".

19) As the F40 sample runs within Codescape, texture files are loaded from
    the GD-ROM filesystem.  You should see a number of messages in the
    GD Workshop log window indicating that ".pvr" files have been loaded.

If any error occurs during the emulation process, perform a hard reset of
the Katana development system (using Codescape, select "Reset" "Hard Reset"
from the "File" menu).  Wait a few seconds, then open and close the
"Drive Door" in GD Workshop.


8. Compiling the Samples
------------------------

When the Katana SDK is installed using the standard "InstallShield"
utility, the locations of Microsoft Developer Studio and Hitachi SHC/C++
are recorded in a batch file labeled "Katana\Lib\SetPaths.bat".

If an error occurred during the installation process or files were copied
manually from the CD-ROM, "SetPaths.bat" may contain incorrect information.
In this case, running the batch file will report the exact nature of the
error.  If you need to edit "SetPaths.bat", open the file and search for
the default environmental variable settings.  Modify these to match your
system's configuration.

To re-compile all the sample programs within any library directory (Ninja,
Kamui, Shinobi, Libc), double-click the "Make.bat" icon.  This will open a
MS-DOS shell, set the necessary paths, and issue a "NMake" command.
To perform the same operation manually:

1) Open an MS-DOS shell to the appropriate library directory
   (i.e. "Katana\Lib\Ninja\Samples") and type "SetPaths".

Note: The default environmental variable space for a MS-DOS shell is too
small for the necessary paths and settings.  You can increase ENV memory
to maximum (32 KB) by issuing the following: "Command /E:32768".

2) Type "NMake" to build all the samples in a given library.
   Enter "NMake Clean" to erase all temporary files, object files, and
   executables.

3) To build individual sample programs, enter the directory where the
   sample resides and type "NMake -f SampleName.mak".  For example, to
   build the "Teapot" sample:

   "Command /E:32768"
   "CD Katana\Lib\Ninja\Samples"
   "SetPaths"
   "CD Teapot"
   "NMake -f Teapot.mak"


9. Shinobi Initialization
-------------------------

Within each of the sample program directories exists the source file 
"SbInit.c".  This file contains all the code necessary to initialize the
Shinobi library system.

The following section describes how you can modify "SbInit.c" to perform
the most common customizations to the Ninja and Kamui samples.

1) Controller Box

Set 4 development systems are shipped with two versions of the Maple
controller box.  The older type is labeled "Maple Bus - SATURN" in the
upper right-hand corner.  The newer type has a "Katana" scripted signature
near the bottom of the box.  This updated Maple bus design supports both
Saturn and Dreamcast controllers.

The sample programs were originally built for the older Saturn Maple
controller box.  If you received a "Katana" controller box, change the
USE_DCPAD definition to 1 (true) and re-compile.

#define USE_DCPAD 1   /* 0...Use Saturn Maple controller box. */
                      /* 1...Use Dreamcast controller box. */

The best sample program to test the Maple bus is "Print", located in
the "Katana\Lib\Ninja\Samples" folder.  Plug a Saturn 3D analog "Nights"
controller into Port A and run the sample.  Control pad movement and button
presses will be displayed on the screen.

2) GD-ROM Filesystem

To allow an application to use the GD-ROM filesystem, change the USE_GDFS
definition to 1 (true) and re-compile.  See the section labeled "Using
GD-ROM Workshop" for details on how to access files on an emulated GD-ROM.
When the USE_GDFS flag is 0, calls to Shinobi file functions are ignored.

#define USE_GDFS 0   /* 0...No Filesystem. */
                     /* 1...Use GD Filesystem. */

3) Video Mode

The Set 4 development system is capable of generating standard VGA or
composite video output signals, but not both at the same time.

In the Ninja sample programs, the display mode is sent to sbInitSystem()
via the "mode" function parameter.  Pass NJD_RESOLUTION_VGA or
NJD_RESOLUTION_640x480_NTSCI to specify the appropriate video output.

The Kamui samples set the video mode within the "SbInit.c" code.  Look for
the lines:

/* Initialize the display device (VGA/PAL/NTSC). */
kmInitDevice (KM_VGA);

/* Set the frame buffer display mode. */
kmSetDisplayMode (KM_DSPMODE_VGA, KM_DSPBPP_RGB565, FALSE, FALSE);

Replace KM_VGA and KM_DSPMODE_VGA with KM_NTSC and KM_DSPMODE_NTSCI640x480
to change video output.
