Minidump.h revision d111c7844ec26448764ced627e153f406d730c5f
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/BinaryFormat/Minidump.h"
15#include "llvm/Object/Binary.h"
16#include "llvm/Support/Error.h"
17
18namespace llvm {
19namespace object {
20
21/// A class providing access to the contents of a minidump file.
22class MinidumpFile : public Binary {
23public:
24  /// Construct a new MinidumpFile object from the given memory buffer. Returns
25  /// an error if this file cannot be identified as a minidump file, or if its
26  /// contents are badly corrupted (i.e. we cannot read the stream directory).
27  static Expected<std::unique_ptr<MinidumpFile>> create(MemoryBufferRef Source);
28
29  static bool classof(const Binary *B) { return B->isMinidump(); }
30
31  /// Returns the contents of the minidump header.
32  const minidump::Header &header() const { return Header; }
33
34  /// Returns the list of streams (stream directory entries) in this file.
35  ArrayRef<minidump::Directory> streams() const { return Streams; }
36
37  /// Returns the raw contents of the stream given by the directory entry.
38  ArrayRef<uint8_t> getRawStream(const minidump::Directory &Stream) const {
39    return getData().slice(Stream.Location.RVA, Stream.Location.DataSize);
40  }
41
42  /// Returns the raw contents of the stream of the given type, or None if the
43  /// file does not contain a stream of this type.
44  Optional<ArrayRef<uint8_t>> getRawStream(minidump::StreamType Type) const;
45
46  /// Returns the raw contents of an object given by the LocationDescriptor. An
47  /// error is returned if the descriptor points outside of the minidump file.
48  Expected<ArrayRef<uint8_t>>
49  getRawData(minidump::LocationDescriptor Desc) const {
50    return getDataSlice(getData(), Desc.RVA, Desc.DataSize);
51  }
52
53  /// Returns the minidump string at the given offset. An error is returned if
54  /// we fail to parse the string, or the string is invalid UTF16.
55  Expected<std::string> getString(size_t Offset) const;
56
57  /// Returns the contents of the SystemInfo stream, cast to the appropriate
58  /// type. An error is returned if the file does not contain this stream, or
59  /// the stream is smaller than the size of the SystemInfo structure. The
60  /// internal consistency of the stream is not checked in any way.
61  Expected<const minidump::SystemInfo &> getSystemInfo() const {
62    return getStream<minidump::SystemInfo>(minidump::StreamType::SystemInfo);
63  }
64
65  /// Returns the module list embedded in the ModuleList stream. An error is
66  /// returned if the file does not contain this stream, or if the stream is
67  /// not large enough to contain the number of modules declared in the stream
68  /// header. The consistency of the Module entries themselves is not checked in
69  /// any way.
70  Expected<ArrayRef<minidump::Module>> getModuleList() const {
71    return getListStream<minidump::Module>(minidump::StreamType::ModuleList);
72  }
73
74  /// Returns the thread list embedded in the ThreadList stream. An error is
75  /// returned if the file does not contain this stream, or if the stream is
76  /// not large enough to contain the number of threads declared in the stream
77  /// header. The consistency of the Thread entries themselves is not checked in
78  /// any way.
79  Expected<ArrayRef<minidump::Thread>> getThreadList() const {
80    return getListStream<minidump::Thread>(minidump::StreamType::ThreadList);
81  }
82
83  /// Returns the list of memory ranges embedded in the MemoryList stream. An
84  /// error is returned if the file does not contain this stream, or if the
85  /// stream is not large enough to contain the number of memory descriptors
86  /// declared in the stream header. The consistency of the MemoryDescriptor
87  /// entries themselves is not checked in any way.
88  Expected<ArrayRef<minidump::MemoryDescriptor>> getMemoryList() const {
89    return getListStream<minidump::MemoryDescriptor>(
90        minidump::StreamType::MemoryList);
91  }
92
93private:
94  static Error createError(StringRef Str) {
95    return make_error<GenericBinaryError>(Str, object_error::parse_failed);
96  }
97
98  static Error createEOFError() {
99    return make_error<GenericBinaryError>("Unexpected EOF",
100                                          object_error::unexpected_eof);
101  }
102
103  /// Return a slice of the given data array, with bounds checking.
104  static Expected<ArrayRef<uint8_t>> getDataSlice(ArrayRef<uint8_t> Data,
105                                                  size_t Offset, size_t Size);
106
107  /// Return the slice of the given data array as an array of objects of the
108  /// given type. The function checks that the input array is large enough to
109  /// contain the correct number of objects of the given type.
110  template <typename T>
111  static Expected<ArrayRef<T>> getDataSliceAs(ArrayRef<uint8_t> Data,
112                                              size_t Offset, size_t Count);
113
114  MinidumpFile(MemoryBufferRef Source, const minidump::Header &Header,
115               ArrayRef<minidump::Directory> Streams,
116               DenseMap<minidump::StreamType, std::size_t> StreamMap)
117      : Binary(ID_Minidump, Source), Header(Header), Streams(Streams),
118        StreamMap(std::move(StreamMap)) {}
119
120  ArrayRef<uint8_t> getData() const {
121    return arrayRefFromStringRef(Data.getBuffer());
122  }
123
124  /// Return the stream of the given type, cast to the appropriate type. Checks
125  /// that the stream is large enough to hold an object of this type.
126  template <typename T>
127  Expected<const T &> getStream(minidump::StreamType Stream) const;
128
129  /// Return the contents of a stream which contains a list of fixed-size items,
130  /// prefixed by the list size.
131  template <typename T>
132  Expected<ArrayRef<T>> getListStream(minidump::StreamType Stream) const;
133
134  const minidump::Header &Header;
135  ArrayRef<minidump::Directory> Streams;
136  DenseMap<minidump::StreamType, std::size_t> StreamMap;
137};
138
139template <typename T>
140Expected<const T &> MinidumpFile::getStream(minidump::StreamType Stream) const {
141  if (auto OptionalStream = getRawStream(Stream)) {
142    if (OptionalStream->size() >= sizeof(T))
143      return *reinterpret_cast<const T *>(OptionalStream->data());
144    return createEOFError();
145  }
146  return createError("No such stream");
147}
148
149template <typename T>
150Expected<ArrayRef<T>> MinidumpFile::getDataSliceAs(ArrayRef<uint8_t> Data,
151                                                   size_t Offset,
152                                                   size_t Count) {
153  // Check for overflow.
154  if (Count > std::numeric_limits<size_t>::max() / sizeof(T))
155    return createEOFError();
156  auto ExpectedArray = getDataSlice(Data, Offset, sizeof(T) * Count);
157  if (!ExpectedArray)
158    return ExpectedArray.takeError();
159  return ArrayRef<T>(reinterpret_cast<const T *>(ExpectedArray->data()), Count);
160}
161
162} // end namespace object
163} // end namespace llvm
164
165#endif // LLVM_OBJECT_MINIDUMP_H
166