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

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).
  Note: The "EvHk" signature with a capital "E" is deprecated and no longer supported by UnInEvHk.
* 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 the d3-d7/a2-a6 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 the d3-d7/a2-a6 registers
* use a normal RTS (RTE is only for interrupts and will NOT work)

II) Installation
* Your installation program MUST be "nostub" (kernel-independent). Kernels will NOT allow installing event hooks reliably and conformingly to this convention.
* 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, or my HW3Patch to run any TSR (except the HW2 AMS 2 TSR support itself) without black bar crashes.
On hardware version 3, the user will ALWAYS need to install my HW3Patch beforehand.
* 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 OFFSET+0x10 to the address of the handle:
- OFFSET for HW 2 AMS 2 without HW2Patch (but the HW2 AMS 2 TSR support is needed in that case)
- 0x10 to skip the uninstall information
The value of OFFSET is:
- either 0 or 0x40000 for HW1. It is recommended to use 0x40000 on HW1 for backwards compatibility with old versions of UnInEvHk.
- 0x40000 for HW2. My HW2 AMS 2 TSR support needs this to work.
- 0 for HW3. There is no ghost space at 0x40000 on HW3.
* 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.4.00 or higher. Older versions don't support the TI-89 Titanium.

IV) Reserved event types
Event type codes 0x7F00-0x7FFF are reserved for backwards-compatibility with the obsolete event hook convention 2.00. Do NOT use them for ANY purpose.

V) 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://calc.gregd.org

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)
  Remarque: La signature "EvHk" avec un "E" majuscule est obsolte et n'est plus accepte par UnInEvHk.
* 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 les registres d3-d7/a2-a6
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 les registres the d3-d7/a2-a6
* utiliser un RTS normal (RTE est selement pour les interruptions et NE marchera PAS)

II) Installation
* Votre programme d'installation DOIT tre "nostub" (indpendant des kernels). Les kernels NE permettent PAS d'installer les hooks d'vnements de manire fiable et conforme  cette convention.
* 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, soit de mon HW3Patch pour excuter tout programme rsident en mmoire (sauf le HW2 AMS 2 TSR support lui-mme) sans plantages avec barre noire.
Sur la version matrielle 3, l'utilisateur devra TOUJOURS installer mon HW3Patch avant.
* 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 OFFSET+0x10  l'adresse du bloc:
- OFFSET pour HW 2 AMS 2 sans HW2Patch (mais le HW2 AMS 2 TSR support est ncessaire dans ce cas)
- 0x10 pour sauter les informations pour la dsinstallation
La valeur de OFFSET est de:
- 0 ou 0x40000 sur HW1. Il est recommand d'utiliser 0x40000 sur HW1 pour la compatibilit antrieure avec les vieilles versions de UnInEvHk.
- 0x40000 sur HW2. Mon HW2 AMS 2 TSR support ncessite cela pour fonctionner.
- 0 sur HW3. Il n'y a pas d'espace fantme  0x40000 sur HW3.
* 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.4.00 ou suprieure. Les versions antrieures ne grent pas la TI-89 Titanium.

IV) Types d'vnements rservs.
Les numros d'vnement 0x7F00-0x7FFF sont rservs pour la compatibilit avec la convention de hooks d'vnements dpasse 2.00 et NE sont  destiner  AUCUN usage.

V) 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://calc.gregd.org