Creating Custom Memory Mapped CCStudio Register Windows

Background

Register information has traditionally been defined in a binary file called the TPI. To find what information to display in the CCStudio Register Window, CCStudio would query the TPI. CCStudio has recently gone to a new method where this information is contained in XML files. Devices that have been released since then are defined by these XML files. One nice feature about the XML file driven implementation is that it is expendable by users who wish to add additional information, like custom memory mapped registers. This information would then be available in certain windows like the Register Window.

Custom Memory Mapped Registers

Users can add their own custom memory mapped registers to appear in the Register Window by creating their own custom module XML files in the target database. To do so, a device XML file must exist for your particular device. Device XML files are located in the <CCStudio Install Dir>\drivers\TargetDB\Devices directory. If a device XML file exists for you device, then a module XML file where describes your custom register may be created. Module XML files are usually located in the <CCStudio Install Dir>\drivers\TargetDB\Modules directory.

Creating a Module XML File

A module XML file can have the following elements:

---

<module>: Specifies a group of registers. This is the top level element of the module XML file.

Attributes of interest:

• id: name of the module. This will denote the group of registers contained in the module
• description: the description of module

<module id="PLLC0" HW_revision="0" XML_version="1" description="PLL Controller">

---

<register>: Specifies a register. It is a sub-element of <module>

Attributes of interest:

• id: name of the register
• acronym: substitute name (often the same as id)
• offset: specifies the offset from the base address of the module
• width: width of the register (bits)
• description: description of the register

<register id="PID" acronym="PID" offset="0x0" width="32" description="Contains peripheral ID and revision information">

---

<bitfield>: Allows a register to be grouped into fields of bits for easier interpretation and manipulation. It is a sub-element of <register>.

Attributes of interest:

• id: name of the bitfield
• width: width of bitfield (bits)
• begin: the bit number that is the inclusive start address of the bit.
• end: the bit number that is the inclusive end address of the bit. The index starts at the most significant bit of the field. The most significant bit is the bit n-1, where n is the width of the field
• description: description of the bitfield
• rwaccess: read/write access of field: either R (read), W (write) or RW (read and write)

<register id="PID" acronym="PID" offset="0x0" width="32" description="Contains peripheral ID and revision information">
         
    <bitfield id="TYPE" width="8" begin="23" end="16" resetval="0" description="Peripheral Type: 0x01 to identify as PLLCTRL" range="" rwaccess="RW">
    ...
    </bitfield>

    <bitfield id="CLASS" width="8" begin="15" end="8" resetval="0" description="Peripheral Class: 0x08" range="" rwaccess="RW">
    ...
    </bitfield>

    <bitfield id="REV" width="8" begin="7" end="0" resetval="0" description="Peripheral Revision" range="" rwaccess="RW">
    ...
    </bitfield>

</register>

---

<bitenum>: Allows a bitfield to be defined so that it can only be populated with specific values that can be represented by strings. It is a sub-element of <bitfield>.

Attributes of Interest

• id: name of the bitfield enum
• value: value that should be written to the bitfield when the enum is selected
• token: string representation of the enum
• description: description of the bitenum field

<bitfield id="PLLEN" width="1" begin="0" end="0" resetval="0" description="PLL Mode Enable.  PLLCTL. PLLENSRC must be cleared to 0 before this bit will have any effect." range="" rwaccess="RW">                 
    <bitenum id="0: Bypass mode" value="0" token="0: Bypass mode" description="" />
    <bitenum id="1: PLL mode" value="1" token="1: PLL mode" description="" />
</bitfield>

Modifying the Device XML File

Once the module XML file has been created, it needs to be referenced by the applicable device XML file. This is done by adding a new <instance> element to the device XML file.

<instance>: References a module XML file to be used by the Register Window

Attributes of Interest

• href: relative path to the module XML file from the device XML file
• id: name of register group defined in that file (specified in the id attribute of the module element)
• xml: name of the module XML file
• xmlpath: relative path portion of the XML file
• description: description of the register group (often the same as id)
• requestor: the target that the register group should be associated with
• baseaddr: the memory mapped base address for the register group on the target. The offset attribute of the <register> element is from this base address
• endaddr: the memory mapped end address for the register group on the target
• size: the size of the address range of the register group

<instance href="..\Modules\pllc0_arm.xml" id="PLLC0" xml="pllc0_arm.xml" xmlpath="..\Modules\" HW_revision="1.0" description="PLLC0" requestor="TMS470R2X" baseaddr="0x01C40800" endaddr="0x01C4096B" size="" accessnumbytes="4" permissions="p" />

Referencing the Device XML File

Once the module and device XML files have been created, the device XML file will need to be referenced by CCStudio to get the Register Window to display your register(s). Depending on the setup configuration, the device file may automatically be referenced. You can check this in your setup configuration in CCStudio setup. When you select a configuration in setup that looks something has an extra level in setup, then a device XML file is being used. You can see the extra level in setup highlighted below.

If there is no extra level, then a device XML file is not being referenced. A custom configuration can be created that references a device XML file. When choosing the processor type, you can choose either a processor or a device represented by a device XML file. An easy way to determine which is representing a device XML file is to see if there is a driver location associated with the option. The ones without a driver location indicate that it is a device represented by a device XML file. Also looking closely at the icons, you’ll notice that the icon for a processor is slightly different than an icon for a device.

Note that when adding some of the device XML files to your setup, it may have extra (or incorrect) information underneath so carefully check the added devices and modify as needed.

Instead of creating a configuration in setup which references a device XML file, you can also explicitly load the device XML file inside CCStudio with the GEL_InitializeRegisterData(“C:\\CCStudio_v3.3\\drivers\\TargetDB\\Devices\\device.xml”) GEL command. One trick is to place this call in the OnTargetConnect() GEL callback so that it is run every time connection to the target is established. Please note that running this command will reset the current register information and replace it only with the register information contained in the specified file. If the device XML file referenced does not expose those registers then those register will not be available.

Another thing to note is that the XML files are cached as .cache files in the <CCStudio Install Dir>\drivers\TargetDB\Devices folder. If changes are made to the XML files, the .cache file associated with the device (device.xml.cache) must be removed (deleted) otherwise the changes will not be loaded.

If the module and device XML files have been properly created/updated and referenced, then the new custom register group(s) will now be available in the register window for that device.

More examples of module and device XML files can be found in <CCStudio Install Dir>\drivers\TargetDB\Devices and <CCStudio Install Dir>\drivers\TargetDB\Modules