MCSubtargetInfo.h

Go to the documentation of this file.

//===- llvm/MC/MCSubtargetInfo.h - Subtarget Information --------*- 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
//
//===----------------------------------------------------------------------===//
//
// This file describes the subtarget options of a Target machine.
//
//===----------------------------------------------------------------------===//
 
#ifndef LLVM_MC_MCSUBTARGETINFO_H
#define LLVM_MC_MCSUBTARGETINFO_H
 
#include "llvm/ADT/ArrayRef.h"
#include "llvm/ADT/STLExtras.h"
#include "llvm/ADT/StringRef.h"
#include "llvm/ADT/StringTable.h"
#include "llvm/MC/MCInstrItineraries.h"
#include "llvm/MC/MCSchedule.h"
#include "llvm/Support/Compiler.h"
#include "llvm/TargetParser/SubtargetFeature.h"
#include "llvm/TargetParser/Triple.h"
#include <array>
#include <cassert>
#include <cstdint>
#include <memory>
#include <optional>
#include <string>
 
namespace llvm {
 
class MCInst;
 
//===----------------------------------------------------------------------===//
 
/// Used to provide key value pairs for feature and CPU bit flags.
struct SubtargetFeatureKV {
  uint16_t KeyStrOff;
  uint16_t DescStrOff;
  unsigned Value;                       ///< K-V integer value
  FeatureBitArray Implies;              ///< K-V bit mask
 
  constexpr SubtargetFeatureKV(uint16_t KeyStrOff, uint16_t DescStrOff,
                               unsigned Value, FeatureBitArray Implies)
      : KeyStrOff(KeyStrOff), DescStrOff(DescStrOff), Value(Value),
        Implies(Implies) {}
 
  // Because of relative string offsets, this type is not copyable.
  SubtargetFeatureKV(const SubtargetFeatureKV &) = delete;
  SubtargetFeatureKV &operator=(const SubtargetFeatureKV &) = delete;
 
  const char *key() const {
    return reinterpret_cast<const char *>(this) + KeyStrOff;
  }
 
  const char *desc() const {
    return reinterpret_cast<const char *>(this) + DescStrOff;
  }
 
  /// Compare routine for std::lower_bound
  bool operator<(StringRef S) const { return StringRef(key()) < S; }
 
  /// Compare routine for std::is_sorted.
  bool operator<(const SubtargetFeatureKV &Other) const {
    return StringRef(key()) < StringRef(Other.key());
  }
};
 
template <size_t NumFeatures, size_t FeatureStrTabSize>
struct SubtargetFeatureKVStorage {
  SubtargetFeatureKV Features[NumFeatures];
  char Strings[FeatureStrTabSize];
};
 
//===----------------------------------------------------------------------===//
 
/// Used to provide key value pairs for feature and CPU bit flags.
struct SubtargetSubTypeKV {
  uint16_t KeyStrOff;
  unsigned SchedModelIdx;
  FeatureBitArray Implies;              ///< K-V bit mask
  FeatureBitArray TuneImplies;          ///< K-V bit mask
 
  constexpr SubtargetSubTypeKV(uint16_t KeyStrOff, FeatureBitArray Implies,
                               FeatureBitArray TuneImplies,
                               unsigned SchedModelIdx)
      : KeyStrOff(KeyStrOff), SchedModelIdx(SchedModelIdx), Implies(Implies),
        TuneImplies(TuneImplies) {}
 
  // Because of relative string offsets, this type is not copyable.
  SubtargetSubTypeKV(const SubtargetSubTypeKV &) = delete;
  SubtargetSubTypeKV &operator=(const SubtargetSubTypeKV &) = delete;
 
  const char *key() const {
    return reinterpret_cast<const char *>(this) + KeyStrOff;
  }
 
  /// Compare routine for std::lower_bound
  bool operator<(StringRef S) const { return StringRef(key()) < S; }
 
  /// Compare routine for std::is_sorted.
  bool operator<(const SubtargetSubTypeKV &Other) const {
    return StringRef(key()) < StringRef(Other.key());
  }
};
 
/// Maps a CPU alias name to the index of the processor it resolves to.
struct SubtargetSubTypeAliasKV {
  uint16_t KeyStrOff;  ///< Relative offset to the alias name.
  uint16_t SubTypeIdx; ///< Index into the SubtargetSubTypeKV array.
 
  // MSVC STL before VS2022 value-initializes an element of std::array<T, 0>,
  // which every target defining no processor aliases instantiates.
  constexpr SubtargetSubTypeAliasKV() : KeyStrOff(0), SubTypeIdx(0) {}
 
  constexpr SubtargetSubTypeAliasKV(uint16_t KeyStrOff, uint16_t SubTypeIdx)
      : KeyStrOff(KeyStrOff), SubTypeIdx(SubTypeIdx) {}
 
  SubtargetSubTypeAliasKV(const SubtargetSubTypeAliasKV &) = delete;
  SubtargetSubTypeAliasKV &operator=(const SubtargetSubTypeAliasKV &) = delete;
 
  const char *key() const {
    return reinterpret_cast<const char *>(this) + KeyStrOff;
  }
 
  bool operator<(StringRef S) const { return StringRef(key()) < S; }
};
 
template <size_t NumSubTypes, size_t NumAliases, size_t SubTypeStrTabSize>
struct SubtargetSubTypeKVStorage {
  SubtargetSubTypeKV SubTypes[NumSubTypes];
  std::array<SubtargetSubTypeAliasKV, NumAliases> Aliases;
  char Strings[SubTypeStrTabSize];
};
 
//===----------------------------------------------------------------------===//
///
/// Generic base class for all target subtargets.
///
class LLVM_ABI MCSubtargetInfo {
  Triple TargetTriple;
  std::string CPU; // CPU being targeted.
  std::string TuneCPU; // CPU being tuned for.
  StringTable ProcNames; // Processor list, including aliases
  ArrayRef<SubtargetFeatureKV> ProcFeatures;  // Processor feature list
  ArrayRef<SubtargetSubTypeKV> ProcDesc;  // Processor descriptions
  ArrayRef<SubtargetSubTypeAliasKV> ProcAliases; // CPU alias -> processor map
  const MCSchedModel *ProcSchedModels;    ///< Processor scheduling models.
 
  // Scheduler machine model
  const MCWriteProcResEntry *WriteProcResTable;
  const MCWriteLatencyEntry *WriteLatencyTable;
  const MCReadAdvanceEntry *ReadAdvanceTable;
  const MCSchedModel *CPUSchedModel;
 
  const InstrStage *Stages;            // Instruction itinerary stages
  const unsigned *OperandCycles;       // Itinerary operand cycles
  const unsigned *ForwardingPaths;
  FeatureBitset FeatureBits;           // Feature bits for current CPU + FS
  std::string FeatureString;           // Feature string
 
public:
  MCSubtargetInfo(const MCSubtargetInfo &) = default;
  MCSubtargetInfo(const Triple &TT, StringRef CPU, StringRef TuneCPU,
                  StringRef FS, StringTable PN, ArrayRef<SubtargetFeatureKV> PF,
                  ArrayRef<SubtargetSubTypeKV> PD,
                  ArrayRef<SubtargetSubTypeAliasKV> PA, const MCSchedModel *PSM,
                  const MCWriteProcResEntry *WPR, const MCWriteLatencyEntry *WL,
                  const MCReadAdvanceEntry *RA, const InstrStage *IS,
                  const unsigned *OC, const unsigned *FP);
  MCSubtargetInfo() = delete;
  MCSubtargetInfo &operator=(const MCSubtargetInfo &) = delete;
  MCSubtargetInfo &operator=(MCSubtargetInfo &&) = delete;
  virtual ~MCSubtargetInfo() = default;
 
  virtual std::unique_ptr<MCSubtargetInfo> clone() const {
    return std::make_unique<MCSubtargetInfo>(*this);
  }
 
  const Triple &getTargetTriple() const { return TargetTriple; }
  StringRef getCPU() const { return CPU; }
  StringRef getTuneCPU() const { return TuneCPU; }
 
  const FeatureBitset& getFeatureBits() const { return FeatureBits; }
  void setFeatureBits(const FeatureBitset &FeatureBits_) {
    FeatureBits = FeatureBits_;
  }
 
  StringRef getFeatureString() const { return FeatureString; }
 
  bool hasFeature(unsigned Feature) const {
    return FeatureBits[Feature];
  }
 
protected:
  /// Initialize the scheduling model and feature bits.
  ///
  /// FIXME: Find a way to stick this in the constructor, since it should only
  /// be called during initialization.
  void InitMCProcessorInfo(StringRef CPU, StringRef TuneCPU, StringRef FS);
 
public:
  /// Set the features to the default for the given CPU and TuneCPU, with ano
  /// appended feature string.
  void setDefaultFeatures(StringRef CPU, StringRef TuneCPU, StringRef FS);
 
  /// Toggle a feature and return the re-computed feature bits.
  /// This version does not change the implied bits.
  const FeatureBitset &ToggleFeature(uint64_t FB);
 
  /// Toggle a feature and return the re-computed feature bits.
  /// This version does not change the implied bits.
  const FeatureBitset &ToggleFeature(const FeatureBitset &FB);
 
  /// Toggle a set of features and return the re-computed feature bits.
  /// This version will also change all implied bits.
  const FeatureBitset &ToggleFeature(StringRef FS);
 
  /// Apply a feature flag and return the re-computed feature bits, including
  /// all feature bits implied by the flag.
  const FeatureBitset &ApplyFeatureFlag(StringRef FS);
 
  /// Set/clear additional feature bits, including all other bits they imply.
  const FeatureBitset &SetFeatureBitsTransitively(const FeatureBitset &FB);
  const FeatureBitset &ClearFeatureBitsTransitively(const FeatureBitset &FB);
 
  /// Check whether the subtarget features are enabled/disabled as per
  /// the provided string, ignoring all other features.
  bool checkFeatures(StringRef FS) const;
 
  /// Check whether the current subtarget satisfies a target feature expression.
  /// The expression uses feature names from the target's subtarget feature
  /// table. Comma means AND, | means OR, comma has higher precedence than |,
  /// and parentheses group expressions.
  bool checkFeatureExpression(StringRef FeatureExpr) const;
 
  /// Get the machine model of a CPU.
  const MCSchedModel &getSchedModelForCPU(StringRef CPU) const;
 
  /// Get the machine model for this subtarget's CPU.
  const MCSchedModel &getSchedModel() const { return *CPUSchedModel; }
 
  /// Return an iterator at the first process resource consumed by the given
  /// scheduling class.
  const MCWriteProcResEntry *getWriteProcResBegin(
    const MCSchedClassDesc *SC) const {
    return &WriteProcResTable[SC->WriteProcResIdx];
  }
  const MCWriteProcResEntry *getWriteProcResEnd(
    const MCSchedClassDesc *SC) const {
    return getWriteProcResBegin(SC) + SC->NumWriteProcResEntries;
  }
 
  const MCWriteLatencyEntry *getWriteLatencyEntry(const MCSchedClassDesc *SC,
                                                  unsigned DefIdx) const {
    assert(DefIdx < SC->NumWriteLatencyEntries &&
           "MachineModel does not specify a WriteResource for DefIdx");
 
    return &WriteLatencyTable[SC->WriteLatencyIdx + DefIdx];
  }
 
  int getReadAdvanceCycles(const MCSchedClassDesc *SC, unsigned UseIdx,
                           unsigned WriteResID) const {
    // TODO: The number of read advance entries in a class can be significant
    // (~50). Consider compressing the WriteID into a dense ID of those that are
    // used by ReadAdvance and representing them as a bitset.
    for (const MCReadAdvanceEntry *I = &ReadAdvanceTable[SC->ReadAdvanceIdx],
           *E = I + SC->NumReadAdvanceEntries; I != E; ++I) {
      if (I->UseIdx < UseIdx)
        continue;
      if (I->UseIdx > UseIdx)
        break;
      // Find the first WriteResIdx match, which has the highest cycle count.
      if (!I->WriteResourceID || I->WriteResourceID == WriteResID) {
        return I->Cycles;
      }
    }
    return 0;
  }
 
  /// Return the set of ReadAdvance entries declared by the scheduling class
  /// descriptor in input.
  ArrayRef<MCReadAdvanceEntry>
  getReadAdvanceEntries(const MCSchedClassDesc &SC) const {
    if (!SC.NumReadAdvanceEntries)
      return ArrayRef<MCReadAdvanceEntry>();
    return ArrayRef<MCReadAdvanceEntry>(&ReadAdvanceTable[SC.ReadAdvanceIdx],
                                        SC.NumReadAdvanceEntries);
  }
 
  /// Get scheduling itinerary of a CPU.
  InstrItineraryData getInstrItineraryForCPU(StringRef CPU) const;
 
  /// Initialize an InstrItineraryData instance.
  void initInstrItins(InstrItineraryData &InstrItins) const;
 
  /// Resolve a variant scheduling class for the given MCInst and CPU.
  virtual unsigned resolveVariantSchedClass(unsigned SchedClass,
                                            const MCInst *MI,
                                            const MCInstrInfo *MCII,
                                            unsigned CPUID) const {
    return 0;
  }
 
  /// Look up the processor entry for a CPU name, resolving aliases. Returns
  /// nullptr if the name matches neither a processor nor an alias.
  const SubtargetSubTypeKV *resolveCPU(StringRef CPU) const;
 
  /// Check whether the CPU string is valid.
  bool isCPUStringValid(StringRef CPU) const { return resolveCPU(CPU); }
 
  /// Return processor descriptions.
  ArrayRef<SubtargetSubTypeKV> getAllProcessorDescriptions() const {
    return ProcDesc;
  }
 
  /// Return processor features.
  ArrayRef<SubtargetFeatureKV> getAllProcessorFeatures() const {
    return ProcFeatures;
  }
 
  /// Return the list of processor features currently enabled.
  std::vector<const SubtargetFeatureKV *> getEnabledProcessorFeatures() const;
 
  /// HwMode IDs are stored and accessed in a bit set format, enabling
  /// users to efficiently retrieve specific IDs, such as the RegInfo
  /// HwMode ID, from the set as required. Using this approach, various
  /// types of HwMode IDs can be added to a subtarget to manage different
  /// attributes within that subtarget, significantly enhancing the
  /// scalability and usability of HwMode. Moreover, to ensure compatibility,
  /// this method also supports controlling multiple attributes with a single
  /// HwMode ID, just as was done previously.
  enum HwModeType {
    HwMode_Default,     // Return the smallest HwMode ID of current subtarget.
    HwMode_ValueType,   // Return the HwMode ID that controls the ValueType.
    HwMode_RegInfo,     // Return the HwMode ID that controls the RegSizeInfo,
                        // SubRegRange, and RegisterClass.
    HwMode_EncodingInfo // Return the HwMode ID that controls the EncodingInfo.
  };
 
  /// Return a bit set containing all HwMode IDs of the current subtarget.
  virtual unsigned getHwModeSet() const { return 0; }
 
  /// HwMode ID corresponding to the 'type' parameter is retrieved from the
  /// HwMode bit set of the current subtarget. It’s important to note that if
  /// the current subtarget possesses two HwMode IDs and both control a single
  /// attribute (such as RegInfo), this interface will result in an error.
  virtual unsigned getHwMode(enum HwModeType type = HwMode_Default) const {
    return 0;
  }
 
  /// Return the cache size in bytes for the given level of cache.
  /// Level is zero-based, so a value of zero means the first level of
  /// cache.
  ///
  virtual std::optional<unsigned> getCacheSize(unsigned Level) const;
 
  /// Return the cache associatvity for the given level of cache.
  /// Level is zero-based, so a value of zero means the first level of
  /// cache.
  ///
  virtual std::optional<unsigned> getCacheAssociativity(unsigned Level) const;
 
  /// Return the target cache line size in bytes at a given level.
  ///
  virtual std::optional<unsigned> getCacheLineSize(unsigned Level) const;
 
  /// Return the target cache line size in bytes.  By default, return
  /// the line size for the bottom-most level of cache.  This provides
  /// a more convenient interface for the common case where all cache
  /// levels have the same line size.  Return zero if there is no
  /// cache model.
  ///
  virtual unsigned getCacheLineSize() const {
    std::optional<unsigned> Size = getCacheLineSize(0);
    if (Size)
      return *Size;
 
    return 0;
  }
 
  /// Return the preferred prefetch distance in terms of instructions.
  ///
  virtual unsigned getPrefetchDistance() const;
 
  /// Return the maximum prefetch distance in terms of loop
  /// iterations.
  ///
  virtual unsigned getMaxPrefetchIterationsAhead() const;
 
  /// \return True if prefetching should also be done for writes.
  ///
  virtual bool enableWritePrefetching() const;
 
  /// Return the minimum stride necessary to trigger software
  /// prefetching.
  ///
  virtual unsigned getMinPrefetchStride(unsigned NumMemAccesses,
                                        unsigned NumStridedMemAccesses,
                                        unsigned NumPrefetches,
                                        bool HasCall) const;
 
  /// \return if target want to issue a prefetch in address space \p AS.
  virtual bool shouldPrefetchAddressSpace(unsigned AS) const;
};
 
} // end namespace llvm
 
#endif // LLVM_MC_MCSUBTARGETINFO_H