Release Notes for Microsoft Windows CE Toolkit 2.1 for Dreamcast

February 2000

© Microsoft Corporation, 2000. All rights reserved.

Welcome to the Microsoft® Windows® CE Toolkit 2.1 for Dreamcast™. These release notes contain information on known bugs and problems and additions to the documentation.

Contents

• Support Information
  
  
• Dreamcast SDK Licensing
  
  
• Redistribution Disclaimer
  
  
• Installing Hardware and Software
  
  
• Known Bugs and Problems

Support Information

Sega Enterprises provides technical support for the Windows CE Toolkit 2.1 for Dreamcast. Microsoft Corporation can provide additional technical support if required.

For general information and support, send email to:

Wince4DC@Microsoft.com

Dreamcast SDK Licensing

In order to use this software to ship a game title, you must sign the Microsoft license agreement. For more information about the license, please send email to dclicens@microsoft.com.

Redistribution Disclaimer

Cross Products, Ltd. (CPL) has granted Microsoft the right to redistribute the following CPL products within the Windows CE for Dreamcast Software Development Kit (SDK) provided directly to Sega:

• The Salsa library for personal computer linked to Microsoft applications.
  
  
• The GD Workshop utility, as supplied to Microsoft by CPL, along with associated Help and ancillary fields.
  
  
• Updated firmware for the Debug Adapter and GD-Emulator, as supplied to Microsoft by CPL.
  
  
• The DACheck utility for upgrading the specified firmware files.

This redistribution is being allowed so that Microsoft can guarantee compatibility between CPL products and specific releases of the Windows CE for Dreamcast SDK. Microsoft does not market or distribute these products on behalf of CPL. Microsoft provides no warranty to Sega or other users of the Windows CE for Dreamcast SDK for the bundled CPL products, and all responsibility for development and support of the CPL products remains with CPL and Sega.

Sega Product Development of Sega of America grants Microsoft Corporation the right to freely distribute the following audio conversion tools with the Windows CE for Dreamcast SDK:

• WaveCon, a PCM-to-ADPCM conversion tool designed to convert uncompressed PCM WAV audio data to the Yamaha Corporation ADPCM format to run on the Sega Dreamcast hardware.
  
  
• DLS2STB, a DLS-to-Sega tonebank converter, designed to convert data from the MMA DLS instrument bank format to the Sega Dreamcast instrument bank.

Installing Hardware and Software

The following information explains how to set up your Dreamcast Dev.Box and install the software provided with the Microsoft Windows CE Toolkit 2.1 for Dreamcast on your Windows NT® or Windows 98 development computer.

Note

Windows CE for Dreamcast versions 1.1 and 2.1 cannot co-exist on the same computer. Therefore, if you have an earlier version of the SDK installed, check the box to install the new version when prompted. When you do, Setup will uninstall the previous version.

Once you install your hardware and software, you can do the following:

• Run the Windows CE for Dreamcast OS on the Dev.Box.
  
  
• Run the SDK samples on the Dev.Box.
  
  
• Write and build your own applications and games that take advantage of the Windows CE for Dreamcast OS and DirectX® 6.1 components.
  
  
• Remotely debug the samples and your games on your Windows NT or Windows 98 development computer.

Note

Because this version of the SDK uses some ports differently than earlier versions of the SDK, if you previously set up the Dev.Box, you must unplug all cables and start from the beginning.

Hardware Requirements

Before installing the software provided with this SDK, you need the following:

• Desktop computer running Windows NT 4.0 SP5 or Windows 98 (Special Edition not supported), your development and debugging computer. This computer connects directly to the Dreamcast Dev.Box.
  
  
• Dreamcast Dev.Box (SET 5.24), your target platform. This version of the Windows CE for Dreamcast SDK does not support earlier versions of the Dreamcast Dev.Box.

Note

Windows CE for Dreamcast does not support the NEC 98 series platform.

Development Computer Requirements

The following are requirements for your development computer:

• A Pentium® 133MHz, or faster, processor. Microsoft recommends a Pentium II processor.
  
  
• 32 MB of RAM. Microsoft recommends 64 MB of RAM.
  
  
• 380 MB of free disk space for installing software and documentation, or 601 MB for installing software, samples, and documentation.
  
  
• An installed Adaptec SCSI controller (1542, 1742, 2940, 2940U, 2940UW, or  3940), with an external SCSI connector.

  

  Note

  SCSI controllers from other manufacturers may not work with the Dev.Box. While it is possible to connect the Dev.Box to the existing SCSI chain on your development computer, Microsoft highly recommends that you install a separate SCSI card that services only the Dev.Box. This eliminates the risk of corrupting your hard drives or crashing the development computer.

  

Dreamcast Dev.Box Requirements

The following are requirements for your Dreamcast development system:

• A power cable.
  
  
• (Optional) A null-modem serial cable, used only for serial networking.
  
  
• A SCSI cable that fits the external connector on the development computer SCSI controller and has a SCSI2 male connector on the other end.
  
  
• A SCSI terminator. This small device may already be attached to one of the two SCSI ports on the back panel of the Dev.Box.
  
  
• Dreamcast game pads. These plug directly into the front panel of the Dev.Box.
  
  
• (Not included) A VGA monitor with cable or an NTSC television with appropriate RCA cables to connect to the Dreamcast Dev.Box.

 Setting Up Your Dreamcast Development System

Setting up the Dreamcast Dev.Box involves:

• Connecting SCSI cables, the SCSI controller, and a SCSI terminator.
  
  
• Connecting a television or monitor.
  
  
• Connecting the game pads.
  
  
• Connecting the power cable.

The following illustration shows the back panel of the Dev.Box.

The following illustration shows some of the cables you will use with the Dev.Box.

Note

The Windows CE for Dreamcast SDK does not support the dongle.

SCSI Connection

On the back panel of the Dev.Box are two rotary switches that represent SCSI identifiers (IDs). Set these switches to use IDs that are not currently being used by any other existing SCSI devices on your desktop computer. To find out which SCSI IDs are already being used, boot your development computer and watch as your SCSI adapter enumerates the existing SCSI devices on your chain. You may be able to accept the default settings of these switches, which are 3 and 4.

Do not connect the Dev.Box to a SCSI controller serving other SCSI devices, such as a Windows NT system disk or other hard drives. If you do, the debug adapter may lock up or crash during the development process, resulting in possible data loss.

Insert the SCSI terminator in one of the two SCSI ports on the back panel of the Dev.Box.

Turn off your development computer. Insert one end of the SCSI cable in the other SCSI port on the back panel of the Dev.Box. Connect the other end of the SCSI cable to the SCSI card in your development computer.

Television or VGA Monitor Connection

Use the DIP switches on the front panel of the Dev.Box after upgrading the Dreamcast Boot ROM to select television or VGA mode.

If you are using an NTSC television, connect the RCA cable from the television to the port on the back panel of the Dev.Box labeled Video. Set DIP switches 1 and 2 so they are in the down position. Set the rotary switch on the front panel of the Dev.Box to one of the following broadcast format settings:

If you are using a VGA monitor, connect the VGA cable from the monitor to the port on the back panel of the Dev.Box labeled Analog RGB (VGA). Set DIP switches 1 and 2 so they are in the up position.

Note

DIP switches 3 and 4 should always be in the down position.

Game Pad Connection

Connect the Dreamcast game pad(s) to the plugs on the front panel of the Dreamcast Dev.Box.

Power Connection

Before turning on the Dev.Box, you must install the software on your development computer and verify the hardware and software setup. Without turning on the Dev.Box, connect the power cable to the back panel of the Dev.Box and plug it into a suitable power outlet. For more information, see “Installing the Software” and “Verifying Hardware and Software Setup.”

Optional Setup

If you require serial communications, connect one end of the null-modem serial cable to the Dreamcast Dev.Box serial port labeled SERIAL. Connect the other end of the serial cable to the COM1 or COM2 port of your development computer.

If you require sound output, connect suitable speakers or the audio inputs of your television to the two ports on the back panel of the Dev.Box labeled L-Audio-R.

When you need to create a Sega GD-ROM image of the application, install a GD-ROM writer cable in the port labeled For GD-Writer on the back panel of the Dev.Box.

Installing the Software

The following information guides you through installing the Windows CE for Dreamcast SDK on your development computer, and configuring it to work with the Dreamcast Dev.Box. The following software installs with the SDK:

• Microsoft Windows CE Embedded Toolkit for Visual C++®
  
  
• Windows CE for Dreamcast SDK

Setup optionally upgrades the debug adapter firmware, GD-ROM firmware, and the Dreamcast Boot ROM firmware on your Dreamcast Dev.Box. Setup also checks whether your development computer has the Advanced SCSI Programming Interface (ASPI) installed. The ASPI is an Adaptec-developed interface specification for sending commands to SCSI host adapters. You can connect to a web site to install ASPI, through Setup, if you have not previously done so.

Before installing the SDK, note the following information about Visual Studio®:

• You must install Visual Studio, sold separately, before you install the SDK. Do not install any Visual C++ 6.0 service packs.
  
  
• You must install Visual Studio with at least the Typical setting so you can run the SDK samples.
  
  
• You must use the Enterprise version of Visual Studio.
  
  
• You must exit Visual Studio before you install the SDK.

  

  Note

  If you have Visual C++ 6.0 with SP3 installed, you must uninstall it and remove the entire Visual Studio directory structure.  Once the directory structure is gone, reinstall Visual Studio without any Visual C++ 6.0 service packs. Be careful to not delete any personal files when removing Visual C++ 6.0.

  

Versions 1.1 and 2.1 of the SDK cannot co-exist on the same computer. Therefore, if you have an earlier version of the SDK already installed, check the box to install the new version when prompted by Setup. This will uninstall the earlier version automatically and safely, without removing personal files.

To install the Windows CE for Dreamcast SDK

1. Run Setup.exe from either the \Eng or \Jpn directory.
   
   
2. To save disk space, select the Specific Processor(s) option and deselect all but the SH4 Processors option.

When you are ready to begin developing applications, configure the SDK to use either the debug or retail environment using the Image Configuration tool. For more information, see “Choosing an Operating System Version.”

Dreamcast Documentation

Nearly all of the APIs and interfaces supported in this SDK are subsets of Windows CE version 2.12 and DirectX version 6.1. This SDK contains documentation for all APIs supported by Windows CE for Dreamcast.

Upon installation of the SDK, the Dreamcast documentation becomes the preferred, or default, help system collection in Visual Studio. Select a different preferred collection, such as MSDN™, by changing the option on Visual Studio’s Help Systems tab in the Options dialog.

Verifying Hardware and Software Setup

Before proceeding, verify that you installed the Dreamcast Dev.Box and Windows CE for Dreamcast SDK and set up the Adaptec SCSI devices properly.

To verify SDK setup

1. If it is not already on, turn on the Dev.Box.
   
   
2. Open Dreamcast Tool by double-clicking on the Dreamcast Tool icon in your Windows CE for Dreamcast SDK program folder.
   
   
3. When the window opens, choose Boot Dreamcast from the File menu. You should see something similar to this:

   DCTOOL: Files served from "d:\WCEDreamcast\Release\debug"
   DCTOOL: Connecting to Dreamcast...
   DCTOOL: Connected
   DCTOOL: Found SEGA KATANA_DA Device on SCSI Host <0> : SCSI Device <3>.
   DCTOOL: KD Transport for WinDBG
   DCTOOL: Version 2.1  Copyright(C) 1999 Microsoft Corp.
   DCTOOL: Debug adapter connected.
   DCTOOL: dcfs - Dreamcast Windows CE FileServer for NT 
   DCTOOL: Built: Jul 29 1999 01:27:07
   DCTOOL: DCFS using debug adaptor interface
   DCTOOL: resetting target...
   DCTOOL: PPFS supported.
   DCTOOL: >> The console status is 'executing' user code outside debug stub (RUNNING)
   DCTOOL: Image physical size    : 00347a98
   DCTOOL: Physical start address : 8c010000
   DCTOOL: Loading Image:
   .....................................................................
   DCTOOL: Image entry point      : 8c010004
   DCTOOL: running file

4. After Dreamcast Tool has downloaded the image, you should see output in the command window that indicates that the Windows CE for Dreamcast OS is booting.

   You should also see a Windows CE> prompt in the Dreamcast Tool window.

5. Type the following at the prompt.

   s rearviewmirror

   You should see the D3DIM/DDraw/ rearviewmirror sample running on your monitor or TV. Press the X button on the Dreamcast Tool to exit the sample.

To verify Adaptec SCSI device setup

1. Turn on the Dreamcast Dev.Box.
   
   
2. Reboot your development computer.

   As the Windows NT or Windows 98 computer is booting, you should see some basic I/O system (BIOS) messages from the Adaptec SCSI controller, including a list of SCSI hardware found. You should see the GD-M emulator and Katana DA debug adapter, in addition to whatever hardware you normally see listed. The GD-M emulator appears as a removable SCSI disk to Windows NT.

3. For future reference, note the assigned drive letter. If the driver letter is not given here, then Explorer can be used to determine the assigned drive letter. The driver letters do not appear on the NT 4 boot screen, only the device names.

   You are now ready to start developing games using the Windows CE for Dreamcast SDK.

Updating an Existing Dreamcast Project

If you are updating a Dreamcast Visual C++ 5.0 project to a Dreamcast Visual C++ 6.0 project, you must run the Vc5tovc6 converter utility.

Caution

Failure to run the Vc5tovc6 converter utility may damage your project.

The Vc5tovc6.exe utility is in the <WCEDreamcast>/Tools directory. This tool converts your Visual C++ 5.0 project files, which contain both Win32® and Dreamcast configurations, to Visual C++ 6.0 project files, which require separate projects for Win32 and Dreamcast.

To run the Vc5tovc6 conversion tool, type the following at a command prompt:

vc5tovc6 <project file name>

When finished, the utility backs up your original project file and creates two new projects: one for Windows CE and one for Win32. Microsoft recommends you add both projects to your Visual Studio workspace file (.DSW) so that you can build both configurations from within the same workspace.

Known Bugs and Problems

This section contains a list of known bugs and problems with this release of the Windows CE for Dreamcast SDK.

• Looping certain sounds in the Yamaha ADPCM format may cause noise or static during playback. If this occurs, contact Sega technical support for troubleshooting information or use the PCM format for looping sound data.
  
  
• The compiler generates incorrect code if the second parameter for memset has an unsigned value greater than 0xff. To work around this bug, always explicitly type cast the second parameter to unsigned char.
  
  
• The Microsoft Windows CE Toolkit for Visual C++ always installs the Windows CE Tools directory under the root, unless you change both the installation directory and the installation path during installation.
  
  
• GD Workshop may crash when upgrading from version 1.1 to version 2.1. If this occurs, complete the following steps:
  1. Open regedit, and delete (or rename) the following reg key:

     HKEY_CURRENT_USER\Software\Cross Products

  2. Delete or rename “GD Workshop.INI” from your Windows directory.
     
     
  3. Run GDWorkshop. You will receive a warning about missing toolbar settings, but GD Workshop will create the proper defaults and write the correct values into the registry and recreate an appropriate INI file.
     
     
  4. Exit GDWorkshop.
• The midiOutReset function does not return to the callback function nor does it set the MHDR_DONE flag for pending stream output buffers.
  
  
• IOCTL_SEGACD_GET_SCD now requires both an input and an output buffer for parameters. The input buffer is of type SEGACD_SCD. The output buffer is based on the type of data requested in the input buffer and may be either of type SEGACD_SCD_SUB_Q, SEGACD_SCD_MEDIA_CATALOG, or SEGACD_SCD_TRACK_ISRC.
  
  
• You may receive the following error message when running DirectMusic Producer if you do not have a sound driver installed.

  Unexpected error 88780078 when trying to activate connection to the "Microsoft Synthesizer."

  Additionally, DirectMusic Producer is not supported on Windows NT 4.0.

• SPY++ tool does not work when using the standard core OS. This tool only works when using the HTML/IME core OS.
  
  
• In the DirectPlay Server sample program, the client fails to receive from server. To fix this problem, change the second parameter of send function at line 296 of server.cpp, from dpId to pSending->idFrom.
  
  
• IDirectSound::CaptureBuffer requires at least 50ms between calling IDirectSoundCapture->Stop and IDirectSoundCapture->Start.
  
  
• Using DirectShow to stream media to DirectDraw surfaces won't work on retail Dreamcast hardware for version 2.1
  
  
• The way that the smallest polygon setting in platform.reg is interpreted has been changed. Platform.reg now interprets the smallest polygon setting as the smallest polygon rendered in hardware in a 3D operation. It is recommended that you use 0 or a small value like 0 or 0.001 for this setting. Note that the field is entered as a DWORD, but it is scaled by 0.000001f in the driver.
  
  
• Windows 2000 detects the Dev. Box as a “Katana SCSI processor” and displays a “Found New Device” dialog. There are no drivers for this device, so you can simply cancel the dialog box.
  
  
• While the DirectPlay API supports asynchronous messaging, none of the service providers we ship in the SDK supports asynchronous messaging.
  
  
• The mrasentry sample will fail to read the last line of a connectoid if there is not a CRLF at the end of it.