315 lines
12 KiB
C++
315 lines
12 KiB
C++
// VXWSymTab/vxwSymLib.h - symbol table class
|
|
|
|
// Copyright 1995-1999 Wind River Systems, Inc.
|
|
|
|
// modification history
|
|
// --------------------
|
|
// 01c,09mar99,jdi doc: fixed wrong cross-references.
|
|
// 01b,23feb99,fle doc : made it refgen compliant
|
|
// 01c,21feb99,jdi added library section, checked in documentation.
|
|
// 01b,30sep95,rhp documented.
|
|
// 01a,15jun95,srh written.
|
|
|
|
// DESCRIPTION
|
|
// This class 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 character 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 VXWSymTab class 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 the VxWorks system symbol table is configured into your target
|
|
// system, you can use the VXWSymTab class to manipulate it based on
|
|
// its symbol-table ID, recorded in the global \f3sysSymTbl\f1; see
|
|
// VXWSymTab::VXWSymTab() to construct an object based on this global.
|
|
// In the VxWorks target-resident global symbol table, the values for
|
|
// SYM_TYPE are N_ABS, N_TEXT, N_DATA, and N_BSS (defined in a_out.h);
|
|
// these are all even numbers, and any of them may be combined (via
|
|
// boolean or) with N_EXT (1). These values originate in the section
|
|
// names for a.out object code format, but the VxWorks system symbol
|
|
// table uses them as symbol types across all object formats. (The
|
|
// VxWorks system symbol table also occasionally includes additional
|
|
// types, in some object formats.)
|
|
//
|
|
// All operations on a symbol table are interlocked by means of a
|
|
// mutual-exclusion semaphore in the symbol table structure.
|
|
//
|
|
// Symbols are added to a symbol table with VXWSymTab::add(). Each
|
|
// symbol in the symbol table has a name, a value, and a type.
|
|
// Symbols are removed from a symbol table with VXWSymTab::remove().
|
|
//
|
|
// Symbols can be accessed by either name or value. The routine
|
|
// VXWSymTab::findByName() searches the symbol table for a symbol of a
|
|
// specified name. The routine VXWSymTab::findByValue() finds the
|
|
// symbol with the value closest to a specified value. The routines
|
|
// VXWSymTab::findByNameAndType() and VXWSymTab::findByValueAndType()
|
|
// allow the symbol type to be used as an additional criterion in the
|
|
// searches.
|
|
//
|
|
// Symbols in the symbol table are hashed by name into a hash table
|
|
// for fast look-up by name, for instance with VXWSymTab::findByName(). The
|
|
// size of the hash table is specified during the creation of a symbol
|
|
// table. Look-ups by value, such as with VXWSymTab::findByValue(), must
|
|
// search the table linearly; these look-ups can thus be much slower.
|
|
//
|
|
// The routine VXWSymTab::each() 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 VXWSymTab::VXWSymTab(). If name
|
|
// clashes are not allowed, VXWSymTab::add() returns 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 is not an error. In such cases,
|
|
// VXWSymTab::findByName() returns the value most recently added,
|
|
// although all versions of the symbol can be found by
|
|
// VXWSymTab::each().
|
|
//
|
|
// INCLUDE FILES: vxwSymLib.h
|
|
//
|
|
// SEE ALSO: VXWModule
|
|
//
|
|
|
|
#ifndef vxwSymLib_h
|
|
#define vxwSymLib_h
|
|
|
|
#include "vxWorks.h"
|
|
#include "symLib.h"
|
|
#include "vxwObject.h"
|
|
#include "vxwErr.h"
|
|
|
|
class VXWSymTab : virtual public VXWIdObject
|
|
{
|
|
public:
|
|
//_ VXWSymTab Public Constructors
|
|
|
|
///////////////////////////////////////////////////////////////////////////////
|
|
//
|
|
// VXWSymTab::VXWSymTab - create a symbol table
|
|
//
|
|
// This constructor 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: N/A
|
|
|
|
VXWSymTab (int hashSizeLog2, BOOL sameNameOk, PART_ID symPartId)
|
|
: stid_ (symTblCreate (hashSizeLog2, sameNameOk, symPartId))
|
|
{
|
|
if (stid_ == 0)
|
|
vxwThrowErrno ();
|
|
}
|
|
|
|
///////////////////////////////////////////////////////////////////////////////
|
|
//
|
|
// VXWSymTab::VXWSymTab - create a symbol-table object
|
|
//
|
|
// This constructor creates a symbol table object based on an existing
|
|
// symbol table. For example, the following statement creates a
|
|
// symbol-table object for the VxWorks system symbol table (assuming
|
|
// you have configured a target-resident symbol table into your
|
|
// VxWorks system):
|
|
// .CS
|
|
// VXWSymTab sSym;
|
|
// ...
|
|
// sSym = VXWSymTab (sysSymTbl);
|
|
// .CE
|
|
|
|
VXWSymTab (SYMTAB_ID aSymTabId)
|
|
: stid_ (aSymTabId)
|
|
{
|
|
}
|
|
|
|
///////////////////////////////////////////////////////////////////////////////
|
|
//
|
|
// VXWSymTab::~VXWSymTab - delete a symbol table
|
|
//
|
|
// This routine deletes a symbol table; it deallocates all memory
|
|
// associated with its symbol table, including the hash table, and
|
|
// marks the table as invalid.
|
|
//
|
|
// Deletion of a table that still contains symbols throws an 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 table still contains symbols.
|
|
|
|
~VXWSymTab ()
|
|
{
|
|
if (symTblDelete (stid_) != OK)
|
|
vxwThrowErrno ();
|
|
}
|
|
|
|
//_ VXWSymTab Public Member Functions
|
|
|
|
///////////////////////////////////////////////////////////////////////////////
|
|
//
|
|
// VXWSymTab::add - create and add a symbol to a symbol table, including a group number
|
|
//
|
|
// This routine allocates a symbol <name> and adds it to its symbol
|
|
// table with the specified parameters <value>, <type>, and <group>.
|
|
// The <group> parameter specifies the group number assigned to a module when
|
|
// it is loaded on the target; see the manual entry for moduleLib.
|
|
//
|
|
// RETURNS: OK, or ERROR if there is insufficient memory for the symbol to be
|
|
// allocated.
|
|
//
|
|
// SEE ALSO: moduleLib
|
|
|
|
STATUS add (char *name, char *value, SYM_TYPE type, UINT16 group)
|
|
{
|
|
return symAdd (stid_, name, value, type, group);
|
|
}
|
|
|
|
///////////////////////////////////////////////////////////////////////////////
|
|
//
|
|
// VXWSymTab::each - call a routine to examine each entry in a symbol table
|
|
//
|
|
// This routine calls a user-supplied routine to examine each entry in the
|
|
// symbol table; it calls the specified routine once for each entry. The
|
|
// routine must have the following type signature:
|
|
// .CS
|
|
// BOOL routine
|
|
// (
|
|
// char * name, /@ entry name @/
|
|
// int val, /@ value associated with entry @/
|
|
// SYM_TYPE type, /@ entry type @/
|
|
// int arg, /@ arbitrary user-supplied arg @/
|
|
// UINT16 group /@ group number @/
|
|
// )
|
|
// .CE
|
|
// The user-supplied routine must return TRUE if VXWSymTab::each() is to
|
|
// continue calling it for each entry, or FALSE if it is done and
|
|
// VXWSymTab::each() can exit.
|
|
//
|
|
// RETURNS: A pointer to the last symbol reached, or NULL if all symbols are
|
|
// reached.
|
|
|
|
SYMBOL * each (FUNCPTR routine, int routineArg)
|
|
{
|
|
return symEach (stid_, routine, routineArg);
|
|
}
|
|
|
|
///////////////////////////////////////////////////////////////////////////////
|
|
//
|
|
// VXWSymTab::findByName - look up a symbol by name
|
|
//
|
|
// This routine searches its symbol table for a symbol matching a specified
|
|
// name. If the symbol is found, its value and type are copied to <pValue>
|
|
// and <pType>. If multiple symbols have the same name but differ in type,
|
|
// the routine chooses the matching symbol most recently added to the symbol
|
|
// table.
|
|
//
|
|
// RETURNS: OK, or ERROR if the symbol cannot be found.
|
|
|
|
STATUS findByName (char *name, char **pValue, SYM_TYPE *pType) const
|
|
{
|
|
return symFindByName (stid_, name, pValue, pType);
|
|
}
|
|
|
|
///////////////////////////////////////////////////////////////////////////////
|
|
//
|
|
// VXWSymTab::findByNameAndType - look up a symbol by name and type
|
|
//
|
|
// This routine searches its symbol table for a symbol matching both name and
|
|
// type (<name> and <goalType>). If the symbol is found, its value and type are
|
|
// copied to <pValue> and <pType>. The <mask> parameter can be used to match
|
|
// sub-classes of type.
|
|
//
|
|
// RETURNS: OK, or ERROR if the symbol is not found.
|
|
|
|
STATUS findByNameAndType (char *name, char **pValue, SYM_TYPE *pType,
|
|
SYM_TYPE goalType, SYM_TYPE mask) const
|
|
{
|
|
return symFindByNameAndType (stid_, name, pValue,
|
|
pType, goalType, mask);
|
|
}
|
|
|
|
///////////////////////////////////////////////////////////////////////////////
|
|
//
|
|
// VXWSymTab::findByValue - look up a symbol by value
|
|
//
|
|
// This routine searches its symbol table for a symbol matching a specified
|
|
// value. If there is no matching entry, it chooses the table entry with the
|
|
// next lower value. The symbol name (with terminating EOS), the actual
|
|
// value, and the type are copied to <name>, <pValue>, and <pType>.
|
|
//
|
|
// RETURNS: OK, or ERROR if <value> is less than the lowest value in the table.
|
|
|
|
STATUS findByValue (UINT value, char *name, int *pValue,
|
|
SYM_TYPE *pType) const
|
|
{
|
|
return symFindByValue (stid_, value, name, pValue, pType);
|
|
}
|
|
|
|
///////////////////////////////////////////////////////////////////////////////
|
|
//
|
|
// VXWSymTab::findByValueAndType - look up a symbol by value and type
|
|
//
|
|
// This routine searches a symbol table for a symbol matching both
|
|
// value and type (<value> and <goalType>). If there is no matching
|
|
// entry, it chooses the table entry with the next lower value. The
|
|
// symbol name (with terminating EOS), the actual value, and the type
|
|
// are copied to <name>, <pValue>, and <pType>. The <mask> parameter
|
|
// can be used to match sub-classes of type.
|
|
//
|
|
// RETURNS: OK, or ERROR if <value> is less than the lowest value in the table.
|
|
|
|
STATUS findByValueAndType (UINT value, char *name, int *pValue,
|
|
SYM_TYPE *pType, SYM_TYPE goalType,
|
|
SYM_TYPE mask) const
|
|
{
|
|
return symFindByValueAndType (stid_, value, name, pValue,
|
|
pType, goalType, mask);
|
|
}
|
|
|
|
///////////////////////////////////////////////////////////////////////////////
|
|
//
|
|
// VXWSymTab::remove - remove a symbol from a symbol table
|
|
//
|
|
// This routine removes a symbol of matching name and type from
|
|
// its symbol table. The symbol is deallocated if found.
|
|
// Note that VxWorks symbols in a standalone VxWorks image (where the
|
|
// symbol table is linked in) cannot be removed.
|
|
//
|
|
// RETURNS: OK, or ERROR if the symbol is not found
|
|
// or could not be deallocated.
|
|
|
|
STATUS remove (char *name, SYM_TYPE type)
|
|
{
|
|
return symRemove (stid_, name, type);
|
|
}
|
|
|
|
protected:
|
|
VXWSymTab ()
|
|
{
|
|
}
|
|
VXWSymTab (const VXWSymTab &)
|
|
{
|
|
}
|
|
VXWSymTab & operator = (const VXWSymTab &)
|
|
{
|
|
return *this;
|
|
}
|
|
virtual void * myValue ();
|
|
SYMTAB_ID stid_;
|
|
};
|
|
|
|
#endif /* ifndef vxwSymLib_h */
|