1 | //===- Minidump.h - Minidump object file implementation ---------*- C++ -*-===// |
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 | #ifndef LLVM_OBJECT_MINIDUMP_H |
10 | #define LLVM_OBJECT_MINIDUMP_H |
11 | |
12 | #include "llvm/ADT/DenseMap.h" |
13 | #include "llvm/ADT/StringExtras.h" |
14 | #include "llvm/ADT/iterator.h" |
15 | #include "llvm/BinaryFormat/Minidump.h" |
16 | #include "llvm/Object/Binary.h" |
17 | #include "llvm/Support/Error.h" |
18 | |
19 | namespace llvm { |
20 | namespace object { |
21 | |
22 | /// A class providing access to the contents of a minidump file. |
23 | class MinidumpFile : public Binary { |
24 | public: |
25 | /// Construct a new MinidumpFile object from the given memory buffer. Returns |
26 | /// an error if this file cannot be identified as a minidump file, or if its |
27 | /// contents are badly corrupted (i.e. we cannot read the stream directory). |
28 | static Expected<std::unique_ptr<MinidumpFile>> create(MemoryBufferRef Source); |
29 | |
30 | static bool classof(const Binary *B) { return B->isMinidump(); } |
31 | |
32 | /// Returns the contents of the minidump header. |
33 | const minidump::Header &() const { return Header; } |
34 | |
35 | /// Returns the list of streams (stream directory entries) in this file. |
36 | ArrayRef<minidump::Directory> streams() const { return Streams; } |
37 | |
38 | /// Returns the raw contents of the stream given by the directory entry. |
39 | ArrayRef<uint8_t> getRawStream(const minidump::Directory &Stream) const { |
40 | return getData().slice(N: Stream.Location.RVA, M: Stream.Location.DataSize); |
41 | } |
42 | |
43 | /// Returns the raw contents of the stream of the given type, or std::nullopt |
44 | /// if the file does not contain a stream of this type. |
45 | std::optional<ArrayRef<uint8_t>> |
46 | getRawStream(minidump::StreamType Type) const; |
47 | |
48 | /// Returns the raw contents of an object given by the LocationDescriptor. An |
49 | /// error is returned if the descriptor points outside of the minidump file. |
50 | Expected<ArrayRef<uint8_t>> |
51 | getRawData(minidump::LocationDescriptor Desc) const { |
52 | return getDataSlice(Data: getData(), Offset: Desc.RVA, Size: Desc.DataSize); |
53 | } |
54 | |
55 | /// Returns the minidump string at the given offset. An error is returned if |
56 | /// we fail to parse the string, or the string is invalid UTF16. |
57 | Expected<std::string> getString(size_t Offset) const; |
58 | |
59 | /// Returns the contents of the SystemInfo stream, cast to the appropriate |
60 | /// type. An error is returned if the file does not contain this stream, or |
61 | /// the stream is smaller than the size of the SystemInfo structure. The |
62 | /// internal consistency of the stream is not checked in any way. |
63 | Expected<const minidump::SystemInfo &> getSystemInfo() const { |
64 | return getStream<minidump::SystemInfo>(Type: minidump::StreamType::SystemInfo); |
65 | } |
66 | |
67 | /// Returns the module list embedded in the ModuleList stream. An error is |
68 | /// returned if the file does not contain this stream, or if the stream is |
69 | /// not large enough to contain the number of modules declared in the stream |
70 | /// header. The consistency of the Module entries themselves is not checked in |
71 | /// any way. |
72 | Expected<ArrayRef<minidump::Module>> getModuleList() const { |
73 | return getListStream<minidump::Module>(Stream: minidump::StreamType::ModuleList); |
74 | } |
75 | |
76 | /// Returns the thread list embedded in the ThreadList stream. An error is |
77 | /// returned if the file does not contain this stream, or if the stream is |
78 | /// not large enough to contain the number of threads declared in the stream |
79 | /// header. The consistency of the Thread entries themselves is not checked in |
80 | /// any way. |
81 | Expected<ArrayRef<minidump::Thread>> getThreadList() const { |
82 | return getListStream<minidump::Thread>(Stream: minidump::StreamType::ThreadList); |
83 | } |
84 | |
85 | /// Returns the contents of the Exception stream. An error is returned if the |
86 | /// file does not contain this stream, or the stream is smaller than the size |
87 | /// of the ExceptionStream structure. The internal consistency of the stream |
88 | /// is not checked in any way. |
89 | Expected<const minidump::ExceptionStream &> getExceptionStream() const { |
90 | return getStream<minidump::ExceptionStream>( |
91 | Type: minidump::StreamType::Exception); |
92 | } |
93 | |
94 | /// Returns the list of descriptors embedded in the MemoryList stream. The |
95 | /// descriptors provide the content of interesting regions of memory at the |
96 | /// time the minidump was taken. An error is returned if the file does not |
97 | /// contain this stream, or if the stream is not large enough to contain the |
98 | /// number of memory descriptors declared in the stream header. The |
99 | /// consistency of the MemoryDescriptor entries themselves is not checked in |
100 | /// any way. |
101 | Expected<ArrayRef<minidump::MemoryDescriptor>> getMemoryList() const { |
102 | return getListStream<minidump::MemoryDescriptor>( |
103 | Stream: minidump::StreamType::MemoryList); |
104 | } |
105 | |
106 | class MemoryInfoIterator |
107 | : public iterator_facade_base<MemoryInfoIterator, |
108 | std::forward_iterator_tag, |
109 | minidump::MemoryInfo> { |
110 | public: |
111 | MemoryInfoIterator(ArrayRef<uint8_t> Storage, size_t Stride) |
112 | : Storage(Storage), Stride(Stride) { |
113 | assert(Storage.size() % Stride == 0); |
114 | } |
115 | |
116 | bool operator==(const MemoryInfoIterator &R) const { |
117 | return Storage.size() == R.Storage.size(); |
118 | } |
119 | |
120 | const minidump::MemoryInfo &operator*() const { |
121 | assert(Storage.size() >= sizeof(minidump::MemoryInfo)); |
122 | return *reinterpret_cast<const minidump::MemoryInfo *>(Storage.data()); |
123 | } |
124 | |
125 | MemoryInfoIterator &operator++() { |
126 | Storage = Storage.drop_front(N: Stride); |
127 | return *this; |
128 | } |
129 | |
130 | private: |
131 | ArrayRef<uint8_t> Storage; |
132 | size_t Stride; |
133 | }; |
134 | |
135 | /// Returns the list of descriptors embedded in the MemoryInfoList stream. The |
136 | /// descriptors provide properties (e.g. permissions) of interesting regions |
137 | /// of memory at the time the minidump was taken. An error is returned if the |
138 | /// file does not contain this stream, or if the stream is not large enough to |
139 | /// contain the number of memory descriptors declared in the stream header. |
140 | /// The consistency of the MemoryInfoList entries themselves is not checked |
141 | /// in any way. |
142 | Expected<iterator_range<MemoryInfoIterator>> getMemoryInfoList() const; |
143 | |
144 | private: |
145 | static Error createError(StringRef Str) { |
146 | return make_error<GenericBinaryError>(Args&: Str, Args: object_error::parse_failed); |
147 | } |
148 | |
149 | static Error createEOFError() { |
150 | return make_error<GenericBinaryError>(Args: "Unexpected EOF" , |
151 | Args: object_error::unexpected_eof); |
152 | } |
153 | |
154 | /// Return a slice of the given data array, with bounds checking. |
155 | static Expected<ArrayRef<uint8_t>> getDataSlice(ArrayRef<uint8_t> Data, |
156 | size_t Offset, size_t Size); |
157 | |
158 | /// Return the slice of the given data array as an array of objects of the |
159 | /// given type. The function checks that the input array is large enough to |
160 | /// contain the correct number of objects of the given type. |
161 | template <typename T> |
162 | static Expected<ArrayRef<T>> getDataSliceAs(ArrayRef<uint8_t> Data, |
163 | size_t Offset, size_t Count); |
164 | |
165 | (MemoryBufferRef Source, const minidump::Header &, |
166 | ArrayRef<minidump::Directory> Streams, |
167 | DenseMap<minidump::StreamType, std::size_t> StreamMap) |
168 | : Binary(ID_Minidump, Source), Header(Header), Streams(Streams), |
169 | StreamMap(std::move(StreamMap)) {} |
170 | |
171 | ArrayRef<uint8_t> getData() const { |
172 | return arrayRefFromStringRef(Input: Data.getBuffer()); |
173 | } |
174 | |
175 | /// Return the stream of the given type, cast to the appropriate type. Checks |
176 | /// that the stream is large enough to hold an object of this type. |
177 | template <typename T> |
178 | Expected<const T &> getStream(minidump::StreamType Stream) const; |
179 | |
180 | /// Return the contents of a stream which contains a list of fixed-size items, |
181 | /// prefixed by the list size. |
182 | template <typename T> |
183 | Expected<ArrayRef<T>> getListStream(minidump::StreamType Stream) const; |
184 | |
185 | const minidump::Header &; |
186 | ArrayRef<minidump::Directory> Streams; |
187 | DenseMap<minidump::StreamType, std::size_t> StreamMap; |
188 | }; |
189 | |
190 | template <typename T> |
191 | Expected<const T &> MinidumpFile::getStream(minidump::StreamType Type) const { |
192 | if (std::optional<ArrayRef<uint8_t>> Stream = getRawStream(Type)) { |
193 | if (Stream->size() >= sizeof(T)) |
194 | return *reinterpret_cast<const T *>(Stream->data()); |
195 | return createEOFError(); |
196 | } |
197 | return createError(Str: "No such stream" ); |
198 | } |
199 | |
200 | template <typename T> |
201 | Expected<ArrayRef<T>> MinidumpFile::getDataSliceAs(ArrayRef<uint8_t> Data, |
202 | size_t Offset, |
203 | size_t Count) { |
204 | // Check for overflow. |
205 | if (Count > std::numeric_limits<size_t>::max() / sizeof(T)) |
206 | return createEOFError(); |
207 | Expected<ArrayRef<uint8_t>> Slice = |
208 | getDataSlice(Data, Offset, Size: sizeof(T) * Count); |
209 | if (!Slice) |
210 | return Slice.takeError(); |
211 | return ArrayRef<T>(reinterpret_cast<const T *>(Slice->data()), Count); |
212 | } |
213 | |
214 | } // end namespace object |
215 | } // end namespace llvm |
216 | |
217 | #endif // LLVM_OBJECT_MINIDUMP_H |
218 | |