| /* Header file for TRAX control Library */ |
| |
| /* |
| * Copyright (c) 2012-2013 Tensilica Inc. |
| * |
| * Permission is hereby granted, free of charge, to any person obtaining |
| * a copy of this software and associated documentation files (the |
| * "Software"), to deal in the Software without restriction, including |
| * without limitation the rights to use, copy, modify, merge, publish, |
| * distribute, sublicense, and/or sell copies of the Software, and to |
| * permit persons to whom the Software is furnished to do so, subject to |
| * the following conditions: |
| * |
| * The above copyright notice and this permission notice shall be included |
| * in all copies or substantial portions of the Software. |
| * |
| * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, |
| * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF |
| * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. |
| * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY |
| * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, |
| * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE |
| * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| */ |
| |
| #ifndef _TRAX_H |
| #define _TRAX_H |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif |
| |
| #define TRAX_STOP_HALT 0x0001 |
| #define TRAX_STOP_QUIET 0x0002 |
| |
| /* Flag values to indicate if the user wanted to reverse the pcstop |
| * parameters */ |
| #define TRAX_PCSTOP_REVERSE 0x0001 |
| #define TRAX_PCSTOP_NO_REVERSE 0x0000 |
| |
| /* Indicating whether postsize should be in terms of bytes, instructions |
| * or percentage of trace size captured */ |
| #define TRAX_POSTSIZE_BYTES 0x0000 |
| #define TRAX_POSTSIZE_INSTR 0x0001 |
| #define TRAX_POSTSIZE_PERCENT 0x0002 |
| |
| /* Size of the header inside the trace file */ |
| #define TRAX_HEADER_SIZE 256 |
| |
| /* Minimum size between start and end addresses */ |
| #define TRAX_MIN_TRACEMEM 64 |
| |
| /* For basic debugging */ |
| #define DEBUG 0 |
| |
| #include <stdbool.h> |
| |
| #define ffs(i) __builtin_ffs(i) |
| |
| /* Data structures */ |
| |
| /* Represents the context of the TRAX unit and the current TRAX session. |
| * To be used by set and show function calls to set and show appropriate |
| * parameters of appropriate TRAX unit. |
| */ |
| |
| typedef struct { |
| int trax_version; /* TRAX PC version information */ |
| unsigned long trax_tram_size; /* If trace RAM is present,size of it */ |
| int hflags; /* Flags that can be used to debug, |
| print info, etc. */ |
| int address_read_last; /* During saving of the trace, this |
| indicates the address from which |
| the current trace reading must |
| resume */ |
| unsigned long bytes_read; /* bytes read uptil now */ |
| unsigned long total_memlen; /* Total bytes to be read based on the |
| trace collected in the trace RAM */ |
| bool get_trace_started; /* indicates that the first chunk of |
| bytes (which include the header) has |
| been read */ |
| } trax_context; |
| |
| |
| /* -----------------------TRAX Initialization ------------------------------*/ |
| |
| /* Initializing the trax context. Reads registers and sets values for version, |
| * trace RAM size, total memory length, etc. Most of the other values are |
| * initialized to their default case. |
| * |
| * context : pointer to structure which contains information about the |
| * current TRAX session |
| * |
| * returns : 0 if successful, -1 if unsuccessful, -2 if ram_size if |
| * incorrect |
| */ |
| int trax_context_init_eri (trax_context *context); |
| |
| /* -----------------Starting/Stopping TRAX session -------------------------*/ |
| |
| /* Start tracing with current parameter setting. If tracing is already in |
| * progress, an error is reported. Otherwise, tracing starts and any unsaved |
| * contents of the TraceRAM is discarded |
| * |
| * context : pointer to structure which contains information about the |
| * current TRAX session |
| * returns : 0 if successful, 1 if trace is already active, |
| * -1 if unsuccessful |
| */ |
| int trax_start (trax_context *context); |
| |
| /* This command initiates a stop trigger or halts a trace session based of the |
| * value of the flag parameter passed. In case stop trigger is initiated, any |
| * selected post-stop-trigger capture proceeds normally. |
| * If trace capture was not in progress, or a stop was already triggered, the |
| * return value indicates appropriately. |
| * |
| * context : pointer to structure which contains information about the |
| * current TRAX session |
| * flags : To differentiate between stopping trace without any |
| * post-size-trigger capture (trax_halt) or with that. |
| * A zero value would stop the trace based on trigger and a |
| * value of one would halt it |
| * |
| * returns : 0 if successful, 1 if already stopped, -1 if unsuccessful |
| */ |
| int trax_stop_halt (trax_context *context, int flags); |
| |
| /* Resets the TRAX parameters to their default values which would internally |
| * involve resetting the TRAX registers. To invoke another trace session or |
| * reset the current tracing mechanism, this function needs to be called as |
| * it resets parameters of the context that deal with tracing information |
| * |
| * context : pointer to structure which contains information about the |
| * current TRAX session |
| * |
| * returns : 0 if successful, -1 if unsuccessful |
| */ |
| int trax_reset (trax_context *context); |
| |
| /* ---------------Set/Get several TRAX parameters --------------------------*/ |
| |
| /* Sets the start address and end address (word aligned) of the trace in the |
| * TraceRAM. Care must be taken to ensure that the difference between the |
| * start and the end addresses is atleast TRAX_MIN_TRACEMEM bytes. If not, |
| * the values are reset to default, which is 0 for startaddr and |
| * traceRAM_words -1 for endaddr |
| * |
| * context : pointer to structure which contains information about the |
| * current TRAX session |
| * startaddr : value to which the start address must be set. Can be |
| * any value between 0 - (traceRAM_words - 1) |
| * endaddr : value to which the end address must be set. Can be any value |
| * between 0 - (traceRAM_words - 1) |
| * |
| * returns : 0 if successful, -1 if unsuccessful, -2 if the difference |
| * between the start and end addresses is less than |
| * TRAX_MIN_TRACEMEM bytes or if they are passed incorrect |
| * values, -3 if memory shared option is not configured, in |
| * which case, start and end addresses are set to default |
| * values instead of those passed by the user |
| */ |
| int trax_set_ram_boundaries (trax_context *context, unsigned startaddr, |
| unsigned endaddr); |
| |
| /* Shows the start address and end address(word aligned) of the trace in the |
| * TraceRAM. If incorrect, the startaddress and the endaddress values are |
| * set to default, i.e. 0 for startaddr and traceRAM_words - 1 for endaddr |
| * |
| * context : pointer to structure which contains information about the |
| * current TRAX session |
| * startaddr : pointer to value which will contain the start address |
| * endaddr : pointer to value which will contain the end address |
| * |
| * returns : 0 if successful, -1 if unsuccessful |
| * |
| */ |
| int trax_get_ram_boundaries (trax_context *context, unsigned *startaddr, |
| unsigned *endaddr); |
| |
| /* Selects stop trigger via cross-trigger input |
| * |
| * context : pointer to structure which contains information about the |
| * current TRAX session |
| * value : 0 = off (reset value), 1 = on |
| * |
| * returns : 0 if successful, -1 if unsuccessful |
| */ |
| int trax_set_ctistop (trax_context *context, unsigned value); |
| |
| /* Shows if stop-trigger via cross-trigger input is off or on |
| * |
| * context : pointer to structure which contains information about the |
| * current TRAX session |
| * returns : 0 if off, 1 if on, -1 if unsuccessful |
| */ |
| int trax_get_ctistop (trax_context *context); |
| |
| /* Selects stop trigger via processor-trigger input |
| * |
| * context : pointer to structure which contains information about the |
| * current TRAX session |
| * value : 0 = off (reset value), 1 = on |
| * |
| * returns : 0 if successful, -1 if unsuccessful |
| */ |
| int trax_set_ptistop (trax_context *context, unsigned value); |
| |
| /* Shows if stop trigger visa processor-trigger input is off or on |
| * |
| * context : pointer to structure which contains information about the |
| * current TRAX session |
| * returns : 0 if off, 1 if on, -1 if unsuccessful |
| */ |
| int trax_get_ptistop (trax_context *context); |
| |
| /* Reports cross trigger output state |
| * |
| * context : pointer to structure which contains information about the |
| * current TRAX session |
| * returns : 0 if CTO bit is reset, 1 if CTO bit is set |
| */ |
| int trax_get_cto (trax_context *context); |
| |
| /* Reports processor trigger output state |
| * |
| * context : pointer to structure which contains information about the |
| * current TRAX session |
| * returns : 0 if PTO bit is reset, 1 if PTO bit is set |
| */ |
| int trax_get_pto (trax_context *context); |
| |
| /* Selects condition that asserts cross trigger output |
| * |
| * context : pointer to structure which contains information about the |
| * current TRAX session |
| * option : 0 = off(reset value)/1 = ontrig/2 = onhalt |
| * |
| * returns : 0 if successful, -1 if unsuccessful |
| */ |
| int trax_set_ctowhen (trax_context *context, int option); |
| |
| /* Shows condition that asserted cross trigger output. It can be |
| * any of: ontrig or onhalt or even off |
| * |
| * context : pointer to structure which contains information about the |
| * current TRAX session |
| * |
| * returns : 0 if off, 1 if ontrig, 2 if onhalt, -1 if unsuccessful |
| */ |
| int trax_get_ctowhen (trax_context *context); |
| |
| /* Selects condition that asserts processor trigger output |
| * |
| * context : pointer to structure which contains information about the |
| * current TRAX session |
| * option : 0 = off(reset value)/1 = ontrig/2 = onhalt |
| * |
| * returns : 0 if successful, -1 if unsuccessful |
| */ |
| int trax_set_ptowhen (trax_context *context, int option); |
| |
| |
| /* Shows condition that asserted processor trigger output. It can be |
| * any of: ontrig or onhalt or even off |
| * |
| * context : pointer to structure which contains information about the |
| * current TRAX session |
| * returns : 0 if off, 1 if ontrig, 2 if onhalt, -1 if unsuccessful |
| */ |
| int trax_get_ptowhen (trax_context *context); |
| |
| /* Selects the trace synchronization message period. |
| * If ATEN enabled, we cannot allow syncper to be off, set it to reset value. |
| * Also, if no trace RAM, and ATEN enabled, set syncper to be reset value |
| * i.e. 256. A value of 1 i.e. on indicates that internally the message |
| * frequency is set to an optimal value. This option should be preferred |
| * if the user is not sure what message frequency option to set for the |
| * trace session. |
| * |
| * context : pointer to structure which contains information about the |
| * current TRAX session |
| * option : 0 = off, 1 = on, -1 = auto, 8, 16, 32, 64, 128, |
| * 256 (reset value) |
| * |
| * returns : 0 if successful, -1 if unsuccessful, -2 if incorrect |
| * arguments |
| */ |
| int trax_set_syncper (trax_context *context, int option); |
| |
| /* Shows trace synchronization message period. Can be one of: |
| * off, on, auto, 8, 16, 32, 64, 128, 256 (reset value) |
| * |
| * context : pointer to structure which contains information about the |
| * current TRAX session |
| * returns : value of sync period, 0 if off, -1 if unsuccessful |
| */ |
| int trax_get_syncper (trax_context *context); |
| |
| /* Selects stop trigger via PC match. Specifies the address or |
| * address range to match against program counter. Trace stops when the |
| * processor executes an instruction matching the specified address |
| * or range. |
| * |
| * context : pointer to structure which contains information about the |
| * current TRAX session |
| * index : indicates the number of stop trigger (currently there is |
| * only one i.e. index = 0) |
| * startaddress : start range of the address at which the stop trigger |
| * should be activated |
| * enaddress : end range of the address at which the stop trigger should |
| * be activated |
| * flags : If non-zero, this inverts the range. i.e. trace stops |
| * when the processor executes an instruction that does not |
| * match the specified address or range |
| * |
| * returns : 0 if successful, -1 if unsuccessful, -2 if incorrect |
| * arguments (unaligned) |
| * |
| * Note : For the current version of TRAX library, the endaddress and |
| * startaddress can differ by at most 31 bytes and the total |
| * range i.e. (endaddress - startaddress + 1) has to be a power |
| * of two |
| */ |
| int trax_set_pcstop (trax_context *context, int index, unsigned long startaddress, |
| unsigned long endaddress, int flags); |
| |
| /* Shows the stop trigger via PC match |
| * |
| * context : pointer to structure which contains information about the |
| * current TRAX session |
| * index : container of information about the number of stop triggers |
| * startaddress : container of start range of stop trigger |
| * endaddress : container of end range of stop trigger |
| * flags : container of information whcih indicates whether the |
| * pc stop range is inverted or not. |
| * |
| * returns : 0 if successful, -1 if unsuccessful |
| */ |
| int trax_get_pcstop (trax_context *context, int *index, |
| unsigned long *startaddress, |
| unsigned long *endaddress, int *flags); |
| |
| /* This function is used to set the amount of trace to be captured past |
| * the stop trigger. |
| * |
| * context : pointer to structure which contains information about the |
| * current TRAX session |
| * count_unit : contains the count of units (instructions or bytes) to be |
| * captured post trigger. If 0, it implies that this is off |
| * unit : unit of measuring the count. 0 is bytes, 1 is instructions |
| * 2 is percentage of trace |
| * |
| * returns : 0 if successful, -1 if unsuccessful, -2 if incorrect |
| * arguments |
| * |
| */ |
| int trax_set_postsize (trax_context *context, int count_unit, int unit); |
| |
| /* This function shows the amount of TraceRAM in terms of the number of |
| * instructions or bytes, captured post the stop trigger |
| * |
| * context : pointer to structure which contains information about the |
| * current TRAX session |
| * count_unit : will contain the count of units(instructions or bytes) post |
| * trigger |
| * unit : will contain information about the events that are counted |
| * 0 implies that the traceRAM words consumed are counted and |
| * 1 implies that the target processor instructions executed and |
| * excpetions/interrupts taken are counted |
| * |
| * returns : 0 if postsize was got successfully, -1 if unsuccessful |
| */ |
| int trax_get_postsize (trax_context *context, int *count_unit, int *unit); |
| |
| /* -------------------------- TRAX save routines ---------------------------*/ |
| |
| /* This function should be called by the user to return a chunk of |
| * bytes in buf. It can be a lower layer function of save, or can be |
| * called by the user explicitly. If bytes_actually_read contains a 0 |
| * after a call to this function has been made, it implies that the entire |
| * trace has been read successfully. |
| * |
| * context : pointer to structure which contains information about |
| * the current TRAX session |
| * buf : Buffer that is allocated by the user, all the trace |
| * data read would be put in this buffer, which can then |
| * be used to generate a tracefile. |
| * The first TRAX_HEADER_SIZE of the buffer will always |
| * contain the header information. |
| * bytes_to_be_read : Indicates the bytes the user wants to read. The first |
| * invocation would need this parameter to be |
| * TRAX_HEADER_SIZE at least. |
| * |
| * returns : bytes actually read during the call to this function. |
| * 0 implies that all the bytes in the trace have been |
| * read, -1 if unsuccessful read/write of |
| * registers or memory, -2 if trace was active while |
| * this function was called, -3 if user enters |
| * bytes_to_be_read < TRAX_HEADER_SIZE in the first |
| * pass |
| */ |
| int trax_get_trace (trax_context *context, void *buf, |
| int bytes_to_be_read); |
| #ifdef __cplusplus |
| } |
| #endif |
| |
| #endif /* _TRAX_H */ |