llvm/llvm/include/llvm/BinaryFormat/Dwarf.h

//===-- llvm/BinaryFormat/Dwarf.h ---Dwarf Constants-------------*- C++ -*-===//
//
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
//
//===----------------------------------------------------------------------===//
//
/// \file
/// This file contains constants used for implementing Dwarf
/// debug support.
///
/// For details on the Dwarf specfication see the latest DWARF Debugging
/// Information Format standard document on http://www.dwarfstd.org. This
/// file often includes support for non-released standard features.
//
//===----------------------------------------------------------------------===//

#ifndef LLVM_BINARYFORMAT_DWARF_H
#define LLVM_BINARYFORMAT_DWARF_H

#include "llvm/Support/Compiler.h"
#include "llvm/Support/DataTypes.h"
#include "llvm/Support/ErrorHandling.h"
#include "llvm/Support/Format.h"
#include "llvm/Support/FormatVariadicDetails.h"
#include "llvm/TargetParser/Triple.h"

#include <limits>

namespace llvm {
class StringRef;

namespace dwarf {

//===----------------------------------------------------------------------===//
// DWARF constants as gleaned from the DWARF Debugging Information Format V.5
// reference manual http://www.dwarfstd.org/.
//

// Do not mix the following two enumerations sets.  DW_TAG_invalid changes the
// enumeration base type.

enum LLVMConstants : uint32_t { … };

/// Constants that define the DWARF format as 32 or 64 bit.
enum DwarfFormat : uint8_t { … };

/// Special ID values that distinguish a CIE from a FDE in DWARF CFI.
/// Not inside an enum because a 64-bit value is needed.
/// @{
const uint32_t DW_CIE_ID = …;
const uint64_t DW64_CIE_ID = …;
/// @}

/// Identifier of an invalid DIE offset in the .debug_info section.
const uint32_t DW_INVALID_OFFSET = …;

enum Tag : uint16_t { … };

inline bool isType(Tag T) { … }

/// Attributes.
enum Attribute : uint16_t { … };

enum Form : uint16_t { … };

enum LocationAtom { … };

enum LlvmUserLocationAtom { … };

enum TypeKind : uint8_t { … };

enum DecimalSignEncoding { … };

enum EndianityEncoding { … };

enum AccessAttribute { … };

enum VisibilityAttribute { … };

enum VirtualityAttribute { … };

enum DefaultedMemberAttribute { … };

enum SourceLanguage { … };

enum SourceLanguageName : uint16_t { … };

/// Convert a DWARF 6 pair of language name and version to a DWARF 5 DW_LANG.
/// If the version number doesn't exactly match a known version it is
/// rounded up to the next-highest known version number.
inline std::optional<SourceLanguage> toDW_LANG(SourceLanguageName name,
                                               uint32_t version) { … }

/// Convert a DWARF 5 DW_LANG to a DWARF 6 pair of language name and version.
inline std::optional<std::pair<SourceLanguageName, uint32_t>>
toDW_LNAME(SourceLanguage language) { … }

llvm::StringRef LanguageDescription(SourceLanguageName name);

inline bool isCPlusPlus(SourceLanguage S) { … }

inline bool isFortran(SourceLanguage S) { … }

inline bool isC(SourceLanguage S) { … }

inline TypeKind getArrayIndexTypeEncoding(SourceLanguage S) { … }

enum CaseSensitivity { … };

enum CallingConvention { … };

enum InlineAttribute { … };

enum ArrayDimensionOrdering { … };

enum DiscriminantList { … };

/// Line Number Standard Opcode Encodings.
enum LineNumberOps : uint8_t { … };

/// Line Number Extended Opcode Encodings.
enum LineNumberExtendedOps { … };

enum LineNumberEntryFormat { … };

enum MacinfoRecordType { … };

/// DWARF v5 macro information entry type encodings.
enum MacroEntryType { … };

/// GNU .debug_macro macro information entry type encodings.
enum GnuMacroEntryType { … };

/// DWARF v5 range list entry encoding values.
enum RnglistEntries { … };

/// DWARF v5 loc list entry encoding values.
enum LoclistEntries { … };

/// Call frame instruction encodings.
enum CallFrameInfo { … };

enum Constants { … };

/// Constants for the DW_APPLE_PROPERTY_attributes attribute.
/// Keep this list in sync with clang's DeclObjCCommon.h
/// ObjCPropertyAttribute::Kind!
enum ApplePropertyAttributes { … };

/// Constants for unit types in DWARF v5.
enum UnitType : unsigned char { … };

enum Index { … };

inline bool isUnitType(uint8_t UnitType) { … }

inline bool isUnitType(dwarf::Tag T) { … }

// Constants for the DWARF v5 Accelerator Table Proposal
enum AcceleratorTable { … };

// Return a suggested bucket count for the DWARF v5 Accelerator Table.
inline uint32_t getDebugNamesBucketCount(uint32_t UniqueHashCount) { … }

// Constants for the GNU pubnames/pubtypes extensions supporting gdb index.
enum GDBIndexEntryKind { … };

enum GDBIndexEntryLinkage { … };

/// \defgroup DwarfConstantsDumping Dwarf constants dumping functions
///
/// All these functions map their argument's value back to the
/// corresponding enumerator name or return an empty StringRef if the value
/// isn't known.
///
/// @{
StringRef TagString(unsigned Tag);
StringRef ChildrenString(unsigned Children);
StringRef AttributeString(unsigned Attribute);
StringRef FormEncodingString(unsigned Encoding);
StringRef OperationEncodingString(unsigned Encoding);
StringRef SubOperationEncodingString(unsigned OpEncoding,
                                     unsigned SubOpEncoding);
StringRef AttributeEncodingString(unsigned Encoding);
StringRef DecimalSignString(unsigned Sign);
StringRef EndianityString(unsigned Endian);
StringRef AccessibilityString(unsigned Access);
StringRef DefaultedMemberString(unsigned DefaultedEncodings);
StringRef VisibilityString(unsigned Visibility);
StringRef VirtualityString(unsigned Virtuality);
StringRef LanguageString(unsigned Language);
StringRef CaseString(unsigned Case);
StringRef ConventionString(unsigned Convention);
StringRef InlineCodeString(unsigned Code);
StringRef ArrayOrderString(unsigned Order);
StringRef LNStandardString(unsigned Standard);
StringRef LNExtendedString(unsigned Encoding);
StringRef MacinfoString(unsigned Encoding);
StringRef MacroString(unsigned Encoding);
StringRef GnuMacroString(unsigned Encoding);
StringRef RangeListEncodingString(unsigned Encoding);
StringRef LocListEncodingString(unsigned Encoding);
StringRef CallFrameString(unsigned Encoding, Triple::ArchType Arch);
StringRef ApplePropertyString(unsigned);
StringRef UnitTypeString(unsigned);
StringRef AtomTypeString(unsigned Atom);
StringRef GDBIndexEntryKindString(GDBIndexEntryKind Kind);
StringRef GDBIndexEntryLinkageString(GDBIndexEntryLinkage Linkage);
StringRef IndexString(unsigned Idx);
StringRef FormatString(DwarfFormat Format);
StringRef FormatString(bool IsDWARF64);
StringRef RLEString(unsigned RLE);
/// @}

/// \defgroup DwarfConstantsParsing Dwarf constants parsing functions
///
/// These functions map their strings back to the corresponding enumeration
/// value or return 0 if there is none, except for these exceptions:
///
/// \li \a getTag() returns \a DW_TAG_invalid on invalid input.
/// \li \a getVirtuality() returns \a DW_VIRTUALITY_invalid on invalid input.
/// \li \a getMacinfo() returns \a DW_MACINFO_invalid on invalid input.
///
/// @{
unsigned getTag(StringRef TagString);
unsigned getOperationEncoding(StringRef OperationEncodingString);
unsigned getSubOperationEncoding(unsigned OpEncoding,
                                 StringRef SubOperationEncodingString);
unsigned getVirtuality(StringRef VirtualityString);
unsigned getLanguage(StringRef LanguageString);
unsigned getCallingConvention(StringRef LanguageString);
unsigned getAttributeEncoding(StringRef EncodingString);
unsigned getMacinfo(StringRef MacinfoString);
unsigned getMacro(StringRef MacroString);
/// @}

/// \defgroup DwarfConstantsVersioning Dwarf version for constants
///
/// For constants defined by DWARF, returns the DWARF version when the constant
/// was first defined. For vendor extensions, if there is a version-related
/// policy for when to emit it, returns a version number for that policy.
/// Otherwise returns 0.
///
/// @{
unsigned TagVersion(Tag T);
unsigned AttributeVersion(Attribute A);
unsigned FormVersion(Form F);
unsigned OperationVersion(LocationAtom O);
unsigned AttributeEncodingVersion(TypeKind E);
unsigned LanguageVersion(SourceLanguage L);
/// @}

/// \defgroup DwarfConstantsVendor Dwarf "vendor" for constants
///
/// These functions return an identifier describing "who" defined the constant,
/// either the DWARF standard itself or the vendor who defined the extension.
///
/// @{
unsigned TagVendor(Tag T);
unsigned AttributeVendor(Attribute A);
unsigned FormVendor(Form F);
unsigned OperationVendor(LocationAtom O);
unsigned AttributeEncodingVendor(TypeKind E);
unsigned LanguageVendor(SourceLanguage L);
/// @}

/// The number of operands for the given LocationAtom.
std::optional<unsigned> OperationOperands(LocationAtom O);

/// The arity of the given LocationAtom. This is the number of elements on the
/// stack this operation operates on. Returns -1 if the arity is variable (e.g.
/// depending on the argument) or unknown.
std::optional<unsigned> OperationArity(LocationAtom O);

std::optional<unsigned> LanguageLowerBound(SourceLanguage L);

/// The size of a reference determined by the DWARF 32/64-bit format.
inline uint8_t getDwarfOffsetByteSize(DwarfFormat Format) { … }

/// A helper struct providing information about the byte size of DW_FORM
/// values that vary in size depending on the DWARF version, address byte
/// size, or DWARF32/DWARF64.
struct FormParams { … };

/// Get the byte size of the unit length field depending on the DWARF format.
inline uint8_t getUnitLengthFieldByteSize(DwarfFormat Format) { … }

/// Get the fixed byte size for a given form.
///
/// If the form has a fixed byte size, then an Optional with a value will be
/// returned. If the form is always encoded using a variable length storage
/// format (ULEB or SLEB numbers or blocks) then std::nullopt will be returned.
///
/// \param Form DWARF form to get the fixed byte size for.
/// \param Params DWARF parameters to help interpret forms.
/// \returns std::optional<uint8_t> value with the fixed byte size or
/// std::nullopt if \p Form doesn't have a fixed byte size.
std::optional<uint8_t> getFixedFormByteSize(dwarf::Form Form,
                                            FormParams Params);

/// Tells whether the specified form is defined in the specified version,
/// or is an extension if extensions are allowed.
bool isValidFormForVersion(Form F, unsigned Version, bool ExtensionsOk = true);

/// Returns the symbolic string representing Val when used as a value
/// for attribute Attr.
StringRef AttributeValueString(uint16_t Attr, unsigned Val);

/// Returns the symbolic string representing Val when used as a value
/// for atom Atom.
StringRef AtomValueString(uint16_t Atom, unsigned Val);

/// Describes an entry of the various gnu_pub* debug sections.
///
/// The gnu_pub* kind looks like:
///
/// 0-3  reserved
/// 4-6  symbol kind
/// 7    0 == global, 1 == static
///
/// A gdb_index descriptor includes the above kind, shifted 24 bits up with the
/// offset of the cu within the debug_info section stored in those 24 bits.
struct PubIndexEntryDescriptor { … };

template <typename Enum> struct EnumTraits : public std::false_type { … };

template <> struct EnumTraits<Attribute> : public std::true_type { … };

template <> struct EnumTraits<Form> : public std::true_type { … };

template <> struct EnumTraits<Index> : public std::true_type { … };

template <> struct EnumTraits<Tag> : public std::true_type { … };

template <> struct EnumTraits<LineNumberOps> : public std::true_type { … };

template <> struct EnumTraits<LocationAtom> : public std::true_type { … };

inline uint64_t computeTombstoneAddress(uint8_t AddressByteSize) { … }

} // End of namespace dwarf

/// Dwarf constants format_provider
///
/// Specialization of the format_provider template for dwarf enums. Unlike the
/// dumping functions above, these format unknown enumerator values as
/// DW_TYPE_unknown_1234 (e.g. DW_TAG_unknown_ffff).
format_provider<Enum, std::enable_if_t<dwarf::EnumTraits<Enum>::value>>;
} // End of namespace llvm

#endif