/* 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 exactly03u,04jul92,jcf  scalable/ANSI/cleanup effort.03t,22jun92,jmm  removed symFooWithGroup, added parameter to routines instead03s,26may92,rrr  the tree shuffle03r,15may92,jmm  Changed "symFooGroup" to "symFooWithGroup"03q,30apr92,jmm  Added support for group numbers03p,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 notice03l,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() call03d,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 documentation02c,01jul86,jlf  minor documentation02b,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 copyright01g,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*//*DESCRIPTIONThis library provides facilities for managing symbol tables.  A symboltable associates a name and type with a value.  A name is simply anarbitrary, null-terminated string.  A symbol type is a small integer(typedef SYM_TYPE), and its value is a pointer.  Though commonly usedas the basis for object loaders, symbol tables may be used wheneverefficient association of a value with a name is needed.If you use the symLib subroutines to manage symbol tables local toyour own applications, the values for SYM_TYPE objects are completelyarbitrary; you can use whatever one-byte integers are appropriate foryour application.If you use the symLib subroutines to manipulate the VxWorks systemsymbol table (whose ID is recorded in the global \f3sysSymTbl\f1), thevalues 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 theadding to, removing from, and searching of tables.  All operations on asymbol table are interlocked by means of a mutual-exclusion semaphorein the symbol table structure.  Tables are deleted with symTblDelete().Symbols are added to a symbol table with symAdd().  Each symbol in thesymbol table has a name, a value, and a type.  Symbols are removed from asymbol table with symRemove().Symbols can be accessed by either name or value.  The routinesymFindByName() searches the symbol table for a symbol with aspecified name.  The routine symByValueFind() finds a symbol with aspecified value or, if there is no symbol with the same value, thesymbol in the table with the next lower value than the specifiedvalue.  The routines symFindByNameAndType() andsymByValueAndTypeFind() allow the symbol type to be used as anadditional criterion in the searches.The routines symFindByValue() and symFindByValueAndType() areobsolete.  They are replaced by the routines symByValueFind() andsymByValueAndTypeFind().Symbols in the symbol table are hashed by name into a hash table forfast look-up by name, e.g., by symFindByName().  The size of the hashtable is specified during the creation of a symbol table.  Look-ups byvalue, e.g., symByValueFind(), must search the table linearly; theselook-ups can thus be much slower.The routine symEach() allows each symbol in the symbol table to beexamined by a user-specified function.Name clashes occur when a symbol added to a table is identical in nameand type to a previously added symbol.  Whether or not symbol tablescan accept name clashes is set by a parameter when the symbol table iscreated with symTblCreate().  If name clashes are not allowed,symAdd() will return an error if there is an attempt to add a symbolwith identical name and type.  If name clashes are allowed, addingmultiple symbols with the same name and type will be permitted.  Insuch 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 aboutconfiguration, intialization, and use of the system symbol table.INTERNALStatic symbol tables are initialized with symTblInit(), which operatesidentically with symTblCreate() without allocating the symbol table.Static symbol tables are terminated with symTblTerminate(), which operatesidentically with symTblDelete() without deallocating the symbol table.Symbols may be separately allocated, initialized, and added to the symboltable.  symInit() initializes an existing uninitialized SYMBOL structure.symAlloc() allocates a SYMBOL structure from the memory partitionspecified to symTblCreate(), and then initializes it.  symTblAdd() adds anexisting initialized SYMBOL structure to a symbol table.  The usualsymAdd() function invokes both symAlloc() and symTblAdd().Symbols are deallocated by symFree().  Symbols still resident in a symboltable cannot be deallocated.INCLUDE FILES: symLib.hSEE 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 */