symlib.c

VxWorks操作系统内核源代码

/* symLib.c - symbol table subroutine library */

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

/*
modification history
--------------------
01j,12oct01,jn   fix SPR 7453 - broken API leads to stack corruption - add
                 new API from AE (symXXXFind - from symLib.c@@/main/tor3_x/3) 
		 and new internal-only API (symXXXGet).  
01i,14mar99,jdi  doc: removed refs to config.h and/or configAll.h (SPR 25663).
04h,14feb97,dvs  added check if sysTblId is NULL in symFindByValueAndType() 
		 (SPR #6876)
04g,30oct96,elp  Added syncSymAddRtn, syncSymRemoveRtn function pointers
		 and symSAdd().
04f,19jun96,ism  added error condition if NULL is passed as symbol table to
                    symFindByNameAndType().
04e,22oct95,jdi  doc: added buffer size to allocate for the symFindByValue
		    routines (SPR 4386).
04d,13may95,p_m  added _func_symFindByValue initialization.
04c,11jan95,rhp  doc: mention system symbol table global, sysSymTbl (SPR#2575)
04b,16sep94,rhp  doc: fuller description of SYM_TYPE (SPR#3538).
04a,19may94,dvs  doc'ed problem of standalone image symbol removal (SPR #3199). 
03z,23feb93,jdi  doc: fuller description of <group> in symAdd().
03y,21jan93,jdi  documentation cleanup for 5.1.
03x,01oct92,jcf  biased symFindByValueAndType against xxx.o and gcc2_compiled.
03w,18jul92,smb  Changed errno.h to errnoLib.h.
03v,14jul92,jmm  added support to symKeyCmpName for matching pointers exactly
03u,04jul92,jcf  scalable/ANSI/cleanup effort.
03t,22jun92,jmm  removed symFooWithGroup, added parameter to routines instead
03s,26may92,rrr  the tree shuffle
03r,15may92,jmm  Changed "symFooGroup" to "symFooWithGroup"
03q,30apr92,jmm  Added support for group numbers
03p,02jan92,gae  used UINT's for value in symFindByValue{AndType}
                 for targets in negative address space (e.g. STAR MVP).
03o,13dec91,gae  ANSI cleanup.  Made symFindByCName() consistent with other
		   symFind* routines.
03n,26nov91,llk  added symName() and symNameValueCmp().
03m,04oct91,rrr  passed through the ansification filter
                  -changed functions to ansi style
		  -changed includes to have absolute path from h/
		  -changed TINY and UTINY to INT8 and UINT8
		  -changed VOID to void
		  -changed copyright notice
03l,20may91,jdi	 documentation tweak.
03k,05apr91,jdi	 documentation -- removed header parens and x-ref numbers;
		 doc review by dnw.
03j,24mar91,jdi  documentation cleanup.
03i,05oct90,dnw  made symFindByCName(), symFindByValueAndType(),
		   symFindSymbol(), symInit(), symTblTerminate() be NOMANUAL
		 made symFindByValueAndType bias against symbols ending in
		   "_text", "_data", "_bss"
03h,05oct90,dnw  added forward declarations.
03g,29sep90,jcf  documentation.
03f,02aug90,jcf  documentation.
03e,17jul90,dnw  changed to new objAlloc() call
03d,05jul90,jcf  documentation.
03c,20jun90,jcf  changed binary semaphore interface
		 changed ffs() changed ffsMsb()
03b,15apr90,jcf  included sysSymTbl.h.
03a,17nov89,jcf  rewritten to use hashLib (2).
		  changed interface/funtionality of symDelete/symInit/symCreate.
		  documentation.
02o,29nov89,llk  added symFindByCName for vxgdb.
02n,07jun89,gae  added symDelete.
02m,01sep88,gae  documentation.
02l,07jul88,jcf  changed malloc to match new declaration.
02k,30may88,dnw  changed to v4 names.
02j,04nov87,ecs  documentation.
02i,16aug87,gae  added parm. to symEach() and made it void.
02h,07jul87,ecs  added symFindType.
		 optimized symEach, symValFind, and symFind.
02g,02apr87,ecs  added include of strLib.c.
02f,23mar87,jlf  documentation
		 changed memAllocate's to malloc's.
02e,21dec86,dnw  changed to not get include files from default directories.
02d,04sep86,jlf  minor documentation
02c,01jul86,jlf  minor documentation
02b,05jun86,dnw  changed SYMTAB to have pointer to SYMBOL array instead of
		   having it imbedded in SYMTAB structure.
02a,11oct85,dnw  changed to dynamically allocate space for symbol strings.
		   Note change to symCreate call which now takes max number of
		   symbols instead of number of bytes in table.
		 De-linted.
01j,21jul85,jlf  documentation.
01i,11jun85,rdc  added variable length symbols.
01h,08sep84,jlf  added comments and copyright
01g,13aug84,ecs  changed status code EMPTY_SYMBOL_TABLE to SYMBOL_NOT_FOUND.
01f,08aug84,ecs  added calls to setStatus to symAdd, symFind, and symValFind.
01e,27jun84,ecs  changed symAdd & symValFind so that names in symbol tables
		   are now EOS terminated.
01d,26jun84,dnw  fixed bug in symValFind of potentially copying too many
		   bytes to user's name buffer.
01c,18jun84,jlf  added symEach and symValFind.
01b,03jun84,dnw  added symCreate.
		 changed symFind to search backwards in table to find most
		   recent of multiply defined symbols.
		 moved typedefs of SYMBOL and SYMTAB to symLib.h.
		 added LINTLIBRARY and various coercions for lint.
01a,03aug83,dnw  written
*/

/*
DESCRIPTION
This library provides facilities for managing symbol tables.  A symbol
table associates a name and type with a value.  A name is simply an
arbitrary, null-terminated string.  A symbol type is a small integer
(typedef SYM_TYPE), and its value is a pointer.  Though commonly used
as the basis for object loaders, symbol tables may be used whenever
efficient association of a value with a name is needed.

If you use the symLib subroutines to manage symbol tables local to
your own applications, the values for SYM_TYPE objects are completely
arbitrary; you can use whatever one-byte integers are appropriate for
your application.

If you use the symLib subroutines to manipulate the VxWorks system
symbol table (whose ID is recorded in the global \f3sysSymTbl\f1), the
values for SYM_TYPE are SYM_UNDF, SYM_LOCAL, SYM_GLOBAL, SYM_ABS,
SYM_TEXT, SYM_DATA, SYM_BSS, and SYM_COMM (defined in symbol.h).

Tables are created with symTblCreate(), which returns a symbol table ID.
This ID serves as a handle for symbol table operations, including the
adding to, removing from, and searching of tables.  All operations on a
symbol table are interlocked by means of a mutual-exclusion semaphore
in the symbol table structure.  Tables are deleted with symTblDelete().

Symbols are added to a symbol table with symAdd().  Each symbol in the
symbol table has a name, a value, and a type.  Symbols are removed from a
symbol table with symRemove().

Symbols can be accessed by either name or value.  The routine
symFindByName() searches the symbol table for a symbol with a
specified name.  The routine symByValueFind() finds a symbol with a
specified value or, if there is no symbol with the same value, the
symbol in the table with the next lower value than the specified
value.  The routines symFindByNameAndType() and
symByValueAndTypeFind() allow the symbol type to be used as an
additional criterion in the searches.

The routines symFindByValue() and symFindByValueAndType() are
obsolete.  They are replaced by the routines symByValueFind() and
symByValueAndTypeFind().

Symbols in the symbol table are hashed by name into a hash table for
fast look-up by name, e.g., by symFindByName().  The size of the hash
table is specified during the creation of a symbol table.  Look-ups by
value, e.g., symByValueFind(), must search the table linearly; these
look-ups can thus be much slower.

The routine symEach() allows each symbol in the symbol table to be
examined by a user-specified function.

Name clashes occur when a symbol added to a table is identical in name
and type to a previously added symbol.  Whether or not symbol tables
can accept name clashes is set by a parameter when the symbol table is
created with symTblCreate().  If name clashes are not allowed,
symAdd() will return an error if there is an attempt to add a symbol
with identical name and type.  If name clashes are allowed, adding
multiple symbols with the same name and type will be permitted.  In
such cases, symFindByName() will return the value most recently added,
although all versions of the symbol can be found by symEach().

The system symbol table (\f3sysSymTbl\f1) allows name clashes.

See the VxWorks Programmmer's Guide for more information about
configuration, intialization, and use of the system symbol table.

INTERNAL
Static symbol tables are initialized with symTblInit(), which operates
identically with symTblCreate() without allocating the symbol table.

Static symbol tables are terminated with symTblTerminate(), which operates
identically with symTblDelete() without deallocating the symbol table.

Symbols may be separately allocated, initialized, and added to the symbol
table.  symInit() initializes an existing uninitialized SYMBOL structure.
symAlloc() allocates a SYMBOL structure from the memory partition
specified to symTblCreate(), and then initializes it.  symTblAdd() adds an
existing initialized SYMBOL structure to a symbol table.  The usual
symAdd() function invokes both symAlloc() and symTblAdd().

Symbols are deallocated by symFree().  Symbols still resident in a symbol
table cannot be deallocated.

INCLUDE FILES: symLib.h

SEE ALSO: loadLib 
*/

/* LINTLIBRARY */

#include "vxWorks.h"
#include "errnoLib.h"
#include "objLib.h"
#include "classLib.h"
#include "symLib.h"
#include "semLib.h"
#include "memLib.h"
#include "memPartLib.h"
#include "hashLib.h"
#include "string.h"
#include "stdlib.h"
#include "sysSymTbl.h"
#include "private/funcBindP.h"

IMPORT int ffsMsb (int bitfield);

#define SYM_HFUNC_SEED	1370364821		/* magic seed */

typedef struct		/* RTN_DESC - routine descriptor */
    {
    FUNCPTR	routine;	/* user routine passed to symEach() */
    int		routineArg;	/* user routine arg passed to symEach() */
    } RTN_DESC;

/* local variables */

LOCAL OBJ_CLASS symTblClass;

/* global variables */

CLASS_ID symTblClassId = &symTblClass;
int mutexOptionsSymLib = SEM_Q_FIFO | SEM_DELETE_SAFE;
UINT16 symGroupDefault = 0;
FUNCPTR syncSymAddRtn = (FUNCPTR) NULL;
FUNCPTR syncSymRemoveRtn = (FUNCPTR) NULL;

/* forward static functions */
 
static BOOL symEachRtn (SYMBOL *pSymbol, RTN_DESC *pRtnDesc);
static int symHFuncName (int elements, SYMBOL *pSymbol, int seed);
static BOOL symKeyCmpName (SYMBOL *pMatchSymbol, SYMBOL *pSymbol,
			   int mask);
static BOOL symNameValueCmp (char *name, int val, SYM_TYPE type, int pSym);


/*******************************************************************************
*
* symLibInit - initialize the symbol table library
*
* This routine initializes the symbol table package.  If the configuration
* macro INCLUDE_SYM_TBL is defined, symLibInit() is called by the root task,
* usrRoot(), in usrConfig.c.
*
* RETURNS: OK, or ERROR if the library could not be initialized.
*/

STATUS symLibInit (void)
    {
    /* avoid direct coupling with symLib with these global variables */

    _func_symFindSymbol = (FUNCPTR) symFindSymbol;
    _func_symNameGet    = (FUNCPTR) symNameGet;
    _func_symValueGet   = (FUNCPTR) symValueGet;
    _func_symTypeGet    = (FUNCPTR) symTypeGet;
   
    /* 
     * XXX JLN The functions symFindByValueAndType and symFindByValue
     * are obsolete and should not be used.  They remain (as functions
     * and as function pointers) for backwards compatibility only.
     * The function pointers should be removed when all uses are
     * removed from vxWorks.  The functions themselves must remain
     * as long as required for backwards compatibility.
     */

    _func_symFindByValueAndType = (FUNCPTR) symFindByValueAndType; 
    _func_symFindByValue        = (FUNCPTR) symFindByValue;

    /* initialize the symbol table class structure */

    return (classInit (symTblClassId, sizeof (SYMTAB), OFFSET (SYMTAB, objCore),
		       (FUNCPTR) symTblCreate, (FUNCPTR) symTblInit,
		       (FUNCPTR) symTblDestroy));
    }

/*******************************************************************************
*
* symTblCreate - create a symbol table
*
* This routine creates and initializes a symbol table with a hash table of a
* specified size.  The size of the hash table is specified as a power of two.
* For example, if <hashSizeLog2> is 6, a 64-entry hash table is created.
*
* If <sameNameOk> is FALSE, attempting to add a symbol with
* the same name and type as an already-existing symbol results in an error.
*
* Memory for storing symbols as they are added to the symbol table will be
* allocated from the memory partition <symPartId>.  The ID of the system
* memory partition is stored in the global variable `memSysPartId', which
* is declared in memLib.h.
*
* RETURNS: Symbol table ID, or NULL if memory is insufficient.
*/

SYMTAB_ID symTblCreate
    (
    int     hashSizeLog2,       /* size of hash table as a power of 2 */
    BOOL    sameNameOk,         /* allow 2 symbols of same name & type */
    PART_ID symPartId           /* memory part ID for symbol allocation */
    )
    {
    SYMTAB_ID symTblId = (SYMTAB_ID) objAlloc (symTblClassId);

    if (symTblId != NULL)
	{
	symTblId->nameHashId = hashTblCreate (hashSizeLog2,
					      (FUNCPTR) symKeyCmpName,
					      (FUNCPTR) symHFuncName,
					      SYM_HFUNC_SEED);

	if (symTblId->nameHashId == NULL)	/* hashTblCreate failed? */
	    {
	    objFree (symTblClassId, (char *) symTblId);
	    return (NULL);
	    }

	if (symTblInit (symTblId, sameNameOk, symPartId,
			symTblId->nameHashId) != OK)
	    {
	    hashTblDelete (symTblId->nameHashId);
	    objFree (symTblClassId, (char *) symTblId);
	    return (NULL);
	    }
	}

    return (symTblId);				/* return the symbol table ID */
    }

/*******************************************************************************
*
* symTblInit - initialize a symbol table
*
* Initialize a symbol table.  Any symbols currently in the table will be lost.
* The specified hash table ID and memory partition ID must already be
* initialized.
*
* RETURNS: OK, or ERROR if initialization failed.
*
* NOMANUAL
*/

STATUS symTblInit
    (
    SYMTAB  *pSymTbl,           /* ptr to symbol table to initialize */
    BOOL    sameNameOk,         /* two symbols of same name and type allowed */
    PART_ID symPartId,          /* partition from which to allocate symbols */
    HASH_ID symHashTblId        /* ID of an initialized hash table */
    )
    {
    if ((OBJ_VERIFY (symHashTblId, hashClassId) != OK) ||
        (semMInit (&pSymTbl->symMutex, mutexOptionsSymLib) != OK))
	{
	return (ERROR);
	}

    pSymTbl->sameNameOk = sameNameOk;		/* name clash policy */
    pSymTbl->nsymbols   = 0;			/* initial number of syms */
    pSymTbl->nameHashId = symHashTblId;		/* fill in hash table ID */
    pSymTbl->symPartId  = symPartId;		/* fill in mem partition ID */

    /* initialize core */

    objCoreInit (&pSymTbl->objCore, symTblClassId);

    return (OK);
    }

/*******************************************************************************
*
* symTblDelete - delete a symbol table
*
* This routine deletes a specified symbol table.  It deallocates all
* associated memory, including the hash table, and marks the table as
* invalid.
*
* Deletion of a table that still contains symbols results in ERROR.
* Successful deletion includes the deletion of the internal hash table and
* the deallocation of memory associated with the table.  The table is marked
* invalid to prohibit any future references.
*
* RETURNS: OK, or ERROR if the symbol table ID is invalid.
*/

STATUS symTblDelete
    (
    SYMTAB_ID symTblId          /* ID of symbol table to delete */
    )
    {
    return (symTblDestroy (symTblId, TRUE));
    }

/*******************************************************************************
*
* symTblTerminate - terminate a symbol table
*
* The specified symbol table is terminated if no symbols are resident.
* Otherwise, ERROR is returned.
*
* RETURNS: OK, or ERROR if invalid symbol table ID, or symbols still in table.
*
* NOMANUAL
*/

STATUS symTblTerminate
    (
    SYMTAB_ID symTblId          /* ID of symbol table to delete */