August 15 release RELEASE NOTES
===============================

SUMMARY:
--------
	This release of Ultra 64 (version 2.0F for RCP 2.0) contains
	various problem fixes and enhancements.

	There is no release for RCP 1.0. RCP 1.0 is no longer
	supported. If you are still using an RCP 1.0 system, do not
	install this release on that system.

	Please note the R4300 multiply problem detailed in the 2.0C
	release.  You MUST install the IRIX 5.3 patch provided. Brief
	instructions are included below in Appendix A; full patch
	installation instructions are included in the release notes
	provided with that patch (also included on this tape).

	Appendix B contains the procedure to install and build the
	Ultra 64 release on an IRIX 6.2 machine.

NEW FEATURES:
-------------
	gspSuper3D
	A new microcode version has been created; this microcode
	combines some of the performance optimizations of "turbo" with
	the useful display list of gspFast3D. It has reduced precision
	and no perspective-corrected textures, but is otherwise
	compatible with gspFast3D.

	gspSprite2D
	New microcode has been created which implements automatic
        loading and display of large textured images through a
        'sprite' based metaphor.  The new microcode features are
        explained in the gsSprite2D(3P) man page and demonstrated in
        the new 'spritemonkey' app. The microcode is meant to provide
        an easy to use API for 2D based content which hides the
        difficulties inherent in dealing with the myriad of texture
        formats and sizes which exist as well as taking care of the
        burden of subdividing into 4KB texture chunks.

	This release of the sprite microcode should be considered to
	be in the 'beta' stage of development. This means that all of
	the intended functionality is present, and known bugs are in
	the "won't fix" category unless they cause undue problems for
	developers. Known bugs, limitations and work-arounds are explained 
	in the gsSprite2D(3P)man page. The final version of the microcode 
	will be released on September 30th. Please send in any bug reports 
	or feature requests so that they may be addressed before final 
	code freeze.

        REVISED HOST TO GAME COMMUNICATION
	The method for communicating between the host Indy and the game
	system has been substantially changed. All communication has been
	removed from the GIO interrupts and has been moved to the RDB 
	debug port. This requires the installation of a revised u64 device
	driver. Because of the way the system is automatically reconfigured
	it may be neccessary to reboot the system twice to properly install
	the new device driver.

	The following tools have been rewritten to support these changes: 
	gload, dbgif, gperf, kdebug. midiDmon has not been changed and is
	not supported by this release. It has been replaced by a new tool,
	ie that is written to take advantage of these changes. 

	The hostio libraries have been modified to support these changes.
	Any development tools that use the hostio libraries need to now
	use /dev/u64_data as the device that they open. This is a change
	from previous releases that used /dev/u64. Under the new system 
	it is not feasible to test to see if data is waiting. Consequently, 
	osTestHost() is no longer supported and has been removed from the 
	library. In past releases, all calls to uhWriteRamrom() and 
	uhReadRamrom() had to be matched by osAckRamromWrite() or 
	osAckRamromRead (). This is no longer neccessary, although stub
	routines remain in the library for backwards compatibility.
	All tools that communicate with game applications, are highly 
	encouraged to use the hostio library routines. 

	As a result of these changes osSyncPrintf's performance has been 
	enhanced. osSyncPrintf is a somewhat misleading name now, since
	it can be either synchronous or asynchronous, depending on whether
	your game application has set up an outgoing rdb buffer with a call
	to osInitRdb(). If an outgoing rdb buffer is set up, performance of 
	osSyncPrintf increases dramatically, and the impact of osSyncPrintf
	on game performance decreases dramatically. 

	IMPORTANT NOTE ABOUT osSyncPrintf:
	Because of the changes to osSyncPrintf it is possible for the 
	game to generate printf's faster than the Indy can print them to the
	screen. This problem can manifest itself in several ways. First, if
	too many printf's occur too close together, you will start to see the
	following message in the console:
	"WARNING:u64:Overflow of minor 1 buffer, data_count 524287, length 3"
	If a heavy continual stream of printf's is generated by the game, the 
	Indy will spend all of it's time servicing the interrupts associated 
	with the printing. When this happens, it will appear as if the Indy has
	locked, and you will be forced to reboot your Indy. In cases where large
	amounts of data are being transferred from the game to the host, it is 
	suggested that an alternative method, such as logging, be used. 

	It is possible to monitor the amount of interrupt activity on the Indy
	with gr_osview.

	Games should never disable interrupts while performing osSyncPrintf.

	To implement the change to using the RDB port, rmon has been significantly
	changed. Consequently, rmonPrintf is no longer supported. osSyncPrintf
	should be used for all printing. Because printing is no longer
	part of rmon, it is not neccessary to start an rmon thread to do
	printing. There are only two reasons why you will need an rmon thread:
	to run dbgif with gvd, and to have fault data printed out in the event
	your application faults.

	CHANGES TO guParseRdbDL guParseGbiDL
	NEW DISPLAY LIST TOOL
	NEW ROUTINE FOR PRINTING AUDIO COMMAND LISTS FOR DEBUGGING
	To avoid potential loss of data when printing out large	display lists,
	guParseRdbDL, and guParseGbiDL have been rewritten to use a new
	tool, dlprint, instead of osSyncPrintf. As and added feature, a
	new routine alParseAbiCL has been added to the audio library to
	print audio command lists. Regardless of what type of display/command
	list you wish to print, you start dlprint on the host Indy. Then
	your game application can call guParseRdpDL, guParseGbiDL, or 
	alParseAbiCL. The data will be transferred from the development 
	system, using the hostio routines, and printed to the window by 
	dlprint. In regular mode, dlprint quits after printing a list.
	However, you can start dlprint with a -s to run in servermode. In
	this case, dlprint will continue to run indefinitely. Applications
	should not make simultaneous calls to guParseRdpDL, guParseGbiDL, 
	and alParseAbiCL from different threads. 
	
	INSTRUMENT EDITOR TOOL
	A new tool named "ie" (for instrument editor) has been developed
	to support editing of .inst files.  This release of this tool is
	considered to be an alpha release so there are known bugs and
	problems with this tool.  The final release on September 30th
	will address these problems.  Please refer to the tool's man
	page for a list of bugs and unimplemented features.

	The ie tool actually provides three primary functions.  First, it
	allows editing and auditioning of .inst files.  Second, it
	allows editing and auditioning of effects.  Third, it provides
	MIDI control of the Nintendo64 development board for auditioning
	sequences and for profiling some of the Nintendo64 audio resources.

	As an .inst editor, it acts as a front end to ic, the instrument
	compiler which compiles .inst files into actual Nintendo64 bank
	files that are loaded into the game.  Although, the current level
	of editing is entirely textually based (there are not graphical
	editors in the tool), it provides an easy way to view and edit
	bank resources.

	As a player, it acts as a MIDI sound module which allows trying
	out instruments and effects without compiling the data into a
	game first.  This greatly shortens the bank and effects
	development cycle.

NEW DEMO APPLICATIONS:
----------------------

	'spritemonkey' a new app which demonstrates use of the new
	sprite microcode.  Instructions for the app are printed on the
	terminal from which gload is run.

	'nosPak' is a sample library and program to use the N64
	font data.

MODIFIED DEMO APPLICATIONS:
----------------------

	All applications that had references to rmonPrintf have had them
	changed to osSyncPrintf.

	Simple has been modified to set up an outgoing rdb buffer in the
	development versions. This involves declaring a buffer and passing
	it to osInitRdb().

	The hostio app has been greatly revised to demonstrate how an Indy
	program can communicate with a game application running on the 
	development system using the hostio library. 

PROBLEM FIXES:
--------------

	AUDIO 
	A problem with "trouble when the sound/sequence player is removed", 
	which was fixed in the patch dated May 1 has been incorporated 
	into this release.

	A problem with "reverb", which was fixed in the patch dated
	May 1 has been incorporated into this release.

	A bug in alSynSetFXParam that occurs when you attempt to change the
	low pass filter coef. has been fixed. In previous releases, attempting
	to change this value would have no effect. It should now change the 
	filtering.

	Changed example audio dma code in simple. In the past, if you ran out
	of available buffers, the dma allocation routine would use attempt
	to use a null pointer. Now, if you run out of available buffers, 
	use a previously used buffer. This will cause an unknown sample
	to be used instead of the correct sample, which may sound bad, but
	at least the game won't crash.

	A bug in the "ic" tool that caused the tool to freeze or hang has
	been fixed.  This bug was caused when the .inst file contained
	a large number of objects (over 1024).  Now the number of objects
	is limited only by the available memory.

	GRAPHICS 
	A problem with Popmatrix was fixed.  Previously when a matrix
	was popped and lighting was enabled, the lighting was
	incorrect on geometry drawn after the pop.  This has been
	fixed.

	OS
	A problem with "NMI and video", which was fixed in the patch dated
	May 1 has been incorporated into this release.

	Many improvements to the PFS system (controller memory pack)
	have been incorporated.

	Problem with setting the correct value for the audio frequency 
	divisor in PAL system has been fixed.

FEATURES ENHANCED:
------------------

	AUDIO


	GRAPHICS

	OS
	Additional 14 video modes for the MPAL system are supported in this
	release.


FEATURES NO LONGER SUPPORT:
---------------------------

	midiDmon is no longer supported. It has been replaced by the tool, 
	AudioEditor.

	RCP Hardware 1.0 is no longer supported. You should *not*
	install this release on a RCP 1.0 system.

THINGS TO WATCH OUT FOR:
------------------------

DOCUMENTATION:
-------------

	Many useful suggestions have been incorporated into
	the man pages and documentation, making them more clear.

	A chapter on optimizing the audio memory usage has been added 
	to the Programmer's Manual.

----------------------------------------------------------------------------
CAVEATS
----------------------------------------------------------------------------

Graphics:
--------

Audio:
-----

Operating System:
----------------

	RCP SPEED:
	We now have 4 different speed systems out there

	   a. HW1			50 Mhz
	   b. HW2 (NTSC)		60.85 Mhz
	   c. HW2 (PAL)			62.07 Mhz
	   d. Real game machines	62.5  Mhz
	      (Both NTSC and PAL)

        To have the correct timing for all the systems, makerom has
	been changed to set the right value for different systems. The
	default value is set to 62.5 Mhz. For case b, developers need
	to pass "-C 0" or "-C 60850000 "to makerom.  For those
	developers who still have HW1, they need to do "makerom -C
	50000000"


Demos:
------

Tools:
------

Debugger:
--------

----------------------------------------------------------------------------
APPENDIX A
----------------------------------------------------------------------------

Important Things from Previous Releases That You Must Know:
----------------------------------------------------------

	You need 'sgitcl' to run the application 'spin'. This
	package is included on 5.3 distribution CD's, and is
	included with this release for convenience. It is
	*not* installed when you do a default ultra install.

	You *must* install the IRIX patch patchSG0001118 to your
	system. This patch fixes your C compiler and Assembler
	in order to work around an R4300 problem. This patch is
	included with this release for convenience. It is
	*not* installed when you do a default ultra install.
	See patch1118/patchSG0001118/relnotes/ch1.z for complete
	installation instructions. Note: You must select this
	patch for install. The default behavior for 'inst' is to
	not install patches. You must request this patch to be
	installed explicitly. (see man inst for more information)


----------------------------------------------------------------------------
APPENDIX B
----------------------------------------------------------------------------

Procedure to install and build the ultra environment on IRIX 6.2 machine
------------------------------------------------------------------------

	The procedure below describes how to install and build the 
	Nintendo64 (also known as Ultra64) development environment on an 
	IRIX 6.2 Indy system. The idea is to have a toolroot directory on 
	this 6.2 machine that contains IRIX 5.3 development tools (ie., 
	compilers, linkers, etc.). The SGI development environment makes 
	extensive use of two important environment variables: TOOLROOT 
	and ROOT. If these variables are not defined, the system uses the
	root "/" directory as default. For example, you will find many 
	references to these two variables in the /usr/include/make/commondefs 
	file. The build environment references these two variables to find 
	tools (ie., compilers, assemblers, linkers), header files, and 
	libraries. The steps to create a working 5.3 toolroot tree on a 
	6.2 machine are described below.


	1)  Login in and become superuser on an IRIX 6.2 Indy workstation.

	    $ login root

	2)  Create a toolroot directory to install all IRIX 5.3 development
	    tools. For example, let's use "/u64_toolroot" as the 
	    5.3 toolroot directory.

	    # mkdir /u64_toolroot

	3)  Run the "inst" program to install the complete set of 5.3 
	    development tools (from CDs) onto this new toolroot directory.
	    Please see the man page on inst(1M) for more info.

	    # inst -f /CDROM/dist -r /u64_toolroot

	4)  From the "inst" list menu, select the following products for 
	    installation: c_eoe, c_dev, c++_eoe, c++_dev, compiler_eoe, 
	    compiler_dev, dev, dmedia_eoe, eoe1, eoe2, gl_dev, and 
	    compiler patch patchSG0001118. 

	    The compiler patch was included in the last Ultra64 release 
	    tapes. The list below contains all the 5.3 products installed on 
	    our test 6.2 Indy system.
	   
	5)  Now, install the new Ultra64 release onto the toolroot. Please 
	    note that only release 2.0F and later have the proper IRIX 6.2 
	    kernel driver for the Ultra64 development board. 

	    # inst -f <source> -r /u64_toolroot

	    where <source> could be a DAT tape or a remote workstation that
	    contains the Ultra installable images.
	
	6)  From the "inst" list menu, select ultra for installation.

	7)  Once the ultra installation is completed, you should see 
	    messages similar to these displayed on your shell window:

	    ULTRA-64 SYSTEM INSTALLATION PROGRAM

	    IRIX 6.X detected...
	    Copying /u64_toolroot/usr/lib/PR/install/u64_6.2.o to 
                /usr/cpu/sysgen/IP22boot/u64.o
	    Copying /u64_toolroot/var/sysgen/master.d/u64 to 
	        /var/sysgen/master.d/u64
	    Copying /u64_toolroot/var/sysgen/system/u64.sm to 
	        /var/sysgen/system/u64.sm
	    Installation completed (...)

	    The above messages simply notify you that all the necessary 
	    kernel driver files have been copied from the toolroot directory 
	    to the proper locations on the 6.2 system.

	8)  Quit the "inst" program

	9)  Rebuilt the kernel to incorporate the new Ultra64 driver by 
	    running the "autoconfig" program.

	    # autoconfig

	10) Reboot the system

	    # reboot

	11) When the system is booting up, if it finds the Ultra64 development
	    board, the following message will be displayed on the console
	    window.

	    u64 (IRIX 6.2): board found at address 0xbf400000

	12) Now, to build the Ultra64 demo applications, you can log back 
	    into the system as any user that have write-access to the 
	    toolroot directory.

	13) Set the TOOLROOT and ROOT environment variables to the toolroot
	    directory. For example,

	    For C shell:
		$ setenv TOOLROOT /u64_toolroot
		$ setenv ROOT /u64_toolroot

	    For Korn shell:
		$ export TOOLROOT=/u64_toolroot
		$ export ROOT=/u64_toolroot

	14) Go to the "simple" demo directory and build this application.

	    $ cd $ROOT/usr/src/PR/simple
	    $ make

	    You should notice (from the make messages) that all the tools 
	    (ie., cc, ld, makerom), header files, and libraries are
	    referenced from the toolroot directory. Therefore, if you have 
	    installed all the necessary 5.3 development tools correctly, 
	    this make should complete successfully.

	15) Now, to test the modified kernel, run the "simple" application 
	    by loading the rom image onto the development board

	    $ gload simple/rom

	16) If you see a spinning SGI cube on the TV set, then you've
	    successfully created an IRIX 5.3 toolroot on a 6.2 machine.

	17) To honor the TOOLROOT and ROOT environment variables, your build
	    environment should use the common defines and rules as specified 
	    in the /usr/include/make/commondefs and 
	    /usr/include/make/commonrules.


-----------------------------------------------------------------------------
List of IRIX 5.3 products installed on our test IRIX 6.2 Indy workstation:
-----------------------------------------------------------------------------

Target: /u64_toolroot/
I = Installed, R = Removed

   Name                 Version     Description

I  c++_dev              1021572035  C++, 4.0
I  c++_dev.hdr          1021572035  C++ Headers
I  c++_dev.hdr.lib      1021572035  C++ Library Headers
I  c++_dev.sw           1021572035  C++ Software
I  c++_dev.sw.c++       1021572035  C++ Compiler
I  c++_dev.sw.lib       1021572035  C++ Libraries

I  c++_eoe              1021572033  Standard Execution Environment (C++, 4.0)
I  c++_eoe.sw           1021572033  Standard Execution Software
I  c++_eoe.sw.lib       1021572033  Standard Execution Libraries

I  c_dev                1021572033  C, 3.19
I  c_dev.hdr            1021572033  C Headers
I  c_dev.hdr.lib        1021572033  C Library Headers
I  c_dev.sw             1021572033  C Software
I  c_dev.sw.c           1021572033  C Compiler
I  c_dev.sw.copt        1021572033  C Scalar Optimizer
I  c_dev.sw.lib         1021572033  C Libraries
I  c_dev.sw.util        1021572033  C Utilities

I  c_eoe                1021572033  Standard Execution Environment (C, 3.19)
I  c_eoe.sw             1021572033  Standard Execution Software
I  c_eoe.sw.lib         1021572033  Standard Execution Libraries

I  compiler_dev         1021572033  Base Compiler Development Environment, 5.3
I  compiler_dev.hdr     1021572033  Base Compiler Headers
I  compiler_dev.hdr.lib 1021572033  Base Compiler Headers
I  compiler_dev.sw      1021572033  Base Compiler Software
I  compiler_dev.sw.base 1021572033  Base Compiler Components
I  compiler_dev.sw.dbx  1021572033  Base Compiler dbx Debugger
I  compiler_dev.sw.ld   1021572033  Base Compiler Loader
I  compiler_dev.sw.lib  1021572033  Base Compiler Libraries
I  compiler_dev.sw.perf 1021572033  Base Compiler Performance Tools
I  compiler_dev.sw.util 1021572033  Base Compiler Utilities

I  compiler_eoe         1021572035  IRIX Standard Execution Environment,
(Compiler, 5.3)
I  compiler_eoe.sw      1021572035  IRIX Standard Execution Environment
Software
I  compiler_eoe.sw.cpp  1021572035  Source Code Preprocessor
I  compiler_eoe.sw.lboot  1021572035  Kernel lboot Software
I  compiler_eoe.sw.lib  1021572035  Base Execution Libraries
I  compiler_eoe.sw.unix 1021572035  IRIX Execution Environment

I  dev                  1021572036  Development System, 5.3
I  dev.hdr              1021572036  Development Headers, 5.3
I  dev.hdr.lib          1021572036  Development Environment Headers
I  dev.sw               1021572036  Development Software, 5.3
I  dev.sw.lib           1021572036  Development Libraries
I  dev.sw.make          1021572036  Parallel Make Utilities

I  dmedia_eoe           1022162520  IRIS Digital Media Execution Environment,
5.5
I  dmedia_eoe.data      1022162520  IRIS Digital Media EOE Data Files
I  dmedia_eoe.data.soundscheme  1022162520  SoundScheme Data Files
I  dmedia_eoe.sw        1022162520  IRIS Digital Media Software
I  dmedia_eoe.sw.common 1022162520  Common Execution Environment Components
I  dmedia_eoe.sw.compression  1022162520  Compression Execution Environment
I  dmedia_eoe.sw.midi   1022162520  MIDI Execution Environment

I  eoe1                 1021572036  IRIX Execution Environment 1, 5.3
I  eoe1.man             1021572036  IRIX Execution Environment Man Pages
I  eoe1.man.relnotes    1021572036  IRIX Release Notes
I  eoe1.man.unix        1021572036  Basic IRIX Man Pages
I  eoe1.sw              1021572036  IRIX Execution Environment Software
I  eoe1.sw.gfx_lib      1021572036  Graphics Execution Libraries
I  eoe1.sw.irix_lib     1021572036  IRIX Execution Libraries
I  eoe1.sw.unix         1021572036  IRIX Execution Environment

I  eoe2                 1021572036  IRIX Execution Environment 2, 5.3
I  eoe2.sw              1021572036  IRIX Execution Environment Software
I  eoe2.sw.imagetools   1021572036  Graphics Library Image Tools

I  gl_dev               1021572036  Graphics Library Development System, 5.3
I  gl_dev.sw            1021572036  GL Software
I  gl_dev.sw.gldev      1021572036  GL Development Environment

I  patchSG0001118       1029999901  Patch SG0001118: workaround for R4300
silicon users (nintendo developers)
I  patchSG0001118.compiler_dev_sw  1029999901  Base Compiler Software
I  patchSG0001118.compiler_dev_sw.base  1029999901  Base Compiler Components

I  ultra                1022149600  Ultra 64 Development Environment, 2.0F
I  ultra.dev            1022149600  Ultra 64 Development Environment Software
I  ultra.dev.base       1022149600  Ultra 64 Base Development
I  ultra.dev.demo       1022149600  Ultra 64 Demonstration Software
I  ultra.man            1022149600  Ultra 64 Development Environment Man Pages
I  ultra.man.base       1022149600  Ultra 64 Base Development Man Pages

-----------------------------------------------------------------------------