Assembleur 32/64 bits GoAsm

GoAsm est couvert par le Copyright © Jeremy Gordon 2001-2016 [MrDuck Software] - all rights reserved.

Vous pouvez utiliser GoAsm à toutes fins, y compris des programmes commerciaux. Vous pouvez le redistribuer librement (mais sans contrepartie financière, ni l'utilisation avec un programme ou tout autre matériau pour lequel l'utilisateur est invité à payer). Vous n'êtes pas habilité à masquer ou à contester mes droits d'auteur.

J'ai fait tous les efforts possibles pour faire en sorte que GoAsm et son programme d'accompagnement AdaptAsm soient au point, mais vous les utilisez entièrement à vos risques. Je ne peux accepter la moindre responsabilité concernant leur fonctionnement, le travail produit, ni les conséquences d'erreurs entachant éventuellement ce manuel.

Un mnémonique est une instruction sous forme de texte que vous utilisez dans votre script source assembleur. GoAsm assemble ces mnémoniques et les convertit en codes opération (opcodes) que le processeur exécute. Ces codes opération sont parfois appelés codes machine. Les mnémoniques sont recommandés par les fabricants de processeurs. Ils sont destinés à transmettre sous forme abrégée et aussi précisément que possible ce que l'instruction fait. Bien qu'il existe maintenant plus de 550 mnémoniques, un programmeur en assembleur n'en utilise seulement que 20 ou 30 régulièrement. Voir une proposition de liste des mnémoniques les plus couramment utilisés dans l'annexe consacrée aux débutants en assembleur.

Pour des raisons de portabilité des scripts source et de cohérence en prévision d'éventuelles mises à jour, tous les assembleurs reconnaissent normalement les mnémoniques au niveau où ils se rejoignent dans la fonction d'assemblage. Pour autant, le processeur ignore les mnémoniques et ne fonctionne que dans le code de la machine lui-même. Les programmeurs non familiers de l'assembleur n'utilisent jamais les mnémoniques. Un compilateur travaillant uniquement en « C », par exemple, produit encore du code machine, mais il ne fonctionne pas avec les mnémoniques en tant que tels (sauf basculé en mode assembleur en ligne).

GoAsm prend en charge tous les mnémoniques correspondant aux instructions à usage général, y compris les instructions x87 en virgule flottante, les instructions MMX, 3DNow! (avec les extensions), SSE, SSE2, SSE3 et SSSE4, ainsi que AES, ADX, et quelques autres nouvelles instructions. GoAsm prend en charge les instructions pseudo CMP qui peuvent être utilisées avec les registres XMM.

GoAsm ne supporte pas certains mnémoniques qui sont utilisés uniquement pour la programmation 16 bits. C'est le cas de IBTS, IRETW, JCXZ, RETF et XBTS.

Enfin, GoAsm ne supporte pas les mnémoniques qui nécessitent des opérandes supplémentaires, et les cas où il existe des mnémoniques plus faciles à utiliser. Entrent dans cette catégorie :

CMPS	; utiliser CMPSB ou CMPSD
INS	; utiliser INSB ou INSD
LODS	; utiliser LODSB ou LODSD
MOVS	; utiliser MOVSB ou MOVSD
OUTS	; utiliser OUTSB ou OUTSD
SCAS	; utiliser SCASB ou SCASD
STOS	; utiliser STOSB ou STOSD
XLAT	; utiliser XLATB

Si la spécification du nom du fichier d'entrée ne comporte pas d'extension, GoAsm cherche le fichier sans aucune extension. Si ce fichier est introuvable en tant que tel, GoAsm recherche à nouveau le même fichier agrémenté d'une extension .asm.

Si aucun chemin d'accès ne précède le nom du fichier d'entrée, ce dernier est supposé être localisé dans le répertoire courant.

Si aucun nom de fichier n'est précisé pour la création du fichier objet, celui-ci est créé avec le même nom que le fichier d'entrée et affecté de la terminaison .obj. Par exemple MyAsm.asm va créer un fichier appelé MyAsm.obj.

Le répertoire qui reçoit le fichier de sortie est :

• le chemin d'accès spécifié si /fo est utilisé, ou si on ne le mentionne pas :
• le répertoire courant si /c est spécifié, ou si on n'utilise pas ce commutateur :
• le chemin d'accès associé au fichier d'entrée, ou si aucun répertoire n'est donné :
• le répertoire courant.

Si aucune extension n'est précisée pour le fichier de sortie, .obj est créée par défaut. Le fichier de listing d'assemblage emploie le même nom que le fichier de sortie, mais avec l'extension .lst et il est créé, par ailleurs, dans le même répertoire que celui-ci.

Vous devez déclarer une section avant que vous ne commenciez à coder. La raison en est que le processeur a besoin de connaître les attributs des instructions qui lui sont adressées. Notez également que le système Windows se repose sur ces attributs pour identifier les parties de votre code. Les attributs les plus courants sont la lecture seule (ne peut pas recevoir d'écriture), la lecture-écriture (peut recevoir une écriture) et l'exécution (instructions de code). En interne, les processeurs traitent l'instruction de la manière la plus appropriée et la plus rapide en rapport avec l'attribut. Par exemple, les instructions de code utilisent le code cache du processeur, le matériau non constitutif de code est assimilé à des données et peut être pris en charge par le cache de données.

Lorsque vous déclarez une section dans votre script source, GoAsm définit automatiquement l'attribut de la section. Une fois ceci fait, vous pouvez commencer à écrire le code ou les données dans votre programme.

En programmation Windows, nous sommes intéressés par seulement quatre types de sections : le code, les données, les constantes, et les données non initialisées. Vous déclarez le code, les données ou les sections de constantes comme suit :

CODE		SECTION
DATA		SECTION
CONST		SECTION
; ou 
CONSTANT	SECTION

Les mots CODE, DATA, CONST et CONSTANT sont réservés à la déclaration des sections et une erreur sera signalée si ces mots sont utilisés ailleurs dans votre source.

GoAsm permet également de raccourcir les formes de déclaration de section comme suit :

CODE
DATA
CONST

Vous pouvez également utiliser

.CODE
.DATA
.CONST

si vous le souhaitez.

GoAsm ajoute automatiquement les attributs en fonction du processeur et de Windows. Une section de code reçoit les attributs lecture, exécution, code. Une section de données est dotée des attributs lecture, écriture, données initialisées. Une section const reçoit les attributs lecture, données initialisées (vous ne pourriez pas écrire dans une section const). Les données non initialisées possèdent les attributs lecture, écriture, données non initialisées.

À défaut d'ajouter l'attribut SHARED, vous ne pouvez faire fi de ces attributs de votre propre initiative. Ceci est inutile car Windows s'arroge le contrôle total sur les attributs de la section lorsqu'elle est chargée et exécutée. Par exemple, même si vous donnez à une section de code l'attribut d'écriture, Windows ne vous permettra pas d'écrire dedans. De la même manière, Windows ne vous permettra pas d'exécuter du code dans une section de données. Vous pouvez néanmoins déroger à ce comportement en appelant l'API VirtualProtect au moment de l'exécution.

Dans GoAsm vous pouvez inclure des données en lecture seule (read-only) dans une section de code, même s'il peut en résulter une réduction des performances.

Déclarer une section positionne implicitement certains commutateurs dans GoAsm qui affectent la syntaxe et le codage. Les règles sont les suivantes.

• Tous les labels d'une section de code doivent impérativement se terminer par deux points. Cela permet à GoAsm de distinguer un label de ce qui n'en est pas un, de veiller à ce que les mnémoniques et les directives mal orthographiés soient toujours signalés comme une erreur.
• Les labels réutilisables ne sont autorisés que dans une section de code. Si vous les utilisez dans une section de données, ils seront considérés comme des labels uniques et intégrés à ce titre dans la table des symboles.
• GoAsm signalera une erreur si une instruction tente d'écrire dans une section const. La section const est destinée aux données et chaînes initialisées qui ne sont pas appelées à recevoir une écriture.

Si vous déclarez des données non initialisées, GoAsm constitue une section spécifique de données non initialisées dans le fichier-objet. Elle sera nommée « .bss » en considération d'autres outils. GoAsm lui attribue d'office ce nom que vous ne pouvez pas modifier parce que certains linkers s'attendent précisément à le trouver. Avec la plupart des linkers, y compris GoLink, la section .bss ne trouve pas sa place dans l'exe final. Au lieu de cela, elle est fusionnée avec une section d'attribut lecture/écriture dans le fichier exe. Les attributs de la section de données non initialisées sont la lecture, l'écriture, les données non initialisées.

L'avantage de déclarer des données non initialisées, plutôt que des données initialisées, est que l'exécutable est plus petit. Ceci, parce que l'exécutable se borne à spécifier la quantité de données non initialisées à réserver sans leur attribuer la moindre valeur. Les buffers de toute sorte sont souvent constitués ainsi. Voir la section déclaration des données non initialisées ordinaires.

Rien n'oblige le programmeur à écrire de grandes sections indivisibles. Par exemple, il est tout à fait envisageable d'avoir une portion de données suivie d'une portion de code, elle-même suivie par une nouvelle portion de données et ainsi de suite, sous réserve de prendre soin d'en déclarer la nature à chaque fois avec un des mots-clés suivants :

CODE	SECTION
DATA	SECTION
CONST	SECTION

ou leur forme abrégée, le cas échéant. Vous pouvez le faire aussi souvent que vous le souhaitez au travers de votre script source. GoAsm et l'éditeur de liens se chargent de concaténer toutes les instructions destinées à chaque section.

Voir aussi sections - gestion avancée sur les dénominations de sections, les sections partagées, les sections de commande, et les considérations liées à l'alignement de la section.

D'une certaine manière toutes les instructions transmises à un processeur sont des « données ». Mais les programmeurs en assembleur utilisent ce mot pour désigner une information qui est, soit fixe, soit susceptible d'être modifiée au moment de l'exécution et qui ne peut pas être exécutée en tant qu'instruction de processeur. Les données peuvent être classées en quatre catégories.

1. Les données en lecture seule - read-only - spécifiées en tant que telles à la phase d'assemblage (lorsque le programme est compilé) et qui sont conservées dans la section const qui a un attribut de lecture seule. On parle alors de « données initialisées » parce que leur contenu est fixé dans le script source. Au moment de l'exécution, ces données peuvent être lues, mais on ne peut écrire dessus et modifier ainsi leur contenu. Dans votre script source, vous devez leur attribuer des labels de sorte qu'elles puissent être référencées facilement.
2. Les données fixées au moment de l'assemblage et localisées dans la section de données du fichier exécutable. Encore une fois, le contenu des données sera fixé dans votre script source mais, au moment de l'exécution, elles pourront être lues ou modifiées en utilisant les labels de donnée correspondants.
3. Les données non fixées au moment de l'assemblage, mais qui sont localisées dans une zone qui leur est réservée. Il s'agit des « données non initialisées » et seule leur taille est recensée dans le fichier exécutable. Dans votre script source assembleur vous spécifiez la quantité de données devant être réservées. Vous pouvez leur attribuer des labels, mais vous ne pouvez pas initialiser leur contenu. L'avantage de ce type de données est qu'elles ne prennent pas de place dans l'exécutable. Au moment du chargement, les données sont seulement localisées et ne reçoivent pas de contenu donné à ce stade. Au moment de l'exécution, les données de ce type peuvent être lues ou écrites de la même manière que leurs homologues de la section de données.
4. Les données établies au moment de l'exécution, soit par le programme lui-même, soit par le système. Ces données ne sont pas établies au moment de la phase d'assemblage de votre script source. Elles le sont, en réalité, par le système d'exploitation lorsque votre code est exécuté.

GoAsm se conforme à la syntaxe assembleur traditionnelle pour déclarer des données dans votre script source.

Dans une section data ou cons, un label ne doit pas être terminé par deux points. Dans une section de code cela est nécessaire, pour favoriser l'identification des erreurs de syntaxe. Quelques exemples (utilisant une section de données) :

HELLO1	DB 0			;  1 octet avec le label "HELLO1" fixé à zéro
	DB 0			;  le second octet fixé à zéro
HELLO2	DW 34h			;  2 octets (soit un mot) fixé à la valeur 34h
HELLO3	DD 12345678h		;  4 octets (un dword) fixés à la valeur 12345678h
HELLO4	DD 12345678D		;  4 octets (un dword) fixés à la valeur décimale 12345678
HELLO5	DD 1.1			;  4 octets (un dword) fixés à la valeur du nombre réel 1.1
HELLO6	DQ 0.0			;  8 octets (un qword) fixés à la valeur du nombre réel 0.0
HELLO7	DQ 123456789ABCDEFh	;  8 octets (un qword) fixés à la valeur 123456789ABCDEFh
HELLO8	DQ 1234567890123456	;  8 octets (un qword) fixés à la valeur décimale 1234567890123456
HELLO9	DT 1.1E0		; 10 octets (un tword) fixés à la valeur du nombre réel 1.1
HELLOA	DT 123456789ABCDEFh	; 10 octets (un tword) fixés à la valeur 123456789ABCDEFh

Notez que DB, DW, DD et DQ acceptent les nombres aussi bien dans le format décimal qu'hexadécimal ; DD, DQ et DT acceptent également les nombres réels.

Voir les sections déclaration des nombres réels, chargement direct de l'exposant et de la mantisse et chargement d'un fichier avec INCBIN.

Une virgule après un initialiseur signifie qu'un autre initialiseur est attendu afin de déclarer d'autres données. La syntaxe est la suivante :

Label	DB	0, 0, 0, 0		; 4 octets fixés à zéro
	DW	33h, 44h, 55h, 66h	; 4 mots initialisés
	DD	33h, 44h, 55h, 66h	; 4 dwords initialisés
	DD	1.1, 2.2		; 2 DD de nombres réels
	DQ	1.1, 2.2		; 2 DQ de nombres réels
	DQ	3333h, 4444h		; 2 DQ de nombres hexa
	DT	1.1, 2.2		; 2 DT de nombres réels
	DT	5555h, 6666h		; 2 DT de nombres hexa

GoAsm rejoint ici la syntaxe traditionnelle des assembleurs mais, à l'instar de A386, il ne nécessite pas de section non initialisée (la section .bss) pour déclarer ce type de variable. Au lieu de cela, un simple point d'interrogation garantit que la donnée est considérée comme non initialisée. Quelques exemples (dans les sections texte data ou const) :

HELLO1	DB	?	;  1 octet avec le label "HELLO1" enregistré comme non initialisé
HELLO2	DW	?	;  2 octets (word)
HELLO3	DD	?	;  4 octets (dword)
HELLO4	DQ	?	;  8 octets (qword) 
HELLO5	DT	?	; 10 octets (tword)

Les données non initialisées orphelines ne sont pas permises : vous ne pouvez pas mélanger les données initialisées et non initialisées, à défaut de quoi vous provoquez une erreur :

DATA6	DD	5 DUP 0
	DB	?	; déclaration non autorisée
	DB	0

En revanche, l'écriture qui suit est parfaitement correcte :

DATA6	DD	5 DUP ?	; 5 dwords pour le client
	DB	?	; un octet pour avoir le plat principal
	DB	?	; et un octet pour avoir les sauces

Ceci vous permet de séparer les zones de données non initialisées de sorte que chaque zone séparée puisse avoir son propre commentaire.

Les données non initialisées ne peuvent pas être déclarées tant qu'une section n'a pas été ouverte. Vous pouvez déclarer des données non initialisées au sein de la section de code, mais les labels doivent se terminer par deux points comme il est de règle pour la section de code, par exemple :

HELLO1:	DB	?	; 1 octet avec le label "HELLO1" enregistré comme non initialisé
HELLO2:	DW	?	; 2 octets (un word)

GoAsm utilise la syntaxe DUP bien connue, mais ne nécessite pas d'initialiseur entre parenthèses. Quelques exemples (dans la section de données) :

HELLO1	DB	2 DUP 0		; 2 octets avec le label "HELLO1" tous les deux initialisés à zéro
HELLO1A	DB	800h DUP ?	; 2K de buffer de données non initialisées
HELLO2	DW	2 DUP 0		; 4 octets tous fixés à zéro
HELLO3	DD	2 DUP ?		; 8 octets dans la section non initialisée
HELLO4	DD	2 DUP 1.1	; nombre réel 1.1 dans dword répété 1 fois
HELLO5	DQ	2 DUP 1.1	; nombre réel 1.1 dans qword répété 1 fois
HELLO6	DQ	2 DUP 333h	; qword répété 1 fois
HELLO7	DT	2 DUP 1.1	; nombre réel 1.1 dans tword répété 1 fois
HELLO8	DT	2 DUP 444h	; tword répété 1 fois

Vous pouvez utiliser DUP pour déclarer une donnée globalement, puis en initialiser individuellement chaque élément :

HELLO300	DB	3 DUP <23, 24, 25>	; déclare 3 octets et les initialise respectivement à 23, 24, 25

qui fait la même chose que :

HELLO300	DB	23, 24, 25	; déclare 3 octets et les initialise respectivement à 23, 24, 25

Bien qu'il puisse sembler inutile d'y recourir, la syntaxe rend plus facile l'initialisation d'un membre d'une structure si celui-ci contient l'opérateur DUP Voir la section initialisation de membres de structure avec déclarations de données DUP.

Au lieu de devoir initialiser des caractères par le biais de leur code ASCII, vous pouvez obtenir plus directement ce résultat en vous bornant à déclarer les caractères entre guillemets. Par exemple :

Letters	DB	'a'		; au lieu de DB 61h
	DW	'xy'		; au lieu de DW 7978h
Sample	DD	'form'		; au lieu de DD 6D726F66h
ZooDay	DQ	'Saturday'	; au lieu de DQ 7961647275746153h

Exception faite du cas de l'insertion de chaînes Unicode, GoAsm ne réalise pas de conversion du caractère, de sorte que la valeur réelle insérée dans le fichier objet dépendra du jeu de caractères courant au moment de l'assemblage.

GoAsm ne mémorise pas le mot et les déclarations de chaîne Word et DWord ci-dessus en utilisant le stockage inverse. Il rejoint en cela la pratique de NASM qui a pris le contrepied de MASM en la matière. Cela signifie que l'octet de poids faible dans DW 'xy' est 'x' et que 'y' est l'octet de poids fort. De même dans DD 'form' correspondant au label Sample, l'octet de plus faible poids est 'f' et ainsi de suite jusqu'à l'octet de plus fort poids qui est 'm'. L'avantage de cette configuration est de vous permettre, par exemple, de transférer très simplement cette chaîne au moyen du codage ci-dessous :

MOV	EDI, ADDR BUFFER
MOV	EAX, [Sample]
STOSD

qui insère dans le buffer la chaîne 'form'.

Les octets non initialisés reçoivent la valeur zéro. Par exemple :

DW	'a'	; le premier octet est 'a', le second est nul
DD	'ab'	; 'a' puis 'b' puis 2 octets à zéro

On peut répéter les initialisations de valeur de caractère, par exemple :

DD	3 DUP "Hi"

Cela insère 'H' puis 'i' puis deux zéros, cette opération étant répétée à trois reprises.

Les chaînes peuvent être entre guillemets simples ou doubles. En voici quelques exemples d'utilisation :

String1	DB	'Ceci est une chaîne'
	DB	'Ceci est une chaîne avec des guillemets "internes"'
String2	DB	"Une chaîne entre guillemets"
	DB	"J'apprécie le contenu de la chaîne"
String3	DB	'"Une chaîne elle-même entre guillemets"'
	DB	"'Une chaîne elle-même entre guillemets simples'"
	DB	"'Une chaîne avec ses propres guillemets simples'"
String4	DB	"""Une chaîne avec ses propres guillemets simples et doubles"""
	DB	'''Une chaîne elle-même avec ses guillemets "internes"'''

Dans String4 chaque couple de deux guillemets consécutifs constitue un guillemet qui est partie intégrante de la chaîne en tant que caractère affichable. Cette convention vaut uniquement pour les guillemets des deux extrémités de la chaîne qu'ils encadrent (contrairement à GoRC, qui agit également à l'intérieur de la chaîne).

Une virgule après une chaîne signifie qu'un autre initialiseur est attendu lequel peut déclarer, soit des données complémentaires, soit une autre chaîne ainsi qu'on peut le voir dans les exemples suivants :

String1	DB	'Ceci est une chaîne avec terminateur null', 0
	DB	'Première chaîne',0,'Et une autre chaîne', 0
String2	DB	22h, "Une chaîne avec ses propres guillemets doubles", 22h

Les valeurs ASCII que vous pouvez utiliser ici, si le vous souhaitez, sont : 22h pour les guillemets doubles et 27h pour les apostrophes.

Dans le cas d'une chaîne plus longue, il est possible de la scinder par faute de place sur la ligne et d'en reporter le contenu résiduel à la ligne suivante tout en faisant précéder ce contenu de l'opérateur DB. Par exemple :

LongString1	DB	'Son premier programme semblait très prometteur'
		DB	'jusqu'à ce qu'il ne fonctionne pour la première fois', 0
LongString2	DB	'Son erreur fondamentale:', 0Dh, 0Ah
		DB	'il ne l'a pas testé en cours de développement', 0

Les valeurs ASCII 0Dh et 0Ah sont respectivement le retour chariot et le saut de ligne. Ils sont utilisés pour commencer une nouvelle ligne lorsque l'ensemble de la chaîne est affiché sur l'écran.

En programmation Windows, vous avez parfois besoin de déclarer des chaînes Unicode dans les sections data ou const, par exemple dans un modèle de dialogue. Il y a plusieurs façons de procéder dans GoAsm qui sont décrites en détail dans le chapitre « Écriture de programmes Unicode » du volume 2. En bref, vous pouvez utiliser l'une ou l'autre des méthodes suivantes.

• Reposez-vous sur le format Unicode de base du script source (GoAsm peut lire les fichiers Unicode UTF-16 et UTF-8) ;
• Utilisez le symbole L suivi d'une apostrophe utilisé en programmation C, par exemple :

DB	L'Bonjour comment vas-tu?'

• Déclarez la séquence Unicode en utilisant DUS :

DUS	'Je suis une chaîne Unicode avec une nouvelle ligne et le terminateur null', 0Dh, 0Ah, 0

Voir aussi la section « Prépositionnement utilisant la directive STRINGS » dans le volume 2.

Pour les blocs de données volumineux risquant d'encombrer inutilement le fichier source, il existe une alternative consistant à utiliser INCBIN pour charger le contenu ou une partie du contenu du fichier contenant ces données. Sinon, vous pouvez utiliser DATABLOCK_BEGIN et DATABLOCK_END s'il s'avère plus approprié de faire figurer explicitement le bloc de données dans le fichier source lui-même.

La syntaxe d'un DATABLOCK est la suivante :

MyBlockData DATABLOCK_BEGIN      ;comment
    .
    . les données sont insérées ici
    .
DATABLOCK_END

Ici tout le matériau positionné entre DATABLOCK_BEGIN et DATABLOCK_END est inséré dans le fichier de sortie de l'assembleur, et vous pouvez ensuite adresser les données en utilisant le label MyBlockData.

GoAsm considère que ces données commencent immédiatement après la fin de la ligne contenant DATABLOCK_BEGIN et s'achèvent à la fin de la ligne précédant immédiatement celle contenant DATABLOCK_END.

Les données sont insérées à l'état brut, c'est-à-dire qu'aucune conversion n'est effectuée. Cela signifie que les caractères qui ne peuvent pas être affichés dans un éditeur ordinaire tel que les espaces ou les tabulations, par exemple, seront également chargés. Cela signifie aussi que le format des données et des caractères qui peuvent être utilisés dans les données ne sont limités que par l'éditeur que vous utilisez pour écrire votre code source.

Il est fréquent que vous ayez besoin de charger un DWord avec l'adresse d'un label, de telle sorte qu'après traitement par l'assembleur puis le linker, ledit DWord contienne un pointeur vers ce label. Le label peut être, soit un label de donnée, soit un label de code. Par exemple :

MS1	DB	'Première chaîne à utiliser', 0
MS2	DB	'Deuxième chaîne à utiliser', 0
Strings	DD	MS1, MS2 			; Strings contient l'adresse de MS1 et MS2

Alors, si vous souhaitez utiliser la chaîne MS2, il vous est possible d'écrire MOV ESI, [Strings+4] au lieu de MOV ESI, ADDR MS2.

En généralisant, tous les tableaux peuvent être créés en utilisant cette méthode et adressés au moyen du multiplicateur de registre d'index * (scale), par exemple :

MOV	ESI, [Strings + EAX * 4]

Ici, le registre EAX reçoit l'index de la chaîne à utiliser. Lorsque EAX est nul, ESI reçoit l'adresse du label de la première chaîne ; lorsque EAX = 1, ESI reçoit l'adresse du label de la première chaîne et ainsi de suite s'il y a plus de chaînes.

Voici un exemple en utilisant des labels de code :

PROCEDURE_TO_CALL	DD	FIRSTPROC, SECONDPROC
			MOV	ESI, ADDR PROCEDURE_TO_CALL	; adresse de la liste de procédures dans ESI
			MOV	ESI, [ESI+EAX*4]		; adresse du label de la procédure recherchée dans ESI
			CALL	[ESI]				; appel de la procédure

Le code est constitué des instructions contenues dans une section nommée « Code », qui a les attributs code et execute. Concrètement, vous indiquez au processeur laquelle des instructions de code doit être exécutée. Le processeur lit les instructions octet par octet et les exécute. Chaque octet de code exécutable est appelé un opcode.

Dans un exécutable ordinaire (fichier .exe), le point d'entrée caractérise l'adresse où l'exécution commence immédiatement après le chargement. Dans une DLL (fichier .dll), cela désigne l'adresse où l'exécution prend place pendant le processus de chargement.

Une fois l'exécution commencée et le point d'entrée atteint, votre programme prend le contrôle de l'exécution et va se poursuivre à partir de cette adresse. Assez souvent, bien que cela ne soit pas une obligation, la première instruction au point d'entrée consiste en un CALL, un saut conditionnel ou inconditionnel à destination de procédures écrites plus avant ou d'API.

De ce qui précède on peut voir que, sauf si votre script source est constitué uniquement de données, il est essentiel de fournir un point d'entrée à votre programme. Dans GoAsm, ceci est réalisé très simplement en attribuant un label au point d'entrée puis en indiquant au linker que ledit label est le point d'entrée du programme. On peut également utiliser le label START - suivi de deux points - mot réservé de GoAsm définissant explicitement le point d'entrée et reconnu comme tel par l'éditeur de liens.

Les exemples qui suivent proposent deux syntaxes possibles du commutateur à mettre sur la ligne de commande de GoLink si l'on décide de ne pas utiliser START et de spécifier un label de point d'entrée distinct, par exemple, entry :

-entry STARTINGADDRESS
/entry STARTINGADDRESS

Si vous utilisez ALINK seule la première méthode fonctionne.

L'intérêt du label réservé START est d'éviter de devoir donner au linker une directive spécifique désignant le point d'entrée. GoLink suppose en effet que celui-ci est constitué par label réservé START sauf avis contraire et lorsqu'il est présent. Voici comment spécifier START dans votre script source pour désigner le point d'entrée du programme :

START:

Cela peut être en majuscules, en minuscules ou en une combinaison des deux.

Nous venons de voir ce qu'il en est en ce qui concerne GoLink. Les linkers concurrents abordent cette question de différentes manières.

Si vous utilisez le MS linker, vous devez faire précéder votre label par un caractère de soulignement. Votre label du point d'entrée devient donc _START: dans votre script source. Ensuite, vous devez positionner l'une ou l'autre de ces deux instructions sur la ligne de commande de l'éditeur de liens (sans le caractère de soulignement) :

-ENTRY START
/ENTRY START

On constate ici que le MS linker est conçu pour fonctionner avec un compilateur C qui fera précéder les labels globaux d'un caractère de soulignement. Donc, l'éditeur de liens cherche l'étiquette _START, plutôt que START. Les programmeurs en assembleur ont dû s'accommoder de ces bizarreries dans les outils Windows pendant de nombreuses années, mais maintenant nous avons notre indépendance !

Voir aussi la section utilisation de GoAsm avec différents linkers.

Un label est un nom que vous attribuez à un emplacement particulier dans les données ou dans le code dans la perspective de pouvoir y accéder simplement. Il a la même fonction qu'un signet. Cela vous permet de vous référer à cet emplacement et d'y accéder en utilisant un nom. Un label de donnée se réfère aux données ; un label de code fait référence à un code exécutable. Un symbole est un label qui apparaît dans la table des symboles du fichier objet et qui peut donc être vu par le débogueur si une version de débogage de l'exécutable est constituée.

Un label unique correspond au cas général d'un label qui ne peut être utilisé qu'une seule fois dans votre script source et dans les fichiers objet liés. Il est dit de portée « globale », c'est-à-dire qu'au moment de l'édition des liens, il peut être accessible à d'autres fichiers objet. Généralement, il est d'usage de choisir un nom qui distingue la fonction de donnée de la fonction de code, par exemple « NAME_LIST » ou « CALCULATE_RESULT ». Si vous avez paramétré votre linker pour fournir une sortie de débogage, tous les labels uniques seront mis dans la liste des symboles et transmis au débogueur. Dans GoAsm vous établissez un label unique comme suit :

NAMEOFLABEL:

Cela ne produit aucun code, mais fixe un signet appelé NAMEOFLABEL au point des données ou du code où il apparaît. Si vous êtes dans une section de données, les deux points ne sont pas obligatoires. Il en va de même si un label donne le nom d'une trame de pile automatisée. Par conséquent, les lignes suivantes créent toutes des labels uniques :

;(dans la section de données)
HELLO	DB	0	; label HELLO
BYE:	DB	0	; label BYE
MEAGAIN			; label MEAGAIN
;(dans la section de code)
RICE:			; label RICE
PEAS:	FRAME		; label PEAS
BEANS	FRAME		; label BEANS

Vous pouvez voir à partir de cela que tout mot qui n'est pas réputé être une directive, un mnémonique, une déclaration ou initialisation de données, ou un mot réservé de GoAsm sera considéré comme un label. GoAsm attend deux points après un label de section de code. Ceci parce qu'il y a de nombreux mots qui doivent être utilisés dans une section de code et que, s'ils sont mal orthographiés, il est important qu'une erreur soit déclarée plutôt que le mot soit interprété à tort comme un label.

Parfois, vous avez besoin d'apposer des labels sur des parties de votre script source avec des noms que vous avez déjà utilisés auparavant. GoAsm offre deux niveaux de labels réutilisables qui peuvent être employés dans une section de code :

• labels réutilisables de portée locale commençant par un point ;
• labels réutilisables de portée non limitée composés de chiffres ou d'un caractère suivi de chiffres.

La portée d'un label définit d'où il peut être consulté en utilisant son propre nom non modifié. Regardons de plus près ces deux types labels réutilisables.

Ces types de labels, d'une syntaxe particulière et donc reconnaissables à ce titre, sont créés en utilisant un point suivi d'un label, par exemple :

.looptop	; label looptop
.fin		; label fin

La limite de la portée de ces labels spéciaux est balisée par les labels de code uniques présents dans le script source. En d'autres termes, le label peut être sauté à condition qu'il n'y ait pas de label unique sur le chemin. Ainsi,  :

JZ > .fin
CALCULATE:
.fin
RET

Ici l'instruction de saut JZ ne trouvera pas .fin parce que le label CALCULATE est un label de code unique placé sur le chemin.

Si vous voulez sauter par-dessus un label de code unique pour atteindre un label réutilisable de portée locale, vous pouvez utiliser un autre label de code unique ou un label réutilisable non délimité comme destination du saut. Il vous est également possible, quoique de manière plus marginale, d'utiliser le label de portée locale dans une trame de pile automatisée. Voir, à ce sujet, labels réutilisables à portée définie dans les trames de pile automatisées.

Les labels réutilisables de portée locale sont envoyés au débogueur comme des symboles avec leur « propriétaire ». Par conséquent le symbole envoyé au débogueur dans l'exemple ci-dessus est CALCULATE.fin, et une autre façon de sauter par-dessus le label unique serait d'écrire JZ >CALCULATE.fin.

Vous rencontrerez souvent dans votre code des sauts ou des boucles d'amplitude faible pour lesquels le choix d'un nom de label mûrement réfléchi n'apporte aucune plus-value à la compréhension du listing. Pour ceux-ci vous pouvez utiliser un label dont le nom ne sera pas transmis au débogueur en tant que symbole. Il est utile, par ailleurs, lors du débogage de limiter la table de symboles aux noms les plus importants dans votre code. Ces labels sont constitués soit uniquement de chiffres, soit d'un caractère suivi d'un ou plusieurs chiffres. Vous pouvez également utiliser une variante avec un point décimal qui facilite l'ajout de nouveaux labels locaux au code existant. Le label lui-même doit toujours se terminer par deux points. Voici des exemples de syntaxe de labels réutilisables non délimités :

L1:
24:
24.6:

Vous pouvez même utiliser deux points tous seuls pour ces destinations de saut de très faible portée dans votre code.

Afin de rendre votre script source plus lisible, GoAsm propose des indicateurs de direction pour préciser la direction du saut. L'indicateur de direction « retour » est facultative. Par exemple, en utilisant des labels réutilisables à portée locale :

JZ	>.fin		; sauter en avant à .fin
JMP	>.exit		; sauter en avant à .exit
LOOP	.looptop	; boucle arrière vers .looptop
LOOP	<.looptop	; boucle arrière vers .looptop (forme alternative)

Voici un exemple en utilisant des labels non délimités :

JZ	>L10	; saut en avant à L10
JNC	L3	; saut en arrière à L3
JNC	L3	; saut en arrière à L3 (forme alternative)
JMP	100	; saut en l'arrière à 100

Ceux-ci sont traités différemment, selon que le saut est effectué ou non en utilisant un mnémonique de saut conditionnel.

Vous pouvez coder des sauts conditionnels à des labels uniques de la même manière que vous le feriez pour des sauts à des labels de portée locale ou non délimitée. En d'autres termes, utilisez l'indicateur vers l'avant « > » si le saut est plus avant dans le script source. En option, vous pouvez utiliser l'indicateur vers l'arrière « < » pour signifier que le saut est à un lieu en amont dans le script source, ou vous pouvez l'omettre. Fondamentalement, GoAsm vous permettra de ne pas sauter d'un fichier en utilisant un saut conditionnel. Ainsi, au lieu de coder :

JZ	EXTERNALLABEL

vous pourriez écrire

JNZ	>
JMP	EXTERNALLABEL

Ceci, pour faciliter la vérification des erreurs. GoAsm suppose qu'un saut conditionnel est censé aboutir à un endroit à l'intérieur du script source existant.

Vous pouvez utiliser un indicateur de direction pour ces sauts si vous le souhaitez, mais vous n'y êtes pas contraint. L'indicateur de direction ne fera que dire à GoAsm de rechercher le label dans le script source. GoAsm ne dira pas au linker de chercher le label dans d'autres scripts source. Si vous n'utilisez pas d'indicateur de direction, GoAsm va néanmoins trouver le label s'il existe dans le script source, mais, si tel n'est pas le cas, il va dire au linker de le rechercher dans d'autres scripts source. Par exemple :

JMP	LABEL			; cherche le label dans tous les scripts source
JMP	<INTERNALLABEL1	; ne cherche le label qu'en amont dans le script source
JM	>INTERNALLABEL2	; ne cherche le label qu'en aval dans le script source

La ponctuation consistant en deux points isolés est traitée comme un label non délimité et peut être utilisée pour vos sauts les moins significatifs, par exemple :

CALL	PROCESS
LOOPZ	<

ou

CMP	EAX,EDX
JZ	>
CALL	PROCESS
:
RET

Un saut court utilise un mécanisme de déplacement relatif qui tient seulement sur deux octets. Il invite le processeur à revenir en arrière ou à aller vers l'avant avec une amplitude de +127 octets ou -128 octets par rapport à la position courante. L'amplitude du saut est contenue dans le deuxième octet de l'opcode, ce qui en explique la limitation aux valeurs précédemment indiquées.

Pour surmonter cette contrainte, il existe une variante de cette instruction contenant six octets. Il s'agit de la forme longue de l'instruction de saut relatif.

L'utilisation de sauts courts non seulement resserre votre code mais en augmente également la vitesse d'exécution parce que le processeur doit lire et exécuter moins d'octets. Cette considération pourra être déterminante dans les structures d'instructions en boucle qui sont exécutées plusieurs fois.

Utilisez soit l'opérateur LONG, soit << ou >>. Par exemple :

JZ	>>.fin		; long saut avant vers .fin
JZ	LONG >.fin	; long saut avant vers .fin (variante)
JC	<<A1		; long saut arrière vers A1
JC	LONG A1		; long saut arrière vers A1 (variante)
JC	LONG <A1	; long saut arrière vers A1 (variante)

Notez qu'il n'y a aucune forme longue de l'instruction LOOP et de ses variantes, ni de JECXZ. Si vous avez besoin d'un saut long de ces instructions utiliser à la place :

DEC	ECX
JNZ	LONG L2		; saut long remplaçant LOOP
OR	ECX, ECX		; test de ECX = 0
JZ	LONG >L44	; saut long remplaçant JECXZ

GoAsm essaie toujours de générer le plus petit code possible, en cohérence avec le fait qu'il s'agit d'un assembleur en une passe. Voici les règles observées :

• GoAsm codera toujours un saut long si c'est spécifié (pour les instructions qui admettent cette possibilité) ;
• pour les sauts en amont vers des labels uniques et portée locale, GoAsm codera automatiquement un saut court si c'est possible, sinon, à défaut, un saut long ;
• pour les sauts en amont vers des labels non délimités, GoAsm codera un saut court ;
• pour les sauts en aval vers des labels non délimités et aussi pour des labels de portée locale, GoAsm codera un saut court ;
• pour les sauts en aval vers des labels uniques, GoAsm va coder un saut long.

GoAsm affichera une erreur si un court saut est spécifié, mais ne peut être atteint. Ceci, pour vous assurer que vous n'avez pas commis d'erreur dans votre script source. Par exemple, vous pourriez avoir codé un saut court tout en oubliant d'ajouter la destination du saut à votre script source.

Les opérateurs ADDR et OFFSET permettent d'obtenir l'adresse d'un label. Dans l'exécutable final sous Windows, ils fournissent la distance du label par rapport au début de la section, ainsi que la position de la section dans la mémoire virtuelle. En d'autres termes, c'est l'adresse du label en mémoire lorsque l'exécutable est chargé et s'exécute.

Voici des exemples d'utilisation de labels uniques :

MOV	ESI, ADDR Process_dabs	; ESI = adresse de code du label Process_dabs
MOV	ESI, ADDR Hello2	; ESI = adresse de la chaîne avec le label Hello2
MOV	ESI, ADDR HelloX+10h	; ESI = adresse 16 octets au-delà du label HelloX

Exemple utilisant un label réutilisable de portée locale :

MOV	ESI, ADDR CALCULATE.fin	; ESI = adresse de code du label .fin
				; dans la procédure CALCULATE

Exemple utilisant une structure formelle :

MOV	ESI, ADDR Lv1.pszText	; ESI = adresse du membre psztext dans
				; la structure formelle Lv1

Pour le code 64 bits, notez qu'un PUSH, ARG, ou MOV vers la mémoire d'un ADDR ou d'un OFFSET concernant un label non local (les labels locaux sont gérés différemment) fera usage du registre R11 et profitera de l'adressage relatif RIP plus court de l'instruction LEA de la manière suivante :

LEA	R11, ADDR Non_Local_Label
PUSH	R11
    
LEA	R11, ADDR Non_Local_Label
MOV	[MEMORY64], R11

Ce sera également le cas avec INVOKE en passant les arguments avec ADDR, qui comprend également l'utilisation de pointeurs vers une chaîne ou une donnée brute (ex. 'Bonjour' ou <'H', 'i', 0>).

La lecture des données à partir de l'endroit pointé par un label est tout à fait différente de l'action consistant à obtenir l'adresse du même label. Ici vous lisez la valeur de données dans le domaine de la mémoire concernée. Cela doit être fait à l'aide des crochets. Exemples :

MOV	ESI, ADDR Hello1	; ESI = adresse du label Hello1
MOV	EAX, [ESI]		; EAX = valeur mémoire à l'emplacement du label Hello1

ou, ce qui revient au même :

MOV	EAX, [Hello1] 	; EAX = valeur mémoire à l'emplacement du label Hello1

Ici, vous provoquez une écriture de donnée comme suit :

MOV	ESI, ADDR Hello1	; ESI = adresse du label Hello1
MOV	[ESI], EAX		; contenu de EAX dans la mémoire dword correspondant au label Hello1

ou ce qui revient au même :

MOV	 [Hello1], EAX	; contenu de EAX dans la mémoire dword correspondant au label Hello1

Supposons que vous ayez une structure simple de données déclarée comme suit :

PARAM_DATA	DD	0	; +0h
		DD 	0	; +4h
		DD	55h	; +8h
		DD	0	; +0Ch
		DD	0	; +10h

Vous pouvez utiliser le label pour lire et écrire dans une partie particulière de la structure en utilisant une valeur de déplacement conformément à l'exemple suivant :

MOV	ESI, ADDR PARAM_DATA	; ESI = offset de PARAM_DATA
MOV	EAX, [ESI+8h]		; EAX = lecture du troisième DWORD de PARAM_DATA
MOV	[ESI+8h], EDX		; on remplace ce 3e DWORD par le contenu de EDX

ou ce qui fait la même chose :

MOV	EAX, [PARAM_DATA+8h]	; EAX = lecture du troisième DWORD de PARAM_DATA
MOV	[PARAM_DATA+8h], EDX	; on remplace ce 3e DWORD par le contenu de EDX

La valeur de déplacement peut prendre toute valeur jusqu'à 0FFFFFFFFh. Elle peut être positive ou négative. Les éléments non numériques doivent être séparés par le signe plus.

Voir la section structures - différents types et utilisation.

Supposons que vous ayez 16 DWords de données déclarés comme suit :

PARAM_DATA	DD	10h DUP 0

Vous pouvez utiliser l'indexation (scaling) en complément du registre d'index comme suit :

MOV	ESI, ADDR PARAM_DATA
MOV	EAX, [ESI+ECX*4]	; EAX = lecture du dword pointé par ESI et indexé par ECX
MOV	[ESI+ECX*4], EDX	; insertion de EDX en remplacement du dword lu précédemment

ou, ce qui revient au même :

MOV	EAX, [PARAM_DATA+ECX*4]	; EAX = lecture du dword pointé par ESI et indexé par ECX
MOV	[PARAM_DATA+ECX*4], EDX	; insertion de EDX en remplacement du dword lu précédemment

Vous pouvez utiliser une indexation de 0, 2, 4 ou 8. Les instructions qui suivent sont toutes valides :

MOVZX	EAX, B[PARAM_DATA+ECX]		; octet pointé par [PARAM_DATA+ECX] avec ext. à 0 sur EAX
MOVZX	EAX, W[PARAM_DATA+ECX*2]	; mot pointé par [PARAM_DATA+ECX*2] avec ext. à 0 sur EAX
MOV	Q[PARAM_DATA+ECX*8], EDX	; insertion EDX dans Qword pointé par [PARAM_DATA+ECX*8]

Les lettres B, W et Q précédant le crochet ouvrant sont des abréviations spécifiques à GoAsm décrivant respectivement les modificateurs de type Byte Ptr, Word Ptr et Qword Ptr.

Les éléments non numériques doivent être séparés par le signe plus.

Dans le codage 32 bits, seuls les registres 32 bits à usage général peuvent être utilisés comme registre d'index - EAX, EBX, ECX, EDI, EDX, ESI ou EBP. Vous ne pouvez pas utiliser ESP en tant que registre d'index.

En codage 64 bits, vous pouvez utiliser les registres 32 bits à usage général ou les nouveaux registres en mode d'adressage 32 bits (R8D à R15D). Vous pouvez également utiliser les extensions 64 bits des registres à usage général - RAX, RBX, RCX, RDI, RDX, RSI, ou RBP -, et les nouveaux registres 64 bits R8 à R15. Vous ne pouvez pas utiliser RSP en tant que registre d'index.

Notez que les instructions ci-dessus qui utilisent PARAM_DATA et l'indexation n'utilisent pas l'adressage relatif RIP, de sorte que la base de l'image doit être bien en dessous 7FFFFFFFh.

Supposons que vous ayez 24 DWords de données déclarés comme suit, où le dernier DWord dans chaque cas détient le résultat requis :

PARAM_DATA	DD	19h, 0, 0, 22222h
		DD	1Ah, 0, 0, 44444h
		DD	1Bh, 0, 0, 66666h
		DD	1Ch, 0, 0, 88888h
		DD	1Dh, 0, 0, 0AAAAAh
		DD	1Eh, 0, 0, 0CCCCCh

Alors, vous pouvez utiliser une indexation (scaling) et un déplacement de la manière suivante :

MOV	ESI, ADDR PARAM_DATA	; adresse de départ de la table de Dwords
CMP	EAX, [ESI+ECX*4]	; voir si EAX = dword pointé par cette table
JNZ	> L2			; non
MOV	EDX, [ESI+ECX*4+0Ch]	; oui, alors on récupère le résultat dans EDX

ou, plus directement, et ce qui revient au même :

CMP	EAX, [PARAM_DATA+ECX*4]		; voir si EAX = dword pointé par cette table
JNZ	> L2				; non
MOV	EDX, [PARAM_DATA+ECX*4+0Ch]	; oui, alors on récupère le résultat dans EDX

Vous devez utiliser l'indexation au moyen des seules valeurs 0, 2, 4 ou 8. La valeur de déplacement peut être toute valeur allant jusqu'à 0FFFFFFFFh. Dans votre script source, cette valeur peut être positive ou négative. Les éléments non numériques doivent être séparés par le signe plus.

Dans le codage 32 bits, seuls les registres 32 bits à usage général peuvent être utilisés comme registres d'index - EAX, EBX, ECX, EDI, EDX, ESI ou EBP. Vous ne pouvez pas utiliser ESP en tant que registre d'index.

En codage 64 bits, vous pouvez utiliser les registres 32 bits à usage général ou les nouveaux registres en mode d'adressage 32 bits (R8D à R15D). Vous pouvez également utiliser les extensions 64 bits des registres à usage général - RAX, RBX, RCX, RDI, RDX, RSI, ou RBP - ainsi que les nouveaux registres 64 bits R8 à R15. Vous ne pouvez pas utiliser RSP en tant que registre d'index.

Notez que les instructions ci-dessus qui utilisent PARAM_DATA et l'indexation n'utilisent pas l'adressage relatif RIP, de sorte que la base de l'image doit être bien en dessous 7FFFFFFFh.

Une procédure est une série d'instructions de code avec un label auquel l'exécution peut être transférée. Les procédures peuvent également être nommées « fonction », « routine » ou « sous-programme ». Voici un exemple de procédure courte :

PROCESS_HASH:				; label permettant d'atteindre la procédure
		XOR	EAX, EAX
		MOV	EDX, ESI
		CALL	PH23
		MOV	EDX, 866h	; retour de la procédure avec EDX = 866h
		RET

Habituellement, l'exécution est transférée à la procédure par l'utilisation de l'instruction CALL. Celle-ci impose tout d'abord au processeur de pousser sur la pile (PUSH) la position dans le code juste après l'instruction CALL, puis de poursuivre l'exécution dans la procédure appelée. À la fin de la procédure, on trouve une instruction RET (abrégé de RETURN) qui invite le processeur à retirer de la pile (POP) la position dans le code immédiatement après le CALL mémorisée précédemment, à placer cette valeur dans le pointeur d'instructions EIP, puis à reprendre l'exécution à partir de ce point.

Exceptionnellement l'exécution peut être transférée à la procédure par l'utilisation de l'instruction JMP. À la fin de la procédure, on peut également rencontrer une autre instruction JMP, comme dans l'exemple qui suit :

PROCESS_HASH:
		XOR	EAX, EAX
		MOV	EDX, ESI
		CALL	PH23		; transfère l'exécution à la procédure PH23 et retourne après celle-ci
		MOV	EDX, 866h	; retour de la procédure avec EDX = 866h
		JMP 	> SOMEWHERE_ELSE

START:					; point d'entrée de l'exécution
		JMP	PROCESS_HASH

La manière habituelle de faire un CALL ou un JMP en direction d'une procédure est d'utiliser le label de code marquant le début de la procédure. Par exemple :

CALL	PROCESS_HASH
JMP	PROCESS_HASH

Parfois, l'adresse de la procédure destination peut être conservée en mémoire, pointée par un label ou un registre ou même localisée à un endroit connu dans la mémoire ainsi que l'illustrent les différents exemples qui suivent :

CALL	 [PROCADDRESS]
CALL	 [PROCTABLE+20h]
CALL	 [ESI]
CALL	 [ESI+EDX]
JMP	 [4000000h]

Il peut arriver enfin que l'adresse de la procédure destination soit détenue par un registre, auquel cas la syntaxe du CALL ou du JMP peut prendre la forme suivante :

CALL	EAX
JMP	EDI

Nous espérons que vous n'aurez jamais à utiliser l'une des formes qui suivent, mais GoAsm les autorise néanmoins (en utilisant soit CALL, soit JMP) :

#define	Hello PROCESS_HASH
	CALL	Hello				; traité comme un CALL à PROCESS_HASH
	CALL	100h				; traité comme un CALL à une adresse relative 
	CALL	[HELLO3+ECX+EDX*4]
	CALL	[HELLO3+ECX+EDX*4+9000h]
	CALL	$$				; CALL au départ du début de la section courante
	CALL	$+20h				; CALL 20h octets plus loin que la position courante

Certains assembleurs vous obligent à signaler dans votre script source au moyen de la directive EXTRN que la destination d'un appel est quelque part en dehors du fichier objet. Ils imposent également que la même destination soit marquée comme GLOBAL ou PUBLIC. GoAsm vous dispense de ces subtilités de syntaxe en considérant que, si la destination d'un l'appel se révèle introuvable lors de l'assemblage, elle est supposée relever d'un appel externe. Aussi, tous les labels qui ne sont pas locaux ou qui ont des noms réutilisables sont supposés être « globaux ». GoAsm fonctionne de la même manière lorsqu'un appel ou un saut doit être effectué à une section de code avec un autre nom.

Donc, si vous voulez appeler une procédure dans un autre script source (lequel produira un autre fichier objet), appelez-la simplement de la manière habituelle. De même, si vous avez une procédure dans un autre exécutable (généralement une DLL), vous pouvez procéder de même.

Par exemple, supposons que vous ayez écrit My.Dll incluant un algorithme de calcul que vous souhaitez utiliser avec le label CALCULATE. On pourrait l'appeler comme suit :

CALL CALCULATE

Dans votre liste des DLL que vous donnerez à GoLink, vous mentionnerez My.Dll. GoLink cherchera d'abord le label de code CALCULATE dans les fichiers objet, mais regardera ensuite dans les DLL spécifiées. La plupart des autres linkers regardent dans les fichiers de bibliothèque (fichiers .lib) pour les fonctions qu'ils contiennent, ce qui signifie que vous avez à constituer un fichier lib. De toute façon, si l'on s'en tient à la syntaxe GoAsm, vous n'avez plus rien à faire dans votre script source. Si l'éditeur de liens ne trouve pas la destination de l'appel, une erreur sera affichée.

Cette forme de l'appel est un appel relatif utilisant l'opcode E8.

Vous pouvez également utiliser cette forme :

CALL	[CALCULATE]

Pour ce type d'appel, GoAsm utilise les opcodes FF15. Il s'agit d'un appel à une adresse absolue. Dans l'assembleur 32 bits, c'est un appel à une adresse de 32 bits, mais dans l'assembleur 64 bits, c'est un appel à une adresse de 64 bits.

Voir aussi :

• bibliothèques de code statique ;
• import direct par ordinal ou par DLL spécifique ;
• utilisation de la bibliothèque C Runtime.

Il est important évidemment d'envoyer les paramètres à l'API dans le bon ordre. INVOKE vous aide à le faire en vous permettant de mettre les paramètres après le nom de l'API comme en C. Cela est appréciable aussi lorsque vous travaillez avec la documentation de Windows qui décrit toujours les paramètres des API en utilisant la syntaxe du C. Par exemple, voici comment l'API MessageBox y est décrite :

int MessageBox(
	HWND hwnd,		// handle of owner window
	LPCTSTR lpText,		// address of text in message box
	LPCTSTR lpCaption,	// address of title of message box
	UINT uType		// style of message box
	);

Avec INVOKE, vous pouvez respecter le même ordre, par exemple :

INVOKE MessageBoxA, [hwnd], EAX, EDX, 40h

qui équivaut à :

ARG	40h, RDX, RAX, [hwnd]
INVOKE	MessageBoxA

Notez que ARG (comme PUSH) lit les paramètres d'une façon, tandis que les paramètres après INVOKE sont lus dans l'autre sens.

INVOKE et ses nombreux paramètres peuvent être écrits sur plusieurs lignes en utilisant le caractère de continuation :

INVOKE	CreateWindowExA, WS_EX_OVERLAPPEDWINDOW, ADDR szClassName, \
	ADDR szWindowName,\
	WS_OVERLAPPEDWINDOW+THING,\
	100, 16, 400, 0, 0, 0, [hInstance], 0

Puisque GoAsm considère les paramètres de INVOKE à partir de la fin, les erreurs vers la fin seront trouvées en premier.

Lors de l'utilisation de INVOKE, si vous souhaitez ranger vos paramètres dans un mot défini, alors GoAsm les récupèrera toujours dans le bon ordre. Par exemple :

z_function_params=3,2,1
INVOKE z_function, z_function_params

produit le même code que :

ARG 1,2,3
INVOKE z_function

Les API Windows qui gèrent des entrées ou sorties de caractères (généralement sous forme de chaînes de caractères) ont généralement deux versions différentes : une version ANSI et une version Unicode. La version ANSI gère les chaînes en ANSI, standard selon lequel un seul octet de valeur 0 à 255 représente un caractère unique basé sur le jeu de caractères courant. Ces caractères sont parfois appelés caractères « multioctets ». De manière on ne peut plus simple, le nom de la version ANSI de l'API se termine par un « A » comme dans l'exemple de l'API CreateWindowEx utilisée ci-dessus. La version Unicode gère les chaînes en format Unicode et utilise à cet effet deux octets par caractère sur la base de la table standard des caractères Unicode. Ceux-ci sont parfois qualifiés de caractères « larges » (wide). La version Unicode de l'API se terminera logiquement par un « W » à la fin de son nom.

Dans votre script source, vous devez spécifier les API que vous souhaitez appeler en ajoutant un « A » ou un « W » à la fin du nom de l'API, selon le cas. Lorsque vous soumettez votre fichier objet au linker et que ce dernier aura été incapable de trouver l'API dans un autre exécutable (ou dans les fichiers .lib si vous n'utilisez pas GoLink), c'est probablement parce que vous aurez oublié d'ajouter le « A » ou le « W ». Vous pourriez également avoir omis de fournir à GoLink le nom de la DLL détenant l'API (ou les fichiers .lib appropriés si vous n'utilisez pas GoLink).

Si vous voulez automatiser le bon appel d'API « A » ou « W », les règles suivantes doivent être observées :

• le programme est en version ANSI sauf spécification contraire ;
• la version Unicode peut être obtenue, soit en mettant le commutateur /d sur la ligne de commande de GoAsm, soit en écrivant la ligne #define UNICODE au début du script source.

Voir le chapitre relatif à l'écriture de programmes Unicode dans le volume 2 pour de plus amples informations sur le sujet.

Il n'y a aucune différence entre l'assemblage 32 et 64 bits à cet égard pour la simple raison que Windows 64 bits a des versions ANSI et Unicode des API tout comme Windows 32 bits.

GoAsm permet une extension de PUSH ou ARG qui est très utile en programmation sous Windows. Souvent, dans ce cas, vous êtes dans la situation d'envoyer à une API un paramètre qui est un pointeur vers une chaîne se terminant par zéro. Supposons, par exemple, l'appel d'API suivant (en 32 bits) :

MBTITLE		DB	'Hello', 0
MBMESSAGE	DB	'Click OK', 0
		PUSH	40h, ADDR MBTITLE, ADDR MBMESSAGE, [hwnd]
		CALL	MessageBoxA

Pour simplifier cette syntaxe, GoAsm permet d'utiliser PUSH ou ARG comme suit tout en garantissant un résultat identique :

PUSH	40h, 'Hello', 'Click OK', [hwnd]
CALL	MessageBoxA

ou, si vous écrivez un script source permettant la compatibilité entre les plateformes 32 et 64 bits :

ARG	40h, 'Hello', 'Click OK', [hwnd]
INVOKE	MessageBoxA

et, si vous préférez envoyer les paramètres par INVOKE :

INVOKE	MessageBoxA, [hwnd], 'Click OK', 'Hello', 40h

Vous pouvez enfin utiliser cette même facilité avec des chaînes Unicode comme suit :

ARG	40h, L'Hello', L'Click OK', [hwnd]
INVOKE	MessageBoxW

ou

INVOKE	MessageBoxW, [hwnd], L'Click OK', L'Hello', 40h

Lorsque vous utilisez l'une de ces formes, la chaîne sera toujours terminée par zéro. Il se trouve en effet que GoAsm place la chaîne dans la section const s'il y en a une (la section data s'il y en a une, sinon, à défaut, dans la section de code) et y ajoute un terminateur null. Puis, GoAsm crée l'instruction correcte et lui donne un pointeur vers la chaîne. Aucun symbole n'est produit à des fins de débogage.

En assemblage 64 bits, GoAsm garantit que les chaînes Unicode sont alignées sur la limite de mot requise par le système.

Notez que ceci est similaire à PUSH ADDR et fera usage du registre R11 tout en tirant avantage de la taille réduite de l'adressage relatif RIP de l'instruction LEA.

Vous pouvez faire la même chose que précédemment avec les données brutes ordinaires (en octets) en utilisant les opérateurs < et >. Par exemple :

PUSH	<23, 24, 25>	; mise en pile d'un pointeur des octets 23,24,25

ou

PUSH	<23, 6 DUP 20h, 23>	; mise en pile d'un pointeur des octets 23,6 espaces, puis 23

ou

PUSH	<'Hi', 0Dh, 0Ah, 'There', 0>	; mise en pile d'un pointeur sur la chaîne terminée
					; par un zéro sur 2 lignes (RC+LF au milieu)

On peut également utiliser les opérateurs < et > de cette manière avec ARG et après INVOKE. Dans ce cas de figure, GoAsm place la déclaration des données entre les opérateurs < et > dans la section const s'il y en a une (ou la section data s'il y en a une, sinon à défaut, dans la section de code). Puis GoAsm crée l'instruction appropriée et calcule un pointeur vers les données. Aucun symbole n'est constitué à des fins de débogage.

Notez que lorsque vous utilisez les opérateurs < et > de cette manière, aucun terminateur Null n'est ajouté aux chaînes.

Lors de l'assemblage 64 bits, GoAsm garantit que les données sont alignées sur une limite de mot rendue nécessaire par le système si les données contiennent des chaînes Unicode.

Penchons-nous sur l'instruction

MOV	[ESI], 20h

Elle consiste à stocker le nombre 20h à l'adresse mémoire spécifiée par le contenu du registre ESI. Mais une question importante apparaît immédiatement. Le nombre doit-il être chargé comme un octet, un mot, un DWord ou tout autre type de donnée ? De la réponse dépend le nombre d'octets de mémoire - à partir de l'adresse fournie par ESI - qui doivent être modifiés. Tous les assembleurs exigent donc à cet effet un indicateur de type pour lever l'ambiguïté mais avec une syntaxe sensiblement différente ainsi que le montrent les exemples suivants (en utilisant DWORD comme exemple) :

MOV	DWORD PTR [ESI], 20h	; MASM
MOV	DWORD [ESI], 20h	; NASM
MOV	D[ESI], 20h		; A386

GoAsm utilise la syntaxe A386 qui nécessite beaucoup moins de frappe de sorte que les indicateurs de type rencontrés sont :

• B signifie Byte (1 octet) ;
• W signifie Word (2 octets) ;
• D signifie DWord (4 octets) ;
• Q signifie QWord (8 octets) ;
• T signifie TWord (10 octets).

Vous pouvez également utiliser ces deux indicateurs de type commutable :

• S est un indicateur dont la taille varie selon les caractères utilisés : 1 (octet) en ANSI et 2 (octets) en Unicode.

MOV	S[EDI], 0	; insère un simple zéro si ANSI, un double zéro si Unicode.

Voir la section « Utilisation de l'indicateur de type commutable pour Unicode/ANSI » dans le chapitre du volume 2 consacré à l'Unicode.

• P est un indicateur dont la taille varie selon le format 32/64 bits (par défaut, 4 pour 32 bits, 8 pour 64 bits) :

MOV	P[RDI], 0	; 0 sur qword à RDI si 64 bits, 0 sur dword à EDI si 32 bits

Voir la section utilisation de l'indicateur de type commutable pour 32/64 bits.

Comme NASM, GoAsm ne vérifie pas les types, de sorte qu'il ne peut connaître la taille d'une opération telle que celle-ci :

INC [COUNT]

Ici, GoAsm ignore tout de la taille de COUNT qui peut être indifféremment un octet, un mot (Word), un double-mot (DWord) ou un quadruple mot (QWord) et ceci, bien que la variable ait été préalablement déclarée. Par conséquent, vous devez impérativement préciser le type de l'opération, par exemple :

INC	B[COUNT]

Bien que cette obligation impose un peu plus de travail au programmeur, force est de reconnaître que le script source s'en trouve plus facile à lire et à comprendre, puisque vous pouvez immédiatement voir la taille de l'opération de l'instruction, plutôt que de devoir explorer l'ensemble du programme pour vous enquérir de la taille avec laquelle COUNT a été déclarée. Du reste, l'utilisation d'indications de type tenant en une seule lettre compense le côté fastidieux induit par la répétition de ces indications.

Généralement toutes les instructions où la taille de l'opération n'est pas implicite sont concernées. Certains des exemples qui suivent utilisent des références de mémoire nominatives alors que d'autres préfèrent des références de mémoire soutenues par des registres :

AND	B[MAINFLAG], 0FEh
ADC	W[EAX], 66h
ADD	D[MEM_AREA], 66h
BT	D[EBX], 31D
CMP	D[HELLOWORD], 0Dh
DEC	D[ECX]
DIV	B[HELLO]
INC	D[EDX]
MOV	B[MEM_AREA], 23h
MOVSX	EDX, B[EDI]
MUL	B[HELLO]
NEG	W[ESI]
NOT	D[HELLO3]
OR	B[MAINFLAG], 1h
SETZ	B[BYTETEST]
SHL	W[IAMAWORD], 23h
SHL	D[IAMADWORD], CL
SUB	D[EBP+10h], 20D
TEST	B[ESP+4h], 1h
XOR	D[IMAWORD], 11111111h

Et, en programmation 64 bits, vous pouvez également voir, par exemple :

ADC	W[RAX], 66h
BT	D[R12], 31D
INC	Q[RDX]
NEG	W[R15D]

Entrent dans cette catégorie les opérations dont la taille de l'opération est évidente, du fait de l'utilisation d'un registre, par exemple :

AND	[MAINFLAG], CL
CMP	[HELLOWORD], EDI
MOV	[IAMABYTE], AL
MOV	[IAMADWORD], ESI
OR	[MAINFLAG], BH
XCHG	CL, [ESI]

De fait, aucune des instructions MMX, XMM ou 3DNow! ne nécessite un indicateur de type. Il en va de même pour plusieurs des instructions en virgule flottante x87. Les autres peuvent prendre plus d'une taille d'opérande. Il y a aussi plusieurs instructions qui n'acceptent qu'une taille d'opérande, de sorte qu'avec celles-ci, l'indicateur de type n'est pas requis. Il en va Ainsi, des instructions CALL, JMP, PUSH et POP qui ne supportent qu'un DWord (en 32 bits). Voir cependant la section relative aux demi-opérations de pile concernant l'utilisation de PUSHW et POPW. Enfin, certaines des instructions les moins courantes n'ont pas besoin d'un indicateur de type, par exemple ARPL, BOUND, BSF, BSR, CMOV (sous toutes ses formes), CMPXCHG et CMPXCHG8B.

La plupart des assembleurs utilisent la syntaxe suivante pour les nombres :

66ABCDEh	; nombre hexadécimal
34567789	; nombre décimal
1100011B	; nombre binaire
1.0		; nombre réel
1.0E0		; nombre réel (autre forme)

GoAsm accepte ces nombres, mais prend également en charge les formats suivants :

9999999D	; nombre décimal
0x456789	; nombre hexadécimal

Un nombre hexadécimal qui commence par une lettre (A à F caractérisant, par convention, les valeurs décimales de 10 à 15) doit impérativement être précédé d'un zéro, par exemple :

0A789ABCDh

ou

0xA789ABCD

GoAsm peut effectuer des opérations arithmétiques limitées à l'intérieur des déclarations de données, du quantitatif de DUP, des définitions, lors de la déclaration de définitions, lors de l'utilisation des définitions, et dans des opérandes des instructions de code. Vous n'êtes pas autorisé à utiliser le signe de multiplication (astérisque) à l'intérieur de crochets autrement que lors de l'utilisation d'un registre d'index.

Soyez prudent en utilisant les opérateurs logiques OR, AND et NOT puisque ceux-ci sont à la fois des mnémoniques processeur et des directives de l'assembleur. Bien que GoAsm sache les distinguer dans leurs deux acceptions, il vous est possible de recourir à une écriture distinctive en utilisant, pour les directives, les symboles | pour OR, & pour AND, et ! pour NOT.

Les opérations arithmétiques entre parenthèses sont effectuées en premier lieu, sinon les calculs sont effectués strictement de gauche à droite. Voici quelques exemples :

DB	2*3
DB	(2+30h)/(2+1)
DD	(2000h+40h-20h)/2
DD	SIZEOF HELLO/2
DD	444444h & 226222h
DB	20h/2 DUP 44h
DB	6+2 DUP 0
#define	globule (2*3)/2
DB	globule
DD	globule|100h
DD	2D00h>>8
DQ	2D00h<<48
MOV	EAX, globule|100h
MOV	EAX, SIZEOF HELLO*2
MOV	EAX, ADDR HELLO+10h
MOV	EAX, 0x68+0x69-0x70
MOV	EAX, [MemName+0x68+0x69-0x70]
MOV	EAX, [ESI*4+45000h]
MOV	EAX, [ESI*4+SIZEOF HELLO/2]
MOV	EAX, 8+8*2			; résultat = 32
MOV	EAX, 8+(8*2)			; résultat = 24

Le quotient des divisions, lorsque cette opération est utilisée, est arrondi selon la règle de l'entier le plus proche ainsi que le montrent les exemples suivants :

MOV	EAX, 32/3	; met 11 dans EAX
MOV	EAX, 31/3	; met 10 dans EAX
MOV	EAX, 10/4	; met 3 dans EAX

GoAsm considère que les multiplications et divisions effectuées dans ce cadre le sont en utilisant des nombres non signés. MUL et DIV sont utilisées lors de la compilation et non leurs homologues signés IMUL et IDIV.

Les nombres réels sont des nombres qui ont la capacité de représenter une valeur inférieure à 1. GoAsm attend des nombres réels présents dans le script source qu'ils prennent la forme d'un nombre à virgule flottante, techniquement composé de plusieurs chiffres et d'un point parmi ceux-ci conformément à la notation anglo-saxonne qui prévaut ici. Le point doit être représenté par le caractère correspondant au code ASCII 2Eh et peut se situer n'importe où pourvu qu'il soit unique et positionné entre deux chiffres consécutifs. Le nombre réel peut, si nécessaire, être assorti d'un exposant décimal signé à la fin du nombre (en utilisant l'indicateur d'exposant « e » ou « E » conformément à la norme IEEE relative aux nombres en virgule flottante). Les registres x87 en virgule flottante du processeur peuvent accepter des nombres réels dans les résolutions 32, 64 ou 80 bits. Le 3DNow! et les instructions SSE travaillent avec des nombres réels 32 bits et les instructions SSE2 utilisent des nombres réels 64 bits.

Parfois, ces types sont nommés :

• 32 bits simple-précision ;
• 64 bits double-précision ;
• 80 bits double-précision étendue.

Donc, les nombres réels peuvent être déclarés comme DWords (32 bits), QWords (64 bits) ou TWords (80 bits). Voici quelques exemples de déclarations de données en nombres réels :

DD	1.6789E3
DQ	1.6789E3
DT	1.6789E3
DD	3 DUP 7.6789E-2
DQ	678.27896435E3
DT	1.2

Vous pouvez également déclarer directement le nombre PI soit en tant que TWord, QWord ou DWord comme suit :

DD	PI	; pi comme un dword
DQ	PI	; pi comme un qword
DT	PI	; pi comme un tword

GoAsm tente d'obtenir une précision maximale dans la fourniture de PI en écrivant une valeur connue directement dans la mantisse.

Vous pouvez également déclarer un nombre réel comme suit :

PUSH	1.1
MOV	EAX, 1.1

Ces deux formes utilisent un format 32 bits pour le nombre réel. La première place ce nombre sur la pile et la seconde le place dans le registre spécifié.

GoAsm utilise des algorithmes spéciaux pour garantir une précision optimale lors du chargement de la déclaration de nombre réel en tant que donnée. Dans le cas de la déclaration d'un TWord (80 bits) le calcul est effectué si nécessaire sur un maximum de 92 bits, avant d'être arrondi puis inséré dans la mantisse 64 bits. La conversion en un QWord (64 bits) est effectuée en utilisant la précision maximale disponible (53 bits de mantisse) avec un arrondi à la valeur la plus proche. La conversion en un DWord (32 bits) est effectuée en utilisant la précision maximale disponible (24 bits de mantisse) avec un arrondi à la valeur la plus proche.

Au lieu d'utiliser des nombres réels pour charger les registres en virgule flottante, vous pouvez déclarer un TWord et charger la mantisse et l'exposant directement en utilisant l'instruction FLD. Pour ce faire, vous aurez besoin de connaître les valeurs de mantisse et d'exposant à charger (ceux-ci peuvent être soit calculés, soit trouvés et vérifiés en utilisant l'une des fonctions de simulation FPU de GoBug). Supposons, par exemple, que vous vouliez une représentation du nombre π aussi précise que possible et vous savez, par ailleurs, que cette représentation consiste en un exposant de +0002 et une mantisse de +C90FDAA22168C235h. Vous pouvez donc déclarer ce nombre par :

DIRECT_PI	DT	4000C90FDAA22168C235h

et le charger en utilisant :

FLD	T[DIRECT_PI]

Considérons maintenant la figure ci-après qui montre la structure d'un registre de données x87. Le bit le plus significatif - bit 79 - dans la déclaration de tword qui précède est le bit de signe indiquant que le nombre réel est positif ou négatif. Ici, le nombre est positif puisque ce bit est à zéro. Le reste des quatre premiers chiffres hexadécimaux contient l'exposant qui est donc représenté sur 15 bits. Pour mieux faire tenir les valeurs d'exposant positives et négatives sur ce format, la valeur nulle est fixée à 3FFEh, ce qui autorise dès lors les exposants à évoluer entre -3FEEh et +4001h sans risquer d'atteindre le bit le plus significatif - le bit 79 évoqué plus haut. Le reste des chiffres hexadécimaux - 0 à 62 inclus - contient la mantisse.

Il est beaucoup plus difficile de charger la mantisse et l'exposant directement à partir de données déclarées en DWord et QWord. Ceci, parce que la répartition entre mantisse et exposant dans ce format numérique s'affranchit partiellement de la modularité 4 bits, base de la notation hexadécimale. Il résulte de cette structure particulière une certaine difficulté à chiffrer les nombres hexadécimaux à déclarer, outre le fait que l'exposant, pour ne rien simplifier, subit un codage qui accentue cette opacité.

Dans votre script source, vous serez souvent amené à représenter des caractères sous différentes formes. Par exemple :

Mess	DB	'I am a string of characters',0
	PUSH	'This is supposed to be a carat ^'
	MOV	EAX, '£$|@'

Il faut se demander quelles valeurs réelles sont chargées par GoAsm à l'issue du traitement de ces instructions. Au moment de l'assemblage GoAsm consulte votre script de source en utilisant les tables de caractères Windows, puis le lit caractère par caractère. En d'autres termes, GoAsm se voit attribuer la valeur des caractères dans le script source par Windows. Lorsque GoAsm charge dans le fichier objet les chaînes de caractères décrites ci-dessus, il charge la même valeur de caractère qui lui est donnée par Windows. Dans le cas de conversion de chaînes ANSI en chaînes Unicode, ces dernières sont passés d'abord par l'API MultiByteToWideChar. Cela signifie que la valeur donnée à GoAsm par Windows correspondra au jeu de caractères courant (page de code). En conséquence, vous devez vous assurer que le jeu de caractères utilisé dans l'ordinateur qui supporte GoAsm est le jeu de caractères pour lequel votre programme est conçu pour fonctionner.

Si vous utilisez un script source qui est dans un format Unicode (UTF-8 ou UTF-16), alors la question de la page de code disparaît. Les caractères corrects sont donnés par leur valeur Unicode.

Parfois, vous aurez à spécifier des caractères par leur valeur réelle dans la table courante pour pouvoir faire face à d'éventuelles variations de jeux de caractères. C'est par exemple le cas pour le symbole représentant l'opérateur logique OR par une barre verticale, lequel peut prendre deux valeurs de code ASCII :

CMP	AL, 124D	; est-ce que ce code est un OR dans ce jeu de caractères ?
JZ	>L4  		; oui
CMP	AL, 221D	; est-ce que ce code est un OR dans cet autre jeu de caractères ?
JZ	>L4		; oui

Cette formulation vous permet d'autoriser une possible variation du propre jeu de caractères de l'utilisateur. Si nécessaire, vous pouvez organiser votre code de telle sorte qu'il teste le jeu de caractères de l'utilisateur au moment de l'exécution, et qu'il teste les caractères ou utilise les chaînes corrigées en conséquence. Vous pouvez également tester la langue de la machine de l'utilisateur et fournir des chaînes dans la langue correcte. Les API de ressources offrent une solution à cet égard et cela peut être fait automatiquement - voir le manuel du compilateur de ressources GoRC dans le volume 2.

Les structures sont des zones de données de taille fixe qui contiennent des données réparties dans divers composants (éléments de structure). Elles peuvent aller de dispositions très souples à d'autres, très formalisées, avec même des structures au sein d'autres structures (structures imbriquées). Elles peuvent être des zones de données résultant d'une déclaration de données ordinaire ou de modèles STRUCT. Les structures sont très importantes en programmation Windows et GoAsm en supporte tous les types.

Voir aussi le paragraphe suivant concernant les unions.

Considérons la structure LV_COLUMN qui est utilisée pour organiser les colonnes dans un contrôle ListView. Le code suivant envoie le message LVM_INSERTCOLUMN (valeur 101Bh) au contrôle ListView pour constituer une nouvelle colonne avec le numéro d'index correspondant dans EAX. Les détails des colonnes sont contenus dans la structure LV_COLUMN. Voici comment ils pourraient être utilisés en code 32 bits :

PUSH	ADDR LV_COLUMN, EAX, 101Bh, hListView
CALL	SendMessageA				; insère la colonne indexée par EAX

Regardons maintenant de plus près la structure LV_COLUMN. Dans le fichier d'en-tête de Windows Commctrl.h (version pre- Win_IE 300) qui contient des informations sur la structure, elle est décrite comme une structure de six DWords. En un sens, donc, la structure peut être considérée comme une succession de six DWords qui peuvent être déclarés très simplement comme suit :

LV_COLUMN	DD	6 DUP 0

Cependant, dans l'information de Windows, il apparaît que chacun des six doubles-mots a un nom qui donne une idée de ce pour quoi il est utilisé, ce qui est utile. De plus, le premier DWord s'avère être un masque qui identifie lesquels des éléments suivants de la structure sont valides. Ce masque est important car une version ultérieure de la structure révèle, par exemple, la présence de deux autres membres, ce qui impose de facto un masque différent. Donc, il pourrait être préférable de déclarer une structure de données de ce genre de telle sorte que le masque puisse être initialisé avec une valeur, et que vous puissiez voir les noms dans votre script source :

LV_COLUMN
		DD	0Fh	; +0h mask
		DD	2h	; +4h fmt=LVCFMT_CENTER=2
		DD	0	; +8h cx
		DD	0	; +0Ch pszText
		DD	0	; +10h cchTextMax
		DD	0	; +14h iSubItem

Ici, remarquons que, tandis que nous déclarions la structure de données, nous en avons profité pour initialiser deux des membres avec des valeurs qui ne changeront pas et que nous avons inclus dans les commentaires l'offset des différents membres, leurs noms ainsi que d'autres informations.

Il est très facile de lire et d'écrire sur la structure simple décrite précédemment :

MOV	EDI, ADDR LV_COLUMN
MOV	ESI, ADDR ColumnText	; récupère en ESI la colonne de texte à utiliser
MOV	[EDI+0Ch], ESI		; et la communique au membre approprié de la structure
MOV	D[EDI+8h], 50D		; et établit la largeur à 50 pixels

ou, vous pouvez utiliser :

MOV	ESI, ADDR ColumnText	; récupère en ESI la colonne de texte à utiliser
MOV	[LV_COLUMN+0Ch], ESI	; et la communique au membre approprié de la structure
MOV	D[LV_COLUMN+8h], 50D	; et établit la largeur à 50 pixels

Certains programmeurs préfèrent être plus formels dans l'utilisation des structures en utilisant notamment un modèle de structure. Cela se fait en deux étapes. La première consiste à élaborer un modèle en utilisant STRUCT et en lui donnant un nom. À ce stade, les données ne sont pas encore déclarées.

Voici un exemple de modèle de structure portant le nom LV_COLUMN :

LV_COLUMN	STRUCT
 mask		DD	0Fh	; mask
 fmt		DD	2h	; LVCFMT_CENTER=2
 cx		DD	0
 pszText		DD	0
 cchTextMax	DD	0
 iSubItem	DD	0
		ENDS

Deux commentaires ont été ajoutés ici pour faciliter la compréhension de l'initialisation de deux membres de la structure. Noter que ENDS (littéralement END STRUCT) marque la fin du modèle. Vous pouvez également marquer cette fin en lui donnant le nom de la structure suivi de ENDS comme ci-dessous :

LV_COLUMN	ENDS

La seconde étape consiste ensuite à utiliser le modèle. Vous y parvenez en le nommant et en faisant précéder ce nom d'un label, par exemple :

Lv1	LV_COLUMN

À ce stade, vous venez de déclarer six doubles-mots en utilisant le modèle de la structure LV_COLUMN et vous avez donné, à la déclaration de la structure, le label Lv1.

Dans GoAsm, des symboles sont créés pour le label de la structure elle-même et également pour chaque membre nommé de la structure. Ceux-ci peuvent ensuite être référencés directement et transmis aussi comme tels au débogueur.

Ainsi :

RECT	STRUCT
 left	DD
 top	DD
 right	DD
 bottom	DD
	ENDS
rc	RECT

crée les symboles :

• rc
• rc.left
• rc.top
• rc.right
• rc.bottom

L'utilisation de la structure formelle vous permet d'être plus explicite dans votre script source lors de la lecture et l'écriture dans la structure. Par exemple :

MOV	ESI, ADDR ColumnText	; récupère en ESI la colonne de texte à utiliser,
MOV	[Lv1.pszText], ESI	; ... la communique au membre approprié de la structure
MOV	D[Lv1.cx], 50D		; ... et établit la largeur à 50 pixels

ou même

MOV	ESI, ADDR ColumnText	; récupère en ESI la colonne de texte à utiliser
MOV	EDX, ADDR Lv1.pszText	; récupère en EDX l'adresse du membre psztext
MOV	[EDX], ESI		; et charge le texte à utiliser
MOV	EDX, ADDR Lv1.cx	; récupère en EDX l'adresse du membre cx
MOV	D[EDX], 50D		; et établit la largeur à 50 pixels

Mais, rien ne vous empêche de recourir à une écriture plus classique qui produit, pour autant, le même résultat :

MOV	ESI, ADDR ColumnText	; récupère en ESI la colonne de texte à utiliser,
MOV	[Lv1+0Ch], ESI		; ... la communique au membre approprié de la structure
MOV	D[Lv1+8h], 50D		; ... et établit la largeur à 50 pixels

Bien qu'elle se révèle plus complexe à mettre en œuvre, la première méthode vous permet de suivre votre code dans le débogueur symbolique. Les symboles de la structure y apparaîtront en entier, c'est-à-dire en associant label de structure et nom du membre, ce qui procure un gain de lisibilité évident. En effet, GoAsm crée des symboles pour tous les membres de la structure et transmet ceux-ci au linker. Il me semble que cette possibilité est spécifique à GoAsm et qu'elle est absente des autres assembleurs.

Il peut arriver que vous ayez à connaître l'offset d'un membre au sein d'une structure. Il vous suffit pour cela de vous référer au nom de la structure auquel vous ajoutez un point puis le nom du membre concerné. Par exemple, si :

POINT	STRUCT
 left	DD	0
 right	DD	0
	ENDS

alors, l'instruction MOV EBX, POINT.right charge la valeur 4 dans EBX, qui est la distance de l'élément par rapport au début de la structure.

Cette façon de récupérer un offset est parfois utile pour obtenir des informations envoyées par Windows dans une structure. À titre d'exemple, la procédure de callback OFNHookProc reçoit de Windows de l'information dans un message de WM_NOTIFY. Le paramètre lParam contient un pointeur vers une structure OFNOTIFY. Il s'agit d'une structure imbriquée de la forme suivante :

OFNOTIFY	STRUCT
 hdr		NMHDR
 lpOFN		DD
 pszFile		DD
		ENDS

dans laquelle la structure NMHDR est :

NMHDR		STRUCT
 hwndFrom	DD
 idFrom		DD
 code		DD
		ENDS

Donc, au sein de votre procédure de fenêtre, vous pouvez obtenir la valeur du membre idFrom dans le NMHDR (identifiant du contrôle d'envoi du message) comme suit :

MOV	ESI, [EBP+14h]			; récupère en ESI le pointeur de la structure OFNOTIFY
MOV	EAX, [ESI+OFNOTIFY.hdr.idFrom]
MOV	EDX, [ESI+OFNOTIFY.pszFile]

En fait, il advient ici que OFNOTIFY.hdr.idFrom contient la valeur 4 ; NOTIFY.pszFile contient la valeur 10h. Ce sont leurs offsets corrects par rapport au début de la structure OFNOTIFY. Bien sûr, les structures concernées doivent être connues de GoAsm. Cela se fait en incluant les modèles de structure dans le script source assembleur, quelque part en amont dans le fichier.

Supposons que vous ayez une structure appelée RECT comme suit :

RECT	STRUCT
 left	DD	10
 top	DD	10
 right	DD	120
 bottom	DD	90
	ENDS

Vous pouvez remplacer l'initialisation de la structure en utilisant les opérateurs < et >, { et }. Par exemple :

rc1	RECT	<0, 20, 120, 300>

réinitialise les doubles-mots dans la structure de données à 0, 20, 120 et 300 respectivement.

Vous pouvez utiliser le point d'interrogation et la virgule, ou tout simplement la virgule pour ignorer certains membres, par exemple :

rc1	RECT	<0, ?, ?, 300>
rc1	RECT	<0, , , 300>

Ici vous remplacez seulement les premier et quatrième membres de la structure.

En utilisant des accolades, vous pouvez nommer explicitement les membres que vous souhaitez réinitialiser :

rc1	RECT	{left=2, top=5}

Vous pouvez même mélanger les deux méthodes :

rc1	RECT	<{left=2, top=5}, 300h>

Lors de l'utilisation des accolades, il n'est pas nécessaire de spécifier les noms complets de symbole (dans l'exemple ci-dessus, ces noms complets seraient « rc1.left » et « rc1.top »). Au lieu de cela vous pouvez vous limiter au seul nom du membre (« left » et « top » dans notre cas). La réinitialisation est également effectuée dans les structures imbriquées. Aussi, si vous utilisez les mêmes noms pour les membres au sein d'une structure imbriquée, il est possible d'initialiser plusieurs membres à la fois en utilisant une accolade de réinitialisation.

Si les membres d'une structure sont établis en utilisant l'opérateur DUP, vous pouvez procéder simplement à leur initialisation en utilisant une chaîne ou en spécifiant chaque élément au sein des délimiteurs < et > :

UP	STRUCT
	DB	27 DUP 0
	DB	2 DUP 0
	ENDS
Pent	UP <'My cat was born on 23 April',<23h,4h>>

L'exemple qui suit décrit la structure GUID et une initialisation typique pour une COM :

GUID	STRUCT
 Data1	dd	?
 Data2	dw	?
 Data3	dw	?
 Data4	db	8 dup ?
GUID	ENDS
IID_IShellLink GUID <0000214eeh, 00000h, 00000h, <0c0h, 00h, 00h, 00h, 00h, 00h, 00h, 46h>>

Une règle importante veut que, dans la mesure où GoAsm est un assembleur à une seule passe, les modèles de structure soient impérativement écrits dans le script source avant qu'ils ne soient utilisés. En effet, l'assembleur ne peut pas connaître à l'avance la taille de la structure. GoAsm est plutôt plus tolérant avec la syntaxe de STRUCT que d'autres assembleurs. Par exemple, STRUC a la même signification que STRUCT. De même, il n'y a pas besoin de fournir des valeurs initiales du tout, et il n'y a pas d'importance à ce que les membres ne soient pas nommés, ainsi qu'en attestent les exemples suivants qui sont parfaitement valides en dépit des apparences :

RECT	STRUCT
 left	DD
 top	DD
 right	DD
 bottom	DD
	ENDS

et

RECT	STRUCT
 left	DD	0
	DD	2 DUP 0
 bottom	DD	0
	ENDS

mais aussi

RECT	STRUCT	DD	4 DUP 0	ENDS

sont des déclarations de structure tout aussi valides les unes que les autres. Toutefois, lorsque les membres sont nommés, ils doivent l'être sur une nouvelle ligne.

Vous pouvez réutiliser le nom de membres de la structure, pourvu que le nom de la structure soit différent, par exemple :

RECT	STRUCT
 left	DD	0
 top	DD	0
 right	DD	0
 bottom	DD	0
	ENDS
RECT2	STRUCT
 left	DD	0
 top	DD	0
 right	DD	0
 bottom	DD	0
	ENDS

Si vous utilisez ? dans l'initialisation des membres de la structure, vous obtenez le même effet qu'avec la valeur zéro. Cela ne se traduit pas, en tout cas, par des données enregistrées comme non initialisées, comme ce serait le cas avec une déclaration de données ordinaire. De la sorte,

RECT	STRUCT
 left	DD	?
 top	DD	?
 right	DD	?
 bottom	DD	?
	ENDS
rc1	RECT

est parfaitement valable, mais les données vont dans la section de données avec initialisation automatique à zéro, comme si des zéros avaient été utilisés.

Dans un modèle de structure, vous pouvez mettre des données supplémentaires sur une même ligne de la manière habituelle. Voici un modèle de structure de quatre DWords utilisant cette facilité :

RECT		STRUCT
 lefttop		DD	0, 0
 rightbottom	DD	0,0
		ENDS

Ce procédé peut être utile pour créer des tableaux et des tables utilisant des modèles de structure. Par exemple :

RECT	<>, <>, <>, <>

crée quatre structures RECT (quatre DWords dans chaque). Dans la mesure où aucun label n'a été utilisé devant RECT, aucun symbole ne sera créé et transmis au débogueur. Dans cet exemple :

Buffer	RECT	<0,0,10,10>, <5,5,20,20>, <8,8,30,30>

un tableau est constitué de trois structures RECT (quatre mots chacune) initialisées selon les valeurs indiquées. Des symboles ne seront élaborés que pour la toute première structure. Ceci afin d'éviter la duplication des noms de symboles.

Si vous voulez que les membres de la matrice aient des noms de symboles uniques, il vous est possible de procéder, par exemple, comme suit :

Buffer1	RECT	<0, 0, 10, 10>
Buffer2	RECT	<5, 5, 20, 20>
Buffer3	RECT	<8, 8, 30, 30>

ou

Buffer	RECT3	<0, 0, 10, 10,  5, 5, 20, 20,  8, 8, 30, 30>

où RECT3 est une structure de trois RECT.

Si vous n'avez pas besoin d'initialiser les structures, vous pouvez les répéter en utilisant, soit :

Buffer	RECT	<>, <>, <>

ce qui crée trois structures RECT, soit :

Buffer	RECT, RECT, RECT

qui fait la même chose.

Vous pouvez également utiliser des DUP pour répéter des structures, par exemple :

ThreeRects	RECT	3 DUP <>
FiveRects	RECT	5 DUP <23, 24, 25, 26>>

Dans le deuxième exemple, chaque RECT est initialisé à la même valeur. L'initialisation de structures dupliquées, de cette manière, ne peut seulement être faite qu'au plus haut niveau et non dans des structures imbriquées.

Les structures peuvent être imbriqués en utilisant une structure à l'intérieur d'une autre, de sorte que :

RECT		STRUCT
 left 		DD	0
 top		DD	0
 right		DD	0
 bottom		DD	0
		ENDS
StructTest	STRUCT
 a		DD	6
 b		RECT
 c		DD	7
 d		DD	8
		ENDS

Dans ce cas, Hello StructTest crée sept DWords. Les symboles créés (et passés au débogueur) sont :

• Hello
• Hello.a
• Hello.b
• Hello.b.left
• Hello.b.top
• Hello.b.right
• Hello.b.bottom
• Hello.c
• Hello.d

et peuvent être lus ou écrits de la manière habituelle, par exemple :

MOV	D[Hello.b.left], 100h	; construction d'un rectangle commençant à 256 pixels

De même que les membres d'une structure, les structures imbriquées n'ont pas nécessairement besoin d'être nommées, de sorte que ce qui suit est parfaitement valable :

StructTest	STRUCT
		DD	6
		RECT
 c		DD	7
 d		DD	8
		ENDS

V-A-12-a. Structures imbriquées internes▲

StructTest	STRUCT
 a		DD	6
 b		STRUCT
		 left	DD 0
		 top	DD 0
		 right	DD 0
		 bottom	DD 0
		ENDS
 c		DD	7
 d		DD	8
		ENDS

Hello	StructTest

Vous devez utiliser avec prudence les délimiteurs < et > pour initialiser les membres corrects de la structure imbriquée. Chaque délimiteur < permettra d'aller plus loin dans l'imbrication tandis que chaque délimiteur > permettra d'en sortir un peu plus. Au sortir d'une imbrication, une virgule est attendue après le délimiteur >. Donc, dans la structure imbriquée StructTest évoquée précédemment :

rc1	StructTest	<23, <10,20,120,300>, 44, 55>

va non seulement initialiser la structure principale mais également son membre b imbriqué. En revanche :

rc1	StructTest	<, <10,20,120,?>, 44, 55>

outrepassera seulement l'initialisation de certains membres, de même que la formulation suivante qui est rigoureusement équivalente :

rc1	StructTest	<, <10,20,120,>, 44, 55>

Enfin, l'écriture qui suit n'apportera aucune modification au membre b imbriqué :

rc1	StructTest	<, , 44, 55>

Une bonne façon de suivre la cohérence des délimiteurs est de visualiser mentalement les membres que vous ne voulez pas modifier par un point d'interrogation. Vous pouvez même les insérer dans l'expression pour en faciliter la lecture. Par exemple le dernier exemple peut être écrit :

rc1	StructTest	<?, ?,4 4, 55>

Plus grand est le niveau d'outrepassement, plus grande sera sa priorité. Supposons, par exemple, que vous ayez ces modèles de structure :

RECT		STRUCT
 left		DD	1
 top		DD	2
 right		DD	3
 bottom		DD	4
		ENDS
StructTest	STRUCT
 a		DD	6
 b		RECT	<3333h, 4444h, 5555h,>
 c		DD	7
 d		DD	8
		ENDS

Puis

Hello	StructTest	<, <,0Bh,0Ch,>, , >

Alors, RECT sera initialisé à 3333h, 0Bh, 0Ch, 4.

Outrepasser le nom des membres en utilisant les accolades {} bénéficie d'une priorité plus élevée que de le faire en utilisant les délimiteurs < et >.

Vous pouvez utiliser des chaînes dans les structures de la même manière que vous le feriez dans une déclaration de données ordinaire, par exemple :

StringStruct	STRUCT
		DB	'I am a lonely string in a struct', 0
		DB	'I will keep you company', 0
		ENDS

Si une structure est déclarée avec ?, alors elle peut être de n'importe quelle taille lorsqu'elle est utilisée avec des chaînes. Par exemple :

Rect	STRUCT
 a	DB	?
	DB	0
 b	DB	?
	DB	0
	ENDS
RC1	Rect	<'Hello', , 'Goodbye'>

fixera la structure Rect en des chaînes terminées par un zéro, de cinq et sept octets respectivement.

Lorsque la taille du membre d'une structure est déjà définie, par exemple :

Rect	STRUCT
 a	DB	'Hello'
	DB	0
 b	DB	'Goodbye'
	DB 0
	ENDS

alors, l'outrepassement de l'initialisation ne changera pas la taille des membres, de sorte que par exemple :

RC1 Rect <'Goodbye',,'Hello'>

se traduira par la chaîne tronquée 'Goodb' au label Rect.a et par la chaîne 'Hello' au label Rect.b, le reste de cette dernière étant comblée avec deux zéros.

L'initialisation des membres des structures établie à l'aide DUP peut également être surpassée par des chaînes. Par exemple :

UP	STRUCT
	DB	20 DUP 0
	ENDS
Pent	UP	<"Hello">

se traduit par la chaîne 'Hello' suivie par 15 zéros.

Voir aussi la section « Utilisation des chaînes Unicode dans les structures » du volume 2, dans le chapitre consacré à l'Unicode.

Vous pouvez utiliser l'assemblage conditionnel directement dans une structure, par exemple :

NMHDR		STRUCT
 hwndFrom	DD
 idFrom		DD
 code		DD
		ENDS

NMTTDISPINFO	STRUCT
 hdr		NMHDR
 lpszText	DD
 #if STRINGS UNICODE
  szText	DW		80 DUP ?
 #else
  szText	DB		80 DUP ?
 #endif
 hinst		DD
 uFlags		DD
 lParam		DD
		ENDS
            
DATA
Use1		NMTTDISPINFO
Use2		NMTTDISPINFO	<<>, , "Hello", , , , >

La deuxième utilisation de la structure va assembler la chaîne 'Hello', soit en Unicode, soit en ANSI selon le paramétrage, en conséquence, de la directive STRINGS.

Voir la section relative à l'assemblage conditionnel.

Les unions, comme les structures, sont des zones de données de taille fixe qui contiennent des données dans divers composants (les membres d'union). Comme pour les structures, aucune zone de données n'est effectivement créée lorsque vous déclarez un modèle d'union. Cette déclaration se fait lorsque vous utilisez le modèle. Les unions diffèrent des structures en ce que chaque membre de l'union commence à la même adresse dans la mémoire. Les unions se révèlent utiles par exemple si vous souhaitez utiliser des labels différents pour traiter la même zone de données. Le label que vous adressez au moment de l'exécution pourrait alors compter sur des éventualités telles que la version du système d'exploitation sur lequel le programme est en cours d'exécution. La taille d'une union est toujours réglée sur celle de la plus grande déclaration de données en son sein. Vous pouvez mélanger les unions avec des structures pour former des modèles complexes. Vous pouvez déclarer des unions dans les données locales et les répéter de la même manière que vous le pouvez pour les structures.

Considérons, par exemple, le modèle d'union déclaré comme suit :

Thing	UNION
 Cat	DD	0
 Dog	DW	0
 Rat	DB	0
	ENDS

Vous pouvez utiliser ce modèle en écrivant :

Hungry	Thing

Ceci définit alors à part une zone de données de quatre octets (DWord). Mais, pourquoi seulement quatre octets ? Tout simplement parce que chaque membre commence à la même place et que l'on prend seulement en considération la taille du plus grand d'entre eux. La fin du modèle de l'union est marquée, au choix, par ENDS ou ENDUNION si vous préférez.

Les symboles créés par cette union sont :

• Hungry
• Hungry.Cat
• Hungry.Dog
• Hungry.Rat

Et vous pouvez adresser ces labels de la manière habituelle, par exemple :

MOV	[Hungry.Cat], EAX
MOV	AL, [Hungry.Dog]
MOV	ESI,[Hungry.Rat]

Ce qui, bien sûr, puisque chaque membre commence à la même place, est identique à :

MOV	[Hungry.Cat], EAX
MOV	AL, [Hungry.Cat]
MOV	ESI, [Hungry.Cat]]

Vous pouvez imbriquer des unions dans des structures, des structures dans des unions ou des unions dans des unions. Par exemple

Laugh		STRUCT
 Balm		DW	0
 Ointment	DB	0
		ENDS
;
Zebra		UNION
 Tiger		DD 0
 Hyaena 	Laugh
		ENDS
;
Lion		STRUCT
 BagPuss	DB	3 DUP 0
 Striped	Zebra
		ENDS
;
Fierce		Lion

qui produit les symboles et offsets correspondants suivants dans Fierce :

Les unions peuvent être imbriquées en les déclarant dans une structure ou une union, tel que le montre l'exemple suivant :

Lion		STRUCT
 BagPuss	DB	3 DUP 0
 Striped	 UNION
  Tiger		DD	0
  Hyaena	  STRUCT
   Balm		  DW	0
   Ointment	  DB	0
  		  ENDS
 		 ENDS
		ENDS
;
Fierce		Lion

produit le même résultat que l'exemple précédent. La seule différence est que Laugh et Zebra ne sont pas disponibles pour être utilisés ailleurs.

De la même manière que dans les structures, vous pouvez utiliser les opérateurs < et > pour initialiser les unions avec des chaînes ou des valeurs numériques, par exemple :

Cat		UNION
 Ginger		DB
 Tortie		DW
 Grey		DD
 Tabby		DQ
		ENDS
Hungry		Cat	<"a string for Ginger">
Anxious		Cat	<, 4444h>			; initialise le mot
Sleepy		Cat	<, , 55555555h>			; initialise le double-mot
Insistent	Cat	<, , , 6666666666666666h> 	; initialise le quadruple-mot

Il est encore plus difficile, lorsque vous utilisez les unions, de suivre les opérateurs < et >. En lieu et place et à votre convenance, vous pouvez spécifier le nom du membre inclus entre les opérateurs { et }, ou vous pouvez les initialiser lors du lancement de l'exécution, par exemple :

Scaredy	Cat	{Ginger="a string for Ginger"}
GString	DB	"a string for the Grey cat"
	MOV	[Scaredy.Grey], ADDR GString	; charge un pointeur vers GString

Rappelez-vous que, dans la mesure où les membres d'unions sont au même endroit, une initialisation ultérieure peut en écraser une précédente.

Le point d'interrogation en option (?) est utile pour montrer que vous ne voulez pas effacer un remplacement précédent.

Exemple :

Laugh		STRUCT
 Balm		DW	6666h
 Ointment	DB
		ENDS
;
Zebra		UNION
 Tiger		DD	88888888h
 Hyaena		Laugh
		ENDS
;
Lion		STRUCT
 BagPuss	DB
		DB
		DB
 Striped	Zebra
		ENDS
;
Fierce		Lion <{Ointment=0AAh} 22h, 33h, 44h, <?,<?,55h>>>

qui initialise la zone de données de la manière suivante :

At Fierce.BagPuss (at offset +0) 22h,33h,44h
Then at Fierce.Striped.Tiger (at offset +3) 66h,66h,0AAh,88h

Il apparaît ici que le DWord Tiger à +3 dans l'union Zebra a été initialisé à 88888888h mais qu'il a ensuite été remplacé par les valeurs de Balm et Ointment (qui étaient dans la même union). Seul le dernier octet a survécu.

Equates, macros et #defines donnent un sens à un mot. En d'autres termes, le mot est défini. Une fois défini, et à partir de ce point dans le script source, la définition est utilisée en lieu et place du mot d'origine si le contexte le permet. Si le mot tel que défini désigne :

• un nombre, alors les programmeurs en assembleur appellent la définition une « equate » parce que, traditionnellement, le mot est défini en utilisant les opérateurs EQU ou = ;
• une chaîne, alors traditionnellement, on parle d'une « equate » texte ;
• quelque chose de plus élaboré qu'un nombre ou une chaîne - une série d'instructions, par exemple - alors les programmeurs appellent cela une « macro ». Ceci parce que, selon un usage répandu, le mot est défini en utilisant l'opérateur MACRO.

Lors de l'utilisation GoAsm, pour les définitions qui peuvent être construites sur une seule ligne, vous aimeriez utiliser EQU, =, ou #define comme vous le feriez en langage C. Il suffit d'utiliser celui des trois que vous aimez le mieux. Vous pouvez utiliser le caractère de continuation (« \ ») pour permettre aux définitions de s'étendre sur plus d'une ligne, mais il est préférable d'utiliser MACRO … ENDM à la place, de manière à éviter d'éventuels problèmes de syntaxe.

Dans la mesure où GoAsm est un assembleur qui ne travaille qu'en une seule passe, vous devez vous assurer que vos définitions ne sont pas utilisées avant qu'elles ne soient déclarées dans le script source. Une fois qu'un mot a été défini, vous pouvez modifier sa définition mais GoAsm vous en avertira car une telle intervention peut ne pas être intentionnelle.

Voici quelques exemples de mise en œuvre de définitions.

Voici trois exemples définissant un mot comme une valeur constante. Le premier utilise =, le second utilise EQU et le troisième, #define. Ils ont tous les trois le même effet.

WS_CHILD=40000000h
WS_CHILD EQU 40000000h
#define WS_CHILD 40000000h

Outre une constante numérique, vous pouvez utiliser une expression arithmétique, des chaînes ou même d'autres définitions lorsque vous définissez un mot. En voici quelques exemples :

SKIP_VALUE EQU 20h|40h
#define SKIP_VALUE 20h|40h
HelloText='Hello world'
#define HelloText "Hello world"
MANIA=SKIP_VALUE+WS_CHILD

Si vous ne donnez pas de valeur à l'equate, celle-ci prend la valeur 1 par défaut, qui correspond à TRUE dans la philosophie Windows. Par exemple :

NT_VERSION=
NT_VERSION EQU
#define NT_VERSION

Une fois un mot défini, vous pouvez l'utiliser dans presque toute situation où la définition est valide, par exemple :

DB	HelloText
PUSH	WS_CHILD|WS_VISIBLE|SS_OWNERDRAW
MOV	EAX, WS_CHILD
MOV	EAX, [ESI+SKIP_VALUE]
MOV	EAX, MANIA+800h

Voici un exemple de la façon dont vous pouvez attribuer à un mot tout ou partie de la fonctionnalité d'une instruction de code :

#define lParam [EBP+14h]

Vous pouvez utiliser alors la définition ainsi créée de la manière suivante :

MOV	lParam, EAX	; identique à MOV [EBP+14h], EAX

Ici, on peut dire, d'une certaine manière, que le texte « [EBP+14h] » a tout simplement été remplacé par lparam dans le script source.

Les arguments sont des valeurs qui sont données lorsque les définitions sont utilisées. Ces valeurs sont ensuite utilisées dans la définition ou la macro elles-mêmes. Ainsi :

RECTB(%a,%b,%c,%d) = DD %a,%b,%c,%d

Ensuite, vous pouvez déclarer quatre DWords initialisés comme spécifié dans les arguments :

rc1	RECTB (10, 10, 100, 200) 	; identique à DD 10,10,100,200

Voici maintenant un autre exemple utilisant #define :

#define DBDATA(%a,%b) DB %a DUP %b
DBDATA(3,'x') ; identique à DB 3 DUP 'x'

Il existe une règle de syntaxe importante lorsque vous utilisez des arguments dans les définitions : il ne doit pas y avoir d'espace entre le nom de la définition et l'ouverture de parenthèse qui précède l'énoncé des arguments.

Ainsi :

RECTB(%a,%b,%c,%d)

est correct, mais

RECTB (%a,%b,%c,%d)

est erroné. Cette contrainte syntaxique, déroutante à certains égards, garantit que GoAsm reconnaît les paramètres entre parenthèses en tant qu'arguments et seulement en tant que tels.

Vous devez également vous assurer que les noms des arguments sont inhabituels et ne risquent donc pas de se retrouver dans tout autre matériau utilisé dans la définition ou la macro. Cela évite que d'autres choses soient remplacées par inadvertance. D'où le signe de pourcentage utilisé dans les exemples ci-dessus.

La définition peut occuper plusieurs lignes pour en accroître la lisibilité et, notamment, pour vous permettre d'ajouter des commentaires. Par exemple :

#define	WS_POPUP	0x80000000L
#define	WS_BORDER	0x00800000L
#define	WS_SYSMENU	0x00080000L
#define	WS_POPUPWINDOW	(WS_POPUP          | \
			 WS_BORDER         | \
			 WS_SYSMENU)

Ce dernier exemple a été pris directement sur le fichier d'en-tête de Windows Winuser.h et vous pouvez voir qu'il épouse la syntaxe typique du C. GoAsm ne peut que s'en réjouir et tolère, de surcroît, l'absence éventuelle des parenthèses :

#define	WS_POPUPWINDOW WS_POPUP          | \
	WS_BORDER         | \
	WS_SYSMENU

Vous pouvez préférer utiliser MACRO … ENDM à la place du caractère de continuation, auquel cas l'exemple ci-dessus peut être récrit sous la forme :

WS_POPUPWINDOW	MACRO	WS_POPUP    |
			WS_BORDER   |
			WS_SYSMENU
		ENDM

Ceci s'applique uniquement à la programmation 32 bits.

Vous pouvez utiliser la méthode de définition multiligne pour constituer un mot signifiant plusieurs lignes d'instructions de code. Par exemple :

OPEN_STACKFRAME(a)	=	PUSH	EBP \
				MOV	EBP, ESP \
				SUB	ESP, a*4 \
				PUSH	EBX, EDI, ESI
CLOSE_STACKFRAME 	=	POP	ESI, EDI, EBX \
				MOV	ESP, EBP \
				POP	EBP

En utilisant MACRO … ENDM, cela donne :

OPEN_STACKFRAME(a)	MACRO	PUSH	EBP
				MOV	EBP, ESP
				SUB	ESP, a*4
				PUSH	EBX, EDI, ESI
			ENDM
CLOSE_STACKFRAME	MACRO	POP	ESI, EDI, EBX
				MOV	ESP, EBP
				POP	EBP
			ENDM

Dans cet exemple, le mot OPEN_STACKFRAME est défini pour élaborer une trame de pile qui pourrait typiquement être utilisée dans une procédure de fenêtres appelée par le système Windows. Il possède un argument qui détient le nombre de mots dans la trame de pile permettant d'accepter des données locales (le pointeur de pile est déplacé par ce paramètre de sorte que la pile puisse être utilisée pour stocker les données locales). Le mot CLOSE_STACKFRAME ferme, quant à lui, la trame de pile. Voici maintenant comment utiliser ces définitions. Dans la section de code :

WndProc:				; nom de cette procédure
		OPEN_STACKFRAME (6)	; création d'un espace pour 6 dwords de données locales
		 ;----------------- insertion du code de la procédure de fenêtre ici
		CLOSE_STACKFRAME
		RET	10h		; retrait de la pile des 4 paramètres envoyés par Windows

Ajoutons maintenant un peu de raffinement de sorte que la pile puisse être accessible de manière plus compréhensible :

lParam	=	[EBP+14h]	;
wParam	=	[EBP+10h]	; on se tient prêt à accéder aux paramètres qui
uMsg	=	[EBP+0Ch]	; sont envoyés par Windows à la procédure de fenêtre
hwnd	=	[EBP+8h]	;
;
hDC    =	[EBP-4h]	; certains noms d'éléments de données
hBrush =	[EBP-8h]	; sont souvent utilisées dans des
hPen   =	[EBP-0Ch]	; procédures de fenêtre différentes
DATA1  =	[EBP-10h]	;
DATA2  =	[EBP-14h]	; espace pour plus de données locales
DATA3  =	[EBP-18h]	;

À l'intérieur de la trame de pile constituée ici, les paramètres envoyés par Windows (hwnd, uMsg, wParam et lParam) seront toujours sur la pile de EBP+14h à EBP+8h. À EBP+4h, nous trouvons l'adresse de retour du CALL. En EBP nous avons la valeur précédente de EBP que nous avons poussée au moment de la constitution de la trame de pile. Puis, de EBP-4h à EBP-18h, nous avons l'espace dévolu à nos données locales qui, dans cet exemple, peuvent être accessibles en utilisant les définitions hDC, hBrush, hPen, DATA1, DATA2 et DATA3 (ou tout nom que vous voudrez bien leur attribuer). À EBP-1Ch nous avons la valeur de EBX quand ce registre a été poussé en pile lorsque la trame de cette dernière a été élaborée. De même EDI est en EBP-20h et ESI en EBP-24h. Toutes ces valeurs sont protégées tandis que la trame de pile reste ouverte (elles ne seront pas écrasées par d'autres fonctions avant la fin du callback). Pour accéder aux données dans la trame de pile, vous devez vous assurer que vous ne modifiez EBP en aucune manière (ou si vous le faites, vous le restaurez à sa valeur initiale). Vous ne devez pas accéder aux données par leur nom. Dans cet exemple, MOV EAX, [hBrush] est la même chose que MOV EAX, [EBP-8h]. Ceci est une question de style et de choix personnel. En utilisant ces méthodes, vous pouvez établir autant de données locales que vous le souhaitez, et si vous vous en tenez à une méthode fixe comme celle-ci, vous saurez toujours où sont vos données locales. Dans cet exemple, le premier DWord des données locales est toujours à EBP-4h. Soustraire 4 de cette valeur pour accéder à chaque DWord supplémentaire de données locales.

Il y a beaucoup d'autres façons de travailler avec la pile dans les callbacks. Voir, à ce sujet, les sections trames de pile pour Callback en 32 et 64 bits, et trames de pile automatisées utilisant FRAME … ENDF, LOCALS et USEDATA.

Voir aussi comprendre la pile (parties 1 et 2) dans les annexes.

Si vous utilisez l'assemblage conditionnel dans vos définitions il est recommandé d'utiliser MACRO … ENDM au lieu de la méthode des caractères de continuation mentionnée plus haut.

Voici un exemple :

STRINGS UNICODE
CODE
;
#define			REPORT
;
MBMACRO(%lpTextW)	MACRO
			#ifdef REPORT
			 INVOKE	MessageBoxW, 0, addr %lpTextW, "Report", 40h
			#endif
			ENDM
;
			MBMACRO("Ce code a été assemblé !")

Dans le code ci-dessus, la boîte de message (Message Box) est affichée de manière classique via l'API MessageBox. On a vu précédemment que la ligne #define REPORT sans autre paramètre donne à REPORT la valeur 1 (TRUE). Cette situation autorise l'affichage. Mais si REPORT était suivi d'une valeur, alors il n'y aurait pas de message affiché. La chaîne « Ce code a été assemblé ! » est envoyée comme un argument à la macro.

Voir la section assemblage conditionnel.

Ceci s'applique uniquement à la programmation 32 bits.

ARGCOUNT renvoie le nombre d'arguments donnés lorsque la définition est utilisée, ce qui peut être utilisé avec l'assemblage conditionnel dans les définitions. Par exemple, considérons la macro nommée macro26 ainsi définie :

macro26(%a,%b,%c,%d,%e,%f)	=	#if ARGCOUNT=6 \
					 PUSH	%f \
					#endif \
					#if ARGCOUNT >=5 \
					 PUSH	%e \
					#endif \
					#if ARGCOUNT >=4 \
					 PUSH	%d \
					#endif \
					#if ARGCOUNT >=3 \
					 PUSH	%c \
					#endif \
					#if ARGCOUNT >=2 \
					 PUSH	%b \
					#endif \
					#if ARGCOUNT >=1 \
					 PUSH	%a \
					#endif

Imaginons maintenant que nous utilisions macro26 comme suit :

macro26(4,3,2,1)

Dans ce cas, ARGCOUNT prendrait la valeur 4 et le code résultant correspondrait exactement à l'instruction multiple suivante :

PUSH	1, 2, 3, 4

Dans l'exemple ci-dessus, les deux premiers PUSH sont ignorés parce que ARGCOUNT est ni 6 (dans le premier test) ni supérieur ou égal à 5 (dans le second test).

Cela peut être amélioré pour établir une macro d'appel de fonction « C » où la pile est effacée après l'appel (le nombre correct d'octets est ajouté au pointeur de pile ESP après l'appel) :

macro26(%x,%a,%b,%c,%d,%e,%f)	=	#if ARGCOUNT=7 \
					 PUSH	%f \
					#endif \
					#if ARGCOUNT >=6 \
					 PUSH %e \
					#endif \
					#if ARGCOUNT >=5 \
					 PUSH %d \
					#endif \
					#if ARGCOUNT >=4 \
					 PUSH %c \
					#endif \
					#if ARGCOUNT >=3 \
					 PUSH %b \
					#endif \
					#if ARGCOUNT >=2 \
					 PUSH %a \
					#endif \
					CALL	%x \
					ADD	ESP, ARGCOUNT-1*4

et ici, on peut voir une autre manière d'y arriver :

cinvoke(funcname,%1,%2,%3,%4,%5)	=	\
						#if ARGCOUNT=1      \
						 invoke	funcname      \
						#elif ARGCOUNT=2      \
						 invoke	funcname, %1     \
						#elif ARGCOUNT=3        \
						 invoke	funcname, %1, %2    \
						#elif ARGCOUNT=4          \
						 invoke	funcname, %1, %2, %3   \
						#elif ARGCOUNT=5            \
						 invoke	funcname, %1, %2, %3, %4  \
						#elif ARGCOUNT=6              \
						 invoke	funcname, %1, %2, %3, %4, %5 \
						#endif                          \
						#if ARGCOUNT>1                   \
						 ADD ESP, ARGCOUNT-1*4              \
						#endif

Lesquels pourraient alors être utilisés comme suit :

cinvoke(_cprintf,23,24,25,26,27)
macro26(_cprintf,23,24,25,26,27)

Si vous ne souhaitez utiliser le caractère de continuation, vous pouvez utiliser MACRO … ENDM en lieu et place.

Un double-dièse dans une définition a pour fonction de joindre deux éléments en supprimant tous les espaces entre les deux. Cela vous permet de créer un seul mot à partir d'un ou plusieurs composants, par exemple :

LVERS=0030
MVERS=0044h
VERSION=LVERS##MVERS
;
MOV	EAX, VERSION

Ici, VERSION est défini par le nombre 00300044h.

Certains programmeurs utilisent des définitions aussi souvent que possible. À mon avis, cela rend le script source plus difficile à lire. Aussi convient-il de déterminer dans quelle mesure quelqu'un d'autre que le concepteur pourrait être amené à parcourir le code source et à en comprendre les tenants et les aboutissants à supposer, bien évidemment, que cela soit souhaitable… Si cette personne doit souvent se référer à d'autres fichiers ou à des listes de définitions pour ce faire, alors le codage manquera, à l'évidence, de clarté. Utilisées cependant avec modération en programmation Windows, les définitions peuvent se révéler utiles pour expliciter le script source. Par exemple :

PUSH	WS_CHILD|WS_VISIBLE|SS_OWNERDRAW

est plus parlant que :

PUSH	5000000Dh

bien qu'un commentaire approprié puisse, en l'espèce, éclairer utilement cette instruction sans qu'il soit nécessaire d'utiliser une définition :

PUSH	5000000Dh	; WS_CHILD, WS_VISIBLE, SS_OWNERDRAW

En revanche, la formulation qui suit nuit à la clarté du code et doit donc être évitée :

#define	wParam	EBP+10h
	MOV	EAX, [wParam]	; identique à MOV EAX, [EBP+10h]

On notera en effet que la référence [wParam] fait apparaître wParam comme un label, ce qui n'est justement pas le cas ici. Mieux vaut écrire en l'occurrence :

#define	wParam	[EBP+10h]
	MOV	EAX, wParam

Ceci est plus clair ainsi parce que, dans GoAsm, la seule chose que vous pouvez aborder de cette manière sans l'aide des crochets est une définition.

Ce qui suit est également contestable et doit être évité à tout prix :

#define	GET_LPARAM	MOV EAX, [EBP+14h]
	GET_LPARAM

Une meilleure pratique de programmation suggère d'écrire :

CALL	GET_LPARAM

et de réaliser correctement cet appel sous forme de fonction. Cependant lors de la manipulation de la pile, il est très difficile d'utiliser une procédure dans la mesure où CALL et RET modifient eux-mêmes la pile. Donc, dans ce cas, il peut être pratique d'utiliser une définition si la clarté du script source n'en souffre pas. Voir, à ce titre, les exemples OPEN_STACKFRAME et CLOSE_STACKFRAME proposés précédemment.

Enfin, il semble qu'il y ait peu d'intérêt à écrire :

THOUSAND	=	1000D
	MOV	EAX, THOUSAND

alors qu'une formulation plus directe serait tout aussi claire :

MOV	EAX, 1000D

À titre d'illustration et en guise de conclusion, imaginez que vous souhaitiez que votre script source soit compréhensible par des non-Anglophones. Dans ce cas, il vous serait parfaitement possible de traduire tous les mnémoniques du processeur en utilisant des equates pour parvenir à vos fins. Voir à ce sujet la section « Utilisation de mots définis dans les fichiers Unicode » dans le chapitre du volume 2 consacré à l'Unicode.

Au moment de l'exécution, les données ne peuvent être importées qu'indirectement. Cela veut dire que vous ne pouvez importer qu'un pointeur vers des données. Cependant, en utilisant ce pointeur, vous pouvez obtenir les données elles-mêmes.

Par exemple, en supposant que DATA_VALUE est un export de données dans un autre programme vous obtenez, avec GoAsm, le pointeur et la donnée comme suit :

MOV	EBX, [DATA_VALUE]	; pointeur vers DATA_VALUE dans EBX
MOV	EAX,	[EBX]		; on récupère la donnée dans EAX à partir de ce pointeur

De la même manière que pour l'importation des procédures d'autres programmes au moment de l'édition de liens, vous donnez au linker (GoLink, en l'occurrence) le nom de l'exécutable contenant l'import.

Le type d'import auquel nous sommes confrontés en utilisant la procédure CALL importera la procédure par son nom. De manière plus détaillée lorsque le chargeur Windows démarre le programme, il parcourt les DLL pour les importations requises par le programme. Il le fait en comparant les noms des exportations dll aux noms des imports du programme. Pour accélérer ce processus avec les Dll privées l'exportation et l'importation par ordinal sont parfois utilisées. Par ce biais, le chargeur peut trouver la bonne importation en utilisant un index dans une table de la DLL. Notez qu'il est imprudent de le faire dans le cas des DLL du système Windows puisque l'uniformité des nombres ordinaux des exportations n'est pas garantie selon les différentes versions de DLL.

En utilisant GoAsm et son complément GoLink, vous pouvez importer par ordinal par cette syntaxe simple :

CALL	MyDll:6

Cette procédure va appeler le numéro 6 dans MyDll.dll. Notez que l'extension « dll » est implicite si aucune extension n'est mentionnée. Supposons que vous vouliez une DLL pour appeler une fonction dans l'exécutable principal par ordinal. Dans ce cas, vous pourriez utiliser :

CALL	Main.exe:15

qui appellera la 15^e fonction de Main.exe.

Les appels ordinaux utilisant la forme absolue (c'est-à-dire utilisant les opcodes FF15) emploient, quant à eux, la syntaxe qui suit :

CALL	[Main.exe:15]

Vous n'avez pas à inclure le chemin d'accès au fichier dans le CALL. GoLink réalise une recherche étendue des fichiers spécifiés, mais s'il était toutefois nécessaire de fournir un chemin ce serait dans le cadre de l'éditeur de liens plutôt qu'au niveau du CALL du script de l'assembleur.

Évidemment, pour utiliser cette méthode d'appel d'une fonction par ordinal vous devez vous assurer que le nombre ordinal de la fonction est fixé. Voir la section export par ordinal.

Note : ce qui précède s'applique uniquement à GoLink.

Il y a une autre façon d'utiliser les ordinaux en utilisant LoadLibrary pour charger la DLL (ou retourner un handle si elle est déjà chargée), puis en appelant GetProcAddress en passant la valeur ordinale pour obtenir la valeur de la procédure à appeler. Enfin, vous appelez la procédure telle que fournie par GetProcAddress.

Occasionnellement, vous voudrez peut-être forcer le linker à utiliser une importation en provenance d'une DLL particulière. Vous pourriez avoir besoin de procéder de la sorte si deux DLL voire plus (désignées au linker au moment de la phase d'édition de liens) comportent des fonctions portant le même nom. Il est donc possible, dans ce cas, de forcer GoLink à établir des liens avec une DLL particulière en utilisant la syntaxe :

CALL	NameOfDll:NameOfAPI

Ceci s'applique uniquement à GoLink.

Les données ne peuvent être exportées qu'indirectement. Seul, un pointeur vers ces données peut être exporté. Par l'utilisation de ce pointeur, le programme d'importation peut toutefois obtenir lui-même les données.

Vous pouvez utiliser exactement la même méthode pour exporter un label de donnée que celle utilisée pour un label de code. Il n'y a pas besoin de déclarer le label comme étant de données ou de code. Il en est ainsi parce que la tâche de vérification de l'appartenance du label à une section de données ou à une section de code incombe à l'éditeur de liens. Voici un exemple d'export du label de donnée :

EXPORT	DATA_VALUE	DD	0

Cette instruction exporte l'étiquette de données DATA_VALUE. Le destinataire peut obtenir la valeur de DATA_VALUE de la manière suivante :

MOV	EBX, [DATA_VALUE]	; EBX = pointeur vers DATA_VALUE
MOV	EAX, [EBX]		; EAX = valeur de DATA_VALUE

Normalement, les exports sont nominatifs. Lorsque le chargeur Windows démarre le programme, il parcourt les DLL pour y chercher les importations requises par le programme. Cela se fait en confrontant les noms des exportations des DLL aux noms des importations du programme. Pour accélérer ce processus avec DLL private, l'exportation et l'importation par ordinal sont parfois utilisées. Dans ce cas, le chargeur peut trouver la bonne importation en utilisant simplement un index destiné à une table dans la DLL. Notez qu'il est imprudent de le faire dans le cas des DLL du système Windows puisque les nombres ordinaux des exportations peuvent varier selon les versions de DLL.

Pour utiliser cette méthode, il est clairement impératif que le programme d'exportation spécifie une valeur ordinale pour une exportation particulière et que l'éditeur de liens ne puisse y apporter aucune modification. Encore une fois, en utilisant GoAsm vous pouvez spécifier la valeur ordinale correcte et la passer au linker via la section .drectve (cependant, les linkers ne supportent pas tous cette pratique).

Voici comment spécifier une exportation par ordinal si les exportations sont listées avant que les sections ne soient déclarées :

EXPORTS CALCULATE:2, DATA_VALUE:6

Ici, le linker sera chargé d'utiliser les ordinaux 2 et 6 pour les exportations. Si vous utilisez la méthode alternative de déclarer les exportations (au sein d'une section) vous pouvez utiliser par exemple :

EXPORT:2 CALCULATE:

ou dans le cas de données :

EXPORT:6 DATA_VALUE DD 0

L'export par ordinal n'empêche pas le nom de l'export d'apparaître dans l'exécutable final. Il en est ainsi parce que c'est le programme d'importation qui décide d'importer par ordinal ou par nom. Tout ce que le programme d'exportation peut faire se limite à fixer la valeur ordinale. Cependant, il peut arriver que le programmeur ne souhaite pas qu'un nom pour l'exportation apparaisse dans l'exécutable final. On peut observer de telles exportations « sans nom » dans les DLL système par exemple, probablement dans le but de masquer le travail effectué par des fonctions particulières. Il est possible de recourir à ce procédé dans GoAsm en ajoutant la déclaration NONAME à la fin de l'exportation. Par exemple :

EXPORT:2:NONAME
CALCULATE:

Ici, la valeur du label de code CALCULATE sera exportée comme nombre ordinal 2, mais le nom de l'exportation n'apparaîtra pas dans l'exécutable final. Cela signifie que si un autre programme essayait d'appeler la fonction CALCULATE, il enregistrerait un échec. La fonction peut seulement être appelée par ordinal.

En programmation Windows, les trames de pile sont nécessaires pour les procédures de fenêtre, les procédures d'hameçonnage (hooking), le sur-classement et le sous-classement, les procédures de chargement et de déchargement de DLL et autres callbacks. Les procédures callback sont toutes appelées par Windows, en utilisant le propre thread de votre programme.

Dans GoAsm, la création et l'utilisation de trames de pile sont entièrement automatisées lorsque vous utilisez FRAME … ENDF.

Voir la section trames de pile automatisées pour savoir comment l'utiliser en pratique.

Entre Windows 32 et 64 bits, les trames de pile sont différentes et doivent donc être traitées de manière spécifique. Mais la syntaxe pour utiliser FRAME … ENDF ainsi que leurs instructions d'accompagnement telles que LOCALS et USEDATA … ENDU est la même sur les deux plateformes. Pour cette raison, lorsque vous utilisez FRAME … ENDF il est possible d'utiliser le même script source pour les deux. Voir le chapitre écriture de programmes 64 bits pour plus d'informations sur la programmation 64 bits en général.

Le travail dévolu à la trame de pile est dicté par la convention d'appel utilisée. Windows 32 bits utilise la convention d'appel standard (STDCALL). Dans ce contexte, la trame de pile dans une procédure de fenêtre doit accomplir quatre actions :

• accéder aux paramètres envoyés par Windows (qui sont justement envoyés sur la pile) ;
• rétablissement de l'équilibre de la pile avant de retourner à l'appelant ;
• allocation d'un espace sur la pile pour les données locales ;
• préservation pour Windows du contenu des registres EBX, ESI, EDI et EBP si ces derniers sont appelés à être modifiés.

Ces quatre actions sont aussi importantes les unes que les autres.

V-H-2-a. Accès aux paramètres à partir de la pile▲

Windows pousse les paramètres sur la pile avant d'appeler votre procédure de fenêtre, de la même manière que vous le faites avant d'appeler une API dans vos programmes. Lorsque Windows appelle une procédure de fenêtre, il envoie les paramètres suivants sous forme de DWords placés sur la pile (les mots utilisés ici sont ceux couramment utilisés pour les nommer) :

hwnd	handle de la fenêtre
uMsg	identificateur de message
wParam	donnée
lParam	donnée

Votre procédure de fenêtre a besoin d'accéder à ces paramètres. Une façon de le faire est de les extraire de la pile par des POP successifs en tant que données statiques, mais il est plus judicieux (et plus sûr) de conserver ces paramètres sur la pile et de les adresser directement. Cela vaut d'autant mieux que les procédures de fenêtres s'appellent elles-mêmes parfois. Cela peut sembler étrange, mais un exemple suffira à s'en convaincre.

Supposons que votre procédure ait besoin de remplir la fenêtre avec un matériau approprié au bon moment. Ceci s'appelle « peindre » la fenêtre. Cela se fait en réponse au message Windows WM_PAINT (numéro de message 0Fh). Maintenant, la bonne façon de répondre à ce message consiste tout d'abord à appeler l'API BeginPaint, puis à peindre la fenêtre, puis appeler enfin l'API EndPoint. Une des choses que BeginPaint fait est de préparer la fenêtre pour la peinture. Ce faisant, elle envoie un autre message à votre procédure de fenêtre, cette fois WM_ERASEBKGND (numéro de message 14h). Ainsi, alors que votre procédure de fenêtre est aux prises avec ce deuxième message, elle n'est pas encore revenue de l'API BeginPaint. Après que le deuxième message a été traité, BeginPaint sera de retour. Ainsi, la procédure de fenêtre est-elle récursive, ce qui revient à dire qu'elle peut revenir sur elle-même. Pour chaque message (sauf pour hwnd) les paramètres seront différents. Si ces derniers sont maintenus sur la pile, cela signifie que chaque fois que la procédure de fenêtre sera appelée les paramètres seront conservés sur une partie différente de la pile et ne pourront pas être écrasés.

Voici, à titre d'exemple, une trame de pile typique sur 32 bits :

 

Sélectionnez

TypicalStackFrame:
			PUSH	EBP		; sauvegarde de EBP qui va être altéré                ┐   appelé
			MOV	EBP, ESP	; EBP mémorise la valeur courante du pointeur de pile ┘ "prologue"
; 						; POINT "X"
; 						; code pour isoler le message WM_PAINT 
			PUSH	ADDR PAINTSTRUCT
			PUSH	[hwnd]
			CALL	BeginPaint	; API prêt à peindre la fenêtre
;						; peinture de la fenêtre et appel de l'API EndPaint
;
			MOV	ESP, EBP	; rétablissement ancienne valeur du pointeur de pile  ┐   appelé
			POP	EBP		; restauration de EBP                                 │ "épilogue"
			RET	10h		; retour à l'appelant en ajustant le pointeur de pile ┘

Pendant toute récursion, ESP sera changé dans la mesure où une utilisation ultérieure de la pile interviendra. En revanche, EBP sera toujours sauvegardé et restauré par cette procédure de sorte qu'il pourra toujours être invoqué pour accéder à la partie correcte de la pile afin que le message soit traité.

Cette particularité sera probablement mieux illustrée en approfondissant le fonctionnement de la pile dans l'exemple qui précède. Dans une procédure de fenêtre typique répondant au message WM_ERASEBKGND, prenons un instantané de la pile lorsque l'exécution est au point « X ». La pile va alors ressembler à ceci (j'ai passé sous silence une bonne partie de l'utilisation de la pile par souci de clarté) :

Ici, les paramètres lParam, wParam, uMsg et hwnd qui sont sur la pile de EBP+3Ch à EBP+30h sont ceux envoyés à la procédure de fenêtre sur le message WM_PAINT. Puis, à EBP+2Ch nous trouvons l'adresse de l'appelant qui envoie le message WM_PAINT (ce sera un appel en provenance d'une DLL Windows). À EBP+28h se situe la valeur de EBP enregistrée sur la première instruction d'entrée dans la procédure de fenêtre sur le message WM_PAINT. Entre EBP+24h et EBP+1Ch on trouve l'utilisation de la pile de votre procédure de fenêtre avant que vous n'appeliez l'API BeginPaint. Concrètement, ces emplacements seraient occupés par deux PUSHes, puis l'adresse de retour sur l'appel de l'API (dans votre procédure de fenêtre) mise sur la pile. Le quatrième PUSH ici pourrait être quelque chose poussé sur la pile par BeginPaint lui-même avant d'envoyer le message WM_ERASEBKGND. En pratique, il pourrait y avoir beaucoup plus d'utilisation de la pile à l'intérieur BeginPaint ici. La prochaine chose que vous voyez à EBP+14h est à nouveau lParam. Mais celui-ci est différent de son homologue situé à EBP+3Ch. Il s'agit du lParam envoyé avec WM_ERASEBKGND. Le reste des entrées à la valeur actuelle de EBP sont en rapport avec le message WM_ERASEBKGRND.

Voyons maintenant ce qui se produit au retour de BeginPaint. Puisque nous savons que BeginPaint restaurera toujours EBP à la valeur qui était la sienne à l'entrée de l'API, nous savons que EBP au retour pointera vers la pile à EBP+28h dans la trame de pile ci-dessus. À partir de ce point, vous pouvez voir que les paramètres antérieurs (ceux envoyés avec WM_PAINT) peuvent être consultés à l'aide de EBP+8h, EBP+0Ch, EBP+10h et EBP+14h comme avant. Ils ont été préservés et n'ont pas été écrasés par l'appel à BeginPaint et par la récursion dans la procédure de fenêtre.

V-H-2-b. Restauration de la pile à l'équilibre avant de retourner à l'appelant▲

PUSH	ADDR PAINTSTRUCT
PUSH	[hwnd]
CALL	BeginPaint		; fait en sorte qu'on puisse être prêt à peindre la fenêtre

V-H-2-c. Création d'un espace sur la pile pour les données locales▲

Une autre tâche importante dévolue à la procédure callback est d'allouer, en cas de besoin, un espace aux données locales. Il s'agit de données qui sont conservées dans la pile pendant que l'exécution se poursuit dans la procédure callback. Elles sont perdues lorsque l'exécution quitte la procédure. Nous avons déjà vu comment les données sur la pile (sous la forme de paramètres) sont conservées en constituant une trame de pile. L'espace pour les données locales utilise le même principe. Supposons que nous ayons besoin d'espace pour trois DWords sur la pile parce que nous voulons préserver ces données cependant que la procédure de fenêtre est en récursion. Le code à utiliser pourrait être le suivant :

 

Sélectionnez

TypicalStackFrame:
			PUSH	EBP		; sauvegarde de EBP qui va être altéré                ┐
			MOV	EBP, ESP	; EBP mémorise la valeur courante du pointeur de pile │ "prologue"
			SUB	ESP, 0Ch	; on constitue un espace pour les données locales     ┘
;						; POINT "X"
;
;						; code de la procédure de fenêtre
;
			MOV	ESP, EBP	; rétablissement ancienne valeur du pointeur de pile  ┐
			POP	EBP		; restauration de EBP                                 │ "épilogue"
			RET	10h		; retour à l'appelant en ajustant le pointeur de pile ┘

Ici, nous avons déplacé le pointeur de pile de 12 octets, ce qui est exactement la même chose que si nous avions procédé à trois PUSH successifs. Ceci permet d'obtenir une zone de la pile qui ne peut être utilisée à d'autres fins.

En utilisant FRAME … ENDF vous pouvez créer automatiquement la trame de pile.

Voici une utilisation typique de FRAME … ENDF qui fait la même chose que TypicalStackFrame ci-dessus et fournit des noms pour les paramètres qui sont envoyés à la procédure de fenêtre et des noms pour chaque DWord de donnée locale :

 

Sélectionnez

WndProc	FRAME	hwnd, uMsg, wParam, lParam
	LOCALS	hDC, hInst, KEEP
;	; POINT "X"
;
;	; le code vient ici
;
	RET
	ENDF

La pile courante apparaît comme ceci au point « X » :

Bien sûr, si le pointeur de pile est soumis à ces déplacements, il va de soi qu'il doit être restauré en sortie. Mais cette fois, l'opération est automatique, car EBP est tout simplement restauré à sa valeur avant de retourner à l'appelant, et EBP avait du reste été enregistré avant le déplacement du pointeur de pile pour faire de la place à des données locales.

V-H-2-d. Préservation pour Windows des registres EBX, ESI, EDI et EBP▲

WndProc	FRAME	hwnd, uMsg, wParam, lParam
	USES	EBX, ESI, EDI
	LOCALS	hDC, hInst, KEEP
;
;	; le code est placé ici
;
	RET
	ENDF

Le travail qui incombe à la trame de pile est dicté par la convention d'appel utilisée. Windows 64 bits utilise la convention d'appel dite rapide (FASTCALL). Au lieu que l'appelant mette les paramètres sur la pile comme dans la convention STDCALL, les quatre premiers paramètres sont mis dans les registres RCX, RDX, R8 et R9. Les éventuels paramètres complémentaires sont mis sur la pile. Ainsi, la procédure de fenêtre doit-elle exécuter les tâches qui suivent :

• enregistrer sur la pile les paramètres envoyés dans les registres et accéder à tous les paramètres supplémentaires envoyés par Windows sur la pile ;
• fournir un espace sur la pile pour les données locales ;
• préserver pour Windows les registres dits « non volatils » dès qu'ils sont modifiés. Il s'agit de RBP, RBX, RDI, RSI, R12 à R15 et XMM6 à XMM15.

Il n'est pas nécessaire que la procédure de fenêtre restaure l'équilibre de la pile, avant de retourner à l'appelant. Ce travail est fait par l'appelant.

V-H-3-a. Enregistrement et accès aux paramètres▲

MOV	[RSP+8h], RCX
MOV	[RSP+10h], RDX
MOV	[RSP+18h], R8
MOV	[RSP+20h], R9
PUSH	RBP
MOV	RBP, RSP

LEA	RSP, [RBP]
POP	RBP
RET

V-H-3-b. Construire un espace sur la pile pour les données locales▲

V-H-3-c. Préservation des registres non volatils pour Windows▲

RBP est déjà sauvegardé par le code du prologue puis restauré par celui de l'épilogue. Comme pour les registres à usage général, si les registres RBX, RDI, RSI et R12 à R15 sont modifiés par la procédure de fenêtre, ils auront besoin de voir leur valeur initiale restaurée. La meilleure façon de le faire est d'utiliser l'instruction USES qui les copie sur la pile. Les registres XMM6 à XMM15 peuvent être sauvegardés et restaurés en bloc, en utilisant les instructions du processeur FXSAVE et FXRSTOR qui n'agissent toutefois qu'au niveau de l'Unité de Calcul en virgule flottante (FPU).

Considérons maintenant l'utilisation assez classique de FRAME … ENDF qui suit :

 

Sélectionnez

WndProc	FRAME	hwnd, uMsg, wParam, lParam
	USES	RBX, RSI, RDI
	LOCALS	hDC, BUFFER[256]:B
;	; POINT 'X'
;	; le code s'écrit ici
;
	RET
	ENDF

Voici maintenant comment la trame de pile se présente en assemblage 64 bits, en utilisant les valeurs de RSP et RBP au début du code au POINT 'X' (notez que RBP affiche 32 octets de moins que RSP affichait en entrant dans la procédure : ce décalage est dû aux instructions PUSH portant successivement sur les registres RBP, RBX, RSI et RDI) :

V-I-1-a. Les bases▲

WndProc	FRAME	hwnd, uMsg, wParam, lParam
	USES	EBX, ESI, EDI
	LOCALS	hDC, BUFFER[256]:B
;
;	; le code s'écrit ici
;
	RET
	ENDF

V-I-1-b. Accès aux paramètres et aux données locales à l'intérieur d'une trame automatisée▲

PUSH	[hwnd]			; équivaut à PUSH [EBP+8h]
MOV	EAX, [uMsg]		; équivaut à MOV EAX, [EBP+0Ch]
MOV	EBX, ADDR wParam	; équivaut à LEA EBX, [EBP+10h]
PUSH	ADDR lParam		; équivaut à PUSH EBP suivi de ADD D[ESP], 14h
MOV	EBX, [hDC]		; équivaut à MOV EBX, [EBP-10h]
MOV	EBX, ADDR BUFFER	; équivaut à LEA EBX, [EBP-110h]

MOV	D[BUFFER+10h], 44h

USES	EBX, EDI, ESI

V-I-1-c. Utilisation de structures comme données locales dans une trame de pile▲

RECT		STRUCT
 left		DD 0
 top		DD 0
 right		DD 0
 bottom		DD 0
		ENDS
;
WndProc		FRAME	hwnd, uMsg, wParam, lParam
		LOCALS	hDC, rc1:RECT
;
;		; le code s'écrit ici
;
		RET
		ENDF

MOV	EAX, [rc1.right]	; équivaut à MOV EAX, [EBP-0Ch]
MOV	EAX, [ESI+RECT.right]	; équivaut à MOV EAX, [ESI+8h]
MOV	EAX, SIZEOF RECT	; équivaut à MOV EAX, 10h
MOV	EAX, ADDR rc1.right	; équivaut à LEA EAX, [EBP-0Ch]
PUSH	[rc1.right]		; équivaut à PUSH [EBP-0Ch]
PUSH	ADDR rc1.right		; équivaut à PUSH EBP suivi de ADD D[ESP], -0Ch
PUSH	ADDR rc1		; équivaut à PUSH EBP suivi de ADD D[ESP], -14h

V-I-2-a. Quelques considérations pratiques▲

V-I-2-b. Appel de procédures à l'intérieur d'une trame de pile - Usage de RETN▲

WndProc	FRAME	hwnd, uMsg, wParam, lParam
	USES	EBX, ESI, EDI
	LOCAL	hDC, BUFFER[256]:B
	MOV	EAX, [uMsg]				; récupération du message envoyé par Windows
	CMP	EAX, 0Fh				; on regarde si c'est WM_PAINT
	JNZ	>L2					; non
	CALL	WINDOW_PAINT				; on peint la fenêtre
	XOR	EAX, EAX				; renvoie zéro pour montrer que le message est traité
	RET						; restauration de la pile et retour à Windows
;
L2:
	ARG	[lParam], [wParam], [uMsg], [hwnd]
	INVOKE	DefWindowProcA				; permet à Windows de traiter avec le message
	RET						; restauration de la pile et retour à Windows
;
WINDOW_PAINT:
; code pour peindre la fenêtre
	RETN						; exécute un retour ordinaire de la procédure de peinture
;
	ENDF						; stoppe toute action FRAME à partir de ce point.

V-I-2-c. Appel de procédures à l'extérieur d'une trame de pile▲

PAINT:
	USEDATA	WndProc
	INVOKE	BeginPaint, [hwnd], ADDR lpPaint	; récupère en EAX le DC à utiliser
	MOV	[hDC], EAX
	INVOKE	Ellipse, [hDC], [lpPaint.rcPaint.left], \
		[lpPaint.rcPaint.top], \
		[lpPaint.rcPaint.right], \
		[lpPaint.rcPaint.bottom]
	INVOKE	EndPaint, [hwnd], ADDR lpPaint
	XOR	EAX, EAX
	RET
	ENDU

V-I-3-a. Déclaration de donnée locale à message spécifique▲

WndProc		FRAME	hwnd, uMsg, wParam, lParam
		USES	EBX, ESI, EDI
		LOCAL	hDC					; déclare hDC pour un usage de trame étendue
		MOV	EAX, [uMsg]				; récupération du message envoyé par Windows
		CMP	EAX, 0Fh				; est-ce WM_PAINT ?
		JNZ	>L2					; non
		CALL	WINDOW_PAINT				; c'est WM_PAINT, alors on peint la fenêtre
		XOR	EAX, EAX				; on retourne zéro pour signifier que le message a été traité
		RET						; restauration de la pile et retour à Windows
;
L2:
		ARG	[lParam], [wParam], [uMsg], [hwnd]
		INVOKE	DefWindowProcA				; permet à Windows de traiter avec le message
		RET						; restauration de la pile et retour à Windows
;
		ENDF						; arrête toute action de FRAME à partir de ce point
;
WINDOW_PAINT:
		USEDATA	WndProc					; utilise les paramètres et les données locales de WndProc
		LOCAL	ps:PAINTSTRUCT				; construit des zones de données locales
		LOCAL	BUFFER[1024]:B				; spécifiquement à ce message
;
		ARG	ADDR ps, [hwnd]
		INVOKE	BeginPaint				; prêt à peindre la fenêtre
		MOV	[hDC], EAX				; sauvegarde le contexte de périphérique dans la donnée locale hDC
								; code pour peindre la fenêtre
		RET						; effectue un retour ordinaire de la procédure de peinture
		ENDU						; met fin à l'utilisation de la trame de données WndProc

V-I-3-b. Création d'une procédure de fenêtre réduite▲

WndProc	FRAME	hwnd, uMsg, wParam, lParam
	MOV	EAX, [uMsg]
	MOV	ECX, SIZEOF MESSAGES/8
	MOV	EDX, OFFSET MESSAGES
:
	DEC	ECX
	JS	>.notfound
	CMP	[EDX+ECX*8], EAX		; est-ce le message correct ?
	JNZ	<				; non, on va voir le suivant...
	CALL	[EDX+ECX*8+4]			; appel de la procédure correcte pour le message
	JNC	>.exit
.notfound
	INVOKE	DefWindowProcA, [hwnd], [uMsg], [wParam], [lParam]
.exit
	RET
	ENDF

MESSAGES	DD	1h, CREATE	; la valeur du message puis l'adresse du code
		DD	2h, DESTROY
		DD	0Fh, PAINT
NextLabel:

CREATE:
	USEDATA	WndProc		; utiliser les données de la pile dans la trame
				; de la procédure de fenêtre
	USES	EBX, EDI, ESI	; préservation des registres pour Windows
	LOCALS	LocalData	; établissement de la zone de données locales requise
;
; code à exécuter sur le message WM_CREATE 
;
	XOR	EAX, EAX	; retourne NC et EAX = 0 pour continuer à créer la fenêtre
	RET			; restauration des registres puis RET
	ENDU			; arrêt de toute action automatique et accès aux données

V-I-3-c. Mots définis localement utilisant #localdef ou LOCALEQU▲

FrameProc1	FRAME	Param
#localdef	THING1	23h
		THING2	LOCALEQU 88h
;
		MOV	EAX, THING1	; définition locale 23h
		MOV	EAX, THING2	; définition locale 88h
;
		RET
		ENDF
;
MyFunction44:	USEDATA	FrameProc1
#localdef	THING3	0CCh
;
		MOV	EAX, THING1	; la définition locale devrait être 23h
		MOV	EAX, THING2	; la définition locale devrait être 88h
;
		RET
		ENDU

V-I-3-d. Portée d'un label réutilisable dans les trames de pile automatisées▲

ExampleProc	FRAME	Param
		CMP	EDX, EAX
		JZ	>.fin
LABEL1:
		XOR	EAX,EAX
.fin
		RET
		ENDF
LABEL2:

V-I-3-e. Héritage et portée avec USEDATA … ENDU▲

Une zone USERDATA … ENDU peut être associée soit directement avec une FRAME, soit avec une autre zone USERDATA … ENDU.

Cela permet aux utilisateurs expérimentés de sélectionner les données locales et les mots définis qu'une zone USEDATA peut utiliser.

La disposition habituelle est d'avoir, pour chaque zone de USEDATA, un enfant de FRAME :

 

Sélectionnez

FrameExample	FRAME			Param
LOCAL		LocalLabel1
#localdef	CONSTANT		23h
;
		RET
		ENDF
;
Usedata#1:	USEDATA			FrameExample
		MOV			EAX, [LocalLabel1]
		MOV			EAX, CONSTANT
		MOV			EAX, [Param]
		RET
		ENDU
;
Usedata#2:	USEDATA			FrameExample
		LOCAL			Specific
#localdef	SPECIFIC_CONSTANT	444444h
		MOV			EAX, [LocalLabel1]
		MOV			EAX, CONSTANT
		MOV			EAX, [Param]
		MOV			EAX, [Specific]
		MOV			EAX, SPECIFIC_CONSTANT
		RET
		ENDU

Ici chaque zone USEDATA peut accéder aux paramètres de FRAME, aux données locales et aux mots définis. Notez cependant que Usedata#2 a ses propres données locales et mots définis. Ceux-là seuls peuvent être référencés dans Usedata#2. Si Usedata#1 avait essayé d'y accéder (ou le code dans FrameExample, d'ailleurs), ils n'auraient pas été trouvés.

Dans la représentation qui suit, la première zone USEDATA est l'émanation de FRAME et la seconde zone USEDATA est sa sous-émanation.

 

Sélectionnez

FrameExample	FRAME			Param
		LOCAL			LocalLabel1
#localdef	CONSTANT		23h
;
R		ET
		ENDF
;
Usedata#1:	USEDATA			FrameExample
		LOCAL			Specific
#localdef	SPECIFIC_CONSTANT	444444h
		RET
		ENDU
;
Usedata#2:	USEDATA			Usedata#1
		MOV			EAX, [LocalLabel1]
		MOV			EAX, CONSTANT
		MOV			EAX, [Param]
		MOV			EAX, [Specific]
		MOV			EAX, SPECIFIC_CONSTANT
		RET
		ENDU

Ici, bien que chaque zone USERDATA puisse accéder aux paramètres de la trame, aux données locales et aux mots définis, Usedata#2 peut également faire référence à des données locales et des mots définis localement dans Usedata#1.

V-I-3-f. Diffusion des données locales et constitution de nouvelles données locales▲

CREATE:
	USEDATA	WndProc		; utilisation des données de la pile dans la trame
				; de la procédure de fenêtre
	USES	RBX, RDI, RSI	; préservation des registres pour Windows
	LOCALS	BUFFER[4000]:B	; établissement d'un grand buffer sur la pile
;
; part de code correspondant à l'exécution sur le message WM_CREATE 
;
	LOCALFREE		; effacement du grand buffer
	LOCALS	BUFFER[256]:B	; établissement d'un buffer plus petit sur la pile
;
; part de code correspondant à l'exécution sur le message WM_CREATE
;
	XOR	RAX, RAX	; retourne NC et RAX=0 pour continuer la création de la fenêtre
	RET			; restauration des registres puis RET
	ENDU			; met fin à toute action automatique et accès aux données

V-I-4-a. Quelques points de syntaxe lors de l'utilisation de FRAME … ENDF▲

CodeLabel:
		FRAME	Parameter List	; si des paramètres sont nécessaires
		USES	Register List	; s'il est nécessaire de sauvegarder des registres
		LOCAL	Local List	; si des variables locales sont requises
 ;
		ret
		ENDF

V-I-4-b. Quelques points de syntaxe lors de l'utilisation de USEDATA … ENDU▲

CodeLabel:
		USEDATA	SourceData
		USES	Register List	; si les registres ont besoin d'être sauvegardés
		LOCAL	Local List	; si des variables locales sont requises
 ;
		ret
		ENDU

V-I-4-c. Ce que vous pouvez voir dans le débogueur▲

USEDATA	WndProc	SHIELDSIZE:20h	; en assemblage 32 bits
USEDATA	WndProc	SHIELDSIZE:40h	; en assemblage 64 bits

L'assemblage conditionnel vous permet de sélectionner, lors de la phase d'assemblage, la partie de votre script source que vous souhaitez voir assemblée. Cela peut être utile si, par exemple, vous voulez constituer différentes versions de votre programme à partir d'un même script source.

Dans ce domaine, GoAsm utilise simplement la syntaxe du langage C qui est basée sur les directives #if, #ifdef, #else, #elif (ou #elseif) et #endif. La syntaxe de la structure de base d'une directive conditionnelle dans sa forme la plus simple est la suivante :

#if condition 
  text A 
#endif

Ici, si la condition est VRAIE, le texte A sera assemblé. A contrario, si la condition est FAUSSE, l'assembleur ignorera le texte A et poursuivra la compilation à partir de #endif.

Vous pouvez ajouter quelque chose à faire si la condition est FAUSSE de cette manière :

#if condition 
  text A 
#else 
  text B 
#endif

Ici, si la condition est VRAIE, texte A sera assemblé, mais pas texte B.

A contrario, si la condition est FAUSSE, texte A sera ignoré et seul texte B sera assemblé.

Le #endif indique la fin de la trame conditionnelle, de sorte que tout le texte au-delà sera assemblé normalement.

La déclaration #else doit toujours précéder #endif.

Vous pouvez ajouter une condition supplémentaire à la structure :

#if condition1 
  text A 
#elif condition2 
  text B 
#endif

Ici, si condition1 est VRAIE, texte A sera assemblé, texte B sera ignoré et l'assemblage se poursuivra à partir du #endif. Toutefois, si condition1 est FAUSSE, texte A ignoré jusqu'à #elif précédant le test de condition2. Si donc condition2 est VRAIE, texte B sera assemblé.

Notez, au passage, que « #elif » est identique à « #elseif ».

L'ajout du #else à la trame conditionnelle ci-dessus produit :

#if condition1 
  text A 
#elif condition2 
  text B 
#else 
  text C 
#endif

Ici, si condition1 est VRAIE, texte A sera assemblé tandis que texte B et texte C seront ignorés et l'assemblage se poursuivra à partir du #endif. Toutefois, si condition1 est FAUSSE, texte A sera ignoré jusqu'à #elif testant condition2. Si donc condition2 est VRAIE, texte B sera assemblé et texte C ignoré ; si, toutefois condition2 est FAUSSE, texte B sera ignoré jusqu'au #else qui fera que texte C sera assemblé.

Vous pouvez avoir autant de #elif (ou #elseif) que vous le souhaitez dans chaque trame conditionnelle, mais il ne peut y avoir qu'un #else par trame, et chaque #if doit avoir un #endif correspondant. Certains programmeurs imbriquent les trames conditionnelles, mais cela peut devenir très confus et ne peut constituer une bonne pratique de programmation. Si toutefois ce choix est retenu, il est recommandé que vous étiquetiez chaque #endif avec un commentaire de sorte que vous puissiez voir à quel #if il se réfère.

#ifdef identifier

où identifier est un mot qui peut être défini dans le script source ou dans un fichier d'inclusion. Cette déclaration renvoie VRAI si identifier est défini et FAUX dans le cas contraire. identifier doit être un mot et pas un nombre, ni une chaîne entre guillemets.

#ifndef identifier

comme ci-dessus, mais cette déclaration retourne FAUX si identifier est défini et VRAI s'il n'est pas défini.

#if expression

où expression peut être un nombre, la déclaration retournant alors FAUX pour 0, et VRAI pour les valeurs non nulles.

où expression peut être un identifier qui évalue un nombre.

où expression peut être l'opérateur défini utilisé comme suit :

defined identifier
defined(identifier)

qui renvoie VRAI (1) si l'identifiant est défini, et FAUX (0) s'il n'est pas défini, de manière similaire à #ifdef.

L'opérateur ! (point d'exclamation) peut être utilisé devant ces expressions simples pour inverser le résultat de la condition, de sorte que par exemple :

#if !0 retournerait VRAI, et

#if !defined identifier retournerait FAUX (0) si identifier était défini, et VRAI (1) dans le cas contraire, de manière similaire à #ifndef.

où expression peut être plus complexe et revêtir la forme :

identifier opérateur-relationnel value

identifier doit être un mot défini ailleurs dans le fichier, dans un fichier inclus ou dans la ligne de commande. Il ne peut pas être un nombre.

L'opérateur relationnel peut être l'un des éléments suivants :

value peut être un nombre ou un mot qui est défini ailleurs dans le fichier, dans un fichier inclus ou dans la ligne de commande, qui évalue un nombre.

où expression peut être plus complexe, combinant plusieurs expressions avec l'opérateur AND conditionnel && ou l'opérateur conditionnel OR ||:

expression1 && expression2
expression1 || expression2

où expression1 et expression2 sont l'un des types d'expressions précédents.

L'instruction && renvoie VRAI si expression1 et expression2 sont VRAIES.

Si expression1 est fausse, alors expression2 est pas évaluée.

L'instruction || renvoie VRAI si expression1 ou expression2 est VRAIE.

Si expression1 est VRAIE, alors expression2 n'est pas évaluée.

Notez que, pour les expressions multiples avec plusieurs opérateurs conditionnels, l'évaluation de la déclaration est effectuée avec un traitement simple de gauche à droite. Normalement && a préséance sur ||. Donc si vous placez ces expressions conditionnelles avec && en premier, vous devez obtenir des résultats similaires.

#define HELLO
;
#ifdef HELLO
	BSWAP	EAX	; inverse l'ordre des octets dans EAX si HELLO est défini
#endif
#if HELLO==3
OUTPUT	DD	3h	; si HELLO est défini comme 3, déclarer le label de donnée OUTPUT à 3
#elif WINVER>=400h
OUTPUT	DD	4h	; donnée alternative data si WINVER est égal ou plus grand que 400h
#else
OUTPUT	DD	5h	; donnée alternative si aucun des cas ci-dessus n'est avéré
#endif

Vous pouvez définir un mot dans la ligne de commande permettant de déclencher la prise en compte des bonnes parties de votre script source pour l'assemblage. Par exemple :

GoASM /l /d WINVER=401h MyProg.ASM

ou simplement

GoASM /l /d VERSIONA MyProg.ASM

signifie que le mot VERSIONA sera défini et qu'il pourra être testé par #ifdef.

Voir également :

• assemblage conditionnel dans les macros
• assemblage conditionnel dans les structures

#include path\filename

path\filename peut être, soit :

• une chaîne entre guillemets ;
• une chaîne sans guillemets ;
• une chaîne de caractères encadrée par les symboles « < » et « > ».

GoAsm va chercher le fichier en utilisant le chemin d'accès spécifié. Si aucun chemin n'est spécifié, il va le chercher dans le répertoire courant. Si le fichier reste malgré tout introuvable, il va le chercher dans le répertoire fourni par la chaîne d'environnement INCLUDE. Vous pouvez paramétrer la chaîne d'environnement INCLUDE en utilisant la commande DOS SET dans la fenêtre MS-DOS (invite de commande), ou en appelant l'API SetEnvironmentVariable. Vous pouvez également utiliser le panneau de configuration (paramètres système avancés, variables d'environnement) si votre système d'exploitation le permet, le tout suivi d'un redémarrage.

Il peut y avoir une chaîne d'environnement différente pour chaque répertoire ou sous-répertoire. Assurez-vous que la chaîne d'environnement que vous souhaitez utiliser est dans le répertoire courant.

Vous pouvez imbriquer des #include file mais il est de bonne pratique d'éviter cela autant que possible.

INCBIN vous permet de charger des morceaux de matériau à partir d'un fichier directement dans une section de données ou de code sans autre traitement. Vous pouvez choisir le nombre d'octets à sauter dès le début du fichier et/ou la quantité à charger à partir du fichier. Voici des exemples de la façon d'utiliser INCBIN :

DATA		SECTION
BULKDATA	INCBIN	MyFile.txt		; charge l'ensemble de MyFile.txt dans la section de
						; données avec le label BULKDATA 
		INCBIN	MyFile.txt, 100		; évite les 100 premiers octets mais charge le reste du fichier
		INCBIN	MyFile.txt, 100, 300	; évite les 100 premiers octets mais charge 300 octets

Voir également la section insertion de blocs de données.

Les bibliothèques de code statiques sont des fichiers avec l'extension « .lib » contenant un ou plusieurs fichiers objet COFF. Ces fichiers objet contiennent du code et des données relatifs à des fonctions prêtes à l'emploi. Le matériau à l'intérieur du fichier de bibliothèque est au format binaire (code machine), et non du code source. Les fichiers de bibliothèque contiennent un index avec une liste des fonctions et les labels de code et de données qu'ils utilisent. Les bibliothèques de code statiques doivent être distinguées des bibliothèques liées dynamiquement (DLL) et de bibliothèques d'importation qui contiennent simplement une liste des fonctions exportées par DLL.

Dans GoAsm, vous pouvez utiliser du code et des données prêts à l'emploi dans des bibliothèques de code statiques simplement en appelant la fonction requise dans votre script source, en mentionnant le nom de la bibliothèque contenant cette fonction. Par exemple :

CALL	zlibstat.lib:compress

Vous pouvez également utiliser des equates pour simplifier le libellé du CALL, par exemple :

LIB1=c:\prog\libs\zlibstat.lib
CALL	LIB1:compress

En utilisant INVOKE, ces exemples deviennent :

INVOKE	zlibstat.lib:compress, [pCompHeap], ADDR ComprSize, [pHeap], [DataSize]
INVOKE	LIB1:compress, [pCompHeap], ADDR ComprSize, [pHeap], [DataSize]

Si votre chemin d'accès contient des espaces, vous devez mettre le chemin d'accès et le nom de fichier entre guillemets.

Le codage qui précède enjoint à GoAsm de charger le code et les données associés et de les fusionner avec le fichier de sortie de GoAsm (fichier objet) lors de l'assemblage. Vous pouvez ensuite envoyer le fichier de sortie au linker de la manière habituelle, mais l'éditeur de liens n'est pas concerné du tout par le code et les données source (le fichier de bibliothèque) : l'ensemble du code et des données associées à la fonction ont déjà été chargés par GoAsm. Le seul travail supplémentaire que vous pourriez avoir besoin de faire au moment de la phase d'édition de liens est de veiller à ce que le linker soit informé de toutes les DLL supplémentaires nécessitées par les fonctions prêtes à l'emploi. Par exemple, une fonction prête à l'emploi peut appeler une API Windows dans OLEAUT32.dll. Afin d'éviter une erreur de « symbole introuvable », il est indispensable de mentionner cette DLL dans la ligne de commande de GoLink. Si vous utilisez un autre éditeur de liens, vous devez ajouter la bibliothèque d'importation pour OLEAUT32.dll à la liste des bibliothèques d'importation donnée à l'éditeur de liens.

La méthode de GoAsm concernant l'utilisation de bibliothèques de code statiques diffère très sensiblement de celle utilisée par les outils Microsoft. Le MS Linker ajoute le code et les données au moment de l'édition des liens. Si vous préférez, vous pouvez toujours utiliser cette méthode avec GoAsm. Pour ce faire vous devez charger les fichiers de sortie de GoAsm dans MS Link et demander à ce dernier de rechercher les fonctions dans la bibliothèque de code statique appropriée.

Voir la section utilisation de GoAsm avec différents linkers.

Si le chemin d'accès du fichier .lib n'est pas donné dans l'appel, GoAsm conduira ses recherches dans le répertoire courant et dans celui donné dans l'environnement LIB. Vous pouvez paramétrer la chaîne d'environnement LIB à l'aide de la commande DOS SET dans la fenêtre MS-DOS (invite de commande), en appelant l'API SetEnvironmentVariable ou en utilisant le panneau de configuration (paramètres système avancés, variables d'environnement) si votre système d'exploitation le permet, le tout suivi d'un redémarrage.

Il peut y avoir une chaîne d'environnement différente pour chaque répertoire ou sous-répertoire. Assurez-vous que la chaîne d'environnement que vous souhaitez utiliser est dans le répertoire courant.

Vous avez besoin de spécifier une seule fois le chemin d'accès du fichier lib dans votre script source (dans un appel à un fichier lib) et GoAsm l'utilisera automatiquement pour tous les fichiers lib spécifiés du même nom.

Vous pouvez effectuer un saut vers une fonction de la manière suivante :

JMP	MyLib.lib:MainProc

Cette méthode peut être employée si, par exemple, le code de la bibliothèque contient un call à l'API ExitProcess pour mettre fin au programme.

Il est très utile de pouvoir identifier les fonctions disponibles dans les bibliothèques de code statiques. Il existe un certain nombre d'outils disponibles à cet effet, mais l'un des plus utiles est PEView de Wayne J. Radburn, qui vous permet de visualiser le contenu de différents fichiers y compris les fichiers lib. Vous pouvez voir à partir de cet outil que les membres individuels des bibliothèques de code statiques sont toujours des fichiers « .obj », mais que les membres individuels de bibliothèques importées sont toujours des fichiers « .dll ».

DUMPBIN est un utilitaire Microsoft qui est généralement associé à MASM et aux compilateurs C. La ligne de commande LINK -dump (utilisant donc l'éditeur de liens Microsoft) est fonctionnellement identique et fournit une liste d'options si elle est utilisée sans autres paramètres également. Il existe diverses options, mais par exemple,

DUMPBIN /LINKER MEMBER: 1 MYLIB.LIB> MyLib.dmp

donnera (dans le fichier MyLib.dmp) des informations sur le premier membre du fichier de bibliothèque et DUMPBIN /ALL MyLib.lib donnera des informations sur tous les membres.

PEDUMP, enfin, est un utilitaire écrit par Matt Pietrek qui peut visualiser, octet par octet, le contenu d'un fichier PE (y compris un fichier lib) d'une manière ordonnée (voir également LIBDUMP du même auteur).

L'utilitaire Microsoft LIB.EXE, qui repose sur LINK.EXE et aussi MsPDB50.dll, permet d'élaborer des fichiers de bibliothèque de code statique. Supposons que vous ayez un fichier objet appelé calculate.obj qui contient une fonction que vous souhaitez réutiliser. Il vous est possible d'en faire une bibliothèque au moyen de la syntaxe de ligne de commande suivante, par exemple :

LIB calculate.obj

Vous obtiendrez ainsi calculate.lib. Et, pour ajouter un autre fichier objet à cette même bibliothèque, vous pouvez procéder comme suit :

LIB calculate.lib added.obj

Cela va ajouter added.obj à la bibliothèque calculate.lib. Ceci est utile si vous voulez garder vos fonctions dans les bibliothèques, afin qu'elles puissent être réutilisées sans avoir à écrire à nouveau le code dans vos scripts source. Ces bibliothèques seront également utiles pour distribuer vos fonctions tout en conservant votre code source à votre seule discrétion. LIB.EXE et ses composants font partie des outils MSDN qui peuvent être téléchargés gratuitement à partir du site Microsoft MSDN (partie du SDK). Le téléchargement exact ne cesse de changer de sorte que des tâtonnements seront peut-être nécessaires pour obtenir ces fichiers. Il est fort probable également que LIB soit rangé du côté d'outils de compilation tels que VC++ ou MASM.

L'appel d'une fonction dans une bibliothèque de code statique agrandit le fichier de sortie GoAsm au prorata du code et des données associés de la fonction. Souvent, du reste, la fonction dépend elle-même d'autres fonctions au sein du même fichier de la bibliothèque, ce qui entraîne encore plus de code et de données à charger. Vous pouvez visualiser ce qui est chargé en utilisant le commutateur /l (édition d'un fichier listing) dans la ligne de commande de GoAsm et en examinant le fichier listing résultant. Malheureusement, certains code et données peuvent être chargés tout en n'étant pas effectivement utilisés. Vous pouvez néanmoins visualiser les labels de code et de données inutilisés à l'aide du commutateur /unused de GoLink.

Certaines fonctions de fichiers de bibliothèque s'attendent à trouver des labels spécifiques de code et de données à l'exécutable qui doivent donc impérativement faire partie de votre script source. Par exemple la procédure de callback RegisterDialogClasses et ses variables de données associées doivent être établies dans votre script source afin d'utiliser SCRNSAVE.LIB pour faire un économiseur d'écran.

Les bibliothèques sont destinées à donner accès à des fonctions au moment de la compilation plutôt que simplement des données. Toutefois, si vous voulez charger une bibliothèque particulière au moment de la compilation de sorte que vous puissiez accéder à ses données, vous pouvez appeler un label de code approprié dans un code inutilisé figurant dans votre script source (le label de code n'est jamais appelé). Par exemple :

CALCULATE1:
		; lignes de code ici
		RET
		CALL	Lib1:DUMMY	; garantit que Lib1 est chargé au moment de la compilation
CALCULATE2:
		; lignes de code ici
		RET

Si vous constituez vos propres fichiers lib, il vous sera utile de comprendre comment le code et les données de bibliothèque sont intégrés au code et aux données résultant du script source principal. Lors de l'utilisation des bibliothèques de code, il est courant de rencontrer des noms de labels identiques, et si cela se produit lors du chargement d'une bibliothèque, GoAsm utilise seulement l'information associée au tout premier label et ignore celle relative aux autres labels de même nom.

Supposons, par exemple, que vous ayez une zone de données appelé « BUFFER » déclarée soit dans le script source principal, soit dans la bibliothèque. Il peut y avoir plusieurs fonctions dans le script source principal ou dans les différents composants de bibliothèque ou même dans d'autres bibliothèques qui pourraient utiliser BUFFER.

Alors, où BUFFER devrait-il être déclaré et ce que se passerait-il s'il l'était plus d'une fois ? Une question similaire se pose avec les fonctions. Le code pour celles-ci peut être dans le script source principal ou dans une bibliothèque. Il peut être dupliqué en plusieurs endroits. La réponse à ces questions se trouve dans les règles de priorité.

Ces règles sont les suivantes :

1. Le script source principal GoAsm et tous fichiers inclus avec extension en « a » ont toujours la priorité. En d'autres termes, tout label de code ou déclaration des données dans les scripts trouveront toujours leur chemin dans le fichier de sortie GoAsm avec le code et les données auxquels ils apposent des labels ;
2. Sous réserve du 1 ci-dessus, les appels formels de la bibliothèque (utilisant le format library:functionname) ont priorité dans l'ordre dans lequel ils sont appelés.

Ces règles signifient que les bibliothèques de code sont en mesure d'appeler des fonctions et d'utiliser les données dans les scripts source directement (sans aucune aide de l'éditeur de liens). Elles signifient également que tous les labels dans une bibliothèque qui a déjà été utilisée dans le script source ou dans une bibliothèque qui a déjà été appelée seront ignorés. Supposons par exemple que BUFFER soit déclaré dans le script source avec une taille de 256 octets. Si library1 le déclare à son tour à 128 octets, ce label est ignoré et BUFFER sera de 256 octets dans le fichier de sortie. Et de plus, bien que la zone de données réservée à BUFFER dans library1 soit chargée dans le fichier de sortie, le label BUFFER ne la pointera pas et s'en tiendra à la zone déclarée dans le script source. Maintenant, si un appel plus tard, Library2 déclare BUFFER à 1024 octets, encore une fois cette zone de données ira dans le fichier de sortie, mais BUFFER continuera à pointer la zone de données d'origine. La raison pour laquelle GoAsm traite ainsi les labels de même nom est double. Tout d'abord, il serait impossible pour un assembleur (ou un linker d'ailleurs) de déterminer quel label est prioritaire au vu de sa taille. En effet, dans GoAsm au moment de l'assemblage et, plus certainement, au moment de l'édition de liens, la taille d'une zone particulière pointée par un label n'est pas connue avec certitude. Ceci, parce que lesdites zones sont parfois agrandies par des zones de code et de données dépourvues de label, ou parfois d'autres labels sont utilisés comme pointeurs vers une position intermédiaire dans la zone.

Les règles ont aussi une signification vis-à-vis de l'ordre dans lequel sont disposées les données. Supposons que votre bibliothèque repose sur des données détenues dans un tampon et également sur des données débordant parfois dans une zone élargie nommée BUFFER_EXT et déclarée immédiatement après BUFFER dans la bibliothèque. Maintenant, dans l'exemple ci-dessus BUFFER ne pointerait pas en réalité vers l'endroit attendu (juste avant BUFFER_EXT). Au contraire, il pointerait vers la première déclaration de BUFFER ailleurs dans la section de données.

Au terme de cette réflexion, je suggèrerais donc que les règles suivantes soient respectées lors de la création de fichiers lib :

1. Utilisez uniquement des labels de même nom dans le script source et dans la bibliothèque si ces labels sont appelés à pointer vers la même chose au même endroit, à savoir, à la première déclarée en tant que label ;
2. Si des labels de donnée de même nom doivent être utilisés dans différentes fonctions dans le fichier lib, il faut savoir que la taille de la zone de données qu'ils identifient sera fixée par la première déclarée en tant que label. Aussi, ne vous attendez pas à ce que la zone de données que le label identifie soit placée dans une position particulière dans l'exécutable.

Actuellement, GoAsm ne supporte pas d'appeler les mêmes fonctions de la bibliothèque à partir de plus d'un module (script source). Si tel est le cas, vous verrez apparaître des erreurs « Duplication de symbole » en provenance de l'éditeur de liens. Pour contourner ce problème, vous devez concentrer tous les appels à la bibliothèque sur la même fonction dans une bibliothèque en un seul script source. Dans des versions ultérieures de GoAsm et de GoLink un support pourrait être ajouté pour les appels vers la même fonction de bibliothèque de plus d'un script source en cas d'utilité avérée pour les utilisateurs.