TI-89/92+ Hardware 2.00 AMS 2.0x TSR support v.1.03
***************************************************
Copyright (C) Kevin Kofler, 2001
Thanks to Zeljko Juric for all the help he has given to me (see the credits
section VI)!

I) Purpose

1) What's it?
This is a program which allows memory resident (TSR) programs to run stable
on HW2 calculators with AMS 2.xx and without HW2Patch. It installs itself
in RAM (it is a TSR itself) and will NOT modify the AMS.
On any other configurations, it will simply refuse installation. (The user
version will show an error message when this happens.)
Note that the TSRs need to be HW2 compatible. (Technically: They still have
to add $40000 to the address of the event or interrupt hook.)
This program is included in the current versions of all my TSR programs
(dated 2001/01/09 or later). Versions dated 2001/07/04 or later will
include v.1.03. By the time you download this, they will probably already
be out, at least at:
http://ti89prog.kevinkofler.cjb.net
Header file versions for A68k and TIGCC are available (look at section
I.3).

2) For users:
The user version is located in the "user" folder of the ZIP file.

a) Installation
To install this program, simply type h220xtsr() from the home screen and
press [ENTER]. V.1.03 is also able to upgrade from prior versions (but
it still won't downgrade newer versions).
Note that this will be included in future TSR programs and if it says so
you will not need it (check the version though).
To update from v.1.01 or older, I strongly recommend you to reset the
calculator and to install the new version afterwards, because those
versions contained a bug which may cause random crashes. V.1.03 will do
the upgrade, but note that this is NOT recommended because of the nasty
bug in the previous versions.
If you were using v.1.02 or 1.02a, it is safe to upgrade.
IMPORTANT: In order to fix the bug when changing the batteries, I had to
           do some internal changes (technically: to hook the trap #4).
           You will have to uninstall any TSRs which install themselves
           on the "trap #4" before installing or upgrading h220xTSR.
           This includes most memory resident keyboard auto-repeat
           accelerators (like Fast Keyboard and FastKeys), password
           programs or clocks. Otherwise, h220xTSR will fail with a
           "trap 4 already hooked" error. You can of course reinstall
           the other TSRs afterwards.

b) Uninstallation
To uninstall this program, simply type unin2tsr() from the home screen and
press [ENTER]. Note that this will only work if all other TSRs are
uninstalled before, for security (crash prevention) reasons.
You will have to use the version of unin2tsr given with v.1.03 because
I had to change the internal architecture in order to fix the bug when
changing the batteries.

3) For developers:
a) A68k assembly version (source)
It is located at "asm-dvlp\h220xtsr.h".
Just include this after your _main: entry point and then continue your
program as normally. And please don't accuse me of wasting a few bytes,
I do this to make the including as simple as possible.
You will also have to include "OS.h". You need the version included with
TeOS or the one given with TIGCC 0.91 or higher (because of the ROM_CALL2
macro). If you want to use the TIGCC IDE under TIGCC 0.9 or lower, you
have to copy this file to the TIGCC\INCLUDE\ASM folder (replacing the
older version given with old versions of TIGCC).
Do not use jmp or jsr instructions to labels in your program. Use bra or
bsr instead!

b) A68k assembly version (binary)
It is located at "asm-dvlp\h220xtsr.bin".
To use it, just incbin it after your _main: entry point.
Do not use jmp or jsr instructions to labels in your program. Use bra or
bsr instead!

c) TI-GCC C version
It is located at "c-dvlp\h220xtsr.h".
To use it, use #include "h220xtsr.h" and call the function h220xTSR();.
Use it only in your main function and, if you do not use it at the end, you
will have to relocate your program to the ghost space if it was not already
there.
For an event hook installer, I recommend the following sequence:
void _main(void)
{
...
if (!h220xTSR()) {ST_helpMsg("Memory error message");return;};
*EV_hook=...;
ST_helpMsg("Success message");
}
Also do NOT use the SAVE_SCREEN or RETURN_VALUE directives, or the support
for the exit command (DO define NO_EXIT_SUPPORT!), since they cause your
main function not to be the real main function of the program.

d) Distribution
See the section V, especially V.ii, for details about how to distribute this
TSR support program together with your programs.

II) History

Current version:
v.1.03: * Bugfix: The calculator no longer crashes when changing the
                  batteries with the HW2 AMS 2 TSR support installed.
          Thanks to Loth Lay for reporting this bug.
          Make sure your calculator is _OFF_ when changing the batteries
          though to avoid data loss and/or crashes!
          I also had to change the internal architecture to fix this bug, so
          you will need the uninstaller given with this version in order to
          uninstall it.
        * This version is able to update from all previous versions.

Previous versions:
v.1.02a: Fixed a serious bug in the C header file for developers and in the
         binary version of the assembly header file for developers, which
         caused crashes which could be fixed only by a reset.
         This bug affects all versions of SampleTSR and ASH by Greg Dietsche
         released BEFORE 2001/05/19. I am not aware of any other programs
         using the buggy header files.
         The standalone version for users and the source version of the
         assembly header file, which I use in AutoClBr, Auto Alpha-Lock Off
         and XtraKeys, are NOT affected by this bug.
         I repeat: h220xtsr.89z, h220xtsr.9xz, AutoClBr, Auto Alpha-Lock Off
         and XtraKeys ARE _NOT_ AFFECTED BY THIS BUG!
         Also, this bug only affects HW2 calculators with AMS 2 which did NOT
         have the HW2Patch or a working version of the HW2 AMS 2 TSR support
         (see the 2 paragraphs above) installed BEFORE SampleTSR or ASH.
         HW1 calculators or HW2 with AMS 1.05 ARE _NOT_ AFFECTED BY THIS BUG!
         Thanks to Greg Dietsche for reporting this bug and sorry for having
         rendered his programs buggy.
v.1.02: * Fixes a nasty bug which could cause random crashes or corrupt the
          mathematical functions of the calculator! If you have used any
          previous version of h220xTSR, I recommend to reset your calculator.
          I am really sorry for that.
        * Adds support for possible different implementations of
          enter_ghost_space.
v.1.01: Now really refuses to install on patched HW2. There is no need to
        reinstall it if you already have v.1.00.
v.1.00: This version was the first "official" public release.
        Just minor changes in the user version.
        An uninstaller and header files for developers added.
v.0.14 alpha: Added support for the Exec command.
v.0.13 alpha: This version was the first public release.

III) How this program works

It makes sure that the so called "ghost space", which consists of RAM
addresses after the actual RAM and which maps to the actual RAM, is never
execution-protected by the hardware. It launches all programs from the "ghost
space".

IV) Bugs

If you change your batteries while the calculator is ON, the HW2 AMS 2 TSR
support will still crash. Sorrily, I cannot do anything about this, since I
have no way to predict when one changes the batteries.
WORKAROUND: Just make sure the calculator is OFF before you take your
            batteries out. (Note that this is recommended by Texas
            Instruments in their manuals as a precaution to take anyway.)

If you have to report a bug to me, see section VII. PLEASE report any bugs
you find, or else I cannot correct them.

V) License

In addition to the following license:

(i)
-----------------------------------------------------------------------------

Kevin Kofler's TI-89 Program License
====================================

This license applies to all TI-89 programs by Kevin Kofler, unless otherwise
stated. Note that CHEMISLV is NOT an exception since the following is a
generalized copy of the CHEMISLV-License (readme point 8).

a.I CAN'T BE HELD RESPONSIBLE FOR ANYTHING! NO WARRANTY!
b.YOU CAN'T SELL MY PROGRAM OR CLAIM IT IS YOURS!
c.IF YOU TRANSMIT ONLY PARTS OF THIS PROGRAM, YOU MUST SAY THAT IT'S A PART
  OF THE (package name) PACKAGE AND ONLY A PART!
d.NORMAL RIGHT APPLIES TO THE THINGS I'VE FORGOTTEN!

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

(ii) I am granting you permission to freely redistribute the header files and
     any program compiled with them as long as:

* The used header file and this file (You should rename it to "h220xtsr.txt".)
  are included.
* Those files are LEFT UNMODIFIED. You need my permission to compile your
  program with a modified version of my header file, or to copy and paste my
  code into it.
* Applicable credit is given in the credits section of the program's
  documentation.
* Your program's documentation states: "This program uses and includes the
  TI-89/92+ Hardware 2.00 AMS 2.0x TSR support v.1.03 by Kevin Kofler in its
  installation routine. See h220xtsr.txt for details about it."
* It is NOT distributed together with or used for ILLEGAL programs.

Ask me for permission if you are not sure about one of these license
requirements.
Please DO NOT distribute modified versions of this program or the
corresponding header files without my permission.

VI) Credits

Thanks to:
* Zeljko Juric for documenting some important operating system functions, for
  the enter_ghost_space function and for the information about the HW2
  protection required to write this program
* Julien Muchembled for the hardware version detection routine
* Rusty Wagner for the Virtual TI emulator
* Sebastian Reichelt for the TI-GCC IDE (integrated developer environment),
  which was used for this program
* Charlie Gibbs and David Ellsworth for the A68K assembler
* Thomas Nussbaumer and the TI-Chess Team (http://tict.ticalc.org) for the
  TIGCC Tools Suite which I have used to create both the binary version of
  the assembly header file (using ttstrip and ttextract) and the C header
  file (using ttstrip, ttextract and ttbin2hex).
* jimhaskell, Kaizer911 and mpjohans for testing version 0.14 alpha
* Jaime McGauley for reporting a nasty bug in v.1.01 and lower.
* Greg Dietsche for reporting a serious bug in the C header file and the
  binary version of the assembly header file of v.1.02 or lower.
* Loth Lay for reporting the bug when changing batteries and for his help
  with testing the pre-release versions of v.1.03.

VII) Contact me

Homepage: http://kevinkofler.cjb.net
E-Mail: kevin.kofler@chello.at