readme.txt
August 17, 1998

This document contains late-breaking and important
information about this Katana development
software.  Please take a moment to read it.

1. Purpose
----------

This release of development software is intended
to allow developers an early preview of the API
functionality in Katana.  The current development
system differs significantly from the final Katana
system, and the performance of this system is
below that of the final system.  In addition,
significant bugs exist in this development
environment for which no workarounds are currently
known.

With this development system, developers can
explore the SH-4 and begin optimizing code for it.
Also, developers can work with an early version of
Katana's filesystem.

Sega is in the process of redesigning Katana's
low-level device drivers based on developer
requests.  Developers that use Kamui for graphic
display should keep in mind that these interfaces
will be rewritten to correspond with final
development hardware.  The new driver interface
will allow developers to access the hardware
at an extremely low level.

Developers that intend to write to Set4's Kamui
layer should plan to spend more time porting to
the final development system's graphic driver API.
Sega will continue to support development using
high-level APIs, such as the Ninja library.  These
APIs will require less porting effort once final
hardware becomes available.  Sega's new graphic
driver interface is currently under development.
We will keep developers informed via the Hardcore
listserver as lower level APIs become functional.

2. Known problems
-----------------

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.

2.1 Installation
----------------

- New ASPI driver is required

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

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

  This driver is required on both Windows 95 and
  Windows 98.

- PC with SCSI hard drive fails to boot when Set4
  system is connected

  We have experienced various crash conditions
  which can cause a Set4 system to put invalid
  data on the SCSI bus, causing other SCSI devices
  on that bus to crash.  Therefore, do not attempt
  to share the SCSI controller with any PC hard
  drives except for the GD-ROM filesystem built
  into the Set4.

- Adaptec 2940 UW SCSI controller highly
  recommended

  Sega recommends dedicating an Adaptec 2940 UW
  type SCSI controller to the Katana development
  system.  Other versions of Adaptec controllers
  may work with Set4; however, one developer found
  incompatibilities with the Adaptec 154x models.
  If the Codescape debugger cannot detect the Set4
  system properly, and no other device conflicts
  or problems exist, swap the existing SCSI
  controller with an Adaptec 2940 UW.

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

  If you need to use both partitions of the GD-ROM
  emulator, compile your code under Windows 95 or
  Windows 98.

2.2 Low-level graphical interface
-------------------------------

- Trilinear mipmapping, YUV textures, palettized
  textures not supported

  For this release, use bilinear filtering with
  mipmaps instead.

2.3 Codescape
-------------

- Codescape does not allow setting breakpoints in
  files that are out of current scope

  You can set breakpoints in a source file only
  if that file is in the current scope.

- Must quit Codescape before rebuilding a program

  Codescape locks the target .ELF executable file
  when a session is currently executing.  Make
  processes that attempt to write this .ELF file
  will fail.

  One workaround is to use the Build... command in
  Codescape to do all building.  The
  Build... command correctly releases locks on
  loaded .ELF files.  This requires an .env file
  to be present in the session directory to set
  environmental variables.  See the Ninja "future"
  sample application for an example of an .env
  file.

- Drag and drop of files into Codescape workspaces
  is unreliable

  Under various circumstances, inserting and
  changing the location of files into Codescape
  workspaces does not give the desired result.
  Dragging and dropping complex directory
  structures, or adding to an existing directory
  within a workspace, seems to be unreliable.

  To verify that a drag and drop operation gave
  the intended result, save the current session
  and reopen it within Codescape.

  As of this writing we are seeking a repeatable
  drag and drop sequence that exhibits this
  behavior.  Please let us know if you've
  discovered one.

- Codescape does not allow saving the current
  session over current session name

- Codescape cannot find the debugger when DACheck
  can

  This problem occurs when outdated firmware is
  present.  Make certain to reflash both the
  GD-ROM emulator and the debug adapter with
  DACheck when installing this software.

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

  This error may be safely ignored, as Codescape
  saves the toolbar status the first time it
  exits.

- End of program execution in Codescape does not
  return control to Codescape

  Debugging does not automatically terminate when
  the end of program execution is reached.  You
  can stop debugging manually with the "Stop"
  command.

- exit() codes in Katana are not propagated to
  Codescape

  Error codes occuring within a Set4 program are
  not returned to the caller.

- Key presses within Codescape are occasionally
  dropped

  This problem was recently fixed in the included
  version of Codescape.  Please contact us if you
  notice this behavior.  

2.4 GD Workshop
---------------

- Reflashing target without passing DACheck tests
  may make development system unbootable

  One developer has made their development system
  unbootable.   After crashing the target, the
  developer immediately attempted to reflash
  the target.  Because the target was in an
  unknown state, the target was only partially
  reflashed and as a result the EPROM was
  unusable.

  In general, if the target system does not pass
  its respective DACheck tests, the system
  cannot be reflashed.  Try a hard reset first
  before executing the DACheck tests.

- GD Workshop must be restarted between creating a
  project and inserting boot and CDA files

  If you insert files to tracks 1 or 2, the file
  may appear to copy but may not be loaded into
  the GD-ROM image.  Closing the GD Workshop door
  can generate the message that tracks 1 and 2
  must have at least 4 seconds of data.

  To workaround, restart GD Workshop.

- Closing CD drawer in GD Workshop too quickly
  freezes GD Workshop for 30 seconds

  To workaround, wait for a hard reset to complete
  in GD Workshop before closing GD Workshop's CD
  drawer.

- Not obvious how to insert a file into a GD
  Workshop project

  Insert a file into a GD Workshop project by
  dragging and dropping it into the workspace
  window.

2.5 Graphic tools
-----------------

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

- pvrconv.exe .bmp alpha values reversed

  White is a transparent color to the pvrconv tool
  if the file input type is .bmp .  

- pvrconv.exe 'outpath' parameter does not work
  as documented

- 3DSMax R2 textures generated with incorrect
  mipmap levels

  Mipmapped .pvr files generated by the 3D Studio
  Max R2 plugin do not have proper mipmaps
  created.  Ninja works around this issue by
  regenerating mipmaps automatically as the .pvr
  file is loaded.  However, the Kamui driver does
  no such regeneration.  To workaround, generate
  mipmap levels in the .pvr texture manually with
  the pvrconv utility.

- lwtonj crashes if more than 32768 vertices
  per model

  Ninja is internally limited to 32768 vertices
  per model.  If you require more vertices, use
  multiple models.

- woman model has artifacts

  One of the sample models, woman, has modelling
  errors in the face area that cause artifacts.

2.6 SH-4 processor
------------------

- Memory read paired with delayed branch can 
  retrieve incorrect value

  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

  The following instruction sequence can return
  incorrect results:

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

2.7 DACheck
-----------

- DACheck fails performance tests on older
  Set 4 systems

  Your Set 4 system probably needs to have its ROM
  reflashed.  Make certain the most recent copy of
  genie.fsh is applied to your system.

2.8 Hitachi SH-4 C compiler
---------------------------

- Compiling with /optimize=1 removes ability to
  set breakpoints on some lines of code

  When in optimize mode, the SH-4 compiler's
  instruction scheduler reorders instructions
  incompatibly with source-level debugging in
  Codescape.  Switch to assembly debugging or
  compile with optimization off to work around.

2.9 Example programs
--------------------

- future demo displays garbage on right side of
  screen

  This is a symptom of a hardware bug on early
  versions of Set4 hardware.  Contact Sega for
  repair information.

- reload01 sample program corrupts texture
  
  Due to a timing error in Kamui, the reload01
  texture is improperly displayed.  We will
  post information about this bug to the
  Hardcore listserver as it becomes available.

2.10 Documentation
------------------

- Codescape soft documentation updated from printed
  documentation

  The soft-copy documentation in this release
  includes information on using the SH-4 profiler.
  This information is not present in the printed
  version of this manual.  Refer to the soft
  version for updated information.

- Dongle unnecessary for Codescape

  Page 6 of the Codescape User's Manual states
  that a dongle is necessary in order to
  install Codescape.  This restriction has been
  eliminated in the version included in this
  release.

2.11 Incomplete or missing functionality
----------------------------------------

- No C++ support

  Developers experimenting with the early C++
  compiler will soon find that templates, new and
  delete operators, iostreams, and anonymous
  structs are not implemented yet.

- No printf() support

- No way to write to the GD-ROM filesystem 
  in Katana code

  Developers requiring program output can use
  Ninja's njPrintC() function or they can write
  directly to memory and use the DATool program to
  view this memory after execution.

- No sound, modem/network, or CD burning support

  These peripherals will be supported in a future
  release of development system.

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.

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

We look forward to hearing about problems or
questions that you have regarding Katana
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.

- Electronic mail

Developers in the United States and developers
working with Sega of America should send e-mail to
dts@sega.com .  Developers in the United Kingdom
and developers working with Sega of Europe should
send e-mail to edts@soepd.sega.co.uk .

Your e-mail will be routed to the appropriate
engineer, and you can then communicate directly
with that engineer.

- DTS Web site

We maintain a private Web site at
http://www.dts.sega.com/NextGen/hardcore that
contains current development software, frequently
asked questions, and message-based discussion
forums.  We host regular technical chats via a
Web-based interface on a variety of Katana topics.
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 to the Web site.

- Listserver

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

- Telephone

In the US, Sega of America's Developer Technical
Support department may be contacted at (650)
802-1719, 10:00 am to 6:00 pm, Monday through
Friday.  In Europe, Sega of Europe's Developer
Technical Support may be contacted at +(44) (1)
181-996-4421.










