------------------------------------------------------------------------
     Memory Mapped Register Description File Format Specification
------------------------------------------------------------------------
The Palm OS Debugger allows you to define an XML file which
describes the memory mapped registers that your debug target has if any
exist. The XML file describes all registers, and allows you to group
these registers into register sets. One of these files can easily be 
edited by users and specified in the "Debugger Plug-ins" preference 
panels for each debugger plug-in. A simple example XML memory mapped 
register definition document is found below:
------------------------------------------------------------------------
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE MemoryMappedRegisterDefinitions>

<MemoryMappedRegisterDefinitions ADDRESS="0xF0000000">
  <RegisterSet NAME="Register With Varying permissions" OFFSET="0">
    <Register  NAME="RCNR" BYTESIZE="4" PERMISSIONS="rw" OFFSET="0" FORMAT="hex"/>
    <Register  NAME="RTAR" BYTESIZE="4" PERMISSIONS="rw" OFFSET="4" FORMAT="hex"/>
    <Register  NAME="RTSR" BYTESIZE="4" PERMISSIONS="w"  OFFSET="8" FORMAT="hex"/>
    <Register  NAME="RTTR" BYTESIZE="4" PERMISSIONS="r"  OFFSET="12" FORMAT="hex"/>
  </RegisterSet>

  <RegisterSet NAME="Relative Addressed Register Set" OFFSET="0x100">
    <Register  NAME="Foo"  BYTESIZE="1" PERMISSIONS="rw" OFFSET="0x0" FORMAT="dec"/>
    <Register  NAME="Bar"  BYTESIZE="1" PERMISSIONS="rw" OFFSET="0x4" FORMAT="hex"/>
  </RegisterSet>
  
  <RegisterSet NAME="Absolute Addressed Register Set" ADDRESS="0x40000000">
    <Register  NAME="Foo"  BYTESIZE="1" PERMISSIONS="rw" OFFSET="0x0" FORMAT="dec"/>
    <Register  NAME="Bar"  BYTESIZE="1" PERMISSIONS="rw" OFFSET="0x4" FORMAT="hex"/>
  </RegisterSet>
  
  <RegisterSet NAME="Absolute Addresses Registers">
    <Register  NAME="Foo"  BYTESIZE="1" ADDRESS="0x20000000" FORMAT="dec"/>
    <Register  NAME="Bar"  BYTESIZE="1" ADDRESS="0x20000004" FORMAT="hex"/>
  </RegisterSet>

  <RegisterSet NAME="Pretend CPSR Register In Memory to show bit field and enums">
    <Register  NAME="CPSR" BYTESIZE="4" PERMISSIONS="rw" ADDRESS="0x8000" OMIT_SPACES="1" CASE_BITFIELDS="1">
      <Bitfield NAME="N"    BITRANGE="31" />
      <Bitfield NAME="Z"    BITRANGE="30" />
      <Bitfield NAME="C"    BITRANGE="29" />
      <Bitfield NAME="V"    BITRANGE="28" />
      <Bitfield NAME=" I"   BITRANGE="7"  /><!-- Space in name is intentional!!! -->
      <Bitfield NAME="F"    BITRANGE="6"  />
      <Bitfield NAME="T"    BITRANGE="5"  />
      <Bitfield NAME=" MODE" BITRANGE="4:0" ><!-- Space in name is intentional!!! -->
        <Enum>
          <EnumValue KEY="USR" VALUE="0x10"/>
          <EnumValue KEY="FIQ"/> <!-- Value will automatically be 0x11 (previous value +1) -->
          <EnumValue KEY="IRQ"/> <!-- Value will automatically be 0x12 (previous value +1) -->
          <EnumValue KEY="SVC"/> <!-- Value will automatically be 0x13 (previous value +1) -->
          <EnumValue KEY="ABT" VALUE="0x17"/>
          <EnumValue KEY="UND" VALUE="0x1B"/>
          <EnumValue KEY="SYS" VALUE="0x1F"/>
        </Enum>
      </Bitfield>
    </Register>
  </RegisterSet>
</MemoryMappedRegisterDefinitions>

------------------------------------------------------------------------
ELEMENT: 
    MemoryMappedRegisterDefinitions
    
DESCRIPTION:
	This is the document element that can contain many register set
	definitions ("RegisterSet" elements). A base address can optionally
	be specified as the base address for all relatively addressed
	register sets and registers. This allows users to change 1 address
	value and relocate all of the memory mapped registers. The 
	definition file is loaded once just after connecting to a target 
	development board. Any changes made to this file will only take 
	effect after disconnecting and reconnecting to a target.
	
ATTRIBUTES: 
    ADDRESS - the absolute address for the base of the memory mapped
      registers. Any RegisterSet element contained within this
      element can use an OFFSET attribute to indicate that the
      RegisterSet is relative to this address.
              
ELEMENT:
    RegisterSet
    
ATTRIBUTES:
    NAME - the name of the register set as it is to be displayed in the
       register views within POD. There is no limit to the name length.
       
    ADDRESS - the absolute address to be used as the base address of
      this register set. *
      
    OFFSET - an address offset that gets added to the 
      "MemoryMappedRegisterDefinitions" ADDRESS attribute in order
       to compute the base address for this register set. *
             
* - Either an OFFSET or ADDRESS attribute can be specified, but not both. 
If both an ADDRESS and OFFSET attribute are present, the  ADDRESS 
attribute will be used. Any Register elements contained within this
element can use an OFFSET attribute to indicate that the Register is
relative to that address. This allows users to edit a single address 
entry (the ADDRESS attribute of the "MemoryMappedRegisterDefinitions" 
element, and/or the ADDRESS or OFFSET attribute of the "RegisterSet" 
element) to change the location of many registers. Any Register elements
contained within this element can use an OFFSET attribute to indicate 
that the Register is relative to this address.

------------------------------------------------------------------------
             
ELEMENT: 
    Register
    
DESCRIPTION:
	"Register" elements are contained within "RegisterSet" elements and
	describe a single memory mapped register that is to appear within
	the parent register set. Registers must specify at least their names
	and ADDRESS or OFFSET attributes. Optional parameters are the 
	BYTESIZE (for registers which are smaller or larger than 4 bytes),
	PERMISSIONS (for registers that are not read/write), FORMAT to specify
	the default display format and a few attributes pertaining to display
	of "Register" elements which contain "Bitfield" descriptions for their
	bits.
	
ATTRIBUTES:
    NAME - the name of this register as it is to be displayed in the POD
      register views. There is no limit to the name length.
    
    BYTESIZE - the size in bytes of this register. This size can be any
      integer value, and must be <= 4 for registers that contain 
      bit field descriptions. 
      The parameter is optional and defaults to "4".
    
    ADDRESS - the absolute address to be used for this register **
    
    OFFSET - an address offset that gets added to the register set 
      address in order to compute the absolute address for this 
      register **
      
    PERMISSIONS - Allows users to specify the register permissions. 
      Possible values are: "r", "rw", or "w".
      This parameter is optional and defaults to "rw".
      
    FORMAT - Specifies the format to be used to display this register. 
      Possible values are: "hex", "dec", "bin", "float", "char", 
      "ASCII Integer", "bool", and "hex bytes" (for unswapped byte 
      buffer). This parameter is optional and defaults to "hex".
      
    OMIT_SPACES - For registers that contain bit field descriptions. If 
      this attribute is present and its value is non zero, no spaces
      will be placed between the values of each bit field as they are 
      described in the register value string. This is useful for 
      registers that are condition registers where each bit in a register
      has a name with a single character value, and their values are
      displayed as upper/lower case to indicate field values.
      This parameter is optional and defaults to "0".
      
    CASE_BITFIELDS - For registers that contain bit field descriptions. If 
      this attribute is present and its value is non-zero, single-bit
      bit field values will be displayed by showing the bit field name in
      upper or lower case depending on whether the bit is set or not. For 
      example a carry bit in a register could be displayed as "C" if the
      bit is set or "c" if the bit is not set as opposed to the default
      display of "C=1" or "C=0".
      This parameter is optional and defaults to "0".
               
** - Either an OFFSET or ADDRESS attribute can be specified, but not 
both.  If both an ADDRESS and OFFSET attribute are present, the ADDRESS
attribute will be used. "Register" elements can use an OFFSET attribute 
to indicate that the register is relative to the address of its parent 
element (RegisterSet). This allows users to edit a single address entry 
(the ADDRESS attribute of the "MemoryMappedRegisterDefinitions" element,
and/or the ADDRESS or OFFSET attribute of the "RegisterSet" element) to
change the location of many registers. Register elements can use an 
ADDRESS attribute to indicate the exact address of a register.

------------------------------------------------------------------------             
ELEMENT: 
    Bitfield

DESCRIPTION:
    "Bitfield" elements can be used to describe all of the bits inside 
    "Register" elements. Bit fields need to describe their name (using 
    the NAME attribute) and bit ranges (using a BITRANGE attribute). 
    Other optional attributes are the FORMAT attribute (to assign a 
    display format other than the default format), and the SHIFT and 
    MASK attributes for non-contiguous bit fields. Bit fields will be 
    displayed in the order in which they are defined within the POD
    register user interface.
    
    
ATTRIBUTES:
    NAME - the name of the bit field as it is to be displayed in the POD
      register views. There is no limit to the name length.
    
    BITRANGE - The range of bits corresponding to this bit field. This 
      can be in the following forms: "MSBit:LSBit" or "Bit". For example
      a bit field that is a single-bit, bit 23, within a register would
      have the following attribute:
          BITRANGE="23"
      A multiple-bit bit field with bits 7:0 would be:
          BITRANGE="7:0"
          
    SHIFT - The amount to shift the register value to the right PRIOR to
      masking its value in order to get the value of the bit field. This
      parameter is seldom used and is only for bit fields whose bits are 
      not contiguous. The BITRANGE attribute should always be used 
      for bit fields whose bits are contiguous. If the SHIFT attribute is
      specified, the MASK attribute must also be specified. This 
      attribute should NOT be specified if the BITRANGE attribute is
      specified.
      
    MASK - A mask to use AFTER shifting the value of the bit field to the
      right. This parameter is seldom used and is only for bit fields 
      whose bits are not contiguous. The BITRANGE attribute should be 
      always used for bit fields whose bits are contiguous. If the 
      MASK attribute is specified, the SHIFT attribute must also be 
      specified. This attribute should NOT be specified if the BITRANGE
      attribute is specified.
      
    FORMAT - Specifies the format to be used to display this bit field. 
      Possible values are: "hex", "dec", "bin", "float", "char", 
      "ASCII Integer", "bool", "hex bytes" (for unswapped byte buffer). 
      This parameter is optional and defaults to "hex".

EXAMPLE:
<MemoryMappedRegisterDefinitions>
  <RegisterSet NAME="Pretend CPSR Register In Memory">
    <Register  NAME="CPSR" BYTESIZE="4" PERMISSIONS="rw" ADDRESS="0x8000" OMIT_SPACES="1" CASE_BITFIELDS="1">
      <Bitfield NAME="N"    BITRANGE="31"  />
      <Bitfield NAME="Z"    BITRANGE="30"  />
      <Bitfield NAME="C"    BITRANGE="29"  />
      <Bitfield NAME="V"    BITRANGE="28"  />
      <Bitfield NAME=" I"   BITRANGE="7"   /><!-- Space in name is intentional!!! -->
      <Bitfield NAME="F"    BITRANGE="6"   />
      <Bitfield NAME="T"    BITRANGE="5"   />
      <Bitfield NAME=" MODE" BITRANGE="4:0" FORMAT="hex"/><!-- Space in name is intentional!!! -->    
    </Register>
  </RegisterSet>
</MemoryMappedRegisterDefinitions>

------------------------------------------------------------------------             
ELEMENT:
    Enum

DESCRIPTION:
    Enumerations can be used to describe the various values of a bit
    field and are always contained within a "Bitfield" element. Each 
    enumeration value is described by an "EnumValue" element that has
    both a KEY (string value) and a value (a signed integer). The VALUE
    element is optional and if never specified it will start out with a
    value of zero, and increment for each EnumValue as they are defined, 
    much like an enumeration in C code.

ATTRIBUTES:
    KEY - the string value of the enumeration.
    
    VALUE - the signed integer value for the enumeration key. This value
      is optional and will start out at zero if never specified and 
      pre-increment every time an "EnumValue" is specified with no VALUE
      attribute.

EXAMPLE:
<MemoryMappedRegisterDefinitions>
  <RegisterSet NAME="Pretend CPSR Register In Memory">
    <Register  NAME="CPSR" BYTESIZE="4" PERMISSIONS="rw" ADDRESS="0x8000" OMIT_SPACES="1" CASE_BITFIELDS="1">
      <Bitfield NAME="N"    BITRANGE="31" />
      <Bitfield NAME="Z"    BITRANGE="30" />
      <Bitfield NAME="C"    BITRANGE="29" />
      <Bitfield NAME="V"    BITRANGE="28" />
      <Bitfield NAME=" I"   BITRANGE="7"  /><!-- Space in name is intentional!!! -->
      <Bitfield NAME="F"    BITRANGE="6"  />
      <Bitfield NAME="T"    BITRANGE="5"  />
      <Bitfield NAME=" MODE" BITRANGE="4:0" ><!-- Space in name is intentional!!! -->
        <Enum>
          <EnumValue KEY="USR" VALUE="0x10"/>
          <EnumValue KEY="FIQ"/> <!-- Value will automatically be 0x11 (previous value +1) -->
          <EnumValue KEY="IRQ"/> <!-- Value will automatically be 0x12 (previous value +1) -->
          <EnumValue KEY="SVC"/> <!-- Value will automatically be 0x13 (previous value +1) -->
          <EnumValue KEY="ABT" VALUE="0x17"/>
          <EnumValue KEY="UND" VALUE="0x1B"/>
          <EnumValue KEY="SYS" VALUE="0x1F"/>
        </Enum>
      </Bitfield>
    </Register>
  </RegisterSet>
</MemoryMappedRegisterDefinitions>
