Source code
Revision control
Copy as Markdown
Other Tools
/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim: set ts=8 sts=2 et sw=2 tw=80: */
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
#ifndef mozilla_WindowsUnwindInfo_h
#define mozilla_WindowsUnwindInfo_h
#ifdef _M_X64
# include <cstdint>
# include "mozilla/Assertions.h"
# include "mozilla/UniquePtr.h"
namespace mozilla {
// On Windows x64, there is no standard function prologue, hence extra
// information that describes the prologue must be added for each non-leaf
// function in order to properly unwind the stack. This extra information is
// grouped into so-called function tables.
//
// A function table is a contiguous array of one or more RUNTIME_FUNCTION
// entries. Each RUNTIME_FUNCTION entry associates a start and end offset in
// code with specific unwind information. The function table is present in the
// .pdata section of binaries for static code, and added dynamically with
// RtlAddFunctionTable or RtlInstallFunctionTableCallback for dynamic code.
// RUNTIME_FUNCTION entries point to the unwind information, which can thus
// live at a different location in memory, for example it lives in the .xdata
// section for static code.
//
// Contrary to RUNTIME_FUNCTION, Microsoft provides no standard structure
// definition to map the unwind information. This file thus provides some
// helpers to read this data, originally based on breakpad code. The unwind
// information is partially documented at:
// The unwind information stores a bytecode in UnwindInfo.unwind_code[] that
// describes how the instructions in the function prologue interact with the
// stack. An instruction in this bytecode is called an unwind code.
// UnwindCodeOperationCodes enumerates all opcodes used by this bytecode.
// Unwind codes are stored in contiguous slots of 16 bits, where each unwind
// code can span either 1, 2, or 3 slots depending on the opcode it uses.
enum UnwindOperationCodes : uint8_t {
// UnwindCode.operation_info == register number
UWOP_PUSH_NONVOL = 0,
// UnwindCode.operation_info == 0 or 1,
// alloc size in next slot (if 0) or next 2 slots (if 1)
UWOP_ALLOC_LARGE = 1,
// UnwindCode.operation_info == size of allocation / 8 - 1
UWOP_ALLOC_SMALL = 2,
// no UnwindCode.operation_info; register number UnwindInfo.frame_register
// receives (rsp + UnwindInfo.frame_offset*16)
UWOP_SET_FPREG = 3,
// UnwindCode.operation_info == register number, offset in next slot
UWOP_SAVE_NONVOL = 4,
// UnwindCode.operation_info == register number, offset in next 2 slots
UWOP_SAVE_NONVOL_FAR = 5,
// Version 1; undocumented; not meant for x64
UWOP_SAVE_XMM = 6,
// Version 2; undocumented
UWOP_EPILOG = 6,
// Version 1; undocumented; not meant for x64
UWOP_SAVE_XMM_FAR = 7,
// Version 2; undocumented
UWOP_SPARE = 7,
// UnwindCode.operation_info == XMM reg number, offset in next slot
UWOP_SAVE_XMM128 = 8,
// UnwindCode.operation_info == XMM reg number, offset in next 2 slots
UWOP_SAVE_XMM128_FAR = 9,
// UnwindCode.operation_info == 0: no error-code, 1: error-code
UWOP_PUSH_MACHFRAME = 10
};
// Strictly speaking, UnwindCode represents a slot -- not a full unwind code.
union UnwindCode {
struct {
uint8_t offset_in_prolog;
UnwindOperationCodes unwind_operation_code : 4;
uint8_t operation_info : 4;
};
uint16_t frame_offset;
};
// UnwindInfo is a variable-sized struct meant for C-style direct access to the
// unwind information. Be careful:
// - prefer using the size() helper method to using sizeof;
// - don't construct objects of this type, cast pointers instead;
// - consider using the IterableUnwindInfo helpers to iterate over unwind
// codes.
struct UnwindInfo {
uint8_t version : 3;
uint8_t flags : 5; // either 0, UNW_FLAG_CHAININFO, or a combination of
// UNW_FLAG_EHANDLER and UNW_FLAG_UHANDLER
uint8_t size_of_prolog;
uint8_t count_of_codes; // contains the length of the unwind_code[] array
uint8_t frame_register : 4;
uint8_t frame_offset : 4;
UnwindCode unwind_code[1]; // variable length
// Note: There is extra data after the variable length array if using flags
// UNW_FLAG_EHANDLER, UNW_FLAG_UHANDLER, or UNW_FLAG_CHAININFO. We
// ignore the extra data at the moment. For more details, see:
//
// When using UNW_FLAG_EHANDLER or UNW_FLAG_UHANDLER, the extra data
// includes handler data of unspecificied size: only the handler knows
// the correct size for this data. This makes it difficult to know the
// size of the full unwind information or to copy it in this particular
// case.
UnwindInfo(const UnwindInfo&) = delete;
UnwindInfo& operator=(const UnwindInfo&) = delete;
UnwindInfo(UnwindInfo&&) = delete;
UnwindInfo& operator=(UnwindInfo&&) = delete;
~UnwindInfo() = delete;
// Size of this structure, including the variable length unwind_code array
// but NOT including the extra data related to flags UNW_FLAG_EHANDLER,
// UNW_FLAG_UHANDLER, and UNW_FLAG_CHAININFO.
//
// The places where we currently use these helpers read unwind information at
// function entry points; as such we expect that they may encounter
// UNW_FLAG_EHANDLER and/or UNW_FLAG_UHANDLER but won't need to use the
// associated extra data, and it is expected that they should not encounter
// UNW_FLAG_CHAININFO. UNW_FLAG_CHAININFO is typically used for code that
// lives separately from the entry point of the function to which it belongs,
// this code then has chained unwind info pointing to the entry point.
inline size_t Size() const {
return offsetof(UnwindInfo, unwind_code) +
count_of_codes * sizeof(UnwindCode);
}
// Note: We currently do not copy the extra data related to flags
// UNW_FLAG_EHANDLER, UNW_FLAG_UHANDLER, and UNW_FLAG_CHAININFO.
UniquePtr<uint8_t[]> Copy() const {
auto s = Size();
auto result = MakeUnique<uint8_t[]>(s);
std::memcpy(result.get(), reinterpret_cast<const void*>(this), s);
return result;
}
// An unwind code spans a number of slots in the unwind_code array that can
// vary from 1 to 3. This method assumes that the index parameter points to
// a slot that is the start of an unwind code. If the unwind code is
// well-formed, it returns true and sets its second parameter to the number
// of slots that the unwind code occupies.
//
// This function returns false if the unwind code is ill-formed, i.e.:
// - either the index points out of bounds;
// - or the opcode is invalid, or unexpected (e.g. UWOP_SAVE_XMM and
// UWOP_SAVE_XMM_FAR in version 1);
// - or using the correct slots count for the opcode would go out of bounds.
bool GetSlotsCountForCodeAt(uint8_t aIndex, uint8_t* aSlotsCount) const {
if (aIndex >= count_of_codes) {
MOZ_ASSERT_UNREACHABLE("The index is out of bounds");
return false;
}
const UnwindCode& unwindCode = unwind_code[aIndex];
uint8_t slotsCount = 0;
switch (unwindCode.unwind_operation_code) {
// Start with fixed-size opcodes common to versions 1 and 2
case UWOP_SAVE_NONVOL_FAR:
case UWOP_SAVE_XMM128_FAR:
slotsCount = 3;
break;
case UWOP_SAVE_NONVOL:
case UWOP_SAVE_XMM128:
slotsCount = 2;
break;
case UWOP_PUSH_NONVOL:
case UWOP_ALLOC_SMALL:
case UWOP_SET_FPREG:
case UWOP_PUSH_MACHFRAME:
slotsCount = 1;
break;
// UWOP_ALLOC_LARGE is the only variable-sized opcode. It is common to
// versions 1 and 2. It is ill-formed if the info is not 0 or 1.
case UWOP_ALLOC_LARGE:
if (unwindCode.operation_info > 1) {
MOZ_ASSERT_UNREACHABLE(
"Operation UWOP_ALLOC_LARGE is used, but operation_info "
"is not 0 or 1");
return false;
}
slotsCount = 2 + unwindCode.operation_info;
break;
case UWOP_SPARE:
if (version != 2) {
MOZ_ASSERT_UNREACHABLE(
"Operation code UWOP_SPARE is used, but version is not 2");
return false;
}
slotsCount = 3;
break;
case UWOP_EPILOG:
if (version != 2) {
MOZ_ASSERT_UNREACHABLE(
"Operation code UWOP_EPILOG is used, but version is not 2");
return false;
}
slotsCount = 2;
break;
default:
MOZ_ASSERT_UNREACHABLE("An unknown operation code is used");
return false;
}
// The unwind code is ill-formed if using the correct number of slots for
// the opcode would go out of bounds.
if (count_of_codes - aIndex < slotsCount) {
MOZ_ASSERT_UNREACHABLE(
"A valid operation code is used, but it spans too many slots");
return false;
}
*aSlotsCount = slotsCount;
return true;
}
};
class IterableUnwindInfo {
class Iterator {
public:
UnwindInfo& Info() { return mInfo; }
uint8_t Index() const {
MOZ_ASSERT(IsValid());
return mIndex;
}
uint8_t SlotsCount() const {
MOZ_ASSERT(IsValid());
return mSlotsCount;
}
// An iterator is valid if it points to a well-formed unwind code.
// The end iterator is invalid as it does not point to any unwind code.
// All invalid iterators compare equal, which allows comparison with the
// end iterator to exit loops as soon as an ill-formed unwind code is met.
bool IsValid() const { return mIsValid; }
bool IsAtEnd() const { return mIndex >= mInfo.count_of_codes; }
bool operator==(const Iterator& aOther) const {
if (mIsValid != aOther.mIsValid) {
return false;
}
// Comparing two invalid iterators.
if (!mIsValid) {
return true;
}
// Comparing two valid iterators.
return mIndex == aOther.mIndex;
}
bool operator!=(const Iterator& aOther) const { return !(*this == aOther); }
Iterator& operator++() {
MOZ_ASSERT(IsValid());
mIndex += mSlotsCount;
if (mIndex < mInfo.count_of_codes) {
mIsValid = mInfo.GetSlotsCountForCodeAt(mIndex, &mSlotsCount);
MOZ_ASSERT(IsValid());
} else {
mIsValid = false;
}
return *this;
}
const UnwindCode& operator*() {
MOZ_ASSERT(IsValid());
return mInfo.unwind_code[mIndex];
}
private:
friend class IterableUnwindInfo;
Iterator(UnwindInfo& aInfo, uint8_t aIndex, uint8_t aSlotsCount,
bool aIsValid)
: mInfo(aInfo),
mIndex(aIndex),
mSlotsCount(aSlotsCount),
mIsValid(aIsValid){};
UnwindInfo& mInfo;
uint8_t mIndex;
uint8_t mSlotsCount;
bool mIsValid;
};
public:
explicit IterableUnwindInfo(UnwindInfo& aInfo)
: mBegin(aInfo, 0, 0, false),
mEnd(aInfo, aInfo.count_of_codes, 0, false) {
if (aInfo.count_of_codes) {
mBegin.mIsValid = aInfo.GetSlotsCountForCodeAt(0, &mBegin.mSlotsCount);
MOZ_ASSERT(mBegin.mIsValid);
}
}
explicit IterableUnwindInfo(uint8_t* aInfo)
: IterableUnwindInfo(*reinterpret_cast<UnwindInfo*>(aInfo)) {}
UnwindInfo& Info() { return mBegin.Info(); }
const Iterator& begin() { return mBegin; }
const Iterator& end() { return mEnd; }
private:
Iterator mBegin;
Iterator mEnd;
};
} // namespace mozilla
#endif // _M_X64
#endif // mozilla_WindowsUnwindInfo_h