/** @mainpage 
 * @brief TRACE32 LOGGER command.
 *
 * @section Usage
 * Usage: Add a single instruction fetch, e.g. function entry into the LOGGER.
 * @code
 * T32_LoggerInit()
 * ...
 * T32_LoggerData(T32_FETCH, &function, 0);
 * @endcode
 * Usage: Add a variable with value into the LOGGER, e.g. nCounter and nFlag.
 * @code
 * T32_LoggerInit()
 * ...
 * long nCounter;
 * char nFlag;
 * nCounter = 0x11223344;
 * T32_LoggerData(T32_DATA_WRITE|T32_LONG, &nCounter, nCounter);
 * nFlag = 5;
 * T32_LoggerData(T32_DATA_READ|T32_BYTE, &nFlag, nFlag);
 * @endcode
 */
/** @file logger.h
 */

#ifndef LOGGER_H
#define LOGGER_H

#define T32_LOGGER_SIZE           1024 //!< Size of the LOGGER Ringbuffer, must be a power of 2

/* program cycle types */
#define T32_FETCH               0x1000 //!< FETCH CYCLE,   add a trace record for a program fetch cycle
#define T32_EXECUTE             0xf000 //!< EXECUTE CYCLE, add a trace record for a program execute cycle, data holds number of executed bytes

/* data cycle types */
#define T32_DATA_READ           0x2000 //!< READ CYCLE,    add a trace record with a read transaction (load), see @ref T32_BYTE @ref T32_WORD @ref T32_LONG
#define T32_DATA_WRITE          0x3000 //!< WRITE CYCLE,   add a trace record with a write transaction (store), see @ref T32_BYTE @ref T32_WORD @ref T32_LONG

/* data cycle - data width specifier, use together with T32_DATA_* */
#define T32_BYTE                0x0100 //!< BYTE access - use together with @ref T32_DATA_READ @ref T32_DATA_WRITE
#define T32_WORD                0x0200 //!< WORD access - use together with @ref T32_DATA_READ @ref T32_DATA_WRITE
#define T32_LONG                0x0400 //!< LONG access - use together with @ref T32_DATA_READ @ref T32_DATA_WRITE

typedef struct 
{
    unsigned long tshigh;       //!< high part of timestamp (upper 16 bit) and cycle info (lower 16 bit)
    unsigned long tslow;        //!< low part of timestamp
    unsigned long address;      //!< program instruction address or address of data load/store transaction
    unsigned long data;         //!< number of executed bytes for T32_EXECUTE, data value of load/store transaction
}
T32_loggerData_t;

typedef struct 
{
    T32_loggerData_t * ptr;     //!< pointer to trace data
    long size;                  //!< size of trace buffer
    volatile long index;        //!< current write pointer
    long tindex;                //!< index of trigger record
    long iflags;                //!< incoming flags, Bit 0: ARM, Bit 8: Stack Mode
    long oflags;                //!< outgoing flags, Bit 0: Overflow, Bit 8: Trigger, Bit 9: Break
    long reserved1;
    long reserved2;
    T32_loggerData_t buffer[T32_LOGGER_SIZE];
}
T32_LoggerStruct_t;

/**
 * @brief Initialize the LOGGER internal data structures.
 *
 * @details This routine must be called before using any other LOGGER related
 * routines. It initializes the logger internal data structures and calls 
 * T32_TimerInit().
 *
 * @param void
 * @return void
 */
void T32_LoggerInit();

/**
 * @brief Add a new event to the LOGGER.
 *
 * @details 
 *
 * @sa T32_FETCH T32_DATA_READ T32_DATA_WRITE T32_EXECUTE T32_LONG T32_WORD T32_BYTE
 * @param cycletype Type of the event, e.g. @ref T32_FETCH or (@ref T32_DATA_READ|@ref T32_LONG).
 * @param address   Address of the event, in case of @ref T32_FETCH and @ref T32_EXECUTE its a instruction address otherwise a data address.
 * @param data      Data related to the event, needed with @ref T32_DATA_READ and @ref T32_EXECUTE.
 * @return void
 */
void T32_LoggerData(int cycletype, void* address, unsigned long data);

/**
 * @brief Add a new event to the LOGGER without timestamp.
 *
 * @sa T32_FETCH T32_DATA_READ T32_DATA_WRITE T32_EXECUTE T32_LONG T32_WORD T32_BYTE
 * @param cycletype Type of the event, e.g. @ref T32_FETCH or (@ref T32_DATA_READ|@ref T32_LONG).
 * @param address   Address of the event, in case of @ref T32_FETCH and @ref T32_EXECUTE its an instruction address otherwise a data address.
 * @param data      Data related to the event, needed with @ref T32_DATA_READ, @ref T32_DATA_WRITE and @ref T32_EXECUTE.
 * @return void
 */
void T32_LoggerDataFast(int cycletype, void* address, unsigned long data);

/**
 * @brief Initialize the architecture specific timer.
 *
 * @details This routine is architecture specific and must be implemented by
 * by the customer. 
 *
 * Please initialize the timer used in T32_TimerGet() in this routine which is 
 * automatically called by T32_LoggerInit().
 *
 * @param  none
 * @return void
 */
void T32_TimerInit();

/**
 * @brief Get current timestamp of architecture specific timer.
 *
 * @details This routine is architecture specific and must be implemented by
 * by the customer. 
 * 
 * @param  none
 * @return current timestamp of the timer, 56bit width.
 */
unsigned long long T32_TimerGet();

#endif