symsynclib.c

VXWORKS源代码

/* symSyncLib.c - host/target symbol table synchronization */

/* Copyright 1996-2002 Wind River Systems, Inc. */

/*
modification history
--------------------
01t,03may02,jhw  Added VX_FP_TASK task option to tSymSync. (SPR 66307)
01s,03apr02,j_s  correct the miscalculation of length limit of symbol name
		 in syncSymAddHook/syncSymRemoveHook (SPR 75036).
01r,30oct01,jn   use symFindSymbol for symbol lookup (SPR #7453)
01q,01oct01,c_c  Fixed SPR 62583.
01p,02apr99,jdi  corrected spelling of NOMANUAL in syncTgtSafeModCheck()
01o,14mar99,jdi  doc: removed refs to config.h and/or configAll.h (SPR 25663).
01n,01sep98,pcn  Added wtxObjModuleUndefSymAdd definition.
01m,27jul98,elp  fixed stack size for SIMSPARCSOLARIS (SPR #20150).
01l,07jul98,pcn  Added include for wtxObjModuleUndefSymAdd.
01k,24apr98,dbt  fixed WTX timeout error message (SPR #20852).
01j,14jul97,dgp  doc: edit new additions
01i,21feb96,elp	 improved timeout managements (added warning message).
01h,13feb97,elp  managed timeout errors on wtxEventGet() (SPR# 7959)
		 + network doc enhancements (SPR# 7852).
01g,06jan97,elp  fixed a typo.
01f,18dec96,jdi  doc: more enhancements and cleanup; changed title line to
		    reflect new name of module.
01e,12dec96,elp  moved hooks initialization into tSymSync
		 + added global symSyncHWtx to enable timeout modifications.
		 + added symSyncTimeout()
		 + name revision.
01d,10dec96,jdi  doc: cleanup.
01c,13nov96,elp  doc generation.
01b,24oct96,elp  added event notification when synchronization is done
		 + synchronize usual target commands (ld(), symAdd(), ...).
01a,04oct96,elp  written.
*/

/*
DESCRIPTION
This module provides host/target symbol table synchronization.
With synchronization, every module or symbol added to the run-time
system from either the target or host side can be seen by facilities
on both the target and the host. Symbol table synchronization makes it 
possible to use host tools to debug application modules loaded with the 
target loader or from a target file system.  To enable synchronization, 
two actions must be performed: 

.iP 1 6
The module is initialized by symSyncLibInit(), which is called automatically 
when the configuration macro INCLUDE_SYM_TBL_SYNC is defined.
.iP 2
The target server is launched with the `-s' option.
.LP

If synchronization is enabled, `symSyncLib' spawns a synchronization task 
on the target, `tSymSync'. This task behaves as a WTX tool and attaches 
itself to the target server.  When the task starts, it synchronizes target 
and host symbol tables so that every module loaded on the target before the 
target server was started can be seen by the host tools.  This feature is 
particularly useful if VxWorks is started with a target-based startup script 
before the target server has been launched.

The `tSymSync' task synchronizes new symbols that are added
by either the target or the host tools.  The task waits for synchronization 
events on two channels:  a WTX event from the host or a message queue additon
from the target.

The `tSymSync' task, like all WTX tools, must be able to connect to the WTX
registry. To make the WTX registry accessible from the target, do one of
the following:

.iP 1 6
Boot the target from a host on the same subnet as the registry.
.iP 2
Start the registry on the same host the target boots from.
.iP 3
Add the needed routes with routeAdd() calls, possibly in a startup script.
.LP

Neither the host tools nor the target loader wait for synchronization
completion to return.  To know when the synchronization is complete, you
can wait for the corresponding event sent by the target server, or,
if your target server was started with the `-V' option, it prints a
message indicating synchronization has completed.

The event sent by the target server is of the following format:

.tS
    SYNC_DONE <syncType> <syncObj> <syncStatus>
.tE

The following are examples of messages displayed by the target server
indicating synchronization is complete:
.CS
    Added target_modules         to target-server.....done
    Added ttTest.o.68k           to target............done
.CE

If synchronization fails, the following message is displayed:
.CS
    Added gopher.o               to target............failed
.CE

This error generally means that synchronization of the corresponding module
or symbol is no longer possible because it no longer exists in the original
symbol table.  If so, it will be followed by:
.CS
    Removed gopher.o             from target..........failed
.CE

Failure can also occur if a timeout is reached.  
Call symSyncTimeoutSet() to modify the WTX timeout between the target
synchronization task and the target server.

LIMITATIONS
Hardware:  Because the synchronization task uses the WTX protocol to
communicate with the target server, the target must include network
facilities.  Depending on how much synchronization is to be done (number
of symbols to transfer), a reasonable throughput between the target server
and target agent is required (the wdbrpc backend is recommended when large
modules are to be loaded).

Performance:  The synchronization task requires some minor overhead in
target routines msgQSend(), loadModule(), symAdd(), and symRemove(); 
however, if an application sends more than 15 synchronization events,
it will fill the message queue and then need to wait for a synchronization
event to be processed by `tSymSync'. Also, waiting for host synchronization 
events is done by polling; thus there may be some impact on performance if 
there are lower-priority tasks than `tSymSync'.  If no more synchronization 
is needed, `tSymSync' can be suspended.

Known problem:  Modules with undefined symbols that are loaded from the target
are not synchronized; however, they are synchronized if they are loaded
from the host.

SEE ALSO
`tgtsvr'
*/

/* includes */

#include "symSyncLib.h"
#include "rpcLib.h"
#include "loadLib.h"
#include "unldLib.h"
#include "symLib.h"
#include "msgQLib.h"
#include "sysLib.h"
#include "a_out.h"	/* XXX ELP to get N_TYPE definition */
#include "usrLib.h"
#include "logLib.h"

/* typedefs */

typedef struct
    {
    DL_NODE 	node;
    UINT16	tgtGroup;
    UINT32	hostGroup;
    } GROUP_NODE;

/* 
 * dummy type that concatenates arguments as only one can be passed to
 * routines called by symEach().
 */

typedef struct 
	{
	HWTX	hWtx;
	UINT16	tgtGroup;
	UINT32	hostGroup;
	} BY_GROUP_ARG_T;

/* defines */

/* #define DEBUG */

#define H_STR_TO_L(str)		(strtoul (str, NULL, 16))

#define SYNC_TGT_EVT_MAX	15		/* max number of sync rqsts */
#define OBJ_NAME_MAX		30
#define SYNC_TGT_EVT_LGTH	60		/* max event string length */
#define OBJ_LOADED_EVT		"OBJ_LOADED"
#define OBJ_UNLOADED_EVT	"OBJ_UNLOADED"
#define SYM_ADDED_EVT		"SYM_ADDED"
#define SYM_REMOVED_EVT		"SYM_REMOVED"
#define SYM_ADDED_EVT_MSG_NON_NAME_LGTH		34
#define USR_RQST_EVT		"USR_RQST"
#define TIMEOUT 		sysClkRateGet()
					/* for sending/receiving events */

#define SYNC_PRIORITY		90

/* XXX - jhw 
 * The VX_FP_TASK option is needed to prevent corruption of 
 * the floating point registers. All tasks that call
 * (directly or indirectly) C++ code that is compiled without 
 * '-fnoexceptions' with gnu 2.96 are affected.
 * See SPR 66307,70995 for additional info.
 * This module calls unldByModuleId() which calls C++ destructors.
 */

#define SYNC_OPTIONS		VX_FP_TASK

#if (CPU_FAMILY == MC680X0) 
#define SYNC_STACK_SIZE		8000
#elif (CPU_FAMILY == I960)
#define SYNC_STACK_SIZE		5000
#elif ((CPU_FAMILY == SIMSPARCSOLARIS) || (CPU_FAMILY == SPARC) || \
       (CPU_FAMILY == SIMSPARCSUNOS))
#define SYNC_STACK_SIZE		15000
#else
#define SYNC_STACK_SIZE		5000
#endif

/* globals */

MSG_Q_ID		symSyncMsgQId;	/* target synchro event container */
HWTX			symSyncHWtx;	/* symbol synchro WTX handle */

/* locals */

LOCAL const char	SYM_SYNC_TOOL_NAME[] = 	"symTblsSync";
LOCAL DL_LIST		symSyncLst;		/* sync modules list */
LOCAL DL_LIST		symSyncTmpLst;		/* tmp buffer */
LOCAL BOOL		symSyncKill;		/* to exit tSymSync loop */
LOCAL UINT32		symSyncWtxTimeout = 5000;	/* wtx timeout */

IMPORT CLASS_ID			symTblClassId;
IMPORT CLASS_ID			moduleClassId;
IMPORT SYMTAB_ID		sysSymTbl;
IMPORT struct opaque_auth	authCred;

/* forward declarations */

extern 			STATUS wtxObjModuleUndefSymAdd (HWTX, char *, UINT32 );

STATUS			symSRemove (SYMTAB_ID, char *, SYM_TYPE);

/* group list processing */

LOCAL STATUS		groupAdd (DL_LIST *, UINT16, UINT32);
LOCAL GROUP_NODE *	groupFind (DL_LIST *, UINT32, FUNCPTR);
LOCAL GROUP_NODE *	groupRemove (DL_LIST *, UINT32, FUNCPTR);
LOCAL BOOL		isInHostGroupList (DL_NODE *, int);
LOCAL BOOL		isInTgtGroupList (DL_NODE *, int);

LOCAL void		syncGroupUpdate ();
LOCAL STATUS		symSyncMain (HWTX);
LOCAL STATUS		symSyncTaskInit (char *);

/* host -> target synchronization */

LOCAL STATUS		symSyncTgtUpdate (HWTX, char *, char *);
LOCAL STATUS		syncModCTgtUpdate (HWTX, UINT32);
LOCAL STATUS		syncModDTgtUpdate (HWTX, UINT32);
LOCAL STATUS		syncSymAddTgtUpdate (HWTX, char *);
LOCAL MODULE_ID		syncTgtModInfoFill (WTX_MODULE_INFO *);

/* target -> host synchronization */

LOCAL STATUS	symSyncHostUpdate (HWTX, char *, char *);
LOCAL STATUS	syncModCHostUpdate (HWTX, DL_LIST *, MODULE_ID, BOOL *,BOOL);
LOCAL STATUS	syncModDHostUpdate (HWTX, char *, UINT16);
LOCAL STATUS	syncSymAddHostUpdate (HWTX, char *, char *, SYM_TYPE, UINT16);
LOCAL STATUS	syncSymRemHostUpdate (HWTX, char *, SYM_TYPE);
LOCAL STATUS	syncHostModInfoFill (WTX_LD_M_FILE_DESC *, MODULE_ID, BOOL);
LOCAL STATUS	syncUsrUpdate (HWTX, int, int);
LOCAL BOOL	syncTgtSafeModCheck (MODULE_ID , int);
LOCAL BOOL	syncEachSymToHost (char *, int, SYM_TYPE, int, UINT16);
LOCAL BOOL	syncSymByGrpToHost (char *, int, SYM_TYPE, int, UINT16);

LOCAL void	syncLoadHook (MODULE_ID);
LOCAL void	syncUnldHook (MODULE_ID);
LOCAL void	syncSymAddHook (char *, char *, SYM_TYPE, UINT16);
LOCAL void	syncSymRemoveHook (char *, SYM_TYPE);

/******************************************************************************
* 
* symSyncLibInit - initialize host/target symbol table synchronization
*
* This routine initializes host/target symbol table synchronization. 
* To enable synchronization, it must be called before a target server
* is started.  It is called automatically if the configuration macro
* INCLUDE_SYM_TBL_SYNC is defined.
*
* RETURNS: N/A
*/

void symSyncLibInit ()
    {

    /* create the target synchronization event folder */
    symSyncMsgQId = msgQCreate (SYNC_TGT_EVT_MAX, SYNC_TGT_EVT_LGTH,
				MSG_Q_FIFO);

    return;
    }

/******************************************************************************
*
* symSyncTimeoutSet - set WTX timeout 
*
* This routine sets the WTX timeout between target server and synchronization
* task.
*
* RETURNS: If <timeout> is 0, the current timeout, otherwise the new timeout
* value in milliseconds.
*/

UINT32 symSyncTimeoutSet
    (
    UINT32	timeout		/* WTX timeout in milliseconds */
    )
    {
    UINT32 curTimeout;

    if (wtxToolConnected (symSyncHWtx))
	{
	if (timeout == 0)
	    {
	    if (wtxTimeoutGet (symSyncHWtx, &curTimeout) == WTX_OK)
		return (curTimeout);
	    return (symSyncWtxTimeout);
	    }
	else
	    {
	    symSyncWtxTimeout = timeout;
	    wtxTimeoutSet (symSyncHWtx, symSyncWtxTimeout);
	    return (symSyncWtxTimeout);
	    }
	}
    
    if (timeout == 0)
	return (symSyncWtxTimeout);
    symSyncWtxTimeout = timeout;
    return (symSyncWtxTimeout);
    }

/******************************************************************************
*
* syncErrHandler - synchronization error handler
* 
* Some WTX errors may happen in an unpredictable way (because information of
* the synchronization task are not up to date). So these errors should be 
* ignored.
*
* RETURNS: FALSE to prevent from calling other error handler. 
*
* NOMANUAL
*/

BOOL32 syncErrHandler
    (
    HWTX	hWtx,		/* WTX API handle */
    void *	pClientData,
    void *	errCode
    )
    {
    if (((WTX_ERROR_T)errCode == WTX_OK) ||
	((WTX_ERROR_T)errCode == WTX_ERR_LOADER_OBJ_MODULE_NOT_FOUND) || 
	((WTX_ERROR_T)errCode == WTX_ERR_SYMTBL_SYMBOL_NOT_FOUND) ||
	((WTX_ERROR_T)errCode == WTX_ERR_SYMTBL_NO_SUCH_MODULE))
	{
#ifdef DEBUG 
	logMsg ("%#x ignored\n", (WTX_ERROR_T)errCode, 0, 0, 0, 0, 0);
#endif
	}
    else if (((WTX_ERROR_T)errCode == WTX_ERR_API_NOT_CONNECTED) ||
	     ((WTX_ERROR_T)errCode == WTX_ERR_API_TOOL_DISCONNECTED) ||
	     ((WTX_ERROR_T)errCode == WTX_ERR_API_REGISTRY_UNREACHABLE) ||
	     ((WTX_ERROR_T)errCode == WTX_ERROR))
	{
	if (!symSyncKill)
	    fprintf (stderr,
		     "Fatal WTX error (%#x), synchronization stopped\n",
		     (int)errCode);
	symSyncKill = TRUE; 	/* end the task */
	}
    else if ((WTX_ERROR_T)errCode == WTX_ERR_API_REQUEST_TIMED_OUT)
	{
	fprintf (stderr, "Warning: tSymSync WTX timeout\n");
	}
    else
	{
#ifdef DEBUG
	fprintf (stderr, "Unexpected WTX error %#x during synchronization\n",
		 (WTX_ERROR_T)errCode);
        taskSuspend (0);
#endif
	}

    return (FALSE);
    }

/******************************************************************************
*
* syncSymStart - start the synchronization task
*
* This routine is the entry point that is called by target server.
* It initializes registry inet and RPC credentials and then starts <tSymSync>
* task.
* Once the synchronization task is started, it sends a request to synchronize
* the symbol tables.
*
* RETURNS: tid of <tSymSync> or WTX_ERROR.
*
* NOMANUAL
*/

STATUS syncSymStart
    (
    char *	tgtSvrName,	/* target server name */
    UINT32	registryInet,	/* registry address */
    int		pCredFlavor,	/* RPC credentials information */
    void *	pCredBase,
    UINT32	pCredLength
    )
    {
    int		tid;
    char	startSyncEvt[SYNC_TGT_EVT_LGTH];

    if (OBJ_VERIFY (sysSymTbl, symTblClassId) != OK)
	return (WTX_ERROR);

    /* store the registry internet address */
    syncRegistry = registryInet;

    /* store RPC credentials */
    authCred.oa_flavor = pCredFlavor;
    authCred.oa_base = pCredBase;
    authCred.oa_length = pCredLength;

    /*
     * Initialize hooks so that module loads and symbol additions send a
     * message in the synchronization message queue.
     */
    taskLock ();
    syncLoadRtn = (FUNCPTR) syncLoadHook;
    syncUnldRtn = (FUNCPTR) syncUnldHook;
    syncSymAddRtn = (FUNCPTR) syncSymAddHook;
    syncSymRemoveRtn = (FUNCPTR) syncSymRemoveHook;
    taskUnlock ();

    tid = taskSpawn ("tSymSync", SYNC_PRIORITY, SYNC_OPTIONS, SYNC_STACK_SIZE,
		     symSyncTaskInit, (int)tgtSvrName, 0,0,0,0,0,0,0,0,0);

    /* bring unknown target symbols to host symbol table */
    sprintf (startSyncEvt, "%s 0x1 0x1", USR_RQST_EVT);
    msgQSend (symSyncMsgQId, startSyncEvt, strlen(startSyncEvt)+1, TIMEOUT, 
	      MSG_PRI_NORMAL);
    
    return (tid);
    }

/******************************************************************************
*
* symSyncTaskInit - WTX initializations
*
* This routine initializes RPC then WTX, attaches to target server and 
* registers for concerned events.
* 
* RETURNS: OK or ERROR.
*
* NOMANUAL
*/

STATUS symSyncTaskInit
    (
    char *	tgtSvrName	/* target server name */
    )
    {
    char 		regEvtStr[50];	/* registered events */
    WTX_HANDLER_T	wtxErrHId; 	/* error handler id */

    strcpy (regEvtStr, "(OBJ_(LOAD|UNLOAD)|SYM_(ADD|REMOV))ED|SYNC_STOP");