[19509] | 1 | /* $Id: dbgmod.h 100931 2023-08-21 23:11:01Z vboxsync $ */
|
---|
| 2 | /** @file
|
---|
| 3 | * IPRT - Internal Header for RTDbgMod and the associated interpreters.
|
---|
| 4 | */
|
---|
| 5 |
|
---|
| 6 | /*
|
---|
[98103] | 7 | * Copyright (C) 2008-2023 Oracle and/or its affiliates.
|
---|
[19509] | 8 | *
|
---|
[96407] | 9 | * This file is part of VirtualBox base platform packages, as
|
---|
| 10 | * available from https://www.virtualbox.org.
|
---|
[19509] | 11 | *
|
---|
[96407] | 12 | * This program is free software; you can redistribute it and/or
|
---|
| 13 | * modify it under the terms of the GNU General Public License
|
---|
| 14 | * as published by the Free Software Foundation, in version 3 of the
|
---|
| 15 | * License.
|
---|
| 16 | *
|
---|
| 17 | * This program is distributed in the hope that it will be useful, but
|
---|
| 18 | * WITHOUT ANY WARRANTY; without even the implied warranty of
|
---|
| 19 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
---|
| 20 | * General Public License for more details.
|
---|
| 21 | *
|
---|
| 22 | * You should have received a copy of the GNU General Public License
|
---|
| 23 | * along with this program; if not, see <https://www.gnu.org/licenses>.
|
---|
| 24 | *
|
---|
[20513] | 25 | * The contents of this file may alternatively be used under the terms
|
---|
| 26 | * of the Common Development and Distribution License Version 1.0
|
---|
[96407] | 27 | * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
|
---|
| 28 | * in the VirtualBox distribution, in which case the provisions of the
|
---|
[20513] | 29 | * CDDL are applicable instead of those of the GPL.
|
---|
| 30 | *
|
---|
| 31 | * You may elect to license modified versions of this file under the
|
---|
| 32 | * terms and conditions of either the GPL or the CDDL or both.
|
---|
[96407] | 33 | *
|
---|
| 34 | * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
|
---|
[19509] | 35 | */
|
---|
| 36 |
|
---|
[76559] | 37 | #ifndef IPRT_INCLUDED_INTERNAL_dbgmod_h
|
---|
| 38 | #define IPRT_INCLUDED_INTERNAL_dbgmod_h
|
---|
[76513] | 39 | #ifndef RT_WITHOUT_PRAGMA_ONCE
|
---|
| 40 | # pragma once
|
---|
| 41 | #endif
|
---|
[19509] | 42 |
|
---|
| 43 | #include <iprt/types.h>
|
---|
[20355] | 44 | #include <iprt/critsect.h>
|
---|
[38515] | 45 | #include <iprt/ldr.h> /* for PFNRTLDRENUMDBG */
|
---|
[19509] | 46 | #include "internal/magics.h"
|
---|
| 47 |
|
---|
[20374] | 48 | RT_C_DECLS_BEGIN
|
---|
[19509] | 49 |
|
---|
[25645] | 50 | /** @addtogroup grp_rt_dbgmod
|
---|
[19509] | 51 | * @internal
|
---|
| 52 | * @{
|
---|
| 53 | */
|
---|
| 54 |
|
---|
| 55 |
|
---|
| 56 | /** Pointer to the internal module structure. */
|
---|
| 57 | typedef struct RTDBGMODINT *PRTDBGMODINT;
|
---|
| 58 |
|
---|
| 59 | /**
|
---|
| 60 | * Virtual method table for executable image interpreters.
|
---|
| 61 | */
|
---|
| 62 | typedef struct RTDBGMODVTIMG
|
---|
| 63 | {
|
---|
| 64 | /** Magic number (RTDBGMODVTIMG_MAGIC). */
|
---|
| 65 | uint32_t u32Magic;
|
---|
[38515] | 66 | /** Reserved. */
|
---|
| 67 | uint32_t fReserved;
|
---|
[19509] | 68 | /** The name of the interpreter. */
|
---|
| 69 | const char *pszName;
|
---|
| 70 |
|
---|
| 71 | /**
|
---|
| 72 | * Try open the image.
|
---|
| 73 | *
|
---|
| 74 | * This combines probing and opening.
|
---|
| 75 | *
|
---|
[20744] | 76 | * @returns IPRT status code. No informational returns defined.
|
---|
[19509] | 77 | *
|
---|
| 78 | * @param pMod Pointer to the module that is being opened.
|
---|
| 79 | *
|
---|
| 80 | * The RTDBGMOD::pszDbgFile member will point to
|
---|
| 81 | * the filename of any debug info we're aware of
|
---|
| 82 | * on input. Also, or alternatively, it is expected
|
---|
| 83 | * that the interpreter will look for debug info in
|
---|
| 84 | * the executable image file when present and that it
|
---|
| 85 | * may ask the image interpreter for this when it's
|
---|
| 86 | * around.
|
---|
| 87 | *
|
---|
| 88 | * Upon successful return the method is expected to
|
---|
[38515] | 89 | * initialize pImgOps and pvImgPriv.
|
---|
[46161] | 90 | * @param enmArch The desired architecture.
|
---|
[83084] | 91 | * @param fLdrFlags Extra loader flags (RTLDR_O_XXX).
|
---|
[19509] | 92 | */
|
---|
[85121] | 93 | DECLCALLBACKMEMBER(int, pfnTryOpen,(PRTDBGMODINT pMod, RTLDRARCH enmArch, uint32_t fLdrFlags));
|
---|
[19509] | 94 |
|
---|
| 95 | /**
|
---|
| 96 | * Close the interpreter, freeing all associated resources.
|
---|
| 97 | *
|
---|
| 98 | * The caller sets the pDbgOps and pvDbgPriv RTDBGMOD members
|
---|
| 99 | * to NULL upon return.
|
---|
| 100 | *
|
---|
| 101 | * @param pMod Pointer to the module structure.
|
---|
| 102 | */
|
---|
[85121] | 103 | DECLCALLBACKMEMBER(int, pfnClose,(PRTDBGMODINT pMod));
|
---|
[19509] | 104 |
|
---|
[38515] | 105 | /**
|
---|
| 106 | * Enumerate the debug info contained in the executable image.
|
---|
| 107 | *
|
---|
| 108 | * Identical to RTLdrEnumDbgInfo.
|
---|
| 109 | *
|
---|
| 110 | * @returns IPRT status code or whatever pfnCallback returns.
|
---|
| 111 | *
|
---|
[38531] | 112 | * @param pMod Pointer to the module structure.
|
---|
[38515] | 113 | * @param pfnCallback The callback function. Ignore the module
|
---|
| 114 | * handle argument!
|
---|
| 115 | * @param pvUser The user argument.
|
---|
| 116 | */
|
---|
[85121] | 117 | DECLCALLBACKMEMBER(int, pfnEnumDbgInfo,(PRTDBGMODINT pMod, PFNRTLDRENUMDBG pfnCallback, void *pvUser));
|
---|
[38515] | 118 |
|
---|
[38531] | 119 | /**
|
---|
[38547] | 120 | * Enumerate the segments in the executable image.
|
---|
| 121 | *
|
---|
| 122 | * Identical to RTLdrEnumSegments.
|
---|
| 123 | *
|
---|
| 124 | * @returns IPRT status code or whatever pfnCallback returns.
|
---|
| 125 | *
|
---|
| 126 | * @param pMod Pointer to the module structure.
|
---|
| 127 | * @param pfnCallback The callback function. Ignore the module
|
---|
| 128 | * handle argument!
|
---|
| 129 | * @param pvUser The user argument.
|
---|
| 130 | */
|
---|
[85121] | 131 | DECLCALLBACKMEMBER(int, pfnEnumSegments,(PRTDBGMODINT pMod, PFNRTLDRENUMSEGS pfnCallback, void *pvUser));
|
---|
[38547] | 132 |
|
---|
| 133 | /**
|
---|
[46113] | 134 | * Enumerates the symbols exported by the module.
|
---|
| 135 | *
|
---|
| 136 | * @returns iprt status code, which might have been returned by pfnCallback.
|
---|
| 137 | * @param pMod Pointer to the module structure.
|
---|
| 138 | * @param fFlags Flags indicating what to return and such.
|
---|
| 139 | * @param BaseAddress The image base addressto use when calculating the
|
---|
| 140 | * symbol values.
|
---|
| 141 | * @param pfnCallback The callback function which each symbol is to be fed
|
---|
| 142 | * to.
|
---|
| 143 | * @param pvUser User argument to pass to the enumerator.
|
---|
| 144 | */
|
---|
[85121] | 145 | DECLCALLBACKMEMBER(int, pfnEnumSymbols,(PRTDBGMODINT pMod, uint32_t fFlags, RTLDRADDR BaseAddress,
|
---|
| 146 | PFNRTLDRENUMSYMS pfnCallback, void *pvUser));
|
---|
[46113] | 147 |
|
---|
| 148 | /**
|
---|
[38547] | 149 | * Gets the size of the loaded image.
|
---|
| 150 | *
|
---|
| 151 | * Identical to RTLdrSize.
|
---|
| 152 | *
|
---|
| 153 | * @returns The size in bytes, RTUINTPTR_MAX on failure.
|
---|
| 154 | *
|
---|
| 155 | * @param pMod Pointer to the module structure.
|
---|
| 156 | */
|
---|
[85121] | 157 | DECLCALLBACKMEMBER(RTUINTPTR, pfnImageSize,(PRTDBGMODINT pMod));
|
---|
[38547] | 158 |
|
---|
| 159 | /**
|
---|
[38581] | 160 | * Converts a link address to a segment:offset address (RVA included).
|
---|
| 161 | *
|
---|
| 162 | * @returns IPRT status code.
|
---|
| 163 | *
|
---|
| 164 | * @param pMod Pointer to the module structure.
|
---|
| 165 | * @param LinkAddress The link address to convert.
|
---|
| 166 | * @param piSeg The segment index.
|
---|
| 167 | * @param poffSeg Where to return the segment offset.
|
---|
| 168 | */
|
---|
[85121] | 169 | DECLCALLBACKMEMBER(int, pfnLinkAddressToSegOffset,(PRTDBGMODINT pMod, RTLDRADDR LinkAddress,
|
---|
| 170 | PRTDBGSEGIDX piSeg, PRTLDRADDR poffSeg));
|
---|
[38581] | 171 |
|
---|
| 172 | /**
|
---|
[46149] | 173 | * Converts an image relative virtual address to a segment:offset.
|
---|
| 174 | *
|
---|
| 175 | * @returns IPRT status code.
|
---|
| 176 | *
|
---|
| 177 | * @param pMod Pointer to the loader module structure.
|
---|
| 178 | * @param Rva The RVA to convert.
|
---|
| 179 | * @param piSeg The segment index.
|
---|
| 180 | * @param poffSeg Where to return the segment offset.
|
---|
| 181 | */
|
---|
[85121] | 182 | DECLCALLBACKMEMBER(int, pfnRvaToSegOffset,(PRTDBGMODINT pMod, RTLDRADDR Rva, uint32_t *piSeg, PRTLDRADDR poffSeg));
|
---|
[46149] | 183 |
|
---|
| 184 | /**
|
---|
[38531] | 185 | * Creates a read-only mapping of a part of the image file.
|
---|
| 186 | *
|
---|
| 187 | * @returns IPRT status code and *ppvMap set on success.
|
---|
| 188 | *
|
---|
| 189 | * @param pMod Pointer to the module structure.
|
---|
[46149] | 190 | * @param iDbgInfo The debug info ordinal number if the request
|
---|
| 191 | * corresponds exactly to a debug info part from
|
---|
| 192 | * pfnEnumDbgInfo. Otherwise, pass UINT32_MAX.
|
---|
[38531] | 193 | * @param off The offset into the image file.
|
---|
| 194 | * @param cb The number of bytes to map.
|
---|
| 195 | * @param ppvMap Where to return the mapping address on success.
|
---|
[46149] | 196 | *
|
---|
| 197 | * @remarks Fixups will only be applied if @a iDbgInfo is specified.
|
---|
[38531] | 198 | */
|
---|
[85121] | 199 | DECLCALLBACKMEMBER(int, pfnMapPart,(PRTDBGMODINT pMod, uint32_t iDbgInfo, RTFOFF off, size_t cb, void const **ppvMap));
|
---|
[38531] | 200 |
|
---|
| 201 | /**
|
---|
| 202 | * Unmaps memory previously mapped by pfnMapPart.
|
---|
| 203 | *
|
---|
| 204 | * @returns IPRT status code, *ppvMap set to NULL on success.
|
---|
| 205 | *
|
---|
| 206 | * @param pMod Pointer to the module structure.
|
---|
| 207 | * @param cb The size of the mapping.
|
---|
| 208 | * @param ppvMap The mapping address on input, NULL on
|
---|
| 209 | * successful return.
|
---|
| 210 | */
|
---|
[85121] | 211 | DECLCALLBACKMEMBER(int, pfnUnmapPart,(PRTDBGMODINT pMod, size_t cb, void const **ppvMap));
|
---|
[38531] | 212 |
|
---|
[46161] | 213 | /**
|
---|
[46266] | 214 | * Reads data from the image file.
|
---|
| 215 | *
|
---|
| 216 | * @returns IPRT status code, *ppvMap set to NULL on success.
|
---|
| 217 | *
|
---|
| 218 | * @param pMod Pointer to the module structure.
|
---|
| 219 | * @param iDbgInfoHint The debug info ordinal number hint, pass UINT32_MAX
|
---|
| 220 | * if not know or sure.
|
---|
| 221 | * @param off The offset into the image file.
|
---|
| 222 | * @param pvBuf The buffer to read into.
|
---|
| 223 | * @param cb The number of bytes to read.
|
---|
| 224 | */
|
---|
[85121] | 225 | DECLCALLBACKMEMBER(int, pfnReadAt,(PRTDBGMODINT pMod, uint32_t iDbgInfoHint, RTFOFF off, void *pvBuf, size_t cb));
|
---|
[46266] | 226 |
|
---|
| 227 | /**
|
---|
[46164] | 228 | * Gets the image format.
|
---|
[46161] | 229 | *
|
---|
[46164] | 230 | * @returns Valid image format on success, RTLDRFMT_INVALID if not supported.
|
---|
[46161] | 231 | * @param pMod Pointer to the module structure.
|
---|
| 232 | */
|
---|
[85121] | 233 | DECLCALLBACKMEMBER(RTLDRFMT, pfnGetFormat,(PRTDBGMODINT pMod));
|
---|
[38531] | 234 |
|
---|
[46164] | 235 | /**
|
---|
| 236 | * Gets the image architecture.
|
---|
| 237 | *
|
---|
| 238 | * @returns Valid image architecutre on success, RTLDRARCH_WHATEVER if not
|
---|
| 239 | * supported.
|
---|
| 240 | * @param pMod Pointer to the module structure.
|
---|
| 241 | */
|
---|
[85121] | 242 | DECLCALLBACKMEMBER(RTLDRARCH, pfnGetArch,(PRTDBGMODINT pMod));
|
---|
[46164] | 243 |
|
---|
[49044] | 244 | /**
|
---|
| 245 | * Generic method for querying image properties.
|
---|
| 246 | *
|
---|
| 247 | * @returns IPRT status code.
|
---|
| 248 | * @param pMod Pointer to the module structure.
|
---|
[57944] | 249 | * @param enmProp The property to query.
|
---|
[49044] | 250 | * @param pvBuf Pointer to the return buffer.
|
---|
| 251 | * @param cbBuf The size of the return buffer.
|
---|
[73375] | 252 | * @param pcbRet How many bytes was actually returned. In the
|
---|
| 253 | * case of VERR_BUFFER_OVERFLOW this will contain
|
---|
| 254 | * the required buffer size. Optional.
|
---|
| 255 | * @sa RTLdrQueryPropEx
|
---|
[49044] | 256 | */
|
---|
[85121] | 257 | DECLCALLBACKMEMBER(int, pfnQueryProp,(PRTDBGMODINT pMod, RTLDRPROP enmProp, void *pvBuf, size_t cbBuf, size_t *pcbRet));
|
---|
[49044] | 258 |
|
---|
[73494] | 259 | /**
|
---|
| 260 | * Try use unwind information to unwind one frame.
|
---|
| 261 | *
|
---|
| 262 | * @returns IPRT status code. Last informational status from stack reader callback.
|
---|
| 263 | * @retval VERR_DBG_NO_UNWIND_INFO if the module contains no unwind information.
|
---|
| 264 | * @retval VERR_DBG_UNWIND_INFO_NOT_FOUND if no unwind information was found
|
---|
| 265 | * for the location given by iSeg:off.
|
---|
| 266 | *
|
---|
| 267 | * @param pMod Pointer to the module structure.
|
---|
| 268 | * @param iSeg The segment number of the program counter.
|
---|
| 269 | * @param off The offset into @a iSeg. Together with @a iSeg
|
---|
| 270 | * this corresponds to the RTDBGUNWINDSTATE::uPc
|
---|
| 271 | * value pointed to by @a pState.
|
---|
| 272 | * @param pState The unwind state to work.
|
---|
| 273 | *
|
---|
| 274 | * @sa RTLdrUnwindFrame, RTDbgModUnwindFrame
|
---|
| 275 | */
|
---|
[85121] | 276 | DECLCALLBACKMEMBER(int, pfnUnwindFrame,(PRTDBGMODINT pMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTDBGUNWINDSTATE pState));
|
---|
[73494] | 277 |
|
---|
[38515] | 278 | /** For catching initialization errors (RTDBGMODVTIMG_MAGIC). */
|
---|
| 279 | uint32_t u32EndMagic;
|
---|
[19509] | 280 | } RTDBGMODVTIMG;
|
---|
| 281 | /** Pointer to a const RTDBGMODVTIMG. */
|
---|
| 282 | typedef RTDBGMODVTIMG const *PCRTDBGMODVTIMG;
|
---|
| 283 |
|
---|
| 284 |
|
---|
| 285 | /**
|
---|
| 286 | * Virtual method table for debug info interpreters.
|
---|
| 287 | */
|
---|
| 288 | typedef struct RTDBGMODVTDBG
|
---|
| 289 | {
|
---|
| 290 | /** Magic number (RTDBGMODVTDBG_MAGIC). */
|
---|
| 291 | uint32_t u32Magic;
|
---|
| 292 | /** Mask of supported debug info types, see grp_rt_dbg_type.
|
---|
| 293 | * Used to speed up the search for a suitable interpreter. */
|
---|
| 294 | uint32_t fSupports;
|
---|
| 295 | /** The name of the interpreter. */
|
---|
| 296 | const char *pszName;
|
---|
| 297 |
|
---|
| 298 | /**
|
---|
| 299 | * Try open the image.
|
---|
| 300 | *
|
---|
| 301 | * This combines probing and opening.
|
---|
| 302 | *
|
---|
[20744] | 303 | * @returns IPRT status code. No informational returns defined.
|
---|
[19509] | 304 | *
|
---|
| 305 | * @param pMod Pointer to the module that is being opened.
|
---|
| 306 | *
|
---|
| 307 | * The RTDBGMOD::pszDbgFile member will point to
|
---|
| 308 | * the filename of any debug info we're aware of
|
---|
| 309 | * on input. Also, or alternatively, it is expected
|
---|
| 310 | * that the interpreter will look for debug info in
|
---|
| 311 | * the executable image file when present and that it
|
---|
| 312 | * may ask the image interpreter for this when it's
|
---|
| 313 | * around.
|
---|
| 314 | *
|
---|
| 315 | * Upon successful return the method is expected to
|
---|
| 316 | * initialize pDbgOps and pvDbgPriv.
|
---|
[46164] | 317 | * @param enmArch The desired architecture.
|
---|
[100931] | 318 | * @param hDbgCfg Optional DBG configuration handle, for loading
|
---|
| 319 | * additional external files and later logging debug file
|
---|
| 320 | * errors during load. Specifically this is to try deal
|
---|
| 321 | * with stuff like the Windows 2000 DBG files which
|
---|
| 322 | * contains a link to the PDB file with the actual symbol
|
---|
| 323 | * information.
|
---|
[19509] | 324 | */
|
---|
[100931] | 325 | DECLCALLBACKMEMBER(int, pfnTryOpen,(PRTDBGMODINT pMod, RTLDRARCH enmArch, RTDBGCFG hDbgCfg));
|
---|
[19509] | 326 |
|
---|
| 327 | /**
|
---|
| 328 | * Close the interpreter, freeing all associated resources.
|
---|
| 329 | *
|
---|
| 330 | * The caller sets the pDbgOps and pvDbgPriv RTDBGMOD members
|
---|
| 331 | * to NULL upon return.
|
---|
| 332 | *
|
---|
| 333 | * @param pMod Pointer to the module structure.
|
---|
| 334 | */
|
---|
[85121] | 335 | DECLCALLBACKMEMBER(int, pfnClose,(PRTDBGMODINT pMod));
|
---|
[19509] | 336 |
|
---|
[20744] | 337 |
|
---|
| 338 |
|
---|
[19509] | 339 | /**
|
---|
[20740] | 340 | * Converts an image relative virtual address address to a segmented address.
|
---|
| 341 | *
|
---|
| 342 | * @returns Segment index on success, NIL_RTDBGSEGIDX on failure.
|
---|
| 343 | * @param pMod Pointer to the module structure.
|
---|
| 344 | * @param uRva The image relative address to convert.
|
---|
| 345 | * @param poffSeg Where to return the segment offset. Optional.
|
---|
| 346 | */
|
---|
[85121] | 347 | DECLCALLBACKMEMBER(RTDBGSEGIDX, pfnRvaToSegOff,(PRTDBGMODINT pMod, RTUINTPTR uRva, PRTUINTPTR poffSeg));
|
---|
[20740] | 348 |
|
---|
[20756] | 349 | /**
|
---|
[33540] | 350 | * Image size when mapped if segments are mapped adjacently.
|
---|
[20756] | 351 | *
|
---|
| 352 | * For ELF, PE, and Mach-O images this is (usually) a natural query, for LX and
|
---|
| 353 | * NE and such it's a bit odder and the answer may not make much sense for them.
|
---|
| 354 | *
|
---|
| 355 | * @returns Image mapped size.
|
---|
| 356 | * @param pMod Pointer to the module structure.
|
---|
| 357 | */
|
---|
[85121] | 358 | DECLCALLBACKMEMBER(RTUINTPTR, pfnImageSize,(PRTDBGMODINT pMod));
|
---|
[20744] | 359 |
|
---|
| 360 |
|
---|
[20756] | 361 |
|
---|
[20740] | 362 | /**
|
---|
[20744] | 363 | * Adds a segment to the module (optional).
|
---|
| 364 | *
|
---|
| 365 | * @returns IPRT status code.
|
---|
| 366 | * @retval VERR_NOT_SUPPORTED if the interpreter doesn't support this feature.
|
---|
| 367 | * @retval VERR_DBG_SEGMENT_INDEX_CONFLICT if the segment index exists already.
|
---|
| 368 | *
|
---|
| 369 | * @param pMod Pointer to the module structure.
|
---|
| 370 | * @param uRva The segment image relative address.
|
---|
| 371 | * @param cb The segment size.
|
---|
| 372 | * @param pszName The segment name.
|
---|
| 373 | * @param cchName The length of the segment name.
|
---|
| 374 | * @param fFlags Segment flags.
|
---|
| 375 | * @param piSeg The segment index or NIL_RTDBGSEGIDX on input.
|
---|
| 376 | * The assigned segment index on successful return.
|
---|
| 377 | * Optional.
|
---|
| 378 | */
|
---|
[85121] | 379 | DECLCALLBACKMEMBER(int, pfnSegmentAdd,(PRTDBGMODINT pMod, RTUINTPTR uRva, RTUINTPTR cb, const char *pszName, size_t cchName,
|
---|
| 380 | uint32_t fFlags, PRTDBGSEGIDX piSeg));
|
---|
[20744] | 381 |
|
---|
| 382 | /**
|
---|
| 383 | * Gets the segment count.
|
---|
| 384 | *
|
---|
| 385 | * @returns Number of segments.
|
---|
| 386 | * @retval NIL_RTDBGSEGIDX if unknown.
|
---|
| 387 | *
|
---|
| 388 | * @param pMod Pointer to the module structure.
|
---|
| 389 | */
|
---|
[85121] | 390 | DECLCALLBACKMEMBER(RTDBGSEGIDX, pfnSegmentCount,(PRTDBGMODINT pMod));
|
---|
[20744] | 391 |
|
---|
| 392 | /**
|
---|
| 393 | * Gets information about a segment.
|
---|
| 394 | *
|
---|
| 395 | * @returns IPRT status code.
|
---|
| 396 | * @retval VERR_DBG_INVALID_SEGMENT_INDEX if iSeg is too high.
|
---|
| 397 | *
|
---|
| 398 | * @param pMod Pointer to the module structure.
|
---|
| 399 | * @param iSeg The segment.
|
---|
| 400 | * @param pSegInfo Where to store the segment information.
|
---|
| 401 | */
|
---|
[85121] | 402 | DECLCALLBACKMEMBER(int, pfnSegmentByIndex,(PRTDBGMODINT pMod, RTDBGSEGIDX iSeg, PRTDBGSEGMENT pSegInfo));
|
---|
[20744] | 403 |
|
---|
| 404 |
|
---|
| 405 |
|
---|
| 406 | /**
|
---|
[20355] | 407 | * Adds a symbol to the module (optional).
|
---|
| 408 | *
|
---|
[20744] | 409 | * @returns IPRT code.
|
---|
[20355] | 410 | * @retval VERR_NOT_SUPPORTED if the interpreter doesn't support this feature.
|
---|
| 411 | *
|
---|
| 412 | * @param pMod Pointer to the module structure.
|
---|
| 413 | * @param pszSymbol The symbol name.
|
---|
[20740] | 414 | * @param cchSymbol The length for the symbol name.
|
---|
[20355] | 415 | * @param iSeg The segment number (0-based). RTDBGMOD_SEG_RVA can be used.
|
---|
| 416 | * @param off The offset into the segment.
|
---|
[20740] | 417 | * @param cb The area covered by the symbol. 0 is fine.
|
---|
[25645] | 418 | * @param fFlags Flags.
|
---|
[20744] | 419 | * @param piOrdinal Where to return the symbol ordinal on success. If the
|
---|
| 420 | * interpreter doesn't do ordinals, this will be set to
|
---|
| 421 | * UINT32_MAX. Optional
|
---|
[20355] | 422 | */
|
---|
[85121] | 423 | DECLCALLBACKMEMBER(int, pfnSymbolAdd,(PRTDBGMODINT pMod, const char *pszSymbol, size_t cchSymbol,
|
---|
[20744] | 424 | uint32_t iSeg, RTUINTPTR off, RTUINTPTR cb, uint32_t fFlags,
|
---|
[85121] | 425 | uint32_t *piOrdinal));
|
---|
[20355] | 426 |
|
---|
| 427 | /**
|
---|
[20744] | 428 | * Gets the number of symbols in the module.
|
---|
| 429 | *
|
---|
| 430 | * This is used for figuring out the max value to pass to pfnSymbolByIndex among
|
---|
| 431 | * other things.
|
---|
| 432 | *
|
---|
| 433 | * @returns The number of symbols, UINT32_MAX if not known/supported.
|
---|
| 434 | *
|
---|
| 435 | * @param pMod Pointer to the module structure.
|
---|
| 436 | */
|
---|
[85121] | 437 | DECLCALLBACKMEMBER(uint32_t, pfnSymbolCount,(PRTDBGMODINT pMod));
|
---|
[20744] | 438 |
|
---|
| 439 | /**
|
---|
| 440 | * Queries symbol information by ordinal number.
|
---|
| 441 | *
|
---|
| 442 | * @returns IPRT status code.
|
---|
| 443 | * @retval VINF_SUCCESS on success, no informational status code.
|
---|
| 444 | * @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
|
---|
| 445 | * @retval VERR_NOT_SUPPORTED if lookup by ordinal is not supported.
|
---|
| 446 | * @retval VERR_SYMBOL_NOT_FOUND if there is no symbol at that index.
|
---|
| 447 | *
|
---|
| 448 | * @param pMod Pointer to the module structure.
|
---|
[20800] | 449 | * @param iOrdinal The symbol ordinal number.
|
---|
| 450 | * @param pSymInfo Where to store the symbol information.
|
---|
[20744] | 451 | */
|
---|
[85121] | 452 | DECLCALLBACKMEMBER(int, pfnSymbolByOrdinal,(PRTDBGMODINT pMod, uint32_t iOrdinal, PRTDBGSYMBOL pSymInfo));
|
---|
[20744] | 453 |
|
---|
| 454 | /**
|
---|
[19509] | 455 | * Queries symbol information by symbol name.
|
---|
| 456 | *
|
---|
[20744] | 457 | * @returns IPRT status code.
|
---|
[19509] | 458 | * @retval VINF_SUCCESS on success, no informational status code.
|
---|
[20744] | 459 | * @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
|
---|
[19509] | 460 | * @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
|
---|
| 461 | *
|
---|
| 462 | * @param pMod Pointer to the module structure.
|
---|
| 463 | * @param pszSymbol The symbol name.
|
---|
[20800] | 464 | * @param cchSymbol The length of the symbol name.
|
---|
| 465 | * @param pSymInfo Where to store the symbol information.
|
---|
[19509] | 466 | */
|
---|
[85121] | 467 | DECLCALLBACKMEMBER(int, pfnSymbolByName,(PRTDBGMODINT pMod, const char *pszSymbol, size_t cchSymbol, PRTDBGSYMBOL pSymInfo));
|
---|
[19509] | 468 |
|
---|
| 469 | /**
|
---|
| 470 | * Queries symbol information by address.
|
---|
| 471 | *
|
---|
[33540] | 472 | * The returned symbol is what the debug info interpreter considers the symbol
|
---|
[19509] | 473 | * most applicable to the specified address. This usually means a symbol with an
|
---|
| 474 | * address equal or lower than the requested.
|
---|
| 475 | *
|
---|
[20744] | 476 | * @returns IPRT status code.
|
---|
[19509] | 477 | * @retval VINF_SUCCESS on success, no informational status code.
|
---|
[20744] | 478 | * @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
|
---|
[19509] | 479 | * @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
|
---|
| 480 | *
|
---|
| 481 | * @param pMod Pointer to the module structure.
|
---|
[20740] | 482 | * @param iSeg The segment number (0-based) or RTDBGSEGIDX_ABS.
|
---|
[19509] | 483 | * @param off The offset into the segment.
|
---|
[41493] | 484 | * @param fFlags Symbol search flags, see RTDBGSYMADDR_FLAGS_XXX.
|
---|
[19509] | 485 | * @param poffDisp Where to store the distance between the specified address
|
---|
| 486 | * and the returned symbol. Optional.
|
---|
[20800] | 487 | * @param pSymInfo Where to store the symbol information.
|
---|
[19509] | 488 | */
|
---|
[85121] | 489 | DECLCALLBACKMEMBER(int, pfnSymbolByAddr,(PRTDBGMODINT pMod, uint32_t iSeg, RTUINTPTR off, uint32_t fFlags,
|
---|
| 490 | PRTINTPTR poffDisp, PRTDBGSYMBOL pSymInfo));
|
---|
[19509] | 491 |
|
---|
[20744] | 492 |
|
---|
| 493 |
|
---|
[19509] | 494 | /**
|
---|
[20740] | 495 | * Adds a line number to the module (optional).
|
---|
| 496 | *
|
---|
[20744] | 497 | * @returns IPRT status code.
|
---|
[20740] | 498 | * @retval VERR_NOT_SUPPORTED if the interpreter doesn't support this feature.
|
---|
| 499 | *
|
---|
| 500 | * @param pMod Pointer to the module structure.
|
---|
| 501 | * @param pszFile The filename.
|
---|
| 502 | * @param cchFile The length of the filename.
|
---|
[25645] | 503 | * @param uLineNo The line number.
|
---|
[20740] | 504 | * @param iSeg The segment number (0-based).
|
---|
| 505 | * @param off The offset into the segment.
|
---|
[20744] | 506 | * @param piOrdinal Where to return the line number ordinal on success. If
|
---|
| 507 | * the interpreter doesn't do ordinals, this will be set to
|
---|
| 508 | * UINT32_MAX. Optional
|
---|
[20740] | 509 | */
|
---|
[85121] | 510 | DECLCALLBACKMEMBER(int, pfnLineAdd,(PRTDBGMODINT pMod, const char *pszFile, size_t cchFile, uint32_t uLineNo,
|
---|
| 511 | uint32_t iSeg, RTUINTPTR off, uint32_t *piOrdinal));
|
---|
[20740] | 512 |
|
---|
| 513 | /**
|
---|
[20744] | 514 | * Gets the number of line numbers in the module.
|
---|
| 515 | *
|
---|
| 516 | * @returns The number or UINT32_MAX if not known/supported.
|
---|
| 517 | *
|
---|
| 518 | * @param pMod Pointer to the module structure.
|
---|
| 519 | */
|
---|
[85121] | 520 | DECLCALLBACKMEMBER(uint32_t, pfnLineCount,(PRTDBGMODINT pMod));
|
---|
[20744] | 521 |
|
---|
| 522 | /**
|
---|
| 523 | * Queries line number information by ordinal number.
|
---|
| 524 | *
|
---|
| 525 | * @returns IPRT status code.
|
---|
| 526 | * @retval VINF_SUCCESS on success, no informational status code.
|
---|
| 527 | * @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
|
---|
| 528 | * @retval VERR_DBG_LINE_NOT_FOUND if there is no line number with that
|
---|
| 529 | * ordinal.
|
---|
| 530 | *
|
---|
| 531 | * @param pMod Pointer to the module structure.
|
---|
| 532 | * @param iOrdinal The line number ordinal number.
|
---|
[20801] | 533 | * @param pLineInfo Where to store the information about the line number.
|
---|
[20744] | 534 | */
|
---|
[85121] | 535 | DECLCALLBACKMEMBER(int, pfnLineByOrdinal,(PRTDBGMODINT pMod, uint32_t iOrdinal, PRTDBGLINE pLineInfo));
|
---|
[20744] | 536 |
|
---|
| 537 | /**
|
---|
[19509] | 538 | * Queries line number information by address.
|
---|
| 539 | *
|
---|
[20744] | 540 | * @returns IPRT status code.
|
---|
[19509] | 541 | * @retval VINF_SUCCESS on success, no informational status code.
|
---|
[20744] | 542 | * @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
|
---|
| 543 | * @retval VERR_DBG_LINE_NOT_FOUND if no suitable line number was found.
|
---|
[19509] | 544 | *
|
---|
| 545 | * @param pMod Pointer to the module structure.
|
---|
[20740] | 546 | * @param iSeg The segment number (0-based) or RTDBGSEGIDX_ABS.
|
---|
[19509] | 547 | * @param off The offset into the segment.
|
---|
| 548 | * @param poffDisp Where to store the distance between the specified address
|
---|
| 549 | * and the returned line number. Optional.
|
---|
[20801] | 550 | * @param pLineInfo Where to store the information about the closest line
|
---|
| 551 | * number.
|
---|
[19509] | 552 | */
|
---|
[85121] | 553 | DECLCALLBACKMEMBER(int, pfnLineByAddr,(PRTDBGMODINT pMod, uint32_t iSeg, RTUINTPTR off,
|
---|
| 554 | PRTINTPTR poffDisp, PRTDBGLINE pLineInfo));
|
---|
[19509] | 555 |
|
---|
[73494] | 556 | /**
|
---|
| 557 | * Try use unwind information to unwind one frame.
|
---|
| 558 | *
|
---|
| 559 | * @returns IPRT status code. Last informational status from stack reader callback.
|
---|
| 560 | * @retval VERR_DBG_NO_UNWIND_INFO if the module contains no unwind information.
|
---|
| 561 | * @retval VERR_DBG_UNWIND_INFO_NOT_FOUND if no unwind information was found
|
---|
| 562 | * for the location given by iSeg:off.
|
---|
| 563 | *
|
---|
| 564 | * @param pMod Pointer to the module structure.
|
---|
| 565 | * @param iSeg The segment number of the program counter.
|
---|
| 566 | * @param off The offset into @a iSeg. Together with @a iSeg
|
---|
| 567 | * this corresponds to the RTDBGUNWINDSTATE::uPc
|
---|
| 568 | * value pointed to by @a pState.
|
---|
| 569 | * @param pState The unwind state to work.
|
---|
| 570 | *
|
---|
| 571 | * @sa RTDbgModUnwindFrame
|
---|
| 572 | */
|
---|
[85121] | 573 | DECLCALLBACKMEMBER(int, pfnUnwindFrame,(PRTDBGMODINT pMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTDBGUNWINDSTATE pState));
|
---|
[20744] | 574 |
|
---|
[19509] | 575 | /** For catching initialization errors (RTDBGMODVTDBG_MAGIC). */
|
---|
| 576 | uint32_t u32EndMagic;
|
---|
| 577 | } RTDBGMODVTDBG;
|
---|
| 578 | /** Pointer to a const RTDBGMODVTDBG. */
|
---|
| 579 | typedef RTDBGMODVTDBG const *PCRTDBGMODVTDBG;
|
---|
| 580 |
|
---|
| 581 |
|
---|
| 582 | /**
|
---|
[45994] | 583 | * Deferred loading callback.
|
---|
| 584 | *
|
---|
| 585 | * @returns IPRT status code. On success the necessary method tables should be
|
---|
| 586 | * installed in @a pMod.
|
---|
[57944] | 587 | * @param pDbgMod Pointer to the debug module structure.
|
---|
[45994] | 588 | * @param pDeferred The deferred load data.
|
---|
| 589 | */
|
---|
[85121] | 590 | typedef DECLCALLBACKTYPE(int, FNRTDBGMODDEFERRED,(PRTDBGMODINT pDbgMod, struct RTDBGMODDEFERRED *pDeferred));
|
---|
[45994] | 591 | /** Pointer to a deferred loading callback. */
|
---|
| 592 | typedef FNRTDBGMODDEFERRED *PFNRTDBGMODDEFERRED;
|
---|
| 593 |
|
---|
| 594 |
|
---|
| 595 | /**
|
---|
| 596 | * Structure pointed to by pvDbgPriv and/or pvImgPriv when
|
---|
| 597 | * g_rtDbgModVtDbgDeferred and/or g_rtDbgModVtImgDeferred are being used.
|
---|
| 598 | */
|
---|
| 599 | typedef struct RTDBGMODDEFERRED
|
---|
| 600 | {
|
---|
[73412] | 601 | /** Magic value (RTDBGMODDEFERRED_MAGIC). */
|
---|
| 602 | uint32_t u32Magic;
|
---|
| 603 | /** Reference counter. */
|
---|
| 604 | uint32_t volatile cRefs;
|
---|
[83084] | 605 | /** RTDBGMOD_F_XXX */
|
---|
| 606 | uint32_t fFlags;
|
---|
[45994] | 607 | /** The image size.
|
---|
| 608 | * Deferred loading is almost pointless without knowing the module size, as
|
---|
| 609 | * it cannot be mapped (correctly) without it. */
|
---|
| 610 | RTUINTPTR cbImage;
|
---|
| 611 | /** The configuration instance (referenced), can be NIL. */
|
---|
| 612 | RTDBGCFG hDbgCfg;
|
---|
| 613 | /** Performs deferred loading of the module. */
|
---|
| 614 | PFNRTDBGMODDEFERRED pfnDeferred;
|
---|
| 615 | /** Callback specific data. */
|
---|
| 616 | union
|
---|
| 617 | {
|
---|
| 618 | struct
|
---|
| 619 | {
|
---|
| 620 | /** The time/date stamp of the executable image and codeview file. */
|
---|
| 621 | uint32_t uTimestamp;
|
---|
| 622 | } PeImage,
|
---|
| 623 | OldCodeView;
|
---|
| 624 |
|
---|
| 625 | struct
|
---|
| 626 | {
|
---|
| 627 | /** The PDB uuid. */
|
---|
| 628 | RTUUID Uuid;
|
---|
| 629 | /** The PDB age. */
|
---|
| 630 | uint32_t uAge;
|
---|
| 631 | } NewCodeview;
|
---|
| 632 |
|
---|
| 633 | struct
|
---|
| 634 | {
|
---|
| 635 | /** The CRC-32 value found in the .gnu_debuglink section. */
|
---|
| 636 | uint32_t uCrc32;
|
---|
| 637 | } GnuDebugLink;
|
---|
[49044] | 638 |
|
---|
| 639 | struct
|
---|
| 640 | {
|
---|
| 641 | /** The image UUID. */
|
---|
| 642 | RTUUID Uuid;
|
---|
| 643 | /** Image architecture. */
|
---|
| 644 | RTLDRARCH enmArch;
|
---|
| 645 | /** Number of segment mappings. */
|
---|
| 646 | uint32_t cSegs;
|
---|
| 647 | /** Segment mappings. */
|
---|
| 648 | RTDBGSEGMENT aSegs[1];
|
---|
| 649 | } MachO;
|
---|
[45994] | 650 | } u;
|
---|
| 651 | } RTDBGMODDEFERRED;
|
---|
| 652 | /** Pointer to the deferred loading data. */
|
---|
| 653 | typedef RTDBGMODDEFERRED *PRTDBGMODDEFERRED;
|
---|
| 654 |
|
---|
| 655 |
|
---|
| 656 | /**
|
---|
[19509] | 657 | * Debug module structure.
|
---|
| 658 | */
|
---|
[19559] | 659 | typedef struct RTDBGMODINT
|
---|
[19509] | 660 | {
|
---|
| 661 | /** Magic value (RTDBGMOD_MAGIC). */
|
---|
[20355] | 662 | uint32_t u32Magic;
|
---|
| 663 | /** The number of reference there are to this module.
|
---|
[19509] | 664 | * This is used to perform automatic cleanup and sharing. */
|
---|
[20355] | 665 | uint32_t volatile cRefs;
|
---|
[22115] | 666 | /** The module tag. */
|
---|
| 667 | uint64_t uTag;
|
---|
[45994] | 668 |
|
---|
| 669 | /** When set, the loading of the image and debug info (including locating any
|
---|
| 670 | * external files), will not have taken place yet. */
|
---|
| 671 | uint32_t fDeferred : 1;
|
---|
| 672 | /** Set if deferred loading failed. */
|
---|
| 673 | uint32_t fDeferredFailed : 1;
|
---|
| 674 | /** Set if the debug info is based on image exports and segments. */
|
---|
| 675 | uint32_t fExports : 1;
|
---|
| 676 | /** Alignment padding. */
|
---|
| 677 | uint32_t fPadding1 : 29;
|
---|
| 678 | #if ARCH_BITS == 64
|
---|
| 679 | uint32_t u32Padding2;
|
---|
| 680 | #endif
|
---|
| 681 |
|
---|
[19509] | 682 | /** The module name (short). */
|
---|
[20799] | 683 | char const *pszName;
|
---|
[46101] | 684 | /** The image file specified by the user. Can be NULL. */
|
---|
| 685 | char const *pszImgFileSpecified;
|
---|
[19509] | 686 | /** The module filename. Can be NULL. */
|
---|
[20799] | 687 | char const *pszImgFile;
|
---|
[19509] | 688 | /** The debug info file (if external). Can be NULL. */
|
---|
[20799] | 689 | char const *pszDbgFile;
|
---|
[19509] | 690 |
|
---|
| 691 | /** The method table for the executable image interpreter. */
|
---|
[20355] | 692 | PCRTDBGMODVTIMG pImgVt;
|
---|
[19509] | 693 | /** Pointer to the private data of the executable image interpreter. */
|
---|
[20355] | 694 | void *pvImgPriv;
|
---|
[19509] | 695 |
|
---|
| 696 | /** The method table for the debug info interpreter. */
|
---|
[20355] | 697 | PCRTDBGMODVTDBG pDbgVt;
|
---|
[19509] | 698 | /** Pointer to the private data of the debug info interpreter. */
|
---|
[20355] | 699 | void *pvDbgPriv;
|
---|
[19509] | 700 |
|
---|
[45994] | 701 | /** Critical section serializing access to the module. */
|
---|
| 702 | RTCRITSECT CritSect;
|
---|
[19509] | 703 | } RTDBGMODINT;
|
---|
[20355] | 704 | /** Pointer to an debug module structure. */
|
---|
| 705 | typedef RTDBGMODINT *PRTDBGMODINT;
|
---|
[19509] | 706 |
|
---|
| 707 |
|
---|
[85124] | 708 | extern DECL_HIDDEN_DATA(RTSTRCACHE) g_hDbgModStrCache;
|
---|
| 709 | extern DECL_HIDDEN_DATA(RTDBGMODVTDBG const) g_rtDbgModVtDbgCodeView;
|
---|
[100931] | 710 | extern DECL_HIDDEN_DATA(RTDBGMODVTDBG const) g_rtDbgModVtDbgPdb;
|
---|
[85124] | 711 | extern DECL_HIDDEN_DATA(RTDBGMODVTDBG const) g_rtDbgModVtDbgDwarf;
|
---|
| 712 | extern DECL_HIDDEN_DATA(RTDBGMODVTDBG const) g_rtDbgModVtDbgNm;
|
---|
| 713 | extern DECL_HIDDEN_DATA(RTDBGMODVTDBG const) g_rtDbgModVtDbgMapSym;
|
---|
[89881] | 714 | #ifdef IPRT_WITH_GHIDRA_DBG_MOD
|
---|
| 715 | extern DECL_HIDDEN_DATA(RTDBGMODVTDBG const) g_rtDbgModVtDbgGhidra;
|
---|
| 716 | #endif
|
---|
[46048] | 717 | #ifdef RT_OS_WINDOWS
|
---|
[85124] | 718 | extern DECL_HIDDEN_DATA(RTDBGMODVTDBG const) g_rtDbgModVtDbgDbgHelp;
|
---|
[46048] | 719 | #endif
|
---|
[85124] | 720 | extern DECL_HIDDEN_DATA(RTDBGMODVTDBG const) g_rtDbgModVtDbgDeferred;
|
---|
| 721 | extern DECL_HIDDEN_DATA(RTDBGMODVTDBG const) g_rtDbgModVtDbgContainer;
|
---|
[46048] | 722 |
|
---|
[85124] | 723 | extern DECL_HIDDEN_DATA(RTDBGMODVTIMG const) g_rtDbgModVtImgLdr;
|
---|
| 724 | extern DECL_HIDDEN_DATA(RTDBGMODVTIMG const) g_rtDbgModVtImgDeferred;
|
---|
[20739] | 725 |
|
---|
[45994] | 726 | DECLHIDDEN(int) rtDbgModContainerCreate(PRTDBGMODINT pMod, RTUINTPTR cbSeg);
|
---|
[46134] | 727 | DECLHIDDEN(int) rtDbgModContainer_SymbolRemoveAll(PRTDBGMODINT pMod);
|
---|
| 728 | DECLHIDDEN(int) rtDbgModContainer_LineRemoveAll(PRTDBGMODINT pMod);
|
---|
| 729 | DECLHIDDEN(int) rtDbgModContainer_RemoveAll(PRTDBGMODINT pMod);
|
---|
| 730 |
|
---|
[45994] | 731 | DECLHIDDEN(int) rtDbgModCreateForExports(PRTDBGMODINT pDbgMod);
|
---|
| 732 | DECLHIDDEN(int) rtDbgModDeferredCreate(PRTDBGMODINT pDbgMod, PFNRTDBGMODDEFERRED pfnDeferred, RTUINTPTR cbImage,
|
---|
[83084] | 733 | RTDBGCFG hDbgCfg, size_t cbDeferred, uint32_t fFlags, PRTDBGMODDEFERRED *ppDeferred);
|
---|
[20355] | 734 |
|
---|
[46083] | 735 | DECLHIDDEN(int) rtDbgModLdrOpenFromHandle(PRTDBGMODINT pDbgMod, RTLDRMOD hLdrMod);
|
---|
| 736 |
|
---|
[75235] | 737 | DECLHIDDEN(int) rtDwarfUnwind_EhData(void const *pvSection, size_t cbSection, RTUINTPTR uRvaSection,
|
---|
| 738 | RTDBGSEGIDX idxSeg, RTUINTPTR offSeg, RTUINTPTR uRva,
|
---|
| 739 | PRTDBGUNWINDSTATE pState, RTLDRARCH enmArch);
|
---|
[73531] | 740 |
|
---|
[19509] | 741 | /** @} */
|
---|
| 742 |
|
---|
[20374] | 743 | RT_C_DECLS_END
|
---|
[19509] | 744 |
|
---|
[76585] | 745 | #endif /* !IPRT_INCLUDED_INTERNAL_dbgmod_h */
|
---|
[19509] | 746 |
|
---|