sordi.h

realview22.rar

/* -*-C-*-
 *
 * $Revision: 1.16.2.7.18.2 $
 *   $Author: dsinclai $
 *     $Date: 2003/07/10 09:56:02 $
 *
 * Copyright (c) ARM Limited 1999-2001.  All Rights Reserved.
 *
 * sordi.h - Shared Object RDI.
 */

#ifndef sordi_h
#define sordi_h

#include "host.h"
#include "toolconf.h"
#include "rdi.h"

#ifdef __cplusplus
extern "C" {
#endif

/*
 * SORDI: "Shared Object RDI"
 * ==========================
 *
 * SORDI defines platform independent C entry points for RDI targets
 * embedded in shared objects of some description (e.g., .so, .sl, .dll)
 * In this file "shared object" refers to a shared object, a shared library,
 * or a DLL.
 *
 * There is a very simple mapping between SORDI and WinRDI, so that on
 * windowing platforms, a platform and environment specific WinRDI wrapper
 * can be supplied.
 *
 * The main reason that we bother to define SORDI_*, rather than reusing
 * WinRDI_*, is because WinRDI is defined to use the windows specific
 * WINAPI calling convention, whereas SORDI uses the standard 'C' calling
 * conventions.
 *
 * WinRDI                          => SORDI
 * ======                             =====
 * WinRDI_Valid_RDI_DLL            => SORDI_Valid_RDI_DLL
 * WinRDI_GetVersion               => SORDI_GetVersion
 * WinRDI_SetVersion               => SORDI_SetVersion
 * WinRDI_GetRDIProcVec            => SORDI_GetRDIProcVec
 * WinRDI_Initialise               => SORDI_Initialise
 * WinRDI_Config                   => no SORDI equivalent
 *                                    WinRDI provides implementation
 * WinRDI_Register_Yield_Callback  => SORDI_RegisterYieldCallback
 * WinRDI_SetProgressFunc          => SORDI_SetProgressFunc
 * WinRDI_ZeroProgressValues       => SORDI_ZeroProgressValues
 */

/*
 * How to use SORDI
 * ================
 *
 * SORDI can be used standalone, to communicate between a non-windowing
 * debug controller and a debug target (Figure 1), and it can be used
 * in conjunction with WinRDI to communicate between a windowing debug
 * controller and a debug target (Figure 2).
 *
 * SORDI Controller   (The debug controller)
 *       |
 *       | SORDI
 *       |
 * SORDI Target       (The debug target)
 *
 * Figure 1
 *
 *
 *
 * WinRDI Controller  (The debug controller)
 *        |
 *        | WinRDI
 *        |
 * WinRDI Target and  (A thin layer providing WinRDI_Config implementation,
 * SORDI Controller    and conduits to SORDI_*)
 *        |
 *        | SORDI
 *        |
 * SORDI Target       (The debug target)
 *
 * Figure 2
 */

/*
 * How to use this file
 * ====================
 *
 * This file defines a type for each SORDI procedure:
 *
 * SORDI_*Proc   : Type definition for entry point
 *
 * This file also defines three things for each SORDI exported symbol:
 *
 * Symbol_*Proc   : Type definition for entry point
 * Symbol         : Prototype for entry point
 * Symbol_*String : String containing name of entry point
 *
 * At present, there is only one SORDI defined exported symbol: QuerySORDI
 *
 *
 * SORDI Target use
 * ================
 *
 * The SORDI target #include's "sordi.h", and then provides implementations
 * for SORDI_*.
 *
 *
 * SORDI Controller use
 * ====================
 *
 * The SORDI controller #include's "sordi.h", and reads the SORDI entry points
 * out of the target, in the following recommended host-specific ways:
 *
 *
 *    Win32
 *    -----
 *
 *       #include <windows.h>
 *
 *       HINSTANCE     *dllHandle;
 *       SORDI_*Proc   *entry;
 *
 *       soHandle = LoadLibrary(...);
 *       entry    = (SORDI_*Proc *)GetProcAddress(dllHandle, SORDI_*String);
 *
 *
 *    Solaris
 *    -------
 *       #include <dlcfn.h>
 *
 *       void        *soHandle;
 *       SORDI_*Proc *entry;
 *
 *       soHandle = dlopen(...);
 *       entry    = (SORDI_*Proc *)dlsym(soHandle, SORDI_*String);
 *
 *
 *    HPUX
 *    ----
 *       #include <dl.h>
 *
 *       shl_t        slHandle;
 *       SORDI_*Proc *entry;
 *
 *       slHandle = shl_load(...);
 *       shl_findsym(&slHandle, SORDI_*String, TYPE_PROCEDURE, (void *)&entry);
 *
 *
 *
 * SORDI Controllers that are also WinRDI Targets
 * ==============================================
 *
 * Aside from the WinRDI_Config call, a complete implementation which should
 * suit all WinRDI/SORDI conversion layers can be found in winsordi.c.  This
 * should be compiled as required by the host WinRDI environment.
 */

/************* Initialization, negotiation and validation ********************/

/*
 * Function: SORDI_Valid_RDI_DLL (required)
 *
 *  Purpose: Identify that this is an SORDI Debug Target
 *
 *  Returns: TRUE if this DLL exports SORDI, FALSE otherwise
 *
 * NOTE: bool_int is defined in host.h to be a bool sized as an in
 */
typedef bool_int SORDI_Valid_RDI_DLLProc(void);


/*
 * Function: SORDI_SetVersion (optional - multi-lingual targets only)
 *
 *  Purpose: SORDI Controller requests to use this version of RDI
 */
typedef void SORDI_SetVersionProc(int version);


/*
 * Function: SORDI_SetVersion (required)
 *
 *  Purpose: Target informs controller which RDI version it is using
 */
typedef int SORDI_GetVersionProc(void);


/*
 * Function: SORDI_Get_DLL_Description (required)
 *
 *  Purpose: Supply a static message describing the DLL. The string should be
 *           limited to 200 characters in length. This allows the Debug
 *           Controller to estimate the amount of window space required to
 *           display the string.
 */
typedef char *SORDI_Get_DLL_DescriptionProc(void);


/*
 * Function: SORDI_GetRDIProcVec (required)
 *
 *  Purpose: Return a pointer to the RDI_ProcVec exported by this DLL.
 */
typedef RDI_ProcVec *SORDI_GetRDIProcVecProc(void);

/*
 * Function: SORDI_Initialise (optional)
 *
 *  Purpose: To be called before RDI_<anything>
 *           Note: SORDI_Initialise differs from WinRDI_Intialise in that it
 *                 does not accept a windows handle, but it does supply an
 *                 error string, if required.  See winsordi.c for an example.
 *
 *  Returns: TRUE if successful, FALSE otherwise.
 *           The SORDI controller should display errstring
 *           string in a message box if initialisation was unsuccessful
 *
 * NOTE: bool_int is defined in host.h to be a bool sized as an in
 */
typedef bool_int SORDI_InitialiseProc(char const **errstring,
                                      RDI_ConfigPointer config);


/************* Yielding Control **********************************************/


typedef struct SORDI_OpaqueYieldArgStr SORDI_YieldArg;
typedef void   SORDI_YieldProc(SORDI_YieldArg *);


/*
 * Function: SORDI_Register_Yield_Callback (required)
 *
 *  Purpose: Supply a callback to yield control to other processes
 *           during Target execution. The callback is passed as a
 *           function/argument closure.
 */
typedef void SORDI_Register_Yield_CallbackProc(SORDI_YieldProc *yieldcallback,
                                               SORDI_YieldArg *hyieldcallback);


/************* Process Indicators ********************************************/


typedef struct SORDI_OpaqueProgressArgStr SORDI_ProgressArg;
typedef struct {
    SORDI_ProgressArg *handle; /* handle passed to SetProgressFunc */
    int nRead;     /* number of bytes read from channel */
    int nWritten;  /* number of bytes written           */
} SORDI_ProgressInfo;

typedef void SORDI_ProgressFuncProc(SORDI_ProgressInfo *info);


/*
 * Function: SORDI_SetProgressFunc (optional)
 *
 *  Purpose: Register a callback for the Debug Target to call
 *           periodically during download. The callback function
 *           receives data (counters) indicating the progress made so