readme.txt
1CFE Diagnostic Entry Points
2---------------------------
3
4---------------------------------------------------------------------------
5
6The CFE diagnostic entry points are used when running verification
7programs under the control of the firmware. They are fixed (constant)
8addresses and have register-based calling sequences. These entry
9points are designed to be as minimal as possible so that as much of the
10verification code as possible can be reused.
11
12You can call the KSEG0 or KSEG1 version of the routine. It is
13recommended that you call the cached version from cached code and
14vice versa.
15
16The firmware will reserve the top megabyte of memory for itself. The
17diagnostic must not touch this memory.
18
19The firmware will be compiled to *NOT* use relocatable data and
20code segments.
21
22The firmware will need one general register that it is allowed to
23trash without saving - I'll be using this to generate the pointer to
24the save area.
25
26The diagnostics can generate records in a log buffer. This buffer
27is allocated in the diagnostic's memory space but is filled in
28by the firmware through the diagnostic entry points. At the end
29of the diagnostic run, user commands in the firmware may be used
30to look through accumulated log records.
31
32If you mess with the caches or with the console device, the
33VAPI functions that print messages to the console may not work.
34
35Log records follow this format:
36
37 +0 SIGNATURE, FORMAT, and ID-CODE
38 +8 Number of 64-bit words in 'Log Data' field.
39 Upper 32 bits are CP0 count register
40 +16 Return address of routine generating this record
41 +24 Log Data
42
43The "Log Record size" field is the number of bytes in the "log data"
44field. No log data would use a value of zero.
45
46The bytes in the SIGNATURE word are broken down as follows:
47
48 S1 S2 P1 F1 I1 I2 I3 I4
49 CF E1 pp xx ii ii ii ii
50
51The "F1" byte is the format code; it describes the type
52of log record being generated.
53
54 0x00 - General register and CP0 dump
55 0x01 - SOC state dump
56 0x02 - Generic log data (multiple of 8 bytes)
57 0x03 - trace RAM
58 0x04 - Diagnostic termination status (8 bytes)
59 0x05 - Floating point registers
60
61The "P1" byte is the processor number, 0 or 1.
62
63The "I1" through "I4" bytes are supplied by the diagnostic
64and can take on any value. You can use these bytes to identify
65what part of the program generated this particular log record.
66
67For example, if the diagnostic logs a single value of
680x0123_4567_89ab_cdef the log entry might look like:
69
70 0xCCFF_EE02_0000_0001
71 0x0001_3F22_0000_0008
72 0xFFFF_FFFF_8000_0120
73 0x0123_4567_89AB_CDEF
74
75
76RETURN TO FIRMWARE
77------------------
78
79Description:
80
81 Returns control to the firmware and displays the test status.
82 The status result is in register A0.
83
84 The firmware will store a "diagnostic termination status"
85 record in the log with the A0 register value. The ID code
86 will be zero for this record.
87
88 CFE's log scanning commands can be used to display log
89 records accumulated by the test.
90
91
92Routine address: 0xBFC00510 (KSEG1)
93 0x9FC00510 (KSEG0)
94
95On entry: A0 ($4) Exit status (9=ok, nonzero=fail)
96On return: Does not return
97Registers used: All
98
99
100DUMP GENERAL REGISTERS
101----------------------
102
103Description:
104
105 This routine causes CFE to display a register dump on the console
106 port. It is assumed that the console hardware state has not been
107 altered by the diagnostic.
108
109 The format of the register dump is: TBD [XXX should it look like the
110 one that the functional simulator uses?]
111
112 The firmware needs one scratch register.
113
114
115Routine address: 0xBFC00520 (KSEG1)
116 0x9FC00520 (KSEG0)
117
118On Entry: RA ($31) Return Address
119On Return: nothing
120Registers used: K0 ($26) Scratch register for CFE
121
122
123SET LOG BUFFER
124--------------
125
126Description:
127
128 This routine sets the address of the log buffer. This
129 call must be made once at the beginning of the diagnostic
130 or else the "SAVE" functions will be considered as
131 NOPs.
132
133 The buffer addresses must be 64-bit aligned.
134
135Routine address: 0xBFC00530 (KSEG1)
136 0x9FC00530 (KSEG0)
137
138On Entry: RA ($31) Return Address
139 A0 ($4) Address of start of buffer
140 A1 ($5) Address of end of buffer
141On Return: Nothing
142Registers Used: K0 ($26) Scratch register for CFE
143
144
145
146LOG SINGLE VALUE
147----------------
148
149Description:
150
151 This routine saves a single 64-bit value in the log.
152
153
154Routine address: 0xBFC00540 (KSEG1)
155 0x9FC00540 (KSEG0)
156
157On Entry: RA ($31) Return Address
158 A0 ($4) Low 32 bits are ID code for value
159 A1 ($5) Value to log
160On Return: Nothing
161Registers Used: K0 ($26) Scratch register for CFE
162
163
164
165LOG MEMORY DATA
166---------------
167
168Description:
169
170 This routine saves a block of memory in the log. The source
171 buffer must be 64-bit aligned.
172
173
174Routine address: 0xBFC00550 (KSEG1)
175 0x9FC00550 (KSEG0)
176
177On Entry: RA ($31) Return Address
178 A0 ($4) Low 32 bits are ID code for values
179 A1 ($5) Address of buffer containing values
180 A2 ($6) Number of 64-bit words to store
181On Return: Nothing
182Registers Used: K0 ($26) Scratch register for CFE
183
184
185
186
187
188SAVE SOC STATE
189--------------
190
191Description:
192
193 This routine saves the SOC state in a user-supplied buffer.
194 The buffer must be large enough to accomodate the SOC state.
195 The SOC state will be written as records with the following
196 format:
197
198 uint64_t phys_address
199 uint64_t value
200 uint64_t phys_address
201 uint64_t value
202 ...
203 uint64_t phys_address
204 uint64_t value
205
206 The table of SOC registers to dump will be maintained by
207 the firmware.
208
209 The firmware needs one scratch register.
210
211Routine address: 0xBFC00570 (KSEG1)
212 0x9FC00570 (KSEG0)
213
214On entry: A0 ($4) Low 32 bits are ID code for values
215 A1 ($5) Bitmask of agents to store in log
216On return: nothing
217Registers used: K0 ($26) Scratch register for CFE
218
219
220SAVE CPU REGISTERS
221------------------
222
223Description:
224
225 This routine saves the CPU general registers and certain CP0
226 registers in a user-supplied buffer.
227
228 This buffer must be large enough to accomodate the data
229 that will be saved. The registers will be written in
230 the following format:
231
232 uint64_t general_registers[32]
233 uint64_t C0_INX
234 uint64_t C0_RAND
235 uint64_t C0_TLBLO0
236 uint64_t C0_TLBLO1
237 uint64_t C0_CTEXT
238 uint64_t C0_PGMASK
239 uint64_t C0_WIRED
240 uint64_t C0_BADVADDR
241 uint64_t C0_COUNT
242 uint64_t C0_TLBHI
243 uint64_t C0_COMPARE
244 uint64_t C0_SR
245 uint64_t C0_CAUSE
246 uint64_t C0_EPC
247 uint64_t C0_PRID
248 uint64_t C0_CONFIG
249 uint64_t C0_LLADDR
250 uint64_t C0_WATCHLO
251 uint64_t C0_WATCHHI
252 uint64_t C0_XCTEXT
253 uint64_t C0_ECC
254 uint64_t C0_CACHEERR
255 uint64_t C0_TAGLO
256 uint64_t C0_TAGHI
257 uint64_t C0_ERREPC
258
259 The firmware needs one scratch register.
260
261Routine address: 0xBFC00580 (KSEG1)
262 0x9FC00580 (KSEG0)
263
264On entry: RA ($31) Return address
265 A0 ($4) Low 32 bits are ID code for values
266On return: nothing
267Registers used: K0 ($26) Scratch register for CFE
268
269
270SAVE FPU REGISTERS
271------------------
272
273Description:
274
275 This routine saves the floating point and floating point
276 control registers. The registers will be written in
277 the following format:
278
279 uint64_t fp_registers[32]
280 uint64_t fp_fir
281 uint64_t fp_status
282 uint64_t fp_condition_codes
283 uint64_t fp_exceptions
284 uint64_t fp_enables
285
286 The firmware needs one scratch register.
287
288Routine address: 0xBFC005B0 (KSEG1)
289 0x9FC005B0 (KSEG0)
290
291On entry: RA ($31) Return address
292 A0 ($4) Low 32 bits are ID code for values
293On return: nothing
294Registers used: K0 ($26) Scratch register for CFE
295
296
297DUMP STRING
298-----------
299
300Description:
301
302 This routine displays a zero-terminated ASCII text string on the
303 console port.
304
305 The firmware needs one scratch register.
306
307
308Routine address: 0xBFC00590 (KSEG1)
309 0x9FC00590 (KSEG0)
310
311On entry: RA ($31) Return address
312 A0 ($4) Pointer to null-terminated string
313On return: nothing
314Registers used: K0 ($26) Scratch register for CFE
315
316
317
318SHOW LED MESSAGE
319----------------
320
321Description:
322
323 This routine writes four characters onto the SWARM board LEDs.
324 Writing to the LEDs is very fast compared to writing to the
325 console and can be useful for providing progress feedback
326 during a run.
327
328 The characters are packed into the low 4 bytes of register A0.
329 The string ABCD would be hex 0x0000_0000_4142_4344
330
331 The firmware needs one scratch register
332
333Routine address: 0xBFC005A0 (KSEG1)
334 0x9FC005A0 (KSEG0)
335
336On entry: RA ($31) Return Address
337 A0 ($4) Four characters
338On return: nothing
339Registers used: K0 ($26) Scratch register for CFE
340
341------------------------------------------------------------------------
342
343