=======================================================================
Jaguar Developer Weekly      August 25, 1995               Vol.1, No.10
=======================================================================

Jaguar Developer Tools & Windows 95
-----------------------------------
Developers who upgrade their PC to Windows 95 may have questions
regarding the operation of the various tools in the Jaguar Developer's
Kit.

Atari's Jaguar Developer Support department has been using pre-release
versions of Windows 95 for several months now.  While some tools did
have problems at first, we are not aware of any problems with any of the
current versions of the Jaguar development tools.  If you have problems,
you may simply need to update to the current versions of the tools.

Keep in mind that while the tools are known to work under Windows 95,
they do not take advantage of new features such as long filenames.

Should you have problems that you suspect are related to Windows 95,
please make sure that you are using the most recent version of the
Jaguar tools involved, and if the problem persists, then contact Atari
immediately.



New CD Track File Creation Utility
----------------------------------
A new tool designed to quickly and easily create CD Track files ready
for CD mastering or for using with the Jaguar CD Emulator has been added
to the Jaguar Developer Kit.

MAKETRK takes a single file or a batch list of files and creates a new
CD Track File with the proper Jaguar CD track header and tailer
information.  It also allows you to specify the 4-byte code used to
create the 64-byte partition marker used to distinguish the beginning of
the data from each of your source files.

The MAKETRK utility writes out a MADMAC source code file containing a
data table with an entry for each of your original files.  Each entry
specifies the track number, block offset, length, and partition marker
for one of your source data files.  It also writes out both MADMAC and C
include files with definitions that can be used in your programs to
reference the entries in the table.

The MAKETRK utility is an MSDOS tool, but a more flexible and powerful
tool that runs under Windows 95 is in development and is expected to be
released in the near future.

The MAKETRK utility can be obtained by downloading the CDROM.ZIP archive
from the Atari Software Development BBS or the Jaguar Developer areas of
the Atari Gaming Forum on Compuserve.


Use Atari's Standard Startup Code...
------------------------------------
Developers who are not already using Atari's standard startup code with
their projects need to be aware that failure to do so may result in
their software failing to work properly on the next-generation Jaguar
machines currently in development.

Atari's standard startup code initializes the Jaguar GPU & DSP,
interrupt vectors, and other hardware in a way that is known to be safe
on current and future machines.  It displays a simple opening graphic,
and jumps to your main program code, which would display any additional
title screens, play a introductory Cinepak film, or whatever else is
appropriate for your program.

Avoid making changes to the startup code.  In most cases, the only
acceptable modification to the startup code is changing the startup
picture.  If you think further modifications are required, please bring
them to Atari's attention at the earliest possible stage of development
so that either they can be approved or an alternate method found.

Atari's startup code can be found in the SOURCE.ZIP archive available
online.  After you've decompressed the archive contents, the source
files will be in the \JAGUAR\SOURCE\STARTUP directory.



And Use Our Current EEPROM Code Too!
------------------------------------
Atari supplies standard routines for accessing a Jaguar cartridge's
EEPROM to store or retrieve high score information, user preferences,
etc.  If you are not using Atari's most current version of these
routines, then your program may not function correctly with new
cartridge EEPROM hardware which will soon be used on Jaguar cartridges.

The EEPROM routines are included in the SOURCE.ZIP archive, available
for downloading online.  The latest revision is from March 14, 1995.
This extracts to the directory \JAGUAR\SOURCE\EEPROM.


CD BIOS v4.5 Update
-------------------
The Jaguar CD BIOS has been updated to version 4.5.  Download CDROM.ZIP
to get the update.  Changes include:

• Added error reporting to CD_switch.  If the disc during
  CD_switch has a data read or other problem causing an unreadable
  directory, this is reflected as a negative number in the first word of
  the Table of Contents.

• Changed the sense of err_flag.

• Changed the time-out scheme on Table of Contents in CD_switch.



Jaguar CD Error Codes
---------------------
There has been some changes and clarifications regarding exactly how
error codes and error detection work with the Jaguar CD.  This has been
a bit of a moving target with previous versions, but it has now
stabilized.  As of the new version 4.5, this is the way it works:

• The err_flag variable is set to zero when an error occurs, and
  set to one when no error occurs.

• The only CD BIOS functions that set the err_flag variable are
  CD_ack and under the right circumstances, the functions listed below:

CD_mute
CD_paus
CD_spin
CD_stop
CD_umute
CD_upaus

Note that these six functions set err_flag only when your program has
passed a value of 1 in register d0 to specify that the CD BIOS should
wait for completion before returning control to your program.

• The CD_ptr function will set register a1 to zero when no error
  has occurred.  Otherwise, it is set to the approximate address of
  the block containing the most recently detected read error.  If the
  high bit is set, then a seek error occurred.

• The CD_read function does not set the err_flag variable.  Detect
  read errors using the CD_ptr function as described above.

• If an error occurs with the CD_switch function, the first long
  word entry in the CD Table of Contents will be set to a negative
  value.


The list below names each CD BIOS function and the method used to return
error information.

CD_ack -- Sets the err_flag variable.

CD_getoc -- Sets the 1st word in TOC to a negative value.

CD_init -- No error codes.

CD_initf -- No error codes.

CD_initm -- No error codes.

CD_jeri -- No error codes.

CD_mode -- No error codes.

CD_mute -- Sets the err_flag variable if you set register d0 to wait
for completion.

CD_osamp -- Sets the err_flag variable.

CD_paus -- Sets the err_flag variable if you set register d0 to wait
for completion.

CD_ptr -- Returns a pointer to the error block address in register a1.

CD_read -- No error codes.

CD_setup -- No error codes.

CD_spin -- Sets the err_flag variable if you set register d0 to wait
for completion.

CD_stop -- Sets the err_flag variable if you set register d0 to wait
for completion.

CD_switch -- Sets the 1st word in TOC to a negative value.

CD_umute -- Sets the err_flag variable if you set register d0 to wait
for completion.

CD_upaus -- Sets the err_flag variable if you set register d0 to wait
for completion.

CD_uread -- No error codes.

Note that the err_flag variable may be changed by functions that are
not documented as returning an error code.  Ignore this, because this
behavior will most likely change in the future.

(Note: The previous issue said "long word" instead of "word" in
reference to the errors returned by the CD_switch and CD_getoc
functions.  These set the first word value in the CD's TOC to a
negative value, not the first long word value.)


CD BIOS Notes
-------------
When an error value appears in register a1 after a CD_ptr call, you
should check that the address in register a0 is equal to or greater than
the buffer start address given in the last CD_read.  If not, a CD_ack
should be issued prior to any other CD BIOS call.  Also note that the
CD_ptr function sets the high bit of register a0 when a seek error
occurs.

The CD_read function uses registers a0, a2, and d1.


Multiple Sessions on Jaguar CD
------------------------------
The ideal Jaguar CD has a total of two sessions.  Session #0 contains
only standard Red Book audio tracks.  Session #1 contains your boot
track as well as all your other code and data files.

Using additional sessions may be useful at times during the development
process, but serves no real purpose on a production disc.  Using more
sessions increases the time needed to master the disc and the time it
takes to start up and go through the encryption verification process on
an end-user's system.


Don't Use More Than 1 File Per Track With Jaguar CD Emulator
------------------------------------------------------------
It is highly recommended that you specify only one file per CD track
when using the Jaguar CD Emulator on the Falcon030 computer.  This file
should be the same as what you would use when mastering a CD, complete
with track header and tailer, and 64-byte sync markers (a unique 4 byte
pattern repeated 16 times) in front of each distinct piece of data (such
as contents of the individual files used to create the track file).

Using one file per track insures that the behavior of the emulator will
be as close as possible to a real CD.  Using multiple files per track
cause the emulator to exhibit unavoidable differences in behavior
compared with an actual CD, which can cause major problems when you try
running your program from a real CD.

Here's a basic explanation of why using multiple files per track in the
emulator is a bad idea.  The emulator reads data from the hard disk at
the same time it sends data to the Jaguar.  The timing for this is very
tight, and when it gets to the end of one file, it doesn't have enough
time to start reading from the next one.  It must send the data on time
or it will cause an error in the I2S connection to the Jaguar.  To avoid
this, it sends zeroes until it can start reading the next file.  The
result is that file sizes get rounded up, which doesn't happen when you
combine files together into a raw track file to master a CD, and this is
where things go wrong.  The position of each file within a track
changes, as does the overall amount of data you must read to load the
entire track in one step.

The solution is to use only one file per track in the first place.  The
one file used for each track should be ready for CD mastering so that
the difference between reading the data from the emulator or from a real
CD will be negligible.  Also, when you want to master a CD, you won't
have to do anything additional to prepare the files.



Jaguar ProController
--------------------
Scheduled to begin production in September, the Jaguar ProController is
an enhanced version of the standard Jaguar joypad that is designed
especially for games that demand more control than a standard
three-button controller.

The ProController features three new primary fire buttons labeled "X",
"Y", and "Z" to complement the "A", "B", and "C" buttons from a standard
joypad.  Another new addition is a pair of "Left" and "Right" direction
buttons at the top of the controller.

From your Jaguar programs, reading the new buttons is very simple,
because they map directly to keys on the numeric keypad, as follows:

	X = "9"
	Y = "8"
	Z = "7"
	Left = "4"
	Right = "6"

To see if the "X" button is pressed, for example, you simply check the
same bit as you would for the "9" key on the keypad.

We'll have more information about the Jaguar ProController, including
developer availability, in an upcoming issue.


New BBS Number
--------------
The new Atari Software Development BBS is now up and running as a two
line system.  The new number to call for both lines is (408) 541-9164.
The old phone number is no longer active.  The new line does not go
through the rest of Atari's phone system, so it should be more reliable
for those callers who have had noise-related connection problems in the
past.


When Signing Onto the BBS For the First Time
--------------------------------------------
The very first time you log onto the Atari Software Development BBS,
you won't have access to the message bases or the file libraries with
the updates to the Jaguar developer kit files.  This is because the
Atari SDBBS is a closed system for developers only, and everybody who
calls must individually be given clearance before they can access
these areas.

To get full access, it is imperative that you leave a detailed message
to the sysop that includes your full name, your company, telephone
number, and the name of the Jaguar project you are working on.

Failure to provide the proper information will result in your access
being delayed indefinitely.  So if you log on and leave a message that
just says something like "Hi, I'm Joe and I need access to the Jaguar
developer areas", you won't get it, because we will not have any means
of verifying who you are.  On the other hand, if you do leave the
proper information, full access should be granted within a day or two
at most.



Christmas is coming...
----------------------
Developers and publishers should keep in mind that all cartridge-based
products must be fully-tested and released into production by October 5, and
CD-based products by October 31, in order to insure that your product is
shipping in time for the Thanksgiving sales weekend, the beginning of the
Christmas selling season.  Remember to allow at least 4 weeks for final
testing.



Jaguar Tool Updates
-------------------
The Jaguar Developers Kit tools and related files listed below have been
updated in the last month.  You can download the latest versions from
the Atari Software Development BBS or from the Jaguar Developer library
in the Atari Gaming forum on Compuserve.

Jaguar CDROM Files — August 23, 1995.  This features the new MAKETRK
utility (see article) as well as a new version of the CD BIOS (v4.5)
as well as some changes to the included CDROM sample reader program,
and changes to the CD Boot Emulator.  Download CDROM.ZIP

LS Directory Lister — August 22, 1995.  The LS directory lister
utility has been updated to work better with directories containing
large numbers of files.  Download UTILPC.ZIP.

Jaguar System Include Files — August 8, 1995.  See the article in this
issue for information.  Download SOURCE.ZIP

Jaguar Artwork Viewer — August 4, 1995.  This new version adds the
ability to control your horizontal resolution, and has improved
communications reliability.  Download ARTWORK.ZIP

Flash ROM Utility — July 27, 1995.  You can now hit Control-C to abort a
download and return to the DOS prompt.  Download UTILPC.ZIP.

Jaguar Graphics Tool — July 24, 1995.  Several minor bugs reported by
Jaguar Developers have been fixed.  Download ARTWORK.ZIP.

Jaguar NVRAM Simulator — July 21, 1995.  The NVRAM simulator uses the
Alpine board to emulate the Jaguar Memory Track cartridge, an add-on for
the Jaguar CD that allows CD game titles to save their user options,
high score lists, saved-games, and other information.  The archive has
been updated with additional documentation.  Download JAGLIB.ZIP for the
complete package.



Dev Kit Roadmap
---------------
The tools, sample source code, libraries, and other components of the
Jaguar Developers Kit are updated frequently.  To keep track of what's
new, see the file ROADMAP.TXT that is posted online on the Atari
Software Development BBS and in the Jaguar Developer library in the
Atari Gaming forum on Compuserve.  This file is updated and reposted
whenever any of the standard distribution archives from the Jaguar
Developer's kit is updated.



If you've missed previous issues...
-----------------------------------
Then it's possible that we may not have a current fax number for you.
Just in case, please contact us with your current address, telephone and
fax numbers.  Also, consider that the better solution would be to
subscribe to the Jaguar Developer Weekly Via EMAIL.

The preferred method for Atari to send out the Jaguar Developer Weekly
is via EMAIL, but unfortunately, we don't have a database of everybody's
EMAIL addresses.  If you have a current Internet or Compuserve EMAIL
address, please send a message to mfulton@atari.com so that we can add
you to the list of developers that receive the Jaguar Developer Weekly
via EMAIL instead of fax.

What you get each week will be the ASCII text of the issue, plus an
online readable version.


Note: The ASCII version of the Jaguar Developer Weekly is now formatted
to 72 columns width since we got a few complaints that the wider lines
on earlier versions did not come through very well.  If you have
problems with this formatting, please let us know.



Jaguar Developer Technical Notes
--------------------------------
Item: JDEV0005
Date: August 25, 1995
Re:   Jaguar CD Mastering

Keep in mind that CD Writers are evolving and will not neccesarily work
correctly out of the box.  It’s likely you will have to fiddle around
with your system before things work correctly.

You absolutely must adhere to the CD layout described in the “Jaguar
CD-ROM” chapter of the Jaguar Developer’s documentation.  This is not a
suggestion, it is a requirement.  Failure to follow this format will
cause your program to fail on a production system, even if it does work
on a developer model Jaguar CD player.  Remember to always use the
proper track header and tailer and keep in mind that the boot code is
always the first track of the second session.

All tracks of a Jaguar CD are written in “CD-DA” format using
Motorola-style byte ordering.  The frame size is 2352 bytes with an
“audio” sub-code.  Overall, the Atari Jaguar CD standard is very close
to what Sony, Phillips, and Microsoft named “CD Plus” (Phillips Blue
Book proposal 3/95).

1.  Different combinations of CD Writer and CD mastering software have a
different approaches to handing small files.  Tracks smaller than 1
megabyte in length should be padded with zeroes at the end (after the
track tailer) to increase their size to 1 megabyte.  Otherwise the
information can get garbled.

2.  Some combinations of CD Writer and CD mastering software have been
known to insert a leading word (two bytes) with a value of zero in front
of each track.  This causes Jaguar to fail to read the data on a long
boundary.  At a minimum, this means your program cannot boot.  A simple
and proven workaround is to insert another dummy word of zero at the
start of the track file, before the Atari track header.

3.  Some writer/software combinations have been known to perform
byte-swapping on the date before writing it to the CD.  This renders the
CD useless for Jaguar, unless you’ve previously byte-swapped your data
to account for this.  This may be configurable in your CD mastering
software.

Here is a current list of Writer/Software/BIOS combinations that have
been tried by Atari, including the problems noted and the required
workarounds (if available):

CD Writer/BIOS Version Combinations:
------------------------------------
A — Phillips CDD522, BIOS v1.00		
B — Phillips CDD522, BIOS v1.06		
C — Plasmon RF4100 BIOS v1.28		
D — Yamaha CDR100 BIOS v1.06		
E — Yamaha CDR100 BIOS v1.09		
					
CD Mastering Software
---------------------
1 — WinOnCD Pro 2.13
2 — WinOnCD ToGo 1.3
3 — Easy CD Pro & MM 3.0
4 — WinOnCD Pro 2.13, w/ WR_YAM.DLL 4/5/95
5 — WinOnCD ToGo 1.3, w/ WR_YAM.DLL 4/5/95
6 — disComposer V2.0beta
7 — WinOnCD Pro 2.13, w/ WR_YAM.DLL 6/7/95
8 — WinOnCD ToGo 1.3, w/ WR_YAM.DLL 6/7/95

-------------------------------------------------------------
CD Writer|CD	   |Inserts| Does |
& BIOS   |Mastering|Garbage| Byte |
version	 |Software |Word   | Swap | Other Problems
-------------------------------------------------------------
   A	     1        No     No**    OK
   B	     1        Yes    No**    OK (with padding word)
   B	     2        Yes    No**    OK (with padding word)
   B	     3        Yes    No	     OK (with padding word)
   C	     1        Yes    No**    OK (with padding word)
   D	     4        Yes    Yes***  unusable for Jaguar
   E	     5        Yes    Yes***  unusable for Jaguar
   E	     7        Yes    No**    OK (with padding word)
   E	     8        Yes    No**    OK (with padding word)
   D	     3        Yes    Yes     OK*
   E	     3        Yes    Yes     OK*
   D	     6        Yes    Yes     OK*
-------------------------------------------------------------
* = Inconvenient, because must byte-swap data before writing.
** = May be controlled via software
*** = Does not do it consistently
-------------------------------------------------------------

The currently most recommended approach is to cancel out the word
mis-alignment by adding another padding word at the beginning of the
file and to use one of the combinations of hard and software marked in
bold.

Technical Support and driver updates of the most commonly used CD Writer
Software can be found in the CD Vendor B Forum on Compuserve (GO
CDVENB).  More specifically:

WinOnCD (CeQuadrat) Peter Hoepfner, Internet: 100073.450@compuserve.com
EZ-D Pro (Incat Systems) Mike Wright, Internet: 71612.1236@compuserve.com

Atari has not tried all possible combinations of CD writer, writer BIOS
versions, and CD mastering software.  Anything not listed in this table
should considered as unexplored territory as far as Jaguar is concerned,
so be careful.

The safest way to find out what REALLY happens on writing a CD is: Burn
a sample CD with a track containing the standard track header at the
beginning.  Now use the Jaguar to read the track back into memory with
CD_init and CD_read.  Finally, look in the buffer for the 16 longwords
of ‘ATRI’ from the track header.  They should be readable, not
byte-swapped (i.e.  ‘ATRI’ not ‘TAIR’) and should be found in memory a
longword boundary.  If this is not the case, then you will have to apply
an appropriate workaround as outlined above.





Jaguar CD Error Recovery Procedures
Atari White Paper,          8/21/95
-----------------------------------

Introduction
------------
Titles designed for the Atari Jaguar CD player must follow certain
technical and procedural guidelines when responding to error
conditions.  This benefits the end-user by ensuring that they are met
with a consistent response to errors on all Atari Jaguar licensed
titles.

Before reading further you should be familiar with the latest technical
information available for the Jaguar CD including the latest
documentation chapter “The Jaguar CD” and any posts or subsequent white
papers on the subject posted electronically on Compuserve and the Atari
Software Development BBS or distributed by group facsimile.


Error Types
-----------
Errors encountered while using a Jaguar CD Player can be broken down
into three groups as follows:


     Read/Seek Errors
     ----------------
     These error conditions are detected with a call to CD_ptr.  A
     non-zero value in A1.l upon return from CD_ptr indicates that a
     data error was reported by the CD mechanism.

     Command Errors
     --------------
     These error conditions are detected by checking the WORD size
     variable err_flag (0x3E00).  err_flag is only valid under some
     conditions.  See the explanation below for details.

     Data Not Found Errors
     ---------------------
     These error conditions occur when a reasonable search of the CD
     data buffer fails to locate the partition marker of the data being
     searched for.


Data Types
----------
Data being read from the CD can be grouped into one of the two
following catagories:

     Critical Data
     -------------
     This is any data whose integrity must be maintained to prevent a
     system crash, such as code or data with embedded offsets, etc…

     Non-Critical Data
     -----------------
     This is any data which, if corrupted, will not significantly
     impact the performance of the game.  Redbook audio is an example
     of non-critical data.  Generally, no error checking in this type
     of data is necessary.


The CD_ptr Call
---------------
CD_ptr returns two longword values in A0.l and A1.l.  The value in A0.l
indicates the address of the last longword of data written.  Register
A1.l gives the address of the most recent data error occurring since
the last CD_read was issued (or will be zero if no error has been
reported).

If the error was a seek error, rather than a read error, the high bit
of A1.l will be set.  There is no functional difference between
handling a seek error and a read error, however you will want to clear
the bit if you need to treat the value as an address.


The err_flag Variable
---------------------
The CD_ack command sets a global WORD size variable called err_flag
(0x3E00).  A value of zero in this location after a call to CD_ack
indicates that an error has occurred.  When any BIOS call which
supports ‘wait for completion’ is called in ‘wait for completion’ mode,
CD_ack is called internally (therefore also setting err_flag).  CD BIOS
calls with this ability are CD_mute, CD_paus, CD_spin, CD_stop,
CD_umute, and CD_upaus.

CD_osamp always calls CD_ack internally, so it also returns an error
code in err_flag.


Error Handling
--------------
CD titles must be responsible for detecting and properly recovering
from each variety of error when they occur.  If an error is detected,
we recommend retrying the operation 3–5 times before abandoning hopes
of retrieving the data.  Before retrying after any type of error, you
should use CD_mode to switch to single-speed and back to double-speed.
This will greatly improve the error retry success rate.

If after several retries, the operation cannot be completed without an
error, some action must be taken.  If an error occurs while attempting
to load non-critical data, and it is possible to proceed in a normal
manner, it is acceptable to skip it.  This might happen if the data was
a sound effect or an intermediary movie which won’t hinder gameplay if
it is omitted or stopped prematurely.

If the game cannot proceed without the requested critical data, use the
following procedure:

1) Issue a CD_uread.

2) Issue a CD_stop command with the ‘wait for completion’ flag set.

3) Display the following message in the currently selected language: An
error has occurred while attempting to read from the CD.  Please remove
the disc, ensure it is clean, and replace the disc when you are done.
The game will attempt to continue when the drive door is closed.

4) Issue a CD_switch command.  This command will not return until the
user has opened and closed the drive door.  If CD_switch fails, go to
#3.

5) Issue a CD_mode command to reset the CD as needed, followed by a
CD_spin with ‘wait for completion’ to the correct session.  Try issuing
the command again.

This procedure should allow the operation to complete successfully in
all circumstances where it is actually possible (i.e.  the disc is not
physically damaged).


CD_switch Errors
----------------
CD_switch reports errors in a different manner than all other CD BIOS
calls.  If CD_switch fails for any reason, the first word of the TOC
area at 0x2C00 will be negative.


General CD-ROM Q & A
--------------------
While these topics aren’t directly related to CD error handling,
improper handling of CD BIOS calls can manifest itself as strange
errors.  Reading the following information carefully should prevent
some common misunderstandings.

  Q: After issuing a CD_read, the read pointer (as returned
     by CD_ptr) never advances but neither err_flag or CD_ptr reported
     an error.  What is the problem?

  A: This symptom is usually caused by a problem in the GPU.  Either
     the GPU has crashed or a read handler was never properly installed
     with some form of CD_init.


  Q: I notice memory being trashed slightly past the end of my read
     buffer.  What is happening?

  A: CD_read is documented as reading as many as 64 bytes past the
     end of the specified read end address.


  Q: What calls are safe to make after a CD_read?

  A: The only two calls that should follow a CD_read are CD_ptr or
     CD_uread.  In other words, never make any BIOS call except CD_ptr
     after a CD_read without doing a CD_uread first.


  Q: When is it safe to call CD_uread?

  A: CD_uread may be called without harming anything even if a read
     isn’t in progress.  CD_ptr is the only BIOS call that can be
     safely called while a read is in progress.  Calling CD_uread
     before other BIOS calls are made is a good way to ensure that any
     prior reads are stopped.


  Q: My code hangs in an infinite loop in the CD BIOS area
     (0x3000-0x3E00).  What’s the problem?

  A: This problem could be caused by any of the following:

     1) Calling a CD BIOS function with ‘return immediately’ set (or
     calling CD_read in seek mode) and not calling CD_ack sometime
     before the next BIOS call is made.

     2) Calling CD_ack in a situation where it was not required.


  Q: I’ve noticed that the CD sometimes stops by itself while I’m
     debugging.  Is this normal?

  A: The CD mechanism will automatically stop the disc when the end
     is reached.  Be aware that even once a read operation has filled
     your buffer, the disc read head continues advancing.  For this
     reason, you should always pause the disc when not reading data
     from it.  Also, it’s a good idea to pad the last segment of data
     on your disc so if you read past the end while filling your
     buffer, the CD doesn’t stop accidentally.

