Definir un diseño de correlación

Este tema utiliza un ejemplo para describir la definición del diseño de una correlación.

Acerca de esta tarea

Crear el archivo XML de diseño

El formato del archivo XML se define en el archivo DTD (definición de tipo de documento) layout.dtd del siguiente modo:

<?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>

Esto significa que el archivo de diseño XML especifica primero una cabecera (title) y la longitud total del diseño, seguido de una lista de subelementos (FIELD) descritos por una cabecera (name), la longitud y el tipo primitivo que se utilizan para determinar la representación predeterminada de ese subelemento.

También hay tipos de subelementos especiales:

El ejemplo siguiente define el diseño de la siguiente estructura de lenguaje C:

typedef struct {
  unsigned short ushort_val;
  short short_val;
  unsigned long ulong_val;
  long long_val;
  char string_val[12];
  char char_val;
} _test;

El archivo XML que describe una vista de árbol de la estructura _test conforme a este formato es:

<?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>

Los atributos offset y offset_mode le permiten especificar la ubicación exacta de un campo en relación al inicio de la correlación (offset_mode=absolute) o en relación a la dirección actual (offset_mode=relative). En el ejemplo siguiente, el elemento llamado b tiene un offset de 10 y offset_mode se define como relative. Sin estos atributos, este elemento tendría un desplazamiento de 80, pero debido a que el desplazamiento se define como 10, en relación a la posición actual, el desplazamiento es 90. Observe que la longitud del elemento a se define en hexadecimal porque la longitud tiene el prefijo 0x. Generalmente, los atributos length y offset se pueden especificar en HEX con el prefijo 0x. El elemento c tiene un desplazamiento de 4 y la modalidad es absolute. Esto significa que el desplazamiento de este elemento es 4 bytes contados a partir del inicio del diseño. Los 10 bytes correlacionados por el campo c también los cubre el campo a:

<Header="offset_Test" length="190">
  <FIELD Header="a" Type="HEX" length="0x64"></FIELD>
  <FIELD Header="b" description="offset = 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>

Definir campos de relleno

El relleno de los campos se puede utilizar para tratar con estructuras alineadas de byte o para saltar áreas de datos en la correlación que no es necesario definir en la correlación de memoria. Por ejemplo, para la estructura _test definida más arriba, puede crear una correlación que ignora el campo long_val pero que muestra el tipo string_val en el diseño. El archivo XML tendría el aspecto siguiente:

<?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>

También podría utilizar aquí el atributo offset para omitir el campo long_val, especificando el offset de string_val como 4, y offset_mode como relative:

  <FIELD Header="string_val" Type="ASCII" length="12" offset="4" offset_mode="relative"></FIELD>

Esto significa que la dirección del campo string_val es realmente 4 bytes relativos último byte del campo ulong_val, saltándose así los bytes utilizados por el campo long_val.

Definir estructuras

El fragmento de XML que sigue muestra la utilización de campos STRUCTURE para correlacionar estructuras anidadas. Un elemento superior de estructura no tiene un valor asociado y puede expandirse para mostrar sus subelementos. Aunque la longitud del campo STRUCTURE se añade al tamaño total del diseño XML, los tamaños de los campos incluidos sólo están destinados a visualización. Por ejemplo, la estructura siguiente indica sólo 344 bytes del tamaño total del diseño.

<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>

Las estructuras pueden definirse interna o externamente para un diseño. Una estructura externa puede crearse como un diseño anidado especificando filename="<nombre de archivo>" en el campo de estructura, donde el archivo al que hace referencia <nombre de archivo> contiene la definición real de la estructura.

Por ejemplo, la estructura MACHINE CHECK LOG OUT AREA puede especificarse externamente en un diseño de correlación del siguiente modo: <FIELD Header="MACHINE CHECK LOG OUT AREA" Type="STRUCTURE" length="344" filename="machine.xml"></FIELD>.

Definir campos de máscaras de bits

El fragmento de XML que sigue es un ejemplo para describir campos BITMASK. La longitud de BITMASK se especifica en bytes y contiene un conjunto de campos BIT para los que la longitud se especifica en bits. El desplazamiento mostrado para los campos BIT es un desplazamiento de bits dentro del campo BITMASK. Aunque la longitud del campo de máscara de bits se añade al tamaño total del diseño XML, los tamaños de los campos BIT individuales sólo están destinados a visualización.

<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> 

Definir uniones

El ejemplo siguiente define el diseño de la siguiente unión de lenguaje C:

union my_union {
  int my_intVal;
  double my_doubleVal;
};

El siguiente ejemplo de XML muestra la forma en que se describe la unión. Observe que en el XML, la longitud de la unión es el tamaño de su campo más grande:

<LAYOUT Header="UNIONS" length="8">
  <FIELD Header="my_union" Type="UNION" length="8">
    <FIELD Header="my_intVal" Type="HEX" length="4" description="value within the union"></FIELD>
    <FIELD Header="my_doubleVal" Type="HEX" length="8"></FIELD>
  </FIELD>
</LAYOUT> 

Definir diseños anidados

Utilizando conjuntamente el tipo de campo MAP y campos de diseño opcionales, puede describir diseños anidados como en el siguiente ejemplo de diseño DSA:

<?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>

Este diseño XML de formato correcto se almacena en un archivo denominado DSA.XML. Dado que el usuario sabe que los campos 3 y 4 contienen punteros a estructuras DSA diferentes, añade dos definiciones de diseño anidadas.

Nota: La correlación de memoria real para ese diseño se ejecuta solamente cuando se expande el elemento de diseño por primera vez para evitar expansiones de diseño recursivas.

Definir grupos

Con la sintaxis de grupos, puede organizar los campos de los diseños de correlación en grupos para facilitar el trabajo con ellos. Para definir un grupo, debe colocar <GROUP Name="groupName"></GROUP> al principio del archivo de diseño. A continuación, debe indicar que el campo pertenece al grupo predefinido especificando: <FIELD Header="RESERVED" Type="HEX" length="12" Groups="groupName"></FIELD>.

Un campo puede pertenecer a varios grupos. Para definir varios grupos, especifíquelos en una lista delimitada por comas en el atributo Groups. Cada grupo del atributo Groups debe haberse definido en el diseño utilizando el código <GROUP>.

El nombre de grupo ALL corresponde a un grupo especial. Si especifica este nombre en un campo, éste pertenecerá a todos los grupos y será visible en todos ellos. El ejemplo de código que sigue contiene grupos:

<?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>

Definir grupos ORG

Puede utilizar el código ORG_GROUP para definir el diseño de un a parte de memoria definida anteriormente. Es similar al comportamiento de la instrucción ORG en ensamblador. Puede especificar la ubicación inicial del nuevo diseño utilizando el atributo FIELD. En el caso más sencillo, el valor del atributo FIELD puede ser el nombre de un campo de la correlación definido anteriormente. También puede utilizar *NONE o * como valores, lo que significa que el diseño es para la ubicación actual en memoria. El atributo Header es simplemente un nombre para el nuevo diseño.

<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="address of F == address of 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="address of J = current location + 4"></FIELD>
    </ORG_GROUP>
  </ORG_GROUP>
  <FIELD Header="R" length="4" Type="HEX"></FIELD>
  <FIELD Header="Z" length="4" Type="HEX"></FIELD>
</LAYOUT> 

donde:


Comentarios