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