		  ________
		 /\  _____\
		 \ \ \____/   __    __ __    __       __
		  \ \  ___\ /'__`\ /\ `__\ /'__`\   /'__`\
		   \ \ \__//\ \_\ \\ \ \  /\ \_\ \ /\ \_\ \
		    \ \_\  \ \___/_\\ \_\ \ \____ \\ \____/
		     \/_/   \/___/_/ \/_/  \/____\ \\/___/
					     /\____/
					     \/___/

			 Version 1.0 - September 1996

			      Copyright (C) 1996
		    David Ellsworth <davidell@ticalc.org>
		       Rob Taylor <rtaylor@ticalc.org>
			  Dan Eble <eble@ticalc.org>

==============================================================================
			      TABLE OF CONTENTS
==============================================================================

 PART 1: FOR USERS
 -------------------
 1.1: INTRODUCTION
 1.2: REQUIREMENTS
 1.3: PUTTING FARGO ON YOUR CALCULATOR
 1.4: RUNNING FARGO PROGRAMS
 1.5: USING THE FARGO SHELL

 PART 2: FOR PROGRAMMERS
 -------------------------
 2.1: DIFFICULTIES OF PROGRAMMING THE TI-92
 2.2: LISTS OF HELPFUL INFORMATION
 2.3: PROGRAMMING OVERVIEW
 2.4: THE FARGO SOURCE CODE FORMAT
 2.5: THE FARGO OBJECT CODE FORMAT

 PART 3: OTHER TOPICS
 ------------------------
 3.1: LEGAL STUFF
 3.2: CONTACTING THE DEVELOPERS
 3.3: NEW VERSIONS AND INFORMATION
 3.4: REVISION HISTORY

==============================================================================
			      PART 1: FOR USERS
==============================================================================
------------------------------------------------------------------------------
 1.1: INTRODUCTION
------------------------------------------------------------------------------

Fargo is a program for the TI-92 graphing calculator that enables execution
of 68000 machine language programs. These programs are stored on your
calculator as PRGM variables.

Fargo consists of four basic components:

  1) the Fargo core
  2) the Fargo shell
  3) ROMlib
  4) Flib

The core contains low level bootstrap routines that are used to load and run
Fargo programs. The shell provides an simple and organized way to list and
execute Fargo programs stored in the calculator's memory. ROMlib allows
Fargo programs to use the TI-92's built-in ROM routines while maintaining
compatibility across all ROM versions. Flib (Fargolib) is a library that
contains routines useful for writing Fargo programs, but not included in the
TI-92's ROM.

------------------------------------------------------------------------------
 1.2: REQUIREMENTS
------------------------------------------------------------------------------

You must have access to a Graph-Link cable if you have a Macintosh and/or
want to use TI's software to transfer Fargo to your TI-92. A PC program is
supplied with Fargo that will allow you to transfer group files and backups
using a homemade link (both the parallel and serial cables are supported).

This version of Fargo works on all known ROM versions starting from 1.2, and
is designed to be compatible with future revisions. However, if you have a
TI-92 with a ROM version later than 1.12, please contact us. TI may make
drastic changes in the TI-92's ROM that will prevent the current version of
Fargo from working; in that case we will work on releasing a new version of
Fargo that will support the new ROM version.

If you attempt to run Fargo on a TI-92 with a ROM version higher than 1.12,
you do so at your own risk. Make sure you have everything on your calculator
backed up.

To find out what ROM version your TI-92 has, press [Diamond] [(] from the
home screen. Then press [2nd] [QUIT] to go back.

------------------------------------------------------------------------------
 1.3: PUTTING FARGO ON YOUR CALCULATOR
------------------------------------------------------------------------------

The following procedure details the process of putting Fargo onto your
TI-92. This process will preserve all the files that you currently have on
your calculator.

The first step is to unzip Fargo into a directory on hard disk. For
discussion purposes, let's call that directory C:\FARGO. The next step is
to transfer a backup from your TI-92 to C:\FARGO. You can give the backup
any name you want.

From the DOS command line, execute the following command:

  C:\FARGO>putfargo <name of backup>

where <name of backup> is the name of the backup file you made, without the
extension. This will put the Fargo core into the backup file. Now you can
transfer this backup file back to your TI-92; it will time out at 99%. Don't
worry, this is supposed to happen. There is now one step remaining: transfer
all the .92P files from C:\FARGO to your TI-92. You now have Fargo on your
calculator.

The following .92P files are required to run Fargo:

  ROMLIB.92P	ROMlib. Provides a library interface to the ROM routines.
  FLIB.92P	Fargolib. Contains useful routines not found in ROM.
  SHELL.92P	The Fargo shell. The listing of programs you see by default
		when you press [Shift] [ON].

The remaining .92P files are sample Fargo programs.

------------------------------------------------------------------------------
 1.4: RUNNING FARGO PROGRAMS
------------------------------------------------------------------------------

To launch the Fargo shell, use the hotkey [Shift] [ON]. This works from
anywhere, provided that your TI-92 is idle; at any given time, you can start
Fargo with this hotkey if and only if you can turn your calculator off using
[Diamond] [ON]. If this condition is not met 1/4 second after the hotkey is
pressed, it will be ignored.

You may also start Fargo programs in the same way that TI-BASIC programs are
called. For example, to directly start FTris, you would enter "ftris()" from
the home screen. Using this method bypasses the Fargo shell.

The Fargo shell can be executed just like any other Fargo program. As an
alternative to pressing Shift-ON, you may execute the TI-BASIC command
"shell()". Any Fargo program renamed to "shell" will be triggered when you
press [Shift] [ON].

If a program has been directly launched, and for some reason is cannot be
executed, the screen will flash to signal the error. (This also happens
when you try to execute a library.) The usual cause for this is a missing
or invalid library required by the program you launched.

The Fargo shell requires the libraries "romlib" and "flib" to run. Different
programs may require different libraries. Also, a certain minimum amount of
memory (approximately 4K) is required to run any Fargo program.

If the Fargo core is not present on your TI-92, pressing [Shift] [ON] will
have no effect. When Fargo programs are launched from TI-BASIC, they will
simply pause the calculator and wait for [ENTER] to be pressed. To put the
Fargo core on your TI-92, follow the instructions in Section 1.3.

------------------------------------------------------------------------------
 1.5: USING THE FARGO SHELL
------------------------------------------------------------------------------

When you start the Fargo shell, it displays a menu of the Fargo programs
present in your calculator's memory. If there are none, it displays an error
message and exits.

Use the following keys to navigate through the Fargo shell:

 [Up]         - move cursor up
 [Down]       - move cursor down
 [2nd] [Up]   - page up
 [2nd] [Down] - page down
 [ENTER]      - execute program
 [F1]         - display "about" dialog box
 [EXIT]       - quit

If a program requires libraries that are not present, when you attempt to
execute it, the Fargo shell will display an error dialog box.

You may bypass the Fargo shell by launching programs directly from TI-BASIC.

==============================================================================
			   PART 2: FOR PROGRAMMERS
==============================================================================
------------------------------------------------------------------------------
 2.1: DIFFICULTIES OF PROGRAMMING THE TI-92
------------------------------------------------------------------------------

 - There is no built-in hook in the TI-92's ROM to execute machine language;
   e.g., you cannot run machine language from the Custom menu like the TI-85
   can. To see how Fargo circumvents this obstacle, read BACKUPS.TXT.

 - Different versions of the ROM are very much alike, but differ slightly in
   the offset of most calls. Take a look at ROMLIB.ASM to see how Fargo
   solves this problem.

 - The calculator dynamically rearranges its memory, so there is never a
   sure way to pinpoint the location of a program in order to access data
   and do JMPs and JSRs. The Fargo core does not face this problem, since it
   is in a fixed location (the top of RAM). For programs, which do move
   around, Fargo solves this problem by automatically relocating programs
   before they are executed (this task is done by the Fargo core).

 - There is very little RAM (about 70 kb) to work with, so routines should be
   optimized to work even under low memory conditions.

------------------------------------------------------------------------------
 2.2: LISTS OF HELPFUL INFORMATION
------------------------------------------------------------------------------

All of the .TXT files included in the distribution contain useful and
necessary information for writing good Fargo programs. These files are
nowhere near complete, so we welcome corrections and additions. Please send
these to <fargo@ticalc.org>.

The files in this package are not meant teach you from scratch how to
program in 68000 assembler; for this, please consult other sources.

The text files are as follows:

  BACKUPS.TXT	Describes the .92B format, and explains the method Fargo
		uses to load the bootrap machine language code.
  FARGO.TXT	Main documentation (this file)
  HANDLES.TXT	Explains how memory handles are used by the TI-92.
  PORTS.TXT	Explains how to access I/O ports on the TI-92.
  RAM.TXT	Describes the TI-92's memory map, and lists some RAM
		addresses along with descriptions.
  TRAPS.TXT	Describes the TI-92's usage of the exception vector table.
  TYPES.TXT	Describes some of the data types used by the TI-92.

For all the .TXT files, the following conventions apply:

  All numbers are in hexadecimal, except for bit indices or numbers ending
  with the suffix (d). In certain places, the prefix '$' will be used to
  clarify that a number is in hex.

  B = byte ( 8 bit integer)
  W = word (16 bit integer)
  L = long (32 bit integer)

  Brackets [] designate pointer indirection. This may be followed by ".B",
  ".W", or ".L" to designate the size of the integer being pointed to.

Remember that the 68000 processor uses "Big Endian" to store integers in
memory; the most significant byte (MSB) is stored first, and the least
significant byte (LSB) is stored last. For example, the number $1234 is
stored as 12 34 in memory.

------------------------------------------------------------------------------
 2.3: PROGRAMMING OVERVIEW
------------------------------------------------------------------------------

Fargo modules (PRGM variables) consist of two classes: programs and
libraries. Programs can be executed directly, and are displayed in the
Fargo shell. Libraries provide commonly used routines to programs; these
routines can be used by simply linking the library to the program. This is
an alternative to copying the source for each routine into the source for
the program that uses the routines.

Fargo source code is contained in .ASM files. Since so much is involved in
compiling a Fargo program with the correct format, this is automated by a
set of macro and include files:

  @LIBRARY	The standard macro file for Fargo libraries.
  @PROGRAM	The standard macro file for Fargo programs.
  FARGO.INC	Contains macros for constructing a Fargo header, including
		relocation and library linking info.
  LIBS.INC	Contains macros for constructing libraries. Also contains
		the current Fargo header version.
  TI-92.INC	Contains useful equates and macros specific to the TI-92,
		but not specific to Fargo. The information here is
		duplicated from some of the .TXT files.

------------------------------------------------------------------------------
 2.4: THE FARGO SOURCE CODE FORMAT
------------------------------------------------------------------------------

This section describes how to create an .ASM file that will compile to a
Fargo .92P module in the correct format. The Fargo package uses a program
called "A68K" to assemble source code; this program has many advanced
features, including macros and include files. These features are used to
their full potential in constructing Fargo source code.

This section precisely describes how to create Fargo source code. To see
this in practical use, please examine ROMLIB and the sample source code
included with Fargo.

The first source code line is the most important. For programs, it must be
this:

	@program	prog_code,prog_name

and for libraries, this:

	@library	<library name>

For programs, both "prog_code" and "prog_name" are labels that must be found
later in the program source code. The "prog_code" label marks the entry
point of the program; it must exit with an RTS instruction. The "prog_name"
label marks a null-terminated string containing the program comment, which
is displayed in the Fargo shell menu. The names of both of these labels may
be changed, as long they are changed in both places.

For libraries, <library name> contains the name of the library; this must be
the same as the file name. All libraries must have an accompanying .SYM
file. This is a text file containing prototypes of all the public routines
in a library. Each line in the .SYM file must begin with "\1," followed by
the name of a routine. All the library routines must be enumerated in this
way. You can also include comments in a .SYM file, useful for documenting
routine parameters and return values. In the main .ASM source for a library,
each routine must begin with:

	label	<name of routine>

this is all you need to do to write a library. It is recommended that you
describe all your library's public functions in a separate file called
<library name>.FN. This convention is followed by all the libraries
included in the Fargo package.

At the end of any Fargo module (either a program or a library), you must
include the following lines:

	reloc_open
	reloc_close

In between these two lines, you may link libraries to the module using this
construction:

	add_library	<name of library>

A68K also requires that you end a program with the directive "end", so the
final line must always be this:

	end

Libraries may be linked to other libraries. In a Fargo module, use the
following construction to call a external library routine:

	jsr	library_name[routine_name]

A library may call its own internal routines without linking to itself. To
do this, simply call the routine as you would any other internal routine:

	bsr	routine_name

There is one special library that is not stored as a program variable on
your calculator. This is the Fargo core library, which is always linked with
all Fargo modules. To see details on the routines in this library, read
CORE.FN.

To compile a Fargo .ASM file into a .92P file, execute this DOS command:

  C:\FARGO>fargo <name of program>

Where <name of program> is the name of the .ASM file, without the extension.
This will also create a file called LIST.TXT that you can use to debug
source code.

------------------------------------------------------------------------------
 2.5: THE FARGO OBJECT CODE FORMAT
------------------------------------------------------------------------------

This section describes the header format for compiled Fargo modules. You do
not need to know or understand this format to write Fargo modules, since it
is created automatically by include files. It is listed here purely for
reference.

Note: A relative pointer is 2 bytes and is relative from the beginning of a
      Fargo module. A relative pointer of $0000 would point to the Fargo
      signature.

 Rel.
Offset   Description
------   -----------
  00     Fargo Signature ($0050='P'rogram, $004C='L'ibrary)
  02     Version (Current=$3130='10')
	 This version number will only be changed if the header format is
	 changed, and in that case it will be changed to match the current
	 version of Fargo. Fargo checks this version against its internal
	 header version number. A program with the wrong version number will
	 not be listed in the main menu. Linked libraries with the incorrect
	 version will cause a relocation error. Also, if you mix and match a
	 Fargo backup and a Fargo .92P file with different header versions,
	 pressing Shift-ON will have no effect.
  04     Relocation table (relative pointer)
	 This points to a table of words, each of which is a relative
	 pointer that table points to an absolute pointer in the program
	 that needs to be relocated. The table is terminated by a zero.
  06     Library linking table #1 (relative pointer)
	 This points to a word indicating the number of libraries linked to
	 a program when it is relocated. Following that word is a list of
	 the variable names of each library. Each name is null-terminated
	 (unless it has a length of 8 characters), then followed by the next
	 library in the list, until all of them have been enumerated.
  08     Library linking table #2 (relative pointer)
	 This must point to an uninitialized array of absolute pointers, one
	 for each library being linked to the program. These are used for
	 storing the beginning address of each library during the relocation
	 and unrelocation process.
  0A     Relocation (usage) count
	 This is initialized to zero in a compiled Fargo program. When it is
	 relocated, the value is incremented; when it is unrelocated, the
	 value is decremented. If a program has already been relocated, and
	 is relocated again, this count while be nonzero, and the relocation
	 routine will do nothing. (Relocating a program twice would crash
	 the TI-92.) The same applies for unrelocation; if unrelocating a
	 program does not reduce the count to zero, it does not actually do
	 any unrelocation. The count is primarily useful for libraries, if a
	 program links to libraries that, in turn, link to each other.
  0C     Programs only: Program comment (relative pointer)
	 This points to the zero-terminated string that will be displayed
	 next to the program's variable name in the main Fargo menu. To
	 prevent a Fargo module from being listed in the Fargo menu, make
	 this field zero (the Fargo shell does this to prevent from being
	 listed in itself, since it is not reentrant).
  0C     Libraries only: Library name
	 This points to the zero-terminated string that is checked against
	 the variable name of a library when it is linked to a program
	 during the relocation process. This insures that simply renaming
	 one library to another will not cause a crash.
  0E     Public Routine Table
	 This table is inside the header itself; it is not a pointer to a
	 table. It consists of relative pointers to the public routines in a
	 Fargo module. This table comes at the end of the header because it
	 can have a variable size, depending on how many public routines are
	 in the module. The first routine has an ID of zero. Each routine
	 pointed to must be preceded by a word specifying that routine's ID;
	 this is used in the unrelocation process. In a program, there is
	 only one public routine: the program entry point, which has an ID
	 of zero. In a library, there can be any number of public routines.

==============================================================================
			     PART 3: OTHER TOPICS
==============================================================================
------------------------------------------------------------------------------
 3.1: LEGAL STUFF
------------------------------------------------------------------------------

Fargo and all the companion files are our work.  We encourage their
distribution as long as they are kept together, unmodified from the form in
which we originally distributed them.

We take no liability for any damage caused directly or indirectly by running
Fargo on your TI-92. Keep in mind, though, that it is extremely unlikely (if
not impossible) for your calculator to be damaged by software.

You may NOT put Fargo up on any WWW-page, FTP-site or BBS without agreement
with the developers. This is NOT to stop the distribution of Fargo. It is to
allow us to keep track of the distribution sites out there, so we can make
sure a bug-fix or upgrade is always available. Just mail the Fargo
development team <fargo@ticalc.org> for an arrangement.

------------------------------------------------------------------------------
 3.2: CONTACTING THE DEVELOPERS
------------------------------------------------------------------------------

First of all - don't hesitate to contact us. If you have a question that is
about something very basic, that you think a normal user could handle, use
one of the mailing lists or newsgroups. However, if you have a comment or
suggestion or something more advanced, please contact us. We will try to
respond to all mail sent to us.

If you want to contact the developers directly, please send email to
<fargo@ticalc.org>. This is an alias for the three members of the Fargo
development team, whose individual email addresses are listed at the
beginning of this document.

------------------------------------------------------------------------------
 3.3: NEW VERSIONS AND INFORMATION
------------------------------------------------------------------------------

New versions will always be available at http://ticalc.org. Updates will be
announced on list-fargo and on the newsgroup bit.listserv.calc-ti, which
echos to the Calc-TI mailing list.

------------------------------------------------------------------------------
 3.4: REVISION HISTORY
------------------------------------------------------------------------------

September ??, 1996: Version 1.0

  First Release.
