Ti-Fr v3 !

Article TI [Programmation]

Articles sur la programmation des TI68k

Tutorial : Programmation de TSR en ASM

Comment programmer un TSR fonctionnel sur TI

La version ZIP de ce tutorial est disponible ICI

Ce tutorial a pour objectif de présenter la programmation de programmes résidents sur calcultrices TI-68k. Ainsi, on pourra grâce à ces infos programmer un petit soft qui clôturerait automatiquement les parenthèses...

Un grand merci à Flanker de nous l'avoir rédigé.

- Tutorial ASM : lesTSR ( page 1 ) -

Programmation assembleur : les TSR 'Event Hook'

Programmation de TSR 'Event Hook' en assembleur 68000

	Flanker, 18 avril 2004
	Le texte suivant s'adresse à ceux qui connaissent déjà la programmation en assembleur 68000 pour les TI89 / TI92Plus / Voyage 200. Il a été écrit pour leur permettre de comprendre les bases de la programmation des TSR du type 'Event Hook', respectant certaines conventions.
	Qu'est-ce donc qu'un TSR sur une TI ?
	C'est un programme (petit, de préférence) dont il reste des morceaux après son exécution. Un programme standard se lance en tapant nomduprogramme() dans le Home et se termine en libérant la mémoire qu'il a utilisé (normalement) quand il retourne au Home. Un TSR s'exécute en tapant nomdutsr() dans le Home, mais ne termine pas son exécution quand il retourne au Home. Il va laisser des bouts de code dans la mémoire pour pouvoir continuer d'agir discrètement (d'où le nom : TSR == Terminate and Stay Resident - Termine et reste en mémoire) de façon souvent transparente. Ici, on va apprendre à coder un certain type de TSR, qui ont la signature EvHk (pour Event Hook, j'en donnerai plus bas la définition)
	Comment fonctionnent ces TSR ?
	Les TSR ici étudiés s'appellent également des Event Hooks, ou Hooks tout court ("crochets d'événements", ou "crochets"). Ils "attrapent" des événements et agissent en fonction de ceux-ci. Pour comprendre ce qu'est un événement pour la TI et comment cela fonctionne, il faut connaître un minimum le fonctionnement de l'AMS : Les applications flash (y compris le Home, le Program Editor, le Y=Editor, ...) ne fonctionnent pas comme les programmes "classiques". Une boucle infinie extérieure à tout programme et aux applications collecte tous les événements (Events) et les envoie à l'app flash actuelle. L'application flash traite l'événement (si c'est une touche correspondant à une lettre dans un éditeur, par exemple, l'éditeur va insérer la lettre à l'endroit du curseur), puis quitte et retourne à la boucle extérieure qui va pouvoir continuer déroulement. Les événements peuvent être de différentes sortes : - des touches - une demande d'insertion de chaîne de caractères - un avis du système pour prévenir l'app flash qu'on veut l'utiliser ... Ce qui est pratique, c'est que l'AMS regarde si EV_Hook contient un adresse de fonction, et si c'est le cas, lui envoie l'événement. A la base, cette fonctionnalité de l'AMS devait servir pour faire du débugguage (il me semble). Nous, on va pouvoir détourner son usage pour voir quels sont les événements envoyés et les modifier à notre guise. Pour la culture gé', cette fameuse boucle extérieure s'appelle EV_eventLoop, alias ROM_CALL_158. La routine de l'application flash qui va traiter tous les events s'appelle un Event_Handler. En (très) gros, EV_eventLoop ressemble à ça :
	while(1){ //je vous l'avais dit que c'était une boucle infinie ! EV_getc(busy, event); //récupère la touche appuyée, éteind la calc si ça dure trop longtemps, etc ... EV_Hook(event); //c'est à ce niveau là que le tsr agit App_Event_Handler(*event); //envoie l'event à l'Application flash actuelle pour qu'elle en fasse quelque chose (de bien si possible : insérer le caractère si l'event est une touche alphabétique, par exemple) }
	Pour plus de détails sur ces intéressantes fonctions, vous devriez vous reporter à la documentation de TIGCC ou de TIFlashStudio.
	"Ghost space" ?
	En français, on pourrait traduire par l'espace fantôme. Sur les TI-89 / TI-92Plus / Voyage 200, la RAM correspond aux adresses comprises entre 0x0 et 0x40000-1, alors que la mémoire flash correspond aux adresses comprises entre 0x200000 et 0x600000-1. Il y a donc un "trou" entre la RAM et la mémoire Flash, qui ne correspond à aucune mémoire physique. En fait, la RAM est dupliquée 7 fois ebtre 0x40000 et 0x200000-1, i.e. si on lit ou écrit à l'adresse x(0x0 <= x < 0x40000) et à l'adresse x + k*0x40000 (0 <= k < 8), les 2 opérations auront exactement le même résultat (exception faite en écriture pour x < 0x120 - consultez un texte sur les ports de la TI et regardez à 0x600001.2). Le ghost space est chacune de ces copies de la RAM. Comme les écritures et les lectures ont le même résultat, on pourrait se dire que le ghost space ne sert à rien, mais il n'en est rien car Texas Instruments a placé des protections matérielles pour qu'on ne puisse pas exécuter en RAM du code assembleur qui fasse plus de 24ko : et cette protection s'avère inefficace dans le ghost space sur les HW2. Pour contourner cette protection, il faut donc que le TSR soit placé dans le Ghost Space. Par habitude, on prend k=1 dans l'exemple précédent, ce qui revient à faire un OR logique entre l'adresse de notre TSR et 0x40000.
	Qu'en est-il des TSR sur la TI-89Titanium ?
	Je ne dispose que d'assez peu d'informations sur la Titanium, mais apparement la protection matérielle protège aussi bien la RAM physique que le ghost space (qui au passage se trouve à 0x200000 et on à 0x40000), donc pour l'instant, je ne sais pas comment outrepasser cette protection :(
	Comment programmer un Hook ?
	Méthode 1 : Vous vous arrêtez ici de lire et vous mettez directement votre code dans le fichier my_tsr.h de mon TSR tutorial. Le pointeur vers la structure event est a4, celui vers la jump table est a5 Méthode 2 : Lisez ce texte en entier, puis les fichiers hook_conv et hook_conv2 de mon TSR tutorial. Vous regardez les fichiers tutorial.asm et init_tsr.h avant, en essayant de les comprendre, puis vous appliquer la méthode 1 Méthode 3 : Vous faites comme moi : vous prenez un Hook pas trop gros (bestview, par exemple) en espérant qu'il est programmé proprement, vous le désassemblez avec un désassembleur à la volée on-calc et vous essayez de comprendre la source obtenue. Méthode 4 : Il faut d'abord s'allouer un bloc de mémoire (handle) en mémoire haute (pour ne pas déranger) et le verrouiller. Cela se fait facilement avec le ROM_CALL HeapAllocHigh. Ce handle contiendra le code du TSR ; pour calculer sa taille, il suffit d'encadrer le code correspondant à la partie installée en RAM de votre programme par BEGINNING_OF_HOOK et END_OF_HOOK et d'appeler HeapAllocHigh avec (END_OF_HOOK-BEGINNING_OF_HOOK) comme argument. Ensuite, il faut recopier le TSR dans ce handle et enfin il faut "activer" votre TSR, i.e. mettre son adresse (ORée avec 0x40000) dans la variable globale EV_Hook. Pour respecter un certain standard de TSR, il ne faut que le handle du TSR débute par un petit header : d'abord une signature 'EvHk' ensuite le nom de votre TSR, qui doit faire impérativement 8 caractères ensuite la valeur d'EV_Hook avant votre passage. et enfin le début de votre code. En bref, le code à recopier dans le handle doit ressembler à ça :
	BEGINNING_OF_HOOK: dc.b 'EvHk' ;c'est la signature (purement conventionnelle) des TSR. S'ils ne portent pas cette signature, ils ne pourront pas être dsinstallés par les désinstalleurs UnHook, CS et UnInEvhK nom_du_tsr: dc.b 'Tutorial' ;mettre le nom du TSR ici - il doit faire 8 lettres exactement ! old_event: dc.l 0 ;un trou où on place l'adresse de l'ancien EvHk, qui sera appelé par Tutorial juste après. Il est également utilisé par les désinstalleurs pour parcourir la liste des TSR (c'est pour ça qu'il ne faut pas changer sa place) beginning: ;voilà le début du code qui sera effectivement appelé à chaque event movem.l d0-d7/a0-a6,-(a7) ;on sauvegarde les registres sur la pile move.l 64(a7),a4 ;l'adresse de l'event est placée sur la pile avant l'appel à notre TSR, il faut donc la récupérer ;ici on peut mettre tout le code utile move.l a4,a2 ; TeOS s'attend à trouver l'adresse de l'Event dans a2, c'est uniquement pour cette raison qu'on fait ça move.l old_event(pc),a0 ;il faut bien récupérer l'adresse du TSR suivant dans la liste ... move.l a0,d0 ;on regarde s'il y en a vraiment un beq no_old_hook move.l a2,-(a7) ; on met l'argument (l'adresse de l'event) sur la pile jsr (a0) ; on appelle l'event suivant addq.l #4,a7 no_old_hook: movem.l (a7)+,d0-d7/a0-a6 ; on restaure les registres rts ;ici aussi on peut mettre du code END_OF_HOOK:
	Le code d'installation devrait ressembler à ça :
	move.l EV_hook,a4 ; l'adresse où est stockée l'adresse du Hook actuel (=0 s'il n'y a pas de Hook, mais qu'il y en ait ou pas n'a pas d'importance) lea old_event(pc),a0 ;l'adresse où on va enregistrer l'adresse du Hook actuel pour pouvoir l'appeler move.l (a4),(a0) move.l #END_OF_HOOK-BEGINNING_OF_HOOK,d3 ; c'est pour calculer la taille du TSR. On alloue un bloc de la même taille dans la mémoire et on recopie notre TSR dedans move.l d3,-(a7) ROM_CALL HeapAllocHigh ; on alloue un handle (i.e. un bloc de mémoire) tout en le verrouillant addq.l #4,a7 tst.w d0 beq tsr_memory_error ; il n'y a pas assez de mémoire, c'est dommage :( move.w d0,-(a7) ROM_CALL HeapDeref addq.l #2,a7 move.l a0,(a4) ; on place l'adresse de notre nouveau Hook à l'endroit qu'il faut pour qu'il soit appelé add.l #$40010,(a4) ; ça c'est des histoires de ghost space... ; le 0x10 (=16) vient du fait que le code exécutable est après le header de 16 octets ;copie du TSR dans le bloc en mémoire subq.l #1,d3 lea BEGINNING_OF_HOOK(pc),a1 \loop: move.b (a1)+,(a0)+ dbra d3,\loop
	Rappelons quelques lignes du fichier hook_conv.txt, qui décrit le standard que j'essaie d'expliquer :
	I) Contenus du hook d'évènements 1) Au début * signature: "EvHk" (4 octets) Remarque: Les anciens hooks ne supportant pas la section IV utilisent une signature "evHk" à la place. * 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) UR 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 * 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 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. * 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 0x40010 à l'adresse du bloc: - 0x40000 pour HW 2 AMS 2 sans HW2Patch (mais le HW2 AMS 2 TSR support est nécessaire dans ce cas) Mon HW2 AMS 2 TSR support nécessite cela pour fonctionner et toutes les versions de UnInEvHk refuseront de désinstaller votre hook d'évènements si vous ne faites pas cela. (C'est une deuxième protection contre les hooks d'évènements incompatibles en plus de la signature "EvHk".) - 0x10 pour sauter les informations pour la désinstallation * mémoriser l'adresse résultante en EV_hook

	Existe-t-il d'autres types de TSR sur TI ?
	Oui. Les Hooks sont les plus nombreux, mais les plus utilisés restent les kernels, qui n'utilisent pas EV_Hook (ils sont appelés par les programmes ou agissent via le biais d'interruptions système)
	Peut-on programmer les event hook en mode kernel ?
	Pour l'instant, non, à moins de passer par un hack tout vilain :( Les kernels ont l'habitude de nettoyer la RAM en supprimant les blocs de mémoire laissés après l'exécution d'un programme, et donc dans le cas d'un TSR, ça supprimerait le bloc contenant notre code, ce qui serait fort regrettable. Avec PreOS, on peut dire de laisser tranquille un handle, mais il restaure EV_Hook que nous venons de modifier, effaçant par là même toute possibilité d'appel à notre routine TSR donc notre TSR serait abandonné en RAM sans qu'il soit jamais appelé. Ca serait un triste sort pour un tsr :'( Aux dernières nouvelles, ça serait possible avec PreOS 0.70 (mais il n'est pas encore sorti)
	Où peut-on trouver une source pas trop dure à comprendre pour s'en inspirer ?
	J'ai codé un TSR qui ne fait pas grand'chose, mais dont j'ai pris soin de bien commenter la source afin qu'elle soit plus facile à comprendre et à modifier pour lui faire faire ce que vous voulez. Il est disponible ici.
	Un grand merci à Squale92 pour son attentive relecture et ses nombreux et pertinents commentaires !!!!

Flanker(2004-04-20 07:42:00)

- Tutorial ASM : lesTSR ( page 1 ) -

En cas de problème avec un article veuillez contacter DIRECTEMENT l'auteur. Merci.

News	Archives	FAQ	Communauté	Projets
News Non Officielles	Le site	TiWiki	Liens