Cluster Level (New)

Cluster adds a new and optional sub-level to the CMSIS SVD registers level. A cluster describes a sequence of registers within a peripheral. A cluster has an base offset relative to the base address of the peripheral. All registers within a cluster specify their address offset relative to the cluster base address. Register and cluster sections can occur in an arbitrary order. This feature, targeted at the generation of device header files, is useful to create a C data structure within the peripheral structure type, rather than describing all registers of a peripheral in a flat structure.

---

<registers> 

    <cluster derivedFrom=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>

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

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;