How To Create TSR Event Hooks using TIGCC

Title: A Sample TSR
Version: 3.1
Platform(s): TI-89, TI-92+, V200

Author: Greg Dietsche aka GForce
Web Site:http://gforce.calc.org
E-Mail: gforce@calc.org
Last Revision: 10/22/02

Modified by: Thomas Naeff
Web Site: www.mytinyarchive.ch.vu
E-Mail: th.n@gmx.ch
Date: 04/07/2006

Summary
The included source files demonstrate a method of creating a TSR EVENT HOOK using GNU C and the TIGCC development environment. Using this method, it is possible to write an event hook that has multiple functions, can use the TIGCC library, and is not limited by optimization levels. This method is also completely compatible with Kevin Kofler's event hook conventions. He has written an uninstall tool that is available at his web site. I suggest that you include it with any hook that you create using this information.

Conventions Used in This Document
    AMS stands for Advanced Mathematics Software.
    TIOS stands for Texas Instruments Operating System. I use tios and ams interchangeably.
    I also use TSR, TSR Event Hook, and Event Hook, interchangeably... even though I probably shouldn't.

What is a TSR Event Hook?
TSR stands for Terminate and Stay Resident. A TSR is a program that runs once to install itself and then exits. Once installed, the TSR will only run only if certain conditions are met; in this case, the TSR monitors the AMS for event messages.

A hook is what we are doing here; it is a TSR that is called when a message is sent by the AMS, hence it "Hooks" into the messages sent by the AMS. We are not sending our own events, but rather waiting to receive an event from the AMS.

Getting In The Correct Mind Set:
For more information on Events and the like, check out the TIGCC documentation. In particular, pay extra attention to the events.h header file. Please note that the methods for creating an event hook that are described in events.h are not ideal. They are buggy, messy etc... (I'm talking about EV_captureEvents and EV_eventLoop in particular). One should notice problems with things such as the catalog and var-link menu, and general instability. The method I am presenting here eliminates said problems.

Now, to get in the correct mind set... Using my method, you are able to change events and/or react to events at your choosing. There is no need to send events from the hook; this is taken care of by the AMS (trust me... have I ever lied to you? ;). A hook created using this method is only responsible to react to and/or change an event and then pass the event along to the next event hook (assuming that there are other event hooks installed).

Using this method, the AMS will send an event to the hook that is pointed to by EV_hook (your hook). That hook has the option to modify the event, react to it, or do nothing. When the event hook returns, the ams will then proceed to do the actual processing of the event; which could be the original event, or a modified version that was changed by an event hook.

How to Use (written for an old version of sampletsr)
To compile this example, just run the file called MakeArray.bat. Your computer will need to have the tigcc command line compiler (v0.96 beta 6), and the TICT tools suite(v1.31) installed so that they work as regular command line tools. If you want to quickly create a TSR Event Hook, you could probably just jump right in, and start coding in the file called Hook.c, but I strongly recommend that you take the time to go through all of the source code and try to understand what is going on; although much if it can be very confusing at first.

I have used a two step compile process. First, the event hook is compiled (Hook.c). Next, it is converted in to a c style array (array.h). Following that, the array is included as a header file for the install program (Install.c). After compiling Install.c, the resulting binary is sent to the calculator. By using this multi-step process, several problems are solved such as finding the address of the main function (in this case it is Install_TSR), optimization levels, multiple functions etc...

How to use (new version wich is included in this archive)
Modifie the file Hook.c (the code in this file will be used as the TSR Event Hook) and save it.
Start MakeArray.bat. It will first compile the Hook.c file and then convert the binary file to the array in array.h.
Open InstallHook.tpr and modify the code if you have to. Then compile InstallHook.tpr.
Send the file InstallHook.xxz to your calculator and run installh().

My advice is:
Study the source code and understand what goes on as it could make your life easier...

Here is an outline of what to expect:

You should tell your users to install event hooks that are incompatible with Kevin's convention first, and the compatible ones last. Otherwise it becomes nearly impossible to uninstall a compatible event hook FYI: incompatible event hooks include shells such as DoorsOS

BUGS
***If you find a bug please PLEASE email me!***

You should note that some functions in the TIGCC library are not applicable to TSR programs.

At the time of this writing, all of the information presented in these files is believed to be accurate and true. However, I cannot guarantee the accuracy of this information. Changes in the TIGCC compiler, and/or the AMS could possibly leave this code broken.

Contact Me
Greg: gforce@calc.org (or Thomas: th.n@gmx.ch )
If you have any suggestions or bug reports please email me (I don't bite)
If you don't understand this (documentation) please ask me I will try to help you out as best as I can. You may also want to visit my webpage at http://gforce.calc.org first though; as I may have posted something there that could help you!

    A Small License
If you use this information, Please give me credit for it in your programs documentation. If you want to redistribute this, it must not be for profit, and the unmodified zip file in which this documentation is a part of should be included. You should also ask me first via email at gforce@calc.org. There is no warrantee implied or otherwise that pertains to this project.
Also, I am requesting that you sign the guest book on my website.

    Many thanks to:
Kevin Kofler     - h220xTSR.h and suggestions to improve the original code
Samuel Stearley - for getting me started on event hooks
Dave Watson    - The original install.c code was originally based on his on-key express event hook (boy that sounds wierd...!)
the TIGCC Team...
the TIGCC Programming Message board
the Assembly-89 mailing list
and anyone else who has directly or indirectly influenced this project.

Creating a TSR Event Hook using ASM
That is out of the scope of this document. If you are interested, but from an assembly language point of view, please go to ticalc.org and lookup the authors Samuel Stearley and Kevin Kofler. They have both written tsr event hooks in ASM, and have released the source code. It is simpler to create event hooks with ASM; the install code and event hook can be contained within one file eliminating the need for multiple files and a batch mode of compilation. I also have experience writing TSR's in ASM, but I have not released any Event Hook TSR's.

04/07/2006 - Version 3.1: Updated for new version of TIGCC by Thomas Naeff (tested with version 0.96 Beta 6). Added the latest h22xtsr v1.12 and UnInEvHk v4.00. Modified the SampleTSR-Readme.html.

10/22/2002 - Complete Rewrite of The source code!! Version 3.0 - Smaller, faster, and easier to maintain I hope :)

02/02/2002 - Updated some of the documentation, and updated my email and webpage addresses, recompiled with h220xtsr v1.05a...

11/10/2001 - Changed the source code so it should work with TIGCC .92 instead of crashing the calc if the binary was built with TIGCC .92...

10/20/2001 - Fixed a bug that could falsely report 'Already Installed' when in fact, there was no previous installation.

08/03/2001 - Recompiled with h220xtsr version 1.03 by Kevin Kofler. This prevents a bug on hw2 calcs when
changing batteries.

07/22/2001 - minor changes and updates. OPTIMIZE_ROM_CALLS should work perfectly now.

05/19/2001 - recompiled the program with Kevin Kofler's h220xTSR version 1.02a. This is a very important update since the version previously included (1.02) could cause HW2/ams2 calculators to crash. See h220xtsr.txt for more information.

04/21/2001 - worked on the documentation some more... updated it to reflect recent changes.

04/11/2001 - a few changes to the documentation.

04/02/2001 - finished this documentation. Also, I fixed a bug that could have caused a memory leak in low memory conditions on the calc; check out install.c for the change. I also added a detection algorithm which can tell if the tsr was previously installed on a calculator.

*The Hook Install Program*
Hook.tpr	A TIGCC project file that contains Hook.c
Hook.c	*This file contains the entire event hook. If you want to, you can use more than one .c file in your project if you make the necessary corrections to make.bat**

*The Actual TSR Event Hook*
InstallHook.tpr	A TIGCC project file that contains Install.c and array.h, h220xtsr.h, and h220xtsr.a
Install.c	The program that installs the event hook.
array.h	The Pre-compiled event hook (generated from Hook.c).

*Other Files*
MakeArray.bat	A batch file that builds the TSR hook for the calculator. You can look in it to find out the exact steps and compiler flags that are needed to compile the hook.
h220xtsr.txt and Related Files	Kevin Kofler's HW2 AMS2 support for TSR event hooks related files - Before you distribute your TSR's, I recommend checking Kevin's website to make sure that you are using the latest version of h220xtsr!!! This is _extremely_ important!

Byte Offset	Contents	Notes
0	evHk	the event Hook signature
4	xxxxxxxx	8 characters that represent your program's name. If you have extra characters left over, fill them in with spaces, or bad things will happen.
12	4 byte pointer to the next Hook that will be called if any.	Usually filled with EV_hook by the install program
16	jmp EventHandler	jumps to the event handler; it originally was jmp Install_TSR, but is modified to jump to the Event Handler by Install_TSR.
22+n	the event handler binary code and data