RELEASE NOTES

SOE SDK8

1. Installation

You can install the Katana Software Development Kit (SDK) by using the standard "InstallShield" utility or by manually copying the contents of the CD-ROM to a hard drive.

To use the standard installer, simply open the "Dreamcast SDK 8" CD-ROM and double-click the "Setup.exe" icon. Follow the instructions contained within the installation program.

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

2. Updating firmware and flash ROM

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

1) Run the DBFlash utility located in "Katana\Utl\Dev\DBFlash."

2) When DBFlash completes its initialization, a four-pane DB-Flash window opens. You can use the three top panes in the window to flash DA Firmware, GD-M Firmware, and Boot ROM. The bottom pane is a text box that displays the status of operations as they are carried out.

Note: If an error occurs when you try to open the DBFlash window, the problem is most likely caused by old or incompatible ASPI drivers. (For more details, see "Installing the Hardware and Drivers" for more information)

3) In the DBFlash window, note the three text boxes labeled "Current Version" numbers that appear in the top three panes of the DB-Flash window. As you complete the steps that follow, DB-Flash Will use these text boxes to match the latest release of the Dreamcast Development firmware with the version numbers of your system's current DA ROM, your system's current GD-M Firmware, and your system's current Boot ROM.

Also notice the check boxes labeled Reflash that appear in the window's top three panes. If a check mark appears inside any of these check boxes during the steps that follow, that means that the corresponding ROM in your system needs to be updated. If no check marks appear during the steps that follow, flashing will not be necessary.

4) To start the job of reflashing your system's firmware, click the "Browse" button in the top (DA Firmware) pane of the DB-Flash window. DBFlash responds by opening a file chooser dialog.

5) Using the file chooser, navigate to the "Genie.fsh" Flash ROM file, which resides in the Utils\Dev\Codescape" folder. Then double-click on the file's icon to select it.

6) If your DA Firmware needs to be updated, two things now happen: A check mark appears inside the Reflash check box in the top (DA Firmware) pane of the DB-Flash window, and the version number of the newest DA Firmware release appears inside the text box just the right of the updated check box. If these two changes occur, you will know that your systems' DA Firmware needs to be reflashed. But it is not time to do that yet. Instead, for now, just move on to Step 7.

7) Navigate to the "gmX_X_Xx.fsh" Flash ROM file (where X's stand for version numbers). This file resides in the "Katana\Utl\Dev\GDWorkshop" folder. When you have located it, double-click on its icon to select it.

8) If your GD-M Firmware needs to be updated, two things now happen: A check mark appears inside the Reflash Check box in the second (GDM Firmware) pane of the DB-Flash window, and the version number of the newest GD-M Firmware release appears inside the text box just the right of the updated check box. If these two changes occur, you will know that you need to reflash your systems' GD-M Firmware.

9) If neither your DA Firmware nor your GD-M Firmware needs to be updated, the version numbers of your system's DA and GD-M Firmware match the corresponding version numbers of the latest Dreamcast firmware release in the DB-Flash window, so you can now close the window without performing any flashing operations.

10) If the preceding steps revealed that your DA Firmware needs updating, or that your GD-M Firmware needs to be updated (or both), click the "Reflash" button in the lower left corner of the DBFlash window. When the flashing process begins, DBFlash displays a status bar at the bottom of the DBFlash window to inform you that the operation has started.

11) It takes about 25 seconds to reflash your system's Firmware. Then DBFlash displays a "Success" dialog.

12) After noting the instructions displayed in the bulleted list in the DB-Flash window, close the window by clicking the "Exit DB-Flash" button.

13) Power down your PC and Dreamcast dev box.

14) Wait at least 30 seconds, and then turn your dev box back on again.

15) Reboot your PC and verify that the DA and GD-M devices mount, as described in Step 10 of "Installing the Hardware and Drivers."

Note: In some cases, Windows may report after a reboot that an "unknown device" has been found. When the "Update Device Driver Wizard" opens, select "Next" to search for a device driver. When the message "Unable to locate a driver for this device" appears, select "Finish." No device drivers are necessary for the Katana DA or GD-M devices.

16) After your Flash ROMs have been updated, you can test the functionality of the development system by running a utility called "DACheck". DACheck is located in the "Katana\Utl\Dev\DACheck" folder. From the DACheck main window, click the "Test DA" and "Test GD-M" buttons. If each component tests OK, the corresponding status light will be green. A red light indicates failure.

3. Compiling the Samples/Programs

Changing SETPATHS.BAT

Is a batch file (replacing the old set_kt.bat) that sets up the necessary environment variables and paths inorder to make the samples. You will need to edit this file to reflect the file position that you have copied/installed this SDK to, change the following line:

SET DCSDK_ROOT = <the root of sdk>

You now need to run setpaths.bat before attempting to compile sample.

Compiling using Hitachi Compiler

1) Navigate to the directory of the sample that you wish to compile.

2) Run the GNUMAKE utility by executing the command

GMAKE -f <sample>.mak

3) Two directories are created - obj, containing the object files, and exe, containing the final elf or bin file depending on the makefile settings. ELF files are loaded and run via Codescape for debugging purposes, BIN files are used for emulation and GDROM mastering.

4) Customizing the makefile (the .mak file in the source directory) is easy just edit the following lines:

PROJECT = Teapot

(the output name of your elf/bin file)

PROJECT_SRC = …

(list all your desired source files to link - their type is automatically determined from their extension)

PROJECT_LIBS =

… (any additional libraries you wish to include, not including gfxlib and sh4lib, specify NONE if no extra needed)

OPTIMIZE = 1

(switches on optomization - maybe more difficult to debug)

DEBUG = TRUE

(includes debug information in the elf file for Codescape)

#LIST = TRUE

(outputs a list map file)

#BIN = TRUE

(if enabled also outputs a binary file)

GFX_LIB = NINJA

(change to KAMUI1 or KAMUI2 depending on your application)

Compiling using Code Warrior

1) In Code Warrior, in each sample folder (such as the Teapot folder), there’s a subfolder named CW_Proj. Launch CodeWarrior. After starting Code Warrior, choose "Open Project" from the file menu. A standard file dialog then opens.

2) Navigate to the folder, select the C:\Katana\Sample\Ninja3D\Teapot\CW_Proj folder.

3) Select the CW_Proj.mcp file. CodeWarrior responds by opening the project and all its associated windows.

4) Build the project by choosing the Make option under the Project menu or pressing the f7 key. By default, the output is a file in the CW_Proj folder named debug.elf.

5. Notes on creating GDROMs

IMPORTANT : When submitting final mastered disks to Sega you should always use the CDCRAFT utility rather than GDWorkshop since this is the only approved method.

Tracks 1 and 2 of Session 1 are not the only tracks on the GD-ROM that require a buffered area at least four seconds long. As mentioned earlier, every track that you place on the GD-ROM must contain at least four seconds of data.

Track 3 - It's particularly important to pad Track 3 (the first Mode1 track of the disk's high-density area) by filling it with zero data. That's because the 1ST_READ.BIN file -- your actual game executable -- is always placed on Track 5, which must always lie outside the disk's 100-minute mark.

Track 3 is used only for padding. To pad it, you fill it with zero data beginning at its first sector. When you do that, GD-Workshop forces any data files on the track to occupy the end of the track. GD-Workshop also calculates the size of the track, and arranges the data on it in such a way that your game's executable always winds up on the outside edge of the disk.

To pad Track 3, check the "Pad Track" check box in the "Track" tab in the GDWorkshop window. CDCraft takes care of this for you anyway.

Track 4 - At least one CDDA track (raw digital audio) is required on Track 4 of Session 2. Even if your game doesn't use digital audio, you still must place at least four seconds of data on Track 4.

5. Creating a Bootable Emulation/GD (a 1ST_READ.BIN file)

1. Edit the makefile for your project such that the option line BIN = TRUE

2. Rename the BIN file to 1ST_READ.BIN if not already.

3. Insert 1ST_READ.BIN into Track 5 of the GD-ROM project.

Note: The last file added to a track is physically located at the end of the track. This is where 1ST_READ.BIN should be.

4. Create files IP0000.BIN and IP.BIN to placed in the single and high density system areas of the GDROM respectively using the IPMAKER utility (Utils\Dev\IpMaker)

Notes on using IPMAKER

On executing ipmaker.exe (utils\dev\ipmaker), locate the Configure button in the bottom part of the window, and select it. That action brings up a dialog that lets you choose the Japanese or English language. Select English and click "OK."

When the IPMaker window opens, find the check boxes that let you specify whether your game will be used in the U.S., in Europe, or in Asia. Check the box appropriate for your product.

Fill out the other edit fields in the window, such as your game title, your development company, and your publishing company. When you're satisfied that you have filled out all those fields correctly, click the "Apply" button at the bottom of the window.

At the bottom of the window, there's a box that lets you select a filename. The filename 1ST_Read.bin appears there by default. Leave the default setting alone; that's the name you'll want to use.

There's also a "Peripherals" tab in the IPMaker window. If your game supports peripherals other than the standard Dreamcast controller, click the "Peripherals" tab and check all boxes that apply to the controllers you plan to use.

Note: If you want your game to support VGA output, check the VGA box, which by default is unchecked.

Testing

Once you have followed the steps above, i.e. created a 1ST_READ.BIN in the last data track, and placed IP.BIN and IP0000.BIN in your project, and padded the project with the necessary data/audio files. Close the emulation door and reset the development kit. You will need to be in OS debugging mode (this can be set from Codescape or Dacheck).

6. GDROM image texture

There is file that you can add to your last Mode1 track. It's a 256x256 file named texture 0gdtex.pvr. It allows you to customize what the texture will be on the picture of the GD that you now see spinning around. If you like, you can change the default texture to your company's logo, or whatever else you think would be cool to display there.

7. Known Problems

Adaptec 2940U SCSI controller recommended

Sega recommends Adaptec 2940U (PCI-to-Ultra SCSI) or 2940UW (PCI-to-Wide Ultra SCSI) controllers for use with the Dreamcast development system. 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 system, problems have been identified in the GD-ROM emulation. Please contact Sega Europe if you are not sure.

Textures and file loads must be 32-byte aligned

Due to DMA restrictions, Kamui textures and file loading operations should be aligned to 32-byte boundaries. For an example of how to do this properly, see the Align32Byte() macro in the QuikTest sample program.

Programs compiled under CodeWarrior do not necessarily run under Codescape

Some example programs compiled with CodeWarrior that use C++ features dereference the NULL pointer if they are run under the Codescape debugger. Debugging the same ELF file with the Metrowerks IDE does not manifest this problem.

Metrowerks's MSLRuntimeDC.lib library handles C++ exceptions. Metrowerks's STL error handling uses exceptions. However, when using Codescape with the STL libraries, register and stack data are trashed on most exceptions, including memory addressing errors.

This can be partially worked around by placing a breakpoint at 0x8c00f500, which is the location of the Shinobi exception handler. Codescape's trace feature can then be used to find out which instruction generated the exception.

GD Workshop hard limits

Due to GD-ROM format and performance considerations, there are certain numeric limits on GD-ROM emulation and usage with GD Workshop:

- Maximum number of files per project: 20,000

- Maximum number of file extents over 1 project: 64,000

- Maximum number of files in a directory on emulation drive: 4,000

- Maximum number of directories on emulation drive: 512

Virtua Fighter 3tb and Dream Passport do not run on development hardware

Neither of these titles run on development systems. The VF3 behavior is by design. Dream Passport only permits on-line access from production units.

Vertex buffers should be set up in non-cacheable memory

For an example of accessing memory in a non-cached manner, examine the SH4_P2NonCachedMem() macro in the QuikTest sample program.

Must rebuild existing libraries with new linker

When linking code with user libraries built using an older Hitachi librarian, the linker may exit with a "Memory Overflow" error. To work around, re-build the library with the current version of the librarian.

SH4 Restrictions

When a LDC instruction is paired with a BF, BT, BRA, JSR or JMP instruction, invalid data may be loaded into the LDC-referenced register. To work around, insert a NOP instruction between the memory access and the delayed branch.

MOV Rm, R0 paired with implicit reference to R0 gives incorrect result:

1) Load R0 from memory

2) MOV Rm, R0

3) One of the following instructions:

MOVCA.L R0, @Rn

MOV.[BWL] Rm, @(R0,Rn)

MOV.[BWL] @(R0, Rm),Rn

MOV.[BW] R0,@(disp, Rn)

CMP/EQ #imm,R0

MOV.[BWL] R0,@(disp,GBR)

[TST,AND,XOR,OR] #imm,R0

FMOV.S @(R0,Rm),FRn

FMOV.S FRm,@(R0,Rn)

FMOV @(R0,Rm),DRn

FMOV DRm,@(R0,Rn)

FMOV @(R0,Rm),XDn

FMOV XDm,@(R0,Rn)

To work around, insert a NOP instruction between the MOV instruction and the instruction in (3).

In the following instruction sequence, the result of instruction (3) is incorrect because instruction (2) blocks the bypass logic from instruction (1) to instruction (3).

1. Instruction that changes the value of floating register FRa, FR(a+1), or both.
2. 32-bit LS instruction with a destination register of FRa or FR(a+1)
3. FMOV with a source register of Dra

Example of code sequence which manifests this bug:

FNEG FRn

FABS FRn

FLDI0 FRn

FLDI1 FRn

FSTS FPUL, FRn

FMOV FRm, FRn

To work around this problem, insert 3 NOP instructions between instruction (2) and instruction (3).

8. Sample Data

The sample data (sound and movies) included with this SDK may not be used in actual game projects except in special cases.*

* The special cases are when the data must be combined with the actual game, or when we recommend that the data be combined with the game.

9. Middleware Licenses

Please be advised that we are anticipating that the MPEG Sofdec and Duck Trumotion will generate royalties when sold as a module together with applications. Please contact your Sega Third Party Department for information.

10. Authorization

Permission to use this SDK Package is based on the following contracts intended to be concluded between our company (a division of Sega Enterprises) and your company.

Dreamcast Software Development Authorization Contract

Dreamcast Software Development Tool Loan and Re-Use Contract