A Sample XML File. freescale IDE 5.7

Register Details Window XML Specification

A Sample XML File

Metrowerks CodeWarrior:CodeWarrior Plugins:Support:Registers

IDE plugins can provide access paths to the IDE to better control the placement of XML files within the Registers folder. For example, you can create sub-folders within the

Registers

folder for specific processors or processor variations and use the plugin access paths to search those sub-folders. These access paths are relative to the

Registers

folder.

The IDE looks up system registers by name. Memory-mapped registers can have any name, since that name is used for display purposes only.

A Sample XML File

This section provides examples of creating XML file for use with the Register Details window.

•

Creating the New XML File

•

Adding Multiple BITFIELD Attributes

•

Adding BFVALUE Attributes

•

Completing the New XML File

Creating the New XML File

When you create a new file, you usually follow these high-level steps:

1. Locate a base XML file.

Instead of creating a completely new XML file, you can adapt an existing XML file for use with the register you wish to document. For example, you can locate a simple, generic XML file and modify it to describe more sophisticated registers.

Listing 30.2

shows a sample base XML file that you can easily adapt to explain complex registers. Note that this generic base file lacks multiple bitfield attributes, conditional expressions, or individual bitfield value attributes.

Listing 30.2 Sample Base XML File

<REGISTER NAME="BAR"

BITRANGE="0:31"

DESCRIPTION="Breakpoint Address Register">

<BITFIELD BITRANGE="0:31"

DESCRIPTION="The address of the load/store cycle that generates the breakpoint.">

</BITFIELD>

462 IDE 5.7 User’s Guide

Register Details Window XML Specification

A Sample XML File

</REGISTER>

2. Save the base XML file under a new name.

Use CodeWarrior to save a copy of the base XML file under a new name, and work with this newly named file for the remainder of the process. This step prevents you from accidentally modifying the original XML file.

3. Modify the base XML file to suit your needs.

After opening your copy of the base XML file, you can adapt the file to accurately document complicated register properties. For example, you can add multiple

BITFIELD

attributes, BFVALUE attributes, and conditional expressions to the base

XML file. The resulting file accurately and thoroughly describes the register. Such a file appears in

Listing 30.5

.

Adding Multiple BITFIELD Attributes

Multiple BITFIELD attributes divide the register into smaller ranges of bits, or

“bitfields.” Such bitfields can have various meanings depending on the register. For example, one bitfield of a register could refer to condition flag information, while another bitfield in the same register could refer to current state information.

Suppose you wish to document a “Memory Controller Base 2” register that contains twelve bitfields. Each bitfield has its own name and description.

Using the sample base XML file of

Listing 30.2

, you could begin adapting the file to your needs by adding eleven additional BITFIELD elements. Following the element formats

described in the Register Details Window XML Specification

, your first revision of the

base file might appear as shown in Listing 30.3

.

Listing 30.3 First Revision of Base XML File

<REGISTER NAME="BR2"

BITRANGE="0:31"

DESCRIPTION="Memory Controller Base Register 2.">

<BITFIELD BITRANGE="0:16"

NAME="BA"

DESCRIPTION="Place the BA bitfield description here.">

</BITFIELD>

<BITFIELD BITRANGE="17:19"

NAME="AT"

DESCRIPTION="Place the AT bitfield desciption here.">

</BITFIELD>

IDE 5.7 User’s Guide 463

Register Details Window XML Specification

A Sample XML File

<BITFIELD BITRANGE="20:21"

NAME="PS"

DESCRIPTION="Place the PS bitfield desciption here.">

</BITFIELD>

<BITFIELD BITRANGE="22"

NAME="-"

DESCRIPTION="Make a note that this bitfield is reserved.">

</BITFIELD>

<BITFIELD BITRANGE="23"

NAME="WP"

DESCRIPTION="Place the AT bitfield desciption here.">

</BITFIELD>

<BITFIELD BITRANGE="24:25"

NAME="-"

DESCRIPTION="Make a note that this bitfield is reserved.">

</BITFIELD>

<BITFIELD BITRANGE="26"

NAME="WEBS"

DESCRIPTION="Place the WEBS bitfield desciption here.">

</BITFIELD>

<BITFIELD BITRANGE="27"

NAME="TBDIP"

DESCRIPTION="Place the TBDIP bitfield desciption here.">

</BITFIELD>

<BITFIELD BITRANGE="28"

NAME="LBDIP"

DESCRIPTION="Place the LBDIP bitfield desciption here.">

</BITFIELD>

<BITFIELD BITRANGE="29"

NAME="SETA"

DESCRIPTION="Place the SETA bitfield desciption here.">

</BITFIELD>

<

<BITFIELD BITRANGE="30"

NAME="BI"

DESCRIPTION="Place the BI bitfield desciption here.">

</BITFIELD>

<BITFIELD BITRANGE="31"

NAME="V"

464 IDE 5.7 User’s Guide

Register Details Window XML Specification

A Sample XML File

DESCRIPTION="Place the V bitfield desciption here.">

</BITFIELD>

/REGISTER>

Adding BFVALUE Attributes

The values in an individual bitfield can describe different things about a register. For example, a bitfield value of 00 might indicate that a certain process is used, while a bitfield value of 01 might indicate that the same process is not used.

To cater your descriptions to accurately reflect such changes in behavior, you can use multiple BFVALUE attributes within a BITFIELD element. Each BFVALUE provides a specific description based on the bitfield value. CodeWarrior determines the applicable description to display in the Register Details window.

Using the example discussed in previous sections, assume that six of the bitfields in the

“Memory Controller Base Register 2” could benefit from the use of BFVALUE attributes.

Following the element formats described in the Register Details Window XML

Specification , your second revision of the base file might resemble

Listing 30.4

.

Listing 30.4 Second Revision of XML Base File

<REGISTER NAME="BR2"

BITRANGE="0:31"

DESCRIPTION="Memory Controller Base Register 2.">

<BITFIELD BITRANGE="0:16"

NAME="BA"

DESCRIPTION="Place the BA bitfield description here.">

</BITFIELD>

<BITFIELD BITRANGE="17:19"

NAME="AT"

DESCRIPTION="Place the AT bitfield desciption here.">

</BITFIELD>

<BITFIELD BITRANGE="20:21"

NAME="PS"

DESCRIPTION="Place the PS bitfield desciption here.">

<BFVALUE VALUE="00" DESCRIPTION="Place the description of the bitfield value of 00 here." />

<BFVALUE VALUE="01" DESCRIPTION="Place the description of the bitfield value of 01 here." />

IDE 5.7 User’s Guide 465

Register Details Window XML Specification

A Sample XML File

<BFVALUE VALUE="10" DESCRIPTION="Place the description of the bitfield value of 10 here." />

<BFVALUE VALUE="11" DESCRIPTION="Place the description of the bitfield value of 11 here." />

</BITFIELD>

<BITFIELD BITRANGE="22"

NAME="-"

DESCRIPTION="Make a note that this bitfield is reserved.">

</BITFIELD>

<BITFIELD BITRANGE="23"

NAME="WP"

DESCRIPTION="Place the AT bitfield desciption here.">

<BFVALUE VALUE="0" DESCRIPTION="Place the description of the bitfield value of 0 here." />

<BFVALUE VALUE="1" DESCRIPTION="Place the description of the bitfield value of 1 here." />

</BITFIELD>

<BITFIELD BITRANGE="24:25"

NAME="-"

DESCRIPTION="Make a note that this bitfield is reserved.">

</BITFIELD>

<BITFIELD BITRANGE="26"

NAME="WEBS"

DESCRIPTION="Place the WEBS bitfield desciption here.">

<BFVALUE VALUE="0" DESCRIPTION="Place the description of the bitfield value of 0 here." />

<BFVALUE VALUE="1" DESCRIPTION="Place the description of the bitfield value of 1 here." />

</BITFIELD>

<BITFIELD BITRANGE="27"

NAME="TBDIP"

DESCRIPTION="Place the TBDIP bitfield desciption here.">

</BITFIELD>

<BITFIELD BITRANGE="28"

NAME="LBDIP"

DESCRIPTION="Place the LBDIP bitfield desciption here.">

<BFVALUE VALUE="0" DESCRIPTION="Place the description of the bitfield value of 0 here." />

<BFVALUE VALUE="1" DESCRIPTION="Place the description of the bitfield value of 1 here." />

</BITFIELD>

466 IDE 5.7 User’s Guide

Register Details Window XML Specification

A Sample XML File

<BITFIELD BITRANGE="29"

NAME="SETA"

DESCRIPTION="Place the SETA bitfield desciption here.">

<BFVALUE VALUE="0" DESCRIPTION="Place the description of the bitfield value of 0 here." />

<BFVALUE VALUE="1" DESCRIPTION="Place the description of the bitfield value of 1 here." />

</BITFIELD>

<BITFIELD BITRANGE="30"

NAME="BI"

DESCRIPTION="Place the BI bitfield desciption here.">

<BFVALUE VALUE="0" DESCRIPTION="Place the description of the bitfield value of 0 here." />

<BFVALUE VALUE="1" DESCRIPTION="Place the description of the bitfield value of 1 here." />

</BITFIELD>

< <BITFIELD BITRANGE="31"

NAME="V"

DESCRIPTION="Place the V bitfield desciption here.">

</BITFIELD>

/REGISTER>

Completing the New XML File

Adding multiple BITFIELD attributes and the BFVALUE attributes further refines the

XML file register description. The final revision of an XML file involves completing the descriptions for each attribute.

Refining the example of previous sections, Listing 30.5

shows the final XML file. To use

this new file with the Register Details window, place the file in the Registers folder.

For more information about this folder, refer to Accessing the XML Files from

CodeWarrior .

Listing 30.5 Sophisticated XML File

<REGISTER NAME="BR2"

BITRANGE="0:31"

DESCRIPTION="Memory Controller Base Register 2.">

<BITFIELD

BITRANGE="0:16"

NAME="BA"

IDE 5.7 User’s Guide 467

Register Details Window XML Specification

A Sample XML File

DESCRIPTION="Base Address. These bits are compared to the corresponding unmasked address signals among ADDR[0:16] to determine if a memory bank controlled by the memory controller is being accessed by an internal bus master. (The address types are also compared.)

These bits are used in conjunction with the A<[0:16] bits in the OR">

</BITFIELD>

<BITFIELD

BITRANGE="17:19"

NAME="AT"

DESCRIPTION="Address type. This field can be used to require accesses of the memory bank to be limited to a certain address space type. These bits are used in conjunction with ATM bits in the OR.">

</BITFIELD>

<BITFIELD

BITRANGE="20:21"

NAME="PS"

DESCRIPTION="Port size.">

<BFVALUE VALUE="00" DESCRIPTION="32-bit port" />

<BFVALUE VALUE="01" DESCRIPTION="8-bit port" />

<BFVALUE VALUE="10" DESCRIPTION="16-bit port" />

<BFVALUE VALUE="11" DESCRIPTION="Reserved" />

</BITFIELD>

<BITFIELD

BITRANGE="22"

NAME="-"

DESCRIPTION="Reserved.">

</BITFIELD>

<BITFIELD

BITRANGE="23"

NAME="WP"

DESCRIPTION="Write protect. An attempt to write to the range of addresses specified in a base address register that has this bit set can cause the TEA signal to be asserted by the bus-monitor logic (if enabled) causing termination of this cycle.">

<BFVALUE VALUE="0" DESCRIPTION="Both read and write accesses are allowed" />

<BFVALUE VALUE="1" DESCRIPTION="Only read accesses are allowed. The CSx signal and TA are not asserted by the memory controller on write cycles to this memory bank. WPER is set in the

MSTAT register if a write to this memory bank is attempted." />

</BITFIELD>

468 IDE 5.7 User’s Guide

Register Details Window XML Specification

A Sample XML File

<BITFIELD

BITRANGE="24:25"

NAME="-"

DESCRIPTION="Reserved">

</BITFIELD>

<BITFIELD

BITRANGE="26"

NAME="WEBS"

DESCRIPTION="Write-enable/byte select. This bit controls the functionality of the WE/BE pads.">

<BFVALUE VALUE="0" DESCRIPTION="The WE/BE pads operate as WE"

/>

<BFVALUE VALUE="1" DESCRIPTION="The WE/BE pads operate as BE"

/>

</BITFIELD>

<BITFIELD

BITRANGE="27"

NAME="TBDIP"

DESCRIPTION="Toggle-burst data in progress. TBDIP determines how long the BDIP strobe will be asserted for each data beat in the burst of cycles.">

</BITFIELD>

<BITFIELD

BITRANGE="28"

NAME="LBDIP"

DESCRIPTION="Late-burst-data-in-progress (LBDIP). This bit determines the timing of the first assertion of the BDIP pin in burst cycles. Note: It is not allowed to set both LBDIP and TBDIP bits in a region's base registers; the behavior of the design in such cases is unpredictable.">

<BFVALUE VALUE="0" DESCRIPTION="Normal timing for BDIP assertion (assesrts one clock after negation of TS" />

<BFVALUE VALUE="1" DESCRIPTION="Late timing for BDIP assertion (asserts after the programmed number of wait states" />

</BITFIELD>

<BITFIELD

BITRANGE="29"

NAME="SETA"

DESCRIPTION="External transfer acknowledge.">

<BFVALUE VALUE="0" DESCRIPTION="TA generated internally by memory controller" />

<BFVALUE VALUE="1" DESCRIPTION="TA generated by external logic. Note that programming the timing of CS/WE OE strobes may have no meaning if this bit is set." />

IDE 5.7 User’s Guide 469