source: trunk/kDbg/kDbgInternal.h@ 3536

/* $Id: kDbgInternal.h 3534 2007-08-23 00:28:15Z bird $ */
/** @file
 * kDbg - The Debug Info Reader, Internal Header.
 */

/*
 * Copyright (c) 2006-2007 knut st. osmundsen <bird-src-spam@anduin.net>
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with This program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *
 */

#ifndef ___kDbgInternal_h___
#define ___kDbgInternal_h___

#include "kDbgBase.h"
#include "kDbgHlp.h"
#include "kDbg.h"

#ifdef __cplusplus
extern "C" {
#endif


/**
 * The debug module method table.
 */
typedef struct KDBGMODOPS
{
    /** The name of the reader. */
    const char *pszName;

    /** Pointer to the next debug module readers.
     * This is only used for dynamically registered readers. */
    struct KDBGMODOPS  *pNext;

    /**
     * Tries to open the module.
     *
     * @returns 0 on success, KDBG_ERR on failure.
     * @param   pFile           The file
     * @param   off             The file offset of the debug info. This is 0 if there isn't
     *                          any specfic debug info section and the reader should start
     *                          looking for debug info at the start of the file.
     * @param   cb              The size of the debug info in the file. INT64_MAX if we don't
     *                          know or there isn't any particular debug info section in the file.
     * @param   pLdrMod         The associated loader module. This can be NULL.
     * @param   ppMod           Where to store the module that's been opened.
     *
     * @remark  This is NULL for the builtin readers.
     */
    int (*pfnOpen)(PKDBGHLPFILE pFile, int64_t off, int64_t cb, PKLDRMOD pLdrMod, PKDBGMOD pMod);

    /**
     * Closes the module.
     *
     * This should free all resources associated with the module
     * except the pMod which is freed by the caller.
     *
     * @returns IPRT status code.
     * @param   pMod        The module.
     */
    int (*pfnClose)(PKDBGMOD pMod);

    /**
     * Gets a symbol by segment:offset.
     * This will be approximated to the nearest symbol if there is no exact match.
     *
     * @returns 0 on success. KLDR_ERR_* on failure.
     * @param   pMod        The module.
     * @param   iSegment    The segment this offset is relative to.
     *                      The -1 segment is special, it means that the addres is relative to
     *                      the image base. The image base is where the first bit of the image
     *                      is mapped during load.
     * @param   off         The offset into the segment.
     * @param   pSym        Where to store the symbol details.
     */
    int (*pfnQuerySymbol)(PKDBGMOD pMod, int32_t iSegment, KDBGADDR off, PKDBGSYMBOL pSym);

    /**
     * Gets a line number entry by segment:offset.
     * This will be approximated to the nearest line number there is no exact match.
     *
     * @returns 0 on success. KLDR_ERR_* on failure.
     * @param   pMod        The module.
     * @param   iSegment    The segment this offset is relative to.
     *                      The -1 segment is special, it means that the addres is relative to
     *                      the image base. The image base is where the first bit of the image
     *                      is mapped during load.
     * @param   off         The offset into the segment.
     * @param   pLine       Where to store the line number details.
     */
    int (*pfnQueryLine)(PKDBGMOD pMod, int32_t iSegment, KDBGADDR uOffset, PKDBGLINE pLine);

} KDBGMODOPS;
/** Pointer to a module method table. */
typedef KDBGMODOPS *PKDBGMODOPS;
/** Pointer to a const module method table. */
typedef const KDBGMODOPS *PCKDBGMODOPS;


/**
 * Internal representation of a debug module.
 */
typedef struct KDBGMOD
{
    /** Magic value (KDBGMOD_MAGIC). */
    uint32_t        u32Magic;
    /** The handle to the module. (If closed, this is NIL_RTFILE.) */
    PKDBGHLPFILE    pFile;
    /** Pointer to the method table. */
    PCKDBGMODOPS    pOps;
} KDBGMOD;


/** The magic value for the debug module structure. (Some dead english writer) */
#define KDBGMOD_MAGIC      0x00000000
/** The magic value of a dead module structure. */
#define KDBGMOD_MAGIC_DEAD 0x00000001


int kdbgModPEOpen(PKDBGHLPFILE pFile, KDBGADDR offHdr, const char *pszModulePath, PKDBGMOD *ppDbgMod);
int kdbgModWinDbgHelpOpen(PKDBGHLPFILE pFile, const char *pszModulePath, PKDBGMOD *ppDbgMod);

#ifdef __cplusplus
}
#endif

#endif