readme.txt
November 5, 1999

Release 9
---------

This document contains late-breaking and important
information about this Katana development
software.  We know this is a lot of information,
but please read it before you try to install this
software.

R9 is an incremental release from R8.  Please
see changes.txt for details.

1. Overview
-----------

This software will allow you to develop for Katana
(Dreamcast).  Make a backup copy of your current
development environment before upgrading to R9.

Due to changes in the audio64 programming layer,
this version is not source-compatible with Release
8 or Release 8.1.  Minimal changes will be
required in order to get your current project to
recompile with this release.  However, we feel
that the significantly improved stability of this
version of the audio64 library is important enough
to warrant these changes. Sega of America
recommends that all active developers use Release
9. We have provided boilerplate code and sample
programs that should help to speed these changes.

Two source-level debugging environments are
included with this release.  Codescape and
Metrowerks CodeWarrior are supported. CodeWarrior
provides an integrated development environment and
better C++ support.  Support for the freely
available, command-line based gnu compiler and
linker have been added in this release.

You can burn and test GD-ROMs with this software,
in conjunction with the GD Writer hardware and
the CD Craft burning software.

This development environment includes a number of
demonstration programs supplied by VideoLogic.
Sega would like to express appreciation to
VideoLogic for supplying these high-quality demos,
which are installed into \sample\kmDemo.
Additionally, VideoLogic has supplied a 3D Studio
Max to Kamui model converter in
\Utl\Gfx\Conv\3DS2Kamui.

R9 does not support modem or network development.
Modem and network development will be supported
in a future release of the development software.

R9 does not support MIDI playback of sounds using
the audio64 driver.  MIDI will be supported in 
the next major release of development software.
Contact Sega DTS if you need a beta version of
the Audio64 MIDI driver.

Please send information about any bugs or 
problems you find to dts@sega.com as soon as 
possible.

NOTE: New functions have been added to the 
Audio64 library: acG2Read() and acG2Write(). You 
must use these functions to read and write to 
audio memory. Due to specific hardware limitations
on production Dreamcast systems, these functions 
must be used when reading or writing sound memory.  
Do not attempt to read or write sound memory 
without using these functions.
 
2. Known problems and issues
----------------------------

This section lists known bugs, problems, and other
issues with this release.  This release is very
environment specific.  Please take note of the
following issues before installing this
development software.

- audio64 handlers must be installed

  In previous versions of audio64, handlers were
  not required for DMA and interrupts.  Now, it is
  necessary to implement these handlers in your
  code in order to allow the audio64 library to
  work correctly.

  We have provided boilerplate sample code to show
  you how to do this.  You can modify these
  samples if your methods for enabling and
  disabling DMA and interrupts are nonstandard.

  Because these changes greatly enhance the
  stability of audio playback, Sega of America is
  requesting all developers to implement these
  changes.  See changes.txt for details on the
  added functions.

- Reflash of GD Writer units required

  An intermittent bug has been identified in the
  firmware of existing GD Writer units that can
  cause disc burns to fail while writing track 2.
  This updated firmware improves the reliability
  of the GD Writer units.  The flash firmware has
  been updated since R8 and it is recommended that
  all developers reflash with this new version.

  The DOS utility for reflashing the GD Writer
  firmware to version 0.49 has been included in
  this release, installed into the
  \utl\dev\dbflash\gdrflash directory.  The
  utility's filename is dld_dos.exe.  The utility
  takes four command-line parameters:

  1) The flash file.  For this parameter, use
     the scsicom.bin file path.

  2) The SCSI ID of the GD Writer to be reflashed.

  3) The ASPI ID of the SCSI card on which the GD
     Writer resides.  This is a zero-based index
     to the card.

  4) The value 11000.

  For example:

     dld_dos.exe scsicom.bin 5 0 11000

  will reflash the GD Writer on ASPI ID #0, on
  SCSI ID #5.

- Development target firmware reflash not required
  when upgrading from R8.  Only flash the firmware
  if upgrading from an early SDK version.

  The installation program initiates the flashing
  process for you by default.  If you need to
  reflash the firmware in your development system
  manually, use the DBFlash program, supplied in
  \utl\dev\dbflash.

  The reflash process requires the SLIDE SW on the
  front of the unit to be toggled twice; follow
  the instructions carefully.
  
- Latest Adaptec ASPI driver required

  The Codescape debugger requires the most recent
  version (4.57) of the Adaptec ASPI driver to be
  installed.  This driver is available from:

http://www.adaptec.com/support/faqs/aspilayer.html

- Using either the audio64 or manatee sound driver
  immediately after initialization may cause errors

  To work around this issue, always pause at least
  500 ms after initializing the audio system
  before issuing any sound commands

- Start of audio streaming using audio64 library
  pauses video

  When loading and playing a digital audio stream
  from GD-ROM, there is a pause in rendering for
  around 250ms while the streamer subsystem
  initializes. This can produce a noticeable hiccup
  in the display.

- gcc does not unroll loops correctly

  The version of gcc included in this release does
  not unroll loops correctly.  Therefore, please
  do not use either the -funroll-loops or the
  -funroll-all-loops flags when compiling with
  gcc.  (These features are not enabled in the
  sample makefiles provided.)

- Second disk partition on GD-ROM emulator drive
  does not appear under Windows NT

  A bug currently exists in Windows NT preventing
  the second partition from being seen.  If you
  need the entire 4 GB storage space, the drive
  can be re-formatted as NTFS or FAT-32.  See the
  section labeled "Formatting the Emulation Drive"
  (p.47) in the "GD-Workshop User Guide"
  distributed with this release.

- Profiling not currently well documented 

  This section describes how to use the profiling
  features of Codescape.

  The key to using this powerful feature of the
  debugger is to enable the Shinobi trace filter.
  Without the filter enabled, your profiling data
  will be almost completely invalidated by the
  excessive amount of time spent in system
  interrupt routines (mostly in the vblank,
  INTERRUPT VBR+0x600).  The filter basically
  masks off these Shinobi functions so that only
  user code is profiled.

  Here's an example of how to use the EVA Trace
  Profiler to evaluate QuikTst2:

  ** Re-build the sample using the profiler
     library.

  1. Edit "Katana\Sample\Katana.inc" and change
  the DEF_LIBS value from "shinobi" to "profiler"
  (or just rename "profiler.lib" to "shinobi.lib"
  temporarily).  This modified version of the
  library has markers added to the interrupt
  service layer to allow Codescape to ignore these
  functions.  In future versions of Shinobi, this
  will be built-in to the standard library, so the
  "profiler.lib" will eventually be removed.

  2. Edit the makefile "QuikTst2.mak" and set the
  value of "LIST = TRUE" to generate a ".map"
  file.

  3. Build QuikTst2:  "gmake -f quiktst2.mak all".

  ** Using the EVA Trace Profiler **

  4. In Codescape, load the re-built
  "QuikTst2.elf".  Make sure that the "Use Symbol
  Info from Hitachi Link Map" is checked in the
  "Load Program Dialog", and do not auto-run the
  program.

  5. From the "Tools" menu, select "Profiler".

  6. After Codescape processes the ELF, right
  click on the "Profiler" window and select
  "Setup".

  7. In the "Profiler Setup Dialog", click "EVA
  Trace Profiling" and select the profiling
  information you desire for each of the
  performance counters (C1 & C2) using the pop-up
  menus.  The default values of "Elapsed time" and
  "Instruction cache miss" are good to start with.

  8. In the second portion of the "Profiler Setup
  Dialog", check the "Enable Trace Interrupt
  Subroutine Filter" box and select "Shinobi
  Filter".  Hit "OK" to continue.

  9. Back in the "Profiler", right click the main
  window and select "Source Display" from the
  menu.

  10. A new source display region will appear.
  Right click in this region and select "Goto
  Address" and enter the symbol "main".

  11. For the QuikTst2 sample, scroll to the main
  "while" loop and place a profiler start
  breakpoint (F5).  Profiler breakpoints can only
  be set within this source window.. they differ
  from standard breakpoints in that they only
  serve as markers to tell Codescape when to begin
  and end profiling a section of code.  ** It is
  important that you place this breakpoint some
  time after the initialization of Shinobi, so
  that the data which "Shinobi Trace Filter"
  depends on is present in memory. **

  12. Scroll to the end of the "while" loop and
  place a profiler end breakpoint (F5).

  13. Right click the "Profiler" window and select
  "Enable" (or use the round stop/start toolbar
  button).

  14. Press F9 to run the program.  If all has
  gone well, the title bar of the "Profiler"
  window (or the main window if maximized) will
  display the message "Shinobi Filter Enabled".

  15. Let the program run for several iterations.
  It will execute very slowly due to the profiler
  sampling.

  16. Disable the profiler.  Codescape will take a
  few seconds to compile the data.  When finished,
  the results will be displayed in the right half
  of the window. With the "Shinobi Filter" active,
  the data now accurately represents the time
  spent in each user routine.

  ** Using the Profiler Instruction Cache Optimizer

  Once you have obtained valid profiling data, you
  may want to use the "Profiler Instruction Cache
  Optimizer" to help identify routines that could
  be grouped or re-ordered for better instruction
  cache coherency.  To begin this process, right
  click the "Profiler" window and select
  "Optimize".  This will bring up an Optimizer
  dialog box.

  In the bottom portion of the window labeled
  "Optimization Information", you will notice a
  description of the functions which can not be
  adjusted, followed by a listing of "fixed
  function groups".  These fixed groupings are
  imposed by the compiler.  Each represents a
  single object file.  To break these apart, you
  would have to move the individual function out
  and into a separate source file.

  From the dialog box, place a check mark next to
  all the routines that you want to analyze, then
  click "Optimize" to continue.  This will bring
  up a file dialog asking you where to save a
  "Link Order File (.lor)".  You can view this
  file in any text editor.  The quick explanation
  for the data in the ".lor" file is that it
  suggests how you can improve instruction cache
  coherency by changing link order based on the
  "Clique" start/end groupings.

- 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.

- gcc generates warnings on headers

  The versions of Shinobi headers in this release
  do not compile cleanly when used with gcc;
  warnings are generated, mostly related to type
  checking.  However, the sample programs run as
  expected.

- Dereferencing NULL not allowed

  System device control registers reside in low
  memory.  Accesses to the memory region
  0x00000000-0x001fffff are almost always the
  result of dereferencing the NULL pointer, which
  is a programming error.  
  
  If you're using Codescape for development, you
  should at some point force Codescape to trap
  these error conditions:

  - Select Debug/Breakpoints/Configure
    Breakpoint(s) to open the breakpoint setup
    dialog box.

  - Click the Add Watch... button.

  - In the Watch Settings tab, enter 0x00000000
    into the Location Expression text box.  In the
    Data Expression group, uncheck the Include
    Data Condition checkbox.  In the Access Size
    option group, select Any.  In the Access Type
    option group, select Write.

  - In the Advanced tab, from Location Mask Selector,
    select "20 bits".

  - Click the OK button to complete the setup.

- Sound example programs may not run as expected
  under default Windows installation

  The low-level sound drivers included in this
  release are called manatee.drv and audio64.drv.
  By default, a Windows machine running Internet
  Explorer 4.0 or higher will not display files
  with a .drv extension.  As a result, when you
  try to create a GD-ROM image by dragging all
  files in the gd_root folder into GD Workshop,
  the driver is not included.

  To see the .drv files, select the drive
  containing the development software
  installation, click the Explorer window's View
  menu, and select Options.  Select the View tab.
  Make sure the "Show all files" radio button is
  selected, and deselect the "Hide file extensions
  for known file types" check box.  Finally, click
  Apply.

- GD Workshop hard limits exist

  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

- Example programs do not run on a VGA display

  The example programs that demonstrate video 
  playback do not support the VGA output.  Make
  certain that your output type is set to
  composite output in order to view these
  programs.

  For more information on automatically detecting
  the display type, see changes.txt.

- System-to-system DMA transfer hardware bug

  A bug within the Hitachi SH-4 when issuing DMA
  transfers from system memory to system memory
  can cause certain registers to fail to be
  updated under a variety of highly specific
  circumstances.

  The bug occurs when all three of the following
  conditions are met:

  1. DMA single-address read mode access is in
     progress

  2. DMA dual-address mode read access from
     external bus or from peripheral control
     registers is in progress
  
  3. CPU attempts to write to peripheral control
     registers: BSC, DMAC, CPG, RTC, INTC, TMU,
     SCI, SCIF, H-UDI, SDSR, and ASERAM.  However,
     this does not include registers SDMR2 and
     SDMR3 of BSC, TCPR2 of TMU, SCRDR1 of SCI,
     SCFDR2 and SCRDR2 of SCIF, and SDRR of H-UDI.
     Note that these control registers are
     accessed whenever any SH-4 peripheral services
     are accessed, such as the GD-ROM controller.

  Because of the complexity of working around this
  bug, it is highly recommended that developers
  abstain from system-to-system memory DMA. Please
  contact Sega DTS for help on this issue.

- Large static arrays compile slowly
 
  Both CodeWarrior and gcc can take an extremely
  long time to compile some of the large static
  arrays used as textures in the Kamui samples.
  For example, the Fortune demo can take up to 20
  minutes to compile on a P2-300, versus 2 minutes
  for Hitachi C.  We are working with both
  compiler vendors to improve this performance.
  In the meantime, try to avoid recompiling large
  data elements in your application.
  
- Use of IPMaker required

  In previous releases of this development
  software, Sega supplied default versions of
  IP.BIN and IP0000.BIN for use in emulating a
  GD-ROM.  Now, Sega provides the tool (IPMaker)
  to allow you to create your own IP.BIN and
  IP0000.BIN file.

- IPMaker shows garbage text on initial startup

  On US and European installations of Windows 98
  and NT, IPMaker shows garbage text the first
  time it is run.  To configure IPMaker for
  English display, click the Config button, then
  click the English Language Setting button.

- Programs do not run on Set 5.23

  Set 5.23 development hardware is no longer
  supported.  Contact Sega for upgrade
  instructions.

- Kamui sample programs may lose text on composite
  output due to overscan

  Some Kamui sample programs output text to the 
  display in regions that NTSC and PAL consider
  to be overscan regions.  To work around and
  see the invisible text, use a VGA monitor.

- Must quit Codescape before rebuilding a program

  By default Codescape locks the target .ELF
  executable file when a session is open.
  To change this operation, check the box labeled
  "Unlock the Program File (uses a copy)" in the
  "Load Program File" dialog window.

- Return codes from main() are not passed
  through Codescape

  Standard arguments and return values from main()
  are not supported by Codescape.  If a program
  passes through the end of its execution cycle,
  an exception is raised.

- Metrowerks produces "Can't assign register" error
  messages under specific optimization levels

  Under certain conditions, the Metrowerks
  compiler may complain about register allocation
  if the "No optimization" optimization level is
  selected.  To work around, select the "C/C++
  Language Options," and change the Inline Depth
  to "Don't Inline" when turning off
  optimizations.

- 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.

- Shinobi timer usage is confusing

  In Shinobi's syTmrGenXXX functions, the timer
  initialization value is assumed to be negative;
  it is incremented until it reaches zero.

- pvrconv.exe requires textures to be 8x8 or
  larger

  If you require a smaller texture, create it
  within an 8x8 bitmap and reference to the proper
  UV coordinates within the 8x8 bitmap.

- 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.

- Codescape reports "Unable to restore toolbar
  state" the first time it is launched

  This message may be safely ignored.  Codescape
  saves the toolbar state the first time it exits.

- 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.

- Compiling with /optimize=1 changes source-level
  debugging behavior

  When in optimize mode, the Hitachi compiler's
  instruction scheduler reorders instructions
  incompatibly with source-level debugging in
  Codescape.  The most common manifestation of
  this behavior is watched variables that appear
  to change their value at strange times.  This
  behavior is confusing but correct.  Switch to
  assembly debugging or compile with optimization
  off to work around.

- Hitachi C compiler does not parse nested
  comments correctly

  To work around, separate the end delimiters
  by one character:
  
  /*/* this parses correctly */ */
  /*/* this does not parse */*/

- Sound Effects Editor crashes if Sound Box is not
  attached

  Sound Effects Editor crashes with an error 10,
  requiring a soft reset on the Macintosh if the
  HKT-03 is not connected or turned on; this
  occurs when you go to Window->I/O Modules, and
  select an Input Module.

- Source selection dialog under PCM stream convert
  appears doubled (buttons overdraw each other)

  In Sound Data Converter, if you choose Edit->PCM
  Stream Convert, and hit the Source button, the
  resulting dialog appears and then redraws,
  appearing doubled.

  It's possible to partially workaround by
  clicking on the location where the button
  originally appears.

- No way to write to the GD-ROM filesystem

  Use the LibCross fileserver routines for simple
  file I/O.  See also the "Hello" sample located
  in the "Katana\Lib\Libc\Samples" folder or
  look at "QuikTest" in the Kamui sample area.

- "Start a new compilation environment" desktop
  icon incorrect under Windows NT

  The icon seems to behave correctly, however.

- Index file closes after launching a .PDF
  documentation link

  When using Adobe Acrobat, in order to keep the
  Index.pdf file open after choosing a new PDF
  file to read, use the File/Preferences/General
  command.  Deselect the checkbox that reads "Open
  Cross-Document Links in Same Window."

- Hitachi C++ not supported

  Sega does not recommend it for usage yet.
  Use the Metrowerks or gnu compilers
  instead.

3. Other important files
------------------------

\legal.txt: Legal information and disclaimer
            associated with this development
            software.

\readme.txt: This file.

\install.txt: Information on setting up your
	      development system.  All users
	      should read this file.

\changes.txt: Major functionality changes
              since R6.

4. Support options
------------------

We look forward to hearing about problems or
questions that you have regarding Dreamcast
development.  Here's how you can get help or
contact us:

- Printed and on-line documentation

Check the \doc folder for on-line versions of the
manuals and training materials.

- Electronic mail

Developers in the United States may contact
Sega of America's technical support by sending
e-mail to dts@sega.com.  Developers in Europe may
contact Sega of Europe by sending e-mail to
edts@soepd.sega.co.uk.

Your e-mail will be routed to the appropriate
engineer.

- DTS Web site

Sega of America maintains a private Web site for
developers at http://www.dts.sega.com/NextGen/
that contains current development software,
frequently asked questions, and archives of
message bases.  To be granted access to the Web
site, send e-mail from your corporate e-mail
address to dts@sega.com.  You will be
voice-validated for access.

- Listserver

Sega provides an active electronic mail listserver
dedicated to Dreamcast game development.  This
listserver allows you to send mail to a large
number of Sega internal and third-party Dreamcast
developers.  To join the listserver, send e-mail
from your corporate e-mail address to
lyris@sega.com with the words "subscribe elite" in
the body of the message.  You will be
voice-validated for access.

- Telephone

Sega of America's phone number has recently
changed.  In the US, Sega of America's Developer
Technical Support department may be contacted at
(415) 701-4060, 10:00 am to 6:00 pm, Monday
through Friday.  In Europe, Sega of Europe's
Developer Technical Support may be contacted at
+(44) (0) 181-996-4421.