Création du fichier XML de présentation
Le format du fichier XML est défini dans le fichier DTD (Document Type Definition) layout.dtd, comme suit :
<?xml version="1.0"?>
<!ELEMENT LAYOUT (FIELD)+>
<!ATTLIST LAYOUT Header CDATA #REQUIRED length CDATA #REQUIRED>
<!ELEMENT GROUP EMPTY>
<!ATTLIST GROUP Name CDATA #REQUIRED>
<!ELEMENT FIELD (FIELD)*>
<!ATTLIST FIELD
Header CDATA #REQUIRED
Type (16_BIT_INT|16_BIT_UINT|16_BIT_HINT|32_BIT_INT|32_BIT_UINT|32_BIT_HINT|32_BIT_FLOAT|64_BIT_INT|64_BIT_FLOAT|CHARACTER|HEX|ASCII|EBCDIC|STRUCTURE|PADDING|BIT|BITMASK|MAP) #REQUIRED
length CDATA #REQUIRED
layout CDATA #IMPLIED
filename CDATA #IMPLIED
Groups CDATA #IMPLIED>
Ainsi, le fichier de présentation XML définit tout d'abord un titre (Header) et la longueur totale de la présentation (length), suivis d'une liste de sous-éléments (FIELD), décrits chacun par un nom (Header), une longueur (length) et un type primitif (Type) utilisé pour déterminer la représentation par défaut de tel ou tel sous-élément.
Il existe également des types de sous-éléments spécifiques :
L'exemple suivant démontre comment définir la présentation de la structure de langage C suivante :
typedef struct {
unsigned short ushort_val;
short short_val;
unsigned long ulong_val;
long long_val;
char string_val[12];
char char_val;
} _test;
Le fichier XML suivant décrit une vue en arborescence de la structure _test en respectant ce format :
<?xml version="1.0"?>
<LAYOUT Header="A Layout" description="Tree view" length="25">
<FIELD Header="ushort_val" Type="16_BIT_UINT" length="2"></FIELD>
<FIELD Header="short_val" Type="16_BIT_INT" length="2"></FIELD>
<FIELD Header="ulong_val" Type="32_BIT_UINT" length="4"></FIELD>
<FIELD Header="long_val" Type="32_BIT_INT" length="4"></FIELD>
<FIELD Header="string_val" Type="ASCII" length="12"></FIELD>
<FIELD Header="char_val" Type="ASCII" length="1"></FIELD>
</LAYOUT>
Les attributs offset et offset_mode permettent de spécifier la position exacte d'une zone soit par rapport au début de la mappe (offset_mode=absolute), soit par rapport à l'adresse en cours (offset_mode=relative). Dans l'exemple suivant, l'élément nommé b a un attribut offset de 10 et son mode est relatif (offset_mode=relative). Sans ces attributs, l'élément aurait un décalage de 80, mais comme son attribut offset est défini à 10 et qu'il s'agit d'un décalage relatif (par rapport à la position en cours), son décalage est de 90. Notez aussi que la longueur de l'élément a est définie en hexadécimal, car la valeur de l'attribut length est préfixée avec 0x. Généralement, les attributs length et offset peuvent être spécifiés en hexadécimal par l'ajout du préfixe 0x. L'élément c a un attribut offset de 4 et son mode est absolute. Cela signifie que cet élément est positionné à quatre octets du début de la présentation (layout). Les dix octets mappés par la zone c sont également couverts par la zone a :
<Header="offset_Test" length="190">
<FIELD Header="a" Type="HEX" length="0x64"></FIELD>
<FIELD Header="b" description="décalage = 90" Type="HEX" length="80" offset="10" offset_mode="relative"></FIELD>
<FIELD Header="c" Type="HEX" length="10" offset="4" offset_mode="absolute"></FIELD>
</LAYOUT>
Définition de zones de remplissage
Les zones de remplissage peuvent servir à traiter des structures alignées par octet ou à sauter des zones de données de la mappe qui n'ont pas besoin d'être définies dans la mappe mémoire. Par exemple, pour la structure _test définie plus haut, vous pourriez créer une mappe qui ignore la zone long_val mais affiche le type string_val dans la présentation. Le fichier XML ressemblerait à ceci :
<?xml version="1.0"?>
<LAYOUT Header="A Layout" description="Tree view" length="0x19">
<FIELD Header="ushort_val" Type="16_BIT_UINT" length="2"></FIELD>
<FIELD Header="short_val" Type="16_BIT_INT" length="2"></FIELD>
<FIELD Header="ulong_val" Type="32_BIT_UINT" length="4"></FIELD>
<FIELD Header="" Type="PADDING" length="4"></FIELD>
<FIELD Header="string_val" Type="ASCII" length="12"></FIELD>
<FIELD Header="char_val" Type="ASCII" length="1"></FIELD>
</LAYOUT>
Ici, vous pourriez aussi utiliser l'attribut offset pour sauter la zone long_val en spécifiant 4 pour l'attribut offset de string_val et relative pour son attribut offset_mode :
<FIELD Header="string_val" Type="ASCII" length="12" offset="4" offset_mode="relative"></FIELD>
Cela signifie que l'adresse de la zone string_val est en fait à 4 octets du dernier octet de la zone ulong_val, ce qui saute les octets utilisés par la zone long_val.
Définition de structures
Le fragment XML suivant illustre l'utilisation des zones STRUCTURE pour mapper des structures imbriquées. L'élément principal d'une structure n'a aucune valeur associée et peut être développé pour que ses sous-éléments soient affichés. Contrairement à la longueur attribuée à la zone STRUCTURE qui s'ajoute à la taille totale de la présentation XML, les tailles des zones incluses ne sont données que pour l'affichage. Par exemple, la structure suivante ne représente que 344 octets de la taille totale de la présentation.
<FIELD Header="MACHINE CHECK LOG OUT AREA" Type="STRUCTURE" length="344">
<FIELD Header="reserved" Type="HEX" length="16"></FIELD>
<FIELD Header="FLCSID" Type="HEX" length="4"></FIELD>
<FIELD Header="FLCIOFP" Type="HEX" length="4"></FIELD>
<FIELD Header="reserved" Type="HEX" length="20"></FIELD>
<FIELD Header="FLCESAR" Type="HEX" length="4"></FIELD>
<FIELD Header="FLCCTSA" Type="HEX" length="8"></FIELD>
<FIELD Header="FLCCCSA" Type="HEX" length="8"></FIELD>
<FIELD Header="FLCMCIC" Type="HEX" length="8"></FIELD>
<FIELD Header="reserved" Type="HEX" length="8"></FIELD>
<FIELD Header="FLCFSA" Type="HEX" length="4"></FIELD>
<FIELD Header="reserved" Type="HEX" length="4"></FIELD>
<FIELD Header="FLCFLA" Type="HEX" length="16"></FIELD>
<FIELD Header="FLCRV110" Type="HEX" length="16"></FIELD>
<FIELD Header="FLCARSAV" Type="STRUCTURE"length="64">
<FIELD Header="AR0" Type="HEX" length="4"></FIELD>
<FIELD Header="AR1" Type="HEX" length="4"></FIELD>
<FIELD Header="AR2" Type="HEX" length="4"></FIELD>
<FIELD Header="AR3" Type="HEX" length="4"></FIELD>
<FIELD Header="AR4" Type="HEX" length="4"></FIELD>
<FIELD Header="AR5" Type="HEX" length="4"></FIELD>
<FIELD Header="AR6" Type="HEX" length="4"></FIELD>
<FIELD Header="AR7" Type="HEX" length="4"></FIELD>
<FIELD Header="AR8" Type="HEX" length="4"></FIELD>
<FIELD Header="AR9" Type="HEX" length="4"></FIELD>
<FIELD Header="AR10" Type="HEX" length="4"></FIELD>
<FIELD Header="AR11" Type="HEX" length="4"></FIELD>
<FIELD Header="AR12" Type="HEX" length="4"></FIELD>
<FIELD Header="AR13" Type="HEX" length="4"></FIELD>
<FIELD Header="AR14" Type="HEX" length="4"></FIELD>
<FIELD Header="AR15" Type="HEX" length="4"></FIELD>
</FIELD>
<FIELD Header="FLCFPSAV" Type="HEX" length="32"></FIELD>
<FIELD Header="" Type="PADDING" length="64"></FIELD>
<FIELD Header="" Type="PADDING" length="64"></FIELD>
</FIELD>
Les structures peuvent être définies à l'intérieur ou à l'extérieur de la présentation. Vous pouvez créer une structure externe comme une présentation imbriquée si vous spécifiez filename="<nomfichier>" dans la structure, où le fichier désigné par <nomfichier> contient la définition proprement dite de la structure.
Par exemple, la structure MACHINE CHECK LOG OUT AREA peut être définie à l'extérieur de la présentation de mappages, comme suit : <FIELD Header = "MACHINE CHECK LOG OUT AREA" Type = "STRUCTURE" length="344" filename="machine.xml"></FIELD>.
Définition de zones de masques de contrôle
Le modèle de fragment XML suivant décrit les zones BITMASK. La longueur du masque de contrôle (BITMASK) est donnée en octets. Il contient plusieurs zones BIT dont la longueur est donnée en bits. Le décalage en regard des zones BIT correspond à un décalage d'un bit dans la zone BITMASK. Contrairement à la longueur attribuée à la zone bitmask qui s'ajoute à la taille totale de la présentation XML, la taille de chaque zone BIT n'est donnée que pour l'affichage.
<FIELD Header="BITMASK" Type="BITMASK" length="1">
<FIELD Header="BIT 1" Type="BIT" length="1"></FIELD>
<FIELD Header="BIT 2" Type="BIT" length="1"></FIELD>
<FIELD Header="BIT 3" Type="BIT" length="1"></FIELD>
<FIELD Header="BIT 4" Type="BIT" length="1"></FIELD>
<FIELD Header="BIT 5" Type="BIT" length="1"></FIELD>
<FIELD Header="BIT 6" Type="BIT" length="1"></FIELD>
<FIELD Header="BIT 7" Type="BIT" length="1"></FIELD>
<FIELD Header="BIT 8" Type="BIT" length="1"></FIELD>
</FIELD>
Définition d'unions
L'exemple ci-après définit la présentation de l'union C suivante :
union my_union {
int my_intVal;
double my_doubleVal;
};
L'exemple de code XML ci-après montre comment décrire l'union. Notez que dans ce code, la longueur de l'union est la taille de la plus grande de ses zones :
<LAYOUT Header="UNIONS" length="8">
<FIELD Header="my_union" Type="UNION" length="8">
<FIELD Header="my_intVal" Type="HEX" length="4" description="valeur dans l'union"></FIELD>
<FIELD Header="my_doubleVal" Type="HEX" length="8"></FIELD>
</FIELD>
</LAYOUT>
Définition de présentations imbriquées
A l'aide du type de zone MAP et d'une zone de présentation en option, vous pouvez décrire des présentations imbriquées, comme dans l'exemple de présentation DSA suivant :
<?xml version="1.0"?>
<!DOCTYPE LAYOUT SYSTEM "Layout.dtd" >
<LAYOUT Header = "DSA" length="72">
<FIELD Header="FLAGS" Type="HEX" length="2"></FIELD>
<FIELD Header="junk" Type="HEX" length="2"></FIELD>
<FIELD Header="Back Chain" Type="MAP" length="4" layout="dsa.xml"></FIELD>
<FIELD Header="Forward Chain" Type="MAP" length="4" layout="dsa.xml"></FIELD>
<FIELD Header="R14" Type="HEX" length="4"></FIELD>
<FIELD Header="R15" Type="HEX" length="4"></FIELD>
<FIELD Header="R0" Type="HEX" length="4"></FIELD>
<FIELD Header="R1" Type="HEX" length="4"></FIELD>
<FIELD Header="R2" Type="HEX" length="4"></FIELD>
<FIELD Header="R3" Type="HEX" length="4"></FIELD>
<FIELD Header="R4" Type="HEX" length="4"></FIELD>
<FIELD Header="R5" Type="HEX" length="4"></FIELD>
<FIELD Header="R6" Type="HEX" length="4"></FIELD>
<FIELD Header="R7" Type="HEX" length="4"></FIELD>
<FIELD Header="R8" Type="HEX" length="4"></FIELD>
<FIELD Header="R9" Type="HEX" length="4"></FIELD>
<FIELD Header="R10" Type="HEX" length="4"></FIELD>
<FIELD Header="R11" Type="HEX" length="4"></FIELD>
<FIELD Header="R12" Type="HEX" length="4"></FIELD>
</LAYOUT>
Cette présentation XML syntaxiquement correcte réside dans le fichier nommé DSA.XML. Les zones 3 et 4 pointent vers des structures DSA différentes. Vous devez donc ajouter deux définitions de présentation imbriquée supplémentaires.
Définition de groupes
Grâce à la syntaxe par groupes, vous pouvez regrouper les zones des présentations de la mappe pour qu'elles soient plus faciles à utiliser. Pour définir un groupe, vous devez indiquer la ligne <GROUP Name = "groupName" ></GROUP> au tout début du fichier de présentation. Vous devez ensuite indiquer que la zone appartient au groupe prédéfini en indiquant : <FIELD Header="RESERVED" Type="HEX" length="12" Groups="groupName"></FIELD>.
Une zone peut appartenir à plusieurs groupes. Pour définir plusieurs groupes, répertoriez-les en les séparant par des virgules dans l'attribut Groups. Chaque groupe listé dans l'attribut Groups doit avoir été défini antérieurement dans la présentation au moyen de la balise <GROUP>.
Le nom de groupe ALL est particulier. Si vous l'indiquez dans une zone, celle-ci appartiendra à tous les groupes et sera visible dans tous les groupes. Le modèle de code suivant contient des groupes :
<?xml version="1.0"?>
<!DOCTYPE LAYOUT SYSTEM "Layout.dtd" >
<LAYOUT Header="GROUP_EXAMPLE" length="32">
<GROUP Name="GroupA"></GROUP>
<GROUP Name="GroupB"></GROUP>
<FIELD Header="FIELD_A" Type="HEX" length="8" Groups="GroupA"></FIELD>
<FIELD Header="FIELD_B" Type="HEX" length="8" Groups="GroupB"></FIELD>
<FIELD Header="FIELD_AB" Type="HEX" length="8" Groups="GroupA,GroupB"></FIELD>
<FIELD Header="FIELD_ALL" Type="HEX" length="8" Groups="ALL"></FIELD>
</LAYOUT>
Définition de groupes ORG
Vous pouvez utiliser la balise ORG_GROUP pour définir la présentation d'un portion de mémoire précédemment définie. Son comportement est similaire à celui de l'instruction ORG en assembleur. Vous pouvez spécifier la position de début de la nouvelle présentation en utilisant l'attribut FIELD. Dans le cas le plus simple, la valeur de l'attribut FIELD peut être le nom d'une zone précédemment définie dans la mappe. Vous pouvez aussi utiliser la valeur *NONE ou *, ce qui signifie que la présentation s'applique à l'emplacement en cours dans la mémoire. L'attribut Header est simplement un nom pour la nouvelle présentation.
<LAYOUT Header="SW00SR" length="271">
<ORG_GROUP FIELD="*NONE" Header="ORG_GROUP1">
<FIELD Header="A" length="4" Type="HEX"></FIELD>
<FIELD Header="B" length="4" Type="HEX"></FIELD>
<FIELD Header="c" length="4" Type="HEX"></FIELD>
</ORG_GROUP>
<ORG_GROUP FIELD="A" Header="my_custom_header">
<FIELD Header="F" length="4" Type="HEX" description="adresse de F == adresse de A"></FIELD>
<FIELD Header="G" length="4" Type="HEX"></FIELD>
<FIELD Header="H" length="4" Type="HEX"></FIELD>
<ORG_GROUP FIELD="*+4" Header="another_org">
<FIELD Header="J" length="2" Type="HEX" description="adresse de J = emplacement en cours + 4"></FIELD>
</ORG_GROUP>
</ORG_GROUP>
<FIELD Header="R" length="4" Type="HEX"></FIELD>
<FIELD Header="Z" length="4" Type="HEX"></FIELD>
</LAYOUT>
où :