OLD | NEW |
(Empty) | |
| 1 // Copyright 2014 The Crashpad Authors. All rights reserved. |
| 2 // |
| 3 // Licensed under the Apache License, Version 2.0 (the "License"); |
| 4 // you may not use this file except in compliance with the License. |
| 5 // You may obtain a copy of the License at |
| 6 // |
| 7 // http://www.apache.org/licenses/LICENSE-2.0 |
| 8 // |
| 9 // Unless required by applicable law or agreed to in writing, software |
| 10 // distributed under the License is distributed on an "AS IS" BASIS, |
| 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 12 // See the License for the specific language governing permissions and |
| 13 // limitations under the License. |
| 14 |
| 15 #ifndef CRASHPAD_MINIDUMP_MINIDUMP_MEMORY_WRITER_H_ |
| 16 #define CRASHPAD_MINIDUMP_MINIDUMP_MEMORY_WRITER_H_ |
| 17 |
| 18 #include <dbghelp.h> |
| 19 #include <sys/types.h> |
| 20 |
| 21 #include <vector> |
| 22 |
| 23 #include "base/basictypes.h" |
| 24 #include "minidump/minidump_stream_writer.h" |
| 25 #include "minidump/minidump_writable.h" |
| 26 #include "util/file/file_writer.h" |
| 27 |
| 28 namespace crashpad { |
| 29 |
| 30 //! \brief The base class for writers of memory ranges pointed to by |
| 31 //! MINIDUMP_MEMORY_DESCRIPTOR objects in a minidump file. |
| 32 //! |
| 33 //! This is an abstract base class because users are expected to provide their |
| 34 //! own implementations that, when possible, obtain the memory contents |
| 35 //! on-demand in their WriteObject() methods. Memory ranges may be large, and |
| 36 //! the alternative construction would require the contents of multiple ranges |
| 37 //! to be held in memory simultaneously while a minidump file is being written. |
| 38 class MinidumpMemoryWriter : public internal::MinidumpWritable { |
| 39 public: |
| 40 //! \brief Returns a MINIDUMP_MEMORY_DESCRIPTOR referencing the data that this |
| 41 //! object writes. |
| 42 //! |
| 43 //! This method is expected to be called by a MinidumpMemoryListWriter in |
| 44 //! order to obtain a MINIDUMP_MEMORY_DESCRIPTOR to include in its list. |
| 45 //! |
| 46 //! \note Valid in #kStateWritable. |
| 47 const MINIDUMP_MEMORY_DESCRIPTOR* MinidumpMemoryDescriptor() const; |
| 48 |
| 49 //! \brief Registers a memory descriptor as one that should point to the |
| 50 //! object on which this method is called. |
| 51 //! |
| 52 //! This method is expected to be called by objects of other classes, when |
| 53 //! those other classes have their own memory descriptors that need to point |
| 54 //! to memory ranges within a minidump file. MinidumpThreadWriter is one such |
| 55 //! class. This method is public for this reason, otherwise it would suffice |
| 56 //! to be private. |
| 57 //! |
| 58 //! \note Valid in #kStateFrozen or any preceding state. |
| 59 void RegisterMemoryDescriptor(MINIDUMP_MEMORY_DESCRIPTOR* memory_descriptor); |
| 60 |
| 61 protected: |
| 62 MinidumpMemoryWriter(); |
| 63 ~MinidumpMemoryWriter() {} |
| 64 |
| 65 //! \brief Returns the base address of the memory region in the address space |
| 66 //! of the process that the snapshot describes. |
| 67 //! |
| 68 //! \note This method will only be called in #kStateFrozen. |
| 69 virtual uint64_t MemoryRangeBaseAddress() const = 0; |
| 70 |
| 71 //! \brief Returns the size of the memory region in bytes. |
| 72 //! |
| 73 //! \note This method will only be called in #kStateFrozen or a subsequent |
| 74 //! state. |
| 75 virtual size_t MemoryRangeSize() const = 0; |
| 76 |
| 77 // MinidumpWritable: |
| 78 virtual bool Freeze() override; |
| 79 virtual size_t SizeOfObject() override final; |
| 80 |
| 81 //! \brief Returns the object’s desired byte-boundary alignment. |
| 82 //! |
| 83 //! Memory regions are aligned to a 16-byte boundary. The actual alignment |
| 84 //! requirements of any data within the memory region are unknown, and may be |
| 85 //! more or less strict than this depending on the platform. |
| 86 //! |
| 87 //! \return `16`. |
| 88 //! |
| 89 //! \note Valid in #kStateFrozen or any subsequent state. |
| 90 virtual size_t Alignment() override; |
| 91 |
| 92 virtual bool WillWriteAtOffsetImpl(off_t offset) override; |
| 93 |
| 94 //! \brief Returns the object’s desired write phase. |
| 95 //! |
| 96 //! Memory regions are written at the end of minidump files, because it is |
| 97 //! expected that unlike most other data in a minidump file, the contents of |
| 98 //! memory regions will be accessed sparsely. |
| 99 //! |
| 100 //! \return #kPhaseLate. |
| 101 //! |
| 102 //! \note Valid in any state. |
| 103 virtual Phase WritePhase() override final; |
| 104 |
| 105 private: |
| 106 MINIDUMP_MEMORY_DESCRIPTOR memory_descriptor_; |
| 107 |
| 108 // weak |
| 109 std::vector<MINIDUMP_MEMORY_DESCRIPTOR*> registered_memory_descriptors_; |
| 110 |
| 111 DISALLOW_COPY_AND_ASSIGN(MinidumpMemoryWriter); |
| 112 }; |
| 113 |
| 114 //! \brief The writer for a MINIDUMP_MEMORY_LIST stream in a minidump file, |
| 115 //! containing a list of MINIDUMP_MEMORY_DESCRIPTOR objects. |
| 116 class MinidumpMemoryListWriter final : public internal::MinidumpStreamWriter { |
| 117 public: |
| 118 MinidumpMemoryListWriter(); |
| 119 ~MinidumpMemoryListWriter(); |
| 120 |
| 121 //! \brief Adds a MinidumpMemoryWriter to the MINIDUMP_MEMORY_LIST. |
| 122 //! |
| 123 //! \a memory_writer will become a child of this object in the overall tree of |
| 124 //! internal::MinidumpWritable objects. |
| 125 //! |
| 126 //! \note Valid in #kStateMutable. |
| 127 void AddMemory(MinidumpMemoryWriter* memory_writer); |
| 128 |
| 129 //! \brief Adds a MinidumpMemoryWriter that’s a child of another |
| 130 //! internal::MinidumpWritable object to the MINIDUMP_MEMORY_LIST. |
| 131 //! |
| 132 //! \a memory_writer does not become a child of this object, but the |
| 133 //! MINIDUMP_MEMORY_LIST will still contain a MINIDUMP_MEMORY_DESCRIPTOR for |
| 134 //! it. \a memory_writer must be a child of another object in the |
| 135 //! internal::MinidumpWritable tree. |
| 136 //! |
| 137 //! This method exists to be called by objects that have their own |
| 138 //! MinidumpMemoryWriter children but wish for them to also appear in the |
| 139 //! minidump file’s MINIDUMP_MEMORY_LIST. MinidumpThreadWriter, which has a |
| 140 //! MinidumpMemoryWriter for thread stack memory, is an example. |
| 141 //! |
| 142 //! \note Valid in #kStateMutable. |
| 143 void AddExtraMemory(MinidumpMemoryWriter* memory_writer); |
| 144 |
| 145 protected: |
| 146 // MinidumpWritable: |
| 147 virtual bool Freeze() override; |
| 148 virtual size_t SizeOfObject() override; |
| 149 virtual std::vector<MinidumpWritable*> Children() override; |
| 150 virtual bool WriteObject(FileWriterInterface* file_writer) override; |
| 151 |
| 152 // MinidumpStreamWriter: |
| 153 virtual MinidumpStreamType StreamType() const override; |
| 154 |
| 155 private: |
| 156 MINIDUMP_MEMORY_LIST memory_list_base_; |
| 157 std::vector<MinidumpMemoryWriter*> memory_writers_; // weak |
| 158 std::vector<MinidumpWritable*> children_; // weak |
| 159 |
| 160 DISALLOW_COPY_AND_ASSIGN(MinidumpMemoryListWriter); |
| 161 }; |
| 162 |
| 163 } // namespace crashpad |
| 164 |
| 165 #endif // CRASHPAD_MINIDUMP_MINIDUMP_MEMORY_WRITER_H_ |
OLD | NEW |