llvm/XRay/InstrumentationMap.h

0001 //===- InstrumentationMap.h - XRay Instrumentation Map ----------*- C++ -*-===//
0002 //
0003 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
0004 // See https://llvm.org/LICENSE.txt for license information.
0005 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
0006 //
0007 //===----------------------------------------------------------------------===//
0008 //
0009 // Defines the interface for extracting the instrumentation map from an
0010 // XRay-instrumented binary.
0011 //
0012 //===----------------------------------------------------------------------===//
0013
0014 #ifndef LLVM_XRAY_INSTRUMENTATIONMAP_H
0015 #define LLVM_XRAY_INSTRUMENTATIONMAP_H
0016
0017 #include "llvm/ADT/StringRef.h"
0018 #include "llvm/Support/Error.h"
0019 #include "llvm/Support/YAMLTraits.h"
0020 #include <cstdint>
0021 #include <optional>
0022 #include <unordered_map>
0023 #include <vector>
0024
0025 namespace llvm {
0026
0027 namespace xray {
0028
0029 // Forward declare to make a friend.
0030 class InstrumentationMap;
0031
0032 /// Loads the instrumentation map from |Filename|. This auto-deduces the type of
0033 /// the instrumentation map.
0034 Expected<InstrumentationMap> loadInstrumentationMap(StringRef Filename);
0035
0036 /// Represents an XRay instrumentation sled entry from an object file.
0037 struct SledEntry {
0038   /// Each entry here represents the kinds of supported instrumentation map
0039   /// entries.
0040   enum class FunctionKinds { ENTRY, EXIT, TAIL, LOG_ARGS_ENTER, CUSTOM_EVENT };
0041
0042   /// The address of the sled.
0043   uint64_t Address;
0044
0045   /// The address of the function.
0046   uint64_t Function;
0047
0048   /// The kind of sled.
0049   FunctionKinds Kind;
0050
0051   /// Whether the sled was annotated to always be instrumented.
0052   bool AlwaysInstrument;
0053
0054   unsigned char Version;
0055 };
0056
0057 struct YAMLXRaySledEntry {
0058   int32_t FuncId;
0059   yaml::Hex64 Address;
0060   yaml::Hex64 Function;
0061   SledEntry::FunctionKinds Kind;
0062   bool AlwaysInstrument;
0063   std::string FunctionName;
0064   unsigned char Version;
0065 };
0066
0067 /// The InstrumentationMap represents the computed function id's and indicated
0068 /// function addresses from an object file (or a YAML file). This provides an
0069 /// interface to just the mapping between the function id, and the function
0070 /// address.
0071 ///
0072 /// We also provide raw access to the actual instrumentation map entries we find
0073 /// associated with a particular object file.
0074 ///
0075 class InstrumentationMap {
0076 public:
0077   using FunctionAddressMap = std::unordered_map<int32_t, uint64_t>;
0078   using FunctionAddressReverseMap = std::unordered_map<uint64_t, int32_t>;
0079   using SledContainer = std::vector<SledEntry>;
0080
0081 private:
0082   SledContainer Sleds;
0083   FunctionAddressMap FunctionAddresses;
0084   FunctionAddressReverseMap FunctionIds;
0085
0086   friend Expected<InstrumentationMap> loadInstrumentationMap(StringRef);
0087
0088 public:
0089   /// Provides a raw accessor to the unordered map of function addresses.
0090   const FunctionAddressMap &getFunctionAddresses() { return FunctionAddresses; }
0091
0092   /// Returns an XRay computed function id, provided a function address.
0093   std::optional<int32_t> getFunctionId(uint64_t Addr) const;
0094
0095   /// Returns the function address for a function id.
0096   std::optional<uint64_t> getFunctionAddr(int32_t FuncId) const;
0097
0098   /// Provide read-only access to the entries of the instrumentation map.
0099   const SledContainer &sleds() const { return Sleds; };
0100 };
0101
0102 } // end namespace xray
0103
0104 namespace yaml {
0105
0106 template <> struct ScalarEnumerationTraits<xray::SledEntry::FunctionKinds> {
0107   static void enumeration(IO &IO, xray::SledEntry::FunctionKinds &Kind) {
0108     IO.enumCase(Kind, "function-enter", xray::SledEntry::FunctionKinds::ENTRY);
0109     IO.enumCase(Kind, "function-exit", xray::SledEntry::FunctionKinds::EXIT);
0110     IO.enumCase(Kind, "tail-exit", xray::SledEntry::FunctionKinds::TAIL);
0111     IO.enumCase(Kind, "log-args-enter",
0112                 xray::SledEntry::FunctionKinds::LOG_ARGS_ENTER);
0113     IO.enumCase(Kind, "custom-event",
0114                 xray::SledEntry::FunctionKinds::CUSTOM_EVENT);
0115   }
0116 };
0117
0118 template <> struct MappingTraits<xray::YAMLXRaySledEntry> {
0119   static void mapping(IO &IO, xray::YAMLXRaySledEntry &Entry) {
0120     IO.mapRequired("id", Entry.FuncId);
0121     IO.mapRequired("address", Entry.Address);
0122     IO.mapRequired("function", Entry.Function);
0123     IO.mapRequired("kind", Entry.Kind);
0124     IO.mapRequired("always-instrument", Entry.AlwaysInstrument);
0125     IO.mapOptional("function-name", Entry.FunctionName);
0126     IO.mapOptional("version", Entry.Version, 0);
0127   }
0128
0129   static constexpr bool flow = true;
0130 };
0131
0132 } // end namespace yaml
0133
0134 } // end namespace llvm
0135
0136 LLVM_YAML_IS_SEQUENCE_VECTOR(xray::YAMLXRaySledEntry)
0137
0138 #endif // LLVM_XRAY_INSTRUMENTATIONMAP_H