VirtualBox

source: vbox/trunk/include/iprt/dbg.h@ 62669

Last change on this file since 62669 was 62473, checked in by vboxsync, 8 years ago

(C) 2016

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 65.1 KB
Line 
1/* $Id: dbg.h 62473 2016-07-22 18:15:28Z vboxsync $ */
2/** @file
3 * IPRT - Debugging Routines.
4 */
5
6/*
7 * Copyright (C) 2008-2016 Oracle Corporation
8 *
9 * This file is part of VirtualBox Open Source Edition (OSE), as
10 * available from http://www.virtualbox.org. This file is free software;
11 * you can redistribute it and/or modify it under the terms of the GNU
12 * General Public License (GPL) as published by the Free Software
13 * Foundation, in version 2 as it comes in the "COPYING" file of the
14 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
15 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16 *
17 * The contents of this file may alternatively be used under the terms
18 * of the Common Development and Distribution License Version 1.0
19 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
20 * VirtualBox OSE distribution, in which case the provisions of the
21 * CDDL are applicable instead of those of the GPL.
22 *
23 * You may elect to license modified versions of this file under the
24 * terms and conditions of either the GPL or the CDDL or both.
25 */
26
27#ifndef ___iprt_dbg_h
28#define ___iprt_dbg_h
29
30#include <iprt/types.h>
31#include <iprt/stdarg.h>
32#include <iprt/ldr.h>
33
34RT_C_DECLS_BEGIN
35
36# ifdef IN_RING3
37
38/** @defgroup grp_rt_dbg RTDbg - Debugging Routines
39 * @ingroup grp_rt
40 * @{
41 */
42
43
44/** Debug segment index. */
45typedef uint32_t RTDBGSEGIDX;
46/** Pointer to a debug segment index. */
47typedef RTDBGSEGIDX *PRTDBGSEGIDX;
48/** Pointer to a const debug segment index. */
49typedef RTDBGSEGIDX const *PCRTDBGSEGIDX;
50/** NIL debug segment index. */
51#define NIL_RTDBGSEGIDX UINT32_C(0xffffffff)
52/** The last normal segment index. */
53#define RTDBGSEGIDX_LAST UINT32_C(0xffffffef)
54/** Special segment index that indicates that the offset is a relative
55 * virtual address (RVA). I.e. an offset from the start of the module. */
56#define RTDBGSEGIDX_RVA UINT32_C(0xfffffff0)
57/** Special segment index that indicates that the offset is a absolute. */
58#define RTDBGSEGIDX_ABS UINT32_C(0xfffffff1)
59/** The last valid special segment index. */
60#define RTDBGSEGIDX_SPECIAL_LAST RTDBGSEGIDX_ABS
61/** The last valid special segment index. */
62#define RTDBGSEGIDX_SPECIAL_FIRST (RTDBGSEGIDX_LAST + 1U)
63
64
65
66/** @name RTDBGSYMADDR_FLAGS_XXX
67 * Flags used when looking up a symbol by address.
68 * @{ */
69/** Less or equal address. (default) */
70#define RTDBGSYMADDR_FLAGS_LESS_OR_EQUAL UINT32_C(0)
71/** Greater or equal address. */
72#define RTDBGSYMADDR_FLAGS_GREATER_OR_EQUAL UINT32_C(1)
73/** Mask of valid flags. */
74#define RTDBGSYMADDR_FLAGS_VALID_MASK UINT32_C(1)
75/** @} */
76
77
78/** Max length (including '\\0') of a segment name. */
79#define RTDBG_SEGMENT_NAME_LENGTH (128 - 8 - 8 - 8 - 4 - 4)
80
81/**
82 * Debug module segment.
83 */
84typedef struct RTDBGSEGMENT
85{
86 /** The load address.
87 * RTUINTPTR_MAX if not applicable. */
88 RTUINTPTR Address;
89 /** The image relative virtual address of the segment.
90 * RTUINTPTR_MAX if not applicable. */
91 RTUINTPTR uRva;
92 /** The segment size. */
93 RTUINTPTR cb;
94 /** The segment flags. (reserved) */
95 uint32_t fFlags;
96 /** The segment index. */
97 RTDBGSEGIDX iSeg;
98 /** Symbol name. */
99 char szName[RTDBG_SEGMENT_NAME_LENGTH];
100} RTDBGSEGMENT;
101/** Pointer to a debug module segment. */
102typedef RTDBGSEGMENT *PRTDBGSEGMENT;
103/** Pointer to a const debug module segment. */
104typedef RTDBGSEGMENT const *PCRTDBGSEGMENT;
105
106
107
108/** Max length (including '\\0') of a symbol name. */
109#define RTDBG_SYMBOL_NAME_LENGTH (512 - 8 - 8 - 8 - 4 - 4 - 8)
110
111/**
112 * Debug symbol.
113 */
114typedef struct RTDBGSYMBOL
115{
116 /** Symbol value (address).
117 * This depends a bit who you ask. It will be the same as offSeg when you
118 * as RTDbgMod, but the mapping address if you ask RTDbgAs. */
119 RTUINTPTR Value;
120 /** Symbol size. */
121 RTUINTPTR cb;
122 /** Offset into the segment specified by iSeg. */
123 RTUINTPTR offSeg;
124 /** Segment number. */
125 RTDBGSEGIDX iSeg;
126 /** Symbol Flags. (reserved). */
127 uint32_t fFlags;
128 /** Symbol ordinal.
129 * This is set to UINT32_MAX if the ordinals aren't supported. */
130 uint32_t iOrdinal;
131 /** Symbol name. */
132 char szName[RTDBG_SYMBOL_NAME_LENGTH];
133} RTDBGSYMBOL;
134/** Pointer to debug symbol. */
135typedef RTDBGSYMBOL *PRTDBGSYMBOL;
136/** Pointer to const debug symbol. */
137typedef const RTDBGSYMBOL *PCRTDBGSYMBOL;
138
139/**
140 * Allocate a new symbol structure.
141 *
142 * @returns Pointer to a new structure on success, NULL on failure.
143 */
144RTDECL(PRTDBGSYMBOL) RTDbgSymbolAlloc(void);
145
146/**
147 * Duplicates a symbol structure.
148 *
149 * @returns Pointer to duplicate on success, NULL on failure.
150 *
151 * @param pSymInfo The symbol info to duplicate.
152 */
153RTDECL(PRTDBGSYMBOL) RTDbgSymbolDup(PCRTDBGSYMBOL pSymInfo);
154
155/**
156 * Free a symbol structure previously allocated by a RTDbg method.
157 *
158 * @param pSymInfo The symbol info to free. NULL is ignored.
159 */
160RTDECL(void) RTDbgSymbolFree(PRTDBGSYMBOL pSymInfo);
161
162
163/** Max length (including '\\0') of a debug info file name. */
164#define RTDBG_FILE_NAME_LENGTH (260)
165
166
167/**
168 * Debug line number information.
169 */
170typedef struct RTDBGLINE
171{
172 /** Address.
173 * This depends a bit who you ask. It will be the same as offSeg when you
174 * as RTDbgMod, but the mapping address if you ask RTDbgAs. */
175 RTUINTPTR Address;
176 /** Offset into the segment specified by iSeg. */
177 RTUINTPTR offSeg;
178 /** Segment number. */
179 RTDBGSEGIDX iSeg;
180 /** Line number. */
181 uint32_t uLineNo;
182 /** Symbol ordinal.
183 * This is set to UINT32_MAX if the ordinals aren't supported. */
184 uint32_t iOrdinal;
185 /** Filename. */
186 char szFilename[RTDBG_FILE_NAME_LENGTH];
187} RTDBGLINE;
188/** Pointer to debug line number. */
189typedef RTDBGLINE *PRTDBGLINE;
190/** Pointer to const debug line number. */
191typedef const RTDBGLINE *PCRTDBGLINE;
192
193/**
194 * Allocate a new line number structure.
195 *
196 * @returns Pointer to a new structure on success, NULL on failure.
197 */
198RTDECL(PRTDBGLINE) RTDbgLineAlloc(void);
199
200/**
201 * Duplicates a line number structure.
202 *
203 * @returns Pointer to duplicate on success, NULL on failure.
204 *
205 * @param pLine The line number to duplicate.
206 */
207RTDECL(PRTDBGLINE) RTDbgLineDup(PCRTDBGLINE pLine);
208
209/**
210 * Free a line number structure previously allocated by a RTDbg method.
211 *
212 * @param pLine The line number to free. NULL is ignored.
213 */
214RTDECL(void) RTDbgLineFree(PRTDBGLINE pLine);
215
216
217/** @defgroup grp_rt_dbgcfg RTDbgCfg - Debugging Configuration
218 *
219 * The settings used when loading and processing debug info is kept in a
220 * RTDBGCFG instance since it's generally shared for a whole debugging session
221 * and anyhow would be a major pain to pass as individual parameters to each
222 * call. The debugging config API not only keeps the settings information but
223 * also provide APIs for making use of it, and in some cases, like for instance
224 * symbol severs, retriving and maintaining it.
225 *
226 * @todo Work in progress - APIs are still missing, adding when needed.
227 *
228 * @{
229 */
230
231/** Debugging configuration handle. */
232typedef struct RTDBGCFGINT *RTDBGCFG;
233/** Pointer to a debugging configuration handle. */
234typedef RTDBGCFG *PRTDBGCFG;
235/** NIL debug configuration handle. */
236#define NIL_RTDBGCFG ((RTDBGCFG)0)
237
238/** @name RTDBGCFG_FLAGS_XXX - Debugging configuration flags.
239 * @{ */
240/** Use deferred loading. */
241#define RTDBGCFG_FLAGS_DEFERRED RT_BIT_64(0)
242/** Don't use the symbol server (http). */
243#define RTDBGCFG_FLAGS_NO_SYM_SRV RT_BIT_64(1)
244/** Don't use system search paths.
245 * On windows this means not using _NT_ALT_SYMBOL_PATH, _NT_SYMBOL_PATH,
246 * _NT_SOURCE_PATH, and _NT_EXECUTABLE_PATH.
247 * On other systems the effect has yet to be determined. */
248#define RTDBGCFG_FLAGS_NO_SYSTEM_PATHS RT_BIT_64(2)
249/** Don't search the debug and image paths recursively. */
250#define RTDBGCFG_FLAGS_NO_RECURSIV_SEARCH RT_BIT_64(3)
251/** Don't search the source paths recursively. */
252#define RTDBGCFG_FLAGS_NO_RECURSIV_SRC_SEARCH RT_BIT_64(4)
253/** @} */
254
255/**
256 * Debugging configuration properties.
257 *
258 * The search paths are using the DOS convention of semicolon as separator
259 * character. The the special 'srv' + asterisk syntax known from the windows
260 * debugger search paths are also supported to some extent, as is 'cache' +
261 * asterisk.
262 */
263typedef enum RTDBGCFGPROP
264{
265 /** The customary invalid 0 value. */
266 RTDBGCFGPROP_INVALID = 0,
267 /** RTDBGCFG_FLAGS_XXX.
268 * Env: _FLAGS
269 * The environment variable can be specified as a unsigned value or one or more
270 * mnemonics separated by spaces. */
271 RTDBGCFGPROP_FLAGS,
272 /** List of paths to search for symbol files and images.
273 * Env: _PATH */
274 RTDBGCFGPROP_PATH,
275 /** List of symbol file suffixes (semicolon separated).
276 * Env: _SUFFIXES */
277 RTDBGCFGPROP_SUFFIXES,
278 /** List of paths to search for source files.
279 * Env: _SRC_PATH */
280 RTDBGCFGPROP_SRC_PATH,
281 /** End of valid values. */
282 RTDBGCFGPROP_END,
283 /** The customary 32-bit type hack. */
284 RTDBGCFGPROP_32BIT_HACK = 0x7fffffff
285} RTDBGCFGPROP;
286
287/**
288 * Configuration property change operation.
289 */
290typedef enum RTDBGCFGOP
291{
292 /** Customary invalid 0 value. */
293 RTDBGCFGOP_INVALID = 0,
294 /** Replace the current value with the given one. */
295 RTDBGCFGOP_SET,
296 /** Append the given value to the existing one. For integer values this is
297 * considered a bitwise OR operation. */
298 RTDBGCFGOP_APPEND,
299 /** Prepend the given value to the existing one. For integer values this is
300 * considered a bitwise OR operation. */
301 RTDBGCFGOP_PREPEND,
302 /** Removes the value from the existing one. For interger values the value is
303 * complemented and ANDed with the existing one, clearing all the specified
304 * flags/bits. */
305 RTDBGCFGOP_REMOVE,
306 /** End of valid values. */
307 RTDBGCFGOP_END,
308 /** Customary 32-bit type hack. */
309 RTDBGCFGOP_32BIT_HACK = 0x7fffffff
310} RTDBGCFGOP;
311
312
313
314/**
315 * Initializes a debugging configuration.
316 *
317 * @returns IPRT status code.
318 * @param phDbgCfg Where to return the configuration handle.
319 * @param pszEnvVarPrefix The environment variable prefix. If NULL, the
320 * environment is not consulted.
321 * @param fNativePaths Whether to pick up native paths from the
322 * environment.
323 *
324 * @sa RTDbgCfgChangeString, RTDbgCfgChangeUInt.
325 */
326RTDECL(int) RTDbgCfgCreate(PRTDBGCFG phDbgCfg, const char *pszEnvVarPrefix, bool fNativePaths);
327
328/**
329 * Retains a new reference to a debugging config.
330 *
331 * @returns New reference count.
332 * UINT32_MAX is returned if the handle is invalid (asserted).
333 * @param hDbgCfg The config handle.
334 */
335RTDECL(uint32_t) RTDbgCfgRetain(RTDBGCFG hDbgCfg);
336
337/**
338 * Releases a references to a debugging config.
339 *
340 * @returns New reference count, if 0 the config was freed. UINT32_MAX is
341 * returned if the handle is invalid (asserted).
342 * @param hDbgCfg The config handle.
343 */
344RTDECL(uint32_t) RTDbgCfgRelease(RTDBGCFG hDbgCfg);
345
346/**
347 * Changes a property value by string.
348 *
349 * For string values the string is used more or less as given. For integer
350 * values and flags, it can contains both values (ORed together) or property
351 * specific mnemonics (ORed / ~ANDed).
352 *
353 * @returns IPRT status code.
354 * @retval VERR_DBG_CFG_INVALID_VALUE
355 * @param hDbgCfg The debugging configuration handle.
356 * @param enmProp The property to change.
357 * @param enmOp How to change the property.
358 * @param pszValue The property value to apply.
359 */
360RTDECL(int) RTDbgCfgChangeString(RTDBGCFG hDbgCfg, RTDBGCFGPROP enmProp, RTDBGCFGOP enmOp, const char *pszValue);
361
362/**
363 * Changes a property value by unsigned integer (64-bit).
364 *
365 * This can only be applied to integer and flag properties.
366 *
367 * @returns IPRT status code.
368 * @retval VERR_DBG_CFG_NOT_UINT_PROP
369 * @param hDbgCfg The debugging configuration handle.
370 * @param enmProp The property to change.
371 * @param enmOp How to change the property.
372 * @param uValue The property value to apply.
373 */
374RTDECL(int) RTDbgCfgChangeUInt(RTDBGCFG hDbgCfg, RTDBGCFGPROP enmProp, RTDBGCFGOP enmOp, uint64_t uValue);
375
376/**
377 * Query a property value as string.
378 *
379 * Integer and flags properties are returned as a list of mnemonics if possible,
380 * otherwise as simple hex values.
381 *
382 * @returns IPRT status code.
383 * @retval VERR_BUFFER_OVERFLOW if there isn't sufficient buffer space. Nothing
384 * is written.
385 * @param hDbgCfg The debugging configuration handle.
386 * @param enmProp The property to change.
387 * @param pszValue The output buffer.
388 * @param cbValue The size of the output buffer.
389 */
390RTDECL(int) RTDbgCfgQueryString(RTDBGCFG hDbgCfg, RTDBGCFGPROP enmProp, char *pszValue, size_t cbValue);
391
392/**
393 * Query a property value as unsigned integer (64-bit).
394 *
395 * Only integer and flags properties can be queried this way.
396 *
397 * @returns IPRT status code.
398 * @retval VERR_DBG_CFG_NOT_UINT_PROP
399 * @param hDbgCfg The debugging configuration handle.
400 * @param enmProp The property to change.
401 * @param puValue Where to return the value.
402 */
403RTDECL(int) RTDbgCfgQueryUInt(RTDBGCFG hDbgCfg, RTDBGCFGPROP enmProp, uint64_t *puValue);
404
405/**
406 * Log callback.
407 *
408 * @param hDbgCfg The debug config instance.
409 * @param iLevel The message level.
410 * @param pszMsg The message.
411 * @param pvUser User argument.
412 */
413typedef DECLCALLBACK(void) FNRTDBGCFGLOG(RTDBGCFG hDbgCfg, uint32_t iLevel, const char *pszMsg, void *pvUser);
414/** Pointer to a log callback. */
415typedef FNRTDBGCFGLOG *PFNRTDBGCFGLOG;
416
417/**
418 * Sets the log callback for the configuration.
419 *
420 * This will fail if there is already a log callback present, unless pfnCallback
421 * is NULL.
422 *
423 * @returns IPRT status code.
424 * @param hDbgCfg The debugging configuration handle.
425 * @param pfnCallback The callback function. NULL to unset.
426 * @param pvUser The user argument.
427 */
428RTDECL(int) RTDbgCfgSetLogCallback(RTDBGCFG hDbgCfg, PFNRTDBGCFGLOG pfnCallback, void *pvUser);
429
430/**
431 * Callback used by the RTDbgCfgOpen function to try out a file that was found.
432 *
433 * @returns On statuses other than VINF_CALLBACK_RETURN and
434 * VERR_CALLBACK_RETURN the search will continue till the end of the
435 * list. These status codes will not necessarily be propagated to the
436 * caller in any consistent manner.
437 * @retval VINF_CALLBACK_RETURN if successuflly opened the file and it's time
438 * to return
439 * @retval VERR_CALLBACK_RETURN if we shouldn't stop searching.
440 *
441 * @param hDbgCfg The debugging configuration handle.
442 * @param pszFilename The path to the file that should be tried out.
443 * @param pvUser1 First user parameter.
444 * @param pvUser2 Second user parameter.
445 */
446typedef DECLCALLBACK(int) FNRTDBGCFGOPEN(RTDBGCFG hDbgCfg, const char *pszFilename, void *pvUser1, void *pvUser2);
447/** Pointer to a open-file callback used to the RTDbgCfgOpen functions. */
448typedef FNRTDBGCFGOPEN *PFNRTDBGCFGOPEN;
449
450
451RTDECL(int) RTDbgCfgOpenPeImage(RTDBGCFG hDbgCfg, const char *pszFilename, uint32_t cbImage, uint32_t uTimestamp,
452 PFNRTDBGCFGOPEN pfnCallback, void *pvUser1, void *pvUser2);
453RTDECL(int) RTDbgCfgOpenPdb70(RTDBGCFG hDbgCfg, const char *pszFilename, PCRTUUID pUuid, uint32_t uAge,
454 PFNRTDBGCFGOPEN pfnCallback, void *pvUser1, void *pvUser2);
455RTDECL(int) RTDbgCfgOpenPdb20(RTDBGCFG hDbgCfg, const char *pszFilename, uint32_t cbImage, uint32_t uTimestamp, uint32_t uAge,
456 PFNRTDBGCFGOPEN pfnCallback, void *pvUser1, void *pvUser2);
457RTDECL(int) RTDbgCfgOpenDbg(RTDBGCFG hDbgCfg, const char *pszFilename, uint32_t cbImage, uint32_t uTimestamp,
458 PFNRTDBGCFGOPEN pfnCallback, void *pvUser1, void *pvUser2);
459RTDECL(int) RTDbgCfgOpenDwo(RTDBGCFG hDbgCfg, const char *pszFilename, uint32_t uCrc32,
460 PFNRTDBGCFGOPEN pfnCallback, void *pvUser1, void *pvUser2);
461RTDECL(int) RTDbgCfgOpenDsymBundle(RTDBGCFG hDbgCfg, const char *pszFilename, PCRTUUID pUuid,
462 PFNRTDBGCFGOPEN pfnCallback, void *pvUser1, void *pvUser2);
463RTDECL(int) RTDbgCfgOpenMachOImage(RTDBGCFG hDbgCfg, const char *pszFilename, PCRTUUID pUuid,
464 PFNRTDBGCFGOPEN pfnCallback, void *pvUser1, void *pvUser2);
465
466
467/** @name Static symbol cache configuration
468 * @{ */
469/** The cache subdirectory containing the UUID mappings for .dSYM bundles.
470 * The UUID mappings implemented by IPRT are splitting the image/dsym UUID up
471 * into five 4 digit parts that maps to directories and one twelve digit part
472 * that maps to a symbolic link. The symlink points to the file in the
473 * Contents/Resources/DWARF/ directory of the .dSYM bundle for a .dSYM map, and
474 * to the image file (Contents/MacOS/bundlename for bundles) for image map.
475 *
476 * According to available documentation, both lldb and gdb are able to use these
477 * UUID maps to find debug info while debugging. See:
478 * http://lldb.llvm.org/symbols.html
479 */
480#define RTDBG_CACHE_UUID_MAP_DIR_DSYMS "dsym-uuids"
481/** The cache subdirectory containing the UUID mappings for image files. */
482#define RTDBG_CACHE_UUID_MAP_DIR_IMAGES "image-uuids"
483/** Suffix used for the cached .dSYM debug files.
484 * In .dSYM bundles only the .dSYM/Contents/Resources/DWARF/debug-file is
485 * copied into the cache, and in order to not clash with the stripped/rich image
486 * file, the cache tool slaps this suffix onto the name. */
487#define RTDBG_CACHE_DSYM_FILE_SUFFIX ".dwarf"
488/** @} */
489
490
491/** @} */
492
493
494/** @defgroup grp_rt_dbgas RTDbgAs - Debug Address Space
495 * @{
496 */
497
498/**
499 * Creates an empty address space.
500 *
501 * @returns IPRT status code.
502 *
503 * @param phDbgAs Where to store the address space handle on success.
504 * @param FirstAddr The first address in the address space.
505 * @param LastAddr The last address in the address space.
506 * @param pszName The name of the address space.
507 */
508RTDECL(int) RTDbgAsCreate(PRTDBGAS phDbgAs, RTUINTPTR FirstAddr, RTUINTPTR LastAddr, const char *pszName);
509
510/**
511 * Variant of RTDbgAsCreate that takes a name format string.
512 *
513 * @returns IPRT status code.
514 *
515 * @param phDbgAs Where to store the address space handle on success.
516 * @param FirstAddr The first address in the address space.
517 * @param LastAddr The last address in the address space.
518 * @param pszNameFmt The name format of the address space.
519 * @param va Format arguments.
520 */
521RTDECL(int) RTDbgAsCreateV(PRTDBGAS phDbgAs, RTUINTPTR FirstAddr, RTUINTPTR LastAddr,
522 const char *pszNameFmt, va_list va) RT_IPRT_FORMAT_ATTR(4, 0);
523
524/**
525 * Variant of RTDbgAsCreate that takes a name format string.
526 *
527 * @returns IPRT status code.
528 *
529 * @param phDbgAs Where to store the address space handle on success.
530 * @param FirstAddr The first address in the address space.
531 * @param LastAddr The last address in the address space.
532 * @param pszNameFmt The name format of the address space.
533 * @param ... Format arguments.
534 */
535RTDECL(int) RTDbgAsCreateF(PRTDBGAS phDbgAs, RTUINTPTR FirstAddr, RTUINTPTR LastAddr,
536 const char *pszNameFmt, ...) RT_IPRT_FORMAT_ATTR(4, 5);
537
538/**
539 * Retains a reference to the address space.
540 *
541 * @returns New reference count, UINT32_MAX on invalid handle (asserted).
542 *
543 * @param hDbgAs The address space handle.
544 *
545 * @remarks Will not take any locks.
546 */
547RTDECL(uint32_t) RTDbgAsRetain(RTDBGAS hDbgAs);
548
549/**
550 * Release a reference to the address space.
551 *
552 * When the reference count reaches zero, the address space is destroyed.
553 * That means unlinking all the modules it currently contains, potentially
554 * causing some or all of them to be destroyed as they are managed by
555 * reference counting.
556 *
557 * @returns New reference count, UINT32_MAX on invalid handle (asserted).
558 *
559 * @param hDbgAs The address space handle. The NIL handle is quietly
560 * ignored and 0 is returned.
561 *
562 * @remarks Will not take any locks.
563 */
564RTDECL(uint32_t) RTDbgAsRelease(RTDBGAS hDbgAs);
565
566/**
567 * Locks the address space for exclusive access.
568 *
569 * @returns IRPT status code
570 * @param hDbgAs The address space handle.
571 */
572RTDECL(int) RTDbgAsLockExcl(RTDBGAS hDbgAs);
573
574/**
575 * Counters the actions of one RTDbgAsUnlockExcl call.
576 *
577 * @returns IRPT status code
578 * @param hDbgAs The address space handle.
579 */
580RTDECL(int) RTDbgAsUnlockExcl(RTDBGAS hDbgAs);
581
582/**
583 * Gets the name of an address space.
584 *
585 * @returns read only address space name.
586 * NULL if hDbgAs is invalid.
587 *
588 * @param hDbgAs The address space handle.
589 *
590 * @remarks Will not take any locks.
591 */
592RTDECL(const char *) RTDbgAsName(RTDBGAS hDbgAs);
593
594/**
595 * Gets the first address in an address space.
596 *
597 * @returns The address.
598 * 0 if hDbgAs is invalid.
599 *
600 * @param hDbgAs The address space handle.
601 *
602 * @remarks Will not take any locks.
603 */
604RTDECL(RTUINTPTR) RTDbgAsFirstAddr(RTDBGAS hDbgAs);
605
606/**
607 * Gets the last address in an address space.
608 *
609 * @returns The address.
610 * 0 if hDbgAs is invalid.
611 *
612 * @param hDbgAs The address space handle.
613 *
614 * @remarks Will not take any locks.
615 */
616RTDECL(RTUINTPTR) RTDbgAsLastAddr(RTDBGAS hDbgAs);
617
618/**
619 * Gets the number of modules in the address space.
620 *
621 * This can be used together with RTDbgAsModuleByIndex
622 * to enumerate the modules.
623 *
624 * @returns The number of modules.
625 *
626 * @param hDbgAs The address space handle.
627 *
628 * @remarks Will not take any locks.
629 */
630RTDECL(uint32_t) RTDbgAsModuleCount(RTDBGAS hDbgAs);
631
632/** @name Flags for RTDbgAsModuleLink and RTDbgAsModuleLinkSeg
633 * @{ */
634/** Replace all conflicting module.
635 * (The conflicting modules will be removed the address space and their
636 * references released.) */
637#define RTDBGASLINK_FLAGS_REPLACE RT_BIT_32(0)
638/** Mask containing the valid flags. */
639#define RTDBGASLINK_FLAGS_VALID_MASK UINT32_C(0x00000001)
640/** @} */
641
642/**
643 * Links a module into the address space at the give address.
644 *
645 * The size of the mapping is determined using RTDbgModImageSize().
646 *
647 * @returns IPRT status code.
648 * @retval VERR_OUT_OF_RANGE if the specified address will put the module
649 * outside the address space.
650 * @retval VERR_ADDRESS_CONFLICT if the mapping clashes with existing mappings.
651 *
652 * @param hDbgAs The address space handle.
653 * @param hDbgMod The module handle of the module to be linked in.
654 * @param ImageAddr The address to link the module at.
655 * @param fFlags See RTDBGASLINK_FLAGS_*.
656 */
657RTDECL(int) RTDbgAsModuleLink(RTDBGAS hDbgAs, RTDBGMOD hDbgMod, RTUINTPTR ImageAddr, uint32_t fFlags);
658
659/**
660 * Links a segment into the address space at the give address.
661 *
662 * The size of the mapping is determined using RTDbgModSegmentSize().
663 *
664 * @returns IPRT status code.
665 * @retval VERR_OUT_OF_RANGE if the specified address will put the module
666 * outside the address space.
667 * @retval VERR_ADDRESS_CONFLICT if the mapping clashes with existing mappings.
668 *
669 * @param hDbgAs The address space handle.
670 * @param hDbgMod The module handle.
671 * @param iSeg The segment number (0-based) of the segment to be
672 * linked in.
673 * @param SegAddr The address to link the segment at.
674 * @param fFlags See RTDBGASLINK_FLAGS_*.
675 */
676RTDECL(int) RTDbgAsModuleLinkSeg(RTDBGAS hDbgAs, RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR SegAddr, uint32_t fFlags);
677
678/**
679 * Unlinks all the mappings of a module from the address space.
680 *
681 * @returns IPRT status code.
682 * @retval VERR_NOT_FOUND if the module wasn't found.
683 *
684 * @param hDbgAs The address space handle.
685 * @param hDbgMod The module handle of the module to be unlinked.
686 */
687RTDECL(int) RTDbgAsModuleUnlink(RTDBGAS hDbgAs, RTDBGMOD hDbgMod);
688
689/**
690 * Unlinks the mapping at the specified address.
691 *
692 * @returns IPRT status code.
693 * @retval VERR_NOT_FOUND if no module or segment is mapped at that address.
694 *
695 * @param hDbgAs The address space handle.
696 * @param Addr The address within the mapping to be unlinked.
697 */
698RTDECL(int) RTDbgAsModuleUnlinkByAddr(RTDBGAS hDbgAs, RTUINTPTR Addr);
699
700/**
701 * Get a the handle of a module in the address space by is index.
702 *
703 * @returns A retained handle to the specified module. The caller must release
704 * the returned reference.
705 * NIL_RTDBGMOD if invalid index or handle.
706 *
707 * @param hDbgAs The address space handle.
708 * @param iModule The index of the module to get.
709 *
710 * @remarks The module indexes may change after calls to RTDbgAsModuleLink,
711 * RTDbgAsModuleLinkSeg, RTDbgAsModuleUnlink and
712 * RTDbgAsModuleUnlinkByAddr.
713 */
714RTDECL(RTDBGMOD) RTDbgAsModuleByIndex(RTDBGAS hDbgAs, uint32_t iModule);
715
716/**
717 * Queries mapping module information by handle.
718 *
719 * @returns IPRT status code.
720 * @retval VERR_NOT_FOUND if no mapping was found at the specified address.
721 *
722 * @param hDbgAs The address space handle.
723 * @param Addr Address within the mapping of the module or segment.
724 * @param phMod Where to the return the retained module handle.
725 * Optional.
726 * @param pAddr Where to return the base address of the mapping.
727 * Optional.
728 * @param piSeg Where to return the segment index. This is set to
729 * NIL if the entire module is mapped as a single
730 * mapping. Optional.
731 */
732RTDECL(int) RTDbgAsModuleByAddr(RTDBGAS hDbgAs, RTUINTPTR Addr, PRTDBGMOD phMod, PRTUINTPTR pAddr, PRTDBGSEGIDX piSeg);
733
734/**
735 * Queries mapping module information by name.
736 *
737 * @returns IPRT status code.
738 * @retval VERR_NOT_FOUND if no mapping was found at the specified address.
739 * @retval VERR_OUT_OF_RANGE if the name index was out of range.
740 *
741 * @param hDbgAs The address space handle.
742 * @param pszName The module name.
743 * @param iName There can be more than one module by the same name
744 * in an address space. This argument indicates which
745 * is meant. (0 based)
746 * @param phMod Where to the return the retained module handle.
747 */
748RTDECL(int) RTDbgAsModuleByName(RTDBGAS hDbgAs, const char *pszName, uint32_t iName, PRTDBGMOD phMod);
749
750/**
751 * Information about a mapping.
752 *
753 * This is used by RTDbgAsModuleGetMapByIndex.
754 */
755typedef struct RTDBGASMAPINFO
756{
757 /** The mapping address. */
758 RTUINTPTR Address;
759 /** The segment mapped there.
760 * This is NIL_RTDBGSEGIDX if the entire module image is mapped here. */
761 RTDBGSEGIDX iSeg;
762} RTDBGASMAPINFO;
763/** Pointer to info about an address space mapping. */
764typedef RTDBGASMAPINFO *PRTDBGASMAPINFO;
765/** Pointer to const info about an address space mapping. */
766typedef RTDBGASMAPINFO const *PCRTDBGASMAPINFO;
767
768/**
769 * Queries mapping information for a module given by index.
770 *
771 * @returns IRPT status code.
772 * @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
773 * @retval VERR_OUT_OF_RANGE if the name index was out of range.
774 * @retval VINF_BUFFER_OVERFLOW if the array is too small and the returned
775 * information is incomplete.
776 *
777 * @param hDbgAs The address space handle.
778 * @param iModule The index of the module to get.
779 * @param paMappings Where to return the mapping information. The buffer
780 * size is given by *pcMappings.
781 * @param pcMappings IN: Size of the paMappings array. OUT: The number of
782 * entries returned.
783 * @param fFlags Flags for reserved for future use. MBZ.
784 *
785 * @remarks See remarks for RTDbgAsModuleByIndex regarding the volatility of the
786 * iModule parameter.
787 */
788RTDECL(int) RTDbgAsModuleQueryMapByIndex(RTDBGAS hDbgAs, uint32_t iModule, PRTDBGASMAPINFO paMappings, uint32_t *pcMappings, uint32_t fFlags);
789
790/**
791 * Adds a symbol to a module in the address space.
792 *
793 * @returns IPRT status code. See RTDbgModSymbolAdd for more specific ones.
794 * @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
795 * @retval VERR_NOT_FOUND if no module was found at the specified address.
796 * @retval VERR_NOT_SUPPORTED if the module interpret doesn't support adding
797 * custom symbols.
798 *
799 * @param hDbgAs The address space handle.
800 * @param pszSymbol The symbol name.
801 * @param Addr The address of the symbol.
802 * @param cb The size of the symbol.
803 * @param fFlags Symbol flags.
804 * @param piOrdinal Where to return the symbol ordinal on success. If
805 * the interpreter doesn't do ordinals, this will be set to
806 * UINT32_MAX. Optional
807 */
808RTDECL(int) RTDbgAsSymbolAdd(RTDBGAS hDbgAs, const char *pszSymbol, RTUINTPTR Addr, RTUINTPTR cb, uint32_t fFlags, uint32_t *piOrdinal);
809
810/**
811 * Query a symbol by address.
812 *
813 * @returns IPRT status code. See RTDbgModSymbolAddr for more specific ones.
814 * @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
815 * @retval VERR_NOT_FOUND if the address couldn't be mapped to a module.
816 * @retval VERR_INVALID_PARAMETER if incorrect flags.
817 *
818 * @param hDbgAs The address space handle.
819 * @param Addr The address which closest symbol is requested.
820 * @param fFlags Symbol search flags, see RTDBGSYMADDR_FLAGS_XXX.
821 * @param poffDisp Where to return the distance between the symbol
822 * and address. Optional.
823 * @param pSymbol Where to return the symbol info.
824 * @param phMod Where to return the module handle. Optional.
825 */
826RTDECL(int) RTDbgAsSymbolByAddr(RTDBGAS hDbgAs, RTUINTPTR Addr, uint32_t fFlags,
827 PRTINTPTR poffDisp, PRTDBGSYMBOL pSymbol, PRTDBGMOD phMod);
828
829/**
830 * Query a symbol by address.
831 *
832 * @returns IPRT status code. See RTDbgModSymbolAddrA for more specific ones.
833 * @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
834 * @retval VERR_NOT_FOUND if the address couldn't be mapped to a module.
835 * @retval VERR_INVALID_PARAMETER if incorrect flags.
836 *
837 * @param hDbgAs The address space handle.
838 * @param Addr The address which closest symbol is requested.
839 * @param fFlags Symbol search flags, see RTDBGSYMADDR_FLAGS_XXX.
840 * @param poffDisp Where to return the distance between the symbol
841 * and address. Optional.
842 * @param ppSymInfo Where to return the pointer to the allocated symbol
843 * info. Always set. Free with RTDbgSymbolFree.
844 * @param phMod Where to return the module handle. Optional.
845 */
846RTDECL(int) RTDbgAsSymbolByAddrA(RTDBGAS hDbgAs, RTUINTPTR Addr, uint32_t fFlags,
847 PRTINTPTR poffDisp, PRTDBGSYMBOL *ppSymInfo, PRTDBGMOD phMod);
848
849/**
850 * Query a symbol by name.
851 *
852 * @returns IPRT status code.
853 * @retval VERR_SYMBOL_NOT_FOUND if not found.
854 *
855 * @param hDbgAs The address space handle.
856 * @param pszSymbol The symbol name. It is possible to limit the scope
857 * of the search by prefixing the symbol with a module
858 * name pattern followed by a bang (!) character.
859 * RTStrSimplePatternNMatch is used for the matching.
860 * @param pSymbol Where to return the symbol info.
861 * @param phMod Where to return the module handle. Optional.
862 */
863RTDECL(int) RTDbgAsSymbolByName(RTDBGAS hDbgAs, const char *pszSymbol, PRTDBGSYMBOL pSymbol, PRTDBGMOD phMod);
864
865/**
866 * Query a symbol by name, allocating the returned symbol structure.
867 *
868 * @returns IPRT status code.
869 * @retval VERR_SYMBOL_NOT_FOUND if not found.
870 *
871 * @param hDbgAs The address space handle.
872 * @param pszSymbol The symbol name. See RTDbgAsSymbolByName for more.
873 * @param ppSymbol Where to return the pointer to the allocated
874 * symbol info. Always set. Free with RTDbgSymbolFree.
875 * @param phMod Where to return the module handle. Optional.
876 */
877RTDECL(int) RTDbgAsSymbolByNameA(RTDBGAS hDbgAs, const char *pszSymbol, PRTDBGSYMBOL *ppSymbol, PRTDBGMOD phMod);
878
879/**
880 * Adds a line number to a module in the address space.
881 *
882 * @returns IPRT status code. See RTDbgModLineAdd for more specific ones.
883 * @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
884 * @retval VERR_NOT_FOUND if no module was found at the specified address.
885 * @retval VERR_NOT_SUPPORTED if the module interpret doesn't support adding
886 * custom symbols.
887 *
888 * @param hDbgAs The address space handle.
889 * @param pszFile The file name.
890 * @param uLineNo The line number.
891 * @param Addr The address of the symbol.
892 * @param piOrdinal Where to return the line number ordinal on success.
893 * If the interpreter doesn't do ordinals, this will be
894 * set to UINT32_MAX. Optional.
895 */
896RTDECL(int) RTDbgAsLineAdd(RTDBGAS hDbgAs, const char *pszFile, uint32_t uLineNo, RTUINTPTR Addr, uint32_t *piOrdinal);
897
898/**
899 * Query a line number by address.
900 *
901 * @returns IPRT status code. See RTDbgModLineAddrA for more specific ones.
902 * @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
903 * @retval VERR_NOT_FOUND if the address couldn't be mapped to a module.
904 *
905 * @param hDbgAs The address space handle.
906 * @param Addr The address which closest symbol is requested.
907 * @param poffDisp Where to return the distance between the line
908 * number and address.
909 * @param pLine Where to return the line number information.
910 * @param phMod Where to return the module handle. Optional.
911 */
912RTDECL(int) RTDbgAsLineByAddr(RTDBGAS hDbgAs, RTUINTPTR Addr, PRTINTPTR poffDisp, PRTDBGLINE pLine, PRTDBGMOD phMod);
913
914/**
915 * Query a line number by address.
916 *
917 * @returns IPRT status code. See RTDbgModLineAddrA for more specific ones.
918 * @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
919 * @retval VERR_NOT_FOUND if the address couldn't be mapped to a module.
920 *
921 * @param hDbgAs The address space handle.
922 * @param Addr The address which closest symbol is requested.
923 * @param poffDisp Where to return the distance between the line
924 * number and address.
925 * @param ppLine Where to return the pointer to the allocated line
926 * number info. Always set. Free with RTDbgLineFree.
927 * @param phMod Where to return the module handle. Optional.
928 */
929RTDECL(int) RTDbgAsLineByAddrA(RTDBGAS hDbgAs, RTUINTPTR Addr, PRTINTPTR poffDisp, PRTDBGLINE *ppLine, PRTDBGMOD phMod);
930
931/** @todo Missing some bits here. */
932
933/** @} */
934
935
936/** @defgroup grp_rt_dbgmod RTDbgMod - Debug Module Interpreter
937 * @{
938 */
939
940/**
941 * Creates a module based on the default debug info container.
942 *
943 * This can be used to manually load a module and its symbol. The primary user
944 * group is the debug info interpreters, which use this API to create an
945 * efficient debug info container behind the scenes and forward all queries to
946 * it once the info has been loaded.
947 *
948 * @returns IPRT status code.
949 *
950 * @param phDbgMod Where to return the module handle.
951 * @param pszName The name of the module (mandatory).
952 * @param cbSeg The size of initial segment. If zero, segments will
953 * have to be added manually using RTDbgModSegmentAdd.
954 * @param fFlags Flags reserved for future extensions, MBZ for now.
955 */
956RTDECL(int) RTDbgModCreate(PRTDBGMOD phDbgMod, const char *pszName, RTUINTPTR cbSeg, uint32_t fFlags);
957
958RTDECL(int) RTDbgModCreateFromImage(PRTDBGMOD phDbgMod, const char *pszFilename, const char *pszName,
959 RTLDRARCH enmArch, RTDBGCFG hDbgCfg);
960RTDECL(int) RTDbgModCreateFromMap(PRTDBGMOD phDbgMod, const char *pszFilename, const char *pszName, RTUINTPTR uSubtrahend,
961 RTDBGCFG hDbgCfg);
962RTDECL(int) RTDbgModCreateFromPeImage(PRTDBGMOD phDbgMod, const char *pszFilename, const char *pszName, RTLDRMOD hLdrMod,
963 uint32_t cbImage, uint32_t uTimeDateStamp, RTDBGCFG hDbgCfg);
964RTDECL(int) RTDbgModCreateFromDbg(PRTDBGMOD phDbgMod, const char *pszFilename, const char *pszName, uint32_t cbImage,
965 uint32_t uTimeDateStamp, RTDBGCFG hDbgCfg);
966RTDECL(int) RTDbgModCreateFromPdb(PRTDBGMOD phDbgMod, const char *pszFilename, const char *pszName, uint32_t cbImage,
967 PCRTUUID pUuid, uint32_t Age, RTDBGCFG hDbgCfg);
968RTDECL(int) RTDbgModCreateFromDwo(PRTDBGMOD phDbgMod, const char *pszFilename, const char *pszName, uint32_t cbImage,
969 uint32_t uCrc32, RTDBGCFG hDbgCfg);
970RTDECL(int) RTDbgModCreateFromMachOImage(PRTDBGMOD phDbgMod, const char *pszFilename, const char *pszName,
971 RTLDRARCH enmArch, uint32_t cbImage, uint32_t cSegs, PCRTDBGSEGMENT paSegs,
972 PCRTUUID pUuid, RTDBGCFG hDbgCfg, uint32_t fFlags);
973
974/** @name Flags for RTDbgModCreate and friends.
975 * @{ */
976/** Overrides the hDbgCfg settings and forces an image and/or symbol file
977 * search. RTDbgModCreate will quietly ignore this flag. */
978#define RTDBGMOD_F_NOT_DEFERRED RT_BIT_32(0)
979/** @} */
980
981
982/**
983 * Retains another reference to the module.
984 *
985 * @returns New reference count, UINT32_MAX on invalid handle (asserted).
986 *
987 * @param hDbgMod The module handle.
988 *
989 * @remarks Will not take any locks.
990 */
991RTDECL(uint32_t) RTDbgModRetain(RTDBGMOD hDbgMod);
992
993/**
994 * Release a reference to the module.
995 *
996 * When the reference count reaches zero, the module is destroyed.
997 *
998 * @returns New reference count, UINT32_MAX on invalid handle (asserted).
999 *
1000 * @param hDbgMod The module handle. The NIL handle is quietly ignored
1001 * and 0 is returned.
1002 *
1003 * @remarks Will not take any locks.
1004 */
1005RTDECL(uint32_t) RTDbgModRelease(RTDBGMOD hDbgMod);
1006
1007/**
1008 * Removes all content from the debug module (container), optionally only
1009 * leaving segments and image size intact.
1010 *
1011 * This is only possible on container modules, i.e. created by RTDbgModCreate().
1012 *
1013 * @returns IPRT status code.
1014 * @param hDbgMod The module handle.
1015 * @param fLeaveSegments Whether to leave segments (and image size) as is.
1016 */
1017RTDECL(int) RTDbgModRemoveAll(RTDBGMOD hDbgMod, bool fLeaveSegments);
1018
1019/**
1020 * Gets the module name.
1021 *
1022 * @returns Pointer to a read only string containing the name.
1023 *
1024 * @param hDbgMod The module handle.
1025 */
1026RTDECL(const char *) RTDbgModName(RTDBGMOD hDbgMod);
1027
1028/**
1029 * Gets the name of the debug info file we're using.
1030 *
1031 * @returns Pointer to a read only string containing the filename, NULL if we
1032 * don't use one.
1033 *
1034 * @param hDbgMod The module handle.
1035 */
1036RTDECL(const char *) RTDbgModDebugFile(RTDBGMOD hDbgMod);
1037
1038/**
1039 * Gets the image filename (as specified by the user).
1040 *
1041 * @returns Pointer to a read only string containing the filename.
1042 *
1043 * @param hDbgMod The module handle.
1044 */
1045RTDECL(const char *) RTDbgModImageFile(RTDBGMOD hDbgMod);
1046
1047/**
1048 * Gets the image filename actually used if it differs from RTDbgModImageFile.
1049 *
1050 * @returns Pointer to a read only string containing the filename, NULL if same
1051 * as RTDBgModImageFile.
1052 *
1053 * @param hDbgMod The module handle.
1054 */
1055RTDECL(const char *) RTDbgModImageFileUsed(RTDBGMOD hDbgMod);
1056
1057/**
1058 * Checks if the loading of the debug info has been postponed.
1059 *
1060 * @returns true if postponed, false if not or invalid handle.
1061 * @param hDbgMod The module handle.
1062 */
1063RTDECL(bool) RTDbgModIsDeferred(RTDBGMOD hDbgMod);
1064
1065/**
1066 * Checks if the debug info is exports only.
1067 *
1068 * @returns true if exports only, false if not or invalid handle.
1069 * @param hDbgMod The module handle.
1070 */
1071RTDECL(bool) RTDbgModIsExports(RTDBGMOD hDbgMod);
1072
1073/**
1074 * Converts an image relative address to a segment:offset address.
1075 *
1076 * @returns Segment index on success.
1077 * NIL_RTDBGSEGIDX is returned if the module handle or the RVA are
1078 * invalid.
1079 *
1080 * @param hDbgMod The module handle.
1081 * @param uRva The image relative address to convert.
1082 * @param poffSeg Where to return the segment offset. Optional.
1083 */
1084RTDECL(RTDBGSEGIDX) RTDbgModRvaToSegOff(RTDBGMOD hDbgMod, RTUINTPTR uRva, PRTUINTPTR poffSeg);
1085
1086/**
1087 * Image size when mapped if segments are mapped adjacently.
1088 *
1089 * For ELF, PE, and Mach-O images this is (usually) a natural query, for LX and
1090 * NE and such it's a bit odder and the answer may not make much sense for them.
1091 *
1092 * @returns Image mapped size.
1093 * RTUINTPTR_MAX is returned if the handle is invalid.
1094 *
1095 * @param hDbgMod The module handle.
1096 */
1097RTDECL(RTUINTPTR) RTDbgModImageSize(RTDBGMOD hDbgMod);
1098
1099/**
1100 * Gets the module tag value if any.
1101 *
1102 * @returns The tag. 0 if hDbgMod is invalid.
1103 *
1104 * @param hDbgMod The module handle.
1105 */
1106RTDECL(uint64_t) RTDbgModGetTag(RTDBGMOD hDbgMod);
1107
1108/**
1109 * Tags or untags the module.
1110 *
1111 * @returns IPRT status code.
1112 * @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1113 *
1114 * @param hDbgMod The module handle.
1115 * @param uTag The tag value. The convention is that 0 is no tag
1116 * and any other value means it's tagged. It's adviced
1117 * to use some kind of unique number like an address
1118 * (global or string cache for instance) to avoid
1119 * collisions with other users
1120 */
1121RTDECL(int) RTDbgModSetTag(RTDBGMOD hDbgMod, uint64_t uTag);
1122
1123
1124/**
1125 * Adds a segment to the module. Optional feature.
1126 *
1127 * This method is intended used for manually constructing debug info for a
1128 * module. The main usage is from other debug info interpreters that want to
1129 * avoid writing a debug info database and instead uses the standard container
1130 * behind the scenes.
1131 *
1132 * @returns IPRT status code.
1133 * @retval VERR_NOT_SUPPORTED if this feature isn't support by the debug info
1134 * interpreter. This is a common return code.
1135 * @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1136 * @retval VERR_DBG_ADDRESS_WRAP if uRva+cb wraps around.
1137 * @retval VERR_DBG_SEGMENT_NAME_OUT_OF_RANGE if pszName is too short or long.
1138 * @retval VERR_INVALID_PARAMETER if fFlags contains undefined flags.
1139 * @retval VERR_DBG_SPECIAL_SEGMENT if *piSeg is a special segment.
1140 * @retval VERR_DBG_INVALID_SEGMENT_INDEX if *piSeg doesn't meet expectations.
1141 *
1142 * @param hDbgMod The module handle.
1143 * @param uRva The image relative address of the segment.
1144 * @param cb The size of the segment.
1145 * @param pszName The segment name. Does not normally need to be
1146 * unique, although this is somewhat up to the
1147 * debug interpreter to decide.
1148 * @param fFlags Segment flags. Reserved for future used, MBZ.
1149 * @param piSeg The segment index or NIL_RTDBGSEGIDX on input.
1150 * The assigned segment index on successful return.
1151 * Optional.
1152 */
1153RTDECL(int) RTDbgModSegmentAdd(RTDBGMOD hDbgMod, RTUINTPTR uRva, RTUINTPTR cb, const char *pszName,
1154 uint32_t fFlags, PRTDBGSEGIDX piSeg);
1155
1156/**
1157 * Gets the number of segments in the module.
1158 *
1159 * This is can be used to determine the range which can be passed to
1160 * RTDbgModSegmentByIndex and derivates.
1161 *
1162 * @returns The segment relative address.
1163 * NIL_RTDBGSEGIDX if the handle is invalid.
1164 *
1165 * @param hDbgMod The module handle.
1166 */
1167RTDECL(RTDBGSEGIDX) RTDbgModSegmentCount(RTDBGMOD hDbgMod);
1168
1169/**
1170 * Query information about a segment.
1171 *
1172 * This can be used together with RTDbgModSegmentCount to enumerate segments.
1173 * The index starts a 0 and stops one below RTDbgModSegmentCount.
1174 *
1175 * @returns IPRT status code.
1176 * @retval VERR_DBG_INVALID_SEGMENT_INDEX if iSeg is too high.
1177 * @retval VERR_DBG_SPECIAL_SEGMENT if iSeg indicates a special segment.
1178 * @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1179 *
1180 * @param hDbgMod The module handle.
1181 * @param iSeg The segment index. No special segments.
1182 * @param pSegInfo Where to return the segment info. The
1183 * RTDBGSEGMENT::Address member will be set to
1184 * RTUINTPTR_MAX or the load address used at link time.
1185 */
1186RTDECL(int) RTDbgModSegmentByIndex(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, PRTDBGSEGMENT pSegInfo);
1187
1188/**
1189 * Gets the size of a segment.
1190 *
1191 * This is a just a wrapper around RTDbgModSegmentByIndex.
1192 *
1193 * @returns The segment size.
1194 * RTUINTPTR_MAX is returned if either the handle and segment index are
1195 * invalid.
1196 *
1197 * @param hDbgMod The module handle.
1198 * @param iSeg The segment index. RTDBGSEGIDX_ABS is not allowed.
1199 * If RTDBGSEGIDX_RVA is used, the functions returns
1200 * the same value as RTDbgModImageSize.
1201 */
1202RTDECL(RTUINTPTR) RTDbgModSegmentSize(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg);
1203
1204/**
1205 * Gets the image relative address of a segment.
1206 *
1207 * This is a just a wrapper around RTDbgModSegmentByIndex.
1208 *
1209 * @returns The segment relative address.
1210 * RTUINTPTR_MAX is returned if either the handle and segment index are
1211 * invalid.
1212 *
1213 * @param hDbgMod The module handle.
1214 * @param iSeg The segment index. No special segment indexes
1215 * allowed (asserted).
1216 */
1217RTDECL(RTUINTPTR) RTDbgModSegmentRva(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg);
1218
1219
1220/**
1221 * Adds a line number to the module.
1222 *
1223 * @returns IPRT status code.
1224 * @retval VERR_NOT_SUPPORTED if the module interpret doesn't support adding
1225 * custom symbols. This is a common place occurrence.
1226 * @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1227 * @retval VERR_DBG_SYMBOL_NAME_OUT_OF_RANGE if the symbol name is too long or
1228 * short.
1229 * @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
1230 * it's not inside any of the segments defined by the module.
1231 * @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
1232 * @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
1233 * end of the segment.
1234 * @retval VERR_DBG_ADDRESS_WRAP if off+cb wraps around.
1235 * @retval VERR_INVALID_PARAMETER if the symbol flags sets undefined bits.
1236 *
1237 * @param hDbgMod The module handle.
1238 * @param pszSymbol The symbol name.
1239 * @param iSeg The segment index.
1240 * @param off The segment offset.
1241 * @param cb The size of the symbol. Can be zero, although this
1242 * may depend somewhat on the debug interpreter.
1243 * @param fFlags Symbol flags. Reserved for the future, MBZ.
1244 * @param piOrdinal Where to return the symbol ordinal on success. If
1245 * the interpreter doesn't do ordinals, this will be set to
1246 * UINT32_MAX. Optional.
1247 */
1248RTDECL(int) RTDbgModSymbolAdd(RTDBGMOD hDbgMod, const char *pszSymbol, RTDBGSEGIDX iSeg, RTUINTPTR off,
1249 RTUINTPTR cb, uint32_t fFlags, uint32_t *piOrdinal);
1250
1251/**
1252 * Gets the symbol count.
1253 *
1254 * This can be used together wtih RTDbgModSymbolByOrdinal or
1255 * RTDbgModSymbolByOrdinalA to enumerate all the symbols.
1256 *
1257 * @returns The number of symbols in the module.
1258 * UINT32_MAX is returned if the module handle is invalid or some other
1259 * error occurs.
1260 *
1261 * @param hDbgMod The module handle.
1262 */
1263RTDECL(uint32_t) RTDbgModSymbolCount(RTDBGMOD hDbgMod);
1264
1265/**
1266 * Queries symbol information by ordinal number.
1267 *
1268 * @returns IPRT status code.
1269 * @retval VERR_SYMBOL_NOT_FOUND if there is no symbol at the given number.
1270 * @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
1271 * @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1272 * @retval VERR_NOT_SUPPORTED if lookup by ordinal is not supported.
1273 *
1274 * @param hDbgMod The module handle.
1275 * @param iOrdinal The symbol ordinal number. 0-based. The highest
1276 * number is RTDbgModSymbolCount() - 1.
1277 * @param pSymInfo Where to store the symbol information.
1278 */
1279RTDECL(int) RTDbgModSymbolByOrdinal(RTDBGMOD hDbgMod, uint32_t iOrdinal, PRTDBGSYMBOL pSymInfo);
1280
1281/**
1282 * Queries symbol information by ordinal number.
1283 *
1284 * @returns IPRT status code.
1285 * @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
1286 * @retval VERR_NOT_SUPPORTED if lookup by ordinal is not supported.
1287 * @retval VERR_SYMBOL_NOT_FOUND if there is no symbol at the given number.
1288 * @retval VERR_NO_MEMORY if RTDbgSymbolAlloc fails.
1289 *
1290 * @param hDbgMod The module handle.
1291 * @param iOrdinal The symbol ordinal number. 0-based. The highest
1292 * number is RTDbgModSymbolCount() - 1.
1293 * @param ppSymInfo Where to store the pointer to the returned
1294 * symbol information. Always set. Free with
1295 * RTDbgSymbolFree.
1296 */
1297RTDECL(int) RTDbgModSymbolByOrdinalA(RTDBGMOD hDbgMod, uint32_t iOrdinal, PRTDBGSYMBOL *ppSymInfo);
1298
1299/**
1300 * Queries symbol information by address.
1301 *
1302 * The returned symbol is what the debug info interpreter considers the symbol
1303 * most applicable to the specified address. This usually means a symbol with an
1304 * address equal or lower than the requested.
1305 *
1306 * @returns IPRT status code.
1307 * @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
1308 * @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
1309 * @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1310 * @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
1311 * it's not inside any of the segments defined by the module.
1312 * @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
1313 * @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
1314 * end of the segment.
1315 * @retval VERR_INVALID_PARAMETER if incorrect flags.
1316 *
1317 * @param hDbgMod The module handle.
1318 * @param iSeg The segment number.
1319 * @param off The offset into the segment.
1320 * @param fFlags Symbol search flags, see RTDBGSYMADDR_FLAGS_XXX.
1321 * @param poffDisp Where to store the distance between the
1322 * specified address and the returned symbol.
1323 * Optional.
1324 * @param pSymInfo Where to store the symbol information.
1325 */
1326RTDECL(int) RTDbgModSymbolByAddr(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, uint32_t fFlags,
1327 PRTINTPTR poffDisp, PRTDBGSYMBOL pSymInfo);
1328
1329/**
1330 * Queries symbol information by address.
1331 *
1332 * The returned symbol is what the debug info interpreter considers the symbol
1333 * most applicable to the specified address. This usually means a symbol with an
1334 * address equal or lower than the requested.
1335 *
1336 * @returns IPRT status code.
1337 * @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
1338 * @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
1339 * @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1340 * @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
1341 * it's not inside any of the segments defined by the module.
1342 * @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
1343 * @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
1344 * end of the segment.
1345 * @retval VERR_NO_MEMORY if RTDbgSymbolAlloc fails.
1346 * @retval VERR_INVALID_PARAMETER if incorrect flags.
1347 *
1348 * @param hDbgMod The module handle.
1349 * @param iSeg The segment index.
1350 * @param off The offset into the segment.
1351 * @param fFlags Symbol search flags, see RTDBGSYMADDR_FLAGS_XXX.
1352 * @param poffDisp Where to store the distance between the
1353 * specified address and the returned symbol. Optional.
1354 * @param ppSymInfo Where to store the pointer to the returned
1355 * symbol information. Always set. Free with
1356 * RTDbgSymbolFree.
1357 */
1358RTDECL(int) RTDbgModSymbolByAddrA(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, uint32_t fFlags,
1359 PRTINTPTR poffDisp, PRTDBGSYMBOL *ppSymInfo);
1360
1361/**
1362 * Queries symbol information by symbol name.
1363 *
1364 * @returns IPRT status code.
1365 * @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
1366 * @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
1367 * @retval VERR_DBG_SYMBOL_NAME_OUT_OF_RANGE if the symbol name is too long or
1368 * short.
1369 *
1370 * @param hDbgMod The module handle.
1371 * @param pszSymbol The symbol name.
1372 * @param pSymInfo Where to store the symbol information.
1373 */
1374RTDECL(int) RTDbgModSymbolByName(RTDBGMOD hDbgMod, const char *pszSymbol, PRTDBGSYMBOL pSymInfo);
1375
1376/**
1377 * Queries symbol information by symbol name.
1378 *
1379 * @returns IPRT status code.
1380 * @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
1381 * @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
1382 * @retval VERR_DBG_SYMBOL_NAME_OUT_OF_RANGE if the symbol name is too long or
1383 * short.
1384 * @retval VERR_NO_MEMORY if RTDbgSymbolAlloc fails.
1385 *
1386 * @param hDbgMod The module handle.
1387 * @param pszSymbol The symbol name.
1388 * @param ppSymInfo Where to store the pointer to the returned
1389 * symbol information. Always set. Free with
1390 * RTDbgSymbolFree.
1391 */
1392RTDECL(int) RTDbgModSymbolByNameA(RTDBGMOD hDbgMod, const char *pszSymbol, PRTDBGSYMBOL *ppSymInfo);
1393
1394/**
1395 * Adds a line number to the module.
1396 *
1397 * @returns IPRT status code.
1398 * @retval VERR_NOT_SUPPORTED if the module interpret doesn't support adding
1399 * custom symbols. This should be consider a normal response.
1400 * @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1401 * @retval VERR_DBG_FILE_NAME_OUT_OF_RANGE if the file name is too longer or
1402 * empty.
1403 * @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
1404 * it's not inside any of the segments defined by the module.
1405 * @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
1406 * @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
1407 * end of the segment.
1408 * @retval VERR_INVALID_PARAMETER if the line number flags sets undefined bits.
1409 *
1410 * @param hDbgMod The module handle.
1411 * @param pszFile The file name.
1412 * @param uLineNo The line number.
1413 * @param iSeg The segment index.
1414 * @param off The segment offset.
1415 * @param piOrdinal Where to return the line number ordinal on
1416 * success. If the interpreter doesn't do ordinals,
1417 * this will be set to UINT32_MAX. Optional.
1418 */
1419RTDECL(int) RTDbgModLineAdd(RTDBGMOD hDbgMod, const char *pszFile, uint32_t uLineNo,
1420 RTDBGSEGIDX iSeg, RTUINTPTR off, uint32_t *piOrdinal);
1421
1422/**
1423 * Gets the line number count.
1424 *
1425 * This can be used together wtih RTDbgModLineByOrdinal or RTDbgModSymbolByLineA
1426 * to enumerate all the line number information.
1427 *
1428 * @returns The number of line numbers in the module.
1429 * UINT32_MAX is returned if the module handle is invalid or some other
1430 * error occurs.
1431 *
1432 * @param hDbgMod The module handle.
1433 */
1434RTDECL(uint32_t) RTDbgModLineCount(RTDBGMOD hDbgMod);
1435
1436/**
1437 * Queries line number information by ordinal number.
1438 *
1439 * This can be used to enumerate the line numbers for the module. Use
1440 * RTDbgModLineCount() to figure the end of the ordinals.
1441 *
1442 * @returns IPRT status code.
1443 * @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
1444 * @retval VERR_DBG_LINE_NOT_FOUND if there is no line number with that
1445 * ordinal.
1446 * @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1447
1448 * @param hDbgMod The module handle.
1449 * @param iOrdinal The line number ordinal number.
1450 * @param pLineInfo Where to store the information about the line
1451 * number.
1452 */
1453RTDECL(int) RTDbgModLineByOrdinal(RTDBGMOD hDbgMod, uint32_t iOrdinal, PRTDBGLINE pLineInfo);
1454
1455/**
1456 * Queries line number information by ordinal number.
1457 *
1458 * This can be used to enumerate the line numbers for the module. Use
1459 * RTDbgModLineCount() to figure the end of the ordinals.
1460 *
1461 * @returns IPRT status code.
1462 * @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
1463 * @retval VERR_DBG_LINE_NOT_FOUND if there is no line number with that
1464 * ordinal.
1465 * @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1466 * @retval VERR_NO_MEMORY if RTDbgLineAlloc fails.
1467 *
1468 * @param hDbgMod The module handle.
1469 * @param iOrdinal The line number ordinal number.
1470 * @param ppLineInfo Where to store the pointer to the returned line
1471 * number information. Always set. Free with
1472 * RTDbgLineFree.
1473 */
1474RTDECL(int) RTDbgModLineByOrdinalA(RTDBGMOD hDbgMod, uint32_t iOrdinal, PRTDBGLINE *ppLineInfo);
1475
1476/**
1477 * Queries line number information by address.
1478 *
1479 * The returned line number is what the debug info interpreter considers the
1480 * one most applicable to the specified address. This usually means a line
1481 * number with an address equal or lower than the requested.
1482 *
1483 * @returns IPRT status code.
1484 * @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
1485 * @retval VERR_DBG_LINE_NOT_FOUND if no suitable line number was found.
1486 * @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1487 * @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
1488 * it's not inside any of the segments defined by the module.
1489 * @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
1490 * @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
1491 * end of the segment.
1492 *
1493 * @param hDbgMod The module handle.
1494 * @param iSeg The segment number.
1495 * @param off The offset into the segment.
1496 * @param poffDisp Where to store the distance between the
1497 * specified address and the returned symbol.
1498 * Optional.
1499 * @param pLineInfo Where to store the line number information.
1500 */
1501RTDECL(int) RTDbgModLineByAddr(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGLINE pLineInfo);
1502
1503/**
1504 * Queries line number information by address.
1505 *
1506 * The returned line number is what the debug info interpreter considers the
1507 * one most applicable to the specified address. This usually means a line
1508 * number with an address equal or lower than the requested.
1509 *
1510 * @returns IPRT status code.
1511 * @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
1512 * @retval VERR_DBG_LINE_NOT_FOUND if no suitable line number was found.
1513 * @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1514 * @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
1515 * it's not inside any of the segments defined by the module.
1516 * @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
1517 * @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
1518 * end of the segment.
1519 * @retval VERR_NO_MEMORY if RTDbgLineAlloc fails.
1520 *
1521 * @param hDbgMod The module handle.
1522 * @param iSeg The segment number.
1523 * @param off The offset into the segment.
1524 * @param poffDisp Where to store the distance between the
1525 * specified address and the returned symbol.
1526 * Optional.
1527 * @param ppLineInfo Where to store the pointer to the returned line
1528 * number information. Always set. Free with
1529 * RTDbgLineFree.
1530 */
1531RTDECL(int) RTDbgModLineByAddrA(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGLINE *ppLineInfo);
1532/** @} */
1533
1534# endif /* IN_RING3 */
1535
1536
1537/** @name Kernel Debug Info API
1538 *
1539 * This is a specialized API for obtaining symbols and structure information
1540 * about the running kernel. It is relatively OS specific. Its purpose and
1541 * operation is doesn't map all that well onto RTDbgMod, so a few dedicated
1542 * functions was created for it.
1543 *
1544 * @{ */
1545
1546/** Handle to the kernel debug info. */
1547typedef struct RTDBGKRNLINFOINT *RTDBGKRNLINFO;
1548/** Pointer to a kernel debug info handle. */
1549typedef RTDBGKRNLINFO *PRTDBGKRNLINFO;
1550/** Nil kernel debug info handle. */
1551#define NIL_RTDBGKRNLINFO ((RTDBGKRNLINFO)0)
1552
1553/**
1554 * Opens the kernel debug info.
1555 *
1556 * @returns IPRT status code. Can fail for any number of reasons.
1557 *
1558 * @param phKrnlInfo Where to return the kernel debug info handle on
1559 * success.
1560 * @param fFlags Flags reserved for future use. Must be zero.
1561 */
1562RTR0DECL(int) RTR0DbgKrnlInfoOpen(PRTDBGKRNLINFO phKrnlInfo, uint32_t fFlags);
1563
1564/**
1565 * Retains a reference to the kernel debug info handle.
1566 *
1567 * @returns New reference count, UINT32_MAX on invalid handle (asserted).
1568 * @param hKrnlInfo The kernel info handle.
1569 */
1570RTR0DECL(uint32_t) RTR0DbgKrnlInfoRetain(RTDBGKRNLINFO hKrnlInfo);
1571
1572
1573/**
1574 * Releases a reference to the kernel debug info handle, destroying it when the
1575 * counter reaches zero.
1576 *
1577 * @returns New reference count, UINT32_MAX on invalid handle (asserted).
1578 * @param hKrnlInfo The kernel info handle. NIL_RTDBGKRNLINFO is
1579 * quietly ignored.
1580 */
1581RTR0DECL(uint32_t) RTR0DbgKrnlInfoRelease(RTDBGKRNLINFO hKrnlInfo);
1582
1583/**
1584 * Queries the offset (in bytes) of a member of a kernel structure.
1585 *
1586 * @returns IPRT status code.
1587 * @retval VINF_SUCCESS and offset at @a poffMember.
1588 * @retval VERR_NOT_FOUND if the structure or the member was not found.
1589 * @retval VERR_INVALID_HANDLE if hKrnlInfo is bad.
1590 * @retval VERR_INVALID_POINTER if any of the pointers are bad.
1591 *
1592 * @param hKrnlInfo The kernel info handle.
1593 * @param pszModule The name of the module to search, pass NULL to
1594 * search the default kernel module(s).
1595 * @param pszStructure The structure name.
1596 * @param pszMember The member name.
1597 * @param poffMember Where to return the offset.
1598 */
1599RTR0DECL(int) RTR0DbgKrnlInfoQueryMember(RTDBGKRNLINFO hKrnlInfo, const char *pszModule, const char *pszStructure,
1600 const char *pszMember, size_t *poffMember);
1601
1602
1603/**
1604 * Queries the value (usually the address) of a kernel symbol.
1605 *
1606 * This may go looking for the symbol in other modules, in which case it will
1607 * always check the kernel symbol table first.
1608 *
1609 * @returns IPRT status code.
1610 * @retval VINF_SUCCESS and value at @a ppvSymbol.
1611 * @retval VERR_SYMBOL_NOT_FOUND
1612 * @retval VERR_INVALID_HANDLE if hKrnlInfo is bad.
1613 * @retval VERR_INVALID_POINTER if any of the pointers are bad.
1614 *
1615 * @param hKrnlInfo The kernel info handle.
1616 * @param pszModule Reserved for future extensions. Pass NULL.
1617 * @param pszSymbol The C name of the symbol.
1618 * @param ppvSymbol Where to return the symbol value, passing NULL is
1619 * OK. This may be modified even on failure, in
1620 * particular, it will be set to NULL when
1621 * VERR_SYMBOL_NOT_FOUND is returned.
1622 *
1623 * @sa RTLdrGetSymbol.
1624 */
1625RTR0DECL(int) RTR0DbgKrnlInfoQuerySymbol(RTDBGKRNLINFO hKrnlInfo, const char *pszModule,
1626 const char *pszSymbol, void **ppvSymbol);
1627
1628
1629/**
1630 * Queries the size (in bytes) of a kernel data type.
1631 *
1632 * @returns IPRT status code.
1633 * @retval VINF_SUCCESS and size at @a pcbType.
1634 * @retval VERR_NOT_FOUND if the type was not found.
1635 * @retval VERR_INVALID_HANDLE if hKrnlInfo is bad.
1636 * @retval VERR_INVALID_POINTER if any of the pointers are bad.
1637 * @retval VERR_WRONG_TYPE if the type was not a valid data type (e.g. a
1638 * function)
1639 *
1640 * @param hKrnlInfo The kernel info handle.
1641 * @param pszModule The name of the module to search, pass NULL to
1642 * search the default kernel module(s).
1643 * @param pszType The type name.
1644 * @param pcbType Where to return the size of the type.
1645 */
1646RTR0DECL(int) RTR0DbgKrnlInfoQuerySize(RTDBGKRNLINFO hKrnlInfo, const char *pszModule,
1647 const char *pszType, size_t *pcbType);
1648/** @} */
1649
1650/** @} */
1651
1652RT_C_DECLS_END
1653
1654#endif
1655
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette