CMSIS-SVD: Cluster Level

| CMSIS-SVD Version 1.3.1 CMSIS System View Description

- Main Page
- Usage and Description
- Reference

Cluster Level
SVD Extensions

Cluster adds an optional sub-level within the CMSIS SVD registers level. A cluster describes a sequence of neighboring registers within a peripheral. A cluster specifies the addressOffset relative to the baseAddress of the peripheral. All register elements within a cluster specify their addressOffset relative to the cluster base address (peripheral:baseAddress + cluster:addressOffset). Multiple <register/> and <cluster> sections may occur in any order. Since version 1.3 of the specification the nesting of <cluster> elements is supported. This means, that within a <cluster> section any number of <register> and <cluster> sections may occur. Nested cluster express hierarchical structures of registers. It is predominantely targeted at the generation of device header files where it allows to create C data structure within the peripheral structure type instead of a flat list of registers. Note that you can also specify an array of a cluster using the <dim> element.

    <registers>

        <clusterderivedFrom=identifierType>

            <!-- dimElementGroup -->
            <dim>scaledNonNegativeInteger</dim>
            <dimIncrement>scaledNonNegativeInteger</dimIncrement>
            <dimIndex>dimIndexType</dimIndex>
            <!-- end of dimElementGroup -->

            <name>identifierType</name>
            <description>xs:string</description>

            <headerStructName>identifierType</headerStructName>
            <alternateCluster>identifierType</alternateCluster>

            <addressOffset>scaledNonNegativeInteger</addressOffset>

            <cluster> ... </cluster>
            <register> ... </register>
                ...
        </cluster>
        ...
        <register>
            ...
        </register>
        <cluster>
            ...
        </cluster>

    <registers>

Attribute Name | Description | Type | Occurrence
--- | --- | --- | ---
derivedFrom | Specifies the name of the cluster from which to inherit the data. Elements being specified underneath will override the inherited values. Remarks: When deriving a cluster, it is mandatory to specify at least the name, the description, and the addressOffset. | registerType | 0..1
Element Name | Description | Type | Occurrence
See dimElementGroup for details.
dim | The value defines the number of elements in an array of clusters. | scaledNonNegativeInteger | 1..1
dimIncrement | If dim is specified, this element becomes mandatory. The element specifies the address increment in between two neighboring clusters of the cluster array in the address map. | scaledNonNegativeInteger | 1..1
dimIndex | Specifies the substrings that replaces the [%s] placeholder within the cluster name. By default, the index is a decimal value starting with 0 for the first cluster element. | dimIndexType | 0..1
name | String that identifies the cluster. Register names are required to be unique within the scope of a peripheral. Specify [%s] for generating an array in the device header file. | identifierType | 1..1
description | String describing the details of the register. | xs:string | 0..1
alternateCluster | This tag needs to specify the name of the original description of the register sequence if this cluster provides an alternative description. Otherwise the SVDConv will issue errors. | identifierType | 0..1
headerStructName | This tag specifies the struct type name in the device header file. If not specified, then the name of the cluster will be used. | identifierType | 0..1
addressOffset | Value defining the cluster address relative to the baseAddress defined by the peripheral of the register. | scaledNonNegativeInteger | 1..1
register | register description | registerType | 0..*
cluster | cluster description | clusterType | 0..*

# Example:

<cluster>
<dim>4</dim>
<dimIncrement>8</dimIncrement>
<dimIndex>0-3</dimIndex>
<name>TX[%s]</name>
<description>Grouping of Transfer data and address</description>
<addressOffset>0x40</addressOffset>
<register>
<name>TX_DATA</name>
...
<addressOffset>0x0</addressOffset>
...
</register>
<register>
<name>TX_ADDR</name>
...
<addressOffset>0x4</addressOffset>
...
</register>
</cluster>

The example above describes an array of type TX with 4 elements. TX is a cluster of two consecutive registers with 4 elements. The device header file looks like this:

typedef struct {
...
struct {
__IO uint32_t TX_DATA;
__IO uint32_t TX_ADDR;
} TX[4];
...
} ..._Type;