Nucleus Edge XML Description Files

Introduction

The purpose of this chapter is to provide guidelines for the format of XML description files used in the EDGE. The chapter covers each of the four types of description files that can be used to fully describe a new target for use with EDGE. These types are core, target, peripheral and flash description files.

About EDGE XML Description Files

The below figure illustrates how the different types of description files relate to each other in fully describing a target; each target has one or more cores and can optionally have one or more peripheral description files associated with it.

In order for EDGE to recognize and use new description files added after installation, these files have to be placed in specific folders where EDGE is installed.

Further details on developing and organizing EDGE XML description files are presented in subchapters discussing each description file type.

Definitions, Acronyms and Abbreviations

· XML: eXtensible Markup Language. The file format used to store configuration information in the context of the debugger (see http://www.xml.org/, http://www.w3.org/).

· DTD: Document Type Definition. This is a document which specifies the proper formatting for a given type of XML file.

· Core: a part of a computer system which can be instructed to perform computation-related operations and manipulate data stored internally and externally, via external “instructions”.

· Register: a unit of core-resident data storage.

· Register Group: a grouping of registers with related purpose/functionality or related scope. Typically registers in this grouping are all available in a given processor mode, or are all related to a specific processor function.

· Memory: addressable units of off-core data storage.

· Memory Mapped Register: a “register” typically located on core that differs from a tradition core register in that the mechanism to refer to the register is not through a primitive in the instruction set (e.g. not “R13”) Instead these registers are accessed by normal memory reads and writes to certain specified addresses that are not actually located in RAM, but instead are located in hardware on the chip.

· Address Space: a distinct collection of addressable data (NOT just a distinct means of accessing the same data)

· Peripheral or I/O device: a device designed to extend the data-gathering and/or manipulation capabilities of one or more cores, usually to interface to the “real world”. Peripherals can be viewed as groups of Memory Mapped Registers. Examples: UART, Ethernet device, timer subsystem, etc.

EDGE Target Description Files

Target description files are used to fully describe a target for use with Nucleus EDGE. Target description files describe information on a given target such as the core(s) available on the target, memory layout and memory mapped peripheral registers.

Overview

In order for EDGE to find and use the available target description files, they have to reside in a designated folder as illustrated below:

<EDGE_ROOT> (Typically c:\mgc\embedded\edge_1.0)

\bin

\etc

\targets (Target description files)

\cores

\peripherals

The targets subfolder contains other subfolders that by default divide the targets into groups based on family (i.e. processor family) and by manufacturer. For example an Atmel AT91R40807 target description file would be stored as

<EDGE_ROOT>\bin\etc\targets\ARM\Atmel\at91r40807.xml

The placement of target description files is also important in relation to how EDGE will display the different targets when in the debugger. In the example above, the target selection dialog would look like as shown below:

Note: There is a maximum depth of 3 levels from the targets root folder in which target description files will be read. Any target description files that reside 4 levels or deeper under the targets root folder will not be shown as selectable targets in EDGE.

Detailed description

This section describes the target XML description files in in-depth detail and provides a reference for what XML tags are valid tags for this description file type and how these tags must be organized in the XML file in order to be successfully used in EDGE. There is also a listing of valid tags with descriptions and parameter lists in the last section of this chapter.

Target Description File Layout

Specification and Implementation Details

A target description file has two required tags, the root which is the <target> tag which in turn requires one or more <core> tags as children. Each <core> referenced in the description file can have its own set of registers, memory maps, peripherals and flash chip references. For each tag in the description file, there is a set of attributes (some being required) that you can also specify. For your reference, an example of a simple target description file, can be found in section "Example Target Description File" below.

XML Tag Reference (Target Description Files)

<target>	<core>	<space>
<group>	<register>	<field>
<map>	<region>	<peripheral>
<flash>	<name>

Target

Tag		<target>
Required		Yes (root)
Description		The root node of the target description file

	Attribute name		Required	Type	Description
	name		Yes	String	Target name
	part		Yes	String	Used in codelets
	initpart		No	String	Used in initialization codelets

Core

Tag		<core>
Required		Yes (one or more)
Description		A core present on the target

	Attribute name		Required	Type	Description
	id		Yes	Unique id	Unique core ID (typically a single digit)
	file		Yes	String	Reference to core description xml file
	description		No	String	Description of the core
	part		No	String	Core name (e.g. ARM7TDMI)
	endianity		No	Union	Core endianity (little or big)

Space

Tag		<space>
Required		No (zero or more)
Description		Defines (or references) a memory space

	Attribute name		Required	Type	Description
	name		Yes	String	Name of memory space
	mau		Yes	Number	Memory access unit size (in bits)
	size		No	Number	Size of memory space (in bytes)

Group

Tag		<group>
Required		No (zero or more)
Description		Creates a register group

	Attribute name		Required	Type	Description
	name		Yes	String	Name of register group

Register

Tag

Required

Yes (One or more, required by <group>)

Description

Creates a memory mapped register reference

Attribute name

Required

Type

Description

Yes

String

Identifier for register (i.e. SYSCFG)

template

String

Name of template to reference

name

String

Name of register (System Configuration)

description

String

Description of register

location

Yes[1]

Number

The absolute location of register in memory

offset

Yes1

Number

The offset from the base of a memory mapped peripheral

mask

Number

Bit-mask used to mask certain bits from the register value

rshift

Number

Right-shift the read value n times before displaying in debugger

lshift

Number

Left-shift the read value n times before displaying in debugger

width

Yes

Number

The width (in bits) of the register

access

Yes

Union

Any combination of

R	Read
W	Write
E	Re-read (a write should be followed by a read)
V	Volatile (a read changes/destroys the contents, so do not read it)
S	State changed on write: (a write to this register may change the state of the processor. e.g. the PC register.
M	Memory changed on write (writes to this register may change memory contents/interpretation)

(1- Offset and location are mutually exclusive. If register is part of a memory mapped peripheral (in a peripheral description file) use either offset or location. If register is defined in a register group in a target description file, use offset.)

Field

Tag		<field>
Required		No (zero or more)
Description		Used to describe individual bits of a register

	Attribute name		Required	Type	Description
	name		Yes	String	Name of bitfield
	bits		Yes	Special	Bits in field, given as high_bit..low_bit for example 31..16
	description		No	String	Description

Map

Tag		<map>
Required		No (zero or more)
Description		Defines a memory map

	Attribute name		Required	Type	Description
	space		Yes	String	Name of existing memory space
	mau		No	Number	Memory access unit size (in bits)
	size		No	Number	Size of memory space (in bytes)

Region

Tag

Required

Yes (one or more, required by <map>)

Description

Creates a new memory region

Attribute name

Required

Type

Description

name

Yes

String

Name of memory region

base

Yes

Number

Base address of region

size

Yes

Number

Size of region (inclusive)

width

Yes

Number

Memory access width (in bits)

access

Yes

Union

Any combination of

R	Read
W	Write
E	Re-read
V	Volatile
X	Execute

Peripheral

Tag		<peripheral>
Required		No (zero or more)
Description		Creates a reference to a peripheral description file

	Attribute name		Required	Type	Description
	file		Yes	String	Filename (with path[2]) of peripheral description file.
	base		Yes	Number	Memory access unit size (in bits)

(1-The path to the peripheral file referenced is relative to the root peripheral folder which is found at <EDGE_ROOT>\bin\etc\peripherals. For example, “MyPeripherals\uart1.xml” which creates a references to <EDGE_ROOT>\bin\etc\peripherals\MyPeripherals\uart1.xml )

Flash

Tag		<flash>
Required		No (zero or more)
Description		Creates a flash device

	Attribute name		Required	Type	Description
	name		Yes	String	Name of register group
	base		Yes	Number	Base address of flash device
	device		Yes	String	Device name
	count		Yes	Number	Number of bytes in flash device

Name

Tag		<name>
Required		No (zero or more)
Description		Used to describe possible values of a <field>

	Attribute name		Required	Type	Description
	value		Yes	Number	A possible value for a <field>
	text		Yes	String	Description for above value

Example Target Description File

Nucleus EDGE Core Description Files

Core description files are used to describe characteristics and functionality that are unique to one specific core or core family. This includes core registers, co-processors, memory spaces and core-specific exceptions.