/* Trace (ETM) extensions to RDI
   Copyright (C) 2001 Free Software Foundation, Inc.


This file is part of GDB.


GDB is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free
Software Foundation; either version 2, or (at your option) any later
version.


GDB is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
for more details.


You should have received a copy of the GNU General Public License
along with GDB; see the file COPYING.  If not, write to the Free
Software Foundation, 59 Temple Place - Suite 330, Boston, MA
02111-1307, USA.  */

/* -*-C-*-
 *
 * $Revision: 1.13 $
 *   $Author: aberent $
 *     $Date: 2000/09/13 09:21:10 $
 *
 */

#ifndef RDI_RTI_H
#define RDI_RTI_H

#include "host.h"
#include "rdi_info.h"
#include "rdi150.h"
#include "rdi_rti_format.h"

/*
 * Scope
 * -----
 *
 * The RDI Trace Interface (also occasionally known as RTI) defines
 * the interface between a trace-aware Debug Controller (such as a
 * enhanced version of MDW) and a Debug Target (such as an ARM9TDMI
 * with trace port, connected to a Hewlett-Packard nTRACE unit).
 */

/**********************************************************************/

/*
 * Generic typedefs
 */

/*
 * Typedef: RDI_TraceEvent
 * Purpose: An opaque structure containing a single trace event. The exact
 * structure of this type depends upon the format of the trace data.  */
typedef struct RDI_TraceEvent RDI_TraceEvent;

/*
 * Typedef: RDI_TraceIndex
 * Purpose: A number that uniquely identifies a single trace event
 *          within a trace buffer. If an event has an index of n,
 *          then the next event in that block will have an index of
 *          n + 1. An index may be negative -- some Targets may
 *          choose to place index zero at the start of the buffer
 *          (that is, all indexes are positive). Others may place
 *          the zero anywhere in the buffer, usually at the "trigger
 *          point" (so indexes range from negative through zero to
 *          positive. It is also possible that the buffer contains
 *          only negative values and zero.
 */
typedef int32 RDI_TraceIndex;


/**********************************************************************/

/*
 * RDI_InfoProc entry points
 */

/*
 * InfoProc: RDI_InfoProc(mh, RDIInfo_Trace, arg1, arg2)
 *
 * Purpose:  Inquire whether a processor on a Debug Target supports
 *           tracing. A Debug Controller should call this Info call
 *           before trying to use the other Trace calls.
 *
 * Params:   mh  handle identifies processor
 *
 * Return:   RDIError_NoError              Processor supports tracing.
 *           RDIError_UnimplementedMessage Processor does not support tracing.
 */
#define RDIInfo_Trace 0x600 /* Sanity Check - duplicated in rdi_info.h */


/*
 * Typedef:  RDI_TraceFormat
 *
 * Purpose:  An enumeration of trace formats. A Debug Controller that
 *           does not have any preference for a format the Debug Target
 *           should use may specify NoFormat.  The Uncompressed format
 *           and ARMCompressed format are defined in the RTI Specification
 *           Document TRACE-0000-PRIV-ESPC.
 *
 * THIS TYPE IS DEPRECATED, AND SHOULD NOT BE USED IN NEW CODE
 */
typedef enum
{
    RDITrace_NoFormat,
    RDITrace_Uncompressed,
    RDITrace_ARMCompressed,
    RDITrace_ARMUncompressedWithTime,
    RDITrace_ARMCompressedWithTime
} RDI_TraceFormat;

/* 
 * InfoProc: RDI_InfoProc(mh, RDITrace_Format, arg1, arg2)
 *
 * Purpose:  RDITrace_Format allows a Debug Controller to specify what
 *           format of trace data it would prefer, and allows a Debug
 *           Target to specify what format it can provide.
 *
 *           ******************* OBSELETE *******************************
 *
 * Params:
 *  In: mh   Handle of module
 *  In: arg1 (RDI_TraceFormat *) The trace format the Debug Controller would
 *                               prefer. NoFormat if the Debug Controller has
 *                               no preference.
 *  Out:arg1                     The trace format the Debug Target will
 *                               provide. If the Debug Controller cannot use
 *                               this format, it should not attempt to use the
 *                               trace information.
 *  Out:arg2 (uint32 *)          subfmt - A supplementary word describing the
 *                               sub-format used. Its interpretation is
 *                               format-dependant.
 *
 * Return:   RDIError_NoError   
 *           RDIError_UnimplementedMessage Processor does not support tracing.
 *
 *  
 * THIS FUNCTION IS DEPRECATED, AND SHOULD NOT BE USED IN NEW CODE
 */
#define RDITrace_Format (RDIInfo_Trace + 1)


/*
 * Typedef:  RDI_TraceControl
 * Purpose:  An enumeration of values that may be passed to RDITrace_Control.
 */
typedef enum
{
    RDITrace_Start,
    RDITrace_Stop,
    RDITrace_Flush,
    RDITrace_ResetMarker
} RDI_TraceControl;

/*
 * InfoProc: RDI_InfoProc(mh, RDITrace_Control, arg1, arg2)
 * Purpose:  RDITrace_TraceControl allows a Debug Controller to turn on/off
 *           tracing.
 *
 * Params:
 *  In: arg1 (RDI_TraceControl *) Pointer to a word controlling tracing. 
 *
 * Return:   RDIError_NoError   
 *           RDIError_UnimplementedMessage Processor does not support tracing.
 */
#define RDITrace_Control (RDIInfo_Trace + 2)

/*
 * Typedef:  RDI_TraceBufferExtentAction
 * Purpose:  To define the action to be taken by RDITrace_BufferExtent
 */
typedef enum {
    RDITrace_GetLow,
    RDITrace_GetHigh,
    RDITrace_GetConfiguredCapacity,
    RDITrace_GetMinimumCapacity,
    RDITrace_GetMaximumCapacity,
    RDITrace_SetCapacity
} RDI_TraceBufferExtentAction;

/*
 * InfoProc: RDI_InfoProc(mh, RDITrace_BufferExtent, arg1, arg2)
 * Purpose:  To return the lowest and highest entries currently in the trace
 *           buffer. Optionally, to also set the size of that buffer.
 *
 * Params:
 *  In: arg1 (uint32) Must be zero.
 *      arg2 (uint32) The size of the buffer to set, or zero.
 *
 * Out: arg1 (RDI_TraceIndex) The lowest index in the buffer.
 *      arg2 (RDI_TraceIndex) The highest index in the buffer.
 *
 * Return:   RDIError_NoError   
 *           RDIError_UnimplementedMessage Processor does not support tracing.
 */
#define RDITrace_BufferExtent (RDIInfo_Trace + 3)


/*
 * InfoProc: RDI_InfoProc(mh, RDITrace_GetBlockSize, arg1, arg2)
 * Purpose:  To return the optimal size for loading data from the trace
 *           collection tool.
 *
 * Params:
 * Out: arg1 (uint32) The optimal size for fetching blocks, or zero.
 *
 * Return:   RDIError_NoError   
 *           RDIError_UnimplementedMessage Processor does not support tracing.
 */
#define RDITrace_GetBlockSize (RDIInfo_Trace + 4)


/*
 * Typedef:  RDI_TraceTriggerPosition
 * Purpose:  Enumeration of locations for trigger to be placed in the buffer.
 */

typedef enum {
    RDITrace_TriggerAtEnd   = -3,
    RDITrace_TriggerAbout   = -2,
    RDITrace_TriggerAtStart = -1
} RDI_TraceTriggerPosition;

/*
 * InfoProc: RDI_InfoProc(mh, RDITrace_SetTriggerPosition, arg1, arg2)
 * Purpose:  To return the optimal size for loading data from the trace
 *           collection tool.
 *
 * Params:
 *  In: arg1 (RDI_TraceTriggerPosition) The position to place the trigger at.
 *           May also be a +ve, target-dependent, value.
 *