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