/* 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 #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 */