Creating the layout XML file
The XML file format is defined in the layout.dtd document type definition (DTD) file as follows:
<?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>
This means that the XML layout file first specifies a header (title) and the total length of the layout followed by a list of sub-elements (FIELD) described by a header (name), length and primitive type which is used to determine the default representation of that sub-element.
There are also special sub-element types:
The following example defines the layout for the following C language structure:
typedef struct {
unsigned short ushort_val;
short short_val;
unsigned long ulong_val;
long long_val;
char string_val[12];
char char_val;
} _test;
The XML file describing a tree view of the _test structure and conforming to this format is:
<?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>
The offset and offset_mode attributes allow you to specify the exact location of a field either relative to the start of the map (offset_mode=absolute) or relative to the current address (offset_mode=relative). In the following example, the element named b has an offset of 10 and offset_mode defined as relative. Without these attributes, this element would have an offset of 80, but because the offset is defined as 10, relative to current position, the offset is 90. Note that the length of element a is defined in hexadecimal because the length is prefixed with 0x. Generally, the length and offset attributes can be specified in HEX by prefixing with 0x. Element c has an offset of 4 and the mode is absolute. This means that the offset of this element is 4 bytes away from the start of the layout. The 10 bytes mapped by field c are also covered by field 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>
Defining padding fields
Padding fields can be used to deal with byte aligned structures, or to skip data areas in the map that do not need to be defined in the memory map. For example, for the _test structure defined above, you could create a map that ignores the long_val field, but shows the string_val type in the layout. The XML file would look like this:
<?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>
You could also use the offset attribute here to skip the long_val field by specifying the offset of string_val as 4, and the offset_mode as relative:
<FIELD Header="string_val" Type="ASCII" length="12" offset="4" offset_mode="relative"></FIELD>
This means that the address of the string_val field is actually 4 bytes relative to the last byte of the ulong_val field, thus skipping the bytes used by the long_val field.
Defining structures
The following piece of XML shows the usage of STRUCTURE fields for mapping nested structures. A structure top element does not have an associated value and it can be expanded to show its sub-elements. While the length of the STRUCTURE field is added to the total size of the XML layout, the included field sizes are intended for display only. For example, the following structure means only 344 bytes out of the total layout size.
<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>
Structures can be defined internally or externally to a layout. An external structure can be created like a nested layout by specifying filename="<file name>" in the structure field, where the file referenced by <file name> contains the actual definition of the structure.
For example, the MACHINE CHECK LOG OUT AREA structure can be specified in a mapping layout externally as follows: <FIELD Header="MACHINE CHECK LOG OUT AREA" Type="STRUCTURE" length="344" filename="machine.xml"></FIELD>.
Defining bitmask fields
The following XML piece is a sample for describing BITMASK fields. The length of the BITMASK is specified in bytes and it contains a set of BIT fields for which the length is specified in bits. The offset shown for the BIT fields is a bit offset within the BITMASK field. While the length of the bitmask field is added to the total size of the XML layout, the individual BIT field sizes are intended for display only.
<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>
Defining unions
The following example defines the layout for the following C language union:
union my_union {
int my_intVal;
double my_doubleVal;
};
The sample XML below describes how to describe the union. Note that in the XML, the length of the union is the size of its largest field:
<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>
Defining nested layouts
With the MAP field type and optional layout field together, you can describe nested layouts as in the following DSA layout example:
<?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>
This well-formed XML layout is stored in a file called DSA.XML. Since you know that fields 3 and 4 contain pointers to different DSA structures you add two nested layout definitions.
Defining groups
With group syntax, you can organize fields in mapping layouts into groups so that they are easier to work with. To define a group, you need to place <GROUP Name="groupName"></GROUP> at the top of the layout file. You then indicate that the field belongs to the predefined group by specifying: <FIELD Header="RESERVED" Type="HEX" length="12" Groups="groupName"></FIELD>.
A field can belong to multiple groups. To define multiple groups, specify them in a comma-delimited list in the Groups attribute. Each group in the Groups attribute must have been defined in the layout using the <GROUP> tag.
The ALL group name is a special group. Specifying this in a field will cause it to belong to all groups and the field will be visible in all groups. The following code sample contains groups:
<?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>
Defining ORG groups
You can use the ORG_GROUP tag to define the layout of a previously-defined portion of memory. This is similar to the behavior of the ORG instruction in assembler. You can specify the start location of the new layout using the FIELD attribute. In the simple case, the value of the FIELD attribute can be the name of a previously-defined field in the map. You can also use *NONE or * as values, which mean that the layout is for the current location in memory. The Header attribute is simply a name for the new layout.
<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>
where: