2
* Copyright (c) 2017, 2023, Oracle and/or its affiliates. All rights reserved.
3
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
5
* This code is free software; you can redistribute it and/or modify it
6
* under the terms of the GNU General Public License version 2 only, as
7
* published by the Free Software Foundation.
9
* This code is distributed in the hope that it will be useful, but WITHOUT
10
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
12
* version 2 for more details (a copy is included in the LICENSE file that
13
* accompanied this code).
15
* You should have received a copy of the GNU General Public License version
16
* 2 along with this work; if not, write to the Free Software Foundation,
17
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
19
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
20
* or visit www.oracle.com if you need additional information or have any
25
#include "precompiled.hpp"
26
#include "utilities/globalDefinitions.hpp"
27
#include "symbolengine.hpp"
28
#include "utilities/debug.hpp"
29
#include "utilities/ostream.hpp"
30
#include "windbghelp.hpp"
39
// This code may be invoked normally but also as part of error reporting
40
// In the latter case, we may run under tight memory constraints (native oom)
41
// or in a stack overflow situation or the C heap may be corrupted. We may
42
// run very early before VM initialization or very late when C exit handlers
43
// run. In all these cases, callstacks would still be nice, so lets be robust.
45
// We need a number of buffers - for the pdb search path, module handle
46
// lists, for demangled symbols, etc.
48
// These buffers, while typically small, may need to be large for corner
49
// cases (e.g. templatized C++ symbols, or many DLLs loaded). Where do we
52
// We may be in error handling for a stack overflow, so lets not put them on
55
// Dynamically allocating them may fail if we are handling a native OOM. It
56
// is also a bit dangerous, as the C heap may be corrupted already.
58
// That leaves pre-allocating them globally, which is safe and should always
59
// work (if we synchronize access) but incurs an undesirable footprint for
62
// We follow a two-way strategy: Allocate the buffers on the C heap in a
63
// reasonable large size. Failing that, fall back to static preallocated
64
// buffers. The size of the latter is large enough to handle common scenarios
65
// but small enough not to drive up the footprint too much (several kb).
67
// We keep these buffers around once allocated, for subsequent requests. This
68
// means that by running the initialization early at a safe time - before
69
// any error happens - buffers can be pre-allocated. This increases the chance
70
// of useful callstacks in error scenarios in exchange for a some cycles spent
71
// at startup. This behavior can be controlled with -XX:+InitializeDbgHelpEarly
72
// and is off by default.
76
// A simple buffer which attempts to allocate an optimal size but will
77
// fall back to a static minimally sized array on allocation error.
78
template <class T, int MINIMAL_CAPACITY, int OPTIMAL_CAPACITY>
79
class SimpleBufferWithFallback {
80
T _fallback_buffer[MINIMAL_CAPACITY];
84
// A sentinel at the end of the buffer to catch overflows.
85
void imprint_sentinel() {
86
assert(_p && _capacity > 0, "Buffer must be allocated");
87
_p[_capacity - 1] = (T)'X';
93
SimpleBufferWithFallback<T, MINIMAL_CAPACITY, OPTIMAL_CAPACITY> ()
94
: _p(nullptr), _capacity(0)
97
// Note: no destructor because these buffers should, once
98
// allocated, live until process end.
99
// ~SimpleBufferWithFallback()
101
// Note: We use raw ::malloc/::free here instead of os::malloc()/os::free
102
// to prevent circularities or secondary crashes during error reporting.
103
virtual void initialize () {
104
assert(_p == nullptr && _capacity == 0, "Only call once.");
105
const size_t bytes = OPTIMAL_CAPACITY * sizeof(T);
106
T* q = (T*) ::malloc(bytes);
109
_capacity = OPTIMAL_CAPACITY;
111
_p = _fallback_buffer;
112
_capacity = (int)(sizeof(_fallback_buffer) / sizeof(T));
118
// We need a way to reset the buffer to fallback size for one special
119
// case, where two buffers need to be of identical capacity.
120
void reset_to_fallback_capacity() {
121
if (_p != _fallback_buffer) {
124
_p = _fallback_buffer;
125
_capacity = (int)(sizeof(_fallback_buffer) / sizeof(T));
130
T* ptr() { return _p; }
131
const T* ptr() const { return _p; }
132
int capacity() const { return _capacity; }
136
assert(_p[_capacity] == (T)'X', "sentinel lost");
139
void check() const {}
146
// ModuleHandleArray: a list holding module handles. Needs to be large enough
147
// to hold one handle per loaded DLL.
148
// Note: a standard OpenJDK loads normally ~30 libraries, including system
149
// libraries, without third party libraries.
151
typedef SimpleBufferWithFallback <HMODULE, 48, 512> ModuleHandleArrayBase;
153
class ModuleHandleArray : public ModuleHandleArrayBase {
155
int _num; // Number of handles in this array (may be < capacity).
160
ModuleHandleArrayBase::initialize();
164
int num() const { return _num; }
165
void set_num(int n) {
166
assert(n <= capacity(), "Too large");
170
// Compare with another list; returns true if all handles are equal (incl.
172
bool equals(const ModuleHandleArray& other) const {
173
if (_num != other._num) {
176
if (::memcmp(ptr(), other.ptr(), _num * sizeof(HMODULE)) != 0) {
182
// Copy content from other list.
183
void copy_content_from(ModuleHandleArray& other) {
184
assert(capacity() == other.capacity(), "Different capacities.");
185
memcpy(ptr(), other.ptr(), other._num * sizeof(HMODULE));
193
// PathBuffer: a buffer to hold and work with a pdb search PATH - a concatenation
194
// of multiple directories separated by ';'.
195
// A single directory name can be (NTFS) as long as 32K, but in reality is
196
// seldom larger than the (historical) MAX_PATH of 260.
198
#define MINIMUM_PDB_PATH_LENGTH MAX_PATH * 4
199
#define OPTIMAL_PDB_PATH_LENGTH MAX_PATH * 64
201
typedef SimpleBufferWithFallback<char, MINIMUM_PDB_PATH_LENGTH, OPTIMAL_PDB_PATH_LENGTH> PathBufferBase;
203
class PathBuffer: public PathBufferBase {
206
// Search PDB path for a directory. Search is case insensitive. Returns
207
// true if directory was found in the path, false otherwise.
208
bool contains_directory(const char* directory) {
209
if (ptr() == nullptr) {
212
const size_t len = strlen(directory);
218
char* q = strchr(p, ';');
220
if (len == (q - p)) {
221
if (_strnicmp(p, directory, len) == 0) {
228
return _stricmp(p, directory) == 0;
234
// Appends the given directory to the path. Returns false if internal
235
// buffer size was not sufficient.
236
bool append_directory(const char* directory) {
237
const size_t len = strlen(directory);
242
const size_t len_now = strlen(p);
243
const size_t needs_capacity = len_now + 1 + len + 1; // xxx;yy\0
244
if (needs_capacity > (size_t)capacity()) {
247
if (len_now > 0) { // Not the first path element.
252
strcpy(p, directory);
258
// A simple buffer to hold one single file name. A file name can be (NTFS) as
259
// long as 32K, but in reality is seldom larger than MAX_PATH.
260
typedef SimpleBufferWithFallback<char, MAX_PATH, 8 * K> FileNameBuffer;
262
// A buffer to hold a C++ symbol. Usually small, but symbols may be larger for
264
#define MINIMUM_SYMBOL_NAME_LEN 128
265
#define OPTIMAL_SYMBOL_NAME_LEN 1024
267
typedef SimpleBufferWithFallback<uint8_t,
268
sizeof(IMAGEHLP_SYMBOL64) + MINIMUM_SYMBOL_NAME_LEN,
269
sizeof(IMAGEHLP_SYMBOL64) + OPTIMAL_SYMBOL_NAME_LEN> SymbolBuffer;
273
// Two buffers to hold lists of loaded modules. handles across invocations of
274
// SymbolEngine::recalc_search_path().
275
ModuleHandleArray loaded_modules;
276
ModuleHandleArray last_loaded_modules;
277
// Buffer to retrieve and assemble the pdb search path.
278
PathBuffer search_path;
279
// Buffer to retrieve directory names for loaded modules.
280
FileNameBuffer dir_name;
281
// Buffer to retrieve decoded symbol information (in SymbolEngine::decode)
282
SymbolBuffer decode_buffer;
285
search_path.initialize();
286
dir_name.initialize();
287
decode_buffer.initialize();
289
loaded_modules.initialize();
290
last_loaded_modules.initialize();
292
// Note: both module lists must have the same capacity. If one allocation
293
// did fail, let them both fall back to the fallback size.
294
if (loaded_modules.capacity() != last_loaded_modules.capacity()) {
295
loaded_modules.reset_to_fallback_capacity();
296
last_loaded_modules.reset_to_fallback_capacity();
299
assert(search_path.capacity() > 0 && dir_name.capacity() > 0 &&
300
decode_buffer.capacity() > 0 && loaded_modules.capacity() > 0 &&
301
last_loaded_modules.capacity() > 0, "Init error.");
307
// Scan the loaded modules.
309
// For each loaded module, add the directory it is located in to the pdb search
310
// path, but avoid duplicates. Prior search path content is preserved.
312
// If p_search_path_was_updated is not null, points to a bool which, upon
313
// successful return from the function, contains true if the search path
314
// was updated, false if no update was needed because no new DLLs were
315
// loaded or unloaded.
317
// Returns true for success, false for error.
318
static bool recalc_search_path_locked(bool* p_search_path_was_updated) {
320
if (p_search_path_was_updated) {
321
*p_search_path_was_updated = false;
324
HANDLE hProcess = ::GetCurrentProcess();
326
BOOL success = false;
328
// 1) Retrieve current set search path.
329
// (PDB search path is a global setting and someone might have modified
330
// it, so take care not to remove directories, just to add our own).
332
if (!WindowsDbgHelp::symGetSearchPath(hProcess, g_buffers.search_path.ptr(),
333
(int)g_buffers.search_path.capacity())) {
336
DEBUG_ONLY(g_buffers.search_path.check();)
338
// 2) Retrieve list of modules handles of all currently loaded modules.
339
DWORD bytes_needed = 0;
340
const DWORD buffer_capacity_bytes = (DWORD)g_buffers.loaded_modules.capacity() * sizeof(HMODULE);
341
success = ::EnumProcessModules(hProcess, g_buffers.loaded_modules.ptr(),
342
buffer_capacity_bytes, &bytes_needed);
343
DEBUG_ONLY(g_buffers.loaded_modules.check();)
345
// Note: EnumProcessModules is sloppily defined in terms of whether a
346
// too-small output buffer counts as error. Will it truncate but still
347
// return TRUE? Nobody knows and the manpage is not telling. So we count
348
// truncation it as error, disregarding the return value.
349
if (!success || bytes_needed > buffer_capacity_bytes) {
352
const int num_modules = bytes_needed / sizeof(HMODULE);
353
g_buffers.loaded_modules.set_num(num_modules);
356
// Compare the list of module handles with the last list. If the lists are
357
// identical, no additional dlls were loaded and we can stop.
358
if (g_buffers.loaded_modules.equals(g_buffers.last_loaded_modules)) {
361
// Remember the new set of module handles and continue.
362
g_buffers.last_loaded_modules.copy_content_from(g_buffers.loaded_modules);
365
// 3) For each loaded module: retrieve directory from which it was loaded.
366
// Add directory to search path (but avoid duplicates).
368
bool did_modify_searchpath = false;
370
for (int i = 0; i < (int)g_buffers.loaded_modules.num(); i ++) {
372
const HMODULE hMod = g_buffers.loaded_modules.ptr()[i];
373
char* const filebuffer = g_buffers.dir_name.ptr();
374
const int file_buffer_capacity = g_buffers.dir_name.capacity();
375
const int len_returned = (int)::GetModuleFileName(hMod, filebuffer, (DWORD)file_buffer_capacity);
376
DEBUG_ONLY(g_buffers.dir_name.check();)
377
if (len_returned == 0) {
378
// This may happen when a module gets unloaded after our call to EnumProcessModules.
379
// It should be rare but may sporadically happen. Just ignore and continue with the
382
} else if (len_returned == file_buffer_capacity) {
383
// Truncation. Just skip this module and continue with the next module.
387
// Cut file name part off.
388
char* last_slash = ::strrchr(filebuffer, '\\');
389
if (last_slash == nullptr) {
390
last_slash = ::strrchr(filebuffer, '/');
396
// If this is already part of the search path, ignore it, otherwise
397
// append to search path.
398
if (!g_buffers.search_path.contains_directory(filebuffer)) {
399
if (!g_buffers.search_path.append_directory(filebuffer)) {
402
DEBUG_ONLY(g_buffers.search_path.check();)
403
did_modify_searchpath = true;
406
} // for each loaded module.
408
// If we did not modify the search path, nothing further needs to be done.
409
if (!did_modify_searchpath) {
413
// Set the search path to its new value.
414
if (!WindowsDbgHelp::symSetSearchPath(hProcess, g_buffers.search_path.ptr())) {
418
if (p_search_path_was_updated) {
419
*p_search_path_was_updated = true;
426
static bool demangle_locked(const char* symbol, char *buf, int buflen) {
428
return WindowsDbgHelp::unDecorateSymbolName(symbol, buf, buflen, UNDNAME_COMPLETE) > 0;
432
static bool decode_locked(const void* addr, char* buf, int buflen, int* offset, bool do_demangle) {
434
assert(g_buffers.decode_buffer.capacity() >= (sizeof(IMAGEHLP_SYMBOL64) + MINIMUM_SYMBOL_NAME_LEN),
435
"Decode buffer too small.");
436
assert(buf != nullptr && buflen > 0 && offset != nullptr, "invalid output buffer.");
438
DWORD64 displacement;
439
PIMAGEHLP_SYMBOL64 pSymbol = nullptr;
440
bool success = false;
442
pSymbol = (PIMAGEHLP_SYMBOL64) g_buffers.decode_buffer.ptr();
443
pSymbol->SizeOfStruct = sizeof(IMAGEHLP_SYMBOL64);
444
pSymbol->MaxNameLength = (DWORD)(g_buffers.decode_buffer.capacity() - sizeof(IMAGEHLP_SYMBOL64) - 1);
446
// It is unclear how SymGetSymFromAddr64 handles truncation. Experiments
447
// show it will return TRUE but not zero terminate (which is a really bad
448
// combination). Lets be super careful.
449
::memset(pSymbol->Name, 0, pSymbol->MaxNameLength); // To catch truncation.
451
if (WindowsDbgHelp::symGetSymFromAddr64(::GetCurrentProcess(), (DWORD64)addr, &displacement, pSymbol)) {
453
if (pSymbol->Name[pSymbol->MaxNameLength - 1] != '\0') {
454
// Symbol was truncated. Do not attempt to demangle. Instead, zero terminate the
455
// truncated string. We still return success - the truncated string may still
456
// be usable for the caller.
457
pSymbol->Name[pSymbol->MaxNameLength - 1] = '\0';
461
// Attempt to demangle.
462
if (do_demangle && demangle_locked(pSymbol->Name, buf, buflen)) {
465
::strncpy(buf, pSymbol->Name, buflen - 1);
467
buf[buflen - 1] = '\0';
469
*offset = (int)displacement;
472
DEBUG_ONLY(g_buffers.decode_buffer.check();)
478
state_uninitialized = 0,
481
} g_state = state_uninitialized;
483
static void initialize() {
485
assert(g_state == state_uninitialized, "wrong sequence");
486
g_state = state_error;
488
// 1) Initialize buffers.
489
g_buffers.initialize();
491
// 1) Call SymInitialize
492
HANDLE hProcess = ::GetCurrentProcess();
493
WindowsDbgHelp::symSetOptions(SYMOPT_FAIL_CRITICAL_ERRORS | SYMOPT_DEFERRED_LOADS |
494
SYMOPT_EXACT_SYMBOLS | SYMOPT_LOAD_LINES);
495
if (!WindowsDbgHelp::symInitialize(hProcess, nullptr, TRUE)) {
499
// Note: we ignore any errors from this point on. The symbol engine may be
501
g_state = state_ready;
503
(void)recalc_search_path_locked(nullptr);
507
///////////////////// External functions //////////////////////////
509
// All outside facing functions are synchronized. Also, we run
510
// initialization on first touch.
512
static CRITICAL_SECTION g_cs;
514
namespace { // Do not export.
515
class SymbolEngineEntry {
517
SymbolEngineEntry() {
518
::EnterCriticalSection(&g_cs);
519
if (g_state == state_uninitialized) {
523
~SymbolEngineEntry() {
524
::LeaveCriticalSection(&g_cs);
529
// Called at DLL_PROCESS_ATTACH.
530
void SymbolEngine::pre_initialize() {
531
::InitializeCriticalSection(&g_cs);
534
bool SymbolEngine::decode(const void* addr, char* buf, int buflen, int* offset, bool do_demangle) {
536
assert(buf != nullptr && buflen > 0 && offset != nullptr, "Argument error");
540
if (addr == nullptr) {
544
SymbolEngineEntry entry_guard;
546
// Try decoding the symbol once. If we fail, attempt to rebuild the
547
// symbol search path - maybe the pc points to a dll whose pdb file is
548
// outside our search path. Then do attempt the decode again.
549
bool success = decode_locked(addr, buf, buflen, offset, do_demangle);
551
bool did_update_search_path = false;
552
if (recalc_search_path_locked(&did_update_search_path)) {
553
if (did_update_search_path) {
554
success = decode_locked(addr, buf, buflen, offset, do_demangle);
563
bool SymbolEngine::demangle(const char* symbol, char *buf, int buflen) {
565
SymbolEngineEntry entry_guard;
567
return demangle_locked(symbol, buf, buflen);
571
bool SymbolEngine::recalc_search_path(bool* p_search_path_was_updated) {
573
SymbolEngineEntry entry_guard;
575
return recalc_search_path_locked(p_search_path_was_updated);
579
bool SymbolEngine::refreshModuleList() {
580
SymbolEngineEntry entry_guard;
581
return WindowsDbgHelp::symRefreshModuleList(::GetCurrentProcess());
584
bool SymbolEngine::get_source_info(const void* addr, char* buf, size_t buflen,
587
assert(buf != nullptr && buflen > 0 && line_no != nullptr, "Argument error");
591
if (addr == nullptr) {
595
SymbolEngineEntry entry_guard;
597
IMAGEHLP_LINE64 lineinfo;
598
memset(&lineinfo, 0, sizeof(lineinfo));
599
lineinfo.SizeOfStruct = sizeof(lineinfo);
601
if (WindowsDbgHelp::symGetLineFromAddr64(::GetCurrentProcess(), (DWORD64)addr,
602
&displacement, &lineinfo)) {
603
if (buf != nullptr && buflen > 0 && lineinfo.FileName != nullptr) {
604
// We only return the file name, not the whole path.
605
char* p = lineinfo.FileName;
606
char* q = strrchr(lineinfo.FileName, '\\');
610
::strncpy(buf, p, buflen - 1);
611
buf[buflen - 1] = '\0';
614
*line_no = lineinfo.LineNumber;
621
// Print one liner describing state (if library loaded, which functions are
622
// missing - if any, and the dbhelp API version)
623
void SymbolEngine::print_state_on(outputStream* st) {
625
SymbolEngineEntry entry_guard;
627
st->print("symbol engine: ");
629
if (g_state == state_uninitialized) {
630
st->print("uninitialized.");
631
} else if (g_state == state_error) {
632
st->print("initialization error.");
634
st->print("initialized successfully");
635
st->print(" - sym options: 0x%X", WindowsDbgHelp::symGetOptions());
636
st->print(" - pdb path: ");
637
if (WindowsDbgHelp::symGetSearchPath(::GetCurrentProcess(),
638
g_buffers.search_path.ptr(),
639
(int)g_buffers.search_path.capacity())) {
640
st->print_raw(g_buffers.search_path.ptr());
642
st->print_raw("(cannot be retrieved)");