EVENT HOOK CONVENTIONS RECOMMENDED BY KEVIN KOFLER (document version 1.01)
==========================================================================

ENGLISH:
--------

The following are the conventions required for full compatibility with other event hooks and for compatibility with the UnInEvHk uninstaller:

I) Contents of the event hook
1) At the beginning
* signature: "evHk" (4 bytes)
* program name: 8 non-zero bytes (use spaces if you really need padding)
* placeholder for the address of the old event hook (4 bytes), 0 = no old event hook
* save all registers
2) At the end
* check if "old event hook" is non-zero
* if it is non-zero:
- copy the event structure to a2, because TeOS expects it there
- pass the event structure as an argument (on the stack on (a7))
- call it
* restore all registers
* use a normal RTS (RTE is only for interrupts and will NOT work)

II) Installation
* I recommend including the HW2 AMS 2 TSR support from: http://ti89prog.kevinkofler.cjb.net
If you do not want to include it, please tell your users that, if their calculator is hardware version 2.00 with Advanced Mathematics Software 2.0x, they need either the HW2Patch by Julien Muchembled or my HW2 AMS 2 TSR support to run any TSR (except the HW2 AMS 2 TSR support itself) without black bar crashes.
* store EV_hook to the "old event hook" placeholder in the event handler (EV_hook is 0 if there is no event hook installed, so it will automatically fit with my convention without a special treatment for this case.)
* allocate a handle using HeapAllocHigh
* Contrary to what v.1.00 of this document suggested, there is NO need to lock the handle explicitly since HeapAllocHigh does that automatically.
* dereference (HeapDeref) it
* copy the event handler to the locked handle
* add 0x40010 to the address of the handle:
- 0x40000 for HW 2 AMS 2 without HW2Patch (but the HW2 AMS 2 TSR support is needed in that case)
My HW2 AMS 2 TSR support needs this to work and all versions of UnInEvHk will refuse to uninstall your event hook if you do not do this (as a second protection against incompatible event hooks in addition to the "evHk" signature).
- 0x10 to skip the uninstall information
* store the resulting address to EV_hook

III) Uninstallation
Just include my UnInEvHk uninstaller and give me credit. There is no reason for having multiple uninstallers for the same convention.
Make sure you are distributing v.2.02 and not v.2.00 or v.2.01 which contained memory leak bugs.

IV) Notes about the usage in C
Always use the "-ffixed-a2" switch (under "Compiler Options" if you are using the TI-GCC IDE) to make sure a2 is not modified (else you would have to restore it manually with some inline assembly).
You might also have to use the "-mpcrel" switch (under "Compiler Options" if you are using the TI-GCC IDE) to make sure the code can be moved. If your program crashes, that's probably the reason. However, the best method is converting your event hook to a hex array to be relocated by your installer. That way, you can have more than one function and use TIGCCLIB calls. For how to do this, take a look at SampleTSR (see below).
Greg Dietsche has written a template for programming event hooks in C called SampleTSR. You can obtain it here: http://www.geocities.com/gdietsche/index.html

FRANAIS (FRENCH):
------------------

Les conventions suivantes sont ncessaires pour une compatibilit totale avec d'autres hooks d'vnements et pour la compatibilit avec le programme de dsinstallation UnInEvHk:

I) Contenus du hook d'vnements
1) Au dbut
* signature: "evHk" (4 octets)
* nom du programme: 8 octets non nuls (utilisez des espaces si vous avez vraiment besoin d'un remplissage)
* place rserve pour l'adresse du vieux hook d'vnements (4 octets), 0 = aucun vieux hook d'vnements
* sauvegarder tous les registres
2)  la fin
* vrifier si "vieux hook d'vnements" est non nul
* s'il est non nul:
- copier la structure d'vnements vers a2, parce que TeOS l'attend l
- passer la structure d'vnements comme un argument (sur la pile en (a7))
- l'appeler
* restaurer tous les registres
* utiliser un RTS normal (RTE est selement pour les interruptions et NE marchera PAS)

II) Installation
* Je conseille d'inclure le HW2 AMS 2 TSR support sur: http://ti89prog.francais.kevinkofler.cjb.net
Si vous ne voulez pas l'inclure, veuillez dire  vos utilisateurs que, si leur calculatrice a pour version matrielle 2.00 et pour version de Advanced Mathematics Software 2.0x, alors ils auront besoin soit du HW2Patch de Julien Muchembled, soit de mon HW2 AMS 2 TSR support pour excuter tout programme rsident en mmoire (sauf le HW2 AMS 2 TSR support lui-mme) sans plantages avec barre noire.
* sauvegarder EV_hook vers la place rserve pour le "vieux hook d'vnements" dans la routine manipulatrice d'vnements (EV_hook est 0 s'il n'y a aucun hook d'vnements install, donc ma convention sera automatiquement respecte sans tratement spcial pour ce cas-l.)
* allouer un bloc mmoire en utilisant HeapAllocHigh
* Contrairement  ce que la v.1.00 de ce document suggrait, il N'est PAS ncessaire de verrouiller le bloc explicitement parce que HeapAllocHigh le fait automatiquement.
* le drfrencer (HeapDeref)
* copier la routine manipulatrice d'vnements vers le bloc verrouill
* ajouter 0x40010  l'adresse du bloc:
- 0x40000 pour HW 2 AMS 2 sans HW2Patch (mais le HW2 AMS 2 TSR support est ncessaire dans ce cas)
Mon HW2 AMS 2 TSR support ncessite cela pour fonctionner et toutes les versions de UnInEvHk refuseront de dsinstaller votre hook d'vnements si vous ne faites pas cela. (C'est une deuxime protection contre les hooks d'vnements incompatibles en plus de la signature "evHk".)
- 0x10 pour sauter les informations pour la dsinstallation
* mmoriser l'adresse rsultante en EV_hook

III) Dsinstallation
Incluez simplement mon programme de dsinstallation UnInEvHk et donnez moi le crdit ncessaire. Il n'y aucune raison pour avoir plusieurs programmes de dsinstallation pour la mme convention.
Vrifiez que vous tes en train de distribuer la v.2.02 et non pas la v.2.00 ou la v.2.01 qui contenaient des bogues causant des pertes de mmoire.

IV) Remarques sur l'usage en C
Utilisez toujours l'option "-ffixed-a2" (sous "Compiler Options" si vous utilisez TI-GCC IDE) pour tre sr que a2 n'est pas modifi (sinon vous devriez le restaurer manuellement avec de l'assembleur inline).
Vous pourriez en plus avoir besoin de l'option "-mpcrel" (sous "Compiler Options" si vous utilisez TI-GCC IDE) pour tre sr que le code peut tre dplac. Si votre programme plante, la raison est probablement l. Cependant, la meilleure solution est de convertir votre hook d'vnements en un tableau hexadcimal  rallouer par votre installeur. Ceci vous permettra d'avoir plus d'une fonction et d'utiliser des appels  TIGCCLIB. Pour savoir comment le faire, veuillez jeter un coup d'oeil sur SampleTSR (voir ci-dessous).
Greg Dietsche a cr un programme exemple appel SampleTSR pour crire des hooks d'vnements en C. Il est disponible ici: http://www.geocities.com/gdietsche/index.html