crashpad/snapshot/module_snapshot.h
Mark Mentovai 6278690abe Update copyright boilerplate, 2022 edition (Crashpad)
sed -i '' -E -e 's/Copyright (.+) The Crashpad Authors\. All rights reserved\.$/Copyright \1 The Crashpad Authors/' $(git grep -El 'Copyright (.+) The Crashpad Authors\. All rights reserved\.$')

Bug: chromium:1098010
Change-Id: I8d6138469ddbe3d281a5d83f64cf918ec2491611
Reviewed-on: https://chromium-review.googlesource.com/c/crashpad/crashpad/+/3878262
Reviewed-by: Joshua Peraza <jperaza@chromium.org>
Commit-Queue: Mark Mentovai <mark@chromium.org>
2022-09-06 23:54:07 +00:00

248 lines
10 KiB
C++
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

// Copyright 2014 The Crashpad Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
#ifndef CRASHPAD_SNAPSHOT_MODULE_SNAPSHOT_H_
#define CRASHPAD_SNAPSHOT_MODULE_SNAPSHOT_H_
#include <stdint.h>
#include <sys/types.h>
#include <map>
#include <memory>
#include <set>
#include <string>
#include <vector>
#include "snapshot/annotation_snapshot.h"
#include "snapshot/memory_snapshot.h"
#include "util/misc/uuid.h"
#include "util/numeric/checked_range.h"
namespace crashpad {
class MemorySnapshot;
//! \brief Information describing a custom user data stream in a minidump.
class UserMinidumpStream {
public:
//! \brief Constructs a UserMinidumpStream, takes ownership of \a memory.
UserMinidumpStream(uint32_t stream_type, MemorySnapshot* memory)
: memory_(memory), stream_type_(stream_type) {}
UserMinidumpStream(const UserMinidumpStream&) = delete;
UserMinidumpStream& operator=(const UserMinidumpStream&) = delete;
const MemorySnapshot* memory() const { return memory_.get(); }
uint32_t stream_type() const { return stream_type_; }
private:
//! \brief The memory representing the custom minidump stream.
std::unique_ptr<MemorySnapshot> memory_;
//! \brief The stream type that the minidump stream will be tagged with.
uint32_t stream_type_;
};
//! \brief An abstract interface to a snapshot representing a code module
//! (binary image) loaded into a snapshot process.
class ModuleSnapshot {
public:
virtual ~ModuleSnapshot() {}
//! \brief A modules type.
enum ModuleType {
//! \brief The modules type is unknown.
kModuleTypeUnknown = 0,
//! \brief The module is a main executable.
kModuleTypeExecutable,
//! \brief The module is a shared library.
//!
//! \sa kModuleTypeLoadableModule
kModuleTypeSharedLibrary,
//! \brief The module is a loadable module.
//!
//! On some platforms, loadable modules are distinguished from shared
//! libraries. On these platforms, a shared library is a module that another
//! module links against directly, and a loadable module is not. Loadable
//! modules tend to be binary plug-ins.
kModuleTypeLoadableModule,
//! \brief The module is a dynamic loader.
//!
//! This is the module responsible for loading other modules. This is
//! normally `dyld` for macOS and `ld.so` for Linux and other systems using
//! ELF.
kModuleTypeDynamicLoader,
};
//! \brief Returns the modules pathname.
virtual std::string Name() const = 0;
//! \brief Returns the base address that the module is loaded at in the
//! snapshot process.
virtual uint64_t Address() const = 0;
//! \brief Returns the size that the module occupies in the snapshot process
//! address space, starting at its base address.
//!
//! For macOS snapshots, this method only reports the size of the `__TEXT`
//! segment, because segments may not be loaded contiguously.
virtual uint64_t Size() const = 0;
//! \brief Returns the modules timestamp, if known.
//!
//! The timestamp is typically the modification time of the file that provided
//! the module in `time_t` format, seconds since the POSIX epoch. If the
//! modules timestamp is unknown, this method returns `0`.
virtual time_t Timestamp() const = 0;
//! \brief Returns the modules file version in the \a version_* parameters.
//!
//! If no file version can be determined, the \a version_* parameters are set
//! to `0`.
//!
//! For macOS snapshots, this is taken from the modules `LC_ID_DYLIB` load
//! command for shared libraries, and is `0` for other module types.
virtual void FileVersion(uint16_t* version_0,
uint16_t* version_1,
uint16_t* version_2,
uint16_t* version_3) const = 0;
//! \brief Returns the modules source version in the \a version_* parameters.
//!
//! If no source version can be determined, the \a version_* parameters are
//! set to `0`.
//!
//! For macOS snapshots, this is taken from the modules `LC_SOURCE_VERSION`
//! load command.
virtual void SourceVersion(uint16_t* version_0,
uint16_t* version_1,
uint16_t* version_2,
uint16_t* version_3) const = 0;
//! \brief Returns the modules type.
virtual ModuleType GetModuleType() const = 0;
//! \brief Returns the modules UUID in the \a uuid parameter, and the age of
//! that UUID in \a age.
//!
//! A snapshot modules UUID is taken directly from the module itself. If the
//! module does not have a UUID, the \a uuid parameter will be zeroed out.
//!
//! \a age is the number of times the UUID has been reused. This occurs on
//! Windows with incremental linking. On other platforms \a age will always be
//! `0`.
//!
//! \sa BuildID()
//! \sa DebugFileName()
virtual void UUIDAndAge(crashpad::UUID* uuid, uint32_t* age) const = 0;
//! \brief Returns the modules debug file info name.
//!
//! On Windows, this references the PDB file, which contains symbol
//! information held separately from the module itself. On other platforms,
//! this is normally the basename of the module, because the debug info files
//! name is not relevant even in split-debug scenarios.
//!
//! \sa UUIDAndAge()
virtual std::string DebugFileName() const = 0;
//! \brief Returns the modules build ID.
//!
//! On ELF platforms, the build ID is a variable-length byte stream that
//! identifies a library uniquely, and is usually used to look up its debug
//! symbols when stored separately. This will return an empty vector if it is
//! unsupported.
//!
//! BuildID() and UUIDAndAge() are never available in the same place. When
//! UUIDAndAge() is unavailable, it will be filled out with the contents of
//! BuildID() (either 0-padded or truncated) and age will be zero.
//!
//! \sa UUIDAndAge()
virtual std::vector<uint8_t> BuildID() const = 0;
//! \brief Returns string annotations recorded in the module.
//!
//! This method retrieves annotations recorded in a module. These annotations
//! are intended for diagnostic use, including crash analysis. A module may
//! contain multiple annotations, so they are returned in a vector.
//!
//! For macOS snapshots, these annotations are found by interpreting the
//! modules `__DATA,__crash_info` section as `crashreporter_annotations_t`.
//! System libraries using the crash reporter client interface may reference
//! annotations in this structure. Additional annotations messages may be
//! found in other locations, which may be module-specific. The dynamic linker
//! (`dyld`) can provide an annotation at its `_error_string` symbol.
//!
//! The annotations returned by this method do not duplicate those returned by
//! AnnotationsSimpleMap() or AnnotationObjects().
virtual std::vector<std::string> AnnotationsVector() const = 0;
//! \brief Returns key-value string annotations recorded in the module.
//!
//! This method retrieves annotations recorded in a module. These annotations
//! are intended for diagnostic use, including crash analysis. “Simple
//! annotations” are structured as a sequence of key-value pairs, where all
//! keys and values are strings. These are referred to in Chrome as “crash
//! keys.”
//!
//! For macOS snapshots, these annotations are found by interpreting the
//! `__DATA,crashpad_info` section as `CrashpadInfo`. Clients can use the
//! Crashpad client interface to store annotations in this structure. Most
//! annotations under the clients direct control will be retrievable by this
//! method. For clients such as Chrome, this includes the process type.
//!
//! The annotations returned by this method do not duplicate those returned by
//! AnnotationsVector() or AnnotationObjects(). Additional annotations related
//! to the process, system, or snapshot producer may be obtained by calling
//! ProcessSnapshot::AnnotationsSimpleMap().
virtual std::map<std::string, std::string> AnnotationsSimpleMap() const = 0;
//! \brief Returns the typed annotation objects recorded in the module.
//!
//! This method retrieves annotations recorded in a module. These annotations
//! are intended for diagnostic use, including crash analysis. Annotation
//! objects are strongly-typed name-value pairs. The names are not unique.
//!
//! For macOS snapshots, these annotations are found by interpreting the
//! `__DATA,crashpad_info` section as `CrashpadInfo`. Clients can use the
//! Crashpad client interface to store annotations in this structure. Most
//! annotations under the clients direct control will be retrievable by this
//! method. For clients such as Chrome, this includes the process type.
//!
//! The annotations returned by this method do not duplicate those returned by
//! AnnotationsVector() or AnnotationsSimpleMap().
virtual std::vector<AnnotationSnapshot> AnnotationObjects() const = 0;
//! \brief Returns a set of extra memory ranges specified in the module as
//! being desirable to include in the crash dump.
virtual std::set<CheckedRange<uint64_t>> ExtraMemoryRanges() const = 0;
//! \brief Returns a list of custom minidump stream specified in the module to
//! be included in the crash dump.
//!
//! \return The caller does not take ownership of the returned objects, they
//! are scoped to the lifetime of the ModuleSnapshot object that they were
//! obtained from.
virtual std::vector<const UserMinidumpStream*> CustomMinidumpStreams()
const = 0;
};
} // namespace crashpad
#endif // CRASHPAD_SNAPSHOT_MODULE_SNAPSHOT_H_