wtx.c

vxworks源码源码解读是学习vxworks的最佳途径

/* wtx.c - WTX C library */

/* Copyright 1984-1998 Wind River Systems, Inc. */
#include "copyright_wrs.h"

/*
modification history
--------------------
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, exiting\n");
	    wtxTerminate (hWtx);
	    exit (0);
	    }

    /@ Catch any other errors in one handler and print error message @/

    WTX_CATCH_ALL (hWtx)
	fprintf (stderr, "%s\n", 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 Protocol\fP 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 */

#ifdef HOST
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <fcntl.h>
#ifndef WIN32
#include <unistd.h>
#endif

#ifdef SUN4_SUNOS4
extern int              sys_nerr;
extern char *           sys_errlist;
#endif /* SUN4_SUNOS4 */
#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 "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;

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

/* XXX : fle : put in comment as it was not used anywhere */
/* static const char * WTX_EVT_CALL_GOT_EXC=	"CALL_GOT_EXC"; */

/* Externals */

/* globals */

FUNCPTR	userNotifyFunc;		/* User defined rtn for async. notif. */
HWTX	hWtxForAsyncNotify;	/* HWTX saved handle */


/* forward declarations */

LOCAL WTX_ERROR_T exchange (HWTX hWtx, UINT32 svcNum, void * pIn, void * pOut);
LOCAL WTX_ERROR_T registryConnect (HWTX	hWtx);
LOCAL void 	  registryDisconnect (HWTX hWtx);

LOCAL void        toolCleanup (HWTX hWtx);
LOCAL void	  serverDescFree (HWTX	hWtx);

#ifdef HOST
LOCAL void	  wtxWrapper (WTX_EVENT_DESC * event);
LOCAL void *      wtxThreadSigHandle (void);
#endif /* HOST */
static BOOL	  internalLoadCall;

/*