release/src-rt-6.x.4708/cfe/cfe/verif/readme.txt

   1 CFE Diagnostic Entry Points
   2 ---------------------------
   3
   4 ---------------------------------------------------------------------------
   5
   6 The CFE diagnostic entry points are used when running verification
   7 programs under the control of the firmware.  They are fixed (constant)
   8 addresses and have register-based calling sequences.  These entry
   9 points are designed to be as minimal as possible so that as much of the
  10 verification code as possible can be reused.
  11
  12 You can call the KSEG0 or KSEG1 version of the routine.  It is
  13 recommended that you call the cached version from cached code and
  14 vice versa.
  15
  16 The firmware will reserve the top megabyte of memory for itself.  The
  17 diagnostic must not touch this memory.
  18
  19 The firmware will be compiled to *NOT* use relocatable data and
  20 code segments.
  21
  22 The firmware will need one general register that it is allowed to
  23 trash without saving - I'll be using this to generate the pointer to
  24 the save area.
  25
  26 The diagnostics can generate records in a log buffer.  This buffer
  27 is allocated in the diagnostic's memory space but is filled in
  28 by the firmware through the diagnostic entry points.  At the end
  29 of the diagnostic run, user commands in the firmware may be used
  30 to look through accumulated log records.
  31
  32 If you mess with the caches or with the console device, the
  33 VAPI functions that print messages to the console may not work.
  34
  35 Log 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
  43 The "Log Record size" field is the number of bytes in the "log data"
  44 field.  No log data would use a value of zero.
  45
  46 The 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
  51 The "F1" byte is the format code; it describes the type
  52 of 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
  61 The "P1" byte is the processor number, 0 or 1.
  62
  63 The "I1" through "I4" bytes are supplied by the diagnostic
  64 and can take on any value.  You can use these bytes to identify
  65 what part of the program generated this particular log record.
  66
  67 For example, if the diagnostic logs a single value of
  68 0x0123_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
  76 RETURN TO FIRMWARE
  77 ------------------
  78
  79 Description:
  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
  92 Routine address:        0xBFC00510  (KSEG1)
  93                         0x9FC00510  (KSEG0)
  94
  95 On entry:               A0 ($4)     Exit status (9=ok, nonzero=fail)
  96 On return:              Does not return
  97 Registers used:         All
  98
  99
 100 DUMP GENERAL REGISTERS
 101 ----------------------
 102
 103 Description:
 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
 115 Routine address:        0xBFC00520 (KSEG1)
 116                         0x9FC00520 (KSEG0)
 117
 118 On Entry:               RA ($31)    Return Address
 119 On Return:              nothing
 120 Registers used:         K0 ($26)    Scratch register for CFE
 121
 122
 123 SET LOG BUFFER
 124 --------------
 125
 126 Description:
 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
 135 Routine address:        0xBFC00530 (KSEG1)
 136                         0x9FC00530 (KSEG0)
 137
 138 On Entry:               RA ($31)    Return Address
 139                         A0 ($4)     Address of start of buffer
 140                         A1 ($5)     Address of end of buffer
 141 On Return:              Nothing
 142 Registers Used:         K0 ($26)    Scratch register for CFE
 143
 144
 145
 146 LOG SINGLE VALUE
 147 ----------------
 148
 149 Description:
 150
 151    This routine saves a single 64-bit value in the log.
 152
 153
 154 Routine address:        0xBFC00540 (KSEG1)
 155                         0x9FC00540 (KSEG0)
 156
 157 On Entry:               RA ($31)    Return Address
 158                         A0 ($4)     Low 32 bits are ID code for value
 159                         A1 ($5)     Value to log
 160 On Return:              Nothing
 161 Registers Used:         K0 ($26)    Scratch register for CFE
 162
 163
 164
 165 LOG MEMORY DATA
 166 ---------------
 167
 168 Description:
 169
 170    This routine saves a block of memory in the log.  The source
 171    buffer must be 64-bit aligned.
 172
 173
 174 Routine address:        0xBFC00550 (KSEG1)
 175                         0x9FC00550 (KSEG0)
 176
 177 On 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
 181 On Return:              Nothing
 182 Registers Used:         K0 ($26)    Scratch register for CFE
 183
 184
 185
 186
 187
 188 SAVE SOC STATE
 189 --------------
 190
 191 Description:
 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
 211 Routine address:        0xBFC00570 (KSEG1)
 212                         0x9FC00570 (KSEG0)
 213
 214 On entry:               A0 ($4)    Low 32 bits are ID code for values
 215                         A1 ($5)    Bitmask of agents to store in log
 216 On return:              nothing
 217 Registers used:         K0 ($26)   Scratch register for CFE
 218
 219
 220 SAVE CPU REGISTERS
 221 ------------------
 222
 223 Description:
 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
 261 Routine address:        0xBFC00580 (KSEG1)
 262                         0x9FC00580 (KSEG0)
 263
 264 On entry:               RA ($31)   Return address
 265                         A0 ($4)    Low 32 bits are ID code for values
 266 On return:              nothing
 267 Registers used:         K0 ($26)   Scratch register for CFE
 268
 269
 270 SAVE FPU REGISTERS
 271 ------------------
 272
 273 Description:
 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
 288 Routine address:        0xBFC005B0 (KSEG1)
 289                         0x9FC005B0 (KSEG0)
 290
 291 On entry:               RA ($31)   Return address
 292                         A0 ($4)    Low 32 bits are ID code for values
 293 On return:              nothing
 294 Registers used:         K0 ($26)   Scratch register for CFE
 295
 296
 297 DUMP STRING
 298 -----------
 299
 300 Description:
 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
 308 Routine address:        0xBFC00590 (KSEG1)
 309                         0x9FC00590 (KSEG0)
 310
 311 On entry:               RA ($31)    Return address
 312                         A0 ($4)     Pointer to null-terminated string
 313 On return:              nothing
 314 Registers used:         K0 ($26)    Scratch register for CFE
 315
 316
 317
 318 SHOW LED MESSAGE
 319 ----------------
 320
 321 Description:
 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
 333 Routine address:        0xBFC005A0 (KSEG1)
 334                         0x9FC005A0 (KSEG0)
 335
 336 On entry:               RA ($31)    Return Address
 337                         A0 ($4)     Four characters
 338 On return:              nothing
 339 Registers used:         K0 ($26)    Scratch register for CFE
 340
 341 ------------------------------------------------------------------------