Cluster Level

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;