projects / microwatt.git / blob
? search:


fc56ba8a3712f6cff9d10001511db5ad2ab752e9
[microwatt.git] / README.aquila.md
1 # ARCHITECTURE
2
3 Aquila is a Wishbone-compatible, 32-bit, LPC slave device with 64-bit DMA support.
4
5 Aquila provides two interfaces to the system:
6 1. A 32-bit Wishbone slave interface with IRQ support. All functions are supported on this interface in a CPU-interactive mode.
7 2. A 64-bit Wishbone master (DMA) interface, providing high speed data access and configurable DMA access protection ranges.
8
9 # USAGE
10
11 ## General Usage
12
13 TODO
14
15 Usage is complex, given the nature of the protocols and overall external host involvement. Some documentation exists in the form of working firmware for a POWER9 host system, for example here:
16
17 https://gitlab.raptorengineering.com/kestrel-collaboration/kestrel-firmware/zephyr-firmware/-/blob/master/kestrel/src/kestrel.c
18
19 # REGISTER MAP
20
21 ## [0x00 - 0x07] Device ID
22
23 Device make/model unique identifier for PnP functionality
24 Fixed value: 0x7c5250544c504353
25
26 ## [0x08 - 0x0b] Device version
27
28 Device revision (stepping)
29
30 | Bits | Description |
31 |-------|---------------|
32 | 31:16 | Major version |
33 | 15:8 | Minor version |
34 | 7:0 | Patch level |
35
36 Can be used to set divisor to meet specific SPI Flash clock frequency requirements
37
38 ## [0x0c - 0x0f] Control register 1
39
40 Default: 0x00000000
41
42 Definitions:
43 - CIRQ: Interrupt request as wired to Wishbone-attached internal CPU
44 - HIRQ: Interrupt request as wired to external host platform over LPC serial IRQ line
45
46 | Bits | Description |
47 |-------|---------------------------------------------------------------------------------------------------|
48 | 31:20 | Reserved |
49 | 19 | Fire CIRQ on LPC I/O cycle access |
50 | 18 | Fire CIRQ on LPC TPM cycle access |
51 | 17 | Fire CIRQ on LPC firmware cycle access |
52 | 16 | Enable BMC BT interface CIRQ |
53 | 15:8 | IPMI BT I/O port address |
54 | 7 | Use alternate IPMI BT HIRQ (IRQ #11) instead of standard IPMI BT HIRQ (IRQ #10) |
55 | 6 | Enable IPMI BT host interface |
56 | 5 | Enable VUART2 host interface |
57 | 4 | Enable VUART1 host interface |
58 | 3 | Allow LPC I/O cycles from host |
59 | 2 | Allow LPC TPM cycles from host |
60 | 1 | Allow LPC firmware cycles from host |
61 | 0 | Global CIRQ enable, 0 disables all CIRQs, 1 allows any enabled CIRQs to assert main LPC core CIRQ |
62
63 ## [0x10 - 0x13] Control register 2
64
65 Default: 0x00000000
66
67 This register is used only in the CPU-interactive transfer mode. Any activate DMA ranges will take precendence over this register for HOST firmware cycles.
68
69 Definitions:
70 - CPU: Wishbone-attached internal CPU
71 - HOST: External host platform attached via LPC
72
73 | Bits | Description |
74 |-------|----------------------------------------------------------------------------------------------------|
75 | 31:16 | Reserved |
76 | 15:8 | LPC cycle data out (CPU to HOST) |
77 | 7:2 | Reserved |
78 | 1 | Signal LPC bus error to HOST if asserted when bit 0 asserted |
79 | 0 | Assert to transfer data in bits [15:8], [1] to HOST. Completes the active LPC cycle on assertion. |
80
81 ## [0x14 - 0x17] LPC address range 1 configuration register 1
82
83 Default: 0x00000000
84
85 | Bits | Description |
86 |------|-------------------------------------|
87 | 31 | Enable this LPC slave address range |
88 | 30 | Allow I/O cycles for this range |
89 | 29 | Allow TPM cycles for this range |
90 | 28 | Reserved |
91 | 27:0 | LPC range start address |
92
93 ## [0x18 - 0x1b] LPC address range 1 configuration register 2
94
95 Default: 0x00000000
96
97 | Bits | Description |
98 |-------|-----------------------|
99 | 31:28 | Reserved |
100 | 27:0 | LPC range end address |
101
102 ## [0x1c - 0x1f] LPC address range 2 configuration register 1
103
104 Default: 0x00000000
105
106 Same bit mapping as "LPC address range 1 configuration register 1"
107
108 ## [0x20 - 0x23] LPC address range 2 configuration register 2
109
110 Default: 0x00000000
111
112 Same bit mapping as "LPC address range 1 configuration register 2"
113
114 ## [0x24 - 0x27] LPC address range 3 configuration register 1
115
116 Default: 0x00000000
117
118 Same bit mapping as "LPC address range 1 configuration register 1"
119
120 ## [0x28 - 0x2b] LPC address range 3 configuration register 2
121
122 Default: 0x00000000
123
124 Same bit mapping as "LPC address range 1 configuration register 2"
125
126 ## [0x2c - 0x2f] LPC address range 4 configuration register 1
127
128 Default: 0x00000000
129
130 Same bit mapping as "LPC address range 1 configuration register 1"
131
132 ## [0x30 - 0x33] LPC address range 4 configuration register 2
133
134 Default: 0x00000000
135
136 Same bit mapping as "LPC address range 1 configuration register 2"
137
138 ## [0x34 - 0x37] LPC address range 5 configuration register 1
139
140 Default: 0x00000000
141
142 Same bit mapping as "LPC address range 1 configuration register 1"
143
144 ## [0x38 - 0x3b] LPC address range 5 configuration register 2
145
146 Default: 0x00000000
147
148 Same bit mapping as "LPC address range 1 configuration register 2"
149
150 ## [0x3c - 0x3f] LPC address range 6 configuration register 1
151
152 Default: 0x00000000
153
154 Same bit mapping as "LPC address range 1 configuration register 1"
155
156 ## [0x40 - 0x43] LPC address range 6 configuration register 2
157
158 Default: 0x00000000
159
160 Same bit mapping as "LPC address range 1 configuration register 2"
161
162 ## [0x44 - 0x47] DMA configuration register 1
163
164 Default: 0x00000000
165
166 | Bits | Description |
167 |------|---------------------------------------------------------------------------------------------------------------------------|
168 | 31:8 | Reserved |
169 | 7:4 | LPC IDSEL filter |
170 | 3 | Reserved |
171 | 2 | IDSEL filter enable. When asserted, the DMA engine will require the LPC IDSEL to match the configured filter IDSEL value |
172 | 1 | Enable DMA for LPC firmware write cycles |
173 | 0 | Enable DMA for LPC firmware read cycles |
174
175 ## [0x48 - 0x4b] DMA configuration register 2
176
177 Default: 0x00000000
178
179 Definitions:
180 - CPU: Wishbone-attached internal CPU
181 - HOST: External host platform attached via LPC
182
183 | Bits | Description |
184 |------|------------------------------------|
185 | 31:0 | CPU DMA window base address [31:0] |
186
187 NOTE: The DMA engine only supports full word length (64 bit) CPU bus alignment, therefore bits [3:0] of this register are hardwired to zero.
188
189 ## [0x4c - 0x4f] DMA configuration register 3
190
191 Default: 0x00000000
192
193 Definitions:
194 - CPU: Wishbone-attached internal CPU
195 - HOST: External host platform attached via LPC
196
197 | Bits | Description |
198 |------|-------------------------------------|
199 | 31:0 | CPU DMA window base address [63:32] |
200
201 ## [0x50 - 0x53] DMA configuration register 4
202
203 Default: 0x00000000
204
205 Definitions:
206 - CPU: Wishbone-attached internal CPU
207 - HOST: External host platform attached via LPC
208
209 | Bits | Description |
210 |------|------------------------------------|
211 | 31:0 | LPC firmware window length (bytes) |
212
213 NOTE: The DMA engine only supports full word length (64 bit) CPU bus alignment, therefore bits [3:0] of this register are hardwired to zero.
214
215 ## [0x54 - 0x57] DMA configuration register 5
216
217 Default: 0x00000000
218
219 Definitions:
220 - CPU: Wishbone-attached internal CPU
221 - HOST: External host platform attached via LPC
222
223 | Bits | Description |
224 |------|------------------------------------------|
225 | 31:0 | LPC firmware window start offset (bytes) |
226
227 This register defines the start address (DMA window offset) of the active LPC firmware access window.
228
229 All LPC firmware transfers start with an implicit LPC base address of 0x0, which corresponds to offset 0x0 in the configured CPU DMA window (see "DMA configuration register 2").
230 This register allows remapping of the LPC base address within the CPU DMA window, thus allowing LPC address 0x0 to be placed anywhere within the configured CPU DMA memory region. In effect, it is the offset into DMA memory space where the LPC memory space origin is placed.
231
232 Together with the "DMA configuration register 6" register, a defined region of LPC firmware memory space can be set up for DMA access, which is then mapped onto an equivalent region of CPU DMA memory.
233
234 ## [0x58 - 0x5b] DMA configuration register 6
235
236 Default: 0x00000000
237
238 Definitions:
239 - CPU: Wishbone-attached internal CPU
240 - HOST: External host platform attached via LPC
241
242 | Bits | Description |
243 |------|----------------------------------------|
244 | 31:0 | LPC firmware window end offset (bytes) |
245
246 This register defines the end address of the active LPC firmware access window.
247
248 Together with the "DMA configuration register 5" register, a defined region of LPC firmware memory space can be set up for DMA access, which is then mapped onto an equivalent region of CPU DMA memory.
249
250 ## [0x5c - 0x5f] DMA configuration register 7
251
252 Default: 0x00000000
253
254 Definitions:
255 - CPU: Wishbone-attached internal CPU
256 - HOST: External host platform attached via LPC
257
258 | Bits | Description |
259 |------|---------------------------|
260 | 31:0 | LPC firmware address mask |
261
262 This register defines the mask applied to all inbound LPC firmware space addresses, prior to any mapping of those addresses into the DMA region.
263
264 This design allows a specific section of CPU DMA memory to be effectively replicated through the entire LPC address space. In particular, it helps to ensure the DMA window data is available at the end of the LPC firmware address space, as expected by various HOST access patterns.
265
266 ## [0x60 - 0x63] Status register 1
267
268 Default: 0x00000000
269
270 Definitions:
271 - CPU: Wishbone-attached internal CPU
272 - HOST: External host platform attached via LPC
273
274 | Bits | Description |
275 |-------|------------------------------------------------------------------------------|
276 | 31:24 | Reserved |
277 | 23:20 | IDSEL of pending LPC firmware cycle |
278 | 19:16 | MSIZE of pending LPC firmware cycle |
279 | 15:5 | Reserved |
280 | 4 | Asserted when LPC bus is in external HOST-driven reset |
281 | 3:2 | LPC cycle type from host -- 0 == I/O, 1 == TPM, 2 == firmware, 3 == reserved |
282 | 1 | LPC cycle direction from HOST -- 0 == read, 1 == write |
283 | 0 | Attention flag from LPC core |
284
285 ## [0x64 - 0x67] Status register 2
286
287 Default: 0x00000000
288
289 Definitions:
290 - CPU: Wishbone-attached internal CPU
291 - HOST: External host platform attached via LPC
292
293 | Bits | Description |
294 |-------|------------------------------|
295 | 31:28 | Reserved |
296 | 27:0 | Address of pending LPC cycle |
297
298 This register contains the target LPC address of any pending LPC transaction initiated by the HOST.
299
300 ## [0x68 - 0x6b] Status register 3
301
302 Default: 0x00000000
303
304 Definitions:
305 - CPU: Wishbone-attached internal CPU
306 - HOST: External host platform attached via LPC
307
308 | Bits | Description |
309 |------|-----------------------------------------|
310 | 31:8 | Reserved |
311 | 7:0 | HOST-provided data of pending LPC cycle |
312
313 This register contains the HOST-provided data of any pending LPC transaction initiated by the HOST.
314
315 The contents of this register are only defined when the LPC cycle type is WRITE; the contents are undefined for all other cycle types.
316
317 ## [0x6c - 0x6f] Status register 4
318
319 Default: 0x00000000
320
321 Definitions:
322 - CPU: Wishbone-attached internal CPU
323 - HOST: External host platform attached via LPC
324 - CIRQ: Interrupt request as wired to Wishbone-attached internal CPU
325 - HIRQ: Interrupt request as wired to external host platform over LPC serial IRQ line
326
327 | Bits | Description |
328 |-------|--------------------------------------------------------------------------------------------------|
329 | 31:12 | Reserved |
330 | 11:10 | Reason for VUART2 IRQ assert -- 0 == undefined, 1 == queue threshold reached, 2 == queue timeout |
331 | 9:8 | Reason for VUART1 IRQ assert -- 0 == undefined, 1 == queue threshold reached, 2 == queue timeout |
332 | 7 | Reserved |
333 | 6 | LPC I/O cycle CIRQ asserted |
334 | 5 | LPC TPM cycle CIRQ asserted |
335 | 4 | LPC firmware cycle CIRQ asserted |
336 | 3 | IPMI BT CIRQ asserted |
337 | 2 | VUART2 CIRQ asserted |
338 | 1 | VUART1 CIRQ asserted |
339 | 0 | LPC global CIRQ asserted |
340
341 ## [0x70 - 0x73] IPMI BT control register
342
343 Default: 0x00000000
344
345 | Bits | Description |
346 |------|-------------|
347 | 31:8 | Reserved |
348 | 7 | B_BUSY |
349 | 6 | H_BUSY |
350 | 5 | OEM0 |
351 | 4 | EVT_ATN |
352 | 3 | B2H_ATN |
353 | 2 | H2B_ATN |
354 | 1 | CLR_RD_PTR |
355 | 0 | CLR_WR_PTR |
356
357 This is the IPMI-defined BMC-side (CPU accessible) BT control register (BT_CTRL).
358
359 Please refer to the IPMI specification [1] f for a full register definition.
360
361 # LICENSE
362
363 Aquila is licensed under the terms of the GNU LGPLv3+, with included third party components licensed under Apache 2.0. See LICENSE.aquila for details.
364
365 # DOCUMENTATION CREDITS
366
367 (c) 2022 Raptor Engineering, LLC
368
369 # REFERENCES
370
371 1. https://www.intel.com/content/dam/www/public/us/en/documents/specification-updates/ipmi-intelligent-platform-mgt-interface-spec-2nd-gen-v2-0-spec-update.pdf