1 /* Header file for TRAX control Library */ 2 3 /* 4 * Copyright (c) 2012-2013 Tensilica Inc. 5 * 6 * Permission is hereby granted, free of charge, to any person obtaining 7 * a copy of this software and associated documentation files (the 8 * "Software"), to deal in the Software without restriction, including 9 * without limitation the rights to use, copy, modify, merge, publish, 10 * distribute, sublicense, and/or sell copies of the Software, and to 11 * permit persons to whom the Software is furnished to do so, subject to 12 * the following conditions: 13 * 14 * The above copyright notice and this permission notice shall be included 15 * in all copies or substantial portions of the Software. 16 * 17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 18 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 19 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 20 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 21 * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 22 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 23 * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 24 */ 25 26 #ifndef _TRAX_H 27 #define _TRAX_H 28 29 #ifdef __cplusplus 30 extern "C" { 31 #endif 32 33 #define TRAX_STOP_HALT 0x0001 34 #define TRAX_STOP_QUIET 0x0002 35 36 /* Flag values to indicate if the user wanted to reverse the pcstop 37 * parameters */ 38 #define TRAX_PCSTOP_REVERSE 0x0001 39 #define TRAX_PCSTOP_NO_REVERSE 0x0000 40 41 /* Indicating whether postsize should be in terms of bytes, instructions 42 * or percentage of trace size captured */ 43 #define TRAX_POSTSIZE_BYTES 0x0000 44 #define TRAX_POSTSIZE_INSTR 0x0001 45 #define TRAX_POSTSIZE_PERCENT 0x0002 46 47 /* Size of the header inside the trace file */ 48 #define TRAX_HEADER_SIZE 256 49 50 /* Minimum size between start and end addresses */ 51 #define TRAX_MIN_TRACEMEM 64 52 53 /* For basic debugging */ 54 #define DEBUG 0 55 56 #include <stdbool.h> 57 58 #define ffs(i) __builtin_ffs(i) 59 60 /* Data structures */ 61 62 /* Represents the context of the TRAX unit and the current TRAX session. 63 * To be used by set and show function calls to set and show appropriate 64 * parameters of appropriate TRAX unit. 65 */ 66 67 typedef struct { 68 int trax_version; /* TRAX PC version information */ 69 unsigned long trax_tram_size; /* If trace RAM is present,size of it */ 70 int hflags; /* Flags that can be used to debug, 71 print info, etc. */ 72 int address_read_last; /* During saving of the trace, this 73 indicates the address from which 74 the current trace reading must 75 resume */ 76 unsigned long bytes_read; /* bytes read uptil now */ 77 unsigned long total_memlen; /* Total bytes to be read based on the 78 trace collected in the trace RAM */ 79 bool get_trace_started; /* indicates that the first chunk of 80 bytes (which include the header) has 81 been read */ 82 } trax_context; 83 84 85 /* -----------------------TRAX Initialization ------------------------------*/ 86 87 /* Initializing the trax context. Reads registers and sets values for version, 88 * trace RAM size, total memory length, etc. Most of the other values are 89 * initialized to their default case. 90 * 91 * context : pointer to structure which contains information about the 92 * current TRAX session 93 * 94 * returns : 0 if successful, -1 if unsuccessful, -2 if ram_size if 95 * incorrect 96 */ 97 int trax_context_init_eri (trax_context *context); 98 99 /* -----------------Starting/Stopping TRAX session -------------------------*/ 100 101 /* Start tracing with current parameter setting. If tracing is already in 102 * progress, an error is reported. Otherwise, tracing starts and any unsaved 103 * contents of the TraceRAM is discarded 104 * 105 * context : pointer to structure which contains information about the 106 * current TRAX session 107 * returns : 0 if successful, 1 if trace is already active, 108 * -1 if unsuccessful 109 */ 110 int trax_start (trax_context *context); 111 112 /* This command initiates a stop trigger or halts a trace session based of the 113 * value of the flag parameter passed. In case stop trigger is initiated, any 114 * selected post-stop-trigger capture proceeds normally. 115 * If trace capture was not in progress, or a stop was already triggered, the 116 * return value indicates appropriately. 117 * 118 * context : pointer to structure which contains information about the 119 * current TRAX session 120 * flags : To differentiate between stopping trace without any 121 * post-size-trigger capture (trax_halt) or with that. 122 * A zero value would stop the trace based on trigger and a 123 * value of one would halt it 124 * 125 * returns : 0 if successful, 1 if already stopped, -1 if unsuccessful 126 */ 127 int trax_stop_halt (trax_context *context, int flags); 128 129 /* Resets the TRAX parameters to their default values which would internally 130 * involve resetting the TRAX registers. To invoke another trace session or 131 * reset the current tracing mechanism, this function needs to be called as 132 * it resets parameters of the context that deal with tracing information 133 * 134 * context : pointer to structure which contains information about the 135 * current TRAX session 136 * 137 * returns : 0 if successful, -1 if unsuccessful 138 */ 139 int trax_reset (trax_context *context); 140 141 /* ---------------Set/Get several TRAX parameters --------------------------*/ 142 143 /* Sets the start address and end address (word aligned) of the trace in the 144 * TraceRAM. Care must be taken to ensure that the difference between the 145 * start and the end addresses is atleast TRAX_MIN_TRACEMEM bytes. If not, 146 * the values are reset to default, which is 0 for startaddr and 147 * traceRAM_words -1 for endaddr 148 * 149 * context : pointer to structure which contains information about the 150 * current TRAX session 151 * startaddr : value to which the start address must be set. Can be 152 * any value between 0 - (traceRAM_words - 1) 153 * endaddr : value to which the end address must be set. Can be any value 154 * between 0 - (traceRAM_words - 1) 155 * 156 * returns : 0 if successful, -1 if unsuccessful, -2 if the difference 157 * between the start and end addresses is less than 158 * TRAX_MIN_TRACEMEM bytes or if they are passed incorrect 159 * values, -3 if memory shared option is not configured, in 160 * which case, start and end addresses are set to default 161 * values instead of those passed by the user 162 */ 163 int trax_set_ram_boundaries (trax_context *context, unsigned startaddr, 164 unsigned endaddr); 165 166 /* Shows the start address and end address(word aligned) of the trace in the 167 * TraceRAM. If incorrect, the startaddress and the endaddress values are 168 * set to default, i.e. 0 for startaddr and traceRAM_words - 1 for endaddr 169 * 170 * context : pointer to structure which contains information about the 171 * current TRAX session 172 * startaddr : pointer to value which will contain the start address 173 * endaddr : pointer to value which will contain the end address 174 * 175 * returns : 0 if successful, -1 if unsuccessful 176 * 177 */ 178 int trax_get_ram_boundaries (trax_context *context, unsigned *startaddr, 179 unsigned *endaddr); 180 181 /* Selects stop trigger via cross-trigger input 182 * 183 * context : pointer to structure which contains information about the 184 * current TRAX session 185 * value : 0 = off (reset value), 1 = on 186 * 187 * returns : 0 if successful, -1 if unsuccessful 188 */ 189 int trax_set_ctistop (trax_context *context, unsigned value); 190 191 /* Shows if stop-trigger via cross-trigger input is off or on 192 * 193 * context : pointer to structure which contains information about the 194 * current TRAX session 195 * returns : 0 if off, 1 if on, -1 if unsuccessful 196 */ 197 int trax_get_ctistop (trax_context *context); 198 199 /* Selects stop trigger via processor-trigger input 200 * 201 * context : pointer to structure which contains information about the 202 * current TRAX session 203 * value : 0 = off (reset value), 1 = on 204 * 205 * returns : 0 if successful, -1 if unsuccessful 206 */ 207 int trax_set_ptistop (trax_context *context, unsigned value); 208 209 /* Shows if stop trigger visa processor-trigger input is off or on 210 * 211 * context : pointer to structure which contains information about the 212 * current TRAX session 213 * returns : 0 if off, 1 if on, -1 if unsuccessful 214 */ 215 int trax_get_ptistop (trax_context *context); 216 217 /* Reports cross trigger output state 218 * 219 * context : pointer to structure which contains information about the 220 * current TRAX session 221 * returns : 0 if CTO bit is reset, 1 if CTO bit is set 222 */ 223 int trax_get_cto (trax_context *context); 224 225 /* Reports processor trigger output state 226 * 227 * context : pointer to structure which contains information about the 228 * current TRAX session 229 * returns : 0 if PTO bit is reset, 1 if PTO bit is set 230 */ 231 int trax_get_pto (trax_context *context); 232 233 /* Selects condition that asserts cross trigger output 234 * 235 * context : pointer to structure which contains information about the 236 * current TRAX session 237 * option : 0 = off(reset value)/1 = ontrig/2 = onhalt 238 * 239 * returns : 0 if successful, -1 if unsuccessful 240 */ 241 int trax_set_ctowhen (trax_context *context, int option); 242 243 /* Shows condition that asserted cross trigger output. It can be 244 * any of: ontrig or onhalt or even off 245 * 246 * context : pointer to structure which contains information about the 247 * current TRAX session 248 * 249 * returns : 0 if off, 1 if ontrig, 2 if onhalt, -1 if unsuccessful 250 */ 251 int trax_get_ctowhen (trax_context *context); 252 253 /* Selects condition that asserts processor trigger output 254 * 255 * context : pointer to structure which contains information about the 256 * current TRAX session 257 * option : 0 = off(reset value)/1 = ontrig/2 = onhalt 258 * 259 * returns : 0 if successful, -1 if unsuccessful 260 */ 261 int trax_set_ptowhen (trax_context *context, int option); 262 263 264 /* Shows condition that asserted processor trigger output. It can be 265 * any of: ontrig or onhalt or even off 266 * 267 * context : pointer to structure which contains information about the 268 * current TRAX session 269 * returns : 0 if off, 1 if ontrig, 2 if onhalt, -1 if unsuccessful 270 */ 271 int trax_get_ptowhen (trax_context *context); 272 273 /* Selects the trace synchronization message period. 274 * If ATEN enabled, we cannot allow syncper to be off, set it to reset value. 275 * Also, if no trace RAM, and ATEN enabled, set syncper to be reset value 276 * i.e. 256. A value of 1 i.e. on indicates that internally the message 277 * frequency is set to an optimal value. This option should be preferred 278 * if the user is not sure what message frequency option to set for the 279 * trace session. 280 * 281 * context : pointer to structure which contains information about the 282 * current TRAX session 283 * option : 0 = off, 1 = on, -1 = auto, 8, 16, 32, 64, 128, 284 * 256 (reset value) 285 * 286 * returns : 0 if successful, -1 if unsuccessful, -2 if incorrect 287 * arguments 288 */ 289 int trax_set_syncper (trax_context *context, int option); 290 291 /* Shows trace synchronization message period. Can be one of: 292 * off, on, auto, 8, 16, 32, 64, 128, 256 (reset value) 293 * 294 * context : pointer to structure which contains information about the 295 * current TRAX session 296 * returns : value of sync period, 0 if off, -1 if unsuccessful 297 */ 298 int trax_get_syncper (trax_context *context); 299 300 /* Selects stop trigger via PC match. Specifies the address or 301 * address range to match against program counter. Trace stops when the 302 * processor executes an instruction matching the specified address 303 * or range. 304 * 305 * context : pointer to structure which contains information about the 306 * current TRAX session 307 * index : indicates the number of stop trigger (currently there is 308 * only one i.e. index = 0) 309 * startaddress : start range of the address at which the stop trigger 310 * should be activated 311 * enaddress : end range of the address at which the stop trigger should 312 * be activated 313 * flags : If non-zero, this inverts the range. i.e. trace stops 314 * when the processor executes an instruction that does not 315 * match the specified address or range 316 * 317 * returns : 0 if successful, -1 if unsuccessful, -2 if incorrect 318 * arguments (unaligned) 319 * 320 * Note : For the current version of TRAX library, the endaddress and 321 * startaddress can differ by at most 31 bytes and the total 322 * range i.e. (endaddress - startaddress + 1) has to be a power 323 * of two 324 */ 325 int trax_set_pcstop (trax_context *context, int index, unsigned long startaddress, 326 unsigned long endaddress, int flags); 327 328 /* Shows the stop trigger via PC match 329 * 330 * context : pointer to structure which contains information about the 331 * current TRAX session 332 * index : container of information about the number of stop triggers 333 * startaddress : container of start range of stop trigger 334 * endaddress : container of end range of stop trigger 335 * flags : container of information whcih indicates whether the 336 * pc stop range is inverted or not. 337 * 338 * returns : 0 if successful, -1 if unsuccessful 339 */ 340 int trax_get_pcstop (trax_context *context, int *index, 341 unsigned long *startaddress, 342 unsigned long *endaddress, int *flags); 343 344 /* This function is used to set the amount of trace to be captured past 345 * the stop trigger. 346 * 347 * context : pointer to structure which contains information about the 348 * current TRAX session 349 * count_unit : contains the count of units (instructions or bytes) to be 350 * captured post trigger. If 0, it implies that this is off 351 * unit : unit of measuring the count. 0 is bytes, 1 is instructions 352 * 2 is percentage of trace 353 * 354 * returns : 0 if successful, -1 if unsuccessful, -2 if incorrect 355 * arguments 356 * 357 */ 358 int trax_set_postsize (trax_context *context, int count_unit, int unit); 359 360 /* This function shows the amount of TraceRAM in terms of the number of 361 * instructions or bytes, captured post the stop trigger 362 * 363 * context : pointer to structure which contains information about the 364 * current TRAX session 365 * count_unit : will contain the count of units(instructions or bytes) post 366 * trigger 367 * unit : will contain information about the events that are counted 368 * 0 implies that the traceRAM words consumed are counted and 369 * 1 implies that the target processor instructions executed and 370 * excpetions/interrupts taken are counted 371 * 372 * returns : 0 if postsize was got successfully, -1 if unsuccessful 373 */ 374 int trax_get_postsize (trax_context *context, int *count_unit, int *unit); 375 376 /* -------------------------- TRAX save routines ---------------------------*/ 377 378 /* This function should be called by the user to return a chunk of 379 * bytes in buf. It can be a lower layer function of save, or can be 380 * called by the user explicitly. If bytes_actually_read contains a 0 381 * after a call to this function has been made, it implies that the entire 382 * trace has been read successfully. 383 * 384 * context : pointer to structure which contains information about 385 * the current TRAX session 386 * buf : Buffer that is allocated by the user, all the trace 387 * data read would be put in this buffer, which can then 388 * be used to generate a tracefile. 389 * The first TRAX_HEADER_SIZE of the buffer will always 390 * contain the header information. 391 * bytes_to_be_read : Indicates the bytes the user wants to read. The first 392 * invocation would need this parameter to be 393 * TRAX_HEADER_SIZE at least. 394 * 395 * returns : bytes actually read during the call to this function. 396 * 0 implies that all the bytes in the trace have been 397 * read, -1 if unsuccessful read/write of 398 * registers or memory, -2 if trace was active while 399 * this function was called, -3 if user enters 400 * bytes_to_be_read < TRAX_HEADER_SIZE in the first 401 * pass 402 */ 403 int trax_get_trace (trax_context *context, void *buf, 404 int bytes_to_be_read); 405 #ifdef __cplusplus 406 } 407 #endif 408 409 #endif /* _TRAX_H */ 410
