188 lines · c
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-exception6//7//===----------------------------------------------------------------------===//8//9/// \file10/// Structure holding data neccessary for minidump file creation.11///12/// The class MinidumpFileWriter is used to hold the data that will eventually13/// be dumped to the file.14//===----------------------------------------------------------------------===//15 16#ifndef LLDB_SOURCE_PLUGINS_OBJECTFILE_MINIDUMP_MINIDUMPFILEBUILDER_H17#define LLDB_SOURCE_PLUGINS_OBJECTFILE_MINIDUMP_MINIDUMPFILEBUILDER_H18 19#include <cstddef>20#include <cstdint>21#include <map>22#include <unordered_map>23#include <utility>24#include <variant>25 26#include "lldb/Core/Progress.h"27#include "lldb/Symbol/SaveCoreOptions.h"28#include "lldb/Target/Process.h"29#include "lldb/Target/Target.h"30#include "lldb/Utility/DataBufferHeap.h"31#include "lldb/Utility/Status.h"32#include "lldb/lldb-forward.h"33#include "lldb/lldb-types.h"34 35#include "llvm/BinaryFormat/Minidump.h"36#include "llvm/Object/Minidump.h"37 38// Write std::string to minidump in the UTF16 format(with null termination char)39// with the size(without null termination char) preceding the UTF16 string.40// Empty strings are also printed with zero length and just null termination41// char.42lldb_private::Status WriteString(const std::string &to_write,43 lldb_private::DataBufferHeap *buffer);44 45/// \class MinidumpFileBuilder46/// Minidump writer for Linux47///48/// This class provides a Minidump writer that is able to49/// snapshot the current process state.50///51/// Minidumps are a Microsoft format for dumping process state.52/// This class constructs the minidump on disk starting with53/// Headers and Directories are written at the top of the file,54/// with the amount of bytes being precalculates before any writing takes place55/// Then the smaller data sections are written56/// SystemInfo, ModuleList, Misc Info.57/// Then Threads are emitted, threads are the first section that needs to be58/// 'fixed up' this happens when later we emit the memory stream, we identify if59/// that stream is the expected stack, and if so we update the stack with the60/// current RVA. Lastly the Memory lists are added. For Memory List, this will61/// contain everything that can fit within 4.2gb. MemoryList has it's62/// descriptors written at the end so it cannot be allowed to overflow.63///64/// Memory64List is a special case where it has to be begin before 4.2gb but can65/// expand forever The difference in Memory64List is there are no RVA's and all66/// the addresses are figured out by starting at the base RVA, and adding the67/// antecedent memory sections.68///69/// Because Memory64List can be arbitrarily large, this class has to write70/// chunks to disk this means we have to precalculate the descriptors and write71/// them first, and if we encounter any error, or are unable to read the same72/// number of bytes we have to go back and update them on disk.73///74/// And as the last step, after all the directories have been added, we go back75/// to the top of the file to fill in the header and the redirectory sections76/// that we preallocated.77class MinidumpFileBuilder {78public:79 MinidumpFileBuilder(lldb::FileUP &&core_file,80 const lldb::ProcessSP &process_sp,81 lldb_private::SaveCoreOptions &save_core_options)82 : m_process_sp(process_sp), m_core_file(std::move(core_file)),83 m_save_core_options(save_core_options) {}84 85 MinidumpFileBuilder(const MinidumpFileBuilder &) = delete;86 MinidumpFileBuilder &operator=(const MinidumpFileBuilder &) = delete;87 88 MinidumpFileBuilder(MinidumpFileBuilder &&other) = default;89 MinidumpFileBuilder &operator=(MinidumpFileBuilder &&other) = default;90 91 ~MinidumpFileBuilder() = default;92 93 // This method only calculates the amount of bytes the header and directories94 // will take up. It does not write the directories or headers. This function95 // must be called with a followup to fill in the data.96 lldb_private::Status AddHeaderAndCalculateDirectories();97 // Add SystemInfo stream, used for storing the most basic information98 // about the system, platform etc...99 lldb_private::Status AddSystemInfo();100 // Add ModuleList stream, containing information about all loaded modules101 // at the time of saving minidump.102 lldb_private::Status AddModuleList();103 // Add ThreadList stream, containing information about all threads running104 // at the moment of core saving. Contains information about thread105 // contexts.106 lldb_private::Status AddThreadList();107 // Add Exception streams for any threads that stopped with exceptions.108 lldb_private::Status AddExceptions();109 // Add MemoryList stream, containing dumps of important memory segments110 lldb_private::Status AddMemoryList();111 // Add MiscInfo stream, mainly providing ProcessId112 lldb_private::Status AddMiscInfo();113 // Add informative files about a Linux process114 lldb_private::Status AddLinuxFileStreams();115 116 // Run cleanup and write all remaining bytes to file117 lldb_private::Status DumpFile();118 119 // Delete the file if it exists120 void DeleteFile() noexcept;121 122private:123 lldb_private::Status AddLLDBGeneratedStream();124 // Add data to the end of the buffer, if the buffer exceeds the flush level,125 // trigger a flush.126 lldb_private::Status AddData(const void *data, uint64_t size);127 // Add MemoryList stream, containing dumps of important memory segments128 lldb_private::Status129 AddMemoryList_64(std::vector<lldb_private::CoreFileMemoryRange> &ranges,130 lldb_private::Progress &progress);131 lldb_private::Status132 AddMemoryList_32(std::vector<lldb_private::CoreFileMemoryRange> &ranges,133 lldb_private::Progress &progress);134 // Update the thread list on disk with the newly emitted stack RVAs.135 lldb_private::Status FixThreadStacks();136 lldb_private::Status FlushBufferToDisk();137 138 lldb_private::Status DumpHeader() const;139 lldb_private::Status DumpDirectories() const;140 // Add directory of StreamType pointing to the current end of the prepared141 // file with the specified size.142 lldb_private::Status AddDirectory(llvm::minidump::StreamType type,143 uint64_t stream_size);144 lldb::offset_t GetCurrentDataEndOffset() const;145 146 // Read a memory region from the process and write it to the file147 // in fixed size chunks.148 lldb_private::Status149 ReadWriteMemoryInChunks(lldb_private::DataBufferHeap &data_buffer,150 const lldb_private::CoreFileMemoryRange &range,151 uint64_t &bytes_read);152 153 // Stores directories to fill in later154 std::vector<llvm::minidump::Directory> m_directories;155 // When we write off the threads for the first time, we need to clean them up156 // and give them the correct RVA once we write the stack memory list.157 // We save by the end because we only take from the stack pointer up158 // So the saved off range base can differ from the memory region the stack159 // pointer is in.160 std::unordered_map<lldb::addr_t, llvm::minidump::Thread>161 m_thread_by_range_end;162 // Main data buffer consisting of data without the minidump header and163 // directories164 lldb_private::DataBufferHeap m_data;165 lldb::ProcessSP m_process_sp;166 167 size_t m_expected_directories = 0;168 uint64_t m_saved_data_size = 0;169 lldb::offset_t m_thread_list_start = 0;170 // We set the max write amount to 128 mb, this is arbitrary171 // but we want to try to keep the size of m_data small172 // and we will only exceed a 128 mb buffer if we get a memory region173 // that is larger than 128 mb.174 static constexpr uint64_t MAX_WRITE_CHUNK_SIZE = (1024 * 1024 * 128);175 176 static constexpr size_t HEADER_SIZE = sizeof(llvm::minidump::Header);177 static constexpr size_t DIRECTORY_SIZE = sizeof(llvm::minidump::Directory);178 179 // More that one place can mention the register thread context locations,180 // so when we emit the thread contents, remember where it is so we don't have181 // to duplicate it in the exception data.182 std::unordered_map<lldb::tid_t, llvm::minidump::LocationDescriptor>183 m_tid_to_reg_ctx;184 lldb::FileUP m_core_file;185 lldb_private::SaveCoreOptions m_save_core_options;186};187#endif // LLDB_SOURCE_PLUGINS_OBJECTFILE_MINIDUMP_MINIDUMPFILEBUILDER_H188