balst_resolverimpl_xcoff.h

Go to the documentation of this file.

/// @file balst_resolverimpl_xcoff.h
///
/// The content of this file has been pre-processed for Doxygen.
///
 
 
// balst_resolverimpl_xcoff.h                                         -*-C++-*-
#ifndef INCLUDED_BALST_RESOLVERIMPL_XCOFF
#define INCLUDED_BALST_RESOLVERIMPL_XCOFF
 
#include <bsls_ident.h>
BSLS_IDENT("$Id: $")
 
/// @defgroup balst_resolverimpl_xcoff balst_resolverimpl_xcoff
/// @brief  Provide a mechanism to resolve xcoff symbols in a stack trace.
/// @addtogroup bal
/// @{
/// @addtogroup balst
/// @{
/// @addtogroup balst_resolverimpl_xcoff
/// @{
///
/// <h1> Outline </h1>
/// * <a href="#balst_resolverimpl_xcoff-purpose"> Purpose</a>
/// * <a href="#balst_resolverimpl_xcoff-classes"> Classes </a>
/// * <a href="#balst_resolverimpl_xcoff-description"> Description </a>
///   * <a href="#balst_resolverimpl_xcoff-inline-functions"> Inline Functions </a>
///   * <a href="#balst_resolverimpl_xcoff-usage"> Usage </a>
///
/// # Purpose {#balst_resolverimpl_xcoff-purpose}
/// Provide a mechanism to resolve xcoff symbols in a stack trace.
///
/// # Classes {#balst_resolverimpl_xcoff-classes}
///
/// -   balst::ResolverImpl<Xcoff>: symbol resolution for Xcoff objects
///
/// @see  balst_resolverimpl_elf,
///           balst_resolverimpl_windows
///
/// # Description {#balst_resolverimpl_xcoff-description}
/// This component provides a class,
/// `balst::Resolver<Xcoff>`, that, given a vector of `balst::StackTraceFrame`s
/// that have only their `address` fields set, resolves all other fields in
/// those frames.  Xcoff objects are used on AIX platforms.
///
/// ## Inline Functions {#balst_resolverimpl_xcoff-inline-functions}
///
///
/// Inline functions and template functions that are, in fact, called out of
/// line are handled properly.  Functions that are inlined are not represented
/// in the stack trace, and the stack frames of the functions that called them
/// do not have their line number information populated.
///
/// ## Usage {#balst_resolverimpl_xcoff-usage}
///
///
/// This component is an implementation detail of `balst` and is *not* intended
/// for direct client use.  It is subject to change without notice.  As such, a
/// usage example is not provided.
/// @}
/** @} */
/** @} */
 
/** @addtogroup bal
 * @{
 */
/** @addtogroup balst
 * @{
 */
/** @addtogroup balst_resolverimpl_xcoff
 * @{
 */
 
#include <balscm_version.h>
 
#include <balst_objectfileformat.h>
 
#if defined(BALST_OBJECTFILEFORMAT_RESOLVER_XCOFF)
#include <balst_stacktrace.h>
#include <balst_stacktraceframe.h>
#include <balst_resolver_filehelper.h>
 
#include <bdlma_heapbypassallocator.h>
 
#include <bdls_filesystemutil.h>
 
#include <bslma_allocator.h>
 
#include <bslmt_qlock.h>
 
#include <bsls_assert.h>
#include <bsls_types.h>
 
 
struct syment;    // defined in imp by included file '<syms.h>'
union  auxent;    // defined in imp by included file '<syms.h>'
 
 
namespace balst {
 
template <typename RESOLVER_POLICY>
class ResolverImpl;
 
                   // ===========================================
                   // class ResolverImpl<ObjectFileFormat::Xcoff>
                   // ===========================================
 
template <>
class ResolverImpl<ObjectFileFormat::Xcoff> {
    // This class is for resolving symbols in Xcoff executables.  Given a
    // vector of 'StackTraceFrame's that have only their 'address' fields
    // set, it resolves all other fields in those frames.  Xcoff objects are
    // used on AIX platforms.  Note that all methods, including the
    // constructor, are private except for that static method 'resolve' which
    // constructs and destroys the object.
 
  public:
    // PUBLIC TYPES
    typedef bsls::Types::IntPtr  IntPtr;  // 32 bit signed on 32 bit, 64 bit
                                          // signed on 64 bit
    typedef bsls::Types::UintPtr UintPtr; // 32 bit unsigned on 32 bit, 64 bit
                                          // unsigned on 64 bit
 
    typedef bsls::Types::Int64   Int64;
    typedef bsls::Types::Uint64  Uint64;
 
    typedef bdls::FilesystemUtil::Offset  // Usually used for offsets in a
                                 Offset;  // file, absolute or relative.
 
  private:
    // TYPES
    struct AuxInfo;                       // Internal -- fleshed out in the
                                          // implementation file
    struct LoadAuxInfosInfo;              // Internal -- fleshed out in the
                                          // implementation file
 
    enum FindIncludeFileFlags {
        // flags returned by 'findIncludeFile'
 
        k_USE_INCLUDE_SOURCE_FILE_NAME = 0x1,
        k_SUPPRESS_LINE_NUMBER         = 0x2
    };
 
    // DATA
    Resolver_FileHelper   *d_helper;          // helper for reading files
 
    StackTrace            *d_stackTrace_p;    // pointer to stack trace object
                                              // to be populated by resolution.
                                              // Note only the 'address' fields
                                              // are initialized at the start,
                                              // our goal is to initialize all
                                              // the other fields.  Held, not
                                              // owned.
 
    StackTraceFrame      **d_segFramePtrs_p;  // pointers to stack trace frames
                                              // contained in 'd_stackTrace_p'
                                              // listing only those frames
                                              // whose 'address' fields point
                                              // into the current segment
 
    const void           **d_segAddresses_p;  // the 'address' fields from
                                              // 'd_segFramePtrs_p' in 1-1
                                              // correspondence, note this
                                              // duplication of information is
                                              // a performance optimization
 
    AuxInfo               *d_segAuxInfos_p;   // array of aux infos (AuxInfo is
                                              // a struct private to this
                                              // class, defined in the imp) in
                                              // 1-1 correspondence with the
                                              // entries of 'd_segFramePtrs_p'
 
    int                    d_numCurrAddresses;// number of 'address' fields in
                                              // 'd_stackTrace_p' that point
                                              // into the current segment, also
                                              // the length of
                                              // 'd_segFramePtrs_p',
                                              // 'd_segAddresses_p', and
                                              // 'd_segAuxInfos_p', note all 3
                                              // are allocated to have
                                              // 'd_stackTrace_p->length()'
                                              // (worst case) length
 
    char                  *d_scratchBuf_p;    // scratch buffer
 
    char                  *d_symbolBuf_p;     // buffer for reading symbols
 
    Offset                 d_virtualToPhysicalOffset;
                                              // translation from an address
                                              // given in the file to an
                                              // address in memory for the
                                              // current segment
 
    Offset                 d_archiveMemberOffset;
                                              // archive member offset, or 0 if
                                              // the segment is not an archive
                                              // member
 
    Offset                 d_archiveMemberSize;
                                              // archive member size, or size
                                              // of the whole file if the
                                              // segment is not an archive
                                              // member
 
    Offset                 d_symTableOffset;  // absolute offset of symbol
                                              // table in the current file
 
    Offset                 d_stringTableOffset;
                                              // absolute offset of string
                                              // table in the current file
 
    bool                   d_demangle;        // flag indicating whether
                                              // demangling is to be done
 
    bdlma::HeapBypassAllocator
                           d_hbpAlloc;        // heap bypass allocator, all
                                              // memory allocated by this
                                              // object will be freed when this
                                              // allocator is destroyed.
 
    static bslmt::QLock    s_demangleQLock;   // 'QLock' to guard access to
                                              // the non-thread-safe 'Demangle'
                                              // function.
 
  private:
    // NOT IMPLEMENTED
    ResolverImpl(const ResolverImpl&);
    ResolverImpl& operator=(const ResolverImpl&);
 
    // PRIVATE CREATORS
    ResolverImpl(StackTrace *stackTrace,
                 bool        demangle);
        // Create an stack trace reolver that can populate other fields of the
        // specified 'stackFrames' object given previously populated 'address'
        // fields.  Specify 'demangle', which indicates whether demangling of
        // symbols is to occur, and 'basicAllocator', which is to be used for
        // memory allocation.  Note that the behavior is undefined if
        // 'basicAllocator' is 0 or unspecified, the intention is that it
        // should be of type 'bdema::HeapByPassAllocator'.
 
    ~ResolverImpl();
        // Destroy this stack trace resolver object.
 
    // PRIVATE MANIPULATORS
    bslma::Allocator *allocator();
        // Return a pointer to this object's heap bypass allocator.
 
    int findArchiveMember(const char *memberName);
        // Locate the archive member with the specified 'memberName' in the
        // current archive file and save the member's offset from the beginning
        // of the archive and the member's size.  Return zero on success, and a
        // negative value otherwise.  Note that this is never called on an
        // executable, only on archives.
 
    Offset findCsectIndex(const char *symbolAddress,
                          const char *csectEndAddress,
                          Offset      primarySymIndex);
        // Iterate through all the addresses in d_segAddresses_p, returning the
        // specified 'primarySymIndex', which is the index of the current
        // symbol, if any of them are in the range
        // '[symbolAddress, csectEndAddress)' and 'UintPtr(-1)' otherwise.
 
    int findIncludeFile(syment  *includeSymEnt,
                        Offset   firstLineNumberOffset,
                        Offset   lineNumberOffset,
                        Offset   symStartIndex,
                        Offset   symEndIndex);
        // Read the portion of the symbol table of the current segment starting
        // at the specified 'symStartIndex' and ending at the specified
        // 'symEndIndex' to determine if the specified 'lineNumberOffset' is in
        // an include file.  Return a positive value which is a bitwise or of
        // the appropriate 'FindIncludeFileFlags' if found, 0 if not found, and
        // a negative value if an error is encountered.  The positive value
        // returned on success is a bitwise or of the flags defined by enum
        // 'FindIncludeFileFlags' defined in the class, indicating whether the
        // file was found, and whether the line number we have (which is not
        // passed to this routine) is absolute or relative.  Note that the line
        // numbers corresponding to include files are sometimes absolute, while
        // other line numbers are relative to the beginning of the function in
        // which they occur.  Also note that this routine is called immediately
        // after 'findLineNumber'.
 
    int findLineNumber(int        *outLineNumber_p,
                       Offset     *outLineNumberOffset_p,
                       Offset      lineBufStartOffset,
                       const void *segAddress);
        // Find a line number and line number offset of the source that refers
        // to the specified 'address', and load the results into the specified
        // '*outLineNumber_p' and '*outLineNumberOffset_p'.  Begin the search
        // at the specified 'lineBufStartOffset' in the file and end either at
        // the end of that function, at the end of the archive member, or the
        // end of the file.  Return zero on success, and a nonzero value
        // otherwise.  Note that the line number may be either relative to the
        // beginning of the function, or absolute (see 'findIncludeFile').
        // Note that 'lineBufStartOffset' points to the beginning of line
        // number records describing the function containing the code
        // 'segAddress' refers to.
 
    void loadAuxInfos(const LoadAuxInfosInfo *laiInfo,
                      const char             *functionBeginAddress,
                      const char             *functionEndAddress);
        // Iterate through 'd_segAddresses_p' and, for each address that refers
        // to code in the function specified by 'functionBeginAddress' and
        // 'functionEndAddress', initialize the 'offsetFromSymbol' field of the
        // corresponding stack trace frame, and initialize the corresponding
        // 'AuxInfo' struct with information from variables local to the
        // calling 'loadSymbols' function accessed through pointers in the
        // specified 'laiInfo' struct.
 
    int loadSymbols(Offset numSyms,
                    int    textSectionNum);
        // Read the specified 'numSym' symbols from the symbol table associated
        // with this segment, skipping those symbols not associated with the
        // text section indicated by the specified 'textSectionNum'.  Return 0
        // on success and a non-zero value otherwise.
 
    const char *getSourceName(const auxent *sourceAuxent);
        // Allocate memory for, and return a pointer to, a string containing
        // the name of the source file referred to by the specified
        // 'sourceAuxent'.
 
    const char *getSymbolName(const syment *sourceSyment);
        // Allocate memory for, and return a pointer to, a string containing
        // the name of the symbol defined by the specified 'sourceSyment'.
        // Note the symbol is sometimes a function name, sometimes a source
        // file name.
 
    int resolveSegment(void       *segmentPtr,
                       UintPtr     segmentSize,
                       const char *libraryFileName,
                       const char *displayFileName,
                       const char *archiveMemberName);
        // Populate those stack trace frames whose 'address' fields reside
        // within the segment specfied by 'segmentPtr' and 'segmentSize'.  The
        // segment is in the specified 'libraryFileName', with the specified
        // 'archiveMemberName'.  Specify the 'displayFileName' used to identify
        // the library file name in the stack trace.  Note that
        // 'displayFileName' may be different from 'libraryFileName' because
        // AIX truncates the filename of the executable file to be 32 chars
        // long, so we use another means to open the executable file.  Note
        // that if 'archiveMemberName' is unspecified, the whole library file
        // has a single segment.
 
  public:
    // PUBLIC CLASS METHODS
    static
    int resolve(StackTrace *stackTrace,
                bool        demangle);
        // Populate information for the specified 'stackFrames', a vector of
        // stack trace frames in a stack trace object.  Specify 'demangle', to
        // determine whether demangling is to occur, and 'basicAllocator',
        // which is to be used for memory allocation.  The behavior is
        // undefined unless all the 'address' field in 'stackFrames' are valid
        // and other fields are invalid, and 'basicAllocator != 0'.
 
    static inline
    int testFunc();
        // For testing only.  Do some random garbage and return a line number
        // from within the routine.
};
 
// ============================================================================
//                        INLINE FUNCTION DEFINITIONS
// ============================================================================
 
                              // ------------------
                              // class ResolverImpl
                              // ------------------
 
// PRIVATE MANIPULATORS
inline
bslma::Allocator *ResolverImpl<ObjectFileFormat::Xcoff>::allocator()
{
    return &d_hbpAlloc;
}
 
// CLASS METHODS
inline
int ResolverImpl<ObjectFileFormat::Xcoff>::testFunc()
{
    // Do some random garbage to generate some code, then return a line number
    // within this routine
 
    int line = 0, lineCopy = 0;
 
    for (int i = 0; true; ++i) {
        BSLS_ASSERT_OPT(line == lineCopy);
 
        const int loopGuard = 0x8edf0000;    // garbage with a lot of trailing
                                             // 0's.
        const int mask      = 0xa72c3dca;    // pure garbage
 
        enum { k_LINE = __LINE__ };
 
        for (int i = 0; !(i & loopGuard); ++i) {
            line ^= (i & mask);
        }
 
        // The above loop will leave the value of 'line' unchanged.
 
        BSLS_ASSERT_OPT(line == lineCopy);
 
        if (line != 0) {
            break;
        }
 
        line = k_LINE;
        lineCopy = line;
    }
 
    return line;
}
 
}  // close package namespace
 
 
#endif
#endif
 
// ----------------------------------------------------------------------------
// Copyright 2015 Bloomberg Finance L.P.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// ----------------------------- END-OF-FILE ----------------------------------
 
/** @} */
/** @} */
/** @} */