diff options
Diffstat (limited to 'utils/regtools/desc/spec-1.0.txt')
-rw-r--r-- | utils/regtools/desc/spec-1.0.txt | 140 |
1 files changed, 140 insertions, 0 deletions
diff --git a/utils/regtools/desc/spec-1.0.txt b/utils/regtools/desc/spec-1.0.txt new file mode 100644 index 0000000000..3c28154a1f --- /dev/null +++ b/utils/regtools/desc/spec-1.0.txt | |||
@@ -0,0 +1,140 @@ | |||
1 | This file describes the format of the register map based on XML. | ||
2 | |||
3 | Root | ||
4 | ---- | ||
5 | As any XML document, the content of the file should be enclosed in a "xml" tag. | ||
6 | |||
7 | Example: | ||
8 | <?xml version="1.0"?> | ||
9 | <!-- desc --> | ||
10 | </xml> | ||
11 | |||
12 | Root Element: root | ||
13 | ------------------ | ||
14 | The root element can either be "soc" tag if the file contains a single description, | ||
15 | or "root" with no properties and one or more "soc" tags as children. | ||
16 | |||
17 | Element: soc | ||
18 | ------------ | ||
19 | The XML can contain one or more SoC description. Each description is enclosed in | ||
20 | a "soc" tag. The following properties are defined: | ||
21 | - "name" (mandatory,string): the mnemonic of the SoC. | ||
22 | - "desc" (optional,string): a textual description of the SoC. | ||
23 | |||
24 | Example: | ||
25 | <soc name="stmp3700" desc="STMP3700"> | ||
26 | <!-- soc desc --> | ||
27 | </soc> | ||
28 | |||
29 | Element: soc.dev | ||
30 | ---------------- | ||
31 | Each SoC can contain any number of devices. Each device is enclosed in a "dev" | ||
32 | tag. A device is logical group of registers and doesn't have a precise meaning. | ||
33 | If a SoC has several copies of the same device at different addresses (SSP1, SSP2 | ||
34 | for example), then only one copy has to be described since a device can have | ||
35 | several address (see soc.dev.addr section). The following properties are defined: | ||
36 | - "name" (mandatory,string): the mnemonic of the device. | ||
37 | - "long_name" (optional,string): a short description of the device. | ||
38 | - "desc" (optional,string): a long description of the SoC. | ||
39 | - "version" (optional,string): version of the register description for this device. | ||
40 | |||
41 | Example: | ||
42 | <dev name="APBH" long_name="APHB DMA" desc="AHB-to-APBH Bridge with DMA" version="3.2.0"> | ||
43 | <!-- dev desc> | ||
44 | </dev> | ||
45 | |||
46 | Element: soc.dev.addr | ||
47 | --------------------- | ||
48 | Each device can have one or more addresses associated with it. Each address is | ||
49 | enclosed in a "addr" tag. This allows to describe several blocks are once on SoCs | ||
50 | where several copies of the same block exist at different addresses. | ||
51 | The following properties are defined: | ||
52 | - "name" (mandatory,string): unique name of this instance of the device. | ||
53 | - "addr" (mandatory,integer): base address of this instance of the device. | ||
54 | |||
55 | Example: | ||
56 | <addr name="SSP1" addr="0x80010000" /> | ||
57 | <addr name="SSP2" addr="0x80034000" /> | ||
58 | |||
59 | Element: soc.dev.reg | ||
60 | -------------------- | ||
61 | Each device can contain any number of registers. Each register is enclosed in a | ||
62 | "reg" tag. If a SoC has several copies of the same register at different addresses | ||
63 | (INTERRUPT0, INTERRUPT1 for example), then only one copy has to be described since | ||
64 | a register can have several address (see soc.dev.reg.addr section). | ||
65 | The following properties are defined: | ||
66 | - "name" (mandatory,string): the mnemonic of the register. | ||
67 | - "sct" (optional,"yes" or "no"): STMP specific attribute to specify the existence | ||
68 | of the SCT variants of this register. | ||
69 | As a shortcut, in the case the register has a single address, one can add one more | ||
70 | property: | ||
71 | - "addr" (optional,integer): base address of this instance of the register. | ||
72 | |||
73 | Example: | ||
74 | <reg name="TIMCTRLn" sct="yes"> | ||
75 | <!-- reg desc --> | ||
76 | </reg> | ||
77 | |||
78 | The address shortcut has the following standard translation: | ||
79 | <reg name="GPIO_PADR" addr="0x00"> | ||
80 | <!-- bla --> | ||
81 | </reg> | ||
82 | is equivalent to: | ||
83 | <reg name="GPIO_PADR"> | ||
84 | <addr name="GPIO_PADR" addr="0x00"> | ||
85 | <!-- bla --> | ||
86 | </reg> | ||
87 | |||
88 | Element: soc.dev.reg.addr | ||
89 | ------------------------- | ||
90 | Each device can have one or more addresses associated with it. Each address | ||
91 | is enclosed in a "addr" tag. This allows to describe several register at once on | ||
92 | SoCs where a similar register is replicated several times. | ||
93 | The following properties are defined: | ||
94 | - "name" (mandatory,string): unique name of this instance of the register. | ||
95 | - "addr" (mandatory,integer): base address of this instance of the register. | ||
96 | |||
97 | Example: | ||
98 | <addr name="TIMCTRL0" addr="0x20" /> | ||
99 | <addr name="TIMCTRL1" addr="0x40" /> | ||
100 | <addr name="TIMCTRL2" addr="0x60" /> | ||
101 | |||
102 | Element: soc.dev.reg.formula | ||
103 | ---------------------------- | ||
104 | In the special case where the addresses of the register follow a pattern, an | ||
105 | explicit formula can be described as part of the format. There is no specific | ||
106 | requirement on the formula except that the register addresses be indexed by | ||
107 | a variable "n" which range from 0 to N-1 where N is the number of address. | ||
108 | The formula is not used for anything except header generation where it is | ||
109 | handy to have a formula rather a long list of conditionals. | ||
110 | The following properties are defined: | ||
111 | - "string" (mandatory,string): the equation describing the addresses. | ||
112 | |||
113 | Example: | ||
114 | <formula string="0x20+n*0x20"/> | ||
115 | |||
116 | Element: soc.dev.reg.field | ||
117 | -------------------------- | ||
118 | Each register can be further divided into disjoints fields. Each field | ||
119 | is enclosed in a "field" tag. A field is defined as a contiguous set | ||
120 | of bits in the register. The following properties are defined: | ||
121 | - "name" (mandatory,string): the mnemonic of field | ||
122 | - "bitrange" (mandatory,string): the bit range of the field written as | ||
123 | "n-m" where n and m are integers giving the most (resp. least) significant | ||
124 | bit of the field. | ||
125 | |||
126 | Example: | ||
127 | <field name="PRESCALE" bitrange="5:4"> | ||
128 | <!-- field desc --> | ||
129 | </field> | ||
130 | |||
131 | Element: soc.dev.reg.field.value | ||
132 | -------------------------------- | ||
133 | Each field can describe a list of named values in cases where this is appropriate. | ||
134 | Each value is enclosed in a "value" tag. The following properties are defined: | ||
135 | - "name" (mandatory,string): the mnemonic of the value. | ||
136 | - "value" (mandatory,integer): the associated value. | ||
137 | |||
138 | Example: | ||
139 | <value name="DIV_BY_1" value="0x0" /> | ||
140 | <value name="DIV_BY_2" value="0x1" /> | ||