summaryrefslogtreecommitdiffstats
path: root/utils/regtools/desc/spec-1.0.txt
blob: 3c28154a1ff3a1bdd94f05c67da5a304bf5677b4 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
This file describes the format of the register map based on XML.

Root
----
As any XML document, the content of the file should be enclosed in a "xml" tag.

Example:
<?xml version="1.0"?>
<!-- desc -->
</xml>

Root Element: root
------------------
The root element can either be "soc" tag if the file contains a single description,
or "root" with no properties and one or more "soc" tags as children.

Element: soc
------------
The XML can contain one or more SoC description. Each description is enclosed in
a "soc" tag. The following properties are defined:
- "name" (mandatory,string): the mnemonic of the SoC.
- "desc" (optional,string): a textual description of the SoC.

Example:
<soc name="stmp3700" desc="STMP3700">
<!-- soc desc -->
</soc>

Element: soc.dev
----------------
Each SoC can contain any number of devices. Each device is enclosed in a "dev"
tag. A device is logical group of registers and doesn't have a precise meaning.
If a SoC has several copies of the same device at different addresses (SSP1, SSP2
for example), then only one copy has to be described since a device can have
several address (see soc.dev.addr section). The following properties are defined:
- "name" (mandatory,string): the mnemonic of the device.
- "long_name" (optional,string): a short description of the device.
- "desc" (optional,string): a long description of the SoC.
- "version" (optional,string): version of the register description for this device.

Example:
<dev name="APBH" long_name="APHB DMA" desc="AHB-to-APBH Bridge with DMA" version="3.2.0">
<!-- dev desc>
</dev>

Element: soc.dev.addr
---------------------
Each device can have one or more addresses associated with it. Each address is
enclosed in a "addr" tag. This allows to describe several blocks are once on SoCs
where several copies of the same block exist at different addresses.
The following properties are defined:
- "name" (mandatory,string): unique name of this instance of the device.
- "addr" (mandatory,integer): base address of this instance of the device.

Example:
<addr name="SSP1" addr="0x80010000" />
<addr name="SSP2" addr="0x80034000" />

Element: soc.dev.reg
--------------------
Each device can contain any number of registers. Each register is enclosed in a
"reg" tag. If a SoC has several copies of the same register at different addresses
(INTERRUPT0, INTERRUPT1 for example), then only one copy has to be described since
a register can have several address (see soc.dev.reg.addr section).
The following properties are defined:
- "name" (mandatory,string): the mnemonic of the register.
- "sct" (optional,"yes" or "no"): STMP specific attribute to specify the existence
  of the SCT variants of this register.
As a shortcut, in the case the register has a single address, one can add one more
property:
- "addr" (optional,integer): base address of this instance of the register.

Example:
<reg name="TIMCTRLn" sct="yes">
<!-- reg desc -->
</reg>

The address shortcut has the following standard translation:
<reg name="GPIO_PADR" addr="0x00">
<!-- bla -->
</reg>
is equivalent to:
<reg name="GPIO_PADR">
<addr name="GPIO_PADR" addr="0x00">
<!-- bla -->
</reg>

Element: soc.dev.reg.addr
-------------------------
Each device can have one or more addresses associated with it. Each address
is enclosed in a "addr" tag. This allows to describe several register at once on
SoCs where a similar register is replicated several times.
The following properties are defined:
- "name" (mandatory,string): unique name of this instance of the register.
- "addr" (mandatory,integer): base address of this instance of the register.

Example:
<addr name="TIMCTRL0" addr="0x20" />
<addr name="TIMCTRL1" addr="0x40" />
<addr name="TIMCTRL2" addr="0x60" />

Element: soc.dev.reg.formula
----------------------------
In the special case where the addresses of the register follow a pattern, an
explicit formula can be described as part of the format. There is no specific
requirement on the formula except that the register addresses be indexed by
a variable "n" which range from 0 to N-1 where N is the number of address.
The formula is not used for anything except header generation where it is
handy to have a formula rather a long list of conditionals.
The following properties are defined:
- "string" (mandatory,string): the equation describing the addresses.

Example:
<formula string="0x20+n*0x20"/>

Element: soc.dev.reg.field
--------------------------
Each register can be further divided into disjoints fields. Each field
is enclosed in a "field" tag. A field is defined as a contiguous set
of bits in the register. The following properties are defined:
- "name" (mandatory,string): the mnemonic of field
- "bitrange" (mandatory,string): the bit range of the field written as
  "n-m" where n and m are integers giving the most (resp. least) significant
  bit of the field.

Example:
<field name="PRESCALE" bitrange="5:4">
<!-- field desc -->
</field>

Element: soc.dev.reg.field.value
--------------------------------
Each field can describe a list of named values in cases where this is appropriate.
Each value is enclosed in a "value" tag. The following properties are defined:
- "name" (mandatory,string): the mnemonic of the value.
- "value" (mandatory,integer): the associated value.

Example:
<value name="DIV_BY_1" value="0x0" />
<value name="DIV_BY_2" value="0x1" />