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