CMSIS-SVD Reference
http://www.keil.com/pack/doc/cmsis/svd/html/modules.html
SVD File Schema Levels
Device Level
Peripherals Level
Registers Level
Fields Level
Enumerated Values Level
CMSIS-SVD Schema File Ver. 1.0
http://www.keil.com/pack/doc/cmsis/svd/html/group__schema__gr.html
CMSIS-SVD Schema File Ver. 1.1 (draft)
http://www.keil.com/pack/doc/cmsis/svd/html/group__schema__1__1__gr.html
Description
This section specifies the SVD file format Version 1.0. Each subsection defines one level of hierarchy and lists all mandatory and optional language elements as well as their type.
A brief example description snippet demonstrates the usage of the elements.
- Note
-
- The sequence of elements in CMSIS-SVD is mandatory.
- Optional elements are highlighted in green.
- Mandatory elements are highlighted in blue.
Optional sections can contain mandatory elements, which must be specified when the optional section is used.
In this case the mandatory elements are also highlighted in blue.
Names
All name tags must comply with the ANSI C identifier naming restrictions (identifierType).
In particular they must not contain any spaces or special characters.
This is necessary to support the generation of device header files thus providing consistency
between the names being shown by the debugger and the symbols being used in the CMSIS compliant target software.
Constants
Number constants shall be entered in hexadecimal, decimal, or binary format.
- The Hexadecimal format is indicated by a leading "0x".
- The Binary format is indicated by a leading "#".
- All other formats are interpreted as decimal numbers.
- The value tag in enumeratedValue accepts do not care bits represented by "x".
Comments
Comments have the standard XML format.
- Start a comment with "<!–".
- End a comment with "–>".
Empty Tags
- Single tags are not supported (for example, <name>).
- The tag content must not consist of an empty string (instead, omit optional tags).
- Remarks
- The CMSIS-SVD Schema File Ver. 1.0 and schema_1_1_gr are provided alongside this document.
Device Level
The element device provides the outermost frame of the description.
- Only one device section is allowed per file. All other elements like peripherals, registers, fields, enumerated values, and vendor extensions are described within this scope.
- A device contains one or more peripherals.
- Optional elements like size, access, resetValue, and resetMask defined on this level are used as default values throughout the device description, unless they get redefined at a lower level.
<device <!-- Specifies the CMSIS-SVD schema version the description is compliant to (for example, 1.1). --> schemaVersion="xs:decimal" <!-- Specifies the underlying XML schema to which the CMSIS-SVD schema is compliant. Has to be set to: "http://www.w3.org/2001/XMLSchema-instance". --> xmlns:xs="http://www.w3.org/2001/XMLSchema-instance" <!-- Specifies the file path and file name of the CMSIS-SVD Schema. For example, CMSIS-SVD_Schema_1_1.xsd. --> xs:noNamespaceSchemaLocation="CMSIS-SVD_Schema_1_1.xsd"> <!-- This specifies the vendor of the device using the full name. --> <vendor>stringType</vendor> <!-- This specifies the vendor of the device using the vendor abbreviation that does not contain any spaces or special characters. This information shall be used for defining the directory. --> <vendorID>stringType</vendorID> <!-- The name string is used to identify the device or device series. Device names are required to be unique. --> <name>identifierType</name> <!-- This element specifies the name of the device series. --> <series>stringType</series> <!-- The string defines the version of the file. Silicon vendors maintain the description throughout the life-cycle of the device and ensure that all updated and released copies have a unique version string. Higher numbers indicate a more recent version. --> <version>xs:string</version> <!-- String for describing main features of a device (for example CPU, clock frequency, peripheral overview). --> <description>xs:string</description> <!-- The content of this tag will be copied into the header section of the generated device header file and shall contain the legal disclaimer. New lines can be inserted by using "\n". This section is mandatory if the SVD file shall be used for generating the device header file. --> <licenseText>xs:string</licenseText> <!-- The CPU section describes the processor included in the microcontroller device. This section is mandatory if the SVD file shall be used for the device header file generation. --> <cpu> <!-- The predefined tokens are: CM0: ARM Cortex-M0 CM0PLUS: ARM Cortex-M0+ CM3: ARM Cortex-M3 CM4: ARM Cortex-M4 SC000: ARM Secure Core SC000 SC300: ARM Secure Core SC300 other: other processor architectures --> <name>cpuNameType</name> <!-- Defines the HW revision of the processor. The defined version format is rNpM (N,M = [0 - 9]). --> <revision>revisionType</revision> <!-- Defines the endianess of the processor being one of: little: little endian memory (least significant byte gets allocated at the lowest address). big: byte invariant big endian data organization (most significant byte gets allocated at the lowest address). selectable: little and big endian are configurable for the device and become active after the next reset. other: the endianess is neither little nor big endian. --> <endian>endianType</endian> <!-- Indicates that the processor is equipped with a memory protection unit (MPU). This tag is either set to true or false, 1 or 0. --> <mpuPresent>xs:boolean</mpuPresent> <!-- Indicates that the processor is equipped with a hardware floating point unit (FPU). Cortex-M4 is the only available Cortex-M processor with an optional FPU. This tag is either set to true or false, 1 or 0. --> <fpuPresent>xs:boolean</fpuPresent> <!-- This is an optional flag used for the Cortex-M0+ based devices only. It indicates whether the Vector Table Offset Register (VTOR) is implemented in the Cortex-M0+ device or not. This tag is either set to true or false, 1 or 0. If it is not specified VTOR is assumed to be present. --> <vtorPresent>xs:boolean</vtorPresent> <!-- Defines the number of bits that are available in the Nested Vectored Interrupt Controller (NVIC) for configuring the priority. --> <nvicPrioBits>scaledNonNegativeInteger</nvicPrioBits> <!-- Indicates whether the processor implements a vendor-specific System Tick Timer. If false, then the ARM defined System Tick Timer is available. If true, then a vendor-specific System Tick Timer must be implemented. This tag is either set to true or false, 1 or 0. --> <vendorSystickConfig>xs:boolean</vendorSystickConfig> </cpu> <!-- This tag specifies the file name (without extension) of the device-specific system include file (system_<device>.h; See CMSIS-Core description). This tag is used by the header file generator for customizing the include statement referencing the CMSIS system file within the CMSIS device header file. By default, the filename is "system_device_name.h". In cases where a device series shares a single system header file, the name of the series shall be used instead of the individual device name. --> <headerSystemFilename>identifierType</headerSystemFilename> <!-- The element specifies the string being prepended to all type definition names generated in the CMSIS-Core device header file. This is used if the silicon vendor's software requires vendor-specific types in order to avoid name clashes with other definied types. --> <headerDefinitionsPrefix>identifierType</headerDefinitionsPrefix> <!-- Defines the number of data bits uniquely selected by each address. The value for Cortex-M based devices is 8 (byte-addressable). --> <addressUnitBits>scaledNonNegativeInteger</addressUnitBits> <!-- Defines the number of data bit-width of the maximum single data transfer supported by the bus infrastructure. This information is relevant for debuggers when accessing registers, because it might be required to issue multiple accesses for accessing a resource of a bigger size. The expected value for Cortex-M based devices is 32. --> <width>scaledNonNegativeInteger</width> <!-- registerPropertiesGroup --> <!-- Register properties can be set on device, peripheral, and register level. Element values defined on a lower level overwrite element values defined on a more general level. For example, the register-level.<size> will overwrite peripheral-level.<size>. Elements that have not been defined on a more general level, must be defined at register level at the latest. --> <!-- Defines the default bit-width of any register contained in the device (implicit inheritance). This element can be redefined on any lower level of the description using the size element there. --> <size>scaledNonNegativeInteger</size> <!-- Defines the default access rights for all registers. The predefined tokens are: read-only: read access is permitted. Write operations have an undefined result. write-only: write access is permitted. Read operations have an undefined result. read-write: both read and write accesses are permitted. Writes affect the state of the register and reads return a value related to the register. writeOnce: only the first write after reset has an effect on the register. Read operations deliver undefined results. read-writeOnce: Read operations deliver a result related to the register content. Only the first write access to this register after a reset will have an effect on the register content.--> <access>accessType</access> <!-- Defines the default value for all registers at RESET. The default register value can be redefined on any lower level using the resetValue element there. The actual reset value is calculated from the resetValue and the resetMask. The mask is used to specify bits with an undefined reset value. --> <resetValue>scaledNonNegativeInteger</resetValue> <!-- Identifies which register bits have a defined reset value. These bit positions are set to one. Bit positions with an undefined reset value are set to zero.--> <resetMask>scaledNonNegativeInteger</resetMask> <peripherals> ... </peripherals> <vendorExtensions> ... </vendorExtensions> </device>
<device schemaVersion="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema-instance" xs:noNamespaceSchemaLocation="CMSIS-SVD_Schema_1_0.xsd"> <!-- The device description above is at version 0.1 and uniquely identifies the device by the name "ARM_Cortex_M3". The peripherals are memory mapped in a byte-addressable address space with a bus width of 32 bits. The default size of the registers contained in the peripherals is set to 32 bits. Unless redefined for specific peripherals, all registers or fields are read-write accessible. A reset value of 0, valid for all 32 bits as specified by the reset mask, is set for all registers unless redefined at a lower level. --> <name>ARM_Cortex_M3</name> <version>0.1</version> <description>ARM Cortex-M3 based Microcontroller demonstration device</description> <addressUnitBits>8</addressUnitBits> <width>32</width> <size>32</size> <access>read-write</access> <resetValue>0</resetValue> <resetMask>0xffffffff</resetMask> <peripherals> ... </peripherals> </device> <device schemaVersion="1.1" xmlns:xs="http://www.w3.org/2001/XMLSchema-instance" xs:noNamespaceSchemaLocation="CMSIS-SVD_Schema_1_1.xsd"> <!-- This example describes a device from the vendor Advanced RISC Machines using ARM as short name. The device belongs to the device family identified by ARMCM4. The legal disclaimer in the header files generated from this description is captured and formatted in accordance to the standard ARM CMSIS disclaimer. The CMSIS system file included by the generated device header file is named system_ARMCM4.h and all type definitions will be prepended with ARM_. --> <vendor>Advanced RISC Machines</vendor> <vendorID>ARM</vendorID> <series>ARMCM3</series> <licenseText> ARM Limited (ARM) is supplying this software for use with Cortex-M \n processor based microcontrollers. This file can be freely distributed \n within development tools that are supporting such ARM based processors. \n \n THIS SOFTWARE IS PROVIDED "AS IS". NO WARRANTIES, WHETHER EXPRESS, IMPLIED \n OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF \n MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. \n ARM SHALL NOT, IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL, OR \n CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER. </licenseText> <headerSystemFilename>system_ARMCM4</headeSystemFilename> <headerDefinitionsPrefix>ARM_</headerDefinitionsPrefix> </device> <cpu> <!-- This example describes a Cortex-M4 core of HW revision r0p0, with fixed little endian memory scheme, including Memory Protection Unit and hardware Floating Point Unit. The Nested Vectored Interrupt Controller uses 4 bits for configuring the priority of an interrupt. It is equipped with the standard System Tick Timer as defined by ARM. --> <name>CM4</name> <revision>r0p0</revision> <endian>little</endian> <mpuPresent>true</mpuPresent> <fpuPresent>true</fpuPresent> <nvicPrioBits>4</nvicPrioBits> <vendorSystickConfig>false</vendorSystickConfig> </cpu>
Peripherals Level
All peripherals of a device are enclosed within the tag <peripherals>. At least one peripheral has to be defined. Each peripheral is enclosed in the tag <peripheral>.
- Each peripheral describes all registers belonging to that peripheral.
- The address range allocated by a peripheral is defined through one or more address blocks.
- An address block and register addresses are specified relative to the base address of a peripheral. The address block information can be used for constructing a memory map for the device peripherals.
- Remarks
- The memory map does not contain any information about RAM, ROM, or FLASH memory.
<peripherals> <!-- Specifies the name of a peripheral from which this peripheral will be derived. Values are inherit. Elements specified underneath will override inherited values. --> <peripheral derivedFrom=identifierType> <!-- The name string is used to identify the peripheral. Peripheral names are required to be unique for a device. The name needs to be an ANSI C identifier to allow header file generation. --> <name>identifierType</name> <!-- The string specifies the version of this peripheral description. --> <version>xs:string</version> <!-- The string provides an overview of the purpose and functionality of the peripheral. --> <description>xs:string</description> <!-- --> <groupName>identifierType</groupName> <!-- All register names of this peripheral have their names prefixed with this string. --> <prependToName>identifierType</prependToName> <!-- All register names of this peripheral have their names suffixed with this string. --> <appendToName>identifierType</appendToName> <!-- Is a C-language compliant logical expression returning a TRUE or FALSE result. If TRUE, refreshing the display for this peripheral is disabled and related accesses by the debugger are suppressed. Only constants and references to other registers contained in the description are allowed: <peripheral> -> <register> -> <field>, for example, (System->ClockControl->apbEnable == 0). The following operators are allowed in the expression [&&,||, ==, !=, >>, <<, &, |]. Attention Use this feature only in cases where accesses from the debugger to registers of un-clocked peripherals result in severe debugging failures. SVD is intended to provide static information and does not include any run-time computation or functions. Such capabilities can be added by the tools, and is beyond the scope of this description language. --> <disableCondition>xs:string</disableCondition> <!-- Lowest address reserved or used by the peripheral. --> <baseAddress>scaledNonNegativeInteger</baseAddress> <!-- registerPropertiesGroup --> <!-- Register properties can be set on device, peripheral, and register level. Element values defined on a lower level overwrite element values defined on a more general level. For example, the register-level.<size> will overwrite peripheral-level.<size>. Elements that have not been defined on a more general level, must be defined at register level at the latest. --> <!-- Defines the default bit-width of any register contained in the device (implicit inheritance). This element can be redefined on any lower level of the description using the size element there. --> <size>scaledNonNegativeInteger</size> <!-- Defines the default access rights for all registers. The predefined tokens are: read-only: read access is permitted. Write operations have an undefined result. write-only: write access is permitted. Read operations have an undefined result. read-write: both read and write accesses are permitted. Writes affect the state of the register and reads return a value related to the register. writeOnce: only the first write after reset has an effect on the register. Read operations deliver undefined results. read-writeOnce: Read operations deliver a result related to the register content. Only the first write access to this register after a reset will have an effect on the register content.--> <access>accessType</access> <!-- Defines the default value for all registers at RESET. The default register value can be redefined on any lower level using the resetValue element there. The actual reset value is calculated from the resetValue and the resetMask. The mask is used to specify bits with an undefined reset value. --> <resetValue>scaledNonNegativeInteger</resetValue> <!-- Identifies which register bits have a defined reset value. These bit positions are set to one. Bit positions with an undefined reset value are set to zero.--> <resetMask>scaledNonNegativeInteger</resetMask> <!-- end of registerPropertiesGroup --> <!-- Specifies an address range uniquely mapped to this peripheral. A peripheral must have at least one address block, but may allocate multiple distinct address ranges. If a peripheral is derived form another peripheral, the addressBlock is not mandatory. --> <addressBlock> <!-- Specifies the start address of an address block relative to the peripheral baseAddress. --> <offset>scaledNonNegativeInteger</offset> <!-- Specifies the number of <device> <addressUnitBits> being covered by this address block. The end address of an address block results from the sum of baseAddress, offset, and (size - 1). --> <size>scaledNonNegativeInteger</size> <!-- The following predefined values can be used: registers, buffer, or reserved. --> <usage>usageType</usage> </addressBlock> ... <addressBlock> <offset>scaledNonNegativeInteger</offset> <size>scaledNonNegativeInteger</size> <usage>usageType</usage> </addressBlock> <!-- A peripheral can have multiple associated interrupts. This entry allows the debugger to show interrupt names instead of interrupt numbers. --> <interrupt> <!-- The string represents the interrupt name. --> <name>identifierType</name> <!-- Is the enumeration index value associated to the interrupt. --> <value>scaledNonNegativeInteger</value> </interrupt> <registers> ... </registers> </peripheral> ... <peripheral> ... </peripheral> </peripherals>
<peripheral> <name>Timer0</name> <version>1.0.32</version> <description>Timer 0 is a simple 16 bit timer counting down ... </description> <baseAddress>0x40000000</baseAddress>
<addressBlock> <offset>0x0</offset> <size>0x400</size> <usage>registers</usage> </addressBlock>
<interrupt>
<name>TIM0_INT</name>
<value>34</value>
</interrupt>
<registers> ... </registers>
</peripheral>
<peripheral derivedFrom="Timer0"> <name>Timer1</name> <baseAddress>0x40000400</baseAddress> </peripheral>
The following elements have been added to the peripheral section.
All new elements are optional but are highly recommended to enable the generation of consistent
and CMSIS-compliant device header files from SVD descriptions.
<peripheral> <name>Timer1</name> <!-- The header file generator uses the name of a peripheral as the base name for the C structure type. If this element is specfied, then this string is used instead of the peripheral name. This is particularly useful when multiple peripherals get derived from a peripheral description and a generic type name shall be used. --> <headerStructName>Timer1</headerStructName> <version>1.0</version> <description>Timer 1 is a standard timer ... </description> <baseAddress>0x40002000</baseAddress> ... </peripheral> <peripheral> <name>Timer1_Alt</name> <version>1.0</version> <description>Alternate Timer 1 is a special timer execution mode ... </description> <baseAddress>0x40002000</baseAddress> <!-- All address blocks in the memory space of a device are assigned to a unique peripheral by default. If there are multiple peripherals describing the same address blocks, this needs to be specified explicitly. A peripheral redefining an address block needs to specify the name of the peripheral that is listed first in the description. If no alternate peripheral is specified, then the SVDConv utility will generate errors. --> <alternatePeripheral>Timer1</alternatePeripheral> ... </peripheral>
Registers Level
All registers of a peripheral are enclosed between the <registers> opening and closing tags.
The description of registers is the most essential part of the SVD description.
The register's name, detailed description, and the address-offset relative to the peripheral base address are the mandatory elements.
If the size, access, reset value, and reset mask have not been specified on the device or peripheral level,
or if the default values need to be redefined locally, these fields become mandatory.
A register can represent a single value or can be subdivided into individual bit-fields of specific functionality and semantics.
In schema-terms the fields section is optional, however, from a specification perspective, fields are mandatory when they are described in the device documentation.
The SVD specification supports the array-of-registers concept.
The single register description gets duplicated automatically into an array.
The size of the array is specified by the <dim> element.
The register names can be composed by the register name and an index specific substring define in <dimIndex>.
The <dimIncrement> specifies the address offset between two registers.
<registers> <!-- Specifies the name of the register from which to inherit the data. Elements being specified underneath will override the inherited values. Remarks: When deriving a register, it is mandatory to specify at least the name, the description, and the addressOffset. --> <register derivedFrom=identifierType> <!-- dimElementGroup The SVD specification supports the array-of-registers concept. The single register description gets duplicated automatically into an array. The size of the array is specified by the <dim> element. The register names can be composed by the register name and an index-specific substring defined in <dimIndex>. The <dimIncrement> specifies the address offset between two registers. The elements below can be used to generate an array of registers.--> <!-- The value defines the number of elements in an array of registers. --> <dim>scaledNonNegativeInteger</dim> <!-- If dim is specified, this element becomes mandatory. The element specifies the address increment in between two neighboring registers of the register array in the address map. --> <dimIncrement>scaledNonNegativeInteger</dimIncrement> <!-- Specifies the substrings that replaces the %s placeholder within the register name. By default, the index is a decimal value starting with 0 for the first register. --> <dimIndex>xs:string</dimIndex> <!-- GPIO_A_CTRL, GPIO_B_CTRL, GPIO_C_CTRL, GPIO_D_CTRL, GPIO_E_CTRL, GPIO_Z_CTRL --> <dim>6</dim> <dimIncrement>4</dimIncrement> <dimIndex>A,B,C,D,E,Z</dimIndex> <name>GPIO_%s_CTRL</name> <!-- IRQ3, IRQ4, IRQ5, IRQ6 --> <dim>4</dim> <dimIncrement>4</dimIncrement> <dimIndex>3-6</dimIndex> <name>IRQ%s</name> <!-- end of dimElementGroup --> <!-- Name string used to identify the register. Register names are required to be unique within the scope of a peripheral. --> <name>identifierType</name> <!-- When specified, the string is being used by a graphical frontend to visualize the register. Otherwise the name element is displayed. The displayName may contain special characters and white spaces. The place holder s can be used and is replaced by the dimIndex substring. --> <displayName>xs:string</displayName> <!-- String describing the details of the register. --> <description>xs:string</description> <!-- Specifies a group name associated with all alternate register that have the same name. At the same time, it indicates that there is a register definition allocating the same absolute address in the address space. --> <alternateGroup>xs:Name</alternateGroup> <!-- Value defining the address of the register relative to the baseAddress defined by the peripheral of the register. --> <addressOffset>scaledNonNegativeInteger</addressOffset> <!-- registerPropertiesGroup --> <size>scaledNonNegativeInteger</size> <access>accessType</access> <resetValue>scaledNonNegativeInteger</resetValue> <resetMask>scaledNonNegativeInteger</resetMask> <!-- end of registerPropertiesGroup --> <!-- Element to describe the manipulation of data written to a register. If not specified, the value written to the field is the value stored in the field. The other options define bitwise operations: oneToClear: write data bits of one shall clear (set to zero) the corresponding bit in the register. oneToSet: write data bits of one shall set (set to one) the corresponding bit in the register. oneToToggle: write data bits of one shall toggle (invert) the corresponding bit in the register. zeroToClear: write data bits of zero shall clear (set to zero) the corresponding bit in the register. zeroToSet: write data bits of zero shall set (set to one) the corresponding bit in the register. zeroToToggle: write data bits of zero shall toggle (invert) the corresponding bit in the register. clear: after a write operation all bits in the field are cleared (set to zero). set: after a write operation all bits in the field are set (set to one). modify: after a write operation all bit in the field may be modified (default). --> <modifiedWriteValues>writeValueType</modifiedWriteValues> <!-- Three options exist to set write-constraints: 1. writeAsRead If TRUE, only the last read value can be written. 2. useEnumeratedValues If TRUE, only the values listed in the enumeratedValues list are considered valid write values. 3. range Consists of the following two elements: minimum Specifies the smallest number to be written to the field. maximum Specifies the largest number to be written to the field. --> <writeConstraint>writeConstraintType</writeConstraint> <!-- If set, it specifies the side effect following a read operation. If not set, the register is not modified. The defined side effects are: clear: The register is cleared (set to zero) following a read operation. set: The register is set (set to ones) following a read operation. modify: The register is modified in some way after a read operation. modifyExternal: One or more dependent resources other than the current register are immediately affected by a read operation (it is recommended that the register description specifies these dependencies). Debuggers are not expected to read this register location unless explicitly instructed by the user. --> <readAction>readActionType</readAction> <!-- Next lower level of description (see Fields Level for details). Not all registers are further divided into fields, therefore, this level is optional. In case a register is subdivided into bit fields, it should be reflected in the description. The device header file can only contain bit access macros and bit-field structures if this information is contained in the description. --> <fields> ... </fields> </register> ... <!-- --> <register> ... </register> <registers>
<register> <name>TimerCtrl0</name> <description>Timer Control Register</description> <addressOffset>0x0</addressOffset> <access>read-write</access> <resetValue>0x00008001</resetValue> <resetMask>0x0000ffff</resetMask> <size>32</size> <fields> ... </fields> </register> <register derivedFrom="TimerCtrl0"> <name>TimerCtrl1</name> <description>Derived Timer</description> <addressOffset>0x4</addressOffset> </register>
Cluster Level (New)
Cluster adds a new and optional sub-level to the CMSIS SVD registers level.
A cluster describes a sequence of registers within a peripheral.
A cluster has an base offset relative to the base address of the peripheral.
All registers within a cluster specify their address offset relative to the cluster base address.
Register and cluster sections can occur in an arbitrary order.
This feature, targeted at the generation of device header files,
is useful to create a C data structure within the peripheral structure type,
rather than describing all registers of a peripheral in a flat structure.
<cluster> <dim>4</dim> <dimIncrement>8</dimIncrement> <dimIndex>0-3</dimIndex> <name>TX[%s]</name> <description>Grouping of Transfer data and address</description> <addressOffset>0x40</addressOffset> <register> <name>TX_DATA</name> ... <addressOffset>0x0</addressOffset> ... </register> <register> <name>TX_ADDR</name> ... <addressOffset>0x4</addressOffset> ... </register> </cluster>
// The example above describes an array of type TX with 4 elements. // TX is a cluster of two consecutive registers with 4 elements. // The device header file looks like this: typedef struct { ... struct { __IO uint32_t TX_DATA; __IO uint32_t TX_ADDR; } TX[4]; ... } ..._Type;
Fields Level
All fields of a register are enclosed between the <fields> opening and closing tags
A bit-field has a name that is unique within the register.
The position and size within the register is either described by the combination of
the least significant bit's position (lsb) and the most significant bit's position (msb), or the lsb and the bit-width of the field.
A field may define an enumeratedValue in order to make the display more intuitive to read.
<fields> <!-- The field is cloned from a previously defined field with a unique name. --> <field derivedFrom="identifierType"> <!-- Name string used to identify the field. Field names must be unique within a register. --> <name>xs:Name</name> <!-- String describing the details of the register. --> <description>xs:string</description> <!-- Three options exist to describe the field's bit-range. The options are to be used mutually exclusive: --> <choice> <!-- bitRangeLsbMsbStyle --> <!-- Value defining the position of the least significant bit of the field within the register it belongs to. --> <bitOffset>scaledNonNegativeInteger<bitOffset> <!-- Value defining the bit-width of the bitfield within the register it belongs to. --> <bitWidth>scaledNonNegativeInteger</bitWidth> <!-- bitRangeOffsetWidthStyle --> <!-- Value defining the bit position of the least significant bit within the register it belongs to. --> <lsb>scaledNonNegativeInteger</lsb> <!-- Value defining the bit position of the most significant bit within the register it belongs to. --> <msb>scaledNonNegativeInteger</msb> <!-- bitRangePattern --> <!-- A string in the format: "[<msb>:<lsb>]" --> <bitRange>pattern</bitRange> </choice> <!-- Predefined strings can be used to define the allowed access types for this field: read-only, write-only, read-write, writeOnce, and read-writeOnce. Can be omitted if it matches the access permission set for the parent register. --> <access>accessType</access> <modifiedWriteValues>writeValueType</modifiedWriteValues> <writeConstraint>writeConstraintType</writeConstraint> <readAction>readActionType</readAction> <!-- Next lower level of description. See section Enumerated Values Level for details. --> <enumeratedValues> ... </enumeratedValues> </field> ... <field> ... </field> <fields>
<field> <name>TimerCtrl0_IntSel</name> <description>Select interrupt line that is triggered by timer overflow.</description> <bitOffset>1</bitOffset> <bitWidth>3</bitWidth> <access>read-write</access> <resetValue>0x0</resetValue> <modifiedWriteValues>oneToSet</modifiedWriteValues> <writeConstraint> <range> <minimum>0</minimum> <maximum>5</maximum> </range> </writeConstraint> <readAction>clear</readAction> <enumeratedValues> ... </enumeratedValues> </field>
Enumerated Values Level
Enumerated Values
The concept of enumerated values creates a map between unsigned integers and an identifier string.
In addition, a description string can be associated with each entry in the map.
0 <-> disabled -> "the clock source clk0 is turned off" 1 <-> enabled -> "the clock source clk1 is running"
This information is used for generating an enum in the device header file.
The debugger may use this information to display the identifier string as well as the description.
Just like symbolic constants making source code more readable, the system view in the debugger becomes more instructive.
The detailed description can provide reference manual level details within the debugger.
<!-- Makes a copy from a previously defined enumeratedValues section. No modifications are allowed. An enumeratedValues entry is referenced by its name. If the name is not unique throughout the description, it needs to be further qualified by specifying the associated field, register, and peripheral as required. For example: field: clk.dis_en_enum register + field: ctrl.clk.dis_en_enum peripheral + register + field: timer0.ctrl.clk.dis_en_enum --> <enumeratedValues derivedFrom="xs:Name"> <!-- Identifier for the whole enumeration section. --> <name>enumerationNameType</name> <!-- Possible values are read, write, or read-write. This allows specifying two different enumerated values depending whether it is to be used for a read or a write access. If not specified, the default value read-write is used. --> <usage>usageType</usage> <!-- Describes a single entry in the enumeration. The number of required items depends on the bit width of the associated field. See section below for details. --> <enumeratedValue> <!-- String describing the semantics of the value. Can be displayed instead of the value. --> <name>identifierType</name> <!-- Extended string describing the value. --> <description>xs:string</description> <!-- --> <choice> <!-- Defines the constant of the bit-field that the name corresponds to. --> <value>scaledNonNegativeInteger</value> <!-- Defines the name and description for all other values that are not listed explicitly. --> <isDefault>xs:boolean</isDefault> </choice> </enumeratedValue> ... <enumeratedValue> ... </enumeratedValue> </enumeratedValues>
<enumeratedValues> <name>TimerIntSelect</name> <usage>read-write</usage> <enumeratedValue> <name>disabled</name> <description>The clock source clk0 is turned off.</description> <value>0</value> </enumeratedValue> <enumeratedValue> <name>reserved</name> <description>Reserved values. Do not use.</description> <isDefault>true</isDefault> </enumeratedValue> </enumeratedValues> <enumeratedValues> <name>TimerIntSelect</name> <usage>read-write</usage> <enumeratedValue> <name>disabled</name> <description>Timer does not generate interrupts.</description> <value>0</value> </enumeratedValue> <enumeratedValue> <name>enabled</name> <description>Timer generates interrupts.</description> <isDefault>true</isDefault> </enumeratedValue> </enumeratedValues>
