CMSIS - SVD: Cortex Microcontroller Software Interface Standard - System View Description

# Cortex Microcontroller Software Interface Standard
System View Description

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

- Version 0.91: initial proposal.
- Version 0.92: revised proposal considering forum feedback (e.g. consider IP-XACT constructs and naming scheme)
- Version 1.0: new elements: peripheral version, vendor specific extension section, interrupt mapping information, global peripheral disable condition, naming of register arrays, enhanced naming schemes, etc.
- Version 1.0: SVD versioning and updated schema file
- Version 1.01: Error corrections in the example code. "include" has been removed. Restricted to one device per file.
- Version 1.02: Adding the use case of device header file generation.

## Contents

1. About
2. Motivation
3. Requirements
4. Format
5. Example
6. Questions & Answers

## About

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.

## Motivation

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

- timely and accurate device support provided by a whole range of tool providers
- tool providers become more efficient in supporting a multitude of devices and device variants
- less interaction required between silicon vendors and the tool providers
- silicon provider has control over and maintains the System View Description during the life cycle of the device
- high quality device support in terms of completeness and correctness of device aware debugging
- improved productivity and user experience for the software developer

## Requirements

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.

#### Required content of the description

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:

- minimal addressable unit = smallest series of bits identified by a unique address (e.g. byte-addressable memory)
- register size = number of bits forming a register (ARM Cortex-M usually 32 bits)
- access permission = read and write, read only, write only
- access side effects = accesses by the debugger must be avoided if it has side effects. Some side effects may be reversed by the debugger to compensate for the side effect

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:

- most significant bit = highest bit position of the bit-field in the corresponding register
- least significant bit = lowest bit position of the bit-field within the corresponding register
- access permission = read and write, read only, write only

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:

- value = value of the bit-field that corresponds to the string attribute
- name = short string that describes the semantics of a field when the corresponding value is set
- description = detailed description of the semantics of the field when the corresponding value is set

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:

1. syntactical correctness using XML-Schema checking utilities
2. consistency of the provided information (e.g. multiple registers mapped to the same address, all registers located within the specified address ranges of a peripheral, all fields are within the range of the register size, etc.) by a utility developed by ARM (SVDConv.exe)
3. semantical correctness of the System View Description against the silicon specification executed by the silicon vendor

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.

## Format

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.

#### <device schemaVersion="xs:decimal" xmlns:xs="http://www.w3.org/2001/XMLSchema-instance" xs:noNamespaceSchemaLocation="CMSIS-SVD_Schema_1_0.xsd">

<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>

#### </device>

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).

#### Mandatory items:

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)

#### Optional Items:

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.

#### Example:

    <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.

#### <peripherals>

<peripheral>
...
</peripheral>

...

<peripheral>
...
</peripheral>

#### </peripherals>

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.

#### <peripheral derivedFrom="xs:Name">

<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>

#### </peripheral>

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.

#### Mandatory items:

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)

#### Optional items:

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.

#### Example:

    ...
        <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>

    ...

#### <registers> ... </registers>

This construct sets the frame for all registers contained in a peripheral. This creates container elements which ease-up processing with languages like Java.

#### <register derivedFrom=xs:Name>

<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>

#### </register>

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.

#### Mandatory items:

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.

#### Optional items:

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).

#### Optional attribute:

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.

#### Example:

    ...
           <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>
    ...

#### <fields> ... </fields>

This construct sets the frame for all fields contained in a register. This creates container elements which ease-up processing with languages like Java.

#### <field derivedFrom="xs:Name">

<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>

#### </field>

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.

#### Mandatory items:

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>]

#### Optional items:

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.

#### Example:

    ...
             <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>
    ...

#### <enumeratedValues derivedFrom="xs:Name">

<name>xs:Name</name>
<usage>usageType</usage>
<enumeratedValue>
...
</enumeratedValue>

...

<enumeratedValue>
...
</enumeratedValue>

#### </enumeratedValues>

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.

#### Example:

    ...
               <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>
    ...

#### <enumeratedValue>

<name>xs:name</name>
<description>xs:string</description>
<value>scaledNonNegativeInteger</value>
or
<isDefault>xs:boolean</isDefault>

#### </enumeratedValue>

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

#### Mandatory items:

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

#### Optional item:

description = extended string verbally describing the semantics of the value defined for this enumeratedValue in full detail.

#### Example:

    ...
             <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

Names shall comply with ANSI C variable naming restrictions.

#### Constants

Number constants shall be entered in hexadecimal, decimal or binary format.

- hexadecimal is indicated by a leading "0x"
- 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 "<!--" starts a comment "-->" terminates a comment

## Example

    <?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>

## Questions & Answers

### Is there any relation between the System View Description and the CMSIS standard?

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.

### Why does the format not provide constructs like macros and conditional statements?

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.

### Do we need to consider endianess in the 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.

### Is the System View Description limited to Cortex-M based devices ?

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.