Phoenix 0.50 for TI-82/85/86 by Patrick Davidson - Internal Documentation                

This is the internal documentation for the game Phoenix.  For information
on using the game, see the file 'PHOENIX.TXT'.  This document explains the
internal workings of the program.  It is mainly intended for people who
want to modify the game.

This file is not yet complete; internal interfaces and data structures are
not yet described in it.  However, the introduction and description of the
build process which produces code for all 3 calculators from a single set of
source files.

 _____________________________________ Table of Contents

 1. Introduction ..................................................... 18
 2. The Phoenix-Z80 build process .................................... 51

 _____________________________________ Introduction

Phoenix is free/open source software.  This means that everyone is allowed
to develop modified versions of the game.  Phoenix is now in the public
domain, so it may be used in any way without restrictions.

I chose this for the simple reason of trying to maximize the usefulness of
the program.  This provides many benefits, such as:

1) Allowing people who want to have a slightly different game to make it
   themselves with a minimum of effort.
2) Allowing intermediately-skilled programmers to learn from the design
   of the game.
3) Allowing the more advanced programmers to develop substantially different
   games based on this one more easily than writing new games from scratch.
4) Allowing the program to continue even if I stop supporting it myself.
                           
However, even though several people have talked to me about making such
modified games, nobody has actually released one yet.  To try to make it
easier for people to do that, I am releasing this document which describes
the internals of the game, and have also added many additional comments to
the code itself.

This document only provides an overview of the working of the game.  More
detailed information about specific functions is present in the comments of
the source files themselves.  (That is, it hopefully will be when/if I get
around to putting in more complete comments).

This document assumes that the reader has at least basic familiarity with
programming the Z80-based calculators in assembly.  If you are a complete
beginner, this is probably not the best resource for learning to program the
calculators.

 ______________________________________ The Phoenix-Z80 build process

Both the TI-85 and TI-86 version of the game are built from the same set of
source files.  This is accomplished by using a conversion program, a special
include file for the TI-86, and a few lines of conditionally assembled code
throughout the program.  The TI-85 version is the 'base' version which is
converted to run on the TI-86.  The TI-82 version is built in a similar way,
but some of the source files have separate TI-82 versions.

The conversion program 'srcto86' does only two simple tasks:  It removes all
cases of the & symbol used for relocation from source files (going into
#included files also), and also adds the line '#define __TI86__' to the top
of the output.  The program is run with the command 'srcto86 phoenixz.asm
phoenix.asm' to read from phoenixz.asm and write to phoenix.asm.  The
contents of any included files are put into the output file in converted
form; the originals are not changed.  The source code of this program is in
the file 'srcto86.c'.

The special include file 'ti-86.h' is used to simulate the TI-85's features.
First, it contains equates for TI-86 system calls that have the conventional
TI-85 names (that is, the TI-86's _puts is named D_ZT_STR).  This include
file defines all symbols used; it does not include any other files.  It also
includes code to simulate many functions available under Usgard that aren't
readily accessible on the TI-86, such as D_HL_DECI, GET_KEY, OTH_CLEAR, etc.
Note that while Asm86's 'asm86.h' include files does have equates for some of
those functions, many are only valid on ROM 1.2 so the routines really do
need to be rewritten here.  This include file also does partial emulation of
Usgard's interrupt system (supporting only one interrupt).  Finally, this
file provides an OTH_EXIT replacement which does write-back for saved game
and high score data; anything between the labels permanenet_data_start and
permanent_data_end will be written back to the variable.  This file also
provides a typical TI-86 header, setting the start address and providing
title information for shells.

The least elegant technique used is the conditional code, which has been kept
at a minimum.  Mainly, it is used in the main source file to include the
'ti-86.h' file for the TI-86, and otherwise to include 'usgard.h' and set
the program start to 0.  Also, conditional code is used in some places to
conditionally add PROGRAM_ADDR to addressed stored in data tables (in the
places where I thought this would be more convenient than relocating the
addressed themselves).

The TI-82 version is built with a method similar to the above, but with some
additional changes.  A 'srcto82' program (very similar to 'srcto86') is used
to perform essentially the same conversions as before.  However, since some
parts of the game require larger changes than a few lines of conditional code
and removal of &s, some files have separate versions for the TI-82.  These
files have similar names to the regular versions, but also contain '82' in
the file names.  The main source file for the TI-82 is 'phx82.asm'.  It
includes the other files, and also defines a few routines missing on the
TI-82 (fewer than are needed for the TI-86 though).

Additionally, remember that many ROM calls on the TI-82 must be made with the
ROM_CALL macro, not direct calls.  Therefore, all the TI-82 files must use
this.  Additionally, if you are modifying the files that are shared across
all calculators, you must use ROM_CALL when the TI-82 requires it (this macro
just makes a regular call on other calculators, so it doesn't cause any
problems).  However, it is fairly unlikely that these shared files will use
very many ROM calls (they don't use any at the moment).

Supplied with Phoenix-Z80 is the batch file 'build.bat' which will perform
all steps to build the program automatically on DOS-based systems.  It also
builds the distribution archives 'phx82.zip', 'phx85.zip' and 'phx86.zip'.
Look at it to see how to produce the various files.  Note that it's steps
require Usgard, CrASH, and Asm86 build tools to be installed, and that it
also may be needed to copy some files such as 'usgard.h' and 'tasm80.tab'
into the directory you are building Phoenix in if the build tools are unable
to find these files.

The source files which are used on all calculators, or only on the TI-85 and
TI-86, are kept in the 'source' directory.  Source files used on the TI-82
only are in the 'source82' directory.  The master source files are in the
main directory.  The conversion tools, and their sources, are in the 'pc'
directory.
