LLDB mainline
MinidumpFileBuilder.h
Go to the documentation of this file.
1//===-- MinidumpFileBuilder.h ---------------------------------------------===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8//
9/// \file
10/// Structure holding data neccessary for minidump file creation.
11///
12/// The class MinidumpFileWriter is used to hold the data that will eventually
13/// be dumped to the file.
14//===----------------------------------------------------------------------===//
15
16#ifndef LLDB_SOURCE_PLUGINS_OBJECTFILE_MINIDUMP_MINIDUMPFILEBUILDER_H
17#define LLDB_SOURCE_PLUGINS_OBJECTFILE_MINIDUMP_MINIDUMPFILEBUILDER_H
18
19#include <cstddef>
20#include <cstdint>
21#include <map>
22#include <unordered_map>
23#include <utility>
24#include <variant>
25
26#include "lldb/Target/Process.h"
27#include "lldb/Target/Target.h"
29#include "lldb/Utility/Status.h"
30#include "lldb/lldb-forward.h"
31#include "lldb/lldb-types.h"
32
33#include "llvm/BinaryFormat/Minidump.h"
34#include "llvm/Object/Minidump.h"
35
36// Write std::string to minidump in the UTF16 format(with null termination char)
37// with the size(without null termination char) preceding the UTF16 string.
38// Empty strings are also printed with zero length and just null termination
39// char.
40lldb_private::Status WriteString(const std::string &to_write,
42
43/// \class MinidumpFileBuilder
44/// Minidump writer for Linux
45///
46/// This class provides a Minidump writer that is able to
47/// snapshot the current process state.
48///
49/// Minidumps are a Microsoft format for dumping process state.
50/// This class constructs the minidump on disk starting with
51/// Headers and Directories are written at the top of the file,
52/// with the amount of bytes being precalculates before any writing takes place
53/// Then the smaller data sections are written
54/// SystemInfo, ModuleList, Misc Info.
55/// Then Threads are emitted, threads are the first section that needs to be
56/// 'fixed up' this happens when later we emit the memory stream, we identify if
57/// that stream is the expected stack, and if so we update the stack with the
58/// current RVA. Lastly the Memory lists are added. For Memory List, this will
59/// contain everything that can fit within 4.2gb. MemoryList has it's
60/// descriptors written at the end so it cannot be allowed to overflow.
61///
62/// Memory64List is a special case where it has to be begin before 4.2gb but can
63/// expand forever The difference in Memory64List is there are no RVA's and all
64/// the addresses are figured out by starting at the base RVA, and adding the
65/// antecedent memory sections.
66///
67/// Because Memory64List can be arbitrarily large, this class has to write
68/// chunks to disk this means we have to precalculate the descriptors and write
69/// them first, and if we encounter any error, or are unable to read the same
70/// number of bytes we have to go back and update them on disk.
71///
72/// And as the last step, after all the directories have been added, we go back
73/// to the top of the file to fill in the header and the redirectory sections
74/// that we preallocated.
76public:
78 const lldb::ProcessSP &process_sp,
79 lldb_private::SaveCoreOptions &save_core_options)
80 : m_process_sp(process_sp), m_core_file(std::move(core_file)),
81 m_save_core_options(save_core_options){}
82
85
88
90
91 // This method only calculates the amount of bytes the header and directories
92 // will take up. It does not write the directories or headers. This function
93 // must be called with a followup to fill in the data.
95 // Add SystemInfo stream, used for storing the most basic information
96 // about the system, platform etc...
98 // Add ModuleList stream, containing information about all loaded modules
99 // at the time of saving minidump.
101 // Add ThreadList stream, containing information about all threads running
102 // at the moment of core saving. Contains information about thread
103 // contexts.
105 // Add Exception streams for any threads that stopped with exceptions.
107 // Add MemoryList stream, containing dumps of important memory segments
109 // Add MiscInfo stream, mainly providing ProcessId
111 // Add informative files about a Linux process
113
114 // Run cleanup and write all remaining bytes to file
116
117private:
118 // Add data to the end of the buffer, if the buffer exceeds the flush level,
119 // trigger a flush.
120 lldb_private::Status AddData(const void *data, uint64_t size);
121 // Add MemoryList stream, containing dumps of important memory segments
126 // Update the thread list on disk with the newly emitted stack RVAs.
129
132 // Add directory of StreamType pointing to the current end of the prepared
133 // file with the specified size.
134 lldb_private::Status AddDirectory(llvm::minidump::StreamType type,
135 uint64_t stream_size);
137 // Stores directories to fill in later
138 std::vector<llvm::minidump::Directory> m_directories;
139 // When we write off the threads for the first time, we need to clean them up
140 // and give them the correct RVA once we write the stack memory list.
141 // We save by the end because we only take from the stack pointer up
142 // So the saved off range base can differ from the memory region the stack
143 // pointer is in.
144 std::unordered_map<lldb::addr_t, llvm::minidump::Thread>
146 // Main data buffer consisting of data without the minidump header and
147 // directories
150
152 uint64_t m_saved_data_size = 0;
154 // We set the max write amount to 128 mb, this is arbitrary
155 // but we want to try to keep the size of m_data small
156 // and we will only exceed a 128 mb buffer if we get a memory region
157 // that is larger than 128 mb.
158 static constexpr size_t MAX_WRITE_CHUNK_SIZE = (1024 * 1024 * 128);
159
160 static constexpr size_t HEADER_SIZE = sizeof(llvm::minidump::Header);
161 static constexpr size_t DIRECTORY_SIZE = sizeof(llvm::minidump::Directory);
162
163 // More that one place can mention the register thread context locations,
164 // so when we emit the thread contents, remember where it is so we don't have
165 // to duplicate it in the exception data.
166 std::unordered_map<lldb::tid_t, llvm::minidump::LocationDescriptor>
168 std::unordered_set<lldb::addr_t> m_saved_stack_ranges;
171};
172
173#endif // LLDB_SOURCE_PLUGINS_OBJECTFILE_MINIDUMP_MINIDUMPFILEBUILDER_H
lldb_private::Status WriteString(const std::string &to_write, lldb_private::DataBufferHeap *buffer)
Minidump writer for Linux.
lldb_private::Status AddMemoryList_64(lldb_private::Process::CoreFileMemoryRanges &ranges)
lldb_private::Status AddExceptions()
std::unordered_map< lldb::tid_t, llvm::minidump::LocationDescriptor > m_tid_to_reg_ctx
~MinidumpFileBuilder()=default
lldb_private::Status AddThreadList()
lldb_private::Status AddHeaderAndCalculateDirectories()
static constexpr size_t DIRECTORY_SIZE
lldb_private::DataBufferHeap m_data
lldb_private::Status AddSystemInfo()
lldb_private::Status AddMemoryList()
std::unordered_map< lldb::addr_t, llvm::minidump::Thread > m_thread_by_range_end
lldb_private::Status AddData(const void *data, uint64_t size)
lldb_private::Status DumpFile()
lldb_private::SaveCoreOptions m_save_core_options
lldb_private::Status FlushBufferToDisk()
MinidumpFileBuilder(MinidumpFileBuilder &&other)=default
lldb::offset_t m_thread_list_start
static constexpr size_t MAX_WRITE_CHUNK_SIZE
std::unordered_set< lldb::addr_t > m_saved_stack_ranges
lldb_private::Status AddDirectory(llvm::minidump::StreamType type, uint64_t stream_size)
MinidumpFileBuilder & operator=(MinidumpFileBuilder &&other)=default
lldb_private::Status FixThreadStacks()
lldb::ProcessSP m_process_sp
lldb_private::Status AddMemoryList_32(lldb_private::Process::CoreFileMemoryRanges &ranges)
static constexpr size_t HEADER_SIZE
lldb::offset_t GetCurrentDataEndOffset() const
std::vector< llvm::minidump::Directory > m_directories
lldb_private::Status DumpDirectories() const
lldb_private::Status AddLinuxFileStreams()
lldb_private::Status AddModuleList()
MinidumpFileBuilder(lldb::FileUP &&core_file, const lldb::ProcessSP &process_sp, lldb_private::SaveCoreOptions &save_core_options)
lldb_private::Status AddMiscInfo()
lldb_private::Status DumpHeader() const
MinidumpFileBuilder & operator=(const MinidumpFileBuilder &)=delete
MinidumpFileBuilder(const MinidumpFileBuilder &)=delete
A subclass of DataBuffer that stores a data buffer on the heap.
std::vector< CoreFileMemoryRange > CoreFileMemoryRanges
Definition: Process.h:736
An error handling class.
Definition: Status.h:44
std::unique_ptr< lldb_private::File > FileUP
Definition: lldb-forward.h:350
uint64_t offset_t
Definition: lldb-types.h:85
std::shared_ptr< lldb_private::Process > ProcessSP
Definition: lldb-forward.h:387