This file describes the Cortex Microcontroller Software Interface Standard - System View Description (CMSIS - SVD) concept and syntax.
Version: 1.02 - 27. July 2011
Information in this file, the accompany manuals, and software is
Copyright © ARM Ltd.
All rights reserved.
Revision History
The Cortex Microcontroller Software Interface Standard - System View Description (CMSIS - SVD) answers the challenges of accurate, detailed and timely device aware peripheral debugging support for Cortex Microcontroller based devices by the software development tools vendor community.
Silicon vendors shall create and maintain a formalized description of the debug view for all the peripherals contained in their Cortex Microcontroller based devices. Tool vendors use such descriptions to establish device specific debug support in their debugging tools with minimal turn around times and manageable effort. Device support across many development tools is essential for silicon provider in order to promote new devices and device variants entering the market. Device aware debug views provide fast and convenient access to all registers and fields as well as a detailed description. This enables software developer to develop and debug code most efficiently and adopt new devices early and quickly.
A standardized System View Description shall provide a common approach to capturing peripheral debug related information in a machine readable files. The scope of the contained information is agreed to match the level usually provided by silicon vendors in their device reference manuals, however in a formalized XML based format. There are other description languages already available. IP-XACT from the SPIRIT consortium is a prominent example. IP-XACT covers the register description sufficiently, however it comprises many other aspects of the devices like ports, bus-protocols, modeling, tool flows, etc. making a direct use of IP-XACT too complex. The design of the SVD language is taking some guidance from IP-XACT thus allowing straight forward conversion from IP-XACT to CMSIS-SVD where IP-XACT device information is already available.
In a second step the CMSIS-SVD description shall be used for automatically generating CMSIS compliant a device header file. This enables the information in the header file to be consistent with what the debugger will display and CMSIS compliant by construction. The header file generation will require some additional pieces of information and therefore a future version of the description will need to include some extensions for this purpose.
Device aware debugging support is only one aspect of device support essential to software development environments, however it is one of the most time consuming and error prone ones.
The software developer of microcontroller devices is faced with a growing number of devices with an ever increasing number of peripheral blocks providing a wide range of distinct and complex functionality. The development of drivers for these peripherals is in the critical path of every project. Modern debuggers are supporting the software developer in getting the software to run according to the requirements. A debugger providing peripheral awareness improves the ability to access and interpret complex configuration and status information of peripherals. Even though this is only one aspect of device support within microcontroller development environments it is essential for the successful and timely adoption of development tools and the device by the market.
Today software development environments address device aware debugging in various ways. They either use documents or proprietary file formats as input for providing peripheral views in the debuggers. Extracting peripheral information from written documentation is a very time consuming, tedious and error prone task. Having a file containing peripheral specific information to generate peripheral views is going to make device support more affordable, reliable and timely. The challenge for the tool providers is the support of many different and incompatible file formats from a growing number of silicon vendors. For silicon vendors it is time consuming and costly to engage with many tool provider in order to achieve device support in a wide range of development environments.
Standardizing on a System View Description aims to ease this challenge by agreeing on a formal XML-based file format. In conjunction with supporting web server infrastructure silicon partner shall upload and maintain such descriptions in a tool vendor agnostic device database, hosted e.g. by the web server infrastructure cmsis.arm.com . Access control to sensitive information is managed on a per user basis. This allows silicon vendors to upload information for devices that have not been made public.
Such an approach provides benefits for silicon and tool vendors as well as software developers of Cortex-M based microcontroller devices
The debug description shall capture the information about all the peripherals contained in a specific device. This section describes which items of information are deemed relevant for a debugger. Silicon vendors are expected to provide the System View Description for their devices, matching the information contained in device reference manuals. The System View Description shall be suitable for straight forward generation from existing databases like IP-XACT descriptions or SIDSC. The size of device description is a concern and therefore redundancy in the description shall be avoided. The size of SVD files affects the efficiency of distribution as well as the loading time by the development tools. Last but not least manual editing of SVD files shall be possible for the purpose of customization by SW developers.
From a programmer's perspective a peripheral can be seen as a set of registers with unique names being mapped to fixed addresses allocated within a defined range of an address space.
From a debugger's point of view read accesses to a physical register need to be executed in order to display its current value. The debugger executes a write access to a register when a user edits its value. For this purpose the debugger needs to know about the following additional attributes:
In many cases peripheral registers are partitioned into chunks of bits of distinct functionality. In this document these chunks are referred to as field. Each register that consists of fields shall be described by a list of uniquely named fields (Note: field names are not required to be unique across registers). In order for a debugger to extract the value of a field from the corresponding register the following attributes are required:
An enumerated value maps a number to a specific descriptive string representing the semantics of the value of a field. The debugger displays the descriptive string rather than the number to simplify the access to the information thus avoiding the necessity of a look-up in the device reference manual. Each item of an enumerated value has the following attributes:
The hierarchical structure of the description looks like this:
Device =
Peripherals
Peripheral
Registers
Register
Fields
Field
Enumerated Values
Enumerated Value
One file can only contain a description for a single device or device family sharing the identical description. Devices consists of a one or more peripherals. Each peripheral contains one or more registers, where each register may consist of one or more fields. The values of a field maybe represented through descriptive strings and detailed descriptions, the enumerated values.
In many cases there are multiple instances of the same peripheral in a device (e.g. Timer0, Timer1, etc.). For this reason the description has the concept of deriving a peripheral from a peripheral that has already been described. The attribute derivedFrom specifies such a relationship. Similarly registers or fields can be reused within the device description. The grouping of peripherals providing similar functionality (e.g. Simple Timer, Complex Timer) is controlled via the element groupName. All peripherals associated with the same group name are collectively listed under this group in the order they have been specified in the file. Collecting similar or related peripherals into peripheral groups helps structuring the list of peripherals e.g. in a drop down menu (tool dependent). Devices with a large set of peripherals will benefit from this additional level of structure.
Each of the items (i.e. Device, Peripheral, Register and Field) owns an description element containing verbose information about the respective element. The description field plays an important part in improving the software development productivity. Instead of searching through the reference manual the detailed explanation from the manual could become immediately accessible from within the development environment.
Details about the exact display format and layout of the peripheral view are considered beyond the scope of the description. It is up to the tool vendor to visualize the contained information appropriately. The silicon vendor provides details about the device's peripherals that is commonly available.
System View Description files need to be validated for:
The SVD description format was extended by numerous elements during the
review period targeting version 1.0 and new extensions are expected for future
versions of this format. A new section named "vendorExtensions" has been added
to the end of the top level to allow silicon vendors and tool partners to
innovate and expand the description in order to overcome limitations of the
current specification until these can be incorporated into new versions of
CMSIS-SVD.
The following section describes the SVD file format in detail. Each subsection defines a single hierarchy level of the description and lists all mandatory and optional language elements for that specific level including type information for each element. Each element is discussed in more detail and a brief snippet is provided as an example. The sequence of elements shown below is binding. Optional elements are highlighted in green, blue elements are mandatory unless they have been already specified globally on a higher level.
An XML-schema file is provided alongside this document for syntactical checking of descriptions being developed.
<name>xs:Name</name>
<version>xs:string</version>
<description>xs:string</description>
<addressUnitBits>scaledNonNegativeInteger</addressUnitBits>
<width>scaledNonNegativeInteger </width>
<size>scaledNonNegativeInteger</size>
<access>accessType</access>
<resetValue>scaledNonNegativeInteger</resetValue>
<resetMask>scaledNonNegativeInteger</resetMask>
<peripherals>
...
</peripherals>
<vendorExtensions>
...
</vendorExtensions>
The device provides the outermost frame of the description. All other elements like peripherals, registers and fields are described inside of this scope. A device contains one or more peripherals. The optional elements size, access, resetValue and resetMask are used as default values throughout the device description unless they get overruled on a lower level of the description (e.g. peripheral or register).
name = the unique name string is used to identify the device. All devices of a silicon vendor are required to have a unique name. In case an SVD description covers a family or series of devices, the name of the series or family is placed here. The device names of the members of the series or family are listed in <memberDevices>
description = string describing main features of a device (e.g. CPU, clock frequency, peripheral overview, etc.)
version = the string is defining the version of the description for this device. Silicon vendors will maintain the description throughout the lifecycle of the device and need to ensure that all updated and released copies have a unique version string indicating the order in which. Note: this must not be used for detailing the version of the device.
addressUnitBits = defines the number of data bits for each address increment. The value for Cortex-M based devices is 8 (byte-addressable).
width = defines the number of bits for the maximum single transfer size allowed by the bus interface hence the maximum size of a single register that can be defined for the address space. This information is relevant for debuggers when determining the size of debug transfers. The expected value for Cortex-M based devices is 32.
peripherals = next level of description (see next section for details)
size = defines the default bit-width of registers contained in the device. This element can be overruled by re-specifying the size element on a lower level of the description.
access = defines the default access permissions for all
registers in the device. The allowed 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.
resetValue = defines the default value of all registers after a reset. There are scenarios where SW developers need to know, what the reset value of a register or field is. Even though listed as optional on this level of the description, silicon vendors should ensure that this information is provided for all registers.
resetMask = defines those bit positions set to one to be taken from resetValue element. All other elements are undefined. If a register does not have a defined reset value the resetMask needs to be set to 0.
vendorExtensions = the content and format of this section of the description is unspecified. Silicon vendors may choose to provide additional information. The assumption is that by default this section is completely ignored by the debugger. It is up to the silicon vendor to specify the content of this section and share the specification with the tool vendors. The new elements shall be considered for a future version of the description format.
<device schemaVersion="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema-instance" xs:noNamespaceSchemaLocation="CMSIS-SVD_Schema_1_0.xsd" > <name>CMSIS_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>
The device description above is at version 0.1 and uniquely identifies the device by the name "CMSIS_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, registers or fields all registers 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 overruled at a lower level of the description.
<peripheral>
...
</peripheral>
...
<peripheral>
...
</peripheral>
This construct sets the frame for all peripherals and peripheral groups contained in a device. This creates a container element which ease-up processing with languages like Java.
<name>xs:Name</name>
<version>xs:string</name>
<description>xs:string </description>
<groupName>xs:string</groupName>
<prependToName>xs:string</prependToName>
<appendToName>xs:string</appendToName>
<disableCondition>xs:string</disableCondition>
<baseAddress>scaledNonNegativeInteger</baseAddress>
<size>scaledNonNegativeInteger</size>
<access>accessType</access>
<resetValue>scaledNonNegativeInteger</resetValue>
<resetMask>scaledNonNegativeInteger</resetMask>
<addressBlock>
<offset>scaledNonNegativeInteger</offset>
<size>scaledNonNegativeInteger</size>
<usage>usageType</usage>
</addressBlock>
...
<addressBlock>
<offset>scaledNonNegativeInteger</offset>
<size>scaledNonNegativeInteger</size>
<usage>usageType</usage>
</addressBlock>
<interrupt>
<name>xs:string</name>
<value>scaledNonNegativeInteger</value>
</interrupt>
<registers>
...
</registers>
A peripheral encloses the description of one or more registers belonging to this named peripheral. The address range allocated in the address space for this peripheral is defined through one or more address ranges. An address range is specified relative to the base address of the peripheral. This information allows to display a memory map overview for all peripherals. Please note that such a memory map does not contain any information for memories and unoccupied address ranges.
name = name string used to identify the peripheral. Peripheral names are required to be unique within the scope of a device.
baseAddress = lowest address reserved or used by the peripheral
description = string providing an overview of the purpose and functionality of the peripheral
addressBlock = a peripheral may occupy one or more disparate
blocks in the address space. An addressBlock is a complex element consisting of
the mandatory elements:
offset: specifying the start address of an address block. It
is calculated from the sum of baseAddress and offset
size: specifying the number of addressUnitBits being covered
by this address block. The end address of an address block is the sum of start
address and the size - 1.
usage: the usage element is of usageType specifying
if the addresses within the specified address block is used for
registers or buffer or is reserved.
Note: registers must not be allocated
to an address within a reserved or buffer address range.
registers = next lower level of description (see next section for details)
derivedFrom = this attribute specifies the name of a peripheral that has already been described for this device. The description of that device will be copied. It is mandatory to overwrite the name as well as the addressOffset. All other specified information will overwrite the respective elements in the copy.
version = the string specifies the version of this peripheral description.
disableCondition = C language compliant logical expression resulting in a true or false result. If "true" the refresh of 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> (e.g.: (System->ClockControl->apbEnable == 0)). Only the following operators are allowed [&&,||, ==, !=, >>, <<, &, |]. Warning! This feature must only be use in case accesses from the debugger to registers of un-clocked peripherals result in severe debugging failures. SVD is intended to be fully static information and not include any run-time computation or functions such capabilities may be added by the tools but is considered beyond the scope of this description language.
prependToName = all register names of this peripheral have their names prepended with the string specified
appendToName = all register names of this peripheral have their names appended with the string specified
size = defines the default bit-width of registers contained in the device. This element can be overruled by re-specifying the size element on a lower level of the description.
access = defines the default access permissions for all
registers in the peripheral. The value can be reset on a lower level of the
description. The allowed 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.
resetValue = defines the default value of all registers after a reset but can be set for individual registers and fields on a lower level of the description.
resetMask = defines those bit positions set to one to be taken from resetValue element. All other elements are undefined. This is the default value for the whole peripheral but can be readjusted on lower levels. If a register does not have a defined reset value the resetMask needs to be set to 0.
interrupt = is a complex type that consists of the name of the interrupt and the associated enumeration value. A peripheral can also have multiple associated interrupts. This entry is mainly intended for information only purposes in order to display the interrupts and respective interrupt numbers associated with a peripheral.
...
<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>
...
This construct sets the frame for all registers contained in a peripheral. This creates container elements which ease-up processing with languages like Java.
<dim>scaledNonNegativeInteger</dim>
<dimIncrement>scaledNonNegativeInteger</dimIncrement>
<dimIndex>xs:string</dimIndex>
<name>xs:Name</name>
<displayName>xs:string</displayName>
<description>xs:string</description>
<alternateGroup>xs:Name</alternateGroup>
<addressOffset>scaledNonNegativeInteger
</addressOffset>
<size>scaledNonNegativeInteger</size>
<access>accessType</access>
<resetValue>scaledNonNegativeInteger</resetValue>
<resetMask>scaledNonNegativeInteger</resetMask>
<modifiedWriteValues>writeValueType</modifiedWriteValues>
<writeConstraint>writeConstraintType</writeConstraint>
<readAction>readActionType </readAction>
<fields>
...
</fields>
The definition of registers is the central part of the description. A register may use its complete size for a single purpose and therefore not consist of fields. Otherwise the description of fields is mandatory.
name = name string used to identify the register. Register names are required to be unique within the scope of a peripheral.
description = string describing the details of the register.
addressOffset = value defining the address of the register relative to
the baseAddress defined by the peripheral the register belongs to.
The following elements can be omitted if the corresponding value has been set on a higher level of the description and matches the value required for this register:
size =value defining the bit-width of the register
access = predefined tokens: read-only, write-only, read-write, writeOnce, read-writeOnce strings defining the allowed accesses for this register.
resetValue = element defining the value of the register immediately after a reset.
resetMask= element specifying those bits of the resetValue that are defined (bit positions containing a 0 bit are ignored, bit positions containing a 1 bit are taken from the corresponding bit position of the resetValue). If a register does not have a defined reset value the resetMask needs to be set to 0.
dim = if this field is specified the value defines the number of elements in an array of registers.
dimIncrement = if dim is specified this element becomes mandatory and specifies the address increment in between two neighboring registers of the register array in the address map.
dimIndex = this element specifies the substrings within the
register array names that will replace the %s within the register name. By
default the index is a decimal value starting with 0 for the first register.
Examples:
<dim>6</dim> <dimIncrement>4</dimIncrement> <dimIndex>A,B,C,D,E,Z</dimIndex>
<name>GPIO_%s_CTRL</name> ...
=> GPIO_A_CTRL, GPIO_B_CTRL, GPIO_C_CTRL, GPIO_D_CTRL, GPIO_E_CTRL,
GPIO_Z_CTRL
<dim>4</dim> <dimIncrement>4</dimIncrement> <dimIndex>3-6</dimIndex>
<name>IRQ%s</name> ...
=> IRQ3, IRQ4, IRQ5, IRQ6
displayName = when used, this is the string being used by a graphical frontend to visualize the register otherwise the name element is used. Note: the display name may contain special characters and white spaces. It also uses "%s" as the place holder for the dimIndex substring.
alternateGroup = when used, this element specifies a name of a group that all alternate register with the same name a associated with. At the same time it indicates that there is a register description allocating the same absolute address in the address space.
modifiedWriteValues = 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 are 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)
writeConstraint: has a set of options:
writeAsRead = if true only the last read value can be written
useEnumeratedValues = if true only those values listed in the
enumeratedValues list are considered valid write values
minimum = specifies the smallest number to be written to the
register
maximum = specifies the largest number to be written to the
register
readAction: if set it specifies the side effect following
read operations. If not set the register is not modified following a read
operations. The defined side effects are:
clear: indicates that the register is cleared (set to zero)
following a read operation
set: indicates that the register is set (set to ones) following a
read operation
modify: indicates that the register is modified in some way
after a read operation
modifyExternal: indicates that one or more dependent resources
other than the current register
are immediately affected by a read (it is recommended that the register
description specifies these dependencies). Debuggers are not expected to read
this register location unless explicitly instructed by user.
fields = next lower level of description (see next section for details).
derivedFrom = specifies the name of the register to be replicated. Elements being specified underneath will override the values specified from the register being derived from. Note that it is mandatory to overwrite at least name and addressOffset.
...
<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>
<addressOffset>0x4<addressOffset>
</register>
...
This construct sets the frame for all fields contained in a register. This creates container elements which ease-up processing with languages like Java.
<name>xs:Name</name>
<description>xs:string</description>
<bitOffset>scaledNonNegativeInteger</bitOffset>
<bitWidth>scaledNonNegativeInteger</bitWidth>
or
<lsb>scaledNonNegativeInteger</lsb> <msb>scaledNonNegativeInteger</msb>
or
<bitRange>pattern</bitRange>
<access>accessType</access>
<modifiedWriteValues>writeValueType</modifiedWriteValues>
<writeConstraint>writeConstraintType</writeConstraint>
<readAction>readActionType </readAction>
<enumeratedValues>
...
</enumeratedValues>
A bit-field has a name that is unique for the register it belongs to. 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 size, specifying the bit-width of the field. A field may define an enumeratedValue in order to make the display more intuitive to read.
name = name string used to identify the field. Field names
are required to be unique within the scope of a register.
description = string describing the details of the register.
There are 3 ways to describe a field to be used mutually exclusive:
a) specifying bitOffset and bitWidth (IP-XACT like)
b) specifying lsb and msb of the field.
c) specifying a bit range in the format "[<msb>:<lsb>]"
bitOffset = value defining the position of the least significant bit
of the field within the register it belongs to.
bitWidth = value defining the bit-width of the bitfield within the
register it belongs to.
lsb = value defining the bit position of the least significant
bit within the register it belongs to.
msb = value defining the bit position of the most significant
bit within the register it belongs to.
bitRange = a string in the format: [<msb>:<lsb>]
derivedFrom = the field is cloned from a previously defined field with a unique name.
access = predefined strings defining the allowed accesses for this register: read-only, write-only, read-write, writeOnce, read-writeOnce. Can be omitted if it matches the access permission set for the parent register.
enumeratedValues = next lower level of description (see next section for details)
modifiedWriteValues = element to describe the manipulation of
data written to a field. If not specified the value written to the field is the
value stored in the field. The other options are bitwise operations:
oneToClear: write data bit of one shall clear (set to zero) the
corresponding bit in the field
oneToSet: write data bit of one shall set (set to one) the corresponding
bit in the field
oneToToggle: write data bit of one shall toggle (invert) the
corresponding bit in the field
zeroToClear: write data bit of zero shall clear (set to zero) the
corresponding bit in the field
zeroToSet: write data bit of zero shall set (set to one) the
corresponding bit in the field
zeroToToggle: write data bit of zero shall toggle (invert) the
corresponding bit in the field
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)
writeConstraint: has a set of options:
writeAsRead = if true only the last read value can be written
useEnumeratedValues = if true only those values listed in the
enumeratedValues list are considered valid write values
minimum = specifies the smallest number to be written to the field
maximum = specifies the largest number to be written to the field
readAction: if set it specifies the side effect following
read operations. If not set the field is not modified following a read
operations. The defined side effects are:
clear: indicates that the field is cleared (set to zero)
following a read operation
set: indicates that the field is set (set to ones) following a
read operation
modify: indicates that the field is modified in some way after a
read operation
modifyExternal: indicates that one or more dependent resources
other than this field are immediately affected by a read (it is recommended that
the field description specifies these dependencies). Debuggers are not expected
to read the field unless explicitly instructed by user.
...
<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>
...
<name>xs:Name</name>
<usage>usageType</usage>
<enumeratedValue>
...
</enumeratedValue>
...
<enumeratedValue>
...
</enumeratedValue>
An enumerated value provides one or more enumeration items (enumeratedValue), defining a map between all possible values of the bit-field it belongs to and the corresponding human readable semantics of that value.
Mandatory items:
enumeratedValue = next lower level of description (see next section
for details)
Optional items:
derivedFrom = the enumeratedValues can be copied or derived
from a previously defined enumeratedValue that has been given a unique name.
name = name string to identify an enumeratedValue. Named
enumeratedValues need to be unique in the scope of a device in order to be reusable
throughout the description of a device.
usage = possible values are read, write or
read-write. This allows to specify two different enumerated values
depending whether it is to be used for a read or a write access. If not specified the enueratedValues are valid for read and write.
...
<enumeratedValues>
<name>TimerIntSelect</name>
<usage>read-write</usage>
<enumeratedValue>
<name>disabled</name>
<description>disabled bit</description>
<value>0</value>
</enumeratedValue>
...
<enumeratedValue>
<name>reserved</name>
<description>reserved values. Do not use</description>
<isDefault>true</isDefault>
</enumeratedValue>
</enumeratedValues>
...
<name>xs:name</name>
<description>xs:string</description>
<value>scaledNonNegativeInteger</value>
or
<isDefault>xs:boolean</isDefault>
An enumeratedValue defines a map between a value and the string reading the corresponding human readable semantics for that value in a brief and a detailed version
name= brief string verbally describing the semantics of the value defined for this enumeratedValue. E.g. used for display in visualization of a bit-field instead of the value.
value = defines the constant of the bit-field that the name corresponds to.
isDefault = defines the name and description for all other values that are not explicitly listed
description = extended string verbally describing the semantics of the value defined for this enumeratedValue in full detail.
...
<enumeratedValue>
<name>disabled</name>
<description>Timer does not generate interrupts</description>
<value>0</value>
</enumeratedValue>
...
<enumeratedValue>
<name>enabled</name>
<description>Timer does not generate interrupts</description>
<isDefault>true</isDefault>
</enumeratedValue>
...
Names shall comply with ANSI C variable naming restrictions.
Number constants shall be entered in hexadecimal, decimal or binary format.
Comments have the standard XML format "<!--" starts a comment "-->" terminates a comment
<?xml version="1.0" encoding="utf-8"?>
<device schemaVersion="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema-instance" xs:noNamespaceSchemaLocation="CMSIS-SVD_Schema_1_0.xsd" >
<name>Cortex_M3_Sample</name>
<version>0.1</version>
<description>ARM Cortex-M3 based Microcontroller dummy device</description>
<!-- Bus Interface Properties -->
<!-- Cortex-M3 is byte addressable -->
<addressUnitBits>8</addressUnitBits>
<!-- the maximum data bit width accessible within a single transfer is 32bits -->
<width>32</width>
<!-- Register Default Properties -->
<!-- the size of the registers is set to a bit width of 32. This can be overruled for individual peripherals and/or registers -->
<size>32</size>
<!-- the access to all registers is set to be readable and writeable. This can be overruled for individual peripherals and/or registers -->
<access>read-write</access>
<!-- for demonstration purposes the resetValue for all registers of the device is set to be 0. This can be overruled within the description -->
<resetValue>0</resetValue>
<!-- the resetMask = 0 specifies that by default no register of this device has a defined reset value -->
<resetMask>0</resetMask>
<peripherals>
<peripheral>
<name>Timer0</name>
<description>A simple 16 bit timer counting down ... </description>
<groupName>Timer</groupName>
<baseAddress>0x40000000</baseAddress>
<!-- the first addressBlock is occupied by registers. The second block is reserved -> no access permission -->
<addressBlock>
<offset>0</offset>
<size>0x8</size>
<usage>registers</usage>
</addressBlock>
<addressBlock>
<offset>0x8</offset>
<size>0x3f8</size>
<usage>reserved</usage>
</addressBlock>
<interrupt>
<name>TIM0_IRQn</name>
<value>34</value>
</interrupt>
<registers>
<register>
<name>TimerCtrl0</name>
<!-- the display name is an unrestricted string. -->
<displayName>Timer Ctrl 0</displayName>
<description>Timer Control Register</description>
<addressOffset>0x0</addressOffset>
<!-- size=32, access=read-write, resetValue=0x0, resetMask=0xffffffff, volatile=false -->
<fields>
<field>
<name>TimerCtrl0_En</name>
<description>Enable Bit activates the timer.</description>
<!-- Spirit like bit range description: [0:0] -->
<bitOffset>0</bitOffset>
<bitWidth>1</bitWidth>
<!-- Writing 1 enables, writing 0 has no effect -->
<modifiedWriteValues>oneToSet</modifiedWriteValues>
<!-- The write constraint is defined to be that only the values provided by the enumeratedValues below are allowed -->
<writeConstraint>
<useEnumeratedValues>true</useEnumeratedValues>
</writeConstraint>
<!-- there is no side effect on reads, therefore <readAction> is not set -->
<!-- oneBitEnable named enumeration that can be reused in other parts of the description -->
<enumeratedValues>
<name>oneBitEnable</name>
<!-- the same enumerated Values are used for read and write. This default is assumed when this tag is missing -->
<usage>read-write</usage>
<enumeratedValue>
<name>enabled</name>
<description>Timer is enabled and active</description>
<value>0x0</value>
</enumeratedValue>
<enumeratedValue>
<name>disabled</name>
<description>Timer is disabled and inactive</description>
<value>0x1</value>
</enumeratedValue>
</enumeratedValues>
</field>
<field>
<name>TimerCtrl0_Dis</name>
<description>Disable Bit deactivates the timer.</description>
<!-- Spirit like bit range description: [1:1] -->
<bitOffset>1</bitOffset>
<bitWidth>1</bitWidth>
<!-- Writing 1 sets, writing 0 has no effect -->
<modifiedWriteValues>oneToSet</modifiedWriteValues>
<!-- The write constraint is defined to be that only the values provided by the enumeratedValues below are allowed -->
<writeConstraint>
<useEnumeratedValues>true</useEnumeratedValues>
</writeConstraint>
<!-- there is no side effect on reads, therefore <readAction> is not set -->
<!-- oneBitEnable named enumeration that can be reused in other parts of the description -->
<enumeratedValues derivedFrom="oneBitEnable"></enumeratedValues>
</field>
<field>
<name>TimerCtrl0_Int</name>
<description>Select interrupt line that is triggered by timer overflow.</description>
<!-- the position of the bit field is described in the bitRange style. -->
<bitRange>[4:2]</bitRange>
<enumeratedValues>
<enumeratedValue>
<name>disabled</name>
<description>Timer does not generate interrupts</description>
<value>0</value>
</enumeratedValue>
<enumeratedValue>
<name>int 0</name>
<description>Timer does generate interrupts on interrupt line 0</description>
<value>1</value>
</enumeratedValue>
<enumeratedValue>
<name>int 1</name>
<description>Timer does generate interrupts on interrupt line 1</description>
<value>2</value>
</enumeratedValue>
<enumeratedValue>
<name>int 2</name>
<description>Timer does generate interrupts on interrupt line 2</description>
<value>3</value>
</enumeratedValue>
<enumeratedValue>
<name>int 3</name>
<description>Timer does generate interrupts on interrupt line 3</description>
<value>4</value>
</enumeratedValue>
<enumeratedValue>
<name>int 4</name>
<description>Timer does generate interrupts on interrupt line 4</description>
<value>5</value>
</enumeratedValue>
<!-- this is the default element. All the valid value not listed above (6,7) have the following name and description -->
<enumeratedValue>
<name>reserved</name>
<description>Timer is configured incorrectly and the functionality is considered unpredictable</description>
<isDefault>true</isDefault>
</enumeratedValue>
</enumeratedValues>
</field>
</fields>
</register>
<register>
<name>TimerCounter0</name>
<description>Timer0 16 Bit Counter Register</description>
<addressOffset>0x4</addressOffset>
<size>16</size>
</register>
<!-- a copy of the counter register TimerCounter0 with the name="TimerCounter1" and the addressOffset="0x8" -->
<register derivedFrom="TimerCounter0">
<name>TimerCounter1</name>
<addressOffset>0x6</addressOffset>
</register>
<!-- ... this is a restricted demo example and a real timer peripheral would have more register to be complete -->
</registers>
</peripheral>
<!-- a copy of Timer0 with the name="Timer1 and the baseAddress="0x40000400" -->
<peripheral derivedFrom="Timer0">
<name>Timer1</name>
<baseAddress>0x40000400</baseAddress>
<interrupt>
<name>TIM1_IRQn</name>
<value>35</value>
</interrupt>
</peripheral>
</peripherals>
</device>
Initiallly there was no immediate link but both initiatives had a common goal: Create a sound software development eco-system for Cortex-M based Microcontroller, giving the customers the free choice of devices and software development environments and all resources required for a successful product development in a single location. Meanwhile we have started to generate CMSIS compliant device header files from the same CMSIS-SVD description. We will introduce a small number of additional description tags in the next version of the specification. The benefit is the synchronization between symbols used in the application and the symbols displayed by the debugger.
It is assumed that the description is generated from other sources and therefore such concepts would only complicate the language unnecessarily. It is recommended to use a standard C pre-processor to generate the debug description format from a redundancy optimized description.
This should be specified on a device configuration level and is not specific to the visualization of peripheral details in a System View. Endianess becomes relevant when using bit fields in the CMSIS compliant device header file.
There may have been assumptions made about the structure of the device due to it being developed around a Cortex-M processor. E.g. that all peripherals are assumed to be memory mapped and to reside in a single address space. It is quite likely that the description format may also serve other architectures sufficiently. There is no intent to limit the format to Cortex-M processor based devices.