Subversion Repositories QNX 8.QNX8 LLVM/Clang compiler suite

//===- FunctionInfo.h -------------------------------------------*- 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

//

//===----------------------------------------------------------------------===//

#ifndef LLVM_DEBUGINFO_GSYM_FUNCTIONINFO_H

#define LLVM_DEBUGINFO_GSYM_FUNCTIONINFO_H

#include "llvm/DebugInfo/GSYM/ExtractRanges.h"

#include "llvm/DebugInfo/GSYM/InlineInfo.h"

#include "llvm/DebugInfo/GSYM/LineTable.h"

#include "llvm/DebugInfo/GSYM/LookupResult.h"

#include "llvm/DebugInfo/GSYM/StringTable.h"

#include <cstdint>

#include <tuple>

namespace llvm {

class raw_ostream;

namespace gsym {

class GsymReader;

/// Function information in GSYM files encodes information for one contiguous

/// address range. If a function has discontiguous address ranges, they will

/// need to be encoded using multiple FunctionInfo objects.

///

/// ENCODING

///

/// The function information gets the function start address as an argument

/// to the FunctionInfo::decode(...) function. This information is calculated

/// from the GSYM header and an address offset from the GSYM address offsets

/// table. The encoded FunctionInfo information must be aligned to a 4 byte

/// boundary.

///

/// The encoded data for a FunctionInfo starts with fixed data that all

/// function info objects have:

///

/// ENCODING  NAME        DESCRIPTION

/// ========= =========== ====================================================

/// uint32_t  Size        The size in bytes of this function.

/// uint32_t  Name        The string table offset of the function name.

///

/// The optional data in a FunctionInfo object follows this fixed information

/// and consists of a stream of tuples that consist of:

///

/// ENCODING  NAME        DESCRIPTION

/// ========= =========== ====================================================

/// uint32_t  InfoType    An "InfoType" enumeration that describes the type

///                       of optional data that is encoded.

/// uint32_t  InfoLength  The size in bytes of the encoded data that

///                       immediately follows this length if this value is

///                       greater than zero.

/// uint8_t[] InfoData    Encoded bytes that represent the data for the

///                       "InfoType". These bytes are only present if

///                       "InfoLength" is greater than zero.

///

/// The "InfoType" is an enumeration:

///

///   enum InfoType {

///     EndOfList = 0u,

///     LineTableInfo = 1u,

///     InlineInfo = 2u

///   };

///

/// This stream of tuples is terminated by a "InfoType" whose value is

/// InfoType::EndOfList and a zero for "InfoLength". This signifies the end of

/// the optional information list. This format allows us to add new optional

/// information data to a FunctionInfo object over time and allows older

/// clients to still parse the format and skip over any data that they don't

/// understand or want to parse.

///

/// So the function information encoding essientially looks like:

///

/// struct {

///   uint32_t Size;

///   uint32_t Name;

///   struct {

///     uint32_t InfoType;

///     uint32_t InfoLength;

///     uint8_t InfoData[InfoLength];

///   }[N];

/// }

///

/// Where "N" is the number of tuples.

struct FunctionInfo {

  AddressRange Range;

  uint32_t Name; ///< String table offset in the string table.

  std::optional<LineTable> OptLineTable;

  std::optional<InlineInfo> Inline;

  FunctionInfo(uint64_t Addr = 0, uint64_t Size = 0, uint32_t N = 0)

      : Range(Addr, Addr + Size), Name(N) {}

  /// Query if a FunctionInfo has rich debug info.

  ///

  /// \returns A bool that indicates if this object has something else than

  /// range and name. When converting information from a symbol table and from

  /// debug info, we might end up with multiple FunctionInfo objects for the

  /// same range and we need to be able to tell which one is the better object

  /// to use.

  bool hasRichInfo() const { return OptLineTable || Inline; }

  /// Query if a FunctionInfo object is valid.

  ///

  /// Address and size can be zero and there can be no line entries for a

  /// symbol so the only indication this entry is valid is if the name is

  /// not zero. This can happen when extracting information from symbol

  /// tables that do not encode symbol sizes. In that case only the

  /// address and name will be filled in.

  ///

  /// \returns A boolean indicating if this FunctionInfo is valid.

  bool isValid() const {

    return Name != 0;

  }

  /// Decode an object from a binary data stream.

  ///

  /// \param Data The binary stream to read the data from. This object must

  /// have the data for the object starting at offset zero. The data

  /// can contain more data than needed.

  ///

  /// \param BaseAddr The FunctionInfo's start address and will be used as the

  /// base address when decoding any contained information like the line table

  /// and the inline info.

  ///

  /// \returns An FunctionInfo or an error describing the issue that was

  /// encountered during decoding.

  static llvm::Expected<FunctionInfo> decode(DataExtractor &Data,

                                             uint64_t BaseAddr);

  /// Encode this object into FileWriter stream.

  ///

  /// \param O The binary stream to write the data to at the current file

  /// position.

  ///

  /// \returns An error object that indicates failure or the offset of the

  /// function info that was successfully written into the stream.

  llvm::Expected<uint64_t> encode(FileWriter &O) const;

  /// Lookup an address within a FunctionInfo object's data stream.

  ///

  /// Instead of decoding an entire FunctionInfo object when doing lookups,

  /// we can decode only the information we need from the FunctionInfo's data

  /// for the specific address. The lookup result information is returned as

  /// a LookupResult.

  ///

  /// \param Data The binary stream to read the data from. This object must

  /// have the data for the object starting at offset zero. The data

  /// can contain more data than needed.

  ///

  /// \param GR The GSYM reader that contains the string and file table that

  /// will be used to fill in information in the returned result.

  ///

  /// \param FuncAddr The function start address decoded from the GsymReader.

  ///

  /// \param Addr The address to lookup.

  ///

  /// \returns An LookupResult or an error describing the issue that was

  /// encountered during decoding. An error should only be returned if the

  /// address is not contained in the FunctionInfo or if the data is corrupted.

  static llvm::Expected<LookupResult> lookup(DataExtractor &Data,

                                             const GsymReader &GR,

                                             uint64_t FuncAddr,

                                             uint64_t Addr);

  uint64_t startAddress() const { return Range.start(); }

  uint64_t endAddress() const { return Range.end(); }

  uint64_t size() const { return Range.size(); }

  void clear() {

    Range = {0, 0};

    Name = 0;

    OptLineTable = std::nullopt;

    Inline = std::nullopt;

  }

};

inline bool operator==(const FunctionInfo &LHS, const FunctionInfo &RHS) {

  return LHS.Range == RHS.Range && LHS.Name == RHS.Name &&

         LHS.OptLineTable == RHS.OptLineTable && LHS.Inline == RHS.Inline;

}

inline bool operator!=(const FunctionInfo &LHS, const FunctionInfo &RHS) {

  return !(LHS == RHS);

}

/// This sorting will order things consistently by address range first, but then

/// followed by inlining being valid and line tables. We might end up with a

/// FunctionInfo from debug info that will have the same range as one from the

/// symbol table, but we want to quickly be able to sort and use the best version

/// when creating the final GSYM file.

inline bool operator<(const FunctionInfo &LHS, const FunctionInfo &RHS) {

  // First sort by address range

  if (LHS.Range != RHS.Range)

    return LHS.Range < RHS.Range;

  // Then sort by inline

  if (LHS.Inline.has_value() != RHS.Inline.has_value())

    return RHS.Inline.has_value();

  return LHS.OptLineTable < RHS.OptLineTable;

}

raw_ostream &operator<<(raw_ostream &OS, const FunctionInfo &R);

} // namespace gsym

} // namespace llvm

#endif // LLVM_DEBUGINFO_GSYM_FUNCTIONINFO_H