VxWorks

开发平台：

C/C++

wtx.c：源码内容

/* wtx.c - WTX C library */
#include "copyright_wrs.h"
/*
modification history
--------------------
06k,08mar02,c_c Reworked license management.
06j,04mar02,fle SPR#73615 fix : wtxResultFree () may free already freed
memory
06i,17dec01,c_c Fixed LM file descriptor leak problem.
06h,04dec01,sn Added wtxDefaultDemanglerStyle
06g,05dec01,fle added Object directory retirving to wtxCpuInfoGet ()
06f,18oct01,c_c Updated feature name in license check.
06e,11oct01,c_c Added license bypass.
06d,03oct01,c_c Added license check. Added wtxTargetToolNameGet API.
06c,28sep01,fle Fixed wtxResultFree () to not return WTX_ERROR
06b,15jun01,pch Add new WTX_TS_INFO_GET_V2 service to handle WTX_RT_INFO
change (from BOOL32 hasFpp to UINT32 hasCoprocessor) without
breaking existing clients.
06a,30may01,kab Fixed wtxTgtHasDsp comment
05z,09may01,dtr Changing wtxTgtHasFpp , altivec for new format introduced by
hasCoprocessor. Also adding in wtxTgtHasDsp.
05y,21mar01,dtr Updating comments in code.
05x,06feb01,dtr Adding check for altivec support.
05w,18jan01,dtr Adding altivec register support.
05v,24nov99,fle SPR#28684 fix : made wtxToolAttach() update the target server
key if the first adapter is not the good one
05u,22jun99,fle made wtx compile on target side
05t,02apr99,fle fixed a problem with wtxServiceAdd that was always allocating
wdb service description even if all the wdb parameters were
set to NULL SPR 67367
05s,31mar99,fle doc : specified that wtxFileOpen does not support RDONLY flag
under WIN32
05r,23feb99,c_c Implemented an API to get the target IP address (SPR #25044).
05q,11feb99,c_c Authorize accesses to target's address 0 (SPR #25049).
05p,18jan99,c_c documented WTX_CONSOLE_LINES setting (SPR 6209).
05o,08jan99,fle doc : added REGISTRY_NAME_CLASH to wtxRegister possible
errors
05n,01dec98,pcn SPR #22867: complete the fix: in wtxObjModuleLoad(), copy the
address fields of the input parameter in the protocol input
value.
05m,30nov98,pcn Moved a badly placed #ifdef HOST for the symbol table
synchronization (SPR #22867).
05l,05nov98,fle doc : made wtxLogging been linked correctly
05k,02nov98,c_c Modified WTX_ERR_SVR_EINVAL error explanation for Load
requests.
05j,16sep98,fle Modified wtxMemDisassemble doc since its new output format
05i,22sep98,l_k Removed wtxFindExecutable.
05h,22sep98,pcn Change the returned error in wtxObjModuleLoadProgressReport.
05g,18sep98,l_k Implement wtxFindExecutable.
05f,18sep98,pcn Implement wtxObjModuleInfoAndPathGet.
05e,18sep98,pcn Removed memory leak when asynchronous load is used.
05d,04sep98,pcn Added WTX_EVENT_EVTPT_ADDED, WTX_EVENT_EVTPT_DELETED.
05c,10sep98,pcn Remove wtxResultFree from wtxObjModuleLoadStart and
wtxObjModuleLoadProgressReport.
05b,18aug98,pcn Use WTX_MSG_EVTPT_LIST_2 and doc updated.
05a,20jul98,pcn wtxObjModuleLoadProgressReport doc updated.
04z,20jul98,pcn Added evtptNum and toolId in the wtxEventpointListGet return
list.
04y,10jul98,fle removed wpwrLog calls in wtxCpuInfoGet function
04x,09jul98,fle re-added wtxCommandSend
04w,08jul98,pcn Added undefined symbols list in
wtxObjModuleLoadProgressReport result.
04v,06jul98,pcn Removed wtxObjModuleUndefSymAdd from API.
04u,02jul98,pcn Removed memory leak from wtxObjModuleLoadStart and
wtxObjModuleLoadProgressReport.
04t,19jun98,pcn Added wtxObjModuleLoadStart, wtxObjModuleLoadProgressReport,
wtxObjModuleLoadCancel.
04s,11jun98,pcn Added an input parameter at wtxEventListGet.
04r,09jun98,jmp added wtxAsyncResultFree to free memory used by a
wtxAsyncEventGet() call result, imported wtxAsyncEventGet()
from wtxAsync.c.
04q,03jun98,pcn Added 2 requests: wtxSymListByModuleNameGet and
wtxSymListByModuleIdGet.
04p,25may98,pcn Changed wtxTsLock in wtxTsTimedLock, wtxEventpointList_2 in
wtxEventpointListGet, wtxObjModuleUnload_2 in
wtxObjModuleUnloadByName.
04o,20may98,jmp modified wtxAsyncInitialize() call, now if no user defined
function is given then received events are just stored in the
asynchronous event list, those events can be get using
wtxAsyncEventGet().
04n,19may98,rhp doc: corrected wtxLogging example (supplied missing .CE)
04m,07may98,pcn Re-added WTX_TS_KILLED.
04l,30apr98,dbt added wtxHwBreakpointAdd and wtxEventpointAdd.
04k,28apr98,pcn Removed wtxCommandSend from C API.
04j,24apr98,pcn Removed wtxEventGetThread.
04i,23apr98,fle added CPU name retrieving to wtxCpuInfoGet
04h,23apr98,fle added ifdef HOST around wtxCpuInfoGet
+ added warning for HOST defined functions
04g,08apr98,fle doc: updated and added examples to wtxMemDisassemble
+ added wtxCpuInfoGet function.
04f,02apr98,pcn WTX 2: added new error codes.
04e,31mar98,fle made wtxToolAttach() always call for wtxInfo()
+ made some history cleanup
04d,27mar98,pcn Moved #ifdef HOST after functions parameters in order to
generate manual.
04c,26mar98,pcn Changed strdup in strcpy.
04b,26mar98,pcn WTX 2: Added an event filter for WTX logging. Added new
behavior of wtxObjModuleLoad_2: a file can be opened locally
or by the target server.
04a,24mar98,dbt added wtxContextStatusGet.
03z,17mar98,pcn WTX 2: wtxObjModuleChecksum: set filename to
WTX_ALL_MODULE_CHECK if moduleId is set to WTX_ALL_MODULE_ID.
03y,09mar98,pcn WTX 2: added a test of <fileName> in wtxLogging.
03x,06mar98,pcn WTX 2: changed the width test in wtxMemWidthRead/Write.
03w,05mar98,fle got rid of wtxRegistryPing() routine
03v,03mar98,pcn WTX 2: added fcntl.h for file constants.
03u,03mar98,pcn Added #ifdef for HOST side.
03t,02mar98,pcn WTX 2: added wtxAsyncNotifyEnable, wtxCacheTextUpdate,
wtxEventListGet, wtxEventpointList_2, wtxLogging,
wtxMemWidthRead, wtxMemWidthWrite, wtxObjModuleChecksum,
wtxObjModuleLoad_2, wtxObjModuleUnload_2,
wtxUnregisterForEvent, wtxThreadSigHandle. Changed
WTX_EVT_BREAKPOINT in WTX_EVT_HW_BP, wtxEventAdd,
wtxResultFree, wtxObjModuleUnload, wtxEventToStrType,
wtxTargetRtTypeGet, wtxTargetCpuTypeGet.
03s,29jan98,fle made wtxToolAttach return hWtx->errCode when unable to attch
tool (due to implementation of wtxregdSvrPing())
+ added wtxRegistryPing()
03r,28jan98,c_c Packed all wtxEvtxxxStringGet routines into one.
03q,29aug97,fle Adding the WTX_MEM_DISASSEMBLE service
+ Updating NOTE written after the "forward declarations"
+ made wtxSymListGet() usable by the WTX TCL API
+ moved tsSymListFree() from tgtsvr/server/tssymlk.c in
symLisFree()
03p,06dec96,dgp doc: correct spelling
03o,21nov96,dgp doc: change Object-Module, correct italic and bold formatting
03n,20nov96,dgp doc: correct WTX_THROW() to WTX_THROW
03m,18nov96,dgp doc: final changes, wtxGopherEval, wtxErrExceptionFunc,
wtxSymFind
03l,12nov96,c_s remove use of strerror on sun4-sunos4
03k,11nov96,dgp doc: "final" formatting for API Guide
03j,30sep96,elp put in share, adapted to be compiled on target side
(added wtxSymAddWithGroup() and wtxObjModuleUndefSymAdd()).
03i,19sep96,p_m fixed syntax error in wtxMemAlign() introduced by last
doc modification
03h,17sep96,dgp doc: API Guide updates, particularly wtxGopherEval,
wtxObjectModuleLoad
03g,05sep96,p_m Documented wtxToolIdGet() and wtxServiceAdd()
03f,05sep96,elp changed val in wtxMemSet() from UINT8 to UINT32 (SPR# 6894).
03e,02sep96,jmp added wtxToolIdGet(),
added WTX RPC service number argument to wtxServiceAdd().
03d,30aug96,elp Changed wpwrVersionGet() into wtxTsVersionGet().
03c,26jul96,pad Changed order of include files (AIX port).
03b,26jul96,dbt fixed a memory leak. Added serverDescFree to clean servor
descriptor.
03a,15jul96,dbt supressed call to wtxExchangeDelete() and
wtxExchangeTerminate() in exchange() in case of server
exchange handle (SPR #6862).
01a,24dec94,jcf written.
*/
/*
DESCRIPTION
This module implements a C-language transport-neutral interface to the
WTX messaging protocol.
A tool must always call wtxInitialize() to initialize a handle that is
used in all further WTX calls. The tool can then attach to a target
server using a call to wtxToolAttach(). Each WTX handle can only be
connected to one server at a time. After a successful call of
wtxToolAttach(), the handle is considered bound to the specified target
server until a call of wtxToolDetach() is made; then
the handle can be attached to a new target server. When the
handle is no longer required, call wtxTerminate() to release any
internal storage used by the handle. The handle must not be used after
wtxTerminate() has been called.
.CS
#include "wtx.h"
HWTX hWtx;
/@ initialize WTX session handle @/
if (wtxInitialize (&hWtx) != WTX_OK)
return (WTX_ERROR);
/@ attach to Target Server named "soubirou" @/
if (wtxToolAttach (hWtx, "soubirou", "wtxApp") != WTX_OK)
return (WTX_ERROR);
/@ register for events we want to hear about (all events here) @/
if (wtxRegisterForEvent (hWtx, ".*") != WTX_OK)
{
wtxToolDetach (hWtx);
return (WTX_ERROR);
}
/@ core of the WTX application @/
.
.
.
.
/@ detach form the Target Server @/
wtxToolDetach (hWtx);
/@ terminate WTX session @/
wtxTerminate (hWtx);
.CE
Most WTX calls return either a pointer value which is NULL on error or a
STATUS value which is WTX_ERROR if an error occurs. A descriptive string
can be obtained for the last error that occurred by calling
wtxErrMsgGet().
Note that virtually all WTX calls can fail due to an error in the message
transport layer used to carry out WTX requests. Transport errors that
are non-recoverable result in the tool being detached from the server
and an error code of WTX_ERR_API_TOOL_DISCONNECTED. If a non-fatal
error occurs, WTX_ERR_API_REQUEST_FAILED is set, except in the case of
a timeout. In that case the error is WTX_ERR_API_REQUEST_TIMED_OUT. In
the non-fatal cases, the call may be retried. In the fatal case, retrying the
call results in the error WTX_ERR_API_NOT_CONNECTED.
All API calls attempt to check the validity of the API handle provided.
The error WTX_ERR_API_INVALID_HANDLE indicates a bad handle. Other
pointer arguments are checked and WTX_ERR_API_INVALID_ARG indicates a
bad argument value such as a NULL pointer. API calls that require the
handle to be connected to a target server generate the
WTX_ERR_API_NOT_CONNECTED error if the handle is not connected.
In addition to simple error return values, the C API allows error
handlers to be installed on a per handle basis using
wtxErrHandlerAdd(). If an error occurs, the last installed
handler is called first. If it returns a TRUE value, then any
previously installed handlers are called in reverse order, in other words,
last installed, first called. The C API includes macros that use the
predefined error handler wtxErrExceptionFunc() to support C++ style
exception catching. Once an API handle has been initialized using
wtxInitiliaze(), it can be used in the WTX_TRY macro to cause API
errors to be treated like exceptions. When this is done, an API call
that would normally return an error code actually causes a jump
straight to the nearest 'catch' handler as specified using a WTX_CATCH
or WTX_CATCH_ALL macro. The previous example is shown below using this
style of error handling.
.CS
#include "wtx.h"
HWTX hWtx;
/@ initialize WTX session handle @/
if (wtxInitialize (&hWtx) != WTX_OK)
return (WTX_ERROR);
/@ Start a block in which errors will be "caught" by a catch block @/
WTX_TRY (hWtx)
{
/@ attach to Target Server named "soubirou" @/
wtxToolAttach (hWtx, "soubirou", "wtxApp");
/@ register for events we want to hear about (all events here) @/
wtxRegisterForEvent (hWtx, ".*");
/@ core of the WTX application @/
.
.
.
.
/@ detach form the Target Server @/
wtxToolDetach (hWtx);
}
/@ Catch a specific error, WTX_ERR_API_NOT_CONNECTED @/
WTX_CATCH (hWtx, WTX_ERR_API_NOT_CONNECTED)
{
fprintf (stderr, "Connection lost, exitingn");
wtxTerminate (hWtx);
exit (0);
}
/@ Catch any other errors in one handler and print error message @/
WTX_CATCH_ALL (hWtx)
fprintf (stderr, "%sn", wtxErrMsgGet (hWtx));
/@ Finish the try block and resume normal error handling @/
WTX_TRY_END (hWtx);
/@
* Normal error handling is now restored - the WTX_TRY_END macro
* must be executed for this to occur.
@/
/@ wtxTerminate() will also detach the tool if already attached @/
wtxTerminate (hWtx);
.CE
In certain circumstances, it may be useful to generate a user-defined
error or to simulate an API error from within user code. This may be
done using the WTX_THROW macro, which causes execution to jump to the
nearest handler for the error thrown or to the nearest "catch all"
handler.
Many of the C API calls are very similar to the equivalent WTX
protocol calls and the user may also refer to the appropriate section
in the f2WTX ProtocolfP reference for further information.
INCLUDE FILES: wtx.h
*/
/*
INTERNAL
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
! !
! WARNING !
! ------- !
! !
! This file is to be compiled from both host and target side. When adding new !
! functions, please care if it is target oriented or not, and try to compile !
! the target/src/wtx directory. !
! !
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
*/
/* includes */
#include <string.h>
#ifdef HOST
# include <stdlib.h>
# include <stdio.h>
# include <fcntl.h>
# ifndef WIN32
# include <unistd.h>
# endif
# ifdef SUN4_SUNOS4
extern int sys_nerr;
extern char * sys_errlist;
# endif /* SUN4_SUNOS4 */
#ifndef _DEBUG
#include "licmgt.h"
#endif /* _DEBUG */
#endif /* HOST */
#include "private/wtxp.h" /* Private (and public) headers */
#include "wtxexch.h"
#if (! defined WIN32) && (defined HOST)
# include "win32ProfileLib.h"
#endif /* WIN32 */
/*
* These five include files are here because this implementation
* of the WTX API is based on RPC calls. Full implementation of the
* "exchange" layer would remove this transport dependency
*/
#include "wtxrpc.h" /* For handling wtxregd RPC key routines */
#include "wtxxdr.h" /* For WTX XDR routines */
#include <errno.h>
#include <sys/stat.h>
#include <arpa/inet.h> /* inet_ntoa */
#ifdef HOST
# include <netdb.h> /* gethostbyname */
# include "wpwrutil.h"
# include "wtxAsync.h"
#endif
#include "sllLib.h" /* singly linked list library */
#include "pathLib.h"
/* defines */
#define STREQ(a,b) (*(a) == *(b) ? !strcmp ((a), (b)) : 0)
#define WTX_LOAD_BITMASK (WTX_LOAD_FROM_TARGET_SERVER |
WTX_LOAD_ASYNCHRONOUSLY |
WTX_LOAD_PROGRESS_REPORT)
/* typedefs */
/*
* Special dummy message type for anonymous casting and calculating field
* alignments in wtxResultFree()
*/
typedef struct wtx_msg_dummy
{
WTX_CORE wtxCore;
UINT32 field;
} WTX_MSG_DUMMY;
typedef struct wtxFreeNode /* wtxResultFree parameters */
{
SL_NODE node; /* node in list */
void * pToFree; /* pointer to free */
FUNCPTR pFreeFunc; /* function that should free pointer */
void * pMsgToFree; /* WTX message containing pToFree */
WTX_REQUEST svcNum; /* number of server service to free */
WTX_XID server; /* RPC server to connect to */
WTX_SVR_TYPE svrType; /* is it a tgtsvr or registry server */
} WTX_FREE_NODE;
/* See wtx.h and wtxp.h */
/* locals */
static const char * WTX_EVT_NONE = "NONE";
static const char * WTX_EVT_OBJ_LOADED = "OBJ_LOADED";
static const char * WTX_EVT_CTX_EXIT = "CTX_EXIT";
static const char * WTX_EVT_CTX_START = "CTX_START";
static const char * WTX_EVT_TEXT_ACCESS = "TEXT_ACCESS";
static const char * WTX_EVT_OBJ_UNLOADED = "OBJ_UNLOADED";
static const char * WTX_EVT_TGT_RESET = "TGT_RESET";
static const char * WTX_EVT_SYM_ADDED = "SYM_ADDED";
static const char * WTX_EVT_SYM_REMOVED = "SYM_REMOVED";
static const char * WTX_EVT_EXCEPTION = "EXCEPTION";
static const char * WTX_EVT_VIO_WRITE = "VIO_WRITE";
static const char * WTX_EVT_TOOL_ATTACH = "TOOL_ATTACH";
static const char * WTX_EVT_TOOL_DETACH = "TOOL_DETACH";
static const char * WTX_EVT_TOOL_MSG = "TOOL_MSG";
static const char * WTX_EVT_DATA_ACCESS = "DATA_ACCESS";
static const char * WTX_EVT_CALL_RETURN = "CALL_RETURN";
static const char * WTX_EVT_USER = "USER";
static const char * WTX_EVT_HW_BP = "HW_BP";
static const char * WTX_EVT_OTHER = "OTHER";
static const char * WTX_EVT_INVALID = "INVALID";
static const char * WTX_EVT_UNKNOWN = "UNKNOWN";
static const char * WTX_EVT_TS_KILLED = "TS_KILLED";
static const char * WTX_EVT_EVTPT_ADDED = "EVTPT_ADDED";
static const char * WTX_EVT_EVTPT_DELETED = "EVTPT_DELETED";
#if !defined (_DEBUG) && defined (NO_LICENSE)
static BOOL envVarChecked = FALSE; /* do we checked NO_LICENSE env. var? */
#endif /* NO_LICENSE */
#if defined (HOST) && !defined (_DEBUG)
static BOOL licenseCheck = TRUE; /* do check for license ? */
LOCAL int gotLicense = 0; /* Do we own a license ? */
#endif /* HOST */
/* XXX : fle : put in comment as it was not used anywhere */
/* static const char * WTX_EVT_CALL_GOT_EXC= "CALL_GOT_EXC"; */
/* Externals */
/* globals */
static BOOL internalLoadCall; /* states if it is an internal load */
/* forward declarations */
LOCAL WTX_ERROR_T exchange
(
HWTX hWtx,
UINT32 svcNum,
void * pIn,
void * pOut
);
LOCAL WTX_ERROR_T registryConnect /* establish a connection with regd */
(
HWTX hWtx /* WTX session handler */
);
LOCAL void registryDisconnect
(
HWTX hWtx
);
STATUS wtxFreeAdd /* adds elt in wtxResultFree() list */
(
HWTX hWtx, /* wtx session handler */
void * pToFree, /* pointer to be freed */
FUNCPTR pFreeFunc, /* routine to use to free pToFree */
void * pMsgToFree, /* message to free if needed */
WTX_REQUEST svcNum, /* service num to free if needed */
WTX_XID server, /* RPC server to connect to */
WTX_SVR_TYPE svrType /* connected server type */
);
LOCAL STATUS wtxMemDisassembleFree /* free disassembled insts. */
(
WTX_DASM_INST_LIST * pDasmInstList /* disassembled list to free */
);
#if 0
/* XXX : fle : for SRP#67326 */
#ifdef HOST
LOCAL STATUS wtxObjModuleLoadProgressReportFree /* free a status report */
(
HWTX hWtx, /* WTX session handler */
WTX_LOAD_REPORT_INFO * pToFree /* pointer to free */
);
#endif /* HOST */
#endif /* 0 */
LOCAL BOOL wtxResultFreeListTerminate /* empty the wtxResultFree ptrs list */
(
WTX_FREE_NODE * pWtxFreeNode, /* element in singaly linked list */
HWTX * hWtx /* WTX session handler */
);
LOCAL BOOL wtxResultFreeServerListTerminate /* empty tgtsvr pointers list */
(
WTX_FREE_NODE * pWtxFreeNode, /* element in singaly linked list */
HWTX * hWtx /* WTX session handler */
);
#if 0
/* XXX : fle : for SRP#67326 */
#ifdef HOST
LOCAL STATUS wtxAsyncResultFree_2 /* frees async event list */
(
WTX_EVENT_DESC * eventDesc /* pointer to structure to free */
);
#endif /* HOST */
#endif /* 0 */
LOCAL BOOL wtxPtrMatch /* matches a pointer value */
(
WTX_FREE_NODE * pWtxFreeNode, /* element in singaly linked list */
void * pToMatch /* pointer value to find */
);
LOCAL void wtxDescFree /* free a WTX_DESC structure */
(
WTX_DESC * pDescToFree /* WTX_DESC pointer to free */
);
LOCAL WTX_DESC * wtxDescDuplicate /* duplicates a WTX_DESC */
(
HWTX hWtx, /* current WTX session handler */
WTX_DESC * pDesc /* WTX_DESC to duplicate */
);
LOCAL void toolCleanup /* cleanups when a tool detaches */
(
HWTX hWtx /* WTX API handler */
);
LOCAL void serverDescFree /* frees server description item */
(
HWTX hWtx /* WTX API handler */
);
#ifndef HOST
LOCAL char * stringDup /* duplicates a string */
(
const char * strToDup /* string to duplicate */
);
#define strdup stringDup
#endif /* ! HOST */
/*
* NOTE: This is a list of WTX protocol calls not accessible from the
* WTX C API and is based on the service numbers in wtxmsg.h
*
* WTX_VIO_READ - not implemented in server (obsolete?)
* WTX_SYM_TBL_CREATE/DELETE - to do
* WTX_SYM_TBL_LIST - to do
* WTX_WTX_SERVICE_LIST - not implemented in server - undefined
* WTX_WDB_SERVICE_LIST - not implemented in server - undefined
* WTX_OBJ_KILL - (currently TS kill only) Enough ?
* WTX_OBJ_RESTART - undefined (obsolete ?)
*/
#if defined (HOST) && !defined (_DEBUG)
/*******************************************************************************
*
* wtxLmDeauthorize - Check-in a license
*
* This routine releases a license previously checked-out by wtxLmAuthorize ().
* Typically, it is called when the process exits.
*
* RETURNS: N/A
*
* SEE ALSO: wtxLmAuthorize ()
*
* NOMANUAL
*/
void wtxLmDeauthorize (void)
{
/* if we own a license, release it. */
if (gotLicense)
{
flexlmDeauthorize ();
}
}
/*******************************************************************************
*
* wtxLmAuthorize - Check-out a license
*
* This routine establishes a connection to the license server, and tries to
* Check out a license.
* Currently, we check a license upon first call to this routine. Once we get a
* license, we always return OK to any subsequent call to this routine.
* We register a handle to release the license when the tool exits.
*
* RETURNS: WTX_OK or WTX_ERROR if the check-out fails.
*
* SEE ALSO: wtxLmDeauthorize ()
*
* NOMANUAL
*/
STATUS wtxLmAuthorize (void)
{
/* If we already got a license return OK */
if (gotLicense)
return OK;
/* First time: check for a valid license */
if (flexlmAuthorize (FEATURE_TORNADO_2_2, VERSION_TORNADO_2_2, 1) != OK)
return ERROR;
gotLicense = 1; /* we got one! */
/* Record a handler to release the license when the process exits */
atexit (wtxLmDeauthorize);
return OK; /* Return sucess */
}
#endif
/*******************************************************************************
*
* wtxToolAttach - connect a WTX client to the target server
*
* This routine establishes a connection to the target server
* called <serverName> and announces the client as a WTX tool called
* <toolName>. If <serverName> does not contain an `@' character, it is
* used as a regular expression; if it matches more than one (registered)
* target server name, an error is returned. If <serverName> contains
* an `@' character then it must be an exact match for a valid target
* server name.
*
* RETURNS: WTX_OK or WTX_ERROR if the attach fails.
*
* ERRORS:
* .iP WTX_ERR_API_ALREADY_CONNECTED 12
* The handle is already connected to a target server.
* .iP WTX_ERR_API_SERVER_NOT_FOUND
* <serverName> does not match a target server name using the above criteria.
* .iP WTX_ERR_API_AMBIGUOUS_SERVER_NAME
* <serverName> matches more than one target server name.
* .iP WTX_ERR_SVR_DOESNT_RESPOND
* <serverName> is dead : no RPC connection can be achieved
* .iP WTX_ERR_SVR_IS_DEAD
* <serverName> is dead : server has been found dead
* .iP WTX_ERR_SVR_INVALID_LICENSE
* No license could be checked-out for this tool.
*
* SEE ALSO: WTX_TOOL_ATTACH, wtxToolDetach(), wtxToolConnected(), wtxInfoQ()
*/
STATUS wtxToolAttach
(
HWTX hWtx, /* WTX API handle */
const char * serverName, /* Target Server name */
const char * toolName /* tool name */
)
{
WTX_MSG_TOOL_DESC in; /* WTX param */
WTX_MSG_TOOL_DESC * pOut = NULL; /* WTX result */
WTX_DESC_Q * pTsDescQ = NULL; /* Q Info about Target Server */
WTX_ERROR_T callStat; /* status of WTX call */
WTX_ERROR_T errCode=WTX_ERR_NONE; /* connection init status */
WTX_DESC * pSaveDesc = NULL; /* saved server desc */
WTX_DESC * pTsDesc = NULL; /* Info about Target Server */
WTX_DESC * pNewDesc = NULL; /* for updated tgtsvr entry */
char * envUser = NULL; /* result of getenv(USER) */
char * oldKey = NULL; /* for multi adapters tgtsvrs */
char * tmpKey = NULL; /* for multi adapters tgtsvrs */
BOOL usePMap = FALSE; /* do we use port mapper ? */
char userName [256]; /* to format "user@host" */
char serverAtHost [256]; /* serverName@host */
char hostNameBuf [32]; /* for gethostname () */
int ipNum = 0; /* number of IP addr in list */
#ifdef WIN32
char usrName [256]; /* holds name for Win32 */
#endif
WTX_CHECK_HANDLE (hWtx, WTX_ERROR);
if (wtxToolConnected (hWtx))
WTX_ERROR_RETURN (hWtx, WTX_ERR_API_ALREADY_CONNECTED, WTX_ERROR);
if (hWtx->pServerDesc)
{
wtxResultFree (hWtx, hWtx->pServerDesc);
hWtx->pServerDesc = NULL;
}
if (toolName == NULL)
WTX_ERROR_RETURN (hWtx, WTX_ERR_API_INVALID_ARG, WTX_ERROR);
#if defined (HOST) && !defined (_DEBUG)
/*
* License check (HOST side, release version only):
* if NO_LICENSE if defined for this module, we'll look if NO_LICENSE is
* defined in the process' environment. If this is the case, we skip
* license check.
* In all cases, GDB won't be checked for license.
*/
#ifdef NO_LICENSE
if (!envVarChecked)
{
licenseCheck = (wpwrGetEnv ("NO_LICENSE") != NULL)?FALSE:TRUE;
envVarChecked = TRUE;
}
#endif /* NO_LICENSE */
if (licenseCheck)
licenseCheck = (strstr (toolName, "gdb") == NULL)?TRUE:FALSE;
if ((licenseCheck) && (wtxLmAuthorize () != OK))
{
WTX_ERROR_RETURN (hWtx, WTX_ERR_SVR_INVALID_LICENSE, WTX_ERROR);
}
#endif /* HOST */
/* save current name in serverAtHost */
strcpy (serverAtHost, serverName);
if (!strchr (serverName, '@')) /* name: tgtsvr */
{
pTsDescQ = wtxInfoQ (hWtx, (char *)serverName, "tgtsvr", NULL);
if (pTsDescQ == NULL)
WTX_ERROR_RETURN (hWtx, WTX_ERR_API_SERVER_NOT_FOUND, WTX_ERROR);
if (pTsDescQ->pNext != NULL)
{
wtxResultFree (hWtx, pTsDescQ);
WTX_ERROR_RETURN (hWtx, WTX_ERR_API_AMBIGUOUS_SERVER_NAME,
WTX_ERROR);
}
/*
* There is an @ in the target server name, let's see if it is really
* in registry data base.
*/
strcpy (serverAtHost, pTsDescQ->wpwrName);
wtxResultFree (hWtx, pTsDescQ);
}
pTsDesc = wtxInfo (hWtx, (char *)serverAtHost); /* name: tgtsvr@host */
if (pTsDesc == NULL)
WTX_ERROR_RETURN (hWtx, hWtx->errCode, WTX_ERROR);
hWtx->pServerDesc = pTsDesc;
/* allocate space to copy server information */
if ( (pSaveDesc = (WTX_DESC *) malloc (sizeof (WTX_DESC))) == NULL)
{
wtxResultFree (hWtx, hWtx->pServerDesc);
WTX_ERROR_RETURN (hWtx, WTX_ERR_API_MEMALLOC, WTX_ERROR);
}
/* copy server information */
memcpy ((void *) pSaveDesc, (void *) hWtx->pServerDesc, sizeof (WTX_DESC));
if (hWtx->pServerDesc->wpwrName != NULL)
{
if ((pSaveDesc->wpwrName = (char *) malloc (strlen
(hWtx->pServerDesc->wpwrName) + 1)) == NULL)
{
free (pSaveDesc);
wtxResultFree (hWtx, hWtx->pServerDesc);
WTX_ERROR_RETURN (hWtx, WTX_ERR_API_MEMALLOC, WTX_ERROR);
}
strcpy (pSaveDesc->wpwrName, hWtx->pServerDesc->wpwrName);
}
if (hWtx->pServerDesc->wpwrKey != NULL)
{
if ((pSaveDesc->wpwrKey = (char *) malloc (strlen
(hWtx->pServerDesc->wpwrKey) + 1)) == NULL)
{
free (pSaveDesc->wpwrName);
free (pSaveDesc);
wtxResultFree (hWtx, hWtx->pServerDesc);
WTX_ERROR_RETURN (hWtx, WTX_ERR_API_MEMALLOC, WTX_ERROR);
}
strcpy (pSaveDesc->wpwrKey, hWtx->pServerDesc->wpwrKey);
}
if (hWtx->pServerDesc->wpwrType != NULL)
{
if ((pSaveDesc->wpwrType = (char *) malloc (strlen
(hWtx->pServerDesc->wpwrType) + 1)) == NULL)
{
free (pSaveDesc->wpwrKey);
free (pSaveDesc->wpwrName);
free (pSaveDesc);
wtxResultFree (hWtx, hWtx->pServerDesc);
WTX_ERROR_RETURN (hWtx, WTX_ERR_API_MEMALLOC, WTX_ERROR);
}
strcpy (pSaveDesc->wpwrType, hWtx->pServerDesc->wpwrType);
}
wtxResultFree (hWtx, hWtx->pServerDesc);
registryDisconnect (hWtx);
hWtx->pServerDesc = pSaveDesc;
/* first just initialise the connection */
if (wtxExchangeInitialize (&hWtx->server) != WTX_OK ||
wtxExchangeInstall (hWtx->server,
wtxRpcExchangeCreate,
wtxRpcExchangeDelete,
wtxRpcExchange,
wtxRpcExchangeFree,
wtxRpcExchangeControl) != WTX_OK)
{
/* Record the error code */
errCode = wtxExchangeErrGet ((WTX_XID) hWtx->server);
/* free server descriptor */
serverDescFree (hWtx);
/* Cleanup the exchange */
wtxExchangeTerminate ((WTX_XID) hWtx->server);
hWtx->server = (WTX_XID) NULL;
WTX_ERROR_RETURN (hWtx, errCode, WTX_ERROR);
}
use_pmap:
if (wtxExchangeCreate ((WTX_XID) hWtx->server,
hWtx->pServerDesc->wpwrKey, usePMap) != WTX_OK)
{
/*
* if the error comes from the wtxExchangeCreate() routine and if
* it has to deal with the IP address, then let's try to see if we
* can change the IP adapter
*/
if (wtxExchangeErrGet (hWtx->server) == WTX_ERR_EXCHANGE_NO_SERVER)
{
/* if there are several adapter, let's try the next one */
oldKey = hWtx->pServerDesc->wpwrKey;
while ((tmpKey = wtxRpcKeyIPListUpdate (hWtx->pServerDesc->wpwrKey,
++ipNum)) != NULL)
{
if (wtxExchangeCreate ((WTX_XID) hWtx->server, tmpKey, usePMap)
== WTX_OK)
{
HWTX regdHWtx; /* wtx handle for registry */
/* this is the right key, save it and update registry */
hWtx->pServerDesc->wpwrKey = tmpKey;
free (oldKey);
/* init the registry session */
wtxInitialize (&regdHWtx);
/* update registry entry */
if (wtxUnregister (regdHWtx, hWtx->pServerDesc->wpwrName)
!= WTX_OK)
WTX_ERROR_RETURN (hWtx, regdHWtx->errCode, WTX_ERROR);
if ( (pNewDesc = wtxRegister (regdHWtx,
hWtx->pServerDesc->wpwrName,
hWtx->pServerDesc->wpwrType,
tmpKey)) == NULL)
{
WTX_ERROR_RETURN (hWtx, regdHWtx->errCode, WTX_ERROR);
}
/*
* end the registry session, wtxTerminate should free the
* new description, no need to free it manuall.
*/
wtxTerminate (regdHWtx);
goto updated_key;
}
}
/* ok, now try again with the port mapper then ... */
if (!usePMap)
{
usePMap = TRUE;
goto use_pmap;
}
}
/* Record the error code */
errCode = wtxExchangeErrGet ((WTX_XID) hWtx->server);
/* free server descriptor */
serverDescFree (hWtx);
/* Cleanup the exchange */
wtxExchangeTerminate ((WTX_XID) hWtx->server);
hWtx->server = (WTX_XID) NULL;
WTX_ERROR_RETURN (hWtx, errCode, WTX_ERROR);
}
updated_key:
memset (&in, 0, sizeof (in));
in.wtxToolDesc.toolName = (char *) toolName;
#ifdef HOST
#ifdef WIN32
{
UINT32 size = sizeof (usrName);
if(!GetUserName (usrName, &size))
envUser = NULL;
else
envUser = usrName;
}
#else
envUser = getenv ("USER");
#endif /* WIN32 */
gethostname (hostNameBuf, sizeof (hostNameBuf));
#else
envUser = sysBootParams.usr;
strcpy (hostNameBuf, sysBootParams.targetName);
#endif /* HOST */
if (envUser == NULL)
envUser = "unknown";
if (hostNameBuf[0] == '')
strcpy (hostNameBuf, "unknown");
sprintf (userName, "%.24s@%.24s", envUser, hostNameBuf);
in.wtxToolDesc.userName = userName;
pOut = calloc (1, sizeof (WTX_MSG_TOOL_DESC));
if (pOut == NULL)
{
/* Close the connection to the server */
wtxExchangeDelete (hWtx->server);
/* free server descriptor */
serverDescFree (hWtx);
/* Clean up the exchange */
wtxExchangeTerminate (hWtx->server);
hWtx->server = NULL;
WTX_ERROR_RETURN (hWtx, WTX_ERR_API_MEMALLOC, WTX_ERROR);
}
/* Do the attach call */
callStat = exchange (hWtx, WTX_TOOL_ATTACH, &in, pOut);
if (callStat != WTX_ERR_NONE)
{
/* Close the connection to the server */
wtxExchangeDelete (hWtx->server);
/* free server descriptor */
serverDescFree (hWtx);
/* Clean up the exchange */
wtxExchangeTerminate (hWtx->server);
hWtx->server = NULL;
WTX_ERROR_RETURN (hWtx, callStat, WTX_ERROR);
}
/* Set the msgToolId and pToolDesc filed in the HWTX for future use */
hWtx->pToolDesc = &pOut->wtxToolDesc;
hWtx->msgToolId.wtxCore.objId = pOut->wtxToolDesc.id;
if (wtxFreeAdd (hWtx, (void *) &pOut->wtxToolDesc, NULL, pOut,
WTX_TOOL_ATTACH, hWtx->server, WTX_SVR_SERVER) != WTX_OK)
{
WTX_ERROR_RETURN (hWtx, wtxErrGet (hWtx), WTX_ERROR);
}
return (WTX_OK);
}
/*******************************************************************************
*
* wtxToolConnected - check to see if a tool is connected to a target server
*
* This routine checks if the tool represented by <hWtx> is currently
* connected to a target server.
*
* NOTE: If <hWtx> is an invalid handle then FALSE is returned.
*
* RETURNS: TRUE if the tool is connected, FALSE otherwise.
*
* SEE ALSO: wtxErrClear(), wtxErrGet()
*/
BOOL32 wtxToolConnected
(
HWTX hWtx /* WTX API handle */
)
{
WTX_CHECK_HANDLE (hWtx, FALSE);
return (hWtx->server != NULL);
}
/*******************************************************************************
*
* wtxToolDetach - detach from the target server
*
* This routine detaches from the target server.
* The connection status for <hWtx> is cleared and any memory
* allocated by the tool attach is freed.
*
* CLEANUP
* This routine cleans all the tools allocated pointers. All items that have been
* allocated by `wtx' calls during the wtxToolAttach() are freed. All the
* elements are freed calling for the wtxResultFree() routine. This makes
* impossible to access data from previous `wtx' calls.
*
* NOTE: Even if the detach fails internally (for example, the server
* it is attached to has died), the API still puts the handle into a
* detached state and performs all necessary internal cleanup. In this
* case the internal error is `not' reported since the tool is no longer
* attached and the handle can subsequently be attached to another server.
*
* RETURNS: WTX_OK or WTX_ERROR.
*
* SEE ALSO: WTX_TOOL_DETACH, wtxToolAttach()
*/
STATUS wtxToolDetach
(
HWTX hWtx /* WTX API handle */
)
{
WTX_ERROR_T callStat; /* WTX call status */
WTX_MSG_RESULT out; /* WTX result */
WTX_CHECK_HANDLE (hWtx, WTX_ERROR);
if (! wtxToolConnected(hWtx))
return (WTX_OK);
#ifdef HOST
/* close async. notif */
wtxAsyncStop (&hWtx->asyncHandle);
hWtx->asyncHandle = NULL;
#endif /* HOST */
memset (&out, 0, sizeof (out));
callStat = exchange (hWtx, WTX_TOOL_DETACH, &hWtx->msgToolId, &out);
/* Free allocated memory and close neatly the connection to the server */
if (callStat == WTX_ERR_NONE)
wtxExchangeFree (hWtx->server, WTX_TOOL_DETACH, &out);
/*
* free the server descriptor and the strings that were allocated in
* wtxToolAttach().
*/
serverDescFree (hWtx);
toolCleanup(hWtx);
/* Actively ignore any errors that may occur */
return (WTX_OK);
}
/*******************************************************************************
*
* wtxInitialize - initialization routine to be called by the WTX client
*
* This routine allocates a handle structure for the tool's use and
* does any initialization required for use of the WTX interface. All
* subsequent calls by the tool should use the handle returned in <phWtx>.
* If WTX_ERROR is returned and the handle <phWtx> is zero, then the
* initialization failed because the internal handle structure could
* not be allocated. Otherwise use wtxErrMsgGet() to find the cause
* of the error.
*
* RETURNS: WTX_OK or WTX_ERROR if the initialization fails.
*
* ERRORS:
* .iP WTX_ERR_API_INVALID_ARG 12
* The pointer <phWtx> is NULL.
* .iP WTX_ERR_API_MEMALLOC
* The handle cannot be allocated.
*
* SEE ALSO: wtxTerminate(), wtxVerify()
*/
STATUS wtxInitialize
(
HWTX * phWtx /* RETURN: handle to use in subsequent API calls */
)
{
if (phWtx == NULL)
WTX_ERROR_RETURN (NULL, WTX_ERR_API_INVALID_ARG, WTX_ERROR);
*phWtx = calloc (1, sizeof (struct _wtx));
if (*phWtx == NULL)
WTX_ERROR_RETURN (NULL, WTX_ERR_API_MEMALLOC, WTX_ERROR);
/* Set the field that identifies this as a valid handle */
(*phWtx)->self = *phWtx;
(*phWtx)->pWtxFreeList = NULL;
return (WTX_OK);
}
/*******************************************************************************
*
* wtxTerminate - terminate the use of a WTX client handle
*
* This routine destroys the specified context handle so it may no
* longer be used in WTX API calls. If the tool is attached to a
* target server, it is first detached. (It is forcibly detached if
* errors make a normal detach impossible.) Any memory allocated by
* the handle is freed and the handle is invalidated; any subsequent
* use causes an abort.
*
* CLEANUP
* This routine frees all the `wtx' pointers that have been allocated by `wtx'
* calls during the session. Thus, it makes it impossible to address them anymore
*
* RETURNS: WTX_OK or WTX_ERROR.
*
* SEE ALSO: wtxInitialize(), wtxVerify()
*/
STATUS wtxTerminate
(
HWTX hWtx /* WTX API handle */
)
{
WTX_CHECK_HANDLE (hWtx, WTX_ERROR);
wtxToolDetach (hWtx);
/*
* as we exit the WTX session, all the pointers from the wtxResultFree()
* pointers list should be freed.
*/
if (hWtx->pWtxFreeList != NULL)
{
if (sllCount (hWtx->pWtxFreeList) > 0)
{
sllEach (hWtx->pWtxFreeList, wtxResultFreeListTerminate,
(int) &hWtx);
}
sllDelete (hWtx->pWtxFreeList);
hWtx->pWtxFreeList = NULL;
}
if (hWtx->pServerDesc)
{
wtxResultFree (hWtx, hWtx->pServerDesc);
}
if (hWtx->pSelfDesc)
{
wtxResultFree (hWtx, hWtx->pSelfDesc);
}
if (hWtx->registry)
wtxExchangeDelete (hWtx->registry);
wtxExchangeTerminate (hWtx->server);
wtxExchangeTerminate (hWtx->registry);
/* Invalidate this handle in case it is used after terminate */
hWtx->self = NULL;
/* Now free up the handle memory */
free (hWtx);
return (WTX_OK);
}
/*******************************************************************************
*
* wtxErrSet - set the error code for the handle
*
* This routine sets the error value <errCode> in the handle specified
* by <hWtx> so that wtxErrGet() can return <errCode> as the error.
*
* NOTE: Error handlers for the handle are not called. To set the error
* code and call the registered error handlers, use wtxErrDispatch().
*
* RETURNS: WTX_OK or WTX_ERROR.
*
* SEE ALSO: wtxErrGet(), wtxErrMsgGet(), wtxErrClear(), wtxErrDispatch().
*/
STATUS wtxErrSet
(
HWTX hWtx, /* WTX API handle */
UINT32 errCode /* error value to set */
)
{
WTX_CHECK_HANDLE (hWtx, WTX_ERROR);
/* Ensure any allocated strings are freed up */
wtxErrClear (hWtx);
hWtx->errCode = errCode;
return (WTX_OK);
}
/*******************************************************************************
*
* wtxErrGet - return the last error for a handle
*
* This routine returns the last error that occurred for the <hWtx> handle.
* The error code is only valid after an error is reported by one of the
* API calls. To check for an error after a series of API calls use
* wtxErrClear() to clear the error status at the start and call wtxErrGet()
* at the end.
*
* RETURNS: The last error code or WTX_ERROR if the handle is invalid.
*
* SEE ALSO: wtxErrMsgGet(), wtxErrSet(), wtxErrClear()
*/
WTX_ERROR_T wtxErrGet
(
HWTX hWtx /* WTX API handle */
)
{
WTX_CHECK_HANDLE (hWtx, WTX_ERROR);
return (hWtx->errCode);
}
/*******************************************************************************
*
* wtxErrHandlerAdd - add an error handler for the WTX handle
*
* This routine adds a new error handler to the list of registered handlers
* for the handle <hWtx>. The last error handler added is the first one
* called when an error occurs. The function <pFunc> is called with three
* arguments, the handle on which the error occurred, the client data
* <pClientData>, and a call data parameter which is the error code. If the
* function returns the value TRUE then each previously registered handler
* function is called in turn until all are called or one returns the
* value FALSE.
*
* EXAMPLE
* The following is a sample error handler:
*
* .CS
* BOOL32 errorHandler
* (
* HWTX hWtx, /@ WTX API handle @/
* void * pClientData, /@ client data from wtxErrHandlerAdd() call @/
* void * errCode /@ error code passed from wtxErrDispatch() @/
* )
*
* {
* /@ print an error message @/
*
* fprintf (stderr,
* "Error %s (%d) from server %sn",
* wtxErrMsgGet (hWtx),
* (WTX_ERROR_T) errCode, /@ or use wtxErrGet() @/
* wtxTsNameGet (hWtx));
*
* /@ return TRUE allowing previously installed handlers to be called @/
*
* return TRUE;
* }
* .CE
*
* RETURNS: A new handler ID or NULL on failure.
*
* ERRORS:
* .iP WTX_ERR_API_MEMALLOC 12
* No memory is available to add the new handler.
*
* SEE ALSO: wtxErrHandlerRemove(), wtxErrDispatch()
*/
WTX_HANDLER_T wtxErrHandlerAdd
(
HWTX hWtx, /* WTX API handle */
WTX_HANDLER_FUNC pFunc, /* function to call on error */
void * pClientData /* data to pass function */
)
{
WTX_HANDLER_T descNew;
WTX_CHECK_HANDLE (hWtx, NULL);
descNew = calloc (1, sizeof (_WTX_HANDLER_T));
if (descNew == NULL)
WTX_ERROR_RETURN (hWtx, WTX_ERR_API_MEMALLOC, NULL);
descNew->pFunc = pFunc;
descNew->pClientData = pClientData;
descNew->prev = hWtx->errHandler;
hWtx->errHandler = descNew;
return descNew;
}
/*******************************************************************************
*
* wtxErrHandlerRemove - remove an error handler from the WTX handle
*
* This function removes the error handler referenced by <errHandler> from
* the handler list for <hWtx>. The error handler ID <errHandler> must be a
* valid error handler ID returned by a call of wtxErrHandlerAdd().
*
* NOTE: It is safe for wtxErrHandlerRemove() to be called from within an
* error handler function, even if the call is to remove itself.
*
* RETURNS: WTX_OK or WTX_ERROR.
*
* ERRORS:
* .iP WTX_ERR_API_HANDLER_NOT_FOUND 12
* <errHandler> is not a valid handler ID.
*
* SEE ALSO: wtxErrHandlerAdd(), wtxErrDispatch()
*/
STATUS wtxErrHandlerRemove
(
HWTX hWtx, /* WTX API handle */
WTX_HANDLER_T errHandler /* Error handler to remove */
)
{
WTX_HANDLER_T desc;
WTX_HANDLER_T last;
WTX_CHECK_HANDLE (hWtx, WTX_ERROR);
last = NULL;
for (desc = hWtx->errHandler; desc; desc = desc->prev)
{
if (desc == errHandler)
{
/* Got the one to remove */
if (last)
last->prev = desc->prev;
else
hWtx->errHandler = desc->prev;
free (desc);
return (WTX_OK);
}
last = desc;
}
WTX_ERROR_RETURN (hWtx, WTX_ERR_API_HANDLER_NOT_FOUND, WTX_ERROR);
}
/*******************************************************************************
*
* wtxErrDispatch - dispatch an error with supplied code for the given handle
*
* This function records the error <errCode> against the handle <hWtx> and
* calls all the registered error handlers for it until one returns FALSE.
*
* RETURNS: WTX_OK or WTX_ERROR if the handle is invalid.
*
* SEE ALSO: wtxErrHandlerAdd()
*/
STATUS wtxErrDispatch
(
HWTX hWtx, /* WTX API handle */
WTX_ERROR_T errCode /* error code to register */
)
{
WTX_HANDLER_T desc;
BOOL32 continueToDispatch;
/* cannot use macro here as it will cause recursion via WTX_ERROR_RETURN */
if (hWtx == NULL || hWtx->self != hWtx)
{
/* cannot do anything with the error */
/* FIXME: should implement a global error handler */
return WTX_ERROR;
}
/* Record the error code */
hWtx->errCode = errCode;
hWtx->errMsg = NULL;
continueToDispatch = TRUE;
desc = hWtx->errHandler;
/* Dispatch the error to all the error handlers */
while ((desc != NULL) && continueToDispatch)
{
WTX_HANDLER_T prev;
/* Just in case the handler removes itself! */
prev = desc->prev;
/* Be sure the function is non-null */
if (desc->pFunc)
continueToDispatch = desc->pFunc (hWtx,
desc->pClientData,
(void *) errCode);
desc = prev;
}
return (WTX_OK);
}
/*******************************************************************************
*
* wtxErrMsgGet - fetch the last network WTX API error string
*
* This routine gets a meaningful string for the last WTX API call
* that returned WTX_ERROR. The string is only valid after a WTX
* call has returned an error.
*
* NOTE: The return value is a pointer to internal data and must
* not be freed by the caller. Also the string is only valid until
* the next error occurs or wtxErrClear() is called. It must
* be copied by the caller if the value must be stored.
*
* RETURNS: A pointer to a string or NULL if an error has occurred.
*
* SEE ALSO: wtxErrClear(), wtxErrGet()
*/
const char * wtxErrMsgGet
(
HWTX hWtx /* WTX API handle */
)
{
WTX_CHECK_HANDLE (hWtx, NULL);
/* This allows for caching of previous values but is not yet implemented */
if (hWtx->errMsg != NULL)
return hWtx->errMsg;
else
{
hWtx->errMsg = wtxErrToMsg (hWtx, hWtx->errCode);
return hWtx->errMsg;
}
}
/*******************************************************************************
*
* wtxErrToMsg - convert an WTX error code to a descriptive string
*
* This routine takes an error code which has been returned by a WTX API
* call and returns a descriptive string. The value returned is a pointer
* to a string in statically allocated memory. The string must be copied
* if the value is to be stored and it must not be freed by the caller.
*
* RETURNS: A pointer to an error string.
*/
const char * wtxErrToMsg
(
HWTX hWtx,
WTX_ERROR_T errCode
)
{
static char buffer [256];
if (errCode == WTX_ERR_NONE)
return "No error";
if ((errCode > WTXERR_BASE_NUM) && (errCode < WTX_ERR_LAST))
{
FILE * fp;
#ifdef WIN32
sprintf (buffer, "%s\host\resource\tcl\wtxerrdb.tcl",
getenv ("WIND_BASE"));
#else
sprintf (buffer, "%s/host/resource/tcl/wtxerrdb.tcl",
getenv ("WIND_BASE"));
#endif
fp = fopen (buffer, "r");
while (fp != NULL && ! ferror (fp))
{
UINT32 errNum;
char errStr[256];
if (fgets (buffer, sizeof (buffer), fp) == NULL)
break;
if (sscanf (buffer, "set wtxError(0x%x) %s", &errNum, errStr) == 2
&& (errNum == (UINT32)errCode))
{
sprintf (buffer, "%s", errStr);
fclose (fp);
return buffer;
}
}
if (fp)
fclose (fp);
/* A WTX error we have no error text for */
sprintf (buffer, "WTX error %#x", errCode);
}
#ifdef SUN4_SUNOS4
/*
* Avoid strerror() on SUNOS4, as this will pull libiberty.a into
* the link, making it more difficult to bind this code into a
* shared library.
*/
else if (errCode > 0 && errCode < sys_nerr && sys_errlist [errCode] != NULL)
{
/* Probably a system error */
sprintf (buffer, "%s (%d)", sys_errlist [errCode], errCode);
}
#else /* !SUN4_SUNOS4 */
else if (strerror (errCode) != NULL)
/* Probably a system error */
sprintf (buffer, "%s (%d)", strerror (errCode), errCode);
#endif /* SUN4_SUNOS4 */
else
/* Some other error we don't know about */
sprintf (buffer, "error %d (%#x)", errCode, errCode);
return buffer;
}
/*******************************************************************************
*
* wtxErrClear - explicitly clear any error status for the tool
*
* This routine clears an error message already recorded. It can be
* called before a WTX routine if you want to test for an error afterwards
* by checking whether wtxErrGet() returns a non-zero value.
*
* RETURNS: WTX_OK or WTX_ERROR.
*
* SEE ALSO: wtxErrGet(), wtxErrMsgGet(), wtxErrSet()
*/
STATUS wtxErrClear
(
HWTX hWtx /* WTX API handle */
)
{
WTX_CHECK_HANDLE (hWtx, WTX_ERROR);
hWtx->errCode = WTX_ERR_NONE;
hWtx->errMsg = NULL;
return (WTX_OK);
}
/*******************************************************************************
*
* wtxErrExceptionFunc - a function to handle an error using longjmp()
*
* This function is called as part of the error handling process shown in the
* discussion of C++ style exception catching in the wtx library description
* (f2WTX C LibraryfP). The WTX_TRY macro, which registers the error
* handler wtxErrExceptionFunc(), is found in wtx.h. <pClientData> contains
* the address of <jumpBuf> from WTX_TRY and <pCallData> is the error code
* that is returned by WTX_TRY and should be cast to the type WTX_ERROR_T..
*
* RETURNS: FALSE if <pClientData> is NULL, otherwise it does not return.
* It executes a longjmp() back to <jumpBuf> in the WTX_TRY macro, which
* returns the error code passed back by <pCallData>.
*
* SEE ALSO: wtxErrHandlerAdd(), wtxErrDispatch()
*/
BOOL32 wtxErrExceptionFunc
(
HWTX hWtx, /* WTX API handle */
void * pClientData, /* pointer to a jump buffer */
void * pCallData /* error code to return via setjmp() */
)
{
if (pClientData != NULL)
longjmp (pClientData, (int) pCallData);
return FALSE;
}
/*******************************************************************************
*
* wtxClientDataGet - get the client data associated with the WTX handle
*
* This routine sets the pointer pointed at by <ppClientData> to the
* value set by the last call to wtxClientDataSet() for the handle <hWtx>.
*
* RETURNS: WTX_OK or WTX_ERROR.
*
* ERRORS:
* .iP WTX_ERR_API_INVALID_ARG 12
* <ppClientData> is NULL.
*
* SEE ALSO: wtxClientDataSet()
*/
STATUS wtxClientDataGet
(
HWTX hWtx, /* WTX API handle */
void ** ppClientData /* RETURN: pointer to client data pointer */
)
{
WTX_CHECK_HANDLE (hWtx, WTX_ERROR);
if (ppClientData == NULL)
WTX_ERROR_RETURN (hWtx, WTX_ERR_API_INVALID_ARG, WTX_ERROR);
*ppClientData = hWtx->pClientData;
return (WTX_OK);
}
/*******************************************************************************
*
* wtxClientDataSet - set the client data associated with the WTX handle
*
* This routine causes the value <pClientData> to be associated with the
* WTX API handle <hWtx>. The client data can be used by the
* caller in any way and, except when in the set and get routines,
* is not used or altered in any way by the WTX API. The initial value
* of the client data before it is set is always NULL.
*
* RETURNS: WTX_OK or WTX_ERROR.
*
* SEE ALSO: wtxClientDataGet().
*/
STATUS wtxClientDataSet
(
HWTX hWtx, /* WTX API handle */
void * pClientData /* value to associate with handle */
)
{
WTX_CHECK_HANDLE (hWtx, WTX_ERROR);
hWtx->pClientData = pClientData;
return (WTX_OK);
}
/*******************************************************************************
*
* wtxAgentModeGet - get the mode of the target agent
*
* This routine returns the running mode of the target agent that the
* current target server is attached to.
*
* EXPAND ../../../include/wtxtypes.h WTX_AGENT_MODE_TYPE
*
* RETURNS: The current agent running mode or WTX_ERROR.
*
* SEE ALSO: WTX_AGENT_MODE_GET, wtxTsInfoGet(), wtxAgentModeSet()
*/
WTX_AGENT_MODE_TYPE wtxAgentModeGet
(
HWTX hWtx /* WTX API handle */
)
{
WTX_ERROR_T callStat; /* client status */
WTX_AGENT_MODE_TYPE result; /* debug agent mode */
WTX_MSG_RESULT out; /* WTX result */
/*
* All API calls that require a connection to the target server
* should use the WTX_CHECK_CONNECTED macro before doing anything else.
* This macro also calls WTX_CHECK_HANDLE to validate the handle.
*/
WTX_CHECK_CONNECTED (hWtx, WTX_ERROR);
/* Always remember to initialize the out params */
memset (&out, 0, sizeof (out));
callStat = exchange (hWtx, WTX_AGENT_MODE_GET, &hWtx->msgToolId, &out);
/*
* If there is an error we don't need to free the result with
* wtxExchangeFree() because wtxExchange() (called by exchange())
* does this for us when there is an error.
*/
if (callStat != WTX_ERR_NONE)
/*
* On error the WTX_ERROR_RETURN macro calls wtxErrDispatch() for
* us (which sets the error code in the API handle and calls any
* registered error handlers). It then returns the last param as
* the result. In the case where the out param was dynamically
* allocated (see wtxEventGet() for example) is the API call fails
* then we must call free() on the result before the error return.
*/
WTX_ERROR_RETURN (hWtx, callStat, WTX_ERROR);
/*
* Here we extract any information we want from the out param, then
* free it using wtxExchangeFree() so any exchange allocated memory is
* released and then return the desired result value.
*/
result = out.val.value_u.v_int32;
wtxExchangeFree (hWtx->server, WTX_AGENT_MODE_GET, &out);
return result;
}
/*******************************************************************************
*
* wtxAgentModeSet - set the mode of the target agent
*
* This routine sets the mode of the target agent that the current target
* server is attached to. A given agent may not support all the possible
* modes.
*
* EXPAND ../../../include/wtxtypes.h WTX_AGENT_MODE_TYPE
*
* RETURNS: WTX_OK or WTX_ERROR.
*
* SEE ALSO: WTX_AGENT_MODE_SET, wtxTsInfoGet(), wtxAgentModeGet()
*/
STATUS wtxAgentModeSet
(
HWTX hWtx, /* WTX API handle */
WTX_AGENT_MODE_TYPE agentMode /* debug agent mode */
)
{
WTX_ERROR_T callStat; /* client status */
WTX_MSG_PARAM in; /* WTX param */
WTX_MSG_RESULT out; /* WTX result */
/*
* All API calls that require a connection to the target server
* should use the WTX_CHECK_CONNECTED macro before doing anything else.
* This macro also calls WTX_CHECK_HANDLE to validate the handle.
*/
WTX_CHECK_CONNECTED (hWtx, WTX_ERROR);
/* Always remember to initialize the in and out params */
memset (&in, 0, sizeof (in));
memset (&out, 0, sizeof (out));
/* Fill in the relevant fields of the in params for the call */
in.param.valueType = V_UINT32;
in.param.value_u.v_uint32 = agentMode;
/* Now make the call recording the result status */
callStat = exchange (hWtx, WTX_AGENT_MODE_SET, &in, &out);
/*
* If there is an error we don't need to free the result with
* wtxExchangeFree() because wtxExchange() (called by exchange())
* does this for us when there is an error.
*/
if (callStat != WTX_ERR_NONE)
/*
* On error the WTX_ERROR_RETURN macro calls wtxErrDispatch() for
* us (which sets the error code in the API handle and calls any
* registered error handlers). It then returns the last param as
* the result. In the case where the out param was dynamically
* allocated (see wtxEventGet() for example) is the API call fails
* then we must call free() on the result before the error return.
*/
WTX_ERROR_RETURN (hWtx, callStat, WTX_ERROR);
/*
* Here we extract any information we want from the out param, then
* free it using wtxExchangeFree() so any exchange allocated memory is
* released and then return the desired result value.
*/
wtxExchangeFree (hWtx->server, WTX_AGENT_MODE_SET, &out);
return (WTX_OK);
}
/*******************************************************************************
*
* wtxAsyncNotifyEnable - start the asynchronous event notification
*
* This function creates a socket-based link between the target server and
* the client where events will be sent. If a user defined function
* is given (pFunc != NULL) then this function is called each time an
* event is received by the target server, this function must take
* a WTX_EVENT_DESC as input parameter. If no user defined function is
* given then received events are just stored in the asynchronous event
* list, those events can be get using wtxAsyncEventGet().
*
* In conjunction with wtxAsyncNotifyEnable(), wtxRegisterForEvent() (or
* wtxUnregisterForEvent()) must be used to specify which type of events must
* be sent to the requester.
*
* Upon calling this function, the wtxEventGet() and wtxEventListGet()
* routines will always return nothing.
*
* When an event is coming to the client, the event is put in an
* WTX_EVENT_DESC structure and passed to the user provided function
* pointed to by <pFunc>.
*
* All strings contained in the WTX_EVENT_DESC structure must be copied
* before to be used because their life duration is depending on the events
* stream.
*
* The user defined function must take a WTX_EVENT_DESC * as input
* parameter. It is called each time an event is received by the target
* server.
*
* NOTE:
* This service uses WTX_COMMAND_SEND request of the WTX protocol.
*
* EXAMPLE:
*
* Declaration of a simple event handler.
*
* .CS
* LOCAL void eventHookRtn /@ Hook routine used by the notification @/
* (
* WTX_EVENT_DESC * event /@ Event received from the target server @/
* )
* {
* /@ Just print the event string and exit @/
*
* if (event->event != NULL)
* printf ("Received event: %sn", event->event);
* }
* .CE
*
* Start of the asynchronous notification from the C API.
*
* .CS
* /@ Initialization @/
* .
* .
*
* /@ Start the notification @/
*
* if (wtxAsyncNotifyEnable (wtxh, (FUNCPTR) eventHookRtn)
* != (UINT32) WTX_OK)
* return (WTX_ERROR);
*
* /@ core of the WTX application @/
* .
* .
* .CE
*
* RETURN: WTX_OK or WTX_ERROR if the request failed.
*
* ERRORS:
* .iP WTX_ERR_API_SERVICE_ALREADY_STARTED 12
* An wtxAsyncNotifyDisable must be called before.
* .iP WTX_ERR_API_CANT_OPEN_SOCKET
* Socket creation, bind or listen failed.
* .iP WTX_ERR_API_CANT_GET_HOSTNAME
* Cannot get name of current host.
*
* SEE ALSO: WTX_COMMAND_SEND, wtxAsyncNotifyEnable(), wtxAsyncEventGet()
*/
STATUS wtxAsyncNotifyEnable
(
HWTX hWtx, /* WTX API handle */
FUNCPTR pFunc /* User defined function */
)
{
#ifdef HOST
WTX_MSG_PARAM in; /* Query parameters */
WTX_MSG_RESULT out; /* Query result */
WTX_ERROR_T callStat; /* Exchange result */
int status; /* Return value */
struct hostent * he; /* Host entries */
char buf [128]; /* Input param. string */
char bufPort [32]; /* String for port # */
char hostName [32]; /* Host name */
SOCK_DESC sockDesc; /* Socket descriptor */
/*
* All API calls that require a connection to the target server
* should use the WTX_CHECK_CONNECTED macro before doing anything else.
* This macro also calls WTX_CHECK_HANDLE to validate the handle.
*/
WTX_CHECK_CONNECTED (hWtx, WTX_ERROR);
/* Open a socket, create the event list and start the threads */
status = wtxAsyncInitialize (&sockDesc, pFunc, &hWtx->asyncHandle);
if (status != WTX_OK)
{
return (status);
}
/* Set input - ouput parameters for WTX_COMMAND_SEND */
in.param.valueType = V_PCHAR;
if (gethostname (hostName, sizeof (hostName)) != OK)
{
/* Tchao */
return (WTX_ERR_API_CANT_GET_HOSTNAME);
}
he = gethostbyname (hostName);
memset (buf, 0, sizeof (buf));
strcpy (buf, WTX_ASYNC_NOTIFY_ENABLE_CMD);
strcat (buf, SEPARATOR);
strcat (buf, (const char *) inet_ntoa (*((struct in_addr *)he->h_addr)));
strcat (buf, SEPARATOR);
sprintf (bufPort, "%d", sockDesc.portNumber);
strcat (buf, bufPort);
in.param.value_u.v_pchar = buf;
memset (&out, 0, sizeof (out));
/* Call WTX_COMMAND_SEND - wtxAsyncNotifyEnable service */
callStat = exchange (hWtx, WTX_COMMAND_SEND, &in, &out);
if (callStat != WTX_ERR_NONE)
{
/* Set off the asynchronous notification */
wtxAsyncStop (&hWtx->asyncHandle);
hWtx->asyncHandle = NULL;
/* Tchao */
WTX_ERROR_RETURN (hWtx, callStat, WTX_ERROR);
}
wtxExchangeFree (hWtx->server, WTX_COMMAND_SEND, &out);
#endif /* HOST */
return (WTX_OK);
}
/*******************************************************************************
*
* wtxAsyncNotifyDisable - stop the asynchronous event notification
*
* This function sends to the target server an order to stop the asynchronous
* notification of events.
*
* NOTE:
* This service uses WTX_COMMAND_SEND request of the WTX protocol.
*
* RETURN: WTX_OK or WTX_ERROR if exchange failed.
*
* SEE ALSO: WTX_COMMAND_SEND, wtxAsyncNotifyEnable(), wtxAsyncEventGet()
*/
STATUS wtxAsyncNotifyDisable
(
HWTX hWtx /* WTX API handle */
)
{
#ifdef HOST
WTX_ERROR_T callStat = WTX_OK; /* Exchange result */
WTX_MSG_PARAM in; /* Query parameters */
WTX_MSG_RESULT out; /* Query result */
char buf [32]; /* Input buffer */
/*
* All API calls that require a connection to the target server
* should use the WTX_CHECK_CONNECTED macro before doing anything else.
* This macro also calls WTX_CHECK_HANDLE to validate the handle.
*/
WTX_CHECK_CONNECTED (hWtx, WTX_ERROR);
/* Set input - ouput parameters for WTX_COMMAND_SEND */
in.param.valueType = V_PCHAR;
strcpy (buf, WTX_ASYNC_NOTIFY_DISABLE_CMD);
in.param.value_u.v_pchar = buf;
memset (&out, 0, sizeof (out));
/* Call WTX_COMMAND_SEND - wtxAsyncNotifyDisable service */
callStat = exchange (hWtx, WTX_COMMAND_SEND, &in, &out);
if (callStat == WTX_ERR_NONE)
wtxExchangeFree (hWtx->server, WTX_COMMAND_SEND, &out);
/* Free the event list and stop the async. notif. mechanism */
wtxAsyncStop (&hWtx->asyncHandle);
hWtx->asyncHandle = NULL;
/* Tchao */
#endif
return (WTX_OK);
}
/*******************************************************************************
*
* wtxBreakpointAdd - create a new WTX eventpoint of type breakpoint
*
* This routine creates a new eventpoint on the target to represent a
* breakpoint at the address <tgtAddr> for the target context <contextId>.
* The target server maintains a list of eventpoints created on the target
* and this can be queried using wtxEventpointList(). When a context is
* destroyed on the target or the target is reset, eventpoints are deleted
* automatically without intervention from the creator.
*
* The context types are given by:
*
* EXPAND ../../../include/wtxtypes.h WTX_CONTEXT_TYPE
*
* When <contextType> is set to WTX_CONTEXT_SYSTEM, then only breakpoints
* in system mode can be added. When <contextType> is set to WTX_CONTEXT_TASK,
* then only breakpoints in context task can be added.
*
* RETURNS: The ID of the new breakpoint or WTX_ERROR if the add fails.
*
* SEE ALSO: WTX_EVENTPOINT_ADD, wtxEventpointAdd(), wtxEventpointDelete(),
* wtxEventpointList()
*/
UINT32 wtxBreakpointAdd
(
HWTX hWtx, /* WTX API handle */
WTX_CONTEXT_TYPE contextType, /* type of context to put bp in */
WTX_CONTEXT_ID_T contextId, /* associated context */
TGT_ADDR_T tgtAddr /* breakpoint address */
)
{
WTX_MSG_RESULT out;
WTX_MSG_EVTPT_DESC in;
WTX_ERROR_T callStat;
UINT32 bpId;
WTX_CHECK_CONNECTED (hWtx, WTX_ERROR);
memset (&out, 0, sizeof (out));
memset (&in, 0, sizeof (in));
in.wtxEvtpt.event.eventType = WTX_EVENT_TEXT_ACCESS;
in.wtxEvtpt.event.eventArg = (TGT_ARG_T) tgtAddr;
in.wtxEvtpt.context.contextType = contextType;
in.wtxEvtpt.context.contextId = contextId;
/* ??? Not used by target agent */
in.wtxEvtpt.action.actionType = WTX_ACTION_STOP | WTX_ACTION_NOTIFY;
in.wtxEvtpt.action.actionArg = 0; /* ??? Not used by target agent */
in.wtxEvtpt.action.callRtn = 0; /* ??? Not used by target agent */
in.wtxEvtpt.action.callArg = 0; /* ??? Not used by target agent */
callStat = exchange (hWtx, WTX_EVENTPOINT_ADD, &in, &out);
if (callStat != WTX_ERR_NONE)
WTX_ERROR_RETURN (hWtx, callStat, WTX_ERROR);
bpId = out.val.value_u.v_uint32;
wtxExchangeFree (hWtx->server, WTX_EVENTPOINT_ADD, &out);
return bpId;
}
/*******************************************************************************
*
* wtxCacheTextUpdate - synchronize the instruction and data caches.
*
* This function flushes the data chache, then invalidates the instruction cache.
* This operation forces the instruction cache to fetch code that may have been
* created via the data path.
*
* ERRORS:
* .iP WTX_ERR_API_INVALID_ARG 12
* <nBytes> is invalid.
*
* RETURNS: WTX_OK or WTX_ERROR if exchange failed.
*
* SEE ALSO: WTX_CACHE_TEXT_UPDATE, wtxMemRead(), wtxMemWrite()
*/
STATUS wtxCacheTextUpdate
(
HWTX hWtx, /* WTX API handle */
TGT_ADDR_T addr, /* remote addr to update */
UINT32 nBytes /* number of bytes to update */
)
{
WTX_ERROR_T callStat;
WTX_MSG_MEM_BLOCK_DESC in;
WTX_MSG_RESULT out;
WTX_CHECK_CONNECTED (hWtx, WTX_ERROR);
if (nBytes == 0)
WTX_ERROR_RETURN (hWtx, WTX_ERR_API_INVALID_ARG, WTX_ERROR);
memset (&in, 0, sizeof (in));
memset (&out, 0, sizeof (out));
in.startAddr = addr;
in.numBytes = nBytes;
callStat = exchange (hWtx, WTX_CACHE_TEXT_UPDATE, &in, &out);
if (callStat != WTX_ERR_NONE)
WTX_ERROR_RETURN (hWtx, callStat, WTX_ERROR);
wtxExchangeFree (hWtx->server, WTX_CACHE_TEXT_UPDATE, &out);
return (WTX_OK);
}
/******************************************************************************
*
* wtxCommandSend - Pass a string to be interpreted by the target server
*
* This function is used to control the target server behavior.
* Services availables are: wtxTsKill(), wtxTsRestart(), wtxLogging (),
* wtxTsLock(), wtxTsUnlock(), wtxTargetReset(), wtxAsyncNotifyEnable(),
* wtxAsyncNotifyDisable().
*
* This service sends a string to the target server which interprets it.
* If the requested service is not known by tsWtxCommandSend(), then
* the string is sent back to the client.
*
* EXAMPLE
* The following is a sample of string
*
* .CS
* commandString = "wtxTsLock_30"; /@ lock the target server for 30s @/
* commandString = "wtxTsUnlock"; /@ Unlock the target server @/
* commandString = "wtxLoggingOn_/folk/pascal/wtx.txt"; /@ wtx log started @/
* .CE
*
* NOTE:
* A separator is used ("_") and only some command strings can be
* recognized by the target server (plus options if needed):
* .iP "wdbLoggingOn"
* Open the file and log all WDB requests.
* .iP "wdbLoggingOff"
* Close the file and stop the log.
* .iP "wtxLoggingOn"
* Open the file and log all WTX requests.
* .iP "wtxLoggingOff"
* Close the file and stop the log.
* .iP "allLoggingOff"
* Stop WDB and WTX log.
* .iP "wtxAsyncNotifyEnable"
* Start the asynchronous notification of events.
* .iP "wtxAsyncNotifyDisable"
* Stop the asynchronous notification of events.
* .iP "wtxObjKillDestroy"
* Kill the target server.
* .iP "wtxObjKillRestart"
* Restart the target server.
* .iP "wtxTsLock"
* Lock the target server.
* .iP "wtxTsUnlock"
* Unlock the target server.
* .iP "wtxTargetReset"
* Reset the target.
* .iP "wtxTargetIpAddressGet"
* Get the target's IP address (if applicable) in a.b.c.d form.
* .iP "wtxTargetToolNameGet"
* Get the name of the tool used to build target run-time (e.g. "gnu").
*
* RETURNS: string containing the command's result.
*
* SEE ALSO: wtxTsKill(), wtxTsRestart(), wtxLogging(), wtxTsLock(),
* wtxTsUnlock(), wtxTargetReset(), wtxAsyncNotifyEnable(),
* wtxAsyncNotifyDisable(), wtxTargetToolNameGet(), wtxTargetIpAddressGet().
*/
char * wtxCommandSend
(
HWTX hWtx, /* WTX API handle */
char * commandString /* String to be interpreted */
)
{
WTX_MSG_RESULT out;
WTX_MSG_PARAM in;
WTX_ERROR_T callStat;
WTX_CHECK_CONNECTED (hWtx, NULL);
memset (&out, 0, sizeof (out));
memset (&in, 0, sizeof (in));
in.param.valueType = V_PCHAR;
in.param.value_u.v_pchar = commandString;
callStat = exchange (hWtx, WTX_COMMAND_SEND, &in, &out);
if (callStat != WTX_ERR_NONE)
WTX_ERROR_RETURN (hWtx, callStat, NULL);
wtxExchangeFree (hWtx->server, WTX_COMMAND_SEND, &out);
return (out.val.value_u.v_pchar);
}
/*******************************************************************************
*
* wtxTargetIpAddressGet - gets target IP address.
*
* This routine returns the target's IP address in network byte order. The
* returned address is the one used by the target server to connect the target.
*
* On error (the target have no IP address), this value will be (UINT32) 0.
*
* RETURNS: the target's IP address in network byte order or 0 on error.
*/
UINT32 wtxTargetIpAddressGet
(
HWTX hWtx /* WTX API handle */
)
{
WTX_MSG_RESULT out; /* output structure desc */
WTX_MSG_PARAM in; /* input structure desc */
WTX_ERROR_T callStat; /* WTX exchange result status */
UINT32 targetIP = 0; /* returned target IP address */
WTX_CHECK_CONNECTED (hWtx, 0);
memset (&out, 0, sizeof (out));
memset (&in, 0, sizeof (in));
in.param.valueType = V_PCHAR;
in.param.value_u.v_pchar = WTX_TARGET_IP_ADDRESS_CMD;
callStat = exchange (hWtx, WTX_COMMAND_SEND, &in, &out);
if (callStat != WTX_ERR_NONE)
WTX_ERROR_RETURN (hWtx, callStat, 0);
targetIP = inet_addr (out.val.value_u.v_pchar);
/* free the RPC buffers */
wtxExchangeFree (hWtx->server, WTX_COMMAND_SEND, &out);
return (targetIP);
}
/*******************************************************************************
*
* wtxTargetToolNameGet - get target tool name.
*
* This routine returns the name of the tool used to build the target run-time.
*
* On error (the target have no tool name), this value will be "Unknown".
*
* RETURNS: a string representing a tool name (like "gnu") or NULL
*
* SEE ALSO: wtxTsInfoGet
*/
char * wtxTargetToolNameGet
(
HWTX hWtx /* WTX API handle */
)
{
#ifdef HOST
WTX_MSG_RESULT out; /* output structure desc */
WTX_MSG_PARAM in; /* input structure desc */
WTX_ERROR_T callStat; /* WTX exchange result status */
WTX_CHECK_CONNECTED (hWtx, 0);
/* return cached name */
if (hWtx->targetToolName != NULL)
return hWtx->targetToolName;
memset (&out, 0, sizeof (out));
memset (&in, 0, sizeof (in));
in.param.valueType = V_PCHAR;
in.param.value_u.v_pchar = WTX_TARGET_TOOLNAME_GET_CMD;
callStat = exchange (hWtx, WTX_COMMAND_SEND, &in, &out);
if (callStat != WTX_ERR_NONE)
WTX_ERROR_RETURN (hWtx, callStat, 0);
hWtx->targetToolName = strdup (out.val.value_u.v_pchar);
/* free the RPC buffers */
wtxExchangeFree (hWtx->server, WTX_COMMAND_SEND, &out);
#endif /* HOST*/
return (hWtx->targetToolName);
}
/*******************************************************************************
*
* wtxCpuInfoGet - gets cpu related information from architecturedb file
*
* This function allows to get target CPU related informations. <cpuNum>
* specifies the CPU number in data base, while <cpuInfoType> specifies which
* parameter to get.
*
* <cpuInfoType> can be from the following type
*
* EXPAND ../../../include/wtx.h CPU_INFO
*
* NOTE:
* returned value if not NULL should be freed by caller through a call to free()
*
* RETURNS: a string containing parameter in string format or NULL.
*
* SEE ALSO: wtxTsInfoGet()
*/
char * wtxCpuInfoGet
(
int cpuNum, /* cpu number to get info on */
CPU_INFO cpuInfoType /* cpu info type to get */
)
{
char * cpuInfo = NULL; /* returned target cpu information */
#ifdef HOST
char * windBase = NULL; /* win base directory name */
char * cpuFamilyName = NULL; /* family name of CPU num <cpuNum> */
char section [100]; /* section number e.g. CPU ID */
char paramBuf [100]; /* receiving parameter buffer */
char configFile [PATH_MAX]; /* configuration file name */
int ix = 0; /* loop counter */
int nChar = 0; /* # of chars in returned value */
CPU_INFO_TYPE targetCpuInfo[] = /* cpu data initialization */
{
/* param, string, section */
{CPU_INFO_NONE, "none", NULL},
{ARCH_DIR, "Architecture Directory", NULL},
{LEADING_CHAR, "Leading Character", NULL},
{DEMANGLER, "demangler", NULL},
{CPU_NAME, "cpuname", NULL},
{ARCH_OBJ_DIR, "Architecture Object Directory", NULL}
};
sprintf (section, "CPU_%d", cpuNum);
/* setting architecture data base file name */
windBase = wpwrGetEnv ("WIND_BASE");
if (windBase == NULL)
{
goto error1;
}
strcpy (configFile, windBase);
strcat (configFile, "/host/resource/target/architecturedb");
#ifdef WIN32
wpwrBackslashToSlash (configFile);
#endif /* WIN32 */
/* get CPU family name */
nChar = GetPrivateProfileString (section, "cpuFamilyName", "unknown",
paramBuf, sizeof (paramBuf), configFile);
if ( (! strcmp (paramBuf, "unknown")) ||
( (cpuFamilyName = strdup (paramBuf)) == NULL))
{
goto error1;
}
/* section assignement for parameters */
targetCpuInfo[1].section = cpuFamilyName;
targetCpuInfo[2].section = cpuFamilyName;
targetCpuInfo[3].section = "misc";
targetCpuInfo[4].section = (char *) section;
targetCpuInfo[5].section = cpuFamilyName;
/* set searched string */
for (ix = 1 ; ix < (int) NELEMENTS (targetCpuInfo) ; ix++)
{
if (targetCpuInfo[ix].param == cpuInfoType)
{
if ( (targetCpuInfo[ix].section != NULL) &&
(targetCpuInfo[ix].string != NULL))
{
nChar = GetPrivateProfileString (targetCpuInfo[ix].section,
targetCpuInfo[ix].string,
"unknown", paramBuf,
sizeof (paramBuf), configFile);
}
else
{
goto error2;
}
break;
}
}
/* allocate and verify returned value */
if ( (! strcmp (paramBuf, "unknown")) ||
( (cpuInfo = strdup (paramBuf)) == NULL))
{
goto error2;
}
error2:
free (cpuFamilyName);
error1:
#endif /* HOST */
return cpuInfo;
}
/*******************************************************************************
*
* wtxEventpointAdd - create a new WTX eventpoint
*
* This routine creates a new eventpoint on the target. This routine is a
* generic facility for setting breakpoints. An eventpoint specifies the
* context to which it applies, the type of event to detect (for example
* breakpoint, context exit), and the action to be taken upon detection of
* the event (for example, notify the target server of the event).
*
* The target server maintains a list of eventpoints created on the target
* and this can be queried using wtxEventpointList(). When a context is
* destroyed on the target or the target is reset, eventpoints are deleted
* automatically without intervention from the creator.
*
* When <pEvtpt->context.contextType> is set to WTX_CONTEXT_SYSTEM, then
* only eventpoints in system mode can be added.
* When <pEvtpt->context.contextType> is set to WTX_CONTEXT_TASK, then only
* eventpoints in context task can be added.
*
* The eventpoint parameters are grouped into the structure:
*
* EXPAND ../../../include/wtxmsg.h WTX_EVTPT_2
*
* where WTX_EVENT_2 is:
*
* EXPAND ../../../include/wtxmsg.h WTX_EVENT_2
*
* where WTX_CONTEXT is:
*
* EXPAND ../../../include/wtxmsg.h WTX_CONTEXT
*
* The context types are given by:
*
* EXPAND ../../../include/wtxtypes.h WTX_CONTEXT_TYPE
*
* If contextType is set to WTX_CONTEXT_TASK and contextId set to 0,
* then it is equivalent to contextType set to WTX_CONTEXT_ANY_TASK.
*
* where WTX_ACTION is:
*
* EXPAND ../../../include/wtxmsg.h WTX_ACTION
*
* The action types are given by WTX_ACTION_TYPE and can be or'ed
* together if multiple actions are needed:
*
* EXPAND ../../../include/wtxtypes.h WTX_ACTION_TYPE
*
* RETURNS: The ID of the new eventpoint or WTX_ERROR if the add fails.
*
* SEE ALSO: WTX_EVENTPOINT_ADD_2, wtxEventpointDelete(), wtxEventpointList()
*/
UINT32 wtxEventpointAdd
(
HWTX hWtx, /* WTX API handle */
WTX_EVTPT_2 * pEvtpt /* eventpoint descriptor */
)
{
WTX_MSG_RESULT out;
WTX_MSG_EVTPT_DESC_2 in;
WTX_ERROR_T callStat;
UINT32 evtptId;
WTX_CHECK_CONNECTED (hWtx, WTX_ERROR);
memset (&out, 0, sizeof (out));
memset (&in, 0, sizeof (in));
/*
* XXX - must have WTX_EVTPT_2 fields identical to those
* WTX_MSG_EVTPT_DESC_2 from wtxEvtpt onwards. Awaits change to
* message definitions on wtxmsg.h so this hack will go away.
*/
memcpy (&in.wtxEvtpt, pEvtpt, sizeof (WTX_EVTPT_2));
callStat = exchange (hWtx, WTX_EVENTPOINT_ADD_2, &in, &out);
if (callStat != WTX_ERR_NONE)
WTX_ERROR_RETURN (hWtx, callStat, WTX_ERROR);
evtptId = out.val.value_u.v_uint32;
wtxExchangeFree (hWtx->server, WTX_EVENTPOINT_ADD_2, &out);
return evtptId;
}
/*******************************************************************************
*
* wtxEventpointDelete - delete an eventpoint from the target
*
* This routine deletes an existing eventpoint in the context given when it
* was created. The eventpoint is identified by <evtptId> which is the
* ID returned by wtxBreakpointAdd(), wtxContextExitNotifyAdd()... If the
* eventpoint has already been deleted on the target (for example, because
* the context associated with it no longer exists), then the first call of
* wtxEventpointDelete() returns WTX_OK. (The target server ignores the
* deletion of a valid eventpoint ID that no longer exists on the target.)
* If the target server eventpoint list does not contain the <evtptId>, then
* the error WTX_ERR_SVR_INVALID_EVENTPOINT occurs.
*
* RETURNS: WTX_OK or WTX_ERROR if the delete fails.
*
* SEE ALSO: WTX_EVENTPOINT_DELETE, wtxBreakpointAdd(),
* wtxContextExitNotifyAdd(), wtxEventpointAdd(), wtxHwBreakpointAdd(),
* wtxEventpointList()
*/
STATUS wtxEventpointDelete
(
HWTX hWtx, /* WTX API handle */
UINT32 evtptId /* ID of eventpoint to delete */
)
{
WTX_MSG_RESULT out;
WTX_MSG_PARAM in;
WTX_ERROR_T callStat;
WTX_CHECK_CONNECTED (hWtx, WTX_ERROR);
memset (&in, 0, sizeof (in));
memset (&out, 0, sizeof (out));
in.param.valueType = V_UINT32;
in.param.value_u.v_uint32 = evtptId;
callStat = exchange (hWtx, WTX_EVENTPOINT_DELETE, &in, &out);
if (callStat != WTX_ERR_NONE)
WTX_ERROR_RETURN (hWtx, callStat, WTX_ERROR);
wtxExchangeFree (hWtx->server, WTX_EVENTPOINT_DELETE, &out);
return (WTX_OK);
}
/*******************************************************************************
*
* wtxConsoleCreate - create a console window (UNIX only)
*
* This routine creates a new console window. The name passed in <name>
* is used as the title for the new window. If <name> is NULL, a unique
* name is assigned by the target server. When the target server is
* running in an X-Window environment, the <display> parameter
* identifies the X display device to create the window on. The number of
* buffered lines (default 88) can be changed by setting the environment variable
* `WTX_CONSOLE_LINES' to the number of desired buffered lines. Set this
* variable before launching the target server. The <fdIn>
* and <fdOut> parameters are pointers to INT32 variables in
* which are stored the target server file descriptors for the
* input and output of the new console. wtxVioCtl() can be used
* to redirect VIO input and output to the console.
*
* UNIX HOSTS
* On UNIX systems the returned ID is actually a process
* ID of the new console running on the same host as the target server.
*
* WINDOWS HOSTS
* This request is not implemented on Windows. Windows allows only one virtual
* console and it must be started on the target server command line with the
* `-c' option.
*
* RETURNS: The ID number of the new console or WTX_ERROR.
*
* ERRORS:
* .iP WTX_ERR_API_INVALID_ARG 12
* Either <fdIn> or <fdOut> is NULL.
*
* SEE ALSO: WTX_CONSOLE_CREATE, wtxConsoleKill(), wtxVioCtl()
*/
INT32 wtxConsoleCreate
(
HWTX hWtx, /* WTX API handle */
const char *name, /* Name of console window */
const char *display, /* Display name eg: host:0 */
INT32 *fdIn, /* RETURN: input file descriptor */
INT32 *fdOut /* RETURN: output file descriptor */
)
{
WTX_MSG_CONSOLE_DESC out;
WTX_MSG_CONSOLE_DESC in;
WTX_ERROR_T callStat;
INT32 pid;
WTX_CHECK_CONNECTED (hWtx, WTX_ERROR);
if (fdIn == 0 || fdOut == 0)
WTX_ERROR_RETURN (hWtx, WTX_ERR_API_INVALID_ARG, WTX_ERROR);
memset (&in, 0, sizeof (in));
memset (&out, 0, sizeof (out));
in.wtxConsDesc.name = (char *) name;
in.wtxConsDesc.display = (char *) display;
callStat = exchange (hWtx, WTX_CONSOLE_CREATE, &in, &out);
if (callStat != WTX_ERR_NONE)
WTX_ERROR_RETURN (hWtx, callStat, WTX_ERROR);
*fdIn = out.wtxConsDesc.fdIn;
*fdOut = out.wtxConsDesc.fdOut;
pid = out.wtxConsDesc.pid;
wtxExchangeFree (hWtx->server, WTX_CONSOLE_CREATE, &out);
return pid;
}
/*******************************************************************************
*
* wtxConsoleKill - destroy a console (UNIX only)
*
* This routine destroys a console identified by <consoleId> and created by
* a previous call to wtxConsoleCreate().
* WINDOWS HOSTS
* This request is not implemented on Windows. If issued, it returns an
* error, but does not attempt to kill an existing console.
*
* RETURNS: WTX_OK or WTX_ERROR.
*
* SEE ALSO: WTX_CONSOLE_KILL, wtxConsoleCreate()
*/
STATUS wtxConsoleKill
(
HWTX hWtx, /* WTX API handle */
INT32 consoleId /* id of console to destroy */
)
{
WTX_MSG_RESULT out;
WTX_MSG_PARAM in;
WTX_ERROR_T callStat;
WTX_CHECK_CONNECTED (hWtx, WTX_ERROR);
memset (&in, 0, sizeof (in));
memset (&out, 0, sizeof (out));
in.param.valueType = V_INT32;
in.param.value_u.v_int32 = consoleId;
callStat = exchange (hWtx, WTX_CONSOLE_KILL, &in, &out);
if (callStat != WTX_ERR_NONE)
WTX_ERROR_RETURN (hWtx, callStat, WTX_ERROR);
wtxExchangeFree (hWtx->server, WTX_CONSOLE_KILL, &out);
return (WTX_OK);
}
/*******************************************************************************
*
* wtxContextCont - continue execution of a target context
*
* This routine synchronously continues execution of the context <contextId>
* on the target after it has stopped at a breakpoint. This routine should
* be used instead of wtxContextResume() when debugging a task to prevent
* the task hitting the breakpoint a second time.
*
* The context types are given by:
*
* EXPAND ../../../include/wtxtypes.h WTX_CONTEXT_TYPE
*
* RETURNS: WTX_OK or WTX_ERROR on failure.
*
* SEE ALSO: WTX_CONTEXT_CONT, wtxContextResume(), wtxBreakpointAdd()
*/
STATUS wtxContextCont
(
HWTX hWtx, /* WTX API handle */
WTX_CONTEXT_TYPE contextType, /* type of context to continue */
WTX_CONTEXT_ID_T contextId /* id of context to continue */
)
{
WTX_MSG_RESULT out;
WTX_MSG_CONTEXT in;
WTX_ERROR_T callStat;
WTX_CHECK_CONNECTED (hWtx, WTX_ERROR);
memset (&out, 0, sizeof (out));
memset (&in, 0, sizeof (in));
in.contextType = contextType;
in.contextId = contextId;
callStat = exchange (hWtx, WTX_CONTEXT_CONT, &in, &out);
if (callStat != WTX_ERR_NONE)
WTX_ERROR_RETURN (hWtx, callStat, WTX_ERROR);
wtxExchangeFree (hWtx->server, WTX_CONTEXT_CONT, &out);
return (WTX_OK);
}
/*******************************************************************************
*
* wtxContextCreate - create a new context on the target
*
* This routine creates a new context using the information in the
* context descriptor pointed to by <pContextDesc> which describes
* parameters for a new task context or a system context. The caller is
* responsible for freeing information supplied in the context
* descriptor after the call.
*
* EXPAND ../../../include/wtx.h WTX_CONTEXT_DESC
*
* ERRORS:
* .iP WTX_ERR_API_INVALID_ARG 12
* <pContextDesc> is invalid
*
* RETURNS: The ID of the new context or WTX_ERROR.
*
* SEE ALSO: WTX_CONTEXT_CREATE, wtxContextKill()
*/
WTX_CONTEXT_ID_T wtxContextCreate
(
HWTX hWtx, /* WTX API handle */
WTX_CONTEXT_DESC * pContextDesc /* context descriptor */
)
{
WTX_MSG_CONTEXT_DESC in;
WTX_MSG_CONTEXT out;
WTX_ERROR_T callStat;
WTX_CONTEXT_ID_T ctxId;
WTX_CHECK_CONNECTED (hWtx, WTX_ERROR);
if (pContextDesc == NULL)
WTX_ERROR_RETURN (hWtx, WTX_ERR_API_INVALID_ARG, WTX_ERROR);
memset (&in, 0, sizeof (in));
memset (&out, 0, sizeof (out));
/* Fill in the context create descritor message. */
/*
* XXX - must have WTX_CONTEXT_DESC fields identical to those
* WTX_MSG_CONTEXT_DESC from contextType onwards. Awaits change to
* message definitions on wtxmsg.h so this hack will go away.
*/
memcpy (&in.contextType, pContextDesc, sizeof (WTX_CONTEXT_DESC));
callStat = exchange (hWtx, WTX_CONTEXT_CREATE, &in, &out);
if (callStat != WTX_ERR_NONE)
WTX_ERROR_RETURN (hWtx, callStat, WTX_ERROR);
ctxId = out.contextId;
wtxExchangeFree (hWtx->server, WTX_CONTEXT_CREATE, &out);
return ctxId;
}
/*******************************************************************************
*
* wtxContextResume - resume execution of a target context
*
* This routine synchronously resumes execution of the context <contextId>
* on the target after it has been suspended, perhaps by wtxContextSuspend().
* Use wtxContextCont() rather than this routine to continue a task from a
* breakpoint; this routine causes the task to hit the breakpoint again.
*
* The context types are given by:
*
* EXPAND ../../../include/wtxtypes.h WTX_CONTEXT_TYPE
*
* RETURNS: WTX_OK or WTX_ERROR on failure.
*
* SEE ALSO: WTX_CONTEXT_RESUME, wtxContextSuspend()
*/
STATUS wtxContextResume
(
HWTX hWtx, /* WTX API handle */
WTX_CONTEXT_TYPE contextType, /* type of context to resume */
WTX_CONTEXT_ID_T contextId /* id of context to resume */
)
{
WTX_MSG_RESULT out;
WTX_MSG_CONTEXT in;
WTX_ERROR_T callStat;
WTX_CHECK_CONNECTED (hWtx, WTX_ERROR);
memset (&out, 0, sizeof (out));
memset (&in, 0, sizeof (in));
in.contextType = contextType;
in.contextId = contextId;
callStat = exchange (hWtx, WTX_CONTEXT_RESUME, &in, &out);
if (callStat != WTX_ERR_NONE)
WTX_ERROR_RETURN (hWtx, callStat, WTX_ERROR);
wtxExchangeFree (hWtx->server, WTX_CONTEXT_RESUME, &out);
return (WTX_OK);
}
/*******************************************************************************
*
* wtxContextStatusGet - get the status of a context on the target
*
* This routine returns the status of the context <contextId> on the target.
*
* EXPAND ../../../include/wtxtypes.h WTX_CONTEXT_STATUS
*
* The context types are given by:
*
* EXPAND ../../../include/wtxtypes.h WTX_CONTEXT_TYPE
*
* RETURNS: The status of the context or WTX_ERROR.
*
* SEE ALSO: WTX_CONTEXT_STATUS_GET, wtxContextSuspend(), wtxContextResume()
*/
WTX_CONTEXT_STATUS wtxContextStatusGet
(
HWTX hWtx, /* WTX API handle */
WTX_CONTEXT_TYPE contextType, /* type of context */
WTX_CONTEXT_ID_T contextId /* id of context */
)
{
WTX_MSG_RESULT out;
WTX_CONTEXT_STATUS result; /* context status */
WTX_MSG_CONTEXT in;
WTX_ERROR_T callStat;
WTX_CHECK_CONNECTED (hWtx, WTX_ERROR);
memset (&out, 0, sizeof (out));
memset (&in, 0, sizeof (in));
in.contextType = contextType;
in.contextId = contextId;
callStat = exchange (hWtx, WTX_CONTEXT_STATUS_GET, &in, &out);
if (callStat != WTX_ERR_NONE)
WTX_ERROR_RETURN (hWtx, callStat, WTX_ERROR);
result = out.val.value_u.v_int32;
wtxExchangeFree (hWtx->server, WTX_CONTEXT_STATUS_GET, &out);
return (result);
}
/*******************************************************************************
*
* wtxContextExitNotifyAdd - add a context exit notification eventpoint
*
* This routine creates a new eventpoint that notifies the user when the
* specified context exits by sending a WTX_EVT_CTX_EXIT event. The eventpoint
* is removed automatically when the context exits or the routine
* wtxEventpointDelete() can be used to remove the eventpoint before the
* context exits.
*
* When <contextType> is set to WTX_CONTEXT_SYSTEM, then only eventpoints
* in system mode can be added.
* When <contextType> is set to WTX_CONTEXT_TASK, then only eventpoints in
* context task can be added.
*
* The context types are given by:
*
* EXPAND ../../../include/wtxtypes.h WTX_CONTEXT_TYPE
*
* RETURNS: A unique identifier for the new eventpoint or WTX_ERROR.
*
* SEE ALSO: WTX_EVENTPOINT_ADD, wtxEventpointAdd(), wtxEventpointList(),
* wtxEventpointDelete()
*/
UINT32 wtxContextExitNotifyAdd
(
HWTX hWtx, /* WTX API handle */
WTX_CONTEXT_TYPE contextType, /* type of context */
WTX_CONTEXT_ID_T contextId /* associated context */
)
{
WTX_MSG_RESULT out;
WTX_MSG_EVTPT_DESC in;
WTX_ERROR_T callStat;
UINT32 result;
WTX_CHECK_CONNECTED (hWtx, WTX_ERROR);
memset (&out, 0, sizeof (out));
memset (&in, 0, sizeof (in));
in.wtxEvtpt.event.eventType = WTX_EVENT_CTX_EXIT;
in.wtxEvtpt.context.contextType = contextType;
in.wtxEvtpt.context.contextId = contextId;
in.wtxEvtpt.action.actionType = WTX_ACTION_NOTIFY;
callStat = exchange (hWtx, WTX_EVENTPOINT_ADD, &in, &out);
if (callStat != WTX_ERR_NONE)
WTX_ERROR_RETURN (hWtx, callStat, WTX_ERROR);
result = out.val.value_u.v_uint32;
wtxExchangeFree (hWtx->server, WTX_EVENTPOINT_ADD, &out);
return result;
}
/*******************************************************************************
*
* wtxContextKill - kill a target context
*
* This routine synchronously kills the context specified by
* <contextId> on the target.
*
* The context types are given by:
*
* EXPAND ../../../include/wtxtypes.h WTX_CONTEXT_TYPE
*
* NOTE: Killing the the system context may result in a reboot of the
* target. However, the correct way to reboot the target system is by calling
* wtxTargetReset().
*
* RETURNS: WTX_OK or WTX_ERROR if the context kill fails.
*
* SEE ALSO: WTX_CONTEXT_KILL, wtxTargetReset()
*/
STATUS wtxContextKill
(
HWTX hWtx, /* WTX API handle */
WTX_CONTEXT_TYPE contextType, /* type of context to kill */
WTX_CONTEXT_ID_T contextId /* id of context to kill */
)
{
WTX_MSG_RESULT out;
WTX_MSG_CONTEXT in;
WTX_ERROR_T callStat;
WTX_CHECK_CONNECTED (hWtx, WTX_ERROR);
memset (&out, 0, sizeof (out));
memset (&in, 0, sizeof (in));
in.contextType = contextType;
in.contextId = contextId;
callStat = exchange (hWtx, WTX_CONTEXT_KILL, &in, &out);
if (callStat != WTX_ERR_NONE)
WTX_ERROR_RETURN (hWtx, callStat, WTX_ERROR);
wtxExchangeFree (hWtx->server, WTX_CONTEXT_KILL, &out);
return (WTX_OK);
}
/*******************************************************************************
*
* wtxContextStep - single step execution of a target context
*
* This routine asynchronously single steps execution of a context on
* the target. Stepping occurs while <stepStart> <= PC < <stepEnd>. If
* stepStart == stepEnd == 0 then the context is single stepped one
* machine instruction only. Note that <stepStart> does not set the
* initial program counter; this must be done separately.
*
* The context types are given by:
*
* EXPAND ../../../include/wtxtypes.h WTX_CONTEXT_TYPE
*
* NOTE: Stepping is an asynchronous operation so the return of this
* function does not signify completion of the stepping. After stepping
* completes, a breakpoint event is generated at the address which
* terminated the stepping operation.
*
* RETURNS: WTX_OK or WTX_ERROR if the step fails.
*
* SEE ALSO: WTX_CONTEXT_STEP, wtxContextCont(), wtxContextSuspend()
*/
STATUS wtxContextStep
(
HWTX hWtx, /* WTX API handle */
WTX_CONTEXT_TYPE contextType, /* type of context to resume */
WTX_CONTEXT_ID_T contextId, /* id of context to step */
TGT_ADDR_T stepStart, /* stepStart pc value */
TGT_ADDR_T stepEnd /* stepEnd PC vale */
)
{
WTX_MSG_RESULT out;
WTX_MSG_CONTEXT_STEP_DESC in;
WTX_ERROR_T callStat;
WTX_CHECK_CONNECTED (hWtx, WTX_ERROR);
memset (&out, 0, sizeof (out));
memset (&in, 0, sizeof (in));
in.context.contextType = contextType;
in.context.contextId = contextId;
in.startAddr = stepStart;
in.endAddr = stepEnd;
callStat = exchange (hWtx, WTX_CONTEXT_STEP, &in, &out);
if (callStat != WTX_ERR_NONE)
WTX_ERROR_RETURN (hWtx, callStat, WTX_ERROR);
wtxExchangeFree (hWtx->server, WTX_CONTEXT_STEP, &out);
return (WTX_OK);
}
/*******************************************************************************
*
* wtxContextSuspend - suspend a target context
*
* This routine synchronously suspends execution of a context on the
* target.
*
* The context types are given by:
*
* EXPAND ../../../include/wtxtypes.h WTX_CONTEXT_TYPE
*
* RETURNS: WTX_OK or WTX_ERROR if the suspend fails.
*
* SEE ALSO: WTX_CONTEXT_SUSPEND
*/
STATUS wtxContextSuspend
(
HWTX hWtx, /* WTX API handle */
WTX_CONTEXT_TYPE contextType, /* type of context to suspend */
WTX_CONTEXT_ID_T contextId /* id of context being suspended */
)
{
WTX_MSG_RESULT out;
WTX_MSG_CONTEXT in;
WTX_ERROR_T callStat;
WTX_CHECK_CONNECTED (hWtx, WTX_ERROR);
memset (&out, 0, sizeof (out));
memset (&in, 0, sizeof (in));
in.contextType = contextType;
in.contextId = contextId;
callStat = exchange (hWtx, WTX_CONTEXT_SUSPEND, &in, &out);
if (callStat != WTX_ERR_NONE)
WTX_ERROR_RETURN (hWtx, callStat, WTX_ERROR);
wtxExchangeFree (hWtx->server, WTX_CONTEXT_SUSPEND, &out);
return (WTX_OK);
}
/*******************************************************************************
*
* wtxEventAdd - send an event to the target server
*
* This routine sends an event to the target server. The target server adds
* it to the event list of any attached tool that has selected that event
* by using wtxRegisterForEvent() with a suitable event pattern. The
* event is not sent back to the tool that generated it.
*
* EXPAND ../../../include/wtxmsg.h WTX_MSG_EVENT_DESC
*
* EXPAND ../../../include/wtxmsg.h WTX_EVENT_DESC
*
* RETURNS: WTX_OK or WTX_ERROR.
*
* SEE ALSO: WTX_EVENT_ADD, wtxEventGet(), wtxEventListGet(),
* wtxRegisterForEvent(), wtxUnregisterForEvent().
*/
STATUS wtxEventAdd
(
HWTX hWtx, /* WTX API handle */
const char * event, /* event string to send */
UINT32 addlDataLen, /* length of addl data block in bytes */
const void * pAddlData /* pointer to additional data */
)
{
WTX_MSG_EVENT_DESC in;
WTX_MSG_RESULT out;
WTX_ERROR_T callStat;
WTX_CHECK_CONNECTED (hWtx, WTX_ERROR);
if (addlDataLen != 0 && pAddlData == NULL)
WTX_ERROR_RETURN (hWtx, WTX_ERR_API_INVALID_ARG, WTX_ERROR);
if (event == NULL)
WTX_ERROR_RETURN (hWtx, WTX_ERR_API_INVALID_ARG, WTX_ERROR);
memset (&out, 0, sizeof (out));
memset (&in, 0, sizeof (in));
if ((in.eventDesc.event = (char *) malloc (strlen (event) + 1)) == NULL)
WTX_ERROR_RETURN (hWtx, WTX_ERR_API_MEMALLOC, WTX_ERROR);
strcpy (in.eventDesc.event, event);
in.eventDesc.addlDataLen = (INT32) addlDataLen;
if (addlDataLen != 0)
{
if ((in.eventDesc.addlData = (char *) malloc (addlDataLen)) == NULL)
{
free (in.eventDesc.event);
WTX_ERROR_RETURN (hWtx, WTX_ERR_API_MEMALLOC, WTX_ERROR);
}
memcpy (in.eventDesc.addlData, pAddlData, addlDataLen);
}
else
in.eventDesc.addlData = NULL;
callStat = exchange (hWtx, WTX_EVENT_ADD, &in, &out);
if (callStat != WTX_ERR_NONE)
{
if (in.eventDesc.addlDataLen != 0)
free (in.eventDesc.addlData);
free (in.eventDesc.event);
WTX_ERROR_RETURN (hWtx, callStat, WTX_ERROR);
}
if (in.eventDesc.addlDataLen != 0)
free (in.eventDesc.addlData);
free (in.eventDesc.event);
return (WTX_OK);
}
/*******************************************************************************
*
* wtxEventGet - get an event from the target
*
* This routine polls the target server for any events sent to this
* client tool. It only returns one event at a time. The event
* descriptor returned is a string containing the primary event
* data, a length count of additional binary data and a pointer to the
* additional data. The memory allocated for the event-descriptor
* result must be freed by the user using wtxResultFree(). Note that an
* event descriptor is always returned even when no real event is ready
* for the tool. In this case the event descriptor is WTX_EVENT_OTHER,
* `addlDataLen' is 0, and `addlData' is NULL.
*
* EXPAND ../../../include/wtxmsg.h WTX_EVENT_DESC
*
* RETURNS: A pointer to the descriptor for the event received or NULL.
*
* SEE ALSO: WTX_EVENT_GET, wtxEventAdd(), wtxEventListGet(),
* wtxResultFree(), wtxStrToEventType(), wtxStrToInt(), wtxStrToTgtAddr()
*/
WTX_EVENT_DESC * wtxEventGet
(
HWTX hWtx /* WTX API handle */
)
{
WTX_ERROR_T callStat;
WTX_MSG_EVENT_DESC * pOut;
WTX_CHECK_CONNECTED (hWtx, NULL);
pOut = calloc (1, sizeof (WTX_MSG_EVENT_DESC));
if (pOut == NULL)
WTX_ERROR_RETURN (hWtx, WTX_ERR_API_MEMALLOC, NULL);
callStat = exchange (hWtx, WTX_EVENT_GET, &hWtx->msgToolId, pOut);
if (callStat != WTX_ERR_NONE)
{
free (pOut); /* Free allocated message */
WTX_ERROR_RETURN (hWtx, callStat, NULL);
}
/* add pointer to the wtxResultFree () list */
if (wtxFreeAdd (hWtx, (void *) &pOut->eventDesc, NULL, pOut, WTX_EVENT_GET,
hWtx->server, WTX_SVR_SERVER) != WTX_OK)
{
WTX_ERROR_RETURN (hWtx, wtxErrGet (hWtx), NULL);
}
return (&pOut->eventDesc);
}
/******************************************************************************
*
* wtxEventListGet - get all the events in one call.
*
* This function flushes the target server events queue. If more than one
* event is found, WTX_EVENT_NODE structure is filled with the events found
* up to the limit fixed by <nEvents>. If <nEvents> is equal to 1, then this
* function is equivalent to wtxEventGet(). If all the events will have to be
* flushed, then <nEvents> must be equal to WTX_ALL_EVENTS.
*
* WTX_EVENT_NODE contains a WTX_EVENT_DESC structure and a pointer to the
* next WTX_EVENT_NODE (or NULL if it is the last event).
*
* EXPAND ../../../include/wtxmsg.h WTX_EVENT_NODE
* EXPAND ../../../include/wtxmsg.h WTX_EVENT_DESC
*
* NOTE : The result of the wtxEventListGet() call should be freed by a call to
* wtxResultFree ().
*
* RETURN: A pointer to the event list or NULL if there's no events or if
* something failed (errCode must be checked).
*
* SEE ALSO: WTX_EVENT_LIST_GET, wtxEventGet(), wtxEventAdd(),
* wtxRegisterForEvent(), wtxUnregisterForEvent(), wtxResultFree()
*/
WTX_EVENT_NODE * wtxEventListGet
(
HWTX hWtx, /* WTX API handle */
UINT32 nEvents /* Number of events to return */
)
{
WTX_ERROR_T callStat;
WTX_MSG_PARAM in;
WTX_MSG_EVENT_LIST * pOut;
WTX_CHECK_CONNECTED (hWtx, NULL);
memset (&in, 0, sizeof (in));
in.param.valueType = V_UINT32;
in.param.value_u.v_uint32 = nEvents;
/* Output parameter location */
pOut = calloc (1, sizeof (WTX_MSG_EVENT_LIST));
if (pOut == NULL)
WTX_ERROR_RETURN (hWtx, WTX_ERR_API_MEMALLOC, NULL);
callStat = exchange (hWtx, WTX_EVENT_LIST_GET, &in, pOut);
if (callStat != WTX_ERR_NONE)
{
free (pOut); /* Free allocated message */
WTX_ERROR_RETURN (hWtx, callStat, NULL);
}
/* Output parameter */
/* add pointer to the wtxResultFree () list */
if (wtxFreeAdd (hWtx, (void *) pOut->pEventList, NULL, pOut,
WTX_EVENT_LIST_GET, hWtx->server, WTX_SVR_SERVER) != WTX_OK)
{
WTX_ERROR_RETURN (hWtx, wtxErrGet (hWtx), NULL);
}
return (pOut->pEventList);
}
/*******************************************************************************
*
* wtxEventpointList - list eventpoints on the target server
*
* This routine returns a pointer to a list of all eventpoints managed
* by the target server. These include breakpoints and context exit
* notifications. The list returned is dynamically allocated and should
* be freed by calling wtxResultFree()
*
* EXPAND ../../../include/wtx.h WTX_EVTPT_LIST
*
* RETURNS: A pointer to a list of eventpoints or NULL on error.
*
* SEE ALSO: WTX_EVENTPOINT_LIST, wtxEventpointAdd(), wtxBreakpointAdd(),
* wtxContextExitNotifyAdd()
*/
WTX_EVTPT_LIST * wtxEventpointList
(
HWTX hWtx /* WTX API handle */
)
{
WTX_MSG_EVTPT_LIST * pOut;
WTX_ERROR_T callStat;
WTX_CHECK_CONNECTED (hWtx, NULL);
pOut = calloc (1, sizeof (WTX_MSG_EVTPT_LIST));
if (pOut == NULL)
WTX_ERROR_RETURN (hWtx, WTX_ERR_API_MEMALLOC, NULL);
callStat = exchange (hWtx, WTX_EVENTPOINT_LIST, &hWtx->msgToolId, pOut);
if (callStat != WTX_ERR_NONE)
{
free (pOut);
WTX_ERROR_RETURN (hWtx, callStat, NULL);
}
/* add pointer to the wtxResultFree () list */
if (wtxFreeAdd (hWtx, (void *) &pOut->nEvtpt, NULL, pOut,
WTX_EVENTPOINT_LIST, hWtx->server, WTX_SVR_SERVER)
!= WTX_OK)
{
WTX_ERROR_RETURN (hWtx, wtxErrGet (hWtx), NULL);
}
return (WTX_EVTPT_LIST *) &pOut->nEvtpt;
}
/*******************************************************************************
*
* wtxEventpointListGet - list eventpoints on the target server
*
* This routine returns a pointer to a list of eventpoints info: eventpoints
* managed by the target server, the tool identifier and the eventpoint
* identifier.
*
* EXPAND ../../../include/wtx.h WTX_EVTPT_LIST_2
*
* NOTE : The result of a call to wtxEventpointListGet() should be freed via
* wtxResultFree()
*
* RETURNS: A pointer to an eventpoints info list or NULL on error.
*
* SEE ALSO: WTX_EVENTPOINT_LIST_GET, wtxEventpointList(), wtxBreakpointAdd(),
* wtxContextExitNotifyAdd(), wtxHwBreakpointAdd(), wtxEventpointAdd(),
* wtxResultFree()
*/
WTX_EVTPT_LIST_2 * wtxEventpointListGet
(
HWTX hWtx /* WTX API handle */
)
{
WTX_MSG_EVTPT_LIST_2 * pOut;
WTX_ERROR_T callStat;
WTX_CHECK_CONNECTED (hWtx, NULL);
pOut = calloc (1, sizeof (WTX_MSG_EVTPT_LIST_2));
if (pOut == NULL)
WTX_ERROR_RETURN (hWtx, WTX_ERR_API_MEMALLOC, NULL);
callStat = exchange (hWtx, WTX_EVENTPOINT_LIST_GET, &hWtx->msgToolId, pOut);
if (callStat != WTX_ERR_NONE)
{
free (pOut);
WTX_ERROR_RETURN (hWtx, callStat, NULL);
}
/* add pointer to the wtxResultFree () list */
if (wtxFreeAdd (hWtx, (void *) &pOut->nEvtpt, NULL, pOut,
WTX_EVENTPOINT_LIST_GET, hWtx->server, WTX_SVR_SERVER)
!= WTX_OK)
{
WTX_ERROR_RETURN (hWtx, wtxErrGet (hWtx), NULL);
}