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

FRANÇAIS (FRENCH):
------------------

Les conventions suivantes sont nécessaires pour une compatibilité totale avec d'autres hooks d'évènements et pour la compatibilité avec le programme de désinstallation UnInEvHk:

I) Contenus du hook d'évènements
1) Au début
* signature: "evHk" (4 octets)
  Remarque: La signature "EvHk" avec un "E" majuscule est obsolète et n'est plus acceptée par UnInEvHk.
* nom du programme: 8 octets non nuls (utilisez des espaces si vous avez vraiment besoin d'un remplissage)
* place réservée pour l'adresse du vieux hook d'évènements (4 octets), 0 = aucun vieux hook d'évènements
* sauvegarder les registres d3-d7/a2-a6
2) À la fin
* vérifier si "vieux hook d'évènements" est non nul
* s'il est non nul:
- copier la structure d'évènements vers a2, parce que TeOS l'attend là
- passer la structure d'évènements 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" (indépendant des kernels). Les kernels NE permettent PAS d'installer les hooks d'évènements de manière 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 matérielle 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 exécuter tout programme résident en mémoire (sauf le HW2 AMS 2 TSR support lui-même) sans plantages avec barre noire.
Sur la version matérielle 3, l'utilisateur devra TOUJOURS installer mon HW3Patch avant.
* sauvegarder EV_hook vers la place réservée pour le "vieux hook d'évènements" dans la routine manipulatrice d'évènements (EV_hook est 0 s'il n'y a aucun hook d'évènements installé, donc ma convention sera automatiquement respectée sans traîtement spécial pour ce cas-là.)
* allouer un bloc mémoire en utilisant HeapAllocHigh
* Contrairement à ce que la v.1.00 de ce document suggérait, il N'est PAS nécessaire de verrouiller le bloc explicitement parce que HeapAllocHigh le fait automatiquement.
* le déréférencer (HeapDeref)
* copier la routine manipulatrice d'évènements 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 nécessaire dans ce cas)
- 0x10 pour sauter les informations pour la désinstallation
La valeur de OFFSET est de:
- 0 ou 0x40000 sur HW1. Il est recommandé d'utiliser 0x40000 sur HW1 pour la compatibilité antérieure avec les vieilles versions de UnInEvHk.
- 0x40000 sur HW2. Mon HW2 AMS 2 TSR support nécessite cela pour fonctionner.
- 0 sur HW3. Il n'y a pas d'espace fantôme à 0x40000 sur HW3.
* mémoriser l'adresse résultante en EV_hook

III) Désinstallation
Incluez simplement mon programme de désinstallation UnInEvHk et donnez moi le crédit nécessaire. Il n'y aucune raison pour avoir plusieurs programmes de désinstallation pour la même convention.
Vérifiez que vous êtes en train de distribuer la v.4.00 ou supérieure. Les versions antérieures ne gèrent pas la TI-89 Titanium.

IV) Types d'évènements réservés.
Les numéros d'évènement 0x7F00-0x7FFF sont réservés pour la compatibilité avec la convention de hooks d'évènements dépassée 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 sûr 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 sûr que le code peut être déplacé. Si votre programme plante, la raison est probablement là. Cependant, la meilleure solution est de convertir votre hook d'évènements en un tableau hexadécimal à réallouer 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'évènements en C. Il est disponible ici: http://calc.gregd.org