wtx.c

VXWORKS源代码

/* wtx.c - WTX C library */

/* Copyright 1994-2001 Wind River Systems, Inc. */
#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, 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 */

#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";