diff options
Diffstat (limited to 'utils/regtools/desc/spec-2.0.txt')
-rw-r--r-- | utils/regtools/desc/spec-2.0.txt | 373 |
1 files changed, 373 insertions, 0 deletions
diff --git a/utils/regtools/desc/spec-2.0.txt b/utils/regtools/desc/spec-2.0.txt new file mode 100644 index 0000000000..79b9f6be44 --- /dev/null +++ b/utils/regtools/desc/spec-2.0.txt | |||
@@ -0,0 +1,373 @@ | |||
1 | This file describes the format of the register map based on XML, version 2.0. | ||
2 | |||
3 | 1) Overview | ||
4 | ----------- | ||
5 | |||
6 | 1.1) Nodes and instances | ||
7 | ------------------------ | ||
8 | |||
9 | This specification is based on the concept of "nodes". Nodes are containers | ||
10 | which can contain other nodes and/or a register. Each node can have one or more | ||
11 | addresses (addresses are always relative to the parent node). The idea is that | ||
12 | this hierarchy of nodes generates a number of addresses recursively. The example | ||
13 | below outlines this idea: | ||
14 | |||
15 | <node> | ||
16 | <name>N</name> | ||
17 | <instance> | ||
18 | <name>A</name> | ||
19 | <address>X</address> | ||
20 | </instance> | ||
21 | <instance> | ||
22 | <name>B</name> | ||
23 | <address>Y</address> | ||
24 | </instance> | ||
25 | <!-- HERE --> | ||
26 | </node> | ||
27 | |||
28 | This example creates one node named N and two instances named A and B, | ||
29 | at respective addresses X and Y. This means that all subnodes of this node will | ||
30 | have two copies: one relative to X, which path will be prefixed by "A", and | ||
31 | one relative to Y, which path will be prefixed by "B". | ||
32 | This example below explores this idea in details: | ||
33 | |||
34 | <!-- HERE --> | ||
35 | <node> | ||
36 | <name>S_N</name> | ||
37 | <instance> | ||
38 | <name>C</name> | ||
39 | <address>U</address> | ||
40 | </instance> | ||
41 | <instance> | ||
42 | <name>D</name> | ||
43 | <address>V</address> | ||
44 | </instance> | ||
45 | </node> | ||
46 | |||
47 | In this example, N generates two copies of the sub-node S_N. | ||
48 | The sub-node S_N generates two instances C and D. The whole hierarchy thus generates | ||
49 | four instances: | ||
50 | - A.C at X+U | ||
51 | - A.D at X+V | ||
52 | - B.C at Y+U | ||
53 | - B.D at Y+V | ||
54 | |||
55 | As a note for later, notice that there really are two hierarchies in parallel: | ||
56 | - the node hierarchy: it is composed of N and N.S_N | ||
57 | - the instance hierarchy: it is made up of A, B, A.C, A.D, B.C and B.D | ||
58 | |||
59 | 1.2) Ranges | ||
60 | ----------- | ||
61 | |||
62 | To make things more useful, in particular in case of multiple copies of a register, | ||
63 | we introduce the concept of range addresses with an example: | ||
64 | |||
65 | <node> | ||
66 | <name>N</name> | ||
67 | <instance> | ||
68 | <name>A</name> | ||
69 | <range> | ||
70 | <first>1</first> | ||
71 | <count>5</count> | ||
72 | <base>0x1000</base> | ||
73 | <stride>0x100</stride> | ||
74 | </range> | ||
75 | </instance> | ||
76 | <node> | ||
77 | <name>NN</name> | ||
78 | <instance> | ||
79 | <name>E</name> | ||
80 | <address>0x4</address> | ||
81 | </instance> | ||
82 | </node> | ||
83 | </node> | ||
84 | |||
85 | A range describes a contiguous set of adresses, indexed by a number. One can | ||
86 | specify the first number in the range, and the number of copies. In the case | ||
87 | of a regular pattern (base + n * stride), we can specify a stride | ||
88 | to compute the address of the next copy. In this example, the top-level | ||
89 | nodes generates five copies which path is A[1], A[2], ..., A[5] | ||
90 | and which addresses are 0x1000+1*0x100, 0x1000+2*0x100, ..., 0x1000+5*0x100. | ||
91 | If we add the sub-node to the picture, for each copy we create a instance E | ||
92 | we offset 0x4 from the parent. Overall this generates 5 instances: | ||
93 | - A[1].E at 0x1000+1*0x100+0x4 = 0x1104 | ||
94 | - A[2].E at 0x1000+2*0x100+0x4 = 0x1204 | ||
95 | - A[3].E at 0x1000+3*0x100+0x4 = 0x1304 | ||
96 | - A[4].E at 0x1000+4*0x100+0x4 = 0x1404 | ||
97 | - A[5].E at 0x1000+5*0x100+0x4 = 0x1504 | ||
98 | Note that the intermediate path also define instances, so there are 5 additional | ||
99 | instances in reality: | ||
100 | - A[1] at 0x1100 | ||
101 | - A[2] at 0x1200 | ||
102 | - A[3] at 0x1300 | ||
103 | - A[4] at 0x1400 | ||
104 | - A[5] at 0x1500 | ||
105 | |||
106 | For the record, there is a more general way of specifying a range when it does | ||
107 | not follow a nice regular pattern. One can specify a formula where the parameter | ||
108 | is the index. There are no restrictions on the formula except that it must use | ||
109 | usual arithmetic operators. The example below illustrate such a use: | ||
110 | |||
111 | <node> | ||
112 | <name>N</name> | ||
113 | <instance> | ||
114 | <name>F</name> | ||
115 | <range> | ||
116 | <first>0</first> | ||
117 | <count>4</count> | ||
118 | <formula variable="n">0x50+(n/2)*0x100+(n%2)*0x10</formula> | ||
119 | </range> | ||
120 | </instance> | ||
121 | </node> | ||
122 | |||
123 | In this example we generate four nodes F[0], ..., F[3] with a formula. Here "/" | ||
124 | is the euclidian division and "%" is the modulo operator. Note the use of an | ||
125 | attribute to specify which variable represents the index. The generated addresses | ||
126 | are: | ||
127 | - F[0] at 0x50+(0/2)*0x100+(0%2)*0x10 = 0x50 | ||
128 | - F[1] at 0x50+(1/2)*0x100+(1%2)*0x10 = 0x50+0x10 = 0x60 | ||
129 | - F[2] at 0x50+(2/2)*0x100+(2%2)*0x10 = 0x50+0x100 = 0x150 | ||
130 | - F[3] at 0x50+(3/2)*0x100+(3%2)*0x10 = 0x50+0x100+0x10 = 0x160 | ||
131 | |||
132 | 1.3) Node description | ||
133 | --------------------- | ||
134 | |||
135 | For documentation purposes, node can of course carry some description, as well | ||
136 | as instances. More precisely, nodes can have a title, that is a short description | ||
137 | very much like a chapter title, and a description, this is a free form and potentially | ||
138 | lengthy description of the node. Instances too can have a title and a description. | ||
139 | The following example illustrates this: | ||
140 | |||
141 | <node> | ||
142 | <name>icoll</name> | ||
143 | <title>DMA Controller</title> | ||
144 | <desc>The DMA controller provides uniform DMA facilities to transfer data from | ||
145 | and to peripherals. It uses memory-mapped tables and support chained | ||
146 | transfers.</desc> | ||
147 | <instance> | ||
148 | <name>AHB_DMAC</name> | ||
149 | <address>0x80000000</address> | ||
150 | <title>AHB DMA Controller</title> | ||
151 | <desc>The AHB DMA controller provides DMA facilities for the peripherals | ||
152 | on the AHB bus like the SSP and PIX engines.</desc> | ||
153 | </instance> | ||
154 | <instance> | ||
155 | <name>APB_DMAC</name> | ||
156 | <address>0x8001000</address> | ||
157 | <title>APB DMA Controller</title> | ||
158 | <desc>The APB DMA controller provides DMA facilities for the peripherals | ||
159 | on the APB bus like the I2C and PCM engines.</desc> | ||
160 | </instance> | ||
161 | </node> | ||
162 | |||
163 | 1.4) Register description | ||
164 | -------------------------- | ||
165 | |||
166 | The goal of the register description is of course to describe registers! | ||
167 | To see how registers relate to the node hierarchy, see 1.5, this section focuses | ||
168 | only the description only. | ||
169 | |||
170 | A register carries a lot of information, which is organise logically. A register | ||
171 | can have a width, in bits. By default registers are assumed to be 32-bit wide. | ||
172 | The most useful feature of register description is to describe the fields of | ||
173 | the registers. Each field has a name, a start position and a width. Fields | ||
174 | can also carry a description. Finally, each field can specify enumerated values, | ||
175 | that is named values, for convenience. Enumerated values have a name, a value | ||
176 | and an optional description. The example below illustrates all these concepts: | ||
177 | |||
178 | <register> | ||
179 | <width>8</width> | ||
180 | <field> | ||
181 | <name>MODE</name> | ||
182 | <desc>Interrupt mode</desc> | ||
183 | <position>0</position> | ||
184 | <width>2</width> | ||
185 | <enum> | ||
186 | <name>DISABLED</name> | ||
187 | <desc>Interrupt is disabled</desc> | ||
188 | <value>0</value> | ||
189 | </enum> | ||
190 | <enum> | ||
191 | <name>ENABLED</name> | ||
192 | <desc>Interrupt is enabled</desc> | ||
193 | <value>1</value> | ||
194 | </enum> | ||
195 | <enum> | ||
196 | <name>NMI</name> | ||
197 | <desc>Interrupt is non-maskable</desc> | ||
198 | <value>2</value> | ||
199 | </enum> | ||
200 | </field> | ||
201 | <field> | ||
202 | <name>PRIORITY</name> | ||
203 | <desc>Interrupt priority, lower values are more prioritized.</desc> | ||
204 | <position>2</position> | ||
205 | <width>2</width> | ||
206 | </field> | ||
207 | <field> | ||
208 | <name>ARM_MODE</name> | ||
209 | <desc>Select between ARM's FIQ and IRQ mode</desc> | ||
210 | <position>4</position> | ||
211 | <width>1</width> | ||
212 | <enum> | ||
213 | <name>IRQ</name> | ||
214 | <value>0</value> | ||
215 | </enum> | ||
216 | <enum> | ||
217 | <name>FIQ</name> | ||
218 | <value>1</value> | ||
219 | </enum> | ||
220 | </field> | ||
221 | </register> | ||
222 | |||
223 | In this example, the 8-bit registers has three fields: | ||
224 | - MODE(1:0): it has three named values DISABLED(0), ENABLED(1) and NMI(2) | ||
225 | - PRIORITY(2:1): it has no named values | ||
226 | - ARM_MODE(3): it has two named values IRQ(0) and FIQ(1) | ||
227 | |||
228 | 1.5) Register inheritance | ||
229 | ------------------------- | ||
230 | |||
231 | The node hierarchy specifies instances, that is pairs of (path,address), | ||
232 | and the register description describes the internal of a register. The placement | ||
233 | of the register descriptions in the node hierarchy will specify which registers | ||
234 | can be found at each address. More precisely, if a node contains a register | ||
235 | description, it means that this node's and all sub-nodes' instances are registers | ||
236 | following the description. It is forbidden for a node to contain a register | ||
237 | description if one of its parents already contains one. The example below | ||
238 | will make this concept clearer (for readability, we omitted some of the tags): | ||
239 | |||
240 | <node> | ||
241 | <name>dma</name> | ||
242 | <instance><name>DMAC</name><address>0x80000000</address></instance> | ||
243 | <node> | ||
244 | <instance><name>PCM_CHAN</name><address>0x0</address></instance> | ||
245 | <instance><name>I2C_CHAN</name><address>0x10</address></instance> | ||
246 | <register><!--- blabla --></register> | ||
247 | <node> | ||
248 | <name>sct</name> | ||
249 | <instance><name>SET</name><address>0x4</address></instance> | ||
250 | <instance><name>CLR</name><address>0x8</address></instance> | ||
251 | <instance><name>TOG</name><address>0xC</address></instance> | ||
252 | </node> | ||
253 | </node> | ||
254 | </node> | ||
255 | |||
256 | This example describes one register (let's call it blabla) and 9 instances: | ||
257 | - DMAC at 0x80000000, no register | ||
258 | - DMAC.PCM_CHAN at 0x80000000, register blabla | ||
259 | - DMAC.PCM_CHAN.SET at 0x80000004, register blabla | ||
260 | - DMAC.PCM_CHAN.CLR at 0x80000008, register blabla | ||
261 | - DMAC.PCM_CHAN.TOG at 0x8000000C, register blabla | ||
262 | - DMAC.I2C_CHAN at 0x80000010, register blabla | ||
263 | - DMAC.I2C_CHAN.SET at 0x80000014, register blabla | ||
264 | - DMAC.I2C_CHAN.CLR at 0x80000018, register blabla | ||
265 | - DMAC.I2C_CHAN.TOG at 0x8000001C, register blabla | ||
266 | |||
267 | 1.6) Soc description | ||
268 | -------------------- | ||
269 | |||
270 | The description file must also specify some information about the system-on-chip | ||
271 | itself. The entire description, including nodes, is contained in a "soc" tag | ||
272 | which must at least specify the soc name. It can optionally specify the title | ||
273 | and description, as well as the author(s) of the description, the ISA and | ||
274 | the version. | ||
275 | |||
276 | <soc> | ||
277 | <name>vsoc</name> | ||
278 | <title>Virtual SOC</title> | ||
279 | <desc>Virtual SoC is a nice and powerful chip.</desc> | ||
280 | <author>Amaury Pouly</author> | ||
281 | <isa>ARM</isa> | ||
282 | <version>0.5</version> | ||
283 | <!-- put nodes below --> | ||
284 | </soc> | ||
285 | |||
286 | 2) Specification | ||
287 | ---------------- | ||
288 | |||
289 | Root | ||
290 | ---- | ||
291 | As any XML document, the content of the file should be enclosed in a "xml" tag. | ||
292 | The root element must be "soc" tag. | ||
293 | |||
294 | Example: | ||
295 | <?xml version="1.0"?> | ||
296 | <!-- desc --> | ||
297 | </xml> | ||
298 | |||
299 | Element: soc | ||
300 | ------------ | ||
301 | It must contain the following tags: | ||
302 | - name: name of soc, only made of alphanumerical characters | ||
303 | It can contain at most one of each of the following tags: | ||
304 | - title: one line description of the soc | ||
305 | - desc: free form description of the soc | ||
306 | - isa: instruction set assembly | ||
307 | - version: version of the description | ||
308 | It can contain any number of the following tags: | ||
309 | - author: author of the description | ||
310 | - node: node description | ||
311 | |||
312 | Element: node | ||
313 | ------------- | ||
314 | It must contain the following tags: | ||
315 | - name: name of node, only made of alphanumerical characters | ||
316 | It can contain at most one of each of the following tags: | ||
317 | - title: one line description of the node | ||
318 | - desc: free form description of the node | ||
319 | - register: register description | ||
320 | It can contain any number of the following tags: | ||
321 | - instance: author of the description | ||
322 | - node: node description | ||
323 | |||
324 | Element: instance | ||
325 | ----------------- | ||
326 | It must contain the following tags: | ||
327 | - name: name of instance, only made of alphanumerical characters | ||
328 | It can contain at most one of each of the following tags: | ||
329 | - title: one line description of the instance | ||
330 | - desc: free form description of the instance | ||
331 | - address: address for a single instance (non-negative number) | ||
332 | - range: address range for multiple instances | ||
333 | Note that address and range are mutually exclusive, and at least one of them | ||
334 | must exists. | ||
335 | |||
336 | Element: range | ||
337 | -------------- | ||
338 | It must contain the following tags: | ||
339 | - first: index of the first instance (non-negative number) | ||
340 | - count: number of instances (positive number) | ||
341 | It can contain at most one of each of the following tags: | ||
342 | - base: base address (non-negative number) | ||
343 | - stride: stride (number) | ||
344 | - formula: free-form formula, must have a "variable" attribute | ||
345 | Note that stride and formula are mutually exclusive, and at least one of them | ||
346 | must exists. If stride is specified and base is omitted, it is taken to be 0. | ||
347 | |||
348 | Element: register | ||
349 | ----------------- | ||
350 | It can contain at most one of each of the following tags: | ||
351 | - width: width in bits (positive number) | ||
352 | It can contain any number of the following tags: | ||
353 | - field: field description | ||
354 | |||
355 | Element: field | ||
356 | -------------- | ||
357 | It must contain the following tags: | ||
358 | - name: name of field, only made of alphanumerical characters | ||
359 | - position: least significant bit | ||
360 | It can contain at most one of each of the following tags: | ||
361 | - desc: free form description of the instance | ||
362 | - width: width in bits | ||
363 | It can contain any number of the following tags: | ||
364 | - enum: enumerated value | ||
365 | If the width is not specified, it is assumed to be 1. | ||
366 | |||
367 | Element: enum | ||
368 | ------------- | ||
369 | It must contain the following tags: | ||
370 | - name: name of field, only made of alphanumerical characters | ||
371 | - value: value (non-negative, must fit into the field's width) | ||
372 | It can contain at most one of each of the following tags: | ||
373 | - desc: free form description of the instance \ No newline at end of file | ||